From 06483b66eb383068bc53d733cca01c0775bf9e70 Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Sat, 13 Jun 2026 21:38:19 +0200 Subject: [PATCH] docs: rename stale Herdr wire-type names to Colibri in glasspane doc Salvages the non-stale part of docs/colibri-socket-name-cleanup. The daemon's wire types are ColibriCommand/ColibriResponse (renamed from Herdr* long ago), but COLIBRI-DAEMON-GLASSPANE-INTEGRATION.md still documented the old Herdr* names. (The branch's other edit touched docs/CLAWDIE-BUILD.md, which #34 deleted, so it is dropped.) Co-authored-by: Sam & Codex (docs/colibri-socket-name-cleanup) Co-Authored-By: Claude Opus 4.8 --- docs/COLIBRI-DAEMON-GLASSPANE-INTEGRATION.md | 48 ++++++++++---------- 1 file changed, 23 insertions(+), 25 deletions(-) diff --git a/docs/COLIBRI-DAEMON-GLASSPANE-INTEGRATION.md b/docs/COLIBRI-DAEMON-GLASSPANE-INTEGRATION.md index 21b658b..1ef43c0 100644 --- a/docs/COLIBRI-DAEMON-GLASSPANE-INTEGRATION.md +++ b/docs/COLIBRI-DAEMON-GLASSPANE-INTEGRATION.md @@ -18,8 +18,8 @@ crates to be updated in lockstep. │ │ │ ┌──────────┐ ┌───────────┐ ┌──────────┐ ┌───────────────┐ │ │ │ Spawner │ │ Sessions │ │ Heartbeat │ │ Socket Server │ │ -│ │ (agents) │ │ (JSONL) │ │ (30s) │ │ (Unix domain) │──┼──► Colibri TUI / web -│ └─────┬─────┘ └───────────┘ └─────┬─────┘ └───────┬───────┘ │ Zed / optional Herdr Linux +│ │ (agents) │ │ (JSONL) │ │ (30s) │ │ (Unix domain) │──┼──► Herdr / web +│ └─────┬─────┘ └───────────┘ └─────┬─────┘ └───────┬───────┘ │ board / Zed │ │ │ │ │ │ │ stdout JSONL │ poll_exit() │ query │ │ ▼ ▼ ▼ │ @@ -104,8 +104,8 @@ Server: {"ok":true,"data":{"agent_id":"a1b2-c3d4","status":"running"}}\n ### Operator CLI smoke helpers -`colibri-client` also ships small binaries for manual display-client and SSH -smoke tests without hand-writing socket JSON: +`colibri-client` also ships two small binaries for manual Herdr/SSH smoke tests +without hand-writing socket JSON: ```sh # Inspect daemon state @@ -219,19 +219,19 @@ AgentHandle SupervisedPane Session ### Daemon lifecycle events → Glasspane AgentState -| Daemon lifecycle event | Ingested Pi event type | Resulting `AgentState` | Notes | -| ------------------------------ | ------------------------------------------------------- | ---------------------- | ---------------------------------------------- | -| Agent subprocess spawned | _(pane attached, state = `Idle`)_ | `Idle` | `SupervisedPane::new` defaults to `Idle` | -| Agent emits `session` header | `session` / `session_started` | `Idle` | Also captures `pi_session_id` and `cwd` | -| Agent emits turn/message/tool | `turn_start`, `message_start`, `tool_execution_*`, etc. | `Working` | Any of 14 event types | -| Agent emits compaction events | `auto_compaction_*`, `compaction_*` | `Working` | Compaction is active work | -| Agent emits retry events | `auto_retry_*` | `Working` | Retry is active work | -| Agent awaits steering/approval | `queue_update` | `Blocked` | Operator attention needed (dashboard headline) | -| Turn/task complete | `turn_end` / `agent_end` | `Done` | Agent reached a completion point | -| Agent emits explicit error | `error` | `Error` | Terminal failure state | -| Agent subprocess exits (0) | _daemon injects `agent_end`_ | `Done` | Heartbeat detected normal exit | -| Agent subprocess exits (!=0) | _daemon injects `error`_ | `Error` | Heartbeat detected crash/error exit | -| Agent killed externally | _daemon injects `error`_ | `Error` | `kill-agent` command | +| Daemon lifecycle event | Ingested Pi event type | Resulting `AgentState` | Notes | +| ------------------------------ | ------------------------------------------------------- | ---------------------- | ------------------------------------------ | +| Agent subprocess spawned | _(pane attached, state = `Idle`)_ | `Idle` | `SupervisedPane::new` defaults to `Idle` | +| Agent emits `session` header | `session` / `session_started` | `Idle` | Also captures `pi_session_id` and `cwd` | +| Agent emits turn/message/tool | `turn_start`, `message_start`, `tool_execution_*`, etc. | `Working` | Any of 14 event types | +| Agent emits compaction events | `auto_compaction_*`, `compaction_*` | `Working` | Compaction is active work | +| Agent emits retry events | `auto_retry_*` | `Working` | Retry is active work | +| Agent awaits steering/approval | `queue_update` | `Blocked` | Operator attention needed (Herdr headline) | +| Turn/task complete | `turn_end` / `agent_end` | `Done` | Agent reached a completion point | +| Agent emits explicit error | `error` | `Error` | Terminal failure state | +| Agent subprocess exits (0) | _daemon injects `agent_end`_ | `Done` | Heartbeat detected normal exit | +| Agent subprocess exits (!=0) | _daemon injects `error`_ | `Error` | Heartbeat detected crash/error exit | +| Agent killed externally | _daemon injects `error`_ | `Error` | `kill-agent` command | ### State transition diagram @@ -446,12 +446,11 @@ let snapshot = state.glasspane.read().await.snapshot_at( ### Where it is consumed -| Consumer | Transport | Phase | Purpose | -| ----------------------------- | ------------------ | ----- | -------------------------------------------- | -| `colibri` CLI / `colibri-tui` | Unix socket | 4 | Native operator dashboard and smoke surface | -| Herdr (Linux/macOS optional) | Unix socket/bridge | 4 | Optional external display client, not source | -| Zed / web board | HTTP / SSE | 4 | Web-based supervision view | -| colibri-orchestrator | In-memory / socket | 5 | Route/dispatch work across panes | +| Consumer | Transport | Phase | Purpose | +| -------------------- | ------------------ | ----- | -------------------------------- | +| Herdr (Linux) | Unix socket | 4 | Operator dashboard display | +| Zed / web board | HTTP / SSE | 4 | Web-based supervision view | +| colibri-orchestrator | In-memory / socket | 5 | Route/dispatch work across panes | ### Wire shape (JSON) @@ -516,8 +515,7 @@ library crate, not a process — it is compiled into the daemon binary. ├── Accepts connections └── Dispatches ColibriCommand variants │ -5. External clients (colibri CLI/TUI, optional Herdr Linux/macOS, web) connect - and send commands +5. External clients (Herdr, web) connect and send commands ``` ### Clean boot checklist (in sequence) -- 2.45.3