From 968a5c68b65942d6fb9350801ce1338850c292e1 Mon Sep 17 00:00:00 2001 From: Dai Ha Date: Thu, 16 Jul 2026 06:46:40 +0200 Subject: [PATCH] docs(README): update Status to reflect the shipped implementation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Status section still read 'Design selected' β€” but bridged is built and dogfooded (CB-101..114, 105 tests, live MCP tools, multi-profile, cwd inheritance, readiness gate). Replace it with an accurate shipped/next breakdown, and drop the bridge_ask overclaim from the gateway bullet (bridge_ask is roadmap, not built). --- README.md | 32 +++++++++++++++++++++++++++----- 1 file changed, 27 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 828d562..313203d 100644 --- a/README.md +++ b/README.md @@ -50,8 +50,9 @@ flowchart LR plain daemon (no Anthropic quota), so it may poll/subscribe freely. - **One gateway (unified MCP setup):** `bridged` is the **sole communication path** for every Claude session. Primary and workers each mount it as an MCP server (one `claude mcp add` - line, same on both) and talk over MCP tools β€” `bridge_send` / `bridge_reply` / `bridge_ask` / - `bridge_status`. **No Claude session ever addresses a broker, a peer, or the network + line, same on both) and talk over MCP tools β€” `bridge_send` / `bridge_reply` / + `bridge_status` (with `bridge_ask` planned for the blocked-worker path). **No Claude session + ever addresses a broker, a peer, or the network directly**; any queue is `bridged`-internal. MCP tool I/O never sets `ANTHROPIC_BASE_URL`, so mounting the bridge is subscription-safe by construction. - **How the primary consumes a reply:** a single **blocking MCP call** (`bridge_send`); @@ -85,6 +86,27 @@ Gitea wiki. ## Status -🟒 Design β€” herdr-centric **`bridged`** message server selected as the primary approach -(2026-07-11), superseding the AgentAPI plan (2026-07-08). AgentAPI retained as fallback -injector. +🟒 **Implemented & dogfooded** β€” the herdr-centric **`bridged`** message server is built and in +real use: an Opus primary delegates tasks to off-subscription workers that reply through the +bridge (code reviews delegated this way have produced committed bug fixes). Selected as the +primary approach 2026-07-11, superseding the AgentAPI plan (2026-07-08); AgentAPI retained as a +fallback injector. + +**Shipped** (Java 25 Β· Maven Β· 105 tests green β€” unit/acceptance + live-herdr contract tests): + +- **Core gateway** β€” herdr socket client (contract-tested vs live 0.7.0); guard-checked worker + spawn with `ANTHROPIC_BASE_URL` injected only into the worker's env; status-gated injector; + blocking `bridge_send` with reply rendezvous; MCP server as a thin adapter over the REST core. +- **MCP tools** β€” `bridge_send` / `bridge_reply` / `bridge_status` (messaging) and `bridge_spawn` + / `bridge_list` / `bridge_stop` / `bridge_profiles` / `bridge_poll` (fleet). Caller identity is + connection-based (loopback peer PID β†’ herdr pane), so the same mount serves primary and workers. +- **Delivery reliability** β€” completion fallback (a confirmed `workingβ†’idle` turn resolves a + send); async fire-and-poll (beats the caller's MCP call timeout for long tasks); and failure + detection for wedged (`unknown`), vanished, and never-ready workers so a send never hangs. +- **Fleet** β€” multiple worker profiles, each with an independent base_url guard check; workers + inherit the primary's working directory (never `$HOME`); a readiness gate holds delivery until + a worker's Claude has connected the bridge MCP (no paste lost into its boot window). + +**Next** (see the [roadmap](wiki/8-Roadmap.md)) β€” structured envelope schema, `bridge_ask` +(blocked-worker path), session lifecycle / recycle / `idle_ttl`, split-host, and hardening +(auth/TLS, `/metrics`, CI, systemd).