Transcripts

Every agent run rupu executes writes a transcript: an append-only JSON Lines file with one event per line, recording what was sent, what came back, every tool call and what it did. This page is the schema, for anyone who reads transcripts with their own tools.

Where transcripts live

Each agent run writes one file, named after its run id:

<transcripts-dir>/run_<ULID>.jsonl            # an active transcript
<transcripts-dir>/archive/run_<ULID>.jsonl    # after rupu transcript archive

• The file name is the run id. run_ plus a 26-character ULID, so names sort by start time. Only run_start and run_complete repeat the id inside the file.
• Every agent run writes one: a standalone rupu run, each workflow step and fan-out unit, each child started with dispatch, and each session turn. A workflow run’s own records (run.json, step_results.jsonl, events.jsonl) live in the run store and point at each step’s transcript path.
• Not every .jsonl in the directory is an agent transcript. run: step and action: step logs and per-run netflow ledgers use the same naming with their own shapes. An agent transcript’s run_start is written before the agent loop starts, so it survives every tolerated damage mode; a file with no run_start anywhere is one of the others, and rupu’s readers skip it.
• rupu transcript list reads only the run_start event of each file for metadata, which is what lets it sort thousands of transcripts cheaply; it then reads just the --limit most recent end to end (run_complete at the tail carries the status and token totals).

File format

One JSON object per line, UTF-8, newline-terminated. Every line has the same envelope:

{"type": "<event>", "data": { … }}

• type is the event name in snake_case; so are all field names.
• Optional fields are omitted, not null, when they have no value, and boolean flags that default to false are omitted when false. The one exception is run_start.customer, where null is meaningful. Treat a missing key as its default.
• Files are only ever appended to. Several writers (the agent loop, the tool_audit hook, the netflow sink) append to one file, each line whole.

Schema versions

run_start.schema says which writer produced the file. Current rupu writes 2; a transcript with no schema key is version 1.

Fields and events have been added within version 2 since it shipped: outcome, recovery, assistant_block, customer, codename, cache_write_tokens, purpose, skill_index, skill_load, launch_skills, launch_preload_skills, launch_args, message and injected. A reader should accept a missing optional key and an unknown event type.

Reading rules

• No run_complete means the run was killed or crashed (or is still going). Treat it as aborted, the status rupu transcript list gives it. Everything before the end is still valid, and often diagnostic.
• A truncated last line is a write cut off by a crash. Skip it.
• Empty lines: skip them.
• A malformed line mid-file is an error for that line only; keep reading the rest.
• An unknown type is not an error. See Unknown events.

Event order

Within one file:

run_start
notice?                     # model_limits
tool_grant                  # the tools offered, and why
notice*                     # tool_unavailable, one per named tool the run can't serve
skill_index?                # the skills bound, when the run has any
(skill_load | notice)*      # preload, continuation and operator loads; skill_not_indexed, skill_missing
seed?                       # a run seeded from earlier history
user_message?
( turn_start
    ( message* injected )*  # what the collectors delivered before this turn's model call
    usage+                  # one per provider call; a compaction call adds one with purpose
    outcome?                # a non-normal reply, ahead of the turn's content
    ( thinking_delta* thinking | assistant_delta* assistant_message | assistant_block )*
    ( tool_call  tool_result  ( skill_load notice* )?  file_edit?  command_run?  ( message | notice )?  tool_audit )*
  turn_end
  recovery*
  ( skill_load | notice )*  compaction? )*
net_flow*                   # interleaved anywhere, as connections close
run_complete

Reasoning, text, tool calls and other blocks appear in the order the model produced them. An outcome follows the turn’s usage and precedes its content; its recovery events follow it, usually after turn_end. A notice can appear wherever the runtime intervened; a hop to a fallback model writes a model_limits notice just before its fell_back recovery, and a note sent back to the model is a user_message. A successful skills.load writes its skill_load right after the call’s tool_result, then any skill_changed or skill_tools_missing notice. Skills put back after a compaction are skill_load lines with via: reattach, alongside any skill_changed, skill_missing or skill_reattach_truncated notice. A session’s compact pseudo-turn (the compaction a running session’s worker does on request) writes the same lines after its compaction usage; it has no compaction event.

