Skip to content
AIOC Docs

Run Records

RunRecord is the canonical audit artifact produced by aioc when run(..., { record }) is configured.

Why It Exists

Section titled “Why It Exists”

It supports:

  • post-incident review
  • reproducibility checks after prompt or policy changes
  • structured comparison across runs
  • replay-oriented regression analysis

Main Captured Signals

Section titled “Main Captured Signals”
  • items
  • inputItemCount
  • promptSnapshots
  • requestFingerprints
  • policyDecisions
  • initialAgentName, agentName, and executionRecordingStatus
  • guardrailDecisions
  • metadata

Input Scope

Section titled “Input Scope”

items contains the complete normalized run trajectory: the input that was passed to run(...) plus items produced while the run executes.

inputItemCount marks where the original normalized input ends inside items. This lets replay and inspection tools distinguish:

  • prior conversation history and the current user message that started the run
  • tool calls, tool outputs, and assistant messages emitted by the recorded run

For older records that do not include inputItemCount, replay and inspection utilities may infer the boundary from the first request fingerprint messageCount. If neither value is available, they must fall back to the recorded question and the replay is not history-faithful.

Agent Execution

Section titled “Agent Execution”

initialAgentName identifies the starting agent; agentName identifies the final active agent, even if the run fails before that agent calls the model.

For handoff policy decisions, handoffApplied distinguishes authorization from the actual transition:

  • true: the runtime changed the active agent
  • false: the handoff was not applied
  • absent: application evidence is unavailable, not a negative result

This field is populated by runtime, not by HandoffPolicy. Tool decisions do not use it.

executionRecordingStatus is complete when execution evidence is complete, or partial after a diagnostic capture failure. It is independent of status: a failed run can have complete evidence. Partial records retain confirmed transitions, but missing flags must not be interpreted as false. Legacy records can omit all these optional fields.

To reconstruct visits, start with initialAgentName, then follow handoff decisions with handoffApplied === true in recorded order. Do not deduplicate agent names: returning to an agent or handing off to itself starts a new visit. An activated agent may have no request if the run fails before it can make one.

With complete evidence and intact ordered items, each request’s messageCount starts its output interval; the next request’s messageCount ends it, or items.length for the last request. Join policy decisions by turn. Tools and the selected handoff belong to that request’s agent, while the initial history does not create visits in the current run. Removing or reordering items in storage invalidates these boundaries.

Context Snapshot

Section titled “Context Snapshot”

contextSnapshot captures the initial context passed to run(...). It is not the final mutable application state after tools execute.

Use contextRedactor before durable persistence, and persist final app-owned state through your own state store when needed.

Utilities

Section titled “Utilities”

aioc also exposes utilities that operate on run records:

  • extractToolCalls(...)
  • compareRunRecords(...)
  • replayFromRunRecord(...)

These are intended to reduce application boilerplate for analysis and non-regression workflows.