From f8bd5d0c519eba979b0f63f730d8809fc67c898a Mon Sep 17 00:00:00 2001 From: Dai Ha Date: Mon, 17 Aug 2026 14:26:08 +0200 Subject: [PATCH] CB-609: bridge_ack takes target, not ticket; mark MCP-Contract.md as historical The instruction surface named a parameter the tool refuses. bridge_ack requires target and msgId (BridgeMcp.java:1001) and errors with 'target and msgId are required' otherwise, but step 5 of the primary procedure said bridge_ack{ticket, msgId}. The table two sections below it was already correct, so the file contradicted itself and the wrong half was in the numbered steps a lead follows. The same line is fixed in the byte-identical wiki template. docs/MCP-Contract.md still opened with 'Greenfield - no MCP code exists yet' and CLAUDE.md pointed every session at it. Audited against BridgeMcp.java: it names two tools that do not exist, omits four that do, gets nearly every parameter name wrong, and uses /workers paths the daemon does not serve. Its status banner now says so and names the live schema as the authority; CLAUDE.md's pointer is narrowed to section 6, which is the part that did survive. Rewrite is CB-609. --- CLAUDE.md | 8 +++++--- docs/MCP-Contract.md | 23 +++++++++++++++++++---- 2 files changed, 24 insertions(+), 7 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 899dacb..5f23fc6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -78,7 +78,7 @@ below are the procedure — run them in order, every task, not only the big ones what makes them reliable. Where the project ships no such skill, spell the procedure out in the brief instead. The brief is self-contained — the worker sees your message and the repo, nothing of your context, your plan, or your screen. -5. **Collect** — `bridge_poll{ticket}` → `bridge_ack{ticket, msgId}`. Answer a worker's `bridge_ask` +5. **Collect** — `bridge_poll{ticket}` → `bridge_ack{target, msgId}`. Answer a worker's `bridge_ask` with `bridge_send{turnId, content}` — **not** `sessionId`. A worker gone quiet is diagnosed with `bridge_status`, never by reading its terminal; it also reports an open question and the `turnId` that answers it. **A worker's ask waits ~55 seconds, and no nudge makes that longer** — so never @@ -192,8 +192,10 @@ charter, not here. - **Never commit** `.mcp.json` (the primary's local copy, flagged `--skip-worktree`) or `wiki/` (a submodule with its own remote). - **Flows and the error model** — rendezvous, `bridge_ask`, detached delivery, turn-done fallback — - are diagrammed in `docs/MCP-Contract.md` §6, kept out of this file because it loads into every - session's context. + are diagrammed in `docs/MCP-Contract.md` **§6 only**. The rest of that page is a pre-build design + doc whose tool names, parameter names and REST paths never caught up with the code, so do not use + it as the tool reference (CB-609). Section 6 is kept out of this file because this file loads into + every session's context. ### Redeploying the daemon — the lead may do this (primary only) diff --git a/docs/MCP-Contract.md b/docs/MCP-Contract.md index 4ba5fff..d631ed6 100644 --- a/docs/MCP-Contract.md +++ b/docs/MCP-Contract.md @@ -1,9 +1,24 @@ # MCP Contract — `bridged`'s unified gateway -> **Status:** 🟡 Design (2026-07-14). Greenfield — no MCP code exists yet; the pom carries -> only Javalin/Jackson. This page defines the tool surface that CB-104 and its followers -> implement. It supersedes nothing; it fills the "MCP server face" left open by the -> [Architecture](1-Architecture) page. +> **Status: 🔴 HISTORICAL DESIGN — do NOT use as the tool reference.** Written 2026-07-14, before +> any MCP code existed. The system shipped and this page never caught up, so **its tool names, +> parameter names and REST paths are wrong today**. Audited 2026-08-17; the specific drift: +> +> - **Tools it names that do not exist:** `bridge_read`, `bridge_cancel`. +> - **Shipped tools it omits:** `bridge_poll`, `bridge_ack`, `bridge_profiles`, `bridge_whoami`. +> - **Parameter names are wrong nearly everywhere** — it says `message`/`target`/`timeout_seconds`/ +> `block` where the code takes `content`/`sessionId`/`timeoutMs`/`wait`; `text` where +> `bridge_reply` takes `content`; `target` where `bridge_stop` takes `paneId`. +> - **REST paths are wrong:** it says `POST /workers` and `DELETE /workers/{paneId}`; the daemon +> serves `POST /members` and `DELETE /members/{paneId}`. +> +> **The authoritative tool surface is the live MCP schema** (each tool's own description and +> parameters, as mounted), with the intent→tool table in `CLAUDE.md` as the short form. Both were +> checked against `mcp/BridgeMcp.java` on 2026-08-17 and are accurate. +> +> What is still worth reading here is **§6 — the flows and the error model** (rendezvous, +> `bridge_ask`, detached delivery, the turn-done fallback). The shapes it describes are the ones +> that shipped; only the names around them drifted. Rewriting this page is tracked as **CB-609**. `bridged` is the **sole communication gateway** for every Claude session in the bridge. Both the **primary** (Opus, on subscription) and every **worker** (off-subscription Claude Code)