Run introspection

A status such as working tells you that a delegated run is alive. It does not tell you whether the agent is reading the right file, repeating itself, blocked on a tool, or already holding the answer. Run introspection combines Avenor's event stream with a bounded transcript view so hosts can show that difference without loading an entire event log into model context.

Data flow

Avenor keeps the layers separate:

1. Runtime adapters translate backend activity into the canonical event vocabulary.
2. The control protocol stamps runtime events with ts and runtime-local seq, retains a bounded replay window, and streams live notifications.
3. @dougbots/avenor-core normalizes canonical and compatibility events into a bounded run snapshot.
4. Pi and OpenCode choose how to present that snapshot.

The NDJSON file configured by on_event remains the durable source of truth. Control-socket history and host snapshots are intentionally bounded attachment and display surfaces.

Pi

Use /avenor-watch to select a tracked run or pass a run ID directly:

/avenor-watch <run-id>

The inspector shows assistant and reasoning text exposed by the backend, live and completed tools, permissions, status, and final output. It supports scrolling, cancellation, and follow-up input. Raw ANSI and terminal control characters are removed before rendering.

The model-facing avenor_inspect tool returns the same kind of bounded snapshot as JSON. Use it for transcript and tool diagnostics without consuming raw avenor_events records. When the parent only needs the sub-agent's conclusion, avenor_result waits for the run and returns its complete final output without the snapshot.

Pi returns JSON model content in content[0].text and structured details for all tools except avenor_spawn. The renderer creates themed, bounded summaries for display. It does not modify the underlying model content or the details object.

OpenCode

The OpenCode plugin uses the shared observer for live tool metadata, waiting/permission transitions, and final output. It also exposes avenor_inspect. OpenCode does not currently reproduce Pi's full-screen overlay; presentation remains host-specific.

OpenCode returns concise, bounded prose in its shared output for avenor_status, avenor_result, avenor_answer_permission, avenor_follow_up, avenor_events, avenor_inspect, and avenor_shutdown. Structured metadata stays in host/session state. MCP clients render their own results.

Fidelity boundaries

Backends expose different native detail. Avenor normalizes what is available but does not invent hidden reasoning or missing tool output. Compatibility events such as Pi's avenor.message.* and avenor.tool.* remain in the stream for existing consumers, while the shared reducer avoids showing their canonical equivalents twice.

Replay is limited to the control server's recent in-memory history. A subscriber that cannot keep up receives subscriber.lagged; consult the NDJSON log when complete history matters.

See also: Control protocol and Event stream.