Skip to content

Transcript & turn events ​

Conceptual guide: Turns & Transcripts.

Everything on this page is also exported from @fifthrevision/axle/ui — the types, and Transcript itself — which doesn't pull in the provider SDKs. Use that import in UI code.

Transcript ​

typescript
class Transcript<TAnnotation extends Annotation = Annotation, THostEvent extends UnknownEvent = UnknownEvent> {
  constructor(turns?: readonly Turn<TAnnotation>[], pending?: readonly Turn<TAnnotation>[]);
  get turns(): readonly Turn<TAnnotation>[];
  get pending(): readonly Turn<TAnnotation>[];
  getTurn(turnId: string): Turn<TAnnotation> | undefined;
  apply(event: TranscriptInput<TAnnotation, THostEvent>): TranscriptApplyResult<TAnnotation, THostEvent>;
}

The constructor shallow-copies the arrays. turns is readonly; all structural change goes through apply(). The second constructor argument seeds pending to mirror a live transcript for a client that receives the server's turns, pending, and stream position in one read — it discards any entry whose id is already in turns. This changes nothing about what is saved: persist turns only.

typescript
type TranscriptApplyResult<TAnnotation extends Annotation, THostEvent extends UnknownEvent> =
  | { handled: true; event: TurnEvent<TAnnotation> }
  | { handled: false; event: THostEvent };

UnknownEvent and TimingInfo are exported from @fifthrevision/axle/ui only, not from the package root.

Unrecognized event types pass through with handled: false, so a single dispatcher can carry both Axle events and your own.

Turn ​

typescript
interface Turn<TAnnotation extends Annotation = Annotation> {
  id: string;
  owner: "user" | "agent";
  parts: TurnPart<TAnnotation>[];
  status: TurnStatus;
  annotations?: TAnnotation[];
  metadata?: Record<string, unknown>;
  threadId?: string; // on a user turn sent inline by a continuation — the send's id, rooting the thread
  cursor?: string; // where this turn closed on a served event stream, when folded from events carrying one
  timing?: TimingInfo;
  usage?: Stats;
  failure?: TurnFailure;
  error?: TurnError;
  cancelReason?: TimeoutReason;
  reason?: "stop" | "length";
}

type TurnStatus = "pending" | "streaming" | "complete" | "cancelled" | "error";
interface TimingInfo { start: string; end?: string } // ISO timestamps

type TurnFailure =
  | { kind: "api"; type: string; message: string; status?: number }
  | { kind: "incomplete"; type: string; message: string }
  | { kind: "refusal"; message: string; text?: string; category?: string }
  | { kind: "parse"; message: string };
typescript
// A thrown error that ended the turn `error`, instead of a failure.
interface TurnError {
  message: string;
  code?: AxleErrorCode; // only when Axle threw the error
}

// Why a `cancelled` turn was cancelled. Present only when `turnTimeoutMs`
// did it (`{ type: "timeout", limitMs }`); absent on a caller cancel.
type TimeoutReason = { type: "timeout"; limitMs: number };

A pending turn is a preview of a turn the Agent accepted but hasn't opened — the user turn a queued send() will commit, or an agent turn with one pending compaction part for a queued manual compaction. It carries the id the real turn will have, and leaves pending when that turn opens or when the operation is dropped. See Pending lifecycle.

TurnPart ​

typescript
type TurnPart =
  | TextPart
  | CitationPart
  | FilePart
  | ThinkingPart
  | ActionPart
  | CompactionPart;

Every part has id, type, optional annotations, and optional timing.

PartAdditional fields
TextParttext: string, citations?: Citation[], providerMetadata?
CitationPartcitations: Citation[], providerMetadata?
FilePartfile: FileInfo
ThinkingPartsummary?, raw?, continuity?, providerMetadata?
CompactionParttrigger: "manual" | "beforeTurn" | "afterTurn", status: "pending" | "running" | "complete" | "cancelled" | "error", summary?, progress?, error?

ThinkingPart ​

typescript
interface ThinkingPart {
  id: string;
  type: "thinking";
  summary?: string; // the provider's condensed account of its reasoning
  raw?: string; // the chain of thought itself; open-weight models only
  continuity?: ThinkingContinuity;
  providerMetadata?: Record<string, unknown>;
}

Each content field is named for what the provider handed back; neither present is the withheld state. Render summary ?? raw. A field appears only once a delta wrote it, so never test for "". (text / redacted on the turn part were removed in 0.32.0 — redacted now lives only on the message layer; see Messages & parts and Upgrading.)

ActionPart ​

typescript
type ActionPart = ToolAction | SubagentAction | ProviderToolAction;

All share status: "pending" | "running" | "complete" | "cancelled" | "error" and discriminate on kind.

kinddetail
"tool"{ name, parameters, pendingArgs?, result? }
"agent"{ name, config?, children: Turn[], result? }
"provider-tool"{ name, input?, result? }
"deferred"{ name, callId, input, pendingArgs?, result? } — a call answered through onToolCall; never running
typescript
type ActionResult =
  | { type: "in-progress"; content: string }
  | { type: "success"; content?: string | ConsoleOutput | ToolResultPart[] }
  | { type: "error"; error: { type: string; message: string } };

interface ConsoleOutput {
  stdout: string;
  stderr?: string;
  exitCode?: number;
}

ConsoleOutput (added in 0.33.0) arrives only from provider code execution that separates its streams (Anthropic today); OpenAI and Gemini report one stream, so their output arrives as a string. A renderer that narrows content with typeof content === "string" and treats the rest as parts must add the object case. Local tools still return strings or parts.

pendingArgs holds accumulated argument JSON before it can be parsed into parameters. Render it during streaming so there's something on screen.

typescript
interface DeferredAction<TAnnotation extends Annotation = Annotation> {
  id: string;
  type: "action";
  kind: "deferred";
  status: "pending" | "waiting" | "complete" | "cancelled" | "error";
  detail: {
    name: string;
    callId: string; // the tool call id — what the handler's DeferredCall carries as id
    input: Record<string, unknown>; // the validated input once the call is waiting; empty before
    pendingArgs?: string;
    result?: ActionResult;
  };
}

A deferred call never runs, so it is never running: pending while its arguments stream, waiting from action:waiting until the answer, timeout, or cancellation settles it. isActionOf(tool, part) narrows a part to one deferred tool's action with its input typed (a pending part carries no input yet and is excluded).

SubagentAction.detail.children is a nested Turn[], so subagent rendering is recursive.

Annotations ​

typescript
interface Annotation<TData = unknown, TKind extends string = string> {
  id: string;
  kind: TKind;
  label: string;
  placement?: "before" | "after"; // defaults to "after" when accumulated
  status?: "running" | "complete" | "cancelled" | "error";
  data?: TData;
  timing?: TimingInfo;
}

Your own UI state, attached to a turn or a part and never sent to a provider. Omit status for static annotations that have no lifecycle.

TurnEvent ​

agent.on delivers AgentEvent — every TurnEvent below, plus the operation lifecycle framing it. Transcript.apply reports the lifecycle events handled and folds nothing from them, so agent.on(transcript.apply) is unchanged. Events folded from a served stream may carry a cursor beside their fields; apply records it on the turn that turn:user or turn:end closes.

Operation lifecycle ​

EventFields
operation:startid, kind ("send" | "compaction")
after:startid
after:endid
operation:endid, outcome ({ type: "complete" } | { type: "cancelled", reason? } | { type: "error", error: { message } })
agent:idle—

Pending lifecycle ​

EventFields
pending:queuedturn — the preview turn (status: "pending", the id the real turn will carry)
pending:droppedid, reason: PendingDropReason — the operation ended before opening its turn
typescript
type PendingDropReason =
  | { type: "cancelled" }
  | { type: "error"; error: { type: string; message: string } };

A queued handle cancelled (handle.cancel(), agent.clear(), an already-aborted signal) drops as cancelled; a setup failure (an onStart refusal, say) drops as error. Nothing is committed in either case. A switch over event.type with an exhaustiveness check must handle both; a renderer that reads turns alone can ignore them. apply() folds pending:queued into pending, removes the entry on pending:dropped, on the matching turn:user, and on the matching turn:start — so [...turns, ...pending] renders with one component keyed by id.

Turn lifecycle ​

EventFields
turn:userturn — the complete user turn
turn:startturnId, timing?
turn:endturnId, status, usage, failure?, error?, cancelReason?, reason?, timing?

failure is a TurnFailure (the provider's answer that ended the turn ok: false, without usage/raw/cause); reason is "stop" or "length" when the turn ended with a final answer. error is a TurnError (a thrown error the send rejected with, not a provider answer — a turn carries failure or error, never both); cancelReason is present only when turnTimeoutMs cancelled the turn. The old error event is gone — match turn:end's failure instead.

Part streaming ​

EventFields
part:startturnId, part — the whole part object
text:deltaturnId, partId, delta
text:citationturnId, partId, citation
thinking:raw-deltaturnId, partId, delta
thinking:summary-deltaturnId, partId, delta
thinking:updateturnId, partId, continuity?, providerMetadata?
part:endturnId, partId, timing?

Openings carry the full part; deltas carry only ids and the delta.

Actions ​

EventFields
action:args-deltaturnId, partId, delta, accumulated
action:runningturnId, partId, parameters? — never fires for deferred calls
action:waitingturnId, partId, callId, name, input — the validated deferred call, handed to onToolCall
action:inputturnId, partId, input — what the provider tool was asked to do (added in 0.33.0)
action:progressturnId, partId, chunk
action:completeturnId, partId, result, timing?
action:cancelledturnId, partId, timing? — the call never ran or was interrupted; status: "cancelled", no result
action:errorturnId, partId, error, timing?
action:child-eventturnId, partId, event — a nested TurnEvent

Compaction ​

EventFields
compaction:updateturnId, partId, update: { summary?; progress? }
compaction:completeturnId, partId, summary?, timing?
compaction:cancelledturnId, partId, timing? — stopped by a cancel; status: "cancelled", no error
compaction:errorturnId, partId, error, timing? — the compactor failed

The part itself arrives through part:start with status: "running". compaction:complete sets progress: 1.

Annotations ​

EventFields
annotation:starttarget, annotation
annotation:updatetarget, annotation
annotation:endtarget, annotation
typescript
type AnnotationTarget =
  | { type: "turn"; turnId: string }
  | { type: "part"; turnId: string; partId: string };

TurnEventBuilder ​

typescript
import { TurnEventBuilder } from "@fifthrevision/axle";

Converts StreamEvents into TurnEvents — the same translation Agent does internally. You'd only need this if you're driving stream() directly but still want render-layer events.

renderTerminalMarkdown ​

typescript
renderTerminalMarkdown(text: string): string;

Markdown in, ANSI-styled terminal text out. Exported from @fifthrevision/axle/ui only — it's what a terminal renderer needs for a turn's text parts, and it's the same rendering SimpleWriter's markdown option applies to event messages.