colibri/docs/wiki/agent-harness.md

Agent harness: zot & Colibri

← index

Architecture

Two binaries with distinct roles:

• zot — the agent (model frontend). Go binary; executes tasks, calls providers, emits JSONL events on stdout.
• Colibri — the control plane (supervisor). Rust daemon; observes agents via glasspane, runs the task board, owns cost tracking.

Colibri observes zot; it does not embed it. The two communicate through the spawner's stdout JSONL contract and, for RPC agents, a piped stdin channel.

Runtimes

Glasspane normalizes events from all harnesses into one taxonomy via AgentRuntime { Pi, Zot, Local } — see crates/colibri-glasspane/src/lib.rs (zot_event_type() maps zot's event structure onto the standard agent lifecycle names).

Autospawn

When COLIBRI_AUTOSPAWN=YES, the daemon spawns an agent at startup so the node is immediately ready for task work. The agent binary and arguments are configurable:

• COLIBRI_AUTOSPAWN_BINARY — defaults to zot
• COLIBRI_AUTOSPAWN_ARGS — defaults to rpc for zot, --mode json for other harnesses

The spawner pipes stdin for RPC agents; the daemon sends a bootstrap prompt over an RpcSender if COLIBRI_AUTOSPAWN_RPC_PROMPT is set.

After spawn, the agent is registered in the local SQLite store with capabilities detected by probe_capabilities() (OS, ollama, llama.cpp, blender — see clawdie-system-probe --capabilities or the built-in fallback in crates/colibri-daemon/src/socket.rs). The scheduler can then route queued tasks to it.

Where it lives

• Spawn contract, rpc_stdin, RpcSender: crates/colibri-daemon/src/spawner.rs
• Autospawn, capability probe, agent registration: crates/colibri-daemon/src/socket.rs (default_agent_args, autospawn_agent_if_configured, probe_capabilities)
• Wire format: agent-events-reference
• End-to-end test, zot: crates/colibri-daemon/tests/zot_rpc_driver.rs (auto-finds zot in PATH, skips gracefully if absent)
• End-to-end test, pi: crates/colibri-daemon/tests/pi_spawn_live.rs (runs in every cargo test via sample-pi-agent.py)

See also

• naming-decisions — harness naming history
• hive-routing — capability-based task dispatch