Transcript Schema

Reference for the agent exchange transcript JSONL format produced at storage/transcripts/<run-id>.jsonl. Each line is a complete ExchangeEvent. See the Agent Exchange Transcript guide for usage.

ExchangeEvent Envelope#

All lines share the same envelope. Event-specific data lives in payload.

{
  "seq": 1,
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "run.started",
  "path": "",
  "iteration": 0,
  "timestamp": "2026-06-08T08:14:42.123Z",
  "payload": null
}

Envelope Fields#

Event Types#

The vocabulary is closed. The complete set of valid type values is exactly:

Writers never emit values outside this set. Readers must handle unknown type values forward-compatibly — see Forward Compatibility.

Payload Shapes#

StepPayload#

Carried by step.* and run.* events.

{
  "type": "step.started",
  "payload": {
    "name": "analyze",
    "kind": "agent"
  }
}

MessagePayload#

Carried by message.user and message.assistant.

{
  "type": "message.user",
  "payload": {
    "role": "user",
    "blocks": [
      {"type": "text", "fidelity": "router", "text": "Review main.go for bugs."}
    ]
  }
}

ToolPayload#

Carried by tool.call and tool.result.

{
  "type": "tool.call",
  "payload": {
    "name": "Read",
    "call_id": "tool_01H...",
    "input": {"path": "main.go"},
    "output": null,
    "fidelity": "router"
  }
}

ContentBlock#

Building block inside MessagePayload.blocks. The vocabulary is closed; field population depends on type. Unused fields are omitted via omitempty.

Every block carries:

Block-specific fields (only populated for the relevant type; others omitted via omitempty):

{"type": "text", "fidelity": "agent_emitted", "text": "Found 2 issues."}
{"type": "thinking", "fidelity": "agent_emitted", "thinking": "First I should..."}
{"type": "tool_use", "fidelity": "agent_emitted", "tool_name": "Read", "tool_id": "toolu_01", "tool_input": {"path": "main.go"}}
{"type": "tool_result", "fidelity": "router", "tool_id": "toolu_01", "tool_content": "package main\n..."}
{"type": "command", "fidelity": "router", "command": "go test ./..."}

Fidelity#

The fidelity field on every ContentBlock and ToolPayload distinguishes two provenances:

Consumers can use this marker to avoid double-counting tool calls reported on multiple channels.

Payload Dispatch#

The decoder selects the concrete payload type from the envelope type combined with a tolerant probe of the JSON shape:

1. If the raw payload is a JSON array, decode into []ContentBlock.
2. If the raw payload is an object containing "role", decode into *MessagePayload.
3. Else if it contains "call_id", decode into *ToolPayload.
4. Else if it contains "kind", decode into *StepPayload.
5. Otherwise, decode into a generic any (forward-compatibility fallback).

A null or missing payload yields payload: nil — valid for run.* lifecycle events.

File Properties#

Concurrency#

• seq is allocated from a single atomic.AddUint64 inside the recorder before the write lock is taken.
• All writes are serialized; no torn lines even when a payload exceeds PIPE_BUF.
• Multiple goroutines emitting concurrently produce a strictly monotonic seq series with no gaps.

Atomicity#

• O_APPEND guarantees that each successful write() lands at the file end.
• Process kill mid-write cannot tear a line written under PIPE_BUF; the mutex covers the larger case.

Sub-Workflow Linkage#

A call_workflow step produces a new file for the child run. Linkage is bidirectional:

• Parent file — step.call_workflow.started envelope sets child_run_id to the new run’s UUID.
• Child file — every envelope sets parent_run_id to the invoking run’s UUID.

Each file’s seq series is independent and starts at 1. Reconstruction walks child_run_id links from the parent to locate every child file and assembles a connected tree.

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

Forward Compatibility#

The reader is tolerant; the writer is strict:

• Writers only emit values from the closed EventType and BlockType vocabularies.
• Readers that encounter an unknown EventType surface it through errors.Is(err, transcript.ErrUnknownEventType) so callers may treat it as a warning rather than a parse failure. Likewise transcript.ErrUnknownBlockType for unknown BlockType values.
• Adding new envelope fields is safe — older readers ignore unknown fields per the JSON standard.
• Adding new event or block types requires every consumer to handle the unknown-type path explicitly. Removing or renaming values requires a coordinated schema bump.

Coexistence#

The transcript is a pure addition:

• audit.jsonl output is byte-identical whether the transcript recorder is wired or not.
• DisplayEvent streams (used by streaming display and TUI) remain unchanged.
• Plugin behavior is unaffected — instrumentation happens at AWF boundaries, not inside plugins.

Live Fan-Out#

Subscribers connect via the Recorder.Subscribe() port and receive every event written to disk, in order.

Limitations#

• No default secret masking. Prompts, system prompts, and tool inputs are recorded verbatim. The design preserves an opt-in masking hook for future use, but no masking ships in this version.
• awf mcp-serve subprocess capture is not yet instrumented. The fidelity:"agent_emitted" marker documents this gap and enables a future transition without changing the wire format.
• Token-by-token streaming deltas are not captured. The stream block type exists in the vocabulary but is reserved for future use.

Querying Examples#

Decode every event#

jq '.' storage/transcripts/<run-id>.jsonl

Pair tool calls with their results#

jq -s '
  [.[] | select(.type == "tool.call" or .type == "tool.result")]
  | group_by(.payload.call_id)
  | map({
      call_id: .[0].payload.call_id,
      name: .[0].payload.name,
      input: (map(select(.type == "tool.call"))[0].payload.input),
      output: (map(select(.type == "tool.result"))[0].payload.output)
    })
' storage/transcripts/<run-id>.jsonl

Extract every assistant text response#

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

Verify monotonic seq#

jq -s '[.[].seq] | . == (sort)' storage/transcripts/<run-id>.jsonl
# true

Reconstruct a step tree#

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

Walk parent → child runs#

# List every child run spawned by this parent
jq -r 'select(.type == "step.call_workflow.started") | .child_run_id' \
  storage/transcripts/<parent-run-id>.jsonl

Distinguish router-fidelity vs agent-emitted tool calls#

jq -s '
  [.[] | select(.type == "tool.call")]
  | group_by(.payload.fidelity)
  | map({fidelity: .[0].payload.fidelity, count: length})
' storage/transcripts/<run-id>.jsonl

See Also#

• Agent Exchange Transcript Guide — Conceptual overview, file location, fan-out, and security notes
• Audit Trail Schema — The separate paired-event audit format that coexists with the transcript
• Package documentation: run go doc github.com/awf-project/cli/internal/domain/transcript for the in-tree reference