The Open Framework for Building Agents
import type {
TraceAction,
TraceActionError,
TraceActionKind,
TraceStep,
TraceTurn,
TranscriptStreamEvent,
} from "./types";
type MutableTraceAction = {
callId: string;
durationMs?: number;
endTime?: string;
error?: TraceActionError;
input?: unknown;
kind: TraceActionKind;
name: string;
output?: unknown;
startTime?: string;
status: TraceAction["status"];
};
type MutableTraceStep = {
actions: MutableTraceAction[];
actionCount: number;
actionsByCallId: Map<string, MutableTraceAction>;
durationMs?: number;
endTime?: string;
errorMessage?: string;
events: TranscriptStreamEvent[];
finishReason?: string;
reasoningText?: string;
responseText?: string;
startTime?: string;
status: TraceStep["status"];
stepIndex: number;
subagentCount: number;
usage?: TraceStep["usage"];
};
type MutableTraceTurn = {
assistantMessage?: string;
durationMs?: number;
endTime?: string;
events: TranscriptStreamEvent[];
sequence?: number;
startTime?: string;
status: TraceTurn["status"];
steps: MutableTraceStep[];
stepsByIndex: Map<number, MutableTraceStep>;
subagentCount: number;
turnId: string;
userMessage?: string;
};
function isRecord(value: unknown): value is Record<string, unknown> {
return value !== null && typeof value === "object";
}
function readString(value: unknown): string | undefined {
return typeof value === "string" && value.length > 0 ? value : undefined;
}
function readNumber(value: unknown): number | undefined {
return typeof value === "number" ? value : undefined;
}
function readEventTimestamp(event: TranscriptStreamEvent): string | undefined {
return readString(event.meta?.at);
}
function getEventTurnId(event: TranscriptStreamEvent): string | undefined {
if (!("data" in event) || !isRecord(event.data)) {
return undefined;
}
return readString((event.data as Record<string, unknown>).turnId);
}
function getEventSequence(event: TranscriptStreamEvent): number | undefined {
if (!("data" in event) || !isRecord(event.data)) {
return undefined;
}
return readNumber((event.data as Record<string, unknown>).sequence);
}
function getEventStepIndex(event: TranscriptStreamEvent): number | undefined {
if (!("data" in event) || !isRecord(event.data)) {
return undefined;
}
return readNumber((event.data as Record<string, unknown>).stepIndex);
}
function ensureTurn(
orderedTurns: MutableTraceTurn[],
turnsById: Map<string, MutableTraceTurn>,
turnId: string,
): MutableTraceTurn {
const existing = turnsById.get(turnId);
if (existing !== undefined) {
return existing;
}
const nextTurn: MutableTraceTurn = {
events: [],
status: "running",
steps: [],
stepsByIndex: new Map(),
subagentCount: 0,
turnId,
};
turnsById.set(turnId, nextTurn);
orderedTurns.push(nextTurn);
return nextTurn;
}
function ensureStep(turn: MutableTraceTurn, stepIndex: number): MutableTraceStep {
const existing = turn.stepsByIndex.get(stepIndex);
if (existing !== undefined) {
return existing;
}
const nextStep: MutableTraceStep = {
actions: [],
actionCount: 0,
actionsByCallId: new Map(),
events: [],
status: "running",
stepIndex,
subagentCount: 0,
};
turn.stepsByIndex.set(stepIndex, nextStep);
turn.steps.push(nextStep);
return nextStep;
}
function getMostRecentStep(turn: MutableTraceTurn): MutableTraceStep | undefined {
return turn.steps[turn.steps.length - 1];
}
function createTraceAction(input: {
readonly callId: string;
readonly input?: unknown;
readonly kind: TraceActionKind;
readonly name: string;
readonly status?: TraceAction["status"];
}): MutableTraceAction {
return {
callId: input.callId,
input: input.input,
kind: input.kind,
name: input.name,
status: input.status ?? "requested",
};
}
function ensureAction(step: MutableTraceStep, action: MutableTraceAction): MutableTraceAction {
const existing = step.actionsByCallId.get(action.callId);
if (existing !== undefined) {
return existing;
}
step.actionsByCallId.set(action.callId, action);
step.actions.push(action);
step.actionCount = step.actions.length;
return action;
}
function getTraceActionKindFromRequest(action: Record<string, unknown>): TraceActionKind {
const kind = readString(action.kind);
switch (kind) {
case "load-skill":
case "subagent-call":
case "tool-call":
return kind;
default:
return "unknown";
}
}
function getTraceActionKindFromResult(result: Record<string, unknown>): TraceActionKind {
const kind = readString(result.kind);
switch (kind) {
case "load-skill-result":
return "load-skill";
case "subagent-result":
return "subagent-call";
case "tool-result":
return "tool-call";
default:
return "unknown";
}
}
function getTraceActionNameFromRequest(action: Record<string, unknown>): string | undefined {
const kind = getTraceActionKindFromRequest(action);
switch (kind) {
case "load-skill":
return readString(action.name);
case "subagent-call":
return readString(action.subagentName) ?? readString(action.name);
case "tool-call":
return readString(action.toolName);
case "unknown":
return (
readString(action.toolName) ?? readString(action.subagentName) ?? readString(action.name)
);
}
}
function getTraceActionNameFromResult(result: Record<string, unknown>): string | undefined {
const kind = getTraceActionKindFromResult(result);
switch (kind) {
case "load-skill":
return readString(result.name);
case "subagent-call":
return readString(result.subagentName);
case "tool-call":
return readString(result.toolName);
case "unknown":
return (
readString(result.toolName) ?? readString(result.subagentName) ?? readString(result.name)
);
}
}
function readActionResultError(value: unknown): TraceActionError | undefined {
if (!isRecord(value)) {
return undefined;
}
const code = readString(value.code);
const message = readString(value.message);
if (code === undefined || message === undefined) {
return undefined;
}
return {
code,
message,
};
}
function getTraceActionStatusFromResult(eventData: Record<string, unknown>): TraceAction["status"] {
const normalizedStatus = readString(eventData.status);
if (normalizedStatus === "completed" || normalizedStatus === "failed") {
return normalizedStatus;
}
return readActionResultError(eventData.error) !== undefined ? "failed" : "completed";
}
function getTraceActionErrorFromResult(
eventData: Record<string, unknown>,
): TraceActionError | undefined {
return readActionResultError(eventData.error);
}
function abortOpenTraceWork(input: {
readonly endedAt?: string;
readonly message?: string;
readonly turn: MutableTraceTurn;
}): void {
for (const step of input.turn.steps) {
if (step.status === "running") {
if (input.endedAt !== undefined && step.endTime === undefined) {
step.endTime = input.endedAt;
}
if (input.message !== undefined && step.errorMessage === undefined) {
step.errorMessage = input.message;
}
step.status = "aborted";
}
for (const action of step.actions) {
if (action.status !== "requested" && action.status !== "running") {
continue;
}
if (input.endedAt !== undefined && action.endTime === undefined) {
action.endTime = input.endedAt;
}
action.status = "aborted";
}
}
}
function applyDuration(input: {
readonly endTime?: string;
readonly setDuration: (durationMs: number | undefined) => void;
readonly startTime?: string;
}): void {
if (input.startTime === undefined || input.endTime === undefined) {
input.setDuration(undefined);
return;
}
const startMs = Date.parse(input.startTime);
const endMs = Date.parse(input.endTime);
if (Number.isNaN(startMs) || Number.isNaN(endMs) || endMs < startMs) {
input.setDuration(undefined);
return;
}
input.setDuration(endMs - startMs);
}
function toReadonlyTurn(turn: MutableTraceTurn): TraceTurn {
return {
assistantMessage: turn.assistantMessage,
durationMs: turn.durationMs,
endTime: turn.endTime,
events: turn.events,
sequence: turn.sequence,
startTime: turn.startTime,
status: turn.status,
steps: turn.steps.map((step) => ({
actions: step.actions.map((action) => ({
callId: action.callId,
durationMs: action.durationMs,
endTime: action.endTime,
error: action.error,
input: action.input,
kind: action.kind,
name: action.name,
output: action.output,
startTime: action.startTime,
status: action.status,
})),
actionCount: step.actionCount,
durationMs: step.durationMs,
endTime: step.endTime,
errorMessage: step.errorMessage,
events: step.events,
finishReason: step.finishReason,
reasoningText: step.reasoningText,
responseText: step.responseText,
startTime: step.startTime,
status: step.status,
stepIndex: step.stepIndex,
subagentCount: step.subagentCount,
usage: step.usage,
})),
subagentCount: turn.subagentCount,
turnId: turn.turnId,
userMessage: turn.userMessage,
};
}
/**
* Reconstructs the shared turn model from the persisted session transcript.
*
* The web UI renders both chat and debugger surfaces from this one transcript-
* first view, deriving durations from event timestamps when available.
*/
export function buildTraceTurnsFromTranscript(
events: readonly TranscriptStreamEvent[],
): readonly TraceTurn[] {
const orderedTurns: MutableTraceTurn[] = [];
const turnsById = new Map<string, MutableTraceTurn>();
let lastTurnId: string | undefined;
for (const event of events) {
let turnId = getEventTurnId(event);
if (
turnId === undefined &&
lastTurnId !== undefined &&
(event.type === "session.completed" ||
event.type === "session.failed" ||
event.type === "session.waiting")
) {
turnId = lastTurnId;
}
if (turnId === undefined) {
continue;
}
const turn = ensureTurn(orderedTurns, turnsById, turnId);
turn.events.push(event);
lastTurnId = turnId;
const sequence = getEventSequence(event);
if (sequence !== undefined) {
turn.sequence = sequence;
}
const eventTimestamp = readEventTimestamp(event);
const eventStepIndex = getEventStepIndex(event);
const step =
eventStepIndex !== undefined ? ensureStep(turn, eventStepIndex) : getMostRecentStep(turn);
if (step !== undefined && eventStepIndex !== undefined) {
step.events.push(event);
} else if (step !== undefined && event.type === "agent.started") {
step.events.push(event);
}
if (event.type === "turn.started") {
if (eventTimestamp !== undefined) {
turn.startTime = eventTimestamp;
}
continue;
}
if (event.type === "message.received" && isRecord(event.data)) {
turn.userMessage = readString(event.data.message);
continue;
}
if (event.type === "step.started" && step !== undefined) {
if (eventTimestamp !== undefined) {
step.startTime = eventTimestamp;
}
step.status = "running";
continue;
}
if (event.type === "reasoning.appended" && step !== undefined) {
step.reasoningText = (step.reasoningText ?? "") + event.data.reasoningDelta;
continue;
}
if (event.type === "reasoning.completed" && step !== undefined && isRecord(event.data)) {
step.reasoningText = readString(event.data.reasoning);
continue;
}
if (event.type === "message.appended" && step !== undefined) {
step.responseText = (step.responseText ?? "") + event.data.messageDelta;
continue;
}
if (event.type === "message.completed" && step !== undefined && isRecord(event.data)) {
const message = readString(event.data.message);
const finishReason = readString(event.data.finishReason);
if (finishReason !== undefined) {
step.finishReason = finishReason;
}
if (message !== undefined) {
step.responseText = message;
if (finishReason !== "tool-calls") {
turn.assistantMessage = message;
}
}
continue;
}
if (event.type === "actions.requested" && step !== undefined && isRecord(event.data)) {
const actions = event.data.actions;
if (Array.isArray(actions)) {
for (const actionValue of actions) {
if (!isRecord(actionValue)) {
continue;
}
const callId = readString(actionValue.callId);
const name = getTraceActionNameFromRequest(actionValue);
if (callId === undefined || name === undefined) {
continue;
}
const action = ensureAction(
step,
createTraceAction({
callId,
input: actionValue.input,
kind: getTraceActionKindFromRequest(actionValue),
name,
status: "running",
}),
);
action.input = actionValue.input;
action.status = "running";
if (eventTimestamp !== undefined && action.startTime === undefined) {
action.startTime = eventTimestamp;
}
}
}
continue;
}
if (event.type === "input.requested" && step !== undefined && isRecord(event.data)) {
const requests = event.data.requests;
if (Array.isArray(requests)) {
for (const requestValue of requests) {
if (!isRecord(requestValue)) {
continue;
}
const actionValue = requestValue.action;
if (!isRecord(actionValue)) {
continue;
}
const callId = readString(actionValue.callId);
const name = getTraceActionNameFromRequest(actionValue);
if (callId === undefined || name === undefined) {
continue;
}
const action = ensureAction(
step,
createTraceAction({
callId,
input: actionValue.input,
kind: getTraceActionKindFromRequest(actionValue),
name,
status: "requested",
}),
);
action.input = actionValue.input;
action.status = "requested";
if (eventTimestamp !== undefined && action.startTime === undefined) {
action.startTime = eventTimestamp;
}
}
}
continue;
}
if (event.type === "action.result" && step !== undefined && isRecord(event.data)) {
const resultValue = event.data.result;
if (!isRecord(resultValue)) {
continue;
}
const callId = readString(resultValue.callId);
const name = getTraceActionNameFromResult(resultValue);
if (callId === undefined || name === undefined) {
continue;
}
const action = ensureAction(
step,
createTraceAction({
callId,
kind: getTraceActionKindFromResult(resultValue),
name,
}),
);
action.kind = getTraceActionKindFromResult(resultValue);
action.name = name;
action.output = resultValue.output;
action.status = getTraceActionStatusFromResult(event.data);
action.error = getTraceActionErrorFromResult(event.data);
if (eventTimestamp !== undefined) {
action.endTime = eventTimestamp;
}
continue;
}
if (event.type === "agent.started") {
turn.subagentCount += 1;
if (step !== undefined) {
step.subagentCount += 1;
}
continue;
}
if (event.type === "step.completed" && step !== undefined && isRecord(event.data)) {
const finishReason = readString(event.data.finishReason);
if (finishReason !== undefined) {
step.finishReason = finishReason;
}
if (eventTimestamp !== undefined) {
step.endTime = eventTimestamp;
}
step.status = "completed";
const usageValue = event.data.usage;
if (isRecord(usageValue)) {
step.usage = {
cacheReadTokens: readNumber(usageValue.cacheReadTokens),
cacheWriteTokens: readNumber(usageValue.cacheWriteTokens),
inputTokens: readNumber(usageValue.inputTokens),
outputTokens: readNumber(usageValue.outputTokens),
};
}
continue;
}
if (event.type === "step.failed" && step !== undefined && isRecord(event.data)) {
if (eventTimestamp !== undefined) {
step.endTime = eventTimestamp;
}
step.errorMessage = readString(event.data.message);
for (const action of step.actions) {
if (action.status !== "requested" && action.status !== "running") {
continue;
}
if (eventTimestamp !== undefined && action.endTime === undefined) {
action.endTime = eventTimestamp;
}
action.status = "aborted";
}
step.status = "failed";
continue;
}
if (event.type === "turn.completed") {
if (eventTimestamp !== undefined) {
turn.endTime = eventTimestamp;
}
turn.status = "completed";
continue;
}
if (event.type === "turn.failed" || event.type === "session.failed") {
const failureMessage =
isRecord(event.data) && typeof event.data.message === "string"
? event.data.message
: undefined;
if (eventTimestamp !== undefined) {
turn.endTime = eventTimestamp;
}
abortOpenTraceWork({
endedAt: eventTimestamp,
message: failureMessage,
turn,
});
turn.status = "failed";
continue;
}
if (
event.type === "session.waiting" &&
turn.endTime === undefined &&
eventTimestamp !== undefined
) {
turn.endTime = eventTimestamp;
}
}
for (const turn of orderedTurns) {
applyDuration({
endTime: turn.endTime,
setDuration: (durationMs) => {
turn.durationMs = durationMs;
},
startTime: turn.startTime,
});
for (const step of turn.steps) {
applyDuration({
endTime: step.endTime,
setDuration: (durationMs) => {
step.durationMs = durationMs;
},
startTime: step.startTime,
});
for (const action of step.actions) {
applyDuration({
endTime: action.endTime,
setDuration: (durationMs) => {
action.durationMs = durationMs;
},
startTime: action.startTime,
});
}
}
}
return orderedTurns.map(toReadonlyTurn);
}