clawdie/colibri
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 43

docs: move reference docs into wiki (agent-events, headroom, layered-soul)

Browse source
This commit is contained in:
Sam & Claude 2026-06-24 17:32:13 +02:00
parent 28af7ecc75
commit 5896a4ddcd
7 changed files with 58 additions and 44 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/README.md
View file

@ -10,8 +10,6 @@ A quick-reference guide to every document in this folder.
| [`COLIBRI-JAILED-AGENT-SPAWN-DESIGN.md`](COLIBRI-JAILED-AGENT-SPAWN-DESIGN.md) | FreeBSD jail confinement for spawned agents — accepted & implemented | Rust agents |
| [`COLIBRI-SKILLS-PLAN.md`](COLIBRI-SKILLS-PLAN.md) | Skills catalog roadmap: read-only Phase 1, write-gated Phase 2+ | Agents |
| [`COLIBRI-TOKENOMICS-TRIFECTA.md`](COLIBRI-TOKENOMICS-TRIFECTA.md) | Strategic vision: useful tokens, cost-per-intelligence, measurement | All |
| [`HEADROOM-SIDECAR.md`](HEADROOM-SIDECAR.md) | Optional `headroom-ai` tool-result compression sidecar | Agents |
| [`INTEGRATION-LAYERED-SOUL.md`](INTEGRATION-LAYERED-SOUL.md) | How Colibri consumes `layered-soul` reviewed context today vs planned | Agents |
| [`ISO-ACCEPTANCE-RUNBOOK.md`](ISO-ACCEPTANCE-RUNBOOK.md) | Post-boot acceptance commands after staging Colibri into an ISO | Codex (FreeBSD) |
| [`ISO-SERVICE-LAYOUT.md`](ISO-SERVICE-LAYOUT.md) | `rc.conf` service layout for the ISO image | All |
| [`MULTI-AGENT-HOST-PLAN.md`](MULTI-AGENT-HOST-PLAN.md) | **Current sprint**: multi-agent task-board tests + CLI surface gaps | All agents |

17
docs/AGENT-EVENTS-REFERENCE.md → docs/wiki/agent-events-reference.md
View file

@ -1,12 +1,6 @@
# 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).
← [index](./index.md)
## Request shape
@ -64,7 +58,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, 21.jun.2026)
## Real-key transcript (complete tool call, 2026-06-21)
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.
@ -97,7 +91,7 @@ Prompt: "run uname -a and tell me the kernel version in one sentence"
{"type":"done"}
```
Full 61-line transcript at `/tmp/zot_transcript_full.txt` (OSA).
Full 61-line transcript is stored on OSA, outside the repository.
### Confirmed event types (real-key run)
@ -141,3 +135,8 @@ normalizer. `tool_use_start` is the sole entry point for tool execution start.
Step 1 of colibri#143 is complete — wire format and all 15 event types are
validated against real output. The `tool_call` double-fire gap is resolved by
skipping the duplicate standalone event in Glasspane.
## See also
- [agent-harness](./agent-harness.md) — the zot / Colibri split and autospawn model
- [glasspane](./glasspane.md) — the state machine that consumes these events

2
docs/wiki/agent-harness.md
View file

@ -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): [AGENT-EVENTS-REFERENCE](../AGENT-EVENTS-REFERENCE.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)

4
docs/wiki/cost-model.md
View file

@ -27,7 +27,7 @@ you an upper bound but not the real cost. DeepSeek's API sometimes re-caches and
sometimes doesn't — the probe measures what actually happened. The discount is
too large (10×) to leave unmeasured.
→ [`HEADROOM-SIDECAR.md`](../HEADROOM-SIDECAR.md),
→ [headroom-sidecar](./headroom-sidecar.md),
[`COLIBRI-TOKENOMICS-TRIFECTA.md`](../COLIBRI-TOKENOMICS-TRIFECTA.md),
[`crates/colibri-deepseek/src/lib.rs`](../../crates/colibri-deepseek/src/lib.rs)
@ -66,7 +66,7 @@ needs to continue. Compaction preserves the semantic content at lower token cost
The headroom sidecar is optional (off by default); without it, the fallback is
simple truncation.
→ [`HEADROOM-SIDECAR.md`](../HEADROOM-SIDECAR.md),
→ [headroom-sidecar](./headroom-sidecar.md),
[`crates/colibri-daemon/src/session.rs`](../../crates/colibri-daemon/src/session.rs)
### Cache-hit probe (DeepSeek-specific)

9
docs/HEADROOM-SIDECAR.md → docs/wiki/headroom-sidecar.md
View file

@ -1,4 +1,6 @@
# Headroom sidecar for Colibri
# Headroom sidecar
← [index](./index.md)
Colibri can optionally ask a local `headroom-ai` sidecar to compress tool results
before they are rendered through the session read path.
@ -67,3 +69,8 @@ Current daemon timeout: 5 seconds per sidecar request.
FreeBSD: ONNX/ORT-backed extras need local packaging; use a known-good Python
environment and validate `scripts/headroom-sidecar.py` directly before enabling
the daemon flag.
## See also
- [cost-model](./cost-model.md) — cost discipline and when to use Headroom
- [operator-cli](./operator-cli.md) — status JSON reports headroom connection state

41
docs/wiki/index.md
View file

@ -43,22 +43,25 @@ warning.
## Pages
| Page | What it covers |
| ------------------------------------------- | --------------------------------------------------------------------------------------------- |
| [agent-harness](./agent-harness.md) | The zot (agent) + Colibri (control plane) split; autospawn + RPC driver |
| [cost-model](./cost-model.md) | Byte-stable prefixes, cache-hit metering, auto-escalation, T14 compaction |
| [glasspane](./glasspane.md) | Agent state machine, JSONL streaming, AgentRuntime taxonomy, snapshot API |
| [jail-confinement](./jail-confinement.md) | Persistent vs ephemeral jails, priv-mode policy, reuse of spawner confinement for MCP servers |
| [mother-hive](./mother-hive.md) | Mother MCP architecture — forced-command SSH, single-home-in-colibri, peer auth, key-on-seed |
| [naming-decisions](./naming-decisions.md) | Ledger of harness-neutral / architecture renames — shipped and in-flight |
| [task-board](./task-board.md) | Capability match scoring, cron scheduling, intake drain, SQLite backing |
| [quality-gates](./quality-gates.md) | `ci-checks.sh` as the pre-merge gate; why drift reached `main` before |
| [contracts](./contracts.md) | Stable JSON schemas (run-manifest, runtime-inventory, provider-smoke), golden tests |
| [store-schema](./store-schema.md) | SQLite coordination schema and migration discipline |
| [external-mcp](./external-mcp.md) | MCP bridge for editors + external stdio MCP host; read/write/external-call gates |
| [operator-cli](./operator-cli.md) | The `colibri` CLI as a thin typed Unix-socket client over the daemon API |
| [tui](./tui.md) | Terminal dashboard client (colibri-tui) vs the colibri-glasspane state machine |
| [runtime-inventory](./runtime-inventory.md) | Host runtime inventory + watchdog status reader; additive, read-only integrations |
| [skills-catalog](./skills-catalog.md) | Read-only runtime consumer for reviewed Clawdie-AI skill artifacts |
| [vault-provision](./vault-provision.md) | Vaultwarden-driven env-file provisioning into jails after agent spawn |
| [deployment](./deployment.md) | Host installer (clawdie): ZFS layout, rc.d/systemd service, dry-run safety |
| Page | What it covers |
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| [agent-harness](./agent-harness.md) | The zot (agent) + Colibri (control plane) split; autospawn + RPC driver |
| [agent-events-reference](./agent-events-reference.md) | Per-harness zot event reference, Glasspane mappings, and verified transcript fields |
| [cost-model](./cost-model.md) | Byte-stable prefixes, cache-hit metering, auto-escalation, T14 compaction |
| [glasspane](./glasspane.md) | Agent state machine, JSONL streaming, AgentRuntime taxonomy, snapshot API |
| [headroom-sidecar](./headroom-sidecar.md) | Optional tool-result compression sidecar and its Unix-socket protocol |
| [jail-confinement](./jail-confinement.md) | Persistent vs ephemeral jails, priv-mode policy, reuse of spawner confinement for MCP servers |
| [mother-hive](./mother-hive.md) | Mother MCP architecture — forced-command SSH, single-home-in-colibri, peer auth, key-on-seed |
| [naming-decisions](./naming-decisions.md) | Ledger of harness-neutral / architecture renames — shipped and in-flight |
| [layered-soul](./layered-soul.md) | How Colibri consumes the layered-soul reviewed-context repo today vs planned |
| [task-board](./task-board.md) | Capability match scoring, cron scheduling, intake drain, SQLite backing |
| [quality-gates](./quality-gates.md) | `ci-checks.sh` as the pre-merge gate; why drift reached `main` before |
| [contracts](./contracts.md) | Stable JSON schemas (run-manifest, runtime-inventory, provider-smoke), golden tests |
| [store-schema](./store-schema.md) | SQLite coordination schema and migration discipline |
| [external-mcp](./external-mcp.md) | MCP bridge for editors + external stdio MCP host; read/write/external-call gates |
| [operator-cli](./operator-cli.md) | The `colibri` CLI as a thin typed Unix-socket client over the daemon API |
| [tui](./tui.md) | Terminal dashboard client (colibri-tui) vs the colibri-glasspane state machine |
| [runtime-inventory](./runtime-inventory.md) | Host runtime inventory + watchdog status reader; additive, read-only integrations |
| [skills-catalog](./skills-catalog.md) | Read-only runtime consumer for reviewed Clawdie-AI skill artifacts |
| [vault-provision](./vault-provision.md) | Vaultwarden-driven env-file provisioning into jails after agent spawn |
| [deployment](./deployment.md) | Host installer (clawdie): ZFS layout, rc.d/systemd service, dry-run safety |

27
docs/INTEGRATION-LAYERED-SOUL.md → docs/wiki/layered-soul.md
View file

@ -1,4 +1,6 @@
# Integration: Layered Soul → Colibri
# Layered Soul integration
← [index](./index.md)
[clawdie/layered-soul](https://code.smilepowered.org/clawdie/layered-soul) is the
portable, harness-agnostic source of durable identity + reviewed context. This doc
@ -11,23 +13,23 @@ Reviewed **skills** import into Colibri's existing `skills` catalog:
scripts/import-layered-soul.sh <layered-soul-dir> <colibri.sqlite>
It reads each `skills/**/SKILL.md` (frontmatter `name` / `description`; category
It reads each skills SKILL.md file (frontmatter `name` / `description`; category
`soul`) and `INSERT OR IGNORE`s a row into the `skills` table. `references/` and
`templates/` under a skill are supporting material, not separate skills. Same
table as `clawdie-iso/scripts/import-clawdie-skills.sh`; idempotent, safe to re-run.
## What's deferred (planned, not built)
The `adapters/colibri.md` in layered-soul names a "Layered Memory Fabric" with
three stores — `system_skills`, `system_brain`, `system_ops`. As of 13.jun.2026
The the Colibri adapter in layered-soul names a "Layered Memory Fabric" with
three stores — `system_skills`, `system_brain`, `system_ops`. As of 2026-06-13
only a single flat `skills` table exists; the rest is **design only**
(`docs/COLIBRI-SKILLS-PLAN.md`), so the importer intentionally does not target it.
| Layered Soul source | Target (planned) | Status |
| ---------------------------- | ---------------- | ---------------------------------------------------------- |
| `skills/**/SKILL.md` | `system_skills` | imported into the flat `skills` table today |
| `memories/curated/**/*.md` | `system_brain` | NOT imported — no store yet (the importer reports a count) |
| converted task/job manifests | `system_ops` | NOT implemented |
| Layered Soul source | Target (planned) | Status |
| ------------------------------- | ---------------- | ---------------------------------------------------------- |
| skills SKILL.md files | `system_skills` | imported into the flat `skills` table today |
| memories/curated markdown files | `system_brain` | NOT imported — no store yet (the importer reports a count) |
| converted task/job manifests | `system_ops` | NOT implemented |
## Direction (one-way)
@ -38,6 +40,11 @@ then re-import — runtime copies are ephemeral consumers.
## Closing the gap (future work)
1. Implement `system_brain` per `COLIBRI-SKILLS-PLAN.md`, then extend the importer
to load `memories/curated/`.
to load curated memories.
2. Migrate the flat `skills` table to the planned `system_skills` schema.
3. Define and import `system_ops` task/job manifests.
## See also
- [skills-catalog](./skills-catalog.md) — Colibri's read-only runtime skill consumer
- [store-schema](./store-schema.md) — planned `system_skills` / `system_brain` tables