Skip to content

Transcripts

Open as Markdown

A run’s spans tell you where and when something happened. When you need the “what,” open the transcript: the prompt an attempt received, what the agent sent to each tool, what came back, which permissions it requested and how they were answered. SuperWitness reads that content live from AgentPod’s session events, the source of truth, one attempt at a time.

Content is evidence, never telemetry. Traces and logs stay content-free. SuperWitness never stores a transcript, never logs one and never lets one be cached: every answer carries Cache-Control: no-store.

  • Span details. In the Trace tab, click a span’s name. A pane opens on the right (the whole screen on a phone) with the span’s timing, status, attributes and log lines. For an attempt, turn, tool_call or permission span it also shows the Request and Response: a tool call’s input and output, a permission’s question, options and outcome, or the prompt and the agent’s reply. Content is read only when a span is opened.
  • The Transcript tab shows the attempt as a conversation: prompt, agent message, reasoning (folded), tool calls (a failed call has a red edge and opens by itself), permissions (question, options, outcome), state changes, errors, and any other event by its type. 200 steps a page, with Load more. A run with several attempts has a picker.
  • Links both ways. Open in transcript ↗ in the pane goes to the same step; span ↗ on a step goes back to the Trace tab with its span open. The address keeps the tab, the span, the attempt and the seq, so a link opens the exact moment.
  • Cite. A span or a step can be cited as a verdict’s evidence (a span id, or {session_id, seq_from, seq_to}), at most 100 per verdict. A verdict that cites a step links back to it.
  • When content is not there. “Transcripts aren’t available to this account” (the rest of the page still works), “Transcript unavailable, try again” (AgentPod could not be read), and “Attempt still running; refresh for more”.
  • A person signed in to the app. Only principals on SW_ALLOWED_PRINCIPALS can sign in.
  • A bearer token whose AgentPod-signed scope includes transcripts:read. Anyone else gets 403 transcripts_forbidden, over HTTP and over MCP alike. evidence:read alone is not enough.

SuperWitness itself reads AgentPod with its own service credential, whose grant must hold transcripts:read beside evidence:read. Without it, transcript reads answer 502 hub_refused and everything else works as before.

AgentPod redacts every string in a transcript before it leaves the hub; SuperWitness shows what it receives. A redacted value reads [redacted:<rule>], and each step and page says how many values were redacted. The rules are AgentPod’s: the hub’s own secrets, common credential formats (API keys, tokens, private keys, Authorization values, credentials in URLs), JSON keys whose names say they hold a secret, and any rules its operator adds. The stored events are never changed.

A field longer than 16 KiB arrives cut, as {"truncated": true, "bytes": N, "head": "…"}. Show full reads that one step whole (up to 1 MiB).

Every read that reaches AgentPod leaves two records, neither holding content:

  • at AgentPod, an audit row naming SuperWitness, with the person or agent SuperWitness read for in on_behalf_of (SuperWitness sends their prn_ id as X-On-Behalf-Of);
  • in SuperWitness’s log, one transcript.read line with principal, via (session or bearer), run, attempt, seq_from, seq_to, item, full, and on success items and redactions; a refused read logs at WARN with its code. A read SuperWitness itself refuses never reaches AgentPod, so it leaves only that WARN line.
GET /v1/runs/superpipeline/{board}/{run}/transcript?attempt=&seq_from=&seq_to=&cursor=
GET /v1/runs/superpipeline/{board}/{run}/transcript/items/{seq_from}?attempt=&seq_from=&seq_to=&full=1
  • attempt is required when the run has more than one attempt (400 attempt_required).
  • The range must lie inside the attempt (400 range_outside_attempt); without one, the whole attempt is read. A running attempt has no end yet: the read goes to the session’s current end.
  • On the item route, seq_from and seq_to are optional: the range the step was shown in, which the app forwards on Show full. They must lie inside the attempt too.
  • The answer is AgentPod’s, unchanged, plus "attempt_id": {"attempt_id", "session_id", "seq_from", "seq_to", "items": […], "next_cursor", "redactions", "truncated_fields"}. Pass next_cursor back as cursor, with the same seq_from and seq_to, for the next page.
  • Each item has a kind: prompt, message, reasoning, tool_call, permission, state, error or other, with its seqs and fields; a tool call or permission that started before the range has "partial": true.

Agents use the MCP tool get_transcript, with the same rules. Every code is on the HTTP API page. Whichever path you use, the useful result is the same: a redacted, uncached view of one attempt, with enough coordinates to cite the moment without copying its content into a verdict.