Agent Session Events
The daemon-to-dashboard event path, idempotent ingest, and replay.
While a run executes, the daemon inside its container is the sole reporter of the agent's activity. It reports over the per-task token to the dashboard API, which stores every event in ClickHouse in arrival order and streams it back to the browser as one flat stream. The dashboard appends the user's side of the conversation (prompt replies, executed commands) into the same stream, so replay reproduces the whole exchange. Every authorized daemon report doubles as the liveness heartbeat the dispatch reaper relies on.
How to test it
| Suite | Proves |
|---|---|
pnpm vp run @firops/api#test — opencode-events.test.ts | Re-sent events never duplicate, streaming deltas compact on the default read, diffs stay out of the main stream, and reads return what the daemon wrote |
pnpm vp run @firops/api#test — opencode-provider-credentials.integration.test.ts | Ingest is gated by the per-task token, and terminal runs reject stray reports without faking liveness |
pnpm vp run @firops/elysia-opencode#test | The daemon's reporting behavior against real HTTP servers |
Frontend: pnpm vp test — the event-transducer tests | Replaying a recorded event stream folds into the expected transcript, prompts, and counters |
Manual smoke: dispatch a run and watch the console — messages stream live, prompts appear and resolve, and the diff panel follows the run.
Decisions
- One stream, not one per guarantee — a second store once carried the message history under its own ids and sequence, on the theory that history needed a stronger guarantee than live signals. It did not: the single arrival-ordered stream already survives reconnects and re-sends, and the split cost a merged cursor, a second dedup rule, and a copy of every message that no reader ever preferred.
- Ingest is idempotent — a daemon re-sending after a reconnect can never duplicate an event. A queued delivery keeps its identity across retries, so a replay writes the keys it already wrote and reads collapse them; a caller reporting directly is deduplicated by event content. Dedup is the store's job, not the reporter's.
- User interactions land in the same event stream — a prompt reply or an executed command is appended beside the daemon's events, so replaying the stream reproduces the whole conversation with no second source to merge.
- Streaming deltas are compacted on read, not on write — the store keeps the raw truth; the default read collapses keystroke-level noise for the transcript, and a caller that wants everything can ask for it.
- Diffs ride a separate stream from the transcript — full patches are heavy and wanted on demand; keeping them out of the main poll keeps the live transcript cheap.
- The browser replays a flat event array through one pure transducer — the UI derives all state from the stream using the generated Opencode SDK event types directly, with no intermediate event model to drift from upstream.
- All ClickHouse SQL lives in one storage module per table family — every query is reviewed beside the schema it depends on; routes and workers call the storage module and never carry their own SQL.
Next: Security audit log — the append-only trail of who did what across all of the above.