🏇 Avenor

Appearance

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:

text
/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_message, avenor_peers, avenor_events, avenor_inspect, avenor_kill, and avenor_shutdown, and for avenor_workflow's controller_status action. Every other avenor_workflow action returns the control method's result object as indented JSON, since its shape differs per action. 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.