The open-source agent harness - the runtime layer that turns an LLM into a working agent.
import { MAIN_THREAD_ID, type SessionEventTimelineSegment } from './sessionEventTimeline.js';
import { compressInterTurnGaps } from './sessionEventTimelineChart.js';
import {
asTimelineEvent,
eventCreatedAt,
eventId,
eventThreadId,
extractText,
getSubAgentDescription,
getTurnInputSummary,
getTurnInputType,
isAbortShapedThreadError,
isRecord,
parentToolCallId,
parseTimestamp,
readString,
terminalCompletedAt,
terminalMessage,
terminalReason,
terminalStatus,
terminalThreadError,
toolCallDescription,
toolCallsOf,
type TimelineEvent,
} from './sessionTimelineEvents.js';
import type { SessionTurnView } from './sessionTurnViews.js';
type SubAgentToolCallRequest = {
startedAtMs: number;
threadId: string;
modelEventId: string;
};
/**
* Convert server turns and events into the transport-independent intervals
* consumed by the Sessions timeline.
*
* The conversion runs in two passes because several bars need a later event
* to determine their end:
* - tool calls span from the model event that requested them to `tool.response`,
* or to `tool.response_required` / turn end when still waiting on a human;
* - sub-agent tracks span from `thread.created` to `thread.done`, or to
* `turn.done` when the child never emitted done (e.g. client cancel);
* - approval-gated and sub-agent parent calls are excluded from ordinary tool
* bars because they have dedicated visual representations.
*
* The second pass emits one user marker per renderable turn, then chronological
* event segments for each thread. Finally, real idle gaps between turns are
* removed so old sessions remain readable without changing durations inside a turn.
*/
export function buildSessionTimelineSegments(turns: SessionTurnView[]): SessionEventTimelineSegment[] {
const originMs = parseTimestamp(turns[0]?.created.createdAt);
if (originMs == null) return [];
// Correlation indexes built up front let the emission pass calculate complete
// intervals without depending on the source event order.
const toolResponsesByTurnId = new Map<string, Map<string, TimelineEvent>>();
const toolResponseRequiredByTurnId = new Map<string, Map<string, TimelineEvent>>();
const approvalRequiredIdsByTurnId = new Map<string, Set<string>>();
const threadDoneEvents = new Map<string, TimelineEvent>();
const subAgentToolCallIds = new Set<string>();
const toolCallRequestsByTurnId = new Map<string, Map<string, SubAgentToolCallRequest>>();
let latestMs = originMs;
for (const turn of turns) {
latestMs = Math.max(latestMs, parseTimestamp(turn.created.createdAt) ?? latestMs);
latestMs = Math.max(latestMs, parseTimestamp(terminalCompletedAt(turn.done?.state)) ?? latestMs);
for (const raw of turn.events) {
const event = asTimelineEvent(raw);
if (event == null) continue;
latestMs = Math.max(latestMs, parseTimestamp(eventCreatedAt(event)) ?? latestMs);
if (event.type === 'tool.response') {
const toolCallId = readString(event, 'toolCallId', 'tool_call_id');
if (toolCallId == null) continue;
const responses = toolResponsesByTurnId.get(turn.turnId) ?? new Map();
responses.set(toolCallId, event);
toolResponsesByTurnId.set(turn.turnId, responses);
} else if (event.type === 'tool.response_required') {
const pending = toolResponseRequiredByTurnId.get(turn.turnId) ?? new Map();
for (const toolCall of toolCallsOf(event)) {
if (typeof toolCall.id === 'string') pending.set(toolCall.id, event);
}
toolResponseRequiredByTurnId.set(turn.turnId, pending);
} else if (event.type === 'tool.approval_required') {
const ids = approvalRequiredIdsByTurnId.get(turn.turnId) ?? new Set<string>();
for (const toolCall of toolCallsOf(event)) {
if (typeof toolCall.id === 'string') ids.add(toolCall.id);
}
approvalRequiredIdsByTurnId.set(turn.turnId, ids);
} else if (event.type === 'thread.created') {
const toolCallId = parentToolCallId(event);
if (toolCallId != null) subAgentToolCallIds.add(toolCallId);
} else if (event.type === 'thread.done') {
threadDoneEvents.set(eventThreadId(event), event);
} else if (event.type === 'model.message') {
const startedAtMs = parseTimestamp(eventCreatedAt(event));
if (startedAtMs == null) continue;
const requests = toolCallRequestsByTurnId.get(turn.turnId) ?? new Map();
for (const toolCall of toolCallsOf(event)) {
if (typeof toolCall.id === 'string') {
requests.set(toolCall.id, {
startedAtMs,
threadId: eventThreadId(event),
modelEventId: eventId(event),
});
}
}
toolCallRequestsByTurnId.set(turn.turnId, requests);
}
}
}
const segments: SessionEventTimelineSegment[] = [];
const emittedWaitingRequestIds = new Set<string>();
// Only the last event-turn in a display band gets a "Turn completed" marker so
// MCP-auth resumes don't plant a mid-band diamond on top of the next model bar.
const lastTurnIdByNumber = new Map<number, string>();
const displayTurnIndexByEventIndex = new Map<number, number>();
for (const turn of turns) {
lastTurnIdByNumber.set(turn.turnNumber, turn.turnId);
displayTurnIndexByEventIndex.set(turn.eventTurnNumber - 1, turn.turnNumber - 1);
}
for (const turn of turns) {
const createdMs = parseTimestamp(turn.created.createdAt);
if (createdMs == null) continue;
// Compress with unique event-turn indexes so MCP-auth idle between auth and
// resume is removed; remap to the display band afterward.
const turnIndex = turn.eventTurnNumber - 1;
// Resume/MCP-auth turns have no user input; don't invent a user.message marker.
if (turn.renderable) {
segments.push({
id: `${turn.turnId}-user`,
type: 'user',
title: getTurnInputType(turn),
description: getTurnInputSummary(turn),
startMs: createdMs - originMs,
endMs: createdMs - originMs,
turnIndex,
threadId: MAIN_THREAD_ID,
isMarker: true,
});
}
// Model intervals are independent per thread. Using one global previous
// timestamp would make concurrent sub-agent bars consume each other's time.
const lastTimestampByThreadId = new Map<string, number>();
const events = [...turn.events]
.map(asTimelineEvent)
.filter((event): event is TimelineEvent => event != null)
.sort(
(left, right) => (parseTimestamp(eventCreatedAt(left)) ?? 0) - (parseTimestamp(eventCreatedAt(right)) ?? 0),
);
for (const event of events) {
const eventMs = parseTimestamp(eventCreatedAt(event));
if (eventMs == null) continue;
const threadId = eventThreadId(event);
appendEventSegments({
event,
eventMs,
createdMs,
originMs,
turn,
turnIndex,
threadId,
lastTimestampByThreadId,
toolResponsesByTurnId,
toolResponseRequiredByTurnId,
approvalRequiredIdsByTurnId,
subAgentToolCallIds,
toolCallRequestsByTurnId,
threadDoneEvents,
emittedWaitingRequestIds,
segments,
});
lastTimestampByThreadId.set(threadId, eventMs);
}
appendTerminalSegment({
turn,
turnIndex,
originMs,
latestMs,
segments,
emitDoneMarker: lastTurnIdByNumber.get(turn.turnNumber) === turn.turnId,
});
}
return compressInterTurnGaps(
segments.map(segment => ({
...segment,
startMs: Math.max(0, segment.startMs),
endMs: Math.max(0, segment.endMs),
})),
)
.map(segment => ({
...segment,
turnIndex: displayTurnIndexByEventIndex.get(segment.turnIndex) ?? segment.turnIndex,
}))
.sort((left, right) => left.startMs - right.startMs || left.endMs - right.endMs);
}
/**
* Map one supported server event to zero or more visual segments.
*
* New event types should be added here
* when they have a clear visual category and useful timing semantics.
*/
function appendEventSegments({
event,
eventMs,
createdMs,
originMs,
turn,
turnIndex,
threadId,
lastTimestampByThreadId,
toolResponsesByTurnId,
toolResponseRequiredByTurnId,
approvalRequiredIdsByTurnId,
subAgentToolCallIds,
toolCallRequestsByTurnId,
threadDoneEvents,
emittedWaitingRequestIds,
segments,
}: {
event: TimelineEvent;
eventMs: number;
createdMs: number;
originMs: number;
turn: SessionTurnView;
turnIndex: number;
threadId: string;
lastTimestampByThreadId: Map<string, number>;
toolResponsesByTurnId: Map<string, Map<string, TimelineEvent>>;
toolResponseRequiredByTurnId: Map<string, Map<string, TimelineEvent>>;
approvalRequiredIdsByTurnId: Map<string, Set<string>>;
subAgentToolCallIds: Set<string>;
toolCallRequestsByTurnId: Map<string, Map<string, SubAgentToolCallRequest>>;
threadDoneEvents: Map<string, TimelineEvent>;
emittedWaitingRequestIds: Set<string>;
segments: SessionEventTimelineSegment[];
}): void {
switch (event.type) {
case 'model.message': {
const previousMs = lastTimestampByThreadId.get(threadId) ?? createdMs;
const modelContent = extractText(event.content);
const responses = toolResponsesByTurnId.get(turn.turnId);
const pendingRequired = toolResponseRequiredByTurnId.get(turn.turnId);
const approvalIds = approvalRequiredIdsByTurnId.get(turn.turnId);
const turnDoneMs = parseTimestamp(terminalCompletedAt(turn.done?.state));
// A model event can request several tools at once. Each tool gets its own
// response-bounded interval; overlapping intervals are grouped later by
// the chart-layout utility into one parallel-tool-call bar.
// Pending human-wait tools (ask-user) still emit a bar so strip Tool calls
// matches Agent steps even before tool.response arrives.
for (const toolCall of toolCallsOf(event)) {
const toolCallId = typeof toolCall.id === 'string' ? toolCall.id : undefined;
// Skip parent create_sub_agent calls and approval-gated calls; they have their own segments.
if (toolCallId == null || subAgentToolCallIds.has(toolCallId) || approvalIds?.has(toolCallId)) continue;
const response = responses?.get(toolCallId);
const responseMs = response == null ? null : parseTimestamp(eventCreatedAt(response));
const required = pendingRequired?.get(toolCallId);
const requiredMs = required == null ? null : parseTimestamp(eventCreatedAt(required));
const endMs = responseMs ?? requiredMs ?? turnDoneMs ?? eventMs;
if (endMs < eventMs) continue;
segments.push({
id: `${eventId(event)}-${toolCallId}`,
type: 'tool_call',
title: 'tool.call',
description: toolCallDescription(toolCall),
startMs: eventMs - originMs,
endMs: endMs - originMs,
turnIndex,
threadId,
...(responseMs == null && endMs <= eventMs ? { isMarker: true } : {}),
});
}
// The model bar covers processing since the previous event on this thread.
// Keep an empty root model segment because it may still contain tool calls
// and therefore represents real model time.
if (modelContent.length > 0 || threadId === MAIN_THREAD_ID) {
segments.push({
id: eventId(event),
type: 'model',
title: event.type,
description: modelContent,
startMs: Math.max(0, previousMs - originMs),
endMs: Math.max(0, eventMs - originMs),
turnIndex,
threadId,
isMarker: eventMs <= previousMs,
});
}
return;
}
case 'thread.created': {
// The parent call is represented by this track, while child events are
// assigned to the same thread id and rendered on the track's lane.
const parentCallId = parentToolCallId(event);
const request = parentCallId == null ? undefined : toolCallRequestsByTurnId.get(turn.turnId)?.get(parentCallId);
if (request != null) {
const waitingRequestId = `${turn.turnId}:${request.modelEventId}`;
if (!emittedWaitingRequestIds.has(waitingRequestId)) {
emittedWaitingRequestIds.add(waitingRequestId);
if (request.startedAtMs < eventMs) {
segments.push({
id: `${eventId(event)}-waiting`,
type: 'system',
title: 'system.waiting_for_sub_agent',
description: 'System waiting for sub-agent to start executing',
startMs: request.startedAtMs - originMs,
endMs: eventMs - originMs,
turnIndex,
threadId: request.threadId,
});
}
}
}
const doneEvent = threadDoneEvents.get(threadId);
const doneMs = doneEvent == null ? null : parseTimestamp(eventCreatedAt(doneEvent));
// Cancelled unfinished children omit public thread.done; close the bar at turn end
// so the chart still allocates a lane for child model/tool segments.
const turnEndMs = parseTimestamp(terminalCompletedAt(turn.done?.state)) ?? parseTimestamp(turn.done?.createdAt);
const closeMs =
doneMs != null && doneMs >= eventMs ? doneMs : turnEndMs != null && turnEndMs >= eventMs ? turnEndMs : eventMs;
segments.push({
id: eventId(event),
type: 'sub_agent',
title: event.type,
description: getSubAgentDescription(event),
startMs: eventMs - originMs,
endMs: closeMs - originMs,
turnIndex,
threadId,
isMarker: closeMs <= eventMs,
});
const doneState = doneEvent != null && isRecord(doneEvent.state) ? doneEvent.state : undefined;
if (doneState != null && terminalStatus(doneState) === 'error') {
const errorText = terminalThreadError(doneState);
const turnCancelled = terminalStatus(turn.done?.state) === 'cancelled';
// Cancel mid-stream can leave abort-shaped thread.done error; do not chart as failure.
if (!(turnCancelled && isAbortShapedThreadError(errorText))) {
const errorMs = doneMs ?? eventMs;
segments.push({
id: `${eventId(event)}-error`,
type: 'error',
title: 'thread.error',
description: errorText,
startMs: errorMs - originMs,
endMs: errorMs - originMs,
turnIndex,
threadId,
isMarker: true,
});
}
}
return;
}
case 'tool.approval_required':
case 'tool.response_required':
case 'mcp.auth_required':
case 'mcp.initialize':
case 'sandbox.created':
// These are point-in-time state transitions, so start and end are equal
// and Chart.js renders them with the configured minimum marker width.
segments.push({
id: eventId(event),
type:
event.type === 'tool.approval_required'
? 'approval'
: event.type === 'tool.response_required' || event.type === 'mcp.auth_required'
? 'waiting_on_human'
: 'system',
title: event.type,
description:
event.type === 'tool.approval_required'
? 'Approval required'
: event.type === 'tool.response_required'
? 'Waiting for user response'
: event.type === 'mcp.auth_required'
? 'MCP authentication required'
: event.type === 'mcp.initialize'
? 'MCP initialized'
: 'Sandbox created',
startMs: eventMs - originMs,
endMs: eventMs - originMs,
turnIndex,
threadId,
isMarker: true,
});
return;
default:
return;
}
}
/**
* Add the terminal marker that closes a turn.
*
* Errors use the latest observed timestamp when the backend omitted
* `completed_at`, ensuring failures remain visible instead of being dropped.
* Running/paused turns have no terminal marker because they have not ended.
* Intermediate `turn.done` markers are skipped when a later event-turn shares
* the same display band (MCP-auth resume), so the diamond does not cover the
* next model/tool bars.
*/
function appendTerminalSegment({
turn,
turnIndex,
originMs,
latestMs,
segments,
emitDoneMarker,
}: {
turn: SessionTurnView;
turnIndex: number;
originMs: number;
latestMs: number;
segments: SessionEventTimelineSegment[];
emitDoneMarker: boolean;
}): void {
const status = terminalStatus(turn.done?.state);
if (status === 'error') {
const errorMs = parseTimestamp(terminalCompletedAt(turn.done?.state)) ?? latestMs;
segments.push({
id: `${turn.turnId}-error`,
type: 'error',
title: 'turn.error',
description: terminalMessage(turn.done?.state),
startMs: errorMs - originMs,
endMs: errorMs - originMs,
turnIndex,
threadId: MAIN_THREAD_ID,
isMarker: true,
});
return;
}
if (status === 'cancelled') {
const cancelledMs = parseTimestamp(terminalCompletedAt(turn.done?.state)) ?? latestMs;
const reason = terminalReason(turn.done?.state);
segments.push({
id: `${turn.turnId}-turn.cancelled`,
type: 'system',
title: 'turn.cancelled',
description: reason.length > 0 ? reason : 'cancelled',
startMs: cancelledMs - originMs,
endMs: cancelledMs - originMs,
turnIndex,
threadId: MAIN_THREAD_ID,
isMarker: true,
});
return;
}
if (status !== 'done' || !emitDoneMarker) return;
const doneMs = parseTimestamp(terminalCompletedAt(turn.done?.state));
if (doneMs == null) return;
segments.push({
id: `${turn.turnId}-turn.done`,
type: 'system',
title: 'turn.done',
description: 'Turn completed',
startMs: doneMs - originMs,
endMs: doneMs - originMs,
turnIndex,
threadId: MAIN_THREAD_ID,
isMarker: true,
});
}