Sam & Claude 8eff3c6eff

CI / rust (pull_request) Has been cancelled

Details

CI / markdown (pull_request) Has been cancelled

Details

docs: rewrite ADR + jail-spawn design to match shipped code

Both were written as proposals; the decisions are now working code, so slim them
to plain "how it works" docs (code is the source of truth).

- ADR-agent-harness-consolidation: Proposed -> Accepted/implemented; drop the
  migration plan + gates (all shipped), fold in the pi-demotion correction, and
  drop the dangling CLAWDIE-AGENT-WIKI reference (deleted in #34). 116 -> ~55 lines.
- COLIBRI-JAILED-AGENT-SPAWN-DESIGN: proposal -> implemented; describe the shipped
  spawner (name-vs-path lifecycle, command= syntax, PrivMode mdo/helper, socket
  wiring, external-MCP reuse) instead of the original code sketch.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-13 21:56:01 +02:00

2.4 KiB

Raw Blame History

ADR: zot is the agent, Colibri is the control plane

Status: Accepted — implemented · Date: 13.jun.2026 · Owner: Sam & Claude

What we decided

We had five overlapping things that each did some of "run an agent" or "supervise agents": pi, zot, codex, a Rust clawdie mini-binary, and the clawdie-ai TypeScript app. We collapsed that to two clear roles:

zot — the agent (the front door that talks to the model). One static Go binary with built-in providers (DeepSeek + ~25 others), a Telegram bot, JSON output mode, SKILL.md skills, subprocess extensions, and its own credential store ($ZOT_HOME/auth.json).
Colibri — the control plane (the supervisor). Watches agents via glasspane, runs the task board, holds the skills catalog, tracks cost. It does not contain zot — it spawns and observes it.

"Clawdie" is the product name for zot + Colibri together, not a separate binary.

How it works now (shipped, not planned)

pi is kept as a spawnable backend, not the default. zot is the primary harness; Colibri can spawn pi as a worker (including jailed — see COLIBRI-JAILED-AGENT-SPAWN-DESIGN.md). The Node runtime stays for that. glasspane treats pi and zot identically (AgentRuntime { Pi, Zot }).
The Rust clawdie mini-binary is gone — it reimplemented Telegram + DeepSeek + credentials zot already has. Removed (crate deleted).
Herdr — unchanged; optional Linux display client, Colibri glasspane is the FreeBSD-native core.
clawdie-ai (TS) — being pruned; surviving features move to zot skills/extensions or Colibri.
Credentials live in zot's own surface ($ZOT_HOME/auth.json or the rc.d env file), not baked into a custom binary.

Why

zot already did what our own code was reimplementing (providers, Telegram, OAuth, skills, credentials), and pi/zot are interchangeable at the event level. Keeping all of it was duplicate work and dragged the Node runtime into the image. One agent + one control plane = less to maintain, smaller image, one credential model.

Trade-off we accept

zot is an upstream mirror (patriceckhart/zot, MIT). We pin a tag for the ISO and track upstream; MIT lets us fork if ever needed.

References (code is the source of truth)

crates/colibri-glasspane/src/lib.rs — AgentRuntime { Pi, Zot }
crates/colibri-daemon/src/spawner.rs — the agent/pi spawner (+ jail confinement)
docs/COLIBRI-JAILED-AGENT-SPAWN-DESIGN.md

2.4 KiB Raw Blame History