From 064079e3fc02523d942fd54a2cb09fc98ef8f25f Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Wed, 24 Jun 2026 16:33:40 +0200 Subject: [PATCH] docs: harness-agnostic + plainer doc names; codify naming principle MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - ZOT-RPC-TRANSCRIPT.md → AGENT-EVENTS-REFERENCE.md: neutral, per-harness event reference (currently documents zot; pi uses pi --mode json). Avoids baking the current default harness into a name — same lesson as the pi_* renames. Adds a 'Developer reference — operators can skip' header. - VAULT-PROVISION-FIRST-PROOF.md → VAULT-PROVISION-RUNBOOK.md: it's a runbook; 'first-proof' was redundant. - Updated referrers: spawner.rs, wiki/agent-harness.md, docs/README.md. - wiki/naming-decisions.md: new 'Naming principle — harness-agnostic by default' section (neutral concept → neutral name + configurable value; harness-specific → harness in the name, kept symmetric zot_/pi_). - Fixed US/ISO prose dates → DD.mon.YYYY (21.jun.2026) per AGENTS.md; left the literal JSON "time" timestamps in the captured transcript as-is (data). Gates: wiki-lint --strict clean; markdown format clean. --- crates/colibri-daemon/src/spawner.rs | 2 +- ...TRANSCRIPT.md => AGENT-EVENTS-REFERENCE.md} | 12 ++++++++++-- docs/README.md | 2 +- ...RST-PROOF.md => VAULT-PROVISION-RUNBOOK.md} | 2 +- docs/wiki/agent-harness.md | 2 +- docs/wiki/naming-decisions.md | 18 ++++++++++++++++++ 6 files changed, 32 insertions(+), 6 deletions(-) rename docs/{ZOT-RPC-TRANSCRIPT.md => AGENT-EVENTS-REFERENCE.md} (93%) rename docs/{VAULT-PROVISION-FIRST-PROOF.md => VAULT-PROVISION-RUNBOOK.md} (99%) 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 | -- 2.45.3