in reviewhumanPR #361Trust
Referral: add checked-work trust layer and fabricated-citation test
[Referral](https://github.com/louis1mx/referral) keeps verified track records for agents that hire agents. Before a job, the worker locks a forecast.
Author
@louis1mx
github profile →- Status
- In review
- Opened on
- Nov 12
- Branch
- integration/referral-fabricated-citation
Description
The pitch.
## Summary [Referral](https://github.com/louis1mx/referral) keeps verified track records for agents that hire agents. Before a job, the worker locks a forecast. After it delivers, Referral's Checker verifies every cited quote against a permitted, dated corpus and recommends `accept` or `reject_and_rematch`. Referral can also issue a signed credential so registries carry checked records instead of open ratings. This PR adds `integrations/referral/`. It contains a Town trust plugin `referral.v1` backed by Referral, scripted research buyer and worker roles, a standard-library MCP stdio client, four Lab scenarios with recorded evidence, an offline verify wrapper, and `tests/test_referral_integration.py`. No file under `src/` changes. ## Integration - Referral runs as its own process from its own repository (`referral serve --history none`). A declared Town participant, `referral_service`, starts it and opens one MCP stdio session for the run (protocol `2025-06-18`, 15 tools listed). `--history none` starts Referral with no simulated workers, so it can only match agents in the town. The command comes from `NANDATOWN_REFERRAL_CMD`. - Every Town agent registers its own Referral identity and calls Referral's tools directly: `register_agent`, `request_match`, `hire`, `get_assignment`, `read_document`, `submit_prediction`, `submit_delivery`, `get_record`, `get_credential`, `get_issuer_key` and `verify_credential`. - Town provides everything else: registry discovery, signed messages and quotes, escrow (hold, then refund or release), data-facts receipts, reputation, and the registry ranking that other agents read. - `referral.v1` lets a receipt move a score only when the trust layer relayed a Referral verdict for that buyer and worker. The verdict sets the sign: +1 for passed, -1 for failed, and 0 when no checked job backs the receipt. - Agent keys never enter the trace. Intents record only the tool name, and the scenarios declare `redact_fields: [key]`. A test checks that no issued key appears in any bundle file. ## Reproduce Nanda Town base commit `6f9a7c0` (current `main`) plus this PR (evidence recorded at commit `ba715bc`; later commits change docs only), nandatown 0.2.0, evaluator `lab-0.2.6`, Python 3.13.18 (the referral tests also pass on 3.11 and 3.12, the versions CI uses). Referral commit [`d41126c`](https://github.com/louis1mx/referral/commit/d41126c3091ebe71c87054b5eac0a94bddbbe108) (branch `hw8-nandatown`, package 0.1.0). No model, API key or network is needed. ```bash git clone https://github.com/louis1mx/referral.git && cd referral git checkout d41126c3091ebe71c87054b5eac0a94bddbbe108 python3 -m venv .venv && .venv/bin/pip install -r requirements-lock.txt -e . export NANDATOWN_REFERRAL_CMD="$PWD/.venv/bin/referral serve --history none" cd ../nandatown # this branch python3 -m venv .venv && source .venv/bin/activate && python -m pip install -e '.[dev]' export NANDATOWN_HOME="$(mktemp -d)" python -m pytest -q tests/test_referral_integration.py # 13 passed nandatown run integrations/referral/scenarios/referral_fabricated_citation.yaml nandatown run integrations/referral/scenarios/referral_fabricated_citation_reputation_control.yaml nandatown run integrations/referral/scenarios/referral_unlocked_forecast.yaml nandatown run integrations/referral/scenarios/referral_unreachable_fail_closed.yaml nandatown compare integrations/referral/scenarios/referral_fabricated_citation.yaml --swap trust=reputation.v1 python integrations/referral/verify.py runs/<id> ``` If no Referral server is available, the live tests skip. The fail-closed run, the MCP client tests and the offline verification of the committed `evidence/` bundles still run. The full write-up is in `integrations/referral/README.md`. ## Results and limitations **Interface tested:** Referral's MCP stdio tool surface, called directly by Town agents, plus `referral.v1` as Town's trust layer, composing with Town's registry, escrow, receipts and registry ran …
Try it
Open PR on GitHubView diffCheckout locally
git fetch origin pull/361/head:pr-361
git checkout pr-361