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…

Author

Status
In review
Opened on
Nov 11
Branch
integration/common-ground-meetup

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 diff

Checkout locally

git fetch origin pull/355/head:pr-355
git checkout pr-355