|
|
|
@@ -4,11 +4,11 @@
|
|
|
|
|
> 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`.
|
|
|
|
|
> - **Tools it names that do not exist:** `fleet_read`, `fleet_cancel`.
|
|
|
|
|
> - **Shipped tools it omits:** `fleet_poll`, `fleet_ack`, `fleet_profiles`, `fleet_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`.
|
|
|
|
|
> `fleet_reply` takes `content`; `target` where `fleet_stop` takes `paneId`.
|
|
|
|
|
> - **REST paths are wrong:** it says `POST /workers` and `DELETE /workers/{paneId}`; the daemon
|
|
|
|
|
> serves `POST /members` and `DELETE /members/{paneId}`.
|
|
|
|
|
>
|
|
|
|
@@ -60,7 +60,7 @@ face** is the herdr Unix socket. REST/SSE remains only for non-Claude clients an
|
|
|
|
|
flowchart LR
|
|
|
|
|
OPUS["Opus — primary<br/>(Claude Code, env CLEAN)<br/>MCP client"]
|
|
|
|
|
subgraph BD["fleetd — standalone daemon"]
|
|
|
|
|
MCP["MCP server (north face)<br/>bridge_send · bridge_reply<br/>bridge_ask · bridge_status · lifecycle"]
|
|
|
|
|
MCP["MCP server (north face)<br/>fleet_send · fleet_reply<br/>fleet_ask · fleet_status · lifecycle"]
|
|
|
|
|
RDV["rendezvous registry<br/>(blocking-call waiters)"]
|
|
|
|
|
INJ["Injector + StatusPoller<br/>(status-gated writer)"]
|
|
|
|
|
SOCK["herdr socket client (south face)"]
|
|
|
|
@@ -72,8 +72,8 @@ flowchart LR
|
|
|
|
|
HERDR["herdr<br/>panes · agent-status"]
|
|
|
|
|
W["worker claude pane<br/>ANTHROPIC_BASE_URL set<br/>MCP client"]
|
|
|
|
|
|
|
|
|
|
OPUS -->|"bridge_send (blocks)"| MCP
|
|
|
|
|
W -.->|"bridge_reply / bridge_ask"| MCP
|
|
|
|
|
OPUS -->|"fleet_send (blocks)"| MCP
|
|
|
|
|
W -.->|"fleet_reply / fleet_ask"| MCP
|
|
|
|
|
SOCK -->|"agent.start · agent.send<br/>agent.get · pane.close"| HERDR
|
|
|
|
|
HERDR -->|"drives PTY"| W
|
|
|
|
|
|
|
|
|
@@ -97,8 +97,8 @@ request — this is the linchpin of the whole contract and has no code yet.
|
|
|
|
|
- **The primary is "not a worker".** Any connection that does not map to a known worker is
|
|
|
|
|
treated as a primary. It addresses workers **explicitly** by `target` — a session UUID,
|
|
|
|
|
a `terminal_id`, or a friendly `profile` name.
|
|
|
|
|
- **Turn correlation.** A blocking `bridge_send` registers a *waiter* keyed by worker
|
|
|
|
|
identity. A worker's later `bridge_reply` / `bridge_ask` on the same identity resolves that
|
|
|
|
|
- **Turn correlation.** A blocking `fleet_send` registers a *waiter* keyed by worker
|
|
|
|
|
identity. A worker's later `fleet_reply` / `fleet_ask` on the same identity resolves that
|
|
|
|
|
waiter. A `turn_id` is minted per exchange so a clarification round-trip
|
|
|
|
|
(§6.2) rejoins the right turn.
|
|
|
|
|
|
|
|
|
@@ -123,36 +123,36 @@ This adds an MCP-server dependency the pom does not yet carry. See [Open decisio
|
|
|
|
|
|
|
|
|
|
| Tool | Caller | Blocks? | Backing (exists today?) |
|
|
|
|
|
|---|---|---|---|
|
|
|
|
|
| [`bridge_send`](#bridge_send) | primary | yes (default) | `Injector.enqueue` ✅ · rendezvous registry ❌ (CB-104) |
|
|
|
|
|
| [`bridge_reply`](#bridge_reply) | worker | no | rendezvous ❌ · pane injection via `Injector` ✅ |
|
|
|
|
|
| [`bridge_ask`](#bridge_ask) | worker | yes | reverse rendezvous ❌ |
|
|
|
|
|
| [`bridge_status`](#bridge_status) | either | no | `AgentControl.status` ✅ · `Injector.activeTargets` ✅ |
|
|
|
|
|
| [`bridge_spawn`](#lifecycle) | primary | no | `WorkerService.spawn` ✅ (`POST /workers`) |
|
|
|
|
|
| [`bridge_list`](#lifecycle) | either | no | `WorkerService.list` ✅ (`/agents`) |
|
|
|
|
|
| [`bridge_stop`](#lifecycle) | primary | no | `WorkerService.stop` ✅ (`DELETE /workers/{paneId}`) |
|
|
|
|
|
| [`bridge_read`](#bridge_read) | primary | no | `AgentControl.read` ✅ |
|
|
|
|
|
| [`bridge_cancel`](#bridge_cancel) | primary | no | — ❌ (future) |
|
|
|
|
|
| [`fleet_send`](#fleet_send) | primary | yes (default) | `Injector.enqueue` ✅ · rendezvous registry ❌ (CB-104) |
|
|
|
|
|
| [`fleet_reply`](#fleet_reply) | worker | no | rendezvous ❌ · pane injection via `Injector` ✅ |
|
|
|
|
|
| [`fleet_ask`](#fleet_ask) | worker | yes | reverse rendezvous ❌ |
|
|
|
|
|
| [`fleet_status`](#fleet_status) | either | no | `AgentControl.status` ✅ · `Injector.activeTargets` ✅ |
|
|
|
|
|
| [`fleet_spawn`](#lifecycle) | primary | no | `WorkerService.spawn` ✅ (`POST /workers`) |
|
|
|
|
|
| [`fleet_list`](#lifecycle) | either | no | `WorkerService.list` ✅ (`/agents`) |
|
|
|
|
|
| [`fleet_stop`](#lifecycle) | primary | no | `WorkerService.stop` ✅ (`DELETE /workers/{paneId}`) |
|
|
|
|
|
| [`fleet_read`](#fleet_read) | primary | no | `AgentControl.read` ✅ |
|
|
|
|
|
| [`fleet_cancel`](#fleet_cancel) | primary | no | — ❌ (future) |
|
|
|
|
|
|
|
|
|
|
### Core: delegation & rendezvous
|
|
|
|
|
|
|
|
|
|
#### `bridge_send`
|
|
|
|
|
#### `fleet_send`
|
|
|
|
|
*(primary → worker — the headline tool, CB-104)*
|
|
|
|
|
|
|
|
|
|
- **Params:** `message` (required); `target` (optional — defaults to the sole worker / default
|
|
|
|
|
profile); `timeout_seconds` (default 600); `block` (default `true`); `auto_spawn`
|
|
|
|
|
(default `true`); `turn_id` (optional — supplied when answering a worker's `bridge_ask`).
|
|
|
|
|
(default `true`); `turn_id` (optional — supplied when answering a worker's `fleet_ask`).
|
|
|
|
|
- **Blocking (`block:true`):** enqueue `message` via the `Injector`, then hold the call open
|
|
|
|
|
until exactly one of:
|
|
|
|
|
- worker calls `bridge_reply` → `{ outcome:"reply", text }`
|
|
|
|
|
- worker calls `bridge_ask` → `{ outcome:"question", text, turn_id }`
|
|
|
|
|
- worker calls `fleet_reply` → `{ outcome:"reply", text }`
|
|
|
|
|
- worker calls `fleet_ask` → `{ outcome:"question", text, turn_id }`
|
|
|
|
|
- worker's `agent_status` reaches done/idle with no reply → `{ outcome:"turn_done", text:<terminal tail> }`
|
|
|
|
|
- deadline elapses → `{ outcome:"timeout" }`
|
|
|
|
|
- worker gone → error `worker_gone`
|
|
|
|
|
- **Detached (`block:false`):** enqueue and return `{ outcome:"dispatched", dispatch_id }`
|
|
|
|
|
immediately. The eventual reply is injected into the primary's idle pane (§6.3), or drained
|
|
|
|
|
via `bridge_status` on a split-host primary.
|
|
|
|
|
via `fleet_status` on a split-host primary.
|
|
|
|
|
|
|
|
|
|
#### `bridge_reply`
|
|
|
|
|
#### `fleet_reply`
|
|
|
|
|
*(worker → primary)*
|
|
|
|
|
|
|
|
|
|
- **Params:** `text` (required); `final` (default `true`).
|
|
|
|
@@ -160,28 +160,28 @@ This adds an MCP-server dependency the pom does not yet carry. See [Open decisio
|
|
|
|
|
waiter exists (detached delegation), `fleetd` **injects the primary's idle pane** instead.
|
|
|
|
|
Returns `{ delivered:true, mode:"resolved"|"injected" }`. No `target` — identity is implicit.
|
|
|
|
|
|
|
|
|
|
#### `bridge_ask`
|
|
|
|
|
#### `fleet_ask`
|
|
|
|
|
*(worker → primary — the reverse rendezvous)*
|
|
|
|
|
|
|
|
|
|
- **Params:** `question` (required); `timeout_seconds`.
|
|
|
|
|
- **Behavior:** blocks the *worker's* call. Surfaces the question to the primary (resolving its
|
|
|
|
|
open `bridge_send` with `outcome:"question"`, or injecting its pane). When the primary
|
|
|
|
|
answers — a `bridge_send` carrying the matching `turn_id` — that unblocks this call and
|
|
|
|
|
open `fleet_send` with `outcome:"question"`, or injecting its pane). When the primary
|
|
|
|
|
answers — a `fleet_send` carrying the matching `turn_id` — that unblocks this call and
|
|
|
|
|
returns `{ answer }` to the worker, which continues **in the same turn**.
|
|
|
|
|
|
|
|
|
|
### Worker lifecycle
|
|
|
|
|
<a id="lifecycle"></a>
|
|
|
|
|
Thin adapters over [`WorkerService`](1-Architecture) — parity with the existing REST routes.
|
|
|
|
|
|
|
|
|
|
- **`bridge_spawn`** — `{ profile? }` → worker view (`sessionId`, `terminalId`, `paneId`,
|
|
|
|
|
- **`fleet_spawn`** — `{ profile? }` → worker view (`sessionId`, `terminalId`, `paneId`,
|
|
|
|
|
`status`). Guard-checked; a boundary breach returns error `subscription_boundary` (the
|
|
|
|
|
REST `403`).
|
|
|
|
|
- **`bridge_list`** — no params → all workers + `agent_status`. Read-only, either role.
|
|
|
|
|
- **`bridge_stop`** — `{ target }` → tears down the pane and its dedicated tab. Idempotent.
|
|
|
|
|
- **`fleet_list`** — no params → all workers + `agent_status`. Read-only, either role.
|
|
|
|
|
- **`fleet_stop`** — `{ target }` → tears down the pane and its dedicated tab. Idempotent.
|
|
|
|
|
|
|
|
|
|
### Observability
|
|
|
|
|
|
|
|
|
|
#### `bridge_status`
|
|
|
|
|
#### `fleet_status`
|
|
|
|
|
*(either role — the README's 4th named tool)*
|
|
|
|
|
|
|
|
|
|
- **Params:** `target?`.
|
|
|
|
@@ -190,7 +190,7 @@ Thin adapters over [`WorkerService`](1-Architecture) — parity with the existin
|
|
|
|
|
messages addressed to me** — the path a split-host primary's `Stop`-hook uses to wake and
|
|
|
|
|
collect replies without being injectable. Read-only, non-blocking.
|
|
|
|
|
|
|
|
|
|
#### `bridge_read`
|
|
|
|
|
#### `fleet_read`
|
|
|
|
|
*(primary)*
|
|
|
|
|
|
|
|
|
|
- **Params:** `target`; `source` ∈ `visible | recent | recent_unwrapped | detection`.
|
|
|
|
@@ -199,7 +199,7 @@ Thin adapters over [`WorkerService`](1-Architecture) — parity with the existin
|
|
|
|
|
|
|
|
|
|
### Control (future)
|
|
|
|
|
|
|
|
|
|
#### `bridge_cancel`
|
|
|
|
|
#### `fleet_cancel`
|
|
|
|
|
*(primary)*
|
|
|
|
|
|
|
|
|
|
- **Params:** `target`. Interrupt the worker's current turn / abandon the rendezvous. No
|
|
|
|
@@ -294,7 +294,7 @@ sequenceDiagram
|
|
|
|
|
## 7. Status gating
|
|
|
|
|
|
|
|
|
|
Delivery only happens in a safe window. This is the state machine the `Injector` already
|
|
|
|
|
enforces via `AgentStatus.injectable()`; MCP `bridge_send` is simply its producer.
|
|
|
|
|
enforces via `AgentStatus.injectable()`; MCP `fleet_send` is simply its producer.
|
|
|
|
|
|
|
|
|
|
```mermaid
|
|
|
|
|
stateDiagram-v2
|
|
|
|
@@ -330,17 +330,17 @@ touching this state machine.
|
|
|
|
|
|
|
|
|
|
## 8. Error model
|
|
|
|
|
|
|
|
|
|
| Condition | `bridge_send` result | Notes |
|
|
|
|
|
| Condition | `fleet_send` result | Notes |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| Worker replies | `{ outcome:"reply" }` | normal |
|
|
|
|
|
| Worker asks | `{ outcome:"question", turn_id }` | answer with `bridge_send(turn_id)` |
|
|
|
|
|
| Worker asks | `{ outcome:"question", turn_id }` | answer with `fleet_send(turn_id)` |
|
|
|
|
|
| Turn ends, no reply | `{ outcome:"turn_done" }` | terminal tail as text |
|
|
|
|
|
| Deadline elapsed | `{ outcome:"timeout" }` | message may still be queued/delivered |
|
|
|
|
|
| Worker vanished | error `worker_gone` | `Injector.drop` fails the queued future |
|
|
|
|
|
| Guard breach on spawn | error `subscription_boundary` | REST `403` parity |
|
|
|
|
|
| Delivery failed at herdr | error, message dropped | poisoned message not left blocking the FIFO |
|
|
|
|
|
|
|
|
|
|
`bridge_reply` from a worker with no open waiter is **not** an error — it falls through to
|
|
|
|
|
`fleet_reply` from a worker with no open waiter is **not** an error — it falls through to
|
|
|
|
|
detached pane injection (§6.3).
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
@@ -352,11 +352,11 @@ seam. Only the **rendezvous registry** and the **caller-identity resolver** are
|
|
|
|
|
|
|
|
|
|
| MCP tool | Existing collaborator | New work |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| `bridge_send` | `Injector.enqueue`, `AgentControl.send` | waiter registry, timeout, outcome mux (CB-104) |
|
|
|
|
|
| `bridge_reply` / `bridge_ask` | `Injector` (pane injection) | reverse rendezvous, identity resolver |
|
|
|
|
|
| `bridge_status` | `AgentControl.status`, `Injector.activeTargets` | pending-drain projection |
|
|
|
|
|
| `bridge_spawn` / `list` / `stop` | `WorkerService.{spawn,list,stop}` | MCP adapter only |
|
|
|
|
|
| `bridge_read` | `AgentControl.read` | MCP adapter only |
|
|
|
|
|
| `fleet_send` | `Injector.enqueue`, `AgentControl.send` | waiter registry, timeout, outcome mux (CB-104) |
|
|
|
|
|
| `fleet_reply` / `fleet_ask` | `Injector` (pane injection) | reverse rendezvous, identity resolver |
|
|
|
|
|
| `fleet_status` | `AgentControl.status`, `Injector.activeTargets` | pending-drain projection |
|
|
|
|
|
| `fleet_spawn` / `list` / `stop` | `WorkerService.{spawn,list,stop}` | MCP adapter only |
|
|
|
|
|
| `fleet_read` | `AgentControl.read` | MCP adapter only |
|
|
|
|
|
|
|
|
|
|
Because the REST routes in `FleetApp` already exercise the collaborators, MCP tools are
|
|
|
|
|
validated by **parity** against those routes, not by re-testing behavior.
|
|
|
|
@@ -365,14 +365,14 @@ validated by **parity** against those routes, not by re-testing behavior.
|
|
|
|
|
|
|
|
|
|
## 10. Open decisions
|
|
|
|
|
|
|
|
|
|
1. **`bridge_ask` direction.** This page defines it as *worker-asks-primary* (a genuine reverse
|
|
|
|
|
1. **`fleet_ask` direction.** This page defines it as *worker-asks-primary* (a genuine reverse
|
|
|
|
|
channel, matching the "inject the primary's pane" language). The alternative — a synonym for
|
|
|
|
|
a blocking primary→worker send — is weaker and produces different plumbing. **Recommend
|
|
|
|
|
worker-asks-primary.**
|
|
|
|
|
2. **Detached delivery shape.** A `block:false` param on `bridge_send` (keeps the catalog
|
|
|
|
|
small) vs. a separate `bridge_dispatch` tool. **Recommend the param.**
|
|
|
|
|
3. **Auto-spawn on send.** `bridge_send` provisions a worker per profile when none exists
|
|
|
|
|
(simplest primary UX) vs. requiring an explicit `bridge_spawn` first. **Recommend
|
|
|
|
|
2. **Detached delivery shape.** A `block:false` param on `fleet_send` (keeps the catalog
|
|
|
|
|
small) vs. a separate `fleet_dispatch` tool. **Recommend the param.**
|
|
|
|
|
3. **Auto-spawn on send.** `fleet_send` provisions a worker per profile when none exists
|
|
|
|
|
(simplest primary UX) vs. requiring an explicit `fleet_spawn` first. **Recommend
|
|
|
|
|
auto-spawn, defaulting on.**
|
|
|
|
|
4. **Transport & SDK.** Streamable-HTTP/SSE co-located with the REST bind (recommended) vs.
|
|
|
|
|
stdio. Requires choosing a Java MCP server SDK and adding it to the pom.
|
|
|
|
@@ -381,9 +381,9 @@ validated by **parity** against those routes, not by re-testing behavior.
|
|
|
|
|
|
|
|
|
|
## 11. Implementation staging
|
|
|
|
|
|
|
|
|
|
- **CB-104** — blocking `bridge_send` + rendezvous registry + caller-identity resolver
|
|
|
|
|
- **CB-104** — blocking `fleet_send` + rendezvous registry + caller-identity resolver
|
|
|
|
|
(the producer that finally drives the inert `StatusPoller`).
|
|
|
|
|
- **CB-1xx** — `bridge_reply` / `bridge_ask` reverse rendezvous + detached pane injection.
|
|
|
|
|
- **CB-1xx** — lifecycle + observability adapters (`bridge_spawn/list/stop/status/read`).
|
|
|
|
|
- **CB-1xx** — `fleet_reply` / `fleet_ask` reverse rendezvous + detached pane injection.
|
|
|
|
|
- **CB-1xx** — lifecycle + observability adapters (`fleet_spawn/list/stop/status/read`).
|
|
|
|
|
- **CB-1xx** — transport wiring + `claude mcp add` docs; parity tests vs. REST.
|
|
|
|
|
- **Later** — `bridge_cancel`; swap `StatusPoller` for herdr `events.subscribe`.
|
|
|
|
|
- **Later** — `fleet_cancel`; swap `StatusPoller` for herdr `events.subscribe`.
|
|
|
|
|
Dai Ha