diff --git a/Team.md b/6-Team.md similarity index 62% rename from Team.md rename to 6-Team.md index 0209e90..06e7ad1 100644 --- a/Team.md +++ b/6-Team.md @@ -1,27 +1,30 @@ -# 3. Team +# 6. Team -The [[Message-Server]] (`bridged`) delivers **one turn into one worker**. A **team** is the -layer above it: a **Claude team-lead** that fans a job out across a **mixed fleet** of -workers — some on Claude, some on the remote local LLM — and reduces their replies. Same -`bridged` delivery, same subscription boundary; this page is only about **orchestration** — -who the workers are, how the lead picks one, and how it runs many at once. +The [Message Server](2-Message-Server) (`bridged`) delivers **one turn into one worker**. A +**team** is the layer above it: a **Claude team-lead** that fans a job out across a **mixed +fleet** of workers — some on Claude, some on the remote local LLM — and reduces their replies. +Same `bridged` delivery, same subscription boundary; this page is only about **orchestration** +— who the workers are, how the lead picks one, and how it runs many at once. -> Delivery mechanics (blocking `POST /message`, status-gated reply envelope) live in -> [[Message-Server]]. Transport rationale is in [[Approaches]]. This page assumes both. +> Delivery mechanics (blocking `bridge_send` MCP call, status-gated reply) live in +> [Message Server](2-Message-Server). Transport rationale is in [Approaches](3-Approaches). +> This page assumes both. ## The team - **Team-lead** — the primary **Opus** (Claude Code, env **CLEAN**, on Pro/Max). Not a - worker; a **thin client of `bridged`**. It plans, routes, dispatches, and integrates, and - never sets `ANTHROPIC_BASE_URL`. + worker; an **MCP client of `bridged`** (it mounts the bridge like everyone else). It plans, + routes, dispatches via `bridge_send`, and integrates — and never sets `ANTHROPIC_BASE_URL`. - **Workers** — a herd of `claude` panes in herdr, each an addressable `bridged` session - with its **own model/env**: + with its **own model/env**, each also **mounting the bridge MCP** (unified setup — they + reply via `bridge_reply`): - **Claude workers** (clean env, e.g. Sonnet) — reasoning-heavy or high-accuracy subtasks. - **Local workers** (`ANTHROPIC_BASE_URL=https://ollama.ltms.dev`) — bulk, cheap, or embarrassingly parallel subtasks. Every worker is still a *real Claude Code process* (inherits `CLAUDE.md`, hooks, skills, -MCP) — only its model differs. Scale each kind horizontally by adding panes. +MCP) — only its model differs. The **same one MCP-mount line** wires lead and every worker +alike. Scale each kind horizontally by adding panes. ### Topology @@ -37,7 +40,7 @@ flowchart TB ANT["api.anthropic.com
(Pro/Max)"] OLL["ollama.ltms.dev
(local model)"] - LEAD -->|"blocking POST /message (target role)"| BD + LEAD -->|"MCP bridge_send (target role)"| BD BD -->|"Unix socket · send_text · events.subscribe"| HERDR HERDR --> WC1 & WC2 & WL1 & WL2 WC1 --> ANT @@ -67,7 +70,7 @@ the session the lead names. ## Subscription boundary in a team -Unchanged from [[Architecture]], and it scales with the fleet: **only local-worker panes** +Unchanged from [Architecture](1-Architecture), and it scales with the fleet: **only local-worker panes** launch with `ANTHROPIC_BASE_URL`. The lead and every Claude worker stay env-clean on the subscription. `bridged` enforces which panes may carry the off-subscription env, so adding workers never widens the boundary. @@ -86,26 +89,26 @@ sequenceDiagram Note over L: split job → subtask A (reasoning), subtask B (bulk) par A → Claude worker - L->>B: POST /message {role: w-claude, prompt: A} + L->>B: bridge_send {role: w-claude, prompt: A} B->>WC: send_text into running pane - WC-->>B: status working → idle + Stop-hook envelope - B-->>L: 200 reply A + WC-->>B: bridge_reply (or status done) + B-->>L: tool result reply A and B → local worker - L->>B: POST /message {role: w-local, prompt: B} + L->>B: bridge_send {role: w-local, prompt: B} B->>WL: send_text into running pane - WL-->>B: status working → idle + Stop-hook envelope - B-->>L: 200 reply B + WL-->>B: bridge_reply (or status done) + B-->>L: tool result reply B end Note over L: reduce → integrate A + B into final answer ``` -- **Map:** the lead issues N concurrent blocking `POST /message` calls (one per subtask → its - chosen worker). Each call blocks only *that* request; `bridged` holds it open until the - worker's turn completes (status-gated) and returns the reply envelope. -- **Reduce:** the lead collects the N envelopes and integrates. A slow local worker never +- **Map:** the lead issues N concurrent blocking `bridge_send` tool calls (one per subtask → + its chosen worker). Each call blocks only *that* request; `bridged` holds it open until the + worker's turn completes (status-gated) and returns the reply as the tool result. +- **Reduce:** the lead collects the N replies and integrates. A slow local worker never blocks a fast Claude worker — wall-clock ≈ the slowest single subtask, not the sum. - **Detached / long jobs** use the async broker path instead of a held request (Channel 2 in - [[Architecture]]), so the lead never busy-polls across turns. + [Architecture](1-Architecture)), so the lead never busy-polls across turns. Fan-out is bounded by the herd size (pane count) and `bridged`'s concurrency policy, not by the lead. @@ -118,8 +121,8 @@ in the lead's `CLAUDE.md` turns Opus into the orchestrator: ```markdown ## Your team (via bridged) -You are the team-lead. Delegate through the bridged client — never launch workers yourself. -Roster: ask bridged for current sessions/roles. +You are the team-lead. Delegate through the bridge MCP tools — never launch workers yourself. +Roster: call bridge_sessions for current sessions/roles. - w-claude-* — Claude Sonnet. Reasoning-heavy / high-accuracy subtasks. - w-local-* — remote local LLM. Bulk, cheap, or parallelizable subtasks. @@ -128,16 +131,16 @@ of them (concurrent blocking sends), THEN gather — never serialize independent Integrate the reply envelopes; you own the final answer. ``` -Wrap the send as a Claude Code skill (`/delegate ""`) so the lead calls one -tool instead of hand-rolling the HTTP request. +`bridge_send` **is** the one tool call — no HTTP to hand-roll. Optionally wrap it in a Claude +Code skill (`/delegate ""`) for ergonomics. ## What this layer does NOT change -- **Delivery** is still `bridged` → herdr `pane.send_text` + status events ([[Message-Server]]). -- **Completion timing** is still the worker status event; **reply content** still rides the - worker `Stop`-hook envelope. +- **Delivery** is still `bridged` → herdr `pane.send_text` + status events ([Message Server](2-Message-Server)). +- **Completion timing** is still the worker status event; **reply content** rides the worker's + `bridge_reply` (or a `Stop`-hook envelope for a herdr-only worker). - **Single-host** still applies: herdr's socket is local, so the whole herd lives on the - `bridged` host. The lead may be remote — it only needs HTTP to `bridged`. + `bridged` host. The lead may be remote — it only needs to reach `bridged`'s MCP endpoint. ## Open questions @@ -145,10 +148,10 @@ tool instead of hand-rolling the HTTP request. (label-based). Start with the former; promote to the latter if routing logic grows. - **Backpressure:** per-role concurrency caps in `bridged` so a fan-out can't exhaust the local gateway. -- **Result schema:** whether reply envelopes should carry structured metadata (worker, model, - tokens) to help the lead's reduce step. +- **Result schema:** whether `bridge_reply` payloads should carry structured metadata (worker, + model, tokens) to help the lead's reduce step. ## Status 🟡 Design (2026-07-11). Orchestration layer over the selected `bridged` server; inherits -herdr (chosen) + AgentAPI (fallback). Delivery unchanged — see [[Message-Server]]. +herdr (chosen) + AgentAPI (fallback). Delivery unchanged — see [Message Server](2-Message-Server). diff --git a/Home.md b/Home.md index 012d817..e39f3b6 100644 --- a/Home.md +++ b/Home.md @@ -67,6 +67,7 @@ Read in order (the sidebar mirrors this): 3. **[Approaches](3-Approaches)** — herdr-centric vs AgentAPI vs Agent SDK vs bus/tmux (research matrix) 4. **[Setup](4-Setup)** — running herdr + `bridged` + a worker pointed at `ollama.ltms.dev` 5. **[Operations](5-Operations)** — health, restart, model swaps, troubleshooting +6. **[Team](6-Team)** — team-lead orchestrating a mixed Claude + local-LLM worker fleet ## Status diff --git a/_Sidebar.md b/_Sidebar.md index 72c16e3..b665466 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -9,6 +9,7 @@ 3. [Approaches](3-Approaches) — transports compared, why herdr 4. [Setup](4-Setup) — bring-up 5. [Operations](5-Operations) — day-2 runbook +6. [Team](6-Team) — orchestrating a mixed fleet --- 🟢 herdr-centric `bridged` · AgentAPI = fallback