Event reference

Fields marked opt are omitted when empty.

run_start

The first line of every agent transcript.

{"type":"run_start","data":{"run_id":"run_01JB7Q2M4X8T6V0K3N5R9C1D2E","workspace_id":"ws_01JB7PZ0A1B2C3D4E5F6G7H8J9","agent":"code-reviewer","provider":"anthropic","model":"claude-sonnet-4-6","started_at":"2026-10-07T09:14:03Z","mode":"readonly","schema":2,"codename":"amber-delta/kestrel","customer":null}}

run_complete

The last line of a run that ended. Its absence means the run never finished.

turn_start, turn_end and usage

{"type":"usage","data":{"provider":"anthropic","model":"claude-sonnet-4-6","input_tokens":18240,"output_tokens":612,"cached_tokens":16384}}
{"type":"turn_end","data":{"turn_idx":3,"tokens_in":18240,"tokens_out":612,"stop_reason":"tool_use"}}

Conversation events

Tool events

tool_audit fields:

# a write refused by readonly mode
{"type":"tool_audit","data":{"tool":"write_file","declared":false,"granted":true,"blocked":true,"restricted":false,"reason":"declared","decision":"denied:readonly"}}

# an action: step that created an issue
{"type":"action_emitted","data":{"kind":"issues.create","payload":{"title":"null pointer in parser.rs:142","body":"..."},"allowed":true,"applied":true}}

tool_grant

The tools the run offered its model, and why. Written once, right after run_start and its model_limits notice. entries is exactly the model’s tool list.

Services a tool can be missing: scm (configured connectors), launcher (dispatch / join, every child kind), findings, engagement, coverage (a concerns: block), message_bus, run_status, catalog, workflow_generator (workflows.generate), netflow.

{"type":"tool_grant","data":{"entries":[{"tool":"read_file","reasons":["declared"]},{"tool":"findings.report","reasons":["ambient:concerns"]}],"unavailable":[{"tool":"board.post","missing":["message_bus"]}]}}

skill_index and skill_load

A run’s skills leave two kinds of line. skill_index is the skills the run bound, written once, right after tool_grant and its notices, and only when the run has a skill: skills is an array with one row per bound skill.

skill_load records that a skill’s content entered the conversation, for every load, whichever path made it:

{"type":"skill_index","data":{"skills":[{"name":"pdf","layer":"global","stamp":"9f2c…","preload":false,"indexed":true,"reason":"agent"}]}}
{"type":"skill_load","data":{"name":"pdf","layer":"global","content_hash":"4b1e…","base_dir":"/home/me/.rupu/skills/pdf","via":"model"}}

message and injected

A run with a message space records what it sent and received. message is one message, sent or received: sent is written right after the messaging tool’s tool_result; received is written when a collector delivers it, right before the model call that sees it, one event per message, ahead of the injected event that carries it.

injected is context a collector put in front of the model. Every once injection is written, at the point it joined the conversation, so replay re-inserts it. An every_turn injection is written only when its content changed since the turn before, so a standing directive is one line, not one per turn.

{"type":"message","data":{"id":"msg_01J…","direction":"sent","from":"lynx#1","to":"role:recon","kind":"direct","body":"port 22 is open","via":"tool","delivery":{"resolved":["otter#1"]}}}
{"type":"injected","data":{"source":"mailbox:otter#1","kind":"message","cadence":"once","content":"from lynx#1 at 2026-10-13T…: port 22 is open","message_ids":["msg_01J…"]}}

outcome and recovery

When a reply isn’t a normal one, or the provider returns an error, rupu classifies it and records what it did about it. The classes and the recovery ladder are explained in Recovery & reliability.

outcome has turn_idx and an outcome object (an OutcomeRecord; the same shape as run_complete.outcome):

recovery is one recovery action taken for an outcome, written after its outcome:

{"type":"outcome","data":{"turn_idx":5,"outcome":{"id":"oc_2","class":"refusal","severity":"error","title":"refused · cyber","wire":{"provider":"anthropic","value":"refusal"}}}}
{"type":"recovery","data":{"outcome_id":"oc_2","rung":1,"action":"fell_back","provider":"anthropic","model":"claude-opus-5"}}

notice

A runtime intervention worth showing that isn’t part of the conversation: a kind and a human-readable message. Expect new kinds; render an unknown one by its message.

{"type":"notice","data":{"kind":"provider_retry","message":"overloaded; retrying in 2s (attempt 1/3)"}}

net_flow

One outbound network connection the run made: {"flow": <FlowRecord>}, with the host, port, scheme, method and query-stripped path, status and outcome, bytes, timing, and a fidelity that says how much of it was observed. Written as flows are recorded, so these lines can appear anywhere in the file. The record is described on the Netflow page.

gate_requested

Defined (gate_id, prompt, opt decision — approved or rejected —, opt decided_by) but not written by current rupu: workflow approval gates are recorded on the workflow run (run.json, events.jsonl), not in agent transcripts. Readers still parse and render it so older or hand-made files display.

Unknown events

A line whose type a reader doesn’t know is not corruption. rupu reads it as an unknown event that keeps the raw type and data, and writes it back unchanged, so a transcript from a newer rupu survives being read and copied by an older one. rupu itself never writes an unknown event. rupu transcript show prints it as unrecognized event · <type> and the control plane shows an “unrecognized event” block. Your own reader should do the same: skip or pass through, never fail.

What is corruption: a line that isn’t a JSON object, has no type, or has a type that isn’t a string.

Working with transcripts

For your own tooling, the global --format jsonl on show prints the parsed events one per line in the schema above, and --format json wraps them in one transcript_show envelope. Or read the file directly:

# every bash command a run executed, with its exit code
jq -c 'select(.type=="command_run") | [.data.exit_code, (.data.argv|join(" "))]' \
  .rupu/transcripts/run_01JB7Q2M4X8T6V0K3N5R9C1D2E.jsonl

# total spend per model across a run, cache reads included
jq -s 'map(select(.type=="usage").data) | group_by(.model)
       | map({model: .[0].model, input: (map(.input_tokens)|add), output: (map(.output_tokens)|add)})' \
  .rupu/transcripts/run_01JB7Q2M4X8T6V0K3N5R9C1D2E.jsonl

# tool calls that were denied or not granted, with the decision
jq -c 'select(.type=="tool_audit" and .data.blocked) | [.data.tool, .data.decision]' .rupu/transcripts/*.jsonl

Replay

A version 2 transcript is enough to rebuild the exact conversation the provider saw, and rupu does exactly that when it continues a run: rupu run --continue <run-id>, rupu workflow resume continuing an interrupted step, and a session’s next turn. The rules, if you want to rebuild one yourself:

• Start from the seed, if any. A source_transcript seed means “rebuild that transcript first”; its sha256 must match what was rebuilt.
• Add the user_message. Per turn, fold thinking (its raw block), assistant_message, tool_call and assistant_block events, in file order, into one assistant message, skipping abandoned blocks; the turn’s tool_results become the next user message.
• Drop a turn with no turn_end (it was in flight) and a turn whose turn_end is discarded. A recovery with merge_into_previous joins the next turn’s reply onto the previous assistant message.
• An injected event with cadence: once adds its content, framed as the runner framed it, as a user message at its position. An every_turn one was sent with that turn’s request only, so it adds nothing.
• A compaction replaces everything so far with its messages.

A version 1 transcript rebuilds without reasoning blocks, since it never kept the provider’s payload. Deltas, usage, notice, outcome, tool_grant, tool_audit, skill_index, skill_load, message, net_flow and unknown events don’t affect the conversation. The skills a run loaded are folded from its skill_load events separately, so a continued run knows what to re-attach.