in reviewhumanPR #359Transport
Cerata: add legal-check Track integration with fault and fail-closed tests
Cerata is a hosted legal check for AI agents. Before an agent calls, texts, emails, lists a home or posts a job, it tells Cerata what it is about to do; Cerata answers clear, flag, hold or block, with a signed receipt anyone can verify…
Description
The pitch.
## Summary Cerata is a hosted legal check for AI agents. Before an agent calls, texts, emails, lists a home or posts a job, it tells Cerata what it is about to do; Cerata answers clear, flag, hold or block, with a signed receipt anyone can verify and, for a clear, a single-use token for that one action. This PR connects the hosted service to Town without moving it in. It adds `examples/integrations/cerata-preflight/`: a stateless Track seller adapter in front of Cerata's API, an agent buyer that judges each answer and verifies receipts independently, 22 situations with the answer Cerata must give, a compatibility check (40 Track runs plus an MCP check), a results/verify script, an offline fixture for CI, and `tests/test_example_cerata_preflight.py`. No Town code changes; `MANIFEST.in` ships the example's data with the tests that read it. ## Integration - **Subject:** Cerata, hosted separately at `clearance-kohl.vercel.app` (release v1.3, deployed commit `2195f7a6`). It is treated as a black box: the check judges only what an agent sees. - **Interface:** the Track mailbox exchange between two `cmd:` participants. The seller (`cerata_seller.py`) claims a `quote_request` carrying the action and calls `POST /v1/preflight` with a test key from the environment. The buyer (`agent_buyer.py`) is an agent that must ask before it acts; it judges the reply, verifies the receipt with Cerata's public `POST /v1/verify` (a channel that goes through neither the seller nor Town), and uses any clearance token once, then checks a second use is refused. - **Stateless adapter:** the seller keeps no journal. Its `Idempotency-Key` is derived from the Town run and message identity, so a redelivery or a restart that forgot everything gets Cerata's stored answer back (`Idempotent-Replayed: true`) and sends a byte-identical reply. The ack reports an application only when Cerata ran a new check, or when the town holds no record of an earlier one. - **MCP:** `mcp_check.py` uses Cerata's MCP endpoint as a host would: `initialize`, `tools/list`, `tools/call preflight` twice under one idempotency key, `tools/call verify`, and a refused key. - **Fixture:** `fake_cerata.py` answers from `cases.json` so CI can test the wiring offline. It is a Town fixture and is not presented as compatibility evidence. ## Reproduce - Town: `projnanda/nandatown@6f9a7c0` (`main`), nandatown 0.2.0, Track evaluator 0.5.0. This branch: `e31d732`. - Cerata: release v1.3 as deployed at commit `2195f7a6` (v1.3 plus the two fixes for finding 1), test environment. Tested on Ubuntu on WSL2 (Linux 6.6) with Python 3.14.4 (example tests also pass on 3.11 and 3.12). ```bash python3 -m venv .venv && source .venv/bin/activate python -m pip install -e '.[dev]' python -m pytest -q tests/test_example_cerata_preflight.py # offline, no key export CERATA_URL=https://clearance-kohl.vercel.app export CERATA_API_KEY=ak_test_... # test key, environment only examples/integrations/cerata-preflight/check.sh runs/cerata python examples/integrations/cerata-preflight/results.py runs/cerata ``` One case: `CERATA_CASE=fl-call-after-8pm nandatown run quote-amnesia-restart --agent "seller=cmd:python examples/integrations/cerata-preflight/cerata_seller.py" --agent "buyer=cmd:python examples/integrations/cerata-preflight/agent_buyer.py"` ## Results and limitations **40 of 41 checks matched against live Cerata; every Track bundle passes `nandatown verify`. The one difference is explained below.** (about 2 minutes, run 2026-11-11; full tables in `examples/integrations/cerata-preflight/RESULTS.md`). | Section | What it tests | Expected | Observed | |---|---|---|---| | situations (22 runs) | state limits stricter than federal, the recipient's location and local time (daylight-saving change, UTC input), consent and do-not-call facts, a rule not yet in force, places and purposes not covered yet, email, a rental listing; receipts, a single-use token, a repeated case | the expe …
Try it
Open PR on GitHubView diffCheckout locally
git fetch origin pull/359/head:pr-359
git checkout pr-359