Glasspane — agent state supervision

What this is

Glasspane is Colibri’s agent observation layer. It watches agent subprocesses via their JSONL stdout, folds the stream into a semantic state machine (Idle → Working → Done), and exposes a snapshot API for dashboards and daemon coordination. Every spawned agent — Pi, zot, or a local sample — feeds through the same ingestor and ends up in the same taxonomy.

Decisions

Agent state as a state machine, not raw event log

Glasspane doesn’t just relay raw agent events. It ingests JSONL lines and transitions a named pane through a finite set of states:

Idle → Working → Done
         ↳ Error
         ↳ Stalled (no events within a timeout window)

The AgentState enum (Idle, Working, Done, Error, Stalled) is deliberately small. It captures what a supervisor needs to know — “is the agent working? stuck? finished?” — without encoding agent-specific semantics. Events that don’t change the state (e.g. a usage report from zot) are recorded in the pane’s metadata but don’t affect the state machine.

Why not just tail the log: raw event logs are agent-specific and change over time (zot adds new event types). The state machine is a stable contract that the daemon, TUI, and client CLI can all rely on.

→ crates/colibri-glasspane/src/lib.rs

JSONL streaming (one line = one event)

Agents emit structured events as newline-delimited JSON on stdout. Glasspane reads line-by-line with BufReader, deserializes each line, and feeds it into the PiJsonlIngestor (the name is legacy — it handles zot events too).

The reader runs in a single background task per pane (pane_reader_loop). It never blocks the daemon’s main loop — the ingestor is a synchronous fold that updates the pane’s in-memory state, and the snapshot API reads from Arc<RwLock<...>> with no contention on the reader hot path.

Malformed lines are skipped with a counter increment, not an error — dropouts in an agent’s JSONL shouldn’t crash the observer.

Why JSONL, not a socket or gRPC: the agent is a subprocess, not a service. stdout is the universal interface — every language, every harness, zero setup. JSONL is trivial to write from bash, Go, Python, Rust. A structured wire format would add a dep and a handshake to every agent.

→ crates/colibri-glasspane/src/lib.rs (PiJsonlIngestor, pane_reader_loop)

`AgentRuntime { Pi, Zot, Local }` — one taxonomy for two harnesses

Pi and zot emit different raw event types: Pi uses agent_start / turn_end, zot uses turn_start / done. Glasspane maps both into the same AgentState transitions via zot_event_type(). The AgentRuntime enum tags each pane with its harness so the mapping function knows which event vocabulary to parse.

The Pane struct’s session_id field uses #[serde(alias = "pi_session_id")] for backward compatibility with pre-neutrality serialized snapshots.

Why not have two separate state machines: the TUI, daemon scheduler, and client CLI all need to ask “what state is this agent in?” — they don’t care whether it’s zot or Pi. One taxonomy, one API. The mapping is a ~50-line function, not a subsystem.

→ crates/colibri-glasspane/src/lib.rs (zot_event_type, AgentRuntime)

Snapshot API (read-heavy, not write-heavy)

Glasspane exposes a snapshot object (the full set of panes with their current state, session ID, timestamp, and metadata) through Arc<RwLock<...>>. The daemon serves this over its Unix socket to client readers. Writes happen once per event; reads are frequent (TUI polls, CLI status checks).

Why RwLock, not channels: the write path is low-frequency (agent JSONL at human-reading speed), and the read path is lock-free in the common case. A channel-based design would add buffering and delivery semantics for a problem that’s fundamentally about current state, not event delivery.

→ crates/colibri-glasspane/src/lib.rs (Supervisor, snapshot)