diff --git a/crates/colibri-daemon/src/spawner.rs b/crates/colibri-daemon/src/spawner.rs index 60bbe33..7f88cc6 100644 --- a/crates/colibri-daemon/src/spawner.rs +++ b/crates/colibri-daemon/src/spawner.rs @@ -334,7 +334,7 @@ impl RpcSender { /// Build one newline-terminated RPC prompt request line in zot's wire format: /// a bare JSON object `{"id","type":"prompt","message"}` (no JSON-RPC envelope), -/// matching the transcript in `docs/ZOT-RPC-TRANSCRIPT.md`. `serde_json` escapes +/// matching the transcript in `docs/AGENT-EVENTS-REFERENCE.md`. `serde_json` escapes /// the message, so embedded quotes/newlines are safe. fn build_rpc_prompt(id: &str, message: &str) -> String { let obj = serde_json::json!({ diff --git a/docs/ZOT-RPC-TRANSCRIPT.md b/docs/AGENT-EVENTS-REFERENCE.md similarity index 93% rename from docs/ZOT-RPC-TRANSCRIPT.md rename to docs/AGENT-EVENTS-REFERENCE.md index 38f42e9..dfdd092 100644 --- a/docs/ZOT-RPC-TRANSCRIPT.md +++ b/docs/AGENT-EVENTS-REFERENCE.md @@ -1,4 +1,12 @@ -# zot rpc transcript — DeepSeek (2026-06-21) +# Agent events reference + +> **Developer reference — operators can skip.** Plain version: `wiki/agent-harness`. + +Per-harness reference for the event stream Colibri ingests into Glasspane. Each +harness emits its own format; this file documents one section per harness. +Currently documented: **zot** (the pi harness emits `pi --mode json` events, +parsed by `pi_event_type`). The zot capture below is from a real DeepSeek run +(21.jun.2026). ## Request shape @@ -56,7 +64,7 @@ needed to capture a real tool call before the driver can trust those mappings. Step 1 of colibri#143 is complete after the real-key re-run below. Steps 2 and 3 are unblocked. -## Real-key transcript (complete tool call, 2026-06-21) +## Real-key transcript (complete tool call, 21.jun.2026) Prompt: "run uname -a and tell me the kernel version in one sentence" 61 lines, 2 turns, 1 tool call (bash), DeepSeek v4-pro, cached tokens. diff --git a/docs/README.md b/docs/README.md index 9443efa..acc73b6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,4 +18,4 @@ A quick-reference guide to every document in this folder. | [`PLAN-MOTHER-MCP-VAULT-KEYS.md`](PLAN-MOTHER-MCP-VAULT-KEYS.md) | Vaultwarden pubkey exchange for mother MCP link (direction B) | Sam & Hermes | | [`PRIORITY-HANDOFF-ISO-SPAWN-COST.md`](PRIORITY-HANDOFF-ISO-SPAWN-COST.md) | ISO boot validation, Pi spawn path, cost mode enforcement (P2/P3 done) | All agents | | [`TRUSS-SPAWN-ANALYSIS.md`](TRUSS-SPAWN-ANALYSIS.md) | truss trace of jail-spawn Permission Denied — root cause + fix | Debugging | -| [`VAULT-PROVISION-FIRST-PROOF.md`](VAULT-PROVISION-FIRST-PROOF.md) | First-proof runbook: vault → jail → `.env` chain (clean CLI) | Agents, Sam | +| [`VAULT-PROVISION-RUNBOOK.md`](VAULT-PROVISION-RUNBOOK.md) | First-proof runbook: vault → jail → `.env` chain (clean CLI) | Agents, Sam | diff --git a/docs/VAULT-PROVISION-FIRST-PROOF.md b/docs/VAULT-PROVISION-RUNBOOK.md similarity index 99% rename from docs/VAULT-PROVISION-FIRST-PROOF.md rename to docs/VAULT-PROVISION-RUNBOOK.md index 469655f..bbdf75f 100644 --- a/docs/VAULT-PROVISION-FIRST-PROOF.md +++ b/docs/VAULT-PROVISION-RUNBOOK.md @@ -1,4 +1,4 @@ -# Vault Provision — First-Proof Runbook (osa) +# Vault Provision Runbook (osa) **Status.** The spawn → vault-provision → `.env` chain is **wired, hardened, and drivable from the CLI**. The three gaps that previously forced a manual path are diff --git a/docs/wiki/agent-harness.md b/docs/wiki/agent-harness.md index 0226fff..13bb848 100644 --- a/docs/wiki/agent-harness.md +++ b/docs/wiki/agent-harness.md @@ -38,7 +38,7 @@ Where it lives: - autospawn binary-aware argv (`zot → rpc`, pi → `--mode json`): `crates/colibri-daemon/src/socket.rs` (`default_agent_args`, `autospawn_agent_if_configured`) -- wire format (verified against real zot): [ZOT-RPC-TRANSCRIPT](../ZOT-RPC-TRANSCRIPT.md) +- wire format (verified against real zot): [AGENT-EVENTS-REFERENCE](../AGENT-EVENTS-REFERENCE.md) - end-to-end proof: `crates/colibri-daemon/tests/zot_rpc_smoke.rs` (`#[ignore]`, `ZOT_BIN`-gated) diff --git a/docs/wiki/naming-decisions.md b/docs/wiki/naming-decisions.md index be32430..e96807e 100644 --- a/docs/wiki/naming-decisions.md +++ b/docs/wiki/naming-decisions.md @@ -6,6 +6,24 @@ A living record of renames driven by superseded assumptions, so future drift is checkable against one list. "Shipped" means merged to `main`; verify against the linked code before trusting a row. +## Naming principle — harness-agnostic by default + +Name a thing by what it **is**, not by the harness that happens to be the +current default: + +- **Neutral concept** (any harness has one — a session id, an event type, + autospawn, "the agent") → a **neutral name**. The harness is a _configurable + value_ (e.g. `COLIBRI_AUTOSPAWN_BINARY=zot`), never baked into the name and + always operator-overridable. +- **Harness-specific thing** (one harness's actual wire format) → the harness + name belongs in it, and the parallels stay symmetric (`zot_event_type` ↔ + `pi_event_type`, `AgentRuntime::{Zot, Pi}`) so neither is privileged. + +The `pi_*` rows in [Shipped](#shipped) are the cautionary tale: neutral concepts +wrongly named after a harness. Same applies to docs — a per-harness reference is +neutral (`AGENT-EVENTS-REFERENCE`), not `ZOT-…`, unless it is truly about one +harness only. + ## Shipped | Old → New | Why | Anchor |