Agent Exchange Transcript

AWF records a canonical agent exchange transcript for every workflow run. It is an append-only JSONL stream that captures the full workflow lifecycle — step start/end events, user prompts, assistant replies, tool calls, tool results, and sub-workflow linkage — in a single normalized format suitable for offline replay, auditing, and reconstruction of the execution tree.

The transcript coexists with the audit trail and the streaming DisplayEvent output; none of those channels change because the transcript exists.

How It Works#

When a workflow runs, AWF appends one JSON object per line to:

storage/transcripts/<run-id>.jsonl

Each line is a complete ExchangeEvent with a strictly monotonic seq, the workflow run_id, the dot-separated path of the current step, a UTC timestamp, and a typed payload whose shape is determined by the event type.

Events are written to disk first, then broadcast to live subscribers. The disk file is the durable contract: a slow consumer never blocks a write.

Event Vocabulary#

The type field uses a closed vocabulary. Every line in the file is one of:

Readers must treat unknown event types as forward-compatible: surface them with the type intact, do not panic. See Schema → Forward Compatibility.

Content Blocks#

Assistant messages and tool payloads carry typed ContentBlock entries. The closed vocabulary is:

Every block also carries a fidelity marker:

• "router" — block synthesized by AWF’s tools.Router.CallTool seam. Authoritative for in-process tool calls.
• "agent_emitted" — block emitted directly by the agent (e.g., stdio proxy NDJSON tool_use). Provenance is the agent, not the router.

This marker lets consumers distinguish ground truth from agent-reported events without double-counting.

Per-Provider Normalization#

Outputs from Claude, Codex, Gemini, Copilot, and OpenAI HTTP are normalized into the same ContentBlock stream by a single mapping layer in internal/infrastructure/agents/. Provider quirks are absorbed there:

• Codex — embedded NUL bytes in JSONL are handled without corrupting the transcript line.
• Dangling tool_use — a tool_use without a matching tool_result (timeout, crash) is recorded as-is; the parser does not panic or drop the message.
• Mixed blocks — Claude thinking + text + tool_use in one response yields three blocks in order.

The existing per-provider DisplayEvent output is not changed; the transcript adds a sibling mapping rather than replacing the display layer.

Sub-Workflow Linkage#

When a parent run invokes call_workflow, AWF writes the child run to its own file. Linkage is bidirectional:

• The parent emits step.call_workflow.started carrying child_run_id.
• The child writes every lifecycle event with parent_run_id populated.

Each file is self-contained — one seq series per file, reconstructable in isolation. Reading both files yields a single connected execution tree.

Nesting deeper than one level produces one file per level with consistent parent linkage at every depth.

Live Fan-Out#

Consumers subscribe to the recorder to receive events as they are written. Fan-out is bounded:

• Per-subscriber channel buffer: 256 events (default).
• Back-pressure policy: drop-newest — once a subscriber’s buffer fills, new events are dropped for that subscriber until it drains.
• A drop counter is exposed via FanOut.Stats(); the recorder logs a rate-limited WARN (1/s) per subscriber when drops occur.
• The disk write is never blocked by a slow subscriber; the file remains complete and monotonic regardless.

Close() on the recorder or a subscriber is idempotent — calling it twice is safe.

File Properties#

<run-id> is the same UUID v4 used by the audit trail and the state machine — there is no separate ID infrastructure.

Querying the Transcript#

The format is JSONL, so standard tooling works:

# Pretty-print an entire run
jq '.' storage/transcripts/<run-id>.jsonl

# Extract every tool call with its result
jq 'select(.type == "tool.call" or .type == "tool.result")' storage/transcripts/<run-id>.jsonl

# List all assistant text content blocks
jq -r 'select(.type == "message.assistant") | .payload.blocks[] | select(.type == "text") | .text' \
  storage/transcripts/<run-id>.jsonl

# Show only router-fidelity tool events
jq 'select(.type == "tool.call" and .payload.fidelity == "router")' \
  storage/transcripts/<run-id>.jsonl

# Reconstruct the step path tree
jq -r 'select(.type == "step.started") | "\(.seq)\t\(.path)\t\(.payload.kind)"' \
  storage/transcripts/<run-id>.jsonl

# Follow nested sub-workflows: find every child run referenced by a parent
jq -r 'select(.type == "step.call_workflow.started") | .child_run_id' \
  storage/transcripts/<run-id>.jsonl

Coexistence Guarantees#

• audit.jsonl output is byte-identical whether the transcript recorder is wired or not.
• DisplayEvent streams remain unchanged; the transcript adds a parallel mapping, not a replacement.
• Plugins are unaffected — capture happens at AWF boundaries (router seam, agent seam), never inside plugin internals.

Security & Privacy#

• Files are written with mode 0o600 — only the owning user can read them.
• No secrets are masked by default. A message.user event includes the resolved prompt and composed system prompt verbatim; tool.call payloads include arguments verbatim. Treat transcript files like raw command logs.
• The design preserves an opt-in masking hook for future use, but no masking ships in this version.

See Also#

• Transcript Schema — Full field reference, payload shapes, and constraints
• Audit Trail — The separate paired-event audit channel that coexists with the transcript
• Distributed Tracing — OpenTelemetry spans for cross-system correlation