From 43695187e55fd49ce3220662fb8e3d77aa41d99e Mon Sep 17 00:00:00 2001 From: Dai Ha Date: Sat, 11 Jul 2026 14:50:52 +0200 Subject: [PATCH] README: herdr-centric bridged as leading approach; bump wiki - Swap leading approach to the bridged message server driving herdr (AgentAPI retained as fallback injector); add mermaid overview - Update status to Design (2026-07-11) - Advance wiki submodule to new docs --- README.md | 49 +++++++++++++++++++++++++++++++++++-------------- wiki | 2 +- 2 files changed, 36 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index e735964..8b9a051 100644 --- a/README.md +++ b/README.md @@ -9,26 +9,45 @@ Sibling of [`crush-bridge`](https://git.ltms.dev/systems/vms) (which drives a he process*, so it inherits `CLAUDE.md`, hooks, skills, and MCP — just pointed at a cheaper/local model. -## Leading approach — AgentAPI +## Leading approach — herdr-centric message server (`bridged`) -[`coder/agentapi`](https://github.com/coder/agentapi) wraps the Claude Code **CLI** as an -HTTP server (`POST /message`, `GET /messages`, `GET /events` SSE, `GET /status`). The -worker's model is whatever env its wrapped `claude` process launches with — so the worker -server runs with `ANTHROPIC_BASE_URL=https://ollama.ltms.dev` + a bearer token, and the -primary Opus session talks to it over HTTP. +A small always-on message server, **`bridged`**, controls +[herdr](https://herdr.dev) (an agent multiplexer) over its Unix-socket API and exposes a +clean 2-way messaging API (HTTP/SSE + optional broker). herdr owns the PTYs, multiplexing, +persistence, and **agent-status events**; `bridged` owns policy (subscription boundary, +session lifecycle, status-gated delivery) and the client contract. The worker `claude` +launches with `ANTHROPIC_BASE_URL=https://ollama.ltms.dev` + a bearer token; the primary +Opus stays env-clean and talks to `bridged` over HTTP. -``` - Opus (Claude Code, subscription, env CLEAN) - │ HTTP POST /message ─┐ - ▼ ▼ - agentapi server ──launches──► claude (ANTHROPIC_BASE_URL=ollama.ltms.dev, worker model) - ▲ GET /events (SSE) ◄──┘ +```mermaid +flowchart LR + OPUS["Opus — primary
(Claude Code, env CLEAN)"] + BD["bridged
message server
(not a claude process)"] + HERDR["herdr
panes · agent-status"] + W["worker claude
ANTHROPIC_BASE_URL set"] + M["ollama.ltms.dev
(worker model)"] + + OPUS -->|"POST /message · SSE /events"| BD + BD -->|"Unix socket
send_text · events.subscribe"| HERDR + HERDR -->|"drives PTY"| W + W -->|"inference"| M + + classDef ext fill:#2b6cb0,stroke:#1a365d,color:#ffffff; + classDef core fill:#2f855a,stroke:#22543d,color:#ffffff; + class OPUS ext + class BD,HERDR core ``` - **Subscription boundary:** the *primary* never sets `ANTHROPIC_BASE_URL` (stays on - Pro/Max). Only the *secondary* process is off-subscription. + Pro/Max). Only the *secondary* process is off-subscription — and `bridged` itself is a + plain daemon (no Anthropic quota), so it may poll/subscribe freely. +- **Symmetric 2-way:** herdr can inject a turn into *either* pane (typing keystrokes is + subscription-safe), so primary→worker and worker→primary use one mechanism. - **Different model per process** sidesteps Claude Code's lack of per-subagent provider routing — the worker isn't a subagent, it's its own configured process. +- **AgentAPI** ([`coder/agentapi`](https://github.com/coder/agentapi)) is retained only as a + swappable *fallback injector* behind the same interface. See the wiki for the full + design, comparison, and rationale. ## Docs @@ -46,4 +65,6 @@ Gitea wiki. ## Status -🟡 Planning — AgentAPI selected as the primary approach (2026-07-08). +🟢 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. diff --git a/wiki b/wiki index 5f5c84e..c2c14f7 160000 --- a/wiki +++ b/wiki @@ -1 +1 @@ -Subproject commit 5f5c84e5245861ea41e927234a5fea5c6191dbab +Subproject commit c2c14f791223b222696a7f5e392b527664183eaf