in reviewhumanPR #355Transport
Common Ground: three Claude Code agents plan a meetup through the room, with duplicate and dropout tests
Common Ground is a neutral room where people's personal agents plan a real-world meetup for them. Each agent reads its person's private calendar and profile through that person's own MCP server, shares only typed fields with the room (free…
Description
The pitch.
## Summary
Common Ground is a neutral room where people's personal agents plan a real-world meetup for them. Each agent reads its person's private calendar and profile through that person's own MCP server, shares only typed fields with the room (free windows, and a travel and fit score per venue), and the room picks the time and place whose worst-off person scores highest.
This PR adds `examples/integrations/common-ground/`: a Lab scenario in which three real Claude Code agents, each with its person's private MCP server, plan a two-hour work session through the real Common Ground room, under Town's registry, signed messaging and fault injection. It includes two fault variants, a validator built only from Town events, live evidence, replay fixtures, a runner and tests. It does not change Town's core code.
## Integration
**Interface under test:** the room's MCP tool interface (streamable HTTP), used by real agents as a shared Town service: discovery through Town's registry, then `create_plan`, `join_plan`, `post_availability`, `post_scores` and `wait_for_result`, under Town's signed messaging and injected transport faults.
```
person's private MCP server ◄── Claude Code agent (decides windows, tags, scores)
│
jack-agent, javier-agent, sergio-agent ─┴─ Town messages ─► common-ground-room (cg_room_adapter) ─ MCP ─► Common Ground room
```
- **Common Ground:** [javiersgp/common-ground-mvp](https://github.com/javiersgp/common-ground-mvp) (private; access on request). The room (`room/server.py`, FastMCP over streamable HTTP) and each person's private server (`personal/server.py`, stdio MCP: profile, calendar, free blocks, travel) run outside Town. No project code is in this PR
- **`cg_person` (x3):** one person's agent in Town. The organizer finds the room and the other members through the registry, creates the plan and sends a Town invitation. After joining, each hands the brief, the room's rules and the public venue list to a **Claude Code agent** (`claude -p`, `sonnet`, no built-in tools) connected only to its person's private server. That agent reads the calendar and notes, gets travel estimates, and answers with windows, taste tags and a score for every venue. If the room refuses a post, the agent sees the error once and corrects it
- **`cg_room_adapter`:** publishes a signed `meetup.plan` card and is the only role that calls the room. It maps the Town sender, authenticated by `hmac.v1`, to that person's room token, so no agent holds another person's token. Its MCP client is a small `httpx` client, so Town gets no new dependency
- **Town layers exercised:** registry (discovery), auth `hmac.v1` (signed cards and messages), transport faults (duplicate, drop), memory `kv.v1`, privacy `redact.v1` (the private server's keys never appear in Town's records). The runner also scans every output file for calendar titles, notes, preferences and home details
- **Modes:** `live` runs a fresh room and three Claude Code agents per case. `replay` (the default) answers room calls and agent decisions from fixtures recorded live, so reviewers need no checkout, model or login; it reports `live_room` and `live_agents` as `not_tested`
## Reproduce
- **Nanda Town:** `6f9a7c064486c4a0ae9242f1ff341b8a4aad0244`, Python 3.12
- **Common Ground:** `9fdee5c1efcdc09fefa84b2367c7ed03b8bcbdf8` (tag `hw7`, on `main`)
- **Agents:** Claude Code 2.1.319, model `sonnet`. Live evidence recorded 2026-11-11
```bash
python3 -m venv .venv && source .venv/bin/activate
python -m pip install -e '.[dev]'
# Replay (no checkout, model or login needed)
python examples/integrations/common-ground/run_check.py --out runs/cg
python -m pytest -q tests/test_common_ground_example.py
# Verify the committed live evidence offline
python examples/integrations/common-ground/run_check.py --verify examples/integrations/common-ground/evidence/*/sim-*
# Live (needs repo access and `claude` logged in; about 1 minute and US$0.15-0.20 per case)
g
…Try it
Open PR on GitHubView diffCheckout locally
git fetch origin pull/355/head:pr-355
git checkout pr-355