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
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.
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
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 };// 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
type TurnPart =
| TextPart
| CitationPart
| FilePart
| ThinkingPart
| ActionPart
| CompactionPart;Every part has id, type, optional annotations, and optional timing.
| Part | Additional fields |
|---|---|
TextPart | text: string, citations?: Citation[], providerMetadata? |
CitationPart | citations: Citation[], providerMetadata? |
FilePart | file: FileInfo |
ThinkingPart | summary?, raw?, continuity?, providerMetadata? |
CompactionPart | trigger: "manual" | "beforeTurn" | "afterTurn", status: "pending" | "running" | "complete" | "cancelled" | "error", summary?, progress?, error? |
ThinkingPart
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
type ActionPart = ToolAction | SubagentAction | ProviderToolAction;All share status: "pending" | "running" | "complete" | "cancelled" | "error" and discriminate on kind.
kind | detail |
|---|---|
"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 |
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.
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
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
| Event | Fields |
|---|---|
operation:start | id, kind ("send" | "compaction") |
after:start | id |
after:end | id |
operation:end | id, outcome ({ type: "complete" } | { type: "cancelled", reason? } | { type: "error", error: { message } }) |
agent:idle | — |
Pending lifecycle
| Event | Fields |
|---|---|
pending:queued | turn — the preview turn (status: "pending", the id the real turn will carry) |
pending:dropped | id, reason: PendingDropReason — the operation ended before opening its turn |
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
| Event | Fields |
|---|---|
turn:user | turn — the complete user turn |
turn:start | turnId, timing? |
turn:end | turnId, 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
| Event | Fields |
|---|---|
part:start | turnId, part — the whole part object |
text:delta | turnId, partId, delta |
text:citation | turnId, partId, citation |
thinking:raw-delta | turnId, partId, delta |
thinking:summary-delta | turnId, partId, delta |
thinking:update | turnId, partId, continuity?, providerMetadata? |
part:end | turnId, partId, timing? |
Openings carry the full part; deltas carry only ids and the delta.
Actions
| Event | Fields |
|---|---|
action:args-delta | turnId, partId, delta, accumulated |
action:running | turnId, partId, parameters? — never fires for deferred calls |
action:waiting | turnId, partId, callId, name, input — the validated deferred call, handed to onToolCall |
action:input | turnId, partId, input — what the provider tool was asked to do (added in 0.33.0) |
action:progress | turnId, partId, chunk |
action:complete | turnId, partId, result, timing? |
action:cancelled | turnId, partId, timing? — the call never ran or was interrupted; status: "cancelled", no result |
action:error | turnId, partId, error, timing? |
action:child-event | turnId, partId, event — a nested TurnEvent |
Compaction
| Event | Fields |
|---|---|
compaction:update | turnId, partId, update: { summary?; progress? } |
compaction:complete | turnId, partId, summary?, timing? |
compaction:cancelled | turnId, partId, timing? — stopped by a cancel; status: "cancelled", no error |
compaction:error | turnId, partId, error, timing? — the compactor failed |
The part itself arrives through part:start with status: "running". compaction:complete sets progress: 1.
Annotations
| Event | Fields |
|---|---|
annotation:start | target, annotation |
annotation:update | target, annotation |
annotation:end | target, annotation |
type AnnotationTarget =
| { type: "turn"; turnId: string }
| { type: "part"; turnId: string; partId: string };TurnEventBuilder
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
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.