The open-source agent harness - the runtime layer that turns an LLM into a working agent.
import type {
AppendMessage,
CompleteAttachment,
ExportedMessageRepositoryItem,
MessageStatus,
ThreadMessage,
ThreadUserMessagePart,
} from '@assistant-ui/core';
import type {
McpAuthRequiredEvent,
Turn,
TurnCreatedEvent,
TurnEvent,
TurnInputItem,
TurnStreamData,
} from './server/index.js';
import type { AgentChatServer } from './server/types.js';
import { ROOT_THREAD_ID } from './constants.js';
import { extractTurnUserText } from './extractTurnUserText.js';
import {
buildRootAssistantContent,
buildRootAssistantContentForIds,
findFirstPendingApprovalThreadId,
findFirstPendingResponseThreadId,
ingestStreamEvent,
ingestTurnEvent,
PeerThreadFoldState,
type ThreadBucket,
} from './foldPeerThreads.js';
import { drainListPages } from './listPages.js';
import { buildMcpAuthTextParts, mcpAuthAssistantStatus, mcpAuthMessageCustom } from './mcpAuth.js';
import { CANCELLATION_REASON_CUSTOM_KEY } from './messageCustomMetadata.js';
import type { AssistantContentPart } from './modelMessageContent.js';
import { extractImageUrlFromUserContentItem, imageUrlToAttachment } from './modelMessageImageContent.js';
import {
createEmptySessionSnapshot,
replaceSessionSnapshot,
sessionEventsToSessionRecord,
turnToSessionRecord,
type GatewaySessionEventItem,
type ProjectSessionMessagesOptions,
type RequiredActionsOverlay,
type SessionHistoryPagination,
type SessionSnapshot,
type SessionTurnRecord,
} from './sessionSnapshot.js';
import {
applyApprovalDecisionsToContent,
collectApprovalDecisionsFromTurnInput,
collectSubsequentApprovalDecisions,
hasPendingToolApproval,
messageHasPendingApprovals,
TOOL_APPROVAL_THREAD_ID_CUSTOM_KEY,
toolApprovalMessageCustom,
toolApprovalStatus,
} from './toolApproval.js';
import {
applyStagedResponsesToContent,
applyUserToolResponsesToFold,
collectSubsequentToolResponses,
collectToolResponsesFromTurnInput,
hasPendingToolResponse,
messageHasPendingResponses,
TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY,
toolResponseMessageCustom,
toolResponseStatus,
} from './toolResponse.js';
import { appendMcpAuthToTurnContent, appendToolApprovalToTurnContent } from './turnEventHelpers.js';
import type { TurnStreamUpdate } from './turnStreamUpdate.js';
export { CANCELLATION_REASON_CUSTOM_KEY } from './messageCustomMetadata.js';
/**
* Turn / event → assistant-ui normalization
*
* This module is the projection layer: it turns gateway session state into
* `ThreadMessage[]` for `@assistant-ui/core`. The hook in
* `useTrueForgeAgentMessages.ts` owns the mutable `SessionSnapshot`; this
* file defines how that snapshot is built and rendered.
*
* ## Data model
*
* Gateway side:
* - A **session** has ordered **turns** (each with `input`, `state`, `listEvents`).
* - A turn's **input** is either a user message (`user.message`) or a continuation
* (`user.tool_response`, `user.tool_approval`, …).
* - **Events** (`model.message`, `tool.*`, `thread.created`, …) arrive on a
* **thread id**; the root conversation uses `ROOT_THREAD_ID` (`"main"`).
*
* Local side (`SessionSnapshot` in `sessionSnapshot.ts`):
* - `fold` — accumulated events across all threads (see `foldPeerThreads.ts`).
* - `turns` — committed turn records, each optionally storing
* `rootModelMessageIds` (root-thread `model.message` ids ingested with that turn).
* - `pendingUser` / `activeStream` — optimistic UI while a turn is in flight.
* - `groupRootBaseline` — root `model.message` ids that existed before the active
* turn group started; used to scope live streaming to the current group only.
* - `requiredActions` — locally staged approval/response decisions before resume.
*
* Output:
* - Alternating **user** / **assistant** `ThreadMessage` pairs.
* - One assistant message per **turn group** (user turn + its continuation turns).
*
* ## Turn groups
*
* A **turn group** starts at a turn whose input contains `user.message`. Later
* turns with only continuation inputs (tool response, tool approval, MCP resume)
* belong to the same group and are folded into the same assistant message.
*
* Root content for a group is the union of `rootModelMessageIds` on every turn
* in that group. Prior groups must not leak in: scope with
* `rootModelMessageIdsSinceBaseline(fold, baseline)` where
* `baseline = groupRootBaseline ?? computeGroupRootBaseline(turns)`.
*
* ## Pipeline
*
* 1. **Ingest** — `ingestStreamEvent` / `ingestTurnEvent` append events into
* per-thread buckets in `PeerThreadFoldState`. Deltas merge in place.
*
* 2. **Fold to content** — `buildRootAssistantContentForIds` walks scoped
* `model.message` ids and emits assistant-ui parts (reasoning, text, tool-call).
* Sub-agent child threads are attached under `create_sub_agent` tool-calls as
* nested `messages` (see `attachSubAgentMessages` in `foldPeerThreads.ts`).
*
* 3. **History projection** — `projectHistoryTurns` walks committed `turns`:
* - User turn → push user message; push assistant if the group has content.
* - Continuation turn → merge assistant content into the last assistant message
* in the group (same `*-assistant` id as the user turn that opened the group).
* - Apply answers from later continuation turns onto earlier tool-calls via
* `collectSubsequentApprovalDecisions` / `collectSubsequentToolResponses`.
* - A paused group's assistant message keeps `requires-action` until a later
* continuation turn resolves all its approvals/responses, then downgrades
* to the turn-state status (`complete`, `error`, `cancelled`).
*
* 4. **Live projection** — `projectSessionMessages` = history + `pendingUser` +
* `activeStream`. While streaming, `streamTurnEvents` yields content scoped to
* `groupRootBaseline`. When `streamComplete`, `projectActiveStreamUpdate`
* rebuilds from the fold (same baseline scoping as streaming).
*
* 5. **Staged overlay** — Before the SDK resume turn is sent, user decisions sit
* in `requiredActions` and are merged onto messages by
* `applyRequiredActionsOverlayToMessages` so the UI shows interrupt + result
* together. Resume is batched: all pending approvals and ask-user answers in
* a paused message must be resolved before `sendTurn({ inputs })`.
*
* ## Required actions (assistant-ui mapping)
*
* | Gateway event / input | assistant-ui representation |
* |-----------------------------|------------------------------------------------------|
* | `tool.approval_required` | `tool-call` with `approval: { id }`, status |
* | | `requires-action` / `tool-calls`, custom thread id |
* | `user.tool_approval` | closes `tool.approval_required`: sets `approval.approved` |
* | | (+ optional reason) on tool-call |
* | `tool.response_required` | `tool-call` with `interrupt: { type: "human", … }` |
* | (ask_user_question) | payload parsed from tool args (`askUserQuestion.ts`) |
* | `user.tool_response` | closes `tool.response_required`: sets `result` on |
* | | tool-call and clears the pending `interrupt` |
* | `mcp.auth_required` | Appended auth link text parts; status `interrupt` |
*
* Sub-agent threads can have their own pending approval/response; metadata
* `toolApprovalThreadId` / `toolResponseThreadId` on nested assistant messages
* scopes resume inputs to the correct thread.
*
* A sub-agent stays attached under the `create_sub_agent` tool-call that spawned
* it, which lives in the root `model.message` of the turn that opened the group.
* The child thread keeps producing events across several turns (spawn turn, then
* continuation turns that answer its required actions), and all of them render
* under that single tool-call in the group's one assistant message.
*
* INVARIANT — while a sub-agent is active the parent agent is paused awaiting a
* required action, so every following turn until it finishes is a continuation
* (`user.tool_response` / `user.tool_approval` / MCP resume), NOT a `user.message`.
* If a sub-agent is spawned/active in turn 1, turn 2 cannot carry `user.message`
* input. A `user.message` there would open a new turn group (`userText` boundary)
* and split the still-running sub-agent's events away from its tool-call. The
* gateway enforces this; the projection relies on it for correct nesting.
*
* ## Assumptions
*
* - Root-thread model messages use `threadId === ROOT_THREAD_ID`.
* - Turn order in `snapshot.turns` matches gateway chronological order.
* - `rootModelMessageIds` on committed turns is accurate (set in
* `commitActiveStream` when a stream completes).
* - Continuation turns never carry `user.message`; that boundary defines groups.
* In particular, while a sub-agent (or any tool) is mid-flight awaiting a
* required action, the next turn is always a continuation, never a new
* `user.message`.
* - Tool-call identity is stable via `toolCallId` across events, fold state, and
* assistant-ui parts.
* - Reload (`buildSnapshotFromSessionEvents`) and live paths must produce the same
* per-group scoping; history uses cumulative `groupRootIds` per turn index,
* live uses `groupRootBaseline`.
*/
const TURN_EVENTS_PAGE_SIZE = 25;
const SESSION_EVENTS_PAGE_SIZE = 100;
/** Cap how many event pages initial load / load-older may chain for a group boundary. */
const MAX_HISTORY_BOUNDARY_PAGES = 10;
interface FetchSessionEventsOptions {
/**
* Newest turn in the listing window (initial load only). Lists that turn and
* its ancestors. Omit to use the session last turn. Running-turn events are
* excluded by the API — subscribe to that turn for live events.
*/
lastTurnId?: string;
}
interface SessionEventsPageResult {
/** Newest-first items from this request. */
itemsNewestFirst: GatewaySessionEventItem[];
olderPageToken?: string;
hasOlder: boolean;
}
/**
* Drops a leading incomplete turn (events before the first `turn.created`) that
* appears when a page boundary splits a turn.
*/
function trimIncompleteLeadingEvents(itemsAsc: GatewaySessionEventItem[]): GatewaySessionEventItem[] {
const start = itemsAsc.findIndex(item => item.event.type === 'turn.created');
if (start === -1) {
return [];
}
return itemsAsc.slice(start);
}
/**
* Whether the oldest complete turn in a chronological window opens a user group.
* `incomplete` means we still lack a finished oldest turn (need an older page).
*/
function oldestCompleteTurnGroupState(
itemsAsc: GatewaySessionEventItem[],
): 'user-group' | 'continuation' | 'incomplete' {
const trimmed = trimIncompleteLeadingEvents(itemsAsc);
if (trimmed.length === 0) {
return 'incomplete';
}
const created = trimmed[0];
if (created?.event.type !== 'turn.created') {
return 'incomplete';
}
const hasDone = trimmed.some(item => item.turnId === created.turnId && item.event.type === 'turn.done');
if (!hasDone) {
return 'incomplete';
}
return extractTurnUserText(created.event.input) != null ? 'user-group' : 'continuation';
}
async function fetchSessionEventsPage(
server: AgentChatServer,
sessionId: string,
options?: FetchSessionEventsOptions & { pageToken?: string },
): Promise<SessionEventsPageResult> {
const page = await server.listEvents({
sessionId,
limit: SESSION_EVENTS_PAGE_SIZE,
...(options?.lastTurnId != null ? { lastTurnId: options.lastTurnId } : {}),
...(options?.pageToken != null ? { pageToken: options.pageToken } : {}),
});
const olderPageToken = page.nextPageToken;
const hasOlder = olderPageToken != null && olderPageToken !== '';
return {
itemsNewestFirst: page.data,
...(olderPageToken != null && olderPageToken !== '' ? { olderPageToken } : {}),
hasOlder,
};
}
/**
* Fetches pages until the chronological window starts on a complete user-message
* turn group (or history is exhausted).
*/
async function fetchSessionEventsWindow(
server: AgentChatServer,
sessionId: string,
options?: FetchSessionEventsOptions & { pageToken?: string },
): Promise<{
itemsAsc: GatewaySessionEventItem[];
olderPageToken?: string;
hasOlder: boolean;
}> {
let itemsNewestFirst: GatewaySessionEventItem[] = [];
let pageToken = options?.pageToken;
let olderPageToken: string | undefined;
let hasOlder = false;
for (let pageCount = 0; pageCount < MAX_HISTORY_BOUNDARY_PAGES; pageCount++) {
const page = await fetchSessionEventsPage(server, sessionId, {
...options,
...(pageToken != null ? { pageToken } : {}),
});
itemsNewestFirst = [...itemsNewestFirst, ...page.itemsNewestFirst];
olderPageToken = page.olderPageToken;
hasOlder = page.hasOlder;
const itemsAsc = trimIncompleteLeadingEvents([...itemsNewestFirst].reverse());
const groupState = oldestCompleteTurnGroupState(itemsAsc);
if (groupState === 'user-group' || !hasOlder) {
return {
itemsAsc,
...(olderPageToken != null ? { olderPageToken } : {}),
hasOlder,
};
}
if (olderPageToken == null) {
return { itemsAsc, hasOlder: false };
}
pageToken = olderPageToken;
}
const itemsAsc = trimIncompleteLeadingEvents([...itemsNewestFirst].reverse());
return {
itemsAsc,
...(olderPageToken != null ? { olderPageToken } : {}),
hasOlder,
};
}
/**
* Fetches session-level events via `server.listEvents()`. The API returns pages
* in desc order (newest first); the collected array is reversed before returning
* so callers receive events in chronological (asc) order.
*
* Used by rewind/edit paths that need the full ancestor window.
*/
async function fetchAllSessionEvents(
server: AgentChatServer,
sessionId: string,
options?: FetchSessionEventsOptions,
): Promise<GatewaySessionEventItem[]> {
const items = await drainListPages(pageToken =>
server.listEvents({
sessionId,
limit: SESSION_EVENTS_PAGE_SIZE,
...(options?.lastTurnId != null ? { lastTurnId: options.lastTurnId } : {}),
...(pageToken != null ? { pageToken } : {}),
}),
);
items.reverse();
return items;
}
function cloneThreadBucket(bucket: ThreadBucket): ThreadBucket {
return {
events: new Map(bucket.events),
modelMessageIds: [...bucket.modelMessageIds],
toolResults: new Map(bucket.toolResults),
pendingApprovals: new Map(bucket.pendingApprovals),
approvalDecisions: new Map(bucket.approvalDecisions),
pendingResponses: new Map(bucket.pendingResponses),
done: bucket.done,
// Keep sub-agent failure text so a cloned bucket still shows as failed.
...(bucket.error != null ? { error: bucket.error } : {}),
...(bucket.title != null ? { title: bucket.title } : {}),
...(bucket.agentInfo != null ? { agentInfo: bucket.agentInfo } : {}),
};
}
/** Prepends older fold state ahead of the currently loaded fold (scroll-up). */
export function prependFoldState(older: PeerThreadFoldState, newer: PeerThreadFoldState): PeerThreadFoldState {
const result = new PeerThreadFoldState();
const threadIds = new Set([...older.threads.keys(), ...newer.threads.keys()]);
for (const threadId of threadIds) {
const olderBucket = older.threads.get(threadId);
const newerBucket = newer.threads.get(threadId);
if (olderBucket == null && newerBucket != null) {
result.threads.set(threadId, cloneThreadBucket(newerBucket));
continue;
}
if (newerBucket == null && olderBucket != null) {
result.threads.set(threadId, cloneThreadBucket(olderBucket));
continue;
}
if (olderBucket == null || newerBucket == null) {
continue;
}
result.threads.set(threadId, {
events: new Map([...olderBucket.events, ...newerBucket.events]),
modelMessageIds: [...olderBucket.modelMessageIds, ...newerBucket.modelMessageIds],
toolResults: new Map([...olderBucket.toolResults, ...newerBucket.toolResults]),
pendingApprovals: new Map([...olderBucket.pendingApprovals, ...newerBucket.pendingApprovals]),
approvalDecisions: new Map([...olderBucket.approvalDecisions, ...newerBucket.approvalDecisions]),
pendingResponses: new Map([...olderBucket.pendingResponses, ...newerBucket.pendingResponses]),
done: newerBucket.done || olderBucket.done,
// Prefer the newer failure text; if only the older turn failed, keep that.
...(newerBucket.error != null || olderBucket.error != null
? { error: newerBucket.error ?? olderBucket.error }
: {}),
...(newerBucket.title != null || olderBucket.title != null
? { title: newerBucket.title ?? olderBucket.title }
: {}),
...(newerBucket.agentInfo != null || olderBucket.agentInfo != null
? { agentInfo: newerBucket.agentInfo ?? olderBucket.agentInfo }
: {}),
});
}
for (const [threadId, link] of older.threadParents) {
result.threadParents.set(threadId, link);
}
for (const [threadId, link] of newer.threadParents) {
result.threadParents.set(threadId, link);
}
return result;
}
/**
* Ingests a chronologically ordered list of session-level event items into the
* snapshot. `turn.created` marks the start of a turn (provides user input),
* content events are folded as usual, and `turn.done` finalises the turn record
* and pushes it to `snapshot.turns`.
*
* `onTurnComplete` is called after each `turn.done` with the partially-built
* snapshot so callers can update UI progressively. The fold state is correct at
* that point for every turn up to and including the just-completed one.
*/
function ingestSessionEventsIntoSnapshot(
snapshot: SessionSnapshot,
items: GatewaySessionEventItem[],
onTurnComplete?: (snap: SessionSnapshot) => void,
): void {
let currentTurnId: string | null = null;
let currentCreatedEvent: TurnCreatedEvent | null = null;
let currentContentEvents: TurnEvent[] = [];
let beforeCount = 0;
// Session-scoped: sandbox.created fires when a sandbox is (re)created and the
// sandbox is reused by later turns, so carry the latest one forward.
let sessionSandboxId: string | undefined;
for (const item of items) {
const { turnId, event } = item;
if (event.type === 'turn.created') {
currentTurnId = turnId;
currentCreatedEvent = event;
currentContentEvents = [];
beforeCount = snapshot.fold.threads.get(ROOT_THREAD_ID)?.modelMessageIds.length ?? 0;
} else if (event.type === 'turn.done') {
if (currentTurnId == null || currentCreatedEvent == null) {
continue;
}
const afterBucket = snapshot.fold.threads.get(ROOT_THREAD_ID);
const rootModelMessageIds = (afterBucket?.modelMessageIds ?? []).slice(beforeCount);
const sandboxEvent = currentContentEvents.find(
(ev): ev is Extract<TurnEvent, { type: 'sandbox.created' }> => ev.type === 'sandbox.created',
);
sessionSandboxId = sandboxEvent?.sandboxId ?? sessionSandboxId;
applyUserToolResponsesToFold(snapshot.fold, currentCreatedEvent.input ?? []);
snapshot.turns.push(
sessionEventsToSessionRecord(currentTurnId, currentCreatedEvent, event, rootModelMessageIds, sessionSandboxId),
);
// Pass a new object reference so React's Object.is check in
// useState sees a changed value and schedules a re-render.
// The snapshot is mutated in place throughout this loop, so
// passing `snapshot` directly would make every tick look identical
// to React after the first setSnapshot call.
onTurnComplete?.(replaceSessionSnapshot(snapshot, {}));
currentTurnId = null;
currentCreatedEvent = null;
currentContentEvents = [];
} else {
if (currentTurnId != null) {
ingestTurnEvent(snapshot.fold, event);
currentContentEvents.push(event);
}
}
}
}
function rootModelMessageIdsForOpenTip(snapshot: SessionSnapshot): readonly string[] {
const committed = new Set(snapshot.turns.flatMap(turn => turn.rootModelMessageIds ?? []));
const rootIds = snapshot.fold.threads.get(ROOT_THREAD_ID)?.modelMessageIds ?? [];
return rootIds.filter(id => !committed.has(id));
}
/** Commits an open tip that finished before `turn.done` was in the events page. */
function commitFinishedOpenTip(snapshot: SessionSnapshot, turn: Turn): SessionSnapshot {
if (snapshot.turns.some(existing => existing.id === turn.id)) {
return snapshot;
}
return replaceSessionSnapshot(snapshot, {
turns: [
...snapshot.turns,
{
...turnToSessionRecord(turn),
rootModelMessageIds: rootModelMessageIdsForOpenTip(snapshot),
},
],
});
}
function attachRunningTurn(snapshot: SessionSnapshot, runningTurn: Turn | undefined): SessionSnapshot {
if (runningTurn == null) {
return snapshot;
}
const pendingUserText = extractTurnUserText(runningTurn.input);
// Tip is not in `turns`. Baseline committed groups only — fold already
// includes the open tip's messages, which must stay in live resume.
//2 scenario for Page Refresh:
// 1. only baseline the committed groups(there is only user msg no assistant msg)
// 2. the open tip's messages must stay in live resume (there is some assistant msg response in the fold)
const groupRootBaseline =
pendingUserText !== undefined
? snapshot.turns.flatMap(turn => turn.rootModelMessageIds ?? [])
: computeGroupRootBaseline(snapshot.turns);
return replaceSessionSnapshot(snapshot, {
runningTurn,
unstable_resume: true,
groupRootBaseline,
...(pendingUserText !== undefined
? {
pendingUser: {
turnId: runningTurn.id,
content: extractTurnUserMessageContent(runningTurn.input),
createdAt: new Date(runningTurn.createdAt),
},
}
: {}),
});
}
/**
* Last `turn.created` in ASC event order with no following `turn.done` — the
* open tip of the active branch in this window.
*/
function findOpenTurnCreated(
itemsAsc: readonly GatewaySessionEventItem[],
): { turnId: string; event: TurnCreatedEvent } | undefined {
let open: { turnId: string; event: TurnCreatedEvent } | undefined;
for (const item of itemsAsc) {
if (item.event.type === 'turn.created') {
open = { turnId: item.turnId, event: item.event };
} else if (item.event.type === 'turn.done') {
open = undefined;
}
}
return open;
}
function turnFromCreatedEvent(options: { sessionId: string; turnId: string; event: TurnCreatedEvent }): Turn {
const { sessionId, turnId, event } = options;
return {
id: turnId,
sessionId,
state: { status: 'running' },
createdAt: event.createdAt,
...(event.input != null ? { input: event.input } : {}),
...(event.previousTurnId === undefined ? {} : { previousTurnId: event.previousTurnId }),
};
}
interface SessionTip {
/** Turn to resume and subscribe to; absent once the tip has finished. */
runningTurn?: Turn;
/**
* Open tip that finished between `listEvents` and `getTurn`. It was not in
* the events page as `turn.done`, so the caller must commit it or the user
* message painted from the progress snapshot disappears.
*/
finishedTurn?: Turn;
/**
* Tip input that event ingestion could not apply, because it only folds a
* turn's input once that turn's `turn.done` arrives. Answered ask-user
* prompts and approvals live here, so this must be folded even when the tip
* is no longer running.
*/
continuationInput: readonly TurnInputItem[];
}
/**
* Resolves the tip turn of the active branch for resume/subscribe.
*
* An open `turn.created` with no later `turn.done` is the tip. `listEvents`
* includes that turn, so a finished window needs no extra turns fetch.
*/
async function resolveSessionTip(options: {
server: AgentChatServer;
sessionId: string;
itemsAsc: readonly GatewaySessionEventItem[];
}): Promise<SessionTip> {
const open = findOpenTurnCreated(options.itemsAsc);
if (open == null) {
return { continuationInput: [] };
}
const { server, sessionId } = options;
const continuationInput = open.event.input ?? [];
if (typeof server.getTurn === 'function') {
try {
const turn = await server.getTurn({
sessionId,
turnId: open.turnId,
});
if (turn.state.status === 'running') {
return {
runningTurn: turn,
continuationInput: turn.input ?? continuationInput,
};
}
// Tip finished between listEvents and getTurn: nothing to
// resume, but its answers still belong in the fold, and the turn
// itself must be committed so the painted user message stays.
return { finishedTurn: turn, continuationInput: turn.input ?? continuationInput };
} catch {
// getTurn failed; synthesize from the open turn.created below.
}
}
return {
runningTurn: turnFromCreatedEvent({
sessionId,
turnId: open.turnId,
event: open.event,
}),
continuationInput,
};
}
/**
* Builds a session snapshot using the session-level `listEvents` API.
*
* Loads the newest event page (extending only when a page boundary splits a
* turn group), then leaves older pages for `prependOlderSessionHistory`.
* A currently-running tip is an open `turn.created` in that window.
*
* `onProgress` fires after each complete turn, then once with the paintable
* window before `getTurn`, so callers can clear loading before the tip is confirmed.
*/
export async function buildSnapshotFromSessionEvents(
server: AgentChatServer,
sessionId: string,
onProgress?: (snap: SessionSnapshot) => void,
): Promise<SessionSnapshot> {
const window = await fetchSessionEventsWindow(server, sessionId);
const historyPagination: SessionHistoryPagination = {
hasOlder: window.hasOlder,
...(window.olderPageToken != null ? { olderPageToken: window.olderPageToken } : {}),
};
const snapshot = createEmptySessionSnapshot();
ingestSessionEventsIntoSnapshot(snapshot, window.itemsAsc, onProgress);
const withHistory = replaceSessionSnapshot(snapshot, {
historyEvents: window.itemsAsc,
historyPagination,
});
const open = findOpenTurnCreated(window.itemsAsc);
// The open tip is not in `turns` until `turn.done`. Attach it from the
// event so the first paint includes its user message.
const paintable =
open == null
? withHistory
: attachRunningTurn(
withHistory,
turnFromCreatedEvent({
sessionId,
turnId: open.turnId,
event: open.event,
}),
);
if (open != null) {
applyUserToolResponsesToFold(paintable.fold, open.event.input ?? []);
}
onProgress?.(paintable);
const tip = await resolveSessionTip({
server,
sessionId,
itemsAsc: window.itemsAsc,
});
// The tip has no turn.done in this window, so ingestion never folded its
// input. Apply it here so answered approvals / ask-user prompts are not
// restored as pending after a refresh. `getTurn` may carry answers that
// were not on `turn.created`; the write is keyed by tool call id.
applyUserToolResponsesToFold(withHistory.fold, tip.continuationInput);
if (tip.finishedTurn != null) {
return commitFinishedOpenTip(withHistory, tip.finishedTurn);
}
return attachRunningTurn(withHistory, tip.runningTurn);
}
/**
* Fetches the next older `listEvents` window and prepends it onto `snapshot`
* without tearing down live stream / pending UI state.
*/
export async function prependOlderSessionHistory(
server: AgentChatServer,
sessionId: string,
snapshot: SessionSnapshot,
): Promise<SessionSnapshot> {
const pagination = snapshot.historyPagination;
if (pagination?.hasOlder !== true || pagination.olderPageToken == null) {
return snapshot;
}
const window = await fetchSessionEventsWindow(server, sessionId, {
pageToken: pagination.olderPageToken,
});
if (window.itemsAsc.length === 0) {
return replaceSessionSnapshot(snapshot, {
historyPagination: { hasOlder: false },
});
}
const olderSnap = createEmptySessionSnapshot();
ingestSessionEventsIntoSnapshot(olderSnap, window.itemsAsc);
const existingIds = new Set(snapshot.turns.map(turn => turn.id));
const olderTurns = olderSnap.turns.filter(turn => !existingIds.has(turn.id));
const mergedFold = prependFoldState(olderSnap.fold, snapshot.fold);
const historyEvents = [...window.itemsAsc, ...(snapshot.historyEvents ?? [])];
const olderRootIds = olderTurns.flatMap(turn => turn.rootModelMessageIds ?? []);
// Forward-propagate sandbox identity revealed by older pages onto
// already-loaded newer turns that reused the sandbox without emitting
// sandbox.created. A turn's own sandboxId (a mid-session re-create) wins.
let knownSandboxId: string | undefined;
const mergedTurns = [...olderTurns, ...snapshot.turns].map(turn => {
if (turn.sandboxId != null) {
knownSandboxId = turn.sandboxId;
return turn;
}
if (knownSandboxId != null) {
return { ...turn, sandboxId: knownSandboxId };
}
return turn;
});
return replaceSessionSnapshot(snapshot, {
fold: mergedFold,
turns: mergedTurns,
historyEvents,
historyPagination: {
hasOlder: window.hasOlder,
...(window.olderPageToken != null ? { olderPageToken: window.olderPageToken } : {}),
},
...(snapshot.groupRootBaseline != null
? {
groupRootBaseline: [...olderRootIds, ...snapshot.groupRootBaseline],
}
: {}),
});
}
export interface ConvertTurnsResult {
messages: ThreadMessage[];
foldState: PeerThreadFoldState;
runningTurn?: Turn;
unstable_resume?: boolean;
}
function assistantStatusFromTurnState(state: Turn['state']): MessageStatus {
switch (state.status) {
case 'done':
return { type: 'complete', reason: 'stop' };
case 'error':
return { type: 'incomplete', reason: 'error', error: state.message };
case 'cancelled':
return { type: 'incomplete', reason: 'cancelled' };
case 'running':
return { type: 'running' };
default:
return { type: 'complete', reason: 'unknown' };
}
}
/**
* Cancelled-turn UI flow (chat + session detail share this projection):
*
* Example: turn.done { status: "cancelled", reason: "abandoned" } with no model
* text. Without special handling the chat would show only the user bubble.
*
* 1. Live SSE — streamTurnEvents yields status cancelled +
* metadata.cancellationReason = "abandoned" (no synthetic text part).
* 2. Commit — commitActiveStream reads that key, stores TurnStateCancelled on
* the turn record (not a fake "done"), then clears activeStream.
* 3. History / reload — projectHistoryTurns sees state.cancelled, puts the wire
* reason on metadata.custom, and always emits an assistant row even when the
* fold has no model.message parts. trueforge-ui renders the orange banner.
*
* assistant-ui MessageStatus only knows reason: "cancelled" (no wire reason),
* so the human-readable reason lives on metadata.custom.cancellationReason.
*/
/**
* Normal turns only get an assistant bubble when the model produced content.
* Cancelled/error turns still need a bubble so the banner/error chrome can show.
*/
function shouldEmitTerminalAssistant(state: Turn['state'], content: readonly AssistantContentPart[]): boolean {
return content.length > 0 || state.status === 'cancelled' || state.status === 'error';
}
function resolveCreatedAt(
messageId: string,
fallback: Date,
options?: ProjectSessionMessagesOptions,
replace = false,
): Date {
return options?.getCreatedAt?.(messageId, fallback, replace) ?? fallback;
}
function parseDataUriMime(data: string): string {
if (!data.startsWith('data:')) {
return 'application/octet-stream';
}
const match = /^data:([^;,]+)/.exec(data);
return match?.[1] ?? 'application/octet-stream';
}
function fileContentToAttachment(file: FileContent, attachmentId: string): CompleteAttachment {
const mimeType = parseDataUriMime(file.data);
if (mimeType.startsWith('image/')) {
return {
id: attachmentId,
type: 'image',
name: file.name,
contentType: mimeType,
status: { type: 'complete' },
content: [{ type: 'image', image: file.data, filename: file.name }],
};
}
return {
id: attachmentId,
type: 'file',
name: file.name,
contentType: mimeType,
status: { type: 'complete' },
content: [
{
type: 'file',
mimeType,
filename: file.name,
data: file.data,
},
],
};
}
/** Projects gateway turn input onto an assistant-ui user message (text + attachments). */
export function buildUserMessageFromTurnInput(
turnId: string,
input: Turn['input'],
createdAt: string | Date,
options?: ProjectSessionMessagesOptions,
): ThreadMessage {
const fallback = createdAt instanceof Date ? createdAt : new Date(createdAt);
const id = `${turnId}-user`;
const content: ThreadUserMessagePart[] = [];
const attachments: CompleteAttachment[] = [];
for (const item of input ?? []) {
if (item.type !== 'user.message') {
continue;
}
const messageContent = item.content;
if (typeof messageContent === 'string') {
content.push({ type: 'text', text: messageContent });
continue;
}
for (const part of messageContent) {
const imageUrl = extractImageUrlFromUserContentItem(part);
if (imageUrl != null) {
attachments.push(imageUrlToAttachment(imageUrl, `${turnId}-file-${String(attachments.length)}`));
continue;
}
if (part.type === 'text') {
content.push({ type: 'text', text: part.text });
} else {
attachments.push(fileContentToAttachment(part, `${turnId}-file-${String(attachments.length)}`));
}
}
}
return {
id,
role: 'user',
content: content.length > 0 ? content : [{ type: 'text', text: '' }],
attachments,
createdAt: resolveCreatedAt(id, fallback, options),
metadata: { custom: {} },
};
}
function buildAssistantMessage(
turnId: string,
content: AssistantContentPart[],
createdAt: string | Date,
status: MessageStatus,
custom: Record<string, unknown> = {},
options?: ProjectSessionMessagesOptions,
replaceCreatedAt = false,
): ThreadMessage {
const fallback = createdAt instanceof Date ? createdAt : new Date(createdAt);
const id = `${turnId}-assistant`;
return {
id,
role: 'assistant',
content,
status,
createdAt: resolveCreatedAt(id, fallback, options, replaceCreatedAt),
metadata: {
unstable_state: null,
unstable_annotations: [],
unstable_data: [],
steps: [],
custom,
},
};
}
async function ingestTurnEventsIntoFold(
server: AgentChatServer,
sessionId: string,
turnId: string,
foldState: PeerThreadFoldState,
): Promise<void> {
if (server.listTurnEvents == null) {
return;
}
const listTurnEvents = server.listTurnEvents.bind(server);
const events = await drainListPages(pageToken =>
listTurnEvents({
sessionId,
turnId,
order: 'asc',
limit: TURN_EVENTS_PAGE_SIZE,
...(pageToken != null ? { pageToken } : {}),
}),
);
for (const event of events) {
ingestTurnEvent(foldState, event);
}
}
async function fetchTurnEvents(server: AgentChatServer, sessionId: string, turnId: string): Promise<TurnEvent[]> {
if (server.listTurnEvents == null) {
return [];
}
const listTurnEvents = server.listTurnEvents.bind(server);
const events = await drainListPages(pageToken =>
listTurnEvents({
sessionId,
turnId,
order: 'asc',
limit: TURN_EVENTS_PAGE_SIZE,
...(pageToken != null ? { pageToken } : {}),
}),
);
return events;
}
function ingestCollectedEventsIntoFold(foldState: PeerThreadFoldState, events: TurnEvent[]): void {
for (const event of events) {
ingestTurnEvent(foldState, event);
}
}
async function fetchAllTurnEventsWithConcurrency(
server: AgentChatServer,
sessionId: string,
turns: Turn[],
concurrency: number,
): Promise<TurnEvent[][]> {
const results = Array.from({ length: turns.length }, (): TurnEvent[] => []);
const pool = new Set<Promise<void>>();
for (let i = 0; i < turns.length; i++) {
const idx = i;
const turn = turns[idx];
if (turn == null) {
continue;
}
const p: Promise<void> = fetchTurnEvents(server, sessionId, turn.id).then(events => {
results[idx] = events;
pool.delete(p);
});
pool.add(p);
if (pool.size >= concurrency) {
await Promise.race(pool);
}
}
await Promise.all(pool);
return results;
}
export function rootModelMessageIdsSinceBaseline(
foldState: PeerThreadFoldState,
baseline: readonly string[],
): string[] {
const bucket = foldState.threads.get(ROOT_THREAD_ID);
if (bucket == null) {
return [];
}
if (baseline.length === 0) {
return [...bucket.modelMessageIds];
}
const baselineSet = new Set(baseline);
return bucket.modelMessageIds.filter(id => !baselineSet.has(id));
}
export function computeGroupRootBaseline(turns: SessionTurnRecord[]): string[] {
let groupStartIndex = turns.length - 1;
while (groupStartIndex >= 0 && turns[groupStartIndex]?.userText == null) {
groupStartIndex--;
}
const baseline: string[] = [];
for (let i = 0; i < groupStartIndex; i++) {
baseline.push(...(turns[i]?.rootModelMessageIds ?? []));
}
return baseline;
}
function buildTurnUpdateFromFold(
foldState: PeerThreadFoldState,
turn: Pick<Turn, 'state'>,
rootModelMessageIds: readonly string[],
): TurnStreamUpdate {
// While we build this turn's messages, tell nested sub-agents that the parent
// already ended (cancelled/error) so they do not stay stuck as "running".
// Restore afterward so the flag does not leak into the next turn.
const previousParentTerminal = foldState.parentTerminalStatus;
if (turn.state.status === 'cancelled') {
foldState.parentTerminalStatus = 'cancelled';
} else if (turn.state.status === 'error') {
foldState.parentTerminalStatus = 'error';
} else {
foldState.parentTerminalStatus = undefined;
}
try {
const content = buildRootAssistantContentForIds(foldState, rootModelMessageIds);
let update: TurnStreamUpdate = { content };
update = appendMcpAuthToTurnContent(update.content, turn);
update = appendToolApprovalToTurnContent(update, turn);
return update;
} finally {
foldState.parentTerminalStatus = previousParentTerminal;
}
}
function contentHasPendingRequiredActions(content: readonly AssistantContentPart[]): boolean {
const message: ThreadMessage = {
id: 'pending-check',
role: 'assistant',
content,
status: { type: 'complete', reason: 'stop' },
createdAt: new Date(),
metadata: {
unstable_state: null,
unstable_annotations: [],
unstable_data: [],
steps: [],
custom: {},
},
};
return messageHasPendingApprovals(message) || messageHasPendingResponses(message);
}
function resolveProjectedRequiredActionState(
turnUpdate: TurnStreamUpdate,
content: readonly AssistantContentPart[],
record: Pick<Turn, 'state'>,
): { status: MessageStatus; custom: Record<string, unknown> } {
let status = turnUpdate.status ?? assistantStatusFromTurnState(record.state);
let custom = { ...(turnUpdate.metadata?.custom ?? {}) };
if (
status.type === 'requires-action' &&
status.reason === 'tool-calls' &&
!contentHasPendingRequiredActions(content)
) {
status = assistantStatusFromTurnState(record.state);
custom = Object.fromEntries(
Object.entries(custom).filter(
([key]) => key !== TOOL_APPROVAL_THREAD_ID_CUSTOM_KEY && key !== TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY,
),
);
}
return { status, custom };
}
function projectActiveStreamUpdate(snapshot: SessionSnapshot): TurnStreamUpdate {
const activeStream = snapshot.activeStream;
if (activeStream == null) {
throw new Error('projectActiveStreamUpdate requires an active stream');
}
const hasStagedOverlay =
snapshot.requiredActions.approvals.size > 0 || snapshot.requiredActions.toolResponses.size > 0;
// While the user has staged a response locally, keep the paused stream update
// so required-action collection can pair interrupt + result before resume.
if (hasStagedOverlay) {
return activeStream.update;
}
const baseline = snapshot.groupRootBaseline ?? computeGroupRootBaseline(snapshot.turns);
const rootModelMessageIds = rootModelMessageIdsSinceBaseline(snapshot.fold, baseline);
const foldContent = buildRootAssistantContentForIds(snapshot.fold, rootModelMessageIds);
const content = foldContent.length > 0 ? foldContent : activeStream.update.content;
const turnRecord = snapshot.turns.find(turn => turn.id === activeStream.turnId);
const turnLike = turnRecord ?? snapshot.runningTurn;
const rebuilt =
turnLike != null ? buildTurnUpdateFromFold(snapshot.fold, turnLike, rootModelMessageIds) : { content };
const metadata = rebuilt.metadata ?? activeStream.update.metadata;
const status = rebuilt.status ?? activeStream.update.status;
return {
...activeStream.update,
content,
...(metadata == null ? {} : { metadata }),
...(status == null ? {} : { status }),
};
}
function applyRequiredActionsOverlayToMessages(
messages: ThreadMessage[],
overlay: RequiredActionsOverlay,
): ThreadMessage[] {
if (overlay.approvals.size === 0 && overlay.toolResponses.size === 0) {
return messages;
}
return messages.map(message => {
if (message.role !== 'assistant') {
return message;
}
let { content } = message;
if (overlay.approvals.size > 0) {
content = applyApprovalDecisionsToContent(content, overlay.approvals);
}
if (overlay.toolResponses.size > 0) {
content = applyStagedResponsesToContent(content, overlay.toolResponses);
}
if (content === message.content) {
return message;
}
return { ...message, content: [...content] };
});
}
type ThreadAssistantMessagePart = Extract<ThreadMessage, { role: 'assistant' }>['content'][number];
type AssistantToolCallPart = Extract<ThreadAssistantMessagePart, { type: 'tool-call' }>;
function stripInteractivePendingFromContent(
content: readonly ThreadAssistantMessagePart[],
): ThreadAssistantMessagePart[] {
return content.map(part => {
if (part.type !== 'tool-call') {
return part;
}
let next: AssistantToolCallPart = part;
if (hasPendingToolResponse(part)) {
const { interrupt, ...rest } = part;
void interrupt;
next = rest;
}
const approval = next.approval;
if (approval != null && hasPendingToolApproval(approval)) {
next = {
...next,
approval: {
...approval,
approved: false,
reason: 'Superseded by a later message',
},
};
}
if (next.messages != null) {
const nested = next.messages.map(message => {
if (message.role !== 'assistant' || message.status.type !== 'requires-action') {
return message;
}
return stripInteractivePendingFromAssistant(message);
});
next = { ...next, messages: nested };
}
return next;
});
}
function stripInteractivePendingFromAssistant(
message: Extract<ThreadMessage, { role: 'assistant' }>,
): Extract<ThreadMessage, { role: 'assistant' }> {
const content = stripInteractivePendingFromContent(message.content);
const custom = Object.fromEntries(
Object.entries(message.metadata.custom).filter(
([key]) =>
key !== 'pendingMcpAuth' &&
key !== 'mcpServers' &&
key !== TOOL_APPROVAL_THREAD_ID_CUSTOM_KEY &&
key !== TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY,
),
);
return {
...message,
content,
status: { type: 'complete', reason: 'stop' },
metadata: {
...message.metadata,
custom,
},
};
}
/** Clear interactive pause chrome on assistants that a later user message abandoned. */
function abandonSupersededPausedMessages(messages: readonly ThreadMessage[]): ThreadMessage[] {
let lastUserIndex = -1;
for (let i = messages.length - 1; i >= 0; i--) {
if (messages[i]?.role === 'user') {
lastUserIndex = i;
break;
}
}
if (lastUserIndex < 0) {
return [...messages];
}
return messages.map((message, index) => {
if (index >= lastUserIndex) {
return message;
}
if (message.role !== 'assistant' || message.status.type !== 'requires-action') {
return message;
}
return stripInteractivePendingFromAssistant(message);
});
}
function projectHistoryTurns(snapshot: SessionSnapshot, options?: ProjectSessionMessagesOptions): ThreadMessage[] {
const messages: ThreadMessage[] = [];
let lastAssistantIndex: number | undefined;
let groupRootIds: string[] = [];
let sandboxId: string | undefined;
for (let turnIndex = 0; turnIndex < snapshot.turns.length; turnIndex++) {
const record = snapshot.turns[turnIndex];
if (record == null) {
continue;
}
const turnRootIds = record.rootModelMessageIds ?? [];
sandboxId = record.sandboxId ?? sandboxId;
if (record.userText !== undefined) {
groupRootIds = [...turnRootIds];
} else {
groupRootIds = [...groupRootIds, ...turnRootIds];
}
const turnUpdate = buildTurnUpdateFromFold(snapshot.fold, record, groupRootIds);
let content = turnUpdate.content;
const subsequentDecisions = collectSubsequentApprovalDecisions(snapshot.turns, turnIndex);
if (subsequentDecisions.size > 0) {
content = applyApprovalDecisionsToContent(content, subsequentDecisions);
}
const subsequentResponses = collectSubsequentToolResponses(snapshot.turns, turnIndex);
if (subsequentResponses.size > 0) {
content = applyStagedResponsesToContent(content, subsequentResponses);
}
const currentResponses = collectToolResponsesFromTurnInput(record.input);
if (currentResponses.size > 0) {
content = applyStagedResponsesToContent(content, currentResponses);
}
const currentDecisions = collectApprovalDecisionsFromTurnInput(record.input);
if (currentDecisions.size > 0) {
content = applyApprovalDecisionsToContent(content, currentDecisions);
}
const { status, custom: baseCustom } = resolveProjectedRequiredActionState(turnUpdate, content, record);
// Continuation turns fold into the previous assistant message and overwrite this custom,
// so a folded message reports the latest turn that contributed to it — the one whose
// sandbox wrote the newest artifacts.
const custom = {
...baseCustom,
turnId: record.id,
...(sandboxId != null ? { sandboxId } : {}),
...(record.state.status === 'cancelled' ? { [CANCELLATION_REASON_CUSTOM_KEY]: record.state.reason } : {}),
};
const assistantCreatedAt = record.state.status === 'running' ? record.createdAt : record.state.completedAt;
const replaceAssistantCreatedAt = record.state.status !== 'running';
if (record.userText !== undefined) {
messages.push(buildUserMessageFromTurnInput(record.id, record.input, record.createdAt, options));
if (record.state.status === 'running') {
if (content.length > 0) {
messages.push(
buildAssistantMessage(
record.id,
content,
assistantCreatedAt,
status,
custom,
options,
replaceAssistantCreatedAt,
),
);
}
break;
}
// Includes empty cancelled/error turns so the terminal state is visible.
if (shouldEmitTerminalAssistant(record.state, content)) {
messages.push(
buildAssistantMessage(
record.id,
content,
assistantCreatedAt,
status,
custom,
options,
replaceAssistantCreatedAt,
),
);
lastAssistantIndex = messages.length - 1;
} else {
// New user group with no assistant of its own — do not let a later empty
// cancelled/error continuation fold into a prior group's assistant.
lastAssistantIndex = undefined;
}
} else if (shouldEmitTerminalAssistant(record.state, content) && lastAssistantIndex != null) {
if (record.state.status === 'running') {
break;
}
const existing = messages[lastAssistantIndex];
if (existing?.role !== 'assistant') {
continue;
}
messages[lastAssistantIndex] = {
...existing,
content,
status,
createdAt: resolveCreatedAt(existing.id, new Date(assistantCreatedAt), options, true),
metadata: {
...existing.metadata,
custom,
},
};
} else if (record.state.status === 'running') {
break;
}
}
return messages;
}
export function projectSessionMessages(
snapshot: SessionSnapshot,
options?: ProjectSessionMessagesOptions,
): ThreadMessage[] {
let messages = projectHistoryTurns(snapshot, options);
if (snapshot.pendingUser != null) {
messages.push(
buildUserMessageFromTurnInput(
snapshot.pendingUser.turnId,
[{ type: 'user.message', content: snapshot.pendingUser.content }],
snapshot.pendingUser.createdAt,
options,
),
);
}
if (snapshot.activeStream != null) {
const { turnId, update, isContinuation, streamComplete } = snapshot.activeStream;
const resolvedUpdate = streamComplete === true ? projectActiveStreamUpdate(snapshot) : update;
const last = messages.at(-1);
const existingAssistant = isContinuation && last?.role === 'assistant' ? last : undefined;
let assistantMessage = turnStreamUpdateToAssistantMessage(turnId, resolvedUpdate, existingAssistant, options);
if (streamComplete === true && resolvedUpdate.status == null) {
assistantMessage = {
...assistantMessage,
status: { type: 'complete', reason: 'stop' },
};
}
// Update existing assistant message in-place if already present (for
// continuation turns where assistantMessage reuses last.id, or when a turn
// with zero root model messages was already projected by projectHistoryTurns).
// Otherwise, append assistantMessage to the thread.
const existingIndex = messages.findIndex(m => m.id === assistantMessage.id);
if (existingIndex !== -1) {
messages = [...messages.slice(0, existingIndex), assistantMessage, ...messages.slice(existingIndex + 1)];
} else {
messages = [...messages, assistantMessage];
}
}
return abandonSupersededPausedMessages(applyRequiredActionsOverlayToMessages(messages, snapshot.requiredActions));
}
const DEFAULT_LIST_EVENTS_CONCURRENCY = 5;
function ingestTurnsIntoSnapshot(
snapshot: SessionSnapshot,
turns: Turn[],
eventArrays: TurnEvent[][],
): Turn | undefined {
let runningTurn: Turn | undefined;
// Session-scoped: sandbox.created fires when a sandbox is (re)created and the
// sandbox is reused by later turns, so carry the latest one forward.
let sessionSandboxId: string | undefined;
for (let i = 0; i < turns.length; i++) {
const turn = turns[i];
if (turn == null) {
continue;
}
const rootBucket = snapshot.fold.threads.get(ROOT_THREAD_ID);
const beforeCount = rootBucket?.modelMessageIds.length ?? 0;
ingestCollectedEventsIntoFold(snapshot.fold, eventArrays[i] ?? []);
applyUserToolResponsesToFold(snapshot.fold, turn.input ?? []);
const afterBucket = snapshot.fold.threads.get(ROOT_THREAD_ID);
const rootModelMessageIds = (afterBucket?.modelMessageIds ?? []).slice(beforeCount);
const sandboxEvent = (eventArrays[i] ?? []).find(
(event): event is Extract<TurnEvent, { type: 'sandbox.created' }> => event.type === 'sandbox.created',
);
sessionSandboxId = sandboxEvent?.sandboxId ?? sessionSandboxId;
snapshot.turns.push({
...turnToSessionRecord(turn),
rootModelMessageIds,
...(sessionSandboxId != null ? { sandboxId: sessionSandboxId } : {}),
});
if (turn.state.status === 'running') {
runningTurn = turn;
break;
}
}
return runningTurn;
}
export async function buildSnapshotFromSession(
server: AgentChatServer,
sessionId: string,
concurrency: number = DEFAULT_LIST_EVENTS_CONCURRENCY,
): Promise<SessionSnapshot> {
// Completed history comes from session-level listEvents. The session API
// excludes the running turn — hydrate that turn via listTurnEvents so
// convertTurnsToThreadMessages still surfaces in-flight content.
const snapshot = await buildSnapshotFromSessionEvents(server, sessionId);
if (snapshot.runningTurn == null) {
return snapshot;
}
const turn = snapshot.runningTurn;
const eventArrays = await fetchAllTurnEventsWithConcurrency(server, sessionId, [turn], concurrency);
ingestTurnsIntoSnapshot(snapshot, [turn], eventArrays);
// Hydrated in-flight content lives in `turns` / `fold` now — drop the
// reconnect seed so projection does not duplicate the user bubble.
const snapshotWithoutPendingUser = { ...snapshot };
delete snapshotWithoutPendingUser.pendingUser;
return replaceSessionSnapshot(snapshotWithoutPendingUser, {
runningTurn: turn,
unstable_resume: true,
groupRootBaseline: computeGroupRootBaseline(snapshot.turns),
});
}
/**
* Rebuilds the conversation through `anchorTurnId`, including that turn.
* The server follows parent links from the anchor, so turns from abandoned
* branches are excluded. A null anchor represents an empty conversation.
*/
export async function buildSnapshotThroughTurn(
server: AgentChatServer,
sessionId: string,
anchorTurnId: string | null,
): Promise<SessionSnapshot> {
if (anchorTurnId == null) {
return createEmptySessionSnapshot();
}
const items = await fetchAllSessionEvents(server, sessionId, {
lastTurnId: anchorTurnId,
});
const snapshot = createEmptySessionSnapshot();
ingestSessionEventsIntoSnapshot(snapshot, items);
return snapshot;
}
/**
* Resolves `previousTurnId` for edit/retry of `turnId` from the turn's own
* parent pointer (`"none"` for roots). Independent of listTurns order.
*/
export async function resolveGatewayBranchPreviousTurnIdForTurn(
server: AgentChatServer,
sessionId: string,
turnId: string,
): Promise<string> {
const turn = await server.getTurn({ sessionId, turnId });
return turn.previousTurnId ?? 'none';
}
export async function buildTurnAssistantContent(
server: AgentChatServer,
sessionId: string,
turn: Pick<Turn, 'id' | 'state'>,
foldState?: PeerThreadFoldState,
): Promise<AssistantContentPart[]> {
const state = foldState ?? new PeerThreadFoldState();
const beforeCount = state.threads.get(ROOT_THREAD_ID)?.modelMessageIds.length ?? 0;
await ingestTurnEventsIntoFold(server, sessionId, turn.id, state);
const afterIds = state.threads.get(ROOT_THREAD_ID)?.modelMessageIds ?? [];
const rootModelMessageIds = afterIds.slice(beforeCount);
return buildTurnUpdateFromFold(state, turn, rootModelMessageIds).content;
}
export async function convertTurnsToThreadMessages(
server: AgentChatServer,
sessionId: string,
): Promise<ConvertTurnsResult> {
const snapshot = await buildSnapshotFromSession(server, sessionId);
const messages = projectSessionMessages(snapshot);
return {
messages,
foldState: snapshot.fold,
...(snapshot.runningTurn != null
? {
runningTurn: snapshot.runningTurn,
unstable_resume: true,
}
: {}),
};
}
export function getTurnMessageContent(message: AppendMessage): string {
const parts: string[] = [];
for (const part of message.content) {
if (part.type === 'text') {
parts.push(part.text);
}
}
const text = parts.join('\n').trim();
if (!text) {
throw new Error('User message must contain text content.');
}
return text;
}
/**
* Gateway `user.message` content (string for text-only, or text/file parts).
* Derived from SDK `TurnInputItem` so it tracks API changes.
*/
export type UserMessageContent = Extract<TurnInputItem, { type: 'user.message' }>['content'];
type UserMessageContentItem = Exclude<UserMessageContent, string>[number];
type FileContent = Extract<UserMessageContentItem, { type: 'file' }>;
type TextContent = Extract<UserMessageContentItem, { type: 'text' }>;
function toFileDataUri(data: string, mimeType: string): string {
// FileContent expects a data URI (`data:<mime>;base64,<payload>`).
// Attachment adapters typically already produce one via FileReader.readAsDataURL;
// only wrap bare base64 payloads.
if (data.startsWith('data:')) {
return data;
}
return `data:${mimeType};base64,${data}`;
}
function toFileContent(name: string, data: string, mimeType: string): FileContent {
return {
type: 'file',
name,
data: toFileDataUri(data, mimeType),
};
}
/**
* Builds the gateway turn input content from a composer message, forwarding
* attachments as SDK `FileContent` parts. Mirrors how assistant-ui surfaces
* attachment content on `message.attachments[].content`.
*/
export function buildUserMessageContent(message: AppendMessage): UserMessageContent {
const inputParts = [
...message.content,
...(message.attachments?.flatMap(attachment =>
attachment.content.map(part => ({
...part,
filename: attachment.name,
})),
) ?? []),
];
const items: UserMessageContentItem[] = [];
for (const part of inputParts) {
switch (part.type) {
case 'text':
if (part.text.trim().length > 0) {
const textPart: TextContent = { type: 'text', text: part.text };
items.push(textPart);
}
break;
case 'image':
items.push(toFileContent(part.filename ?? 'image', part.image, 'image/png'));
break;
case 'file':
items.push(toFileContent(part.filename ?? 'file', part.data, part.mimeType));
break;
default:
break;
}
}
const hasFile = items.some((item): item is FileContent => item.type === 'file');
if (!hasFile) {
// Text-only: keep the string form and the non-empty invariant.
return getTurnMessageContent(message);
}
return items;
}
/** Derives display text from gateway user-message content (drops file parts). */
export function userMessageContentToText(content: UserMessageContent): string {
if (typeof content === 'string') {
return content;
}
return content
.filter((item): item is TextContent => item.type === 'text')
.map(item => item.text)
.join('\n')
.trim();
}
/** Strips the `-user` suffix from a projected user message id to recover the turn id. */
export function parseTurnIdFromMessageId(messageId: string): string {
return messageId.replace(/-user$/, '');
}
/** Parent turn id for branching before `turnId`; `null` when editing the first turn. */
export function resolveBranchPreviousTurnId(turns: readonly SessionTurnRecord[], turnId: string): string | null {
const turnIndex = turns.findIndex(turn => turn.id === turnId);
if (turnIndex <= 0) {
return null;
}
return turns[turnIndex - 1]?.id ?? null;
}
/** Extracts edited text from an assistant-ui append message (text parts only). */
export function extractEditedText(message: AppendMessage): string {
return getTurnMessageContent(message);
}
/** Original gateway user-message content from a turn record (for reset). */
export function extractTurnUserMessageContent(input: TurnInputItem[] | undefined): UserMessageContent {
for (const item of input ?? []) {
if (item.type === 'user.message') {
return item.content;
}
}
return '';
}
/**
* Builds resubmit content for a text-only edit: replaces text with `editedText`
* while preserving original file parts from the turn record.
*/
export function buildEditedUserMessageContent(
editedText: string,
originalInput: TurnInputItem[] | undefined,
): UserMessageContent {
const fileParts: FileContent[] = [];
for (const item of originalInput ?? []) {
if (item.type !== 'user.message') {
continue;
}
const content = item.content;
if (typeof content === 'string') {
continue;
}
for (const part of content) {
if (part.type === 'file') {
fileParts.push(part);
}
}
}
if (fileParts.length === 0) {
return editedText;
}
const items: UserMessageContentItem[] = [];
if (editedText.trim().length > 0) {
items.push({ type: 'text', text: editedText });
}
items.push(...fileParts);
return items;
}
function buildMcpAuthUpdate(
pendingMcpAuth: McpAuthRequiredEvent,
foldState: PeerThreadFoldState,
groupRootBaseline?: readonly string[],
): TurnStreamUpdate {
const base =
groupRootBaseline != null
? buildRootAssistantContentForIds(foldState, rootModelMessageIdsSinceBaseline(foldState, groupRootBaseline))
: buildRootAssistantContent(foldState);
return {
content: [...base, ...buildMcpAuthTextParts()],
status: mcpAuthAssistantStatus(),
metadata: { custom: mcpAuthMessageCustom(pendingMcpAuth.mcpServers) },
};
}
/** Terminal `turn.done` with `status: error`. Not a transport drop — do not subscribe-retry. */
export class TurnFailedError extends Error {
constructor(message: string) {
super(message);
this.name = 'TurnFailedError';
}
}
/** SSE body ended without `turn.done` or a pause — subscribe-retry. */
export class TurnStreamDisconnectedError extends Error {
constructor(message = 'Turn stream closed before turn.done') {
super(message);
this.name = 'TurnStreamDisconnectedError';
}
}
export async function* streamTurnEvents(
stream: AsyncIterable<TurnStreamData>,
foldState: PeerThreadFoldState,
groupRootBaseline?: readonly string[],
onTurnIdAvailable?: (turnId: string) => void,
onSequenceNumber?: (sequenceNumber: number) => void,
): AsyncGenerator<TurnStreamUpdate> {
let pendingMcpAuth: McpAuthRequiredEvent | undefined;
let sandboxId: string | undefined;
let sandboxIdYielded = false;
let lastSequenceNumber: number | undefined;
let sawTurnDone = false;
const withCursor = (update: TurnStreamUpdate): TurnStreamUpdate => {
const withSeq = lastSequenceNumber == null ? update : { ...update, sequenceNumber: lastSequenceNumber };
if (sandboxId == null) {
return withSeq;
}
return {
...withSeq,
metadata: { ...withSeq.metadata, custom: { ...withSeq.metadata?.custom, sandboxId } },
};
};
const yieldContent = (): AssistantContentPart[] | undefined => {
const ids =
groupRootBaseline != null
? rootModelMessageIdsSinceBaseline(foldState, groupRootBaseline)
: (foldState.threads.get(ROOT_THREAD_ID)?.modelMessageIds ?? []);
const content = buildRootAssistantContentForIds(foldState, ids);
return content.length > 0 ? content : undefined;
};
for await (const data of stream) {
lastSequenceNumber = data.sequenceNumber;
onSequenceNumber?.(data.sequenceNumber);
const event = data.event;
if (event.type === 'turn.created') {
onTurnIdAvailable?.(event.turnId);
continue;
}
if (event.type === 'sandbox.created') {
sandboxId = event.sandboxId;
continue;
}
if (event.type === 'mcp.auth_required') {
pendingMcpAuth = event;
continue;
}
if (event.type === 'turn.done') {
if (event.state.status === 'error') {
throw new TurnFailedError(event.state.message);
}
// Live cancel: stash wire reason for commit + UI banner. Return so
// sandbox/MCP/approval post-loop yields cannot overwrite this update.
if (event.state.status === 'cancelled') {
const ids =
groupRootBaseline != null
? rootModelMessageIdsSinceBaseline(foldState, groupRootBaseline)
: (foldState.threads.get(ROOT_THREAD_ID)?.modelMessageIds ?? []);
// Same as history: mark parent cancelled so open sub-agents render cancelled too.
const previousParentTerminal = foldState.parentTerminalStatus;
foldState.parentTerminalStatus = 'cancelled';
try {
yield withCursor({
content: buildRootAssistantContentForIds(foldState, ids),
status: { type: 'incomplete', reason: 'cancelled' },
metadata: { custom: { [CANCELLATION_REASON_CUSTOM_KEY]: event.state.reason } },
});
} finally {
foldState.parentTerminalStatus = previousParentTerminal;
}
return;
}
// The turn is logically complete once `turn.done` is observed. The
// resumed-turn transport (`subscribeToTurn`) is a reconnectable live
// tail and is not guaranteed to close its SSE body right after this
// event, so we must stop consuming explicitly rather than waiting
// for the underlying stream to end — otherwise `isRunning` never
// clears and the composer's cancel/spinner button gets stuck.
sawTurnDone = true;
break;
}
if (!ingestStreamEvent(foldState, event)) {
continue;
}
const content = yieldContent();
if (content != null) {
if (sandboxId != null) {
sandboxIdYielded = true;
}
yield withCursor({ content });
}
}
if (pendingMcpAuth != null) {
yield withCursor(buildMcpAuthUpdate(pendingMcpAuth, foldState, groupRootBaseline));
return;
}
const approvalThreadId = findFirstPendingApprovalThreadId(foldState);
const responseThreadId = findFirstPendingResponseThreadId(foldState);
if (approvalThreadId != null || responseThreadId != null) {
const custom: Record<string, unknown> = {};
if (approvalThreadId != null) {
Object.assign(
custom,
toolApprovalMessageCustom(approvalThreadId === ROOT_THREAD_ID ? ROOT_THREAD_ID : approvalThreadId),
);
}
if (responseThreadId != null) {
Object.assign(
custom,
toolResponseMessageCustom(responseThreadId === ROOT_THREAD_ID ? ROOT_THREAD_ID : responseThreadId),
);
}
const ids =
groupRootBaseline != null
? rootModelMessageIdsSinceBaseline(foldState, groupRootBaseline)
: (foldState.threads.get(ROOT_THREAD_ID)?.modelMessageIds ?? []);
yield withCursor({
content: buildRootAssistantContentForIds(foldState, ids),
status: approvalThreadId != null ? toolApprovalStatus() : toolResponseStatus(),
metadata: { custom },
});
return;
}
if (sandboxId != null && !sandboxIdYielded) {
const ids =
groupRootBaseline != null
? rootModelMessageIdsSinceBaseline(foldState, groupRootBaseline)
: (foldState.threads.get(ROOT_THREAD_ID)?.modelMessageIds ?? []);
yield withCursor({ content: buildRootAssistantContentForIds(foldState, ids) });
}
if (!sawTurnDone) {
throw new TurnStreamDisconnectedError();
}
}
export function turnStreamUpdateToAssistantMessage(
turnId: string,
update: TurnStreamUpdate,
existing?: ThreadMessage,
options?: ProjectSessionMessagesOptions,
): ThreadMessage {
const id = existing?.role === 'assistant' ? existing.id : `${turnId}-assistant`;
const fallbackCreatedAt = existing?.createdAt ?? new Date();
return {
id,
role: 'assistant',
content: update.content,
status: update.status ?? { type: 'running' },
createdAt: resolveCreatedAt(id, fallbackCreatedAt, options),
metadata: {
unstable_state: null,
unstable_annotations: [],
unstable_data: [],
steps: [],
custom: {
...(existing?.role === 'assistant' ? existing.metadata.custom : {}),
...update.metadata?.custom,
turnId,
},
},
};
}
export function repositoryItemsFromMessages(messages: readonly ThreadMessage[]): ExportedMessageRepositoryItem[] {
const items: ExportedMessageRepositoryItem[] = [];
let parentId: string | null = null;
for (const message of messages) {
items.push({ parentId, message });
parentId = message.id;
}
return items;
}
export type { ProjectSessionMessagesOptions, SessionSnapshot } from './sessionSnapshot.js';