The open-source agent harness - the runtime layer that turns an LLM into a working agent.
'use client';
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import type {
McpAuthRequiredEvent,
ToolApprovalRequiredEvent,
ToolResponseRequiredEvent,
Turn,
TurnInputItem,
TurnStateCancelled,
TurnStateDone,
} from './server/index.js';
import type { AgentChatServer } from './server/types.js';
import { ROOT_THREAD_ID } from './constants.js';
import {
buildEditedUserMessageContent,
buildSnapshotThroughTurn,
CANCELLATION_REASON_CUSTOM_KEY,
computeGroupRootBaseline,
extractTurnUserMessageContent,
prependOlderSessionHistory,
projectSessionMessages,
resolveGatewayBranchPreviousTurnIdForTurn,
rootModelMessageIdsSinceBaseline,
TurnFailedError,
userMessageContentToText,
type UserMessageContent,
} from './convertTurnMessages.js';
import { extractTurnUserText } from './extractTurnUserText.js';
import { ingestTurnEvent } from './foldPeerThreads.js';
import { loadSessionSnapshot } from './loadSessionSnapshot.js';
import { MCP_AUTH_RESUME_RUN_CUSTOM_KEY } from './mcpAuth.js';
import { isMcpServerAuthInfoList } from './messageCustomMetadata.js';
import type { AssistantContentPart } from './modelMessageContent.js';
import {
collectRequiredActionInputs,
findCurrentPausedAssistantMessage,
messageHasPendingRequiredActions,
type RequiredActionInput,
} from './requiredActionInputs.js';
import {
createEmptySessionSnapshot,
replaceSessionSnapshot,
type SessionSnapshot,
type SessionTurnRecord,
} from './sessionSnapshot.js';
import { delayReconnect, isAbortError, STREAM_RECONNECT_MAX_ATTEMPTS } from './streamReconnect.js';
import { resumeTurnStream, streamTurnContent } from './streamTurn.js';
import { TOOL_APPROVAL_THREAD_ID_CUSTOM_KEY, type RespondToToolApprovalOptions } from './toolApproval.js';
import {
applyUserToolResponsesToFold,
TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY,
type RespondToToolResponseOptions,
} from './toolResponse.js';
import type { TurnStreamUpdate } from './turnStreamUpdate.js';
export interface UseTrueForgeAgentMessagesOptions {
server: AgentChatServer;
sessionId: string | undefined;
/** When true the thread is the currently selected (main) thread. */
isMain?: boolean | undefined;
/** URL-selected session may load before the thread list marks it as main. */
isInitialSession?: boolean | undefined;
onError?: ((error: unknown) => void) | undefined;
initializeSession?: () => Promise<{
remoteId: string;
externalId: string | undefined;
}>;
/** Maps a thread `remoteId` to the gateway session id used for turns. */
resolveConversationSessionId?: (remoteId: string) => Promise<string>;
/**
* Optional per-turn headers for createTurn. Invoked once per `sendTurn` after
* the session is resolved; return value is forwarded to `turn.execute`.
*/
getTurnHeaders?: () => Promise<Record<string, string> | undefined>;
}
export type SendTurnOptions =
| {
userMessage: UserMessageContent;
previousTurnId?: string | null;
/** Invoked only when the user turn fails before the gateway registers it. */
onPreTurnFailure?: () => void;
/**
* When branching (edit/reset), the already-rewound history to send from.
* Applied atomically with `pendingUser` so a stale React snapshot cannot
* keep pre-branch turns while the new user message is appended.
*/
branchFromSnapshot?: SessionSnapshot;
/** Original history restored when a branch fails before turn.created. */
branchRollbackSnapshot?: SessionSnapshot;
}
| { inputs: RequiredActionInput[] }
| { resumeMcpAuth: true };
function buildCompletedTurnState(
completedAt: string,
requiredActions: TurnStateDone['requiredActions'] = [],
): TurnStateDone {
return {
status: 'done',
requiredActions,
completedAt,
};
}
function buildCancelledTurnState({
completedAt,
reason = 'Superseded by a later message',
}: {
completedAt: string;
reason?: string;
}): TurnStateCancelled {
return {
status: 'cancelled',
reason,
completedAt,
};
}
/**
* Map the last stream update onto the turn record's terminal state.
* Prefer the wire cancellationReason from streamTurnEvents (e.g. "abandoned");
* otherwise treat a clean stream end as done.
*/
function committedStateFromActiveStream(
update: TurnStreamUpdate,
completedAt: string,
): TurnStateDone | TurnStateCancelled {
const cancelReason = update.metadata?.custom?.[CANCELLATION_REASON_CUSTOM_KEY];
const status = update.status;
if ((status?.type === 'incomplete' && status.reason === 'cancelled') || typeof cancelReason === 'string') {
return buildCancelledTurnState({
completedAt,
reason: typeof cancelReason === 'string' ? cancelReason : 'client-cancelled',
});
}
return buildCompletedTurnState(completedAt, requiredActionsFromActiveUpdate(update));
}
/**
* Custom stream adapters may yield projected content without fold events.
* Materialize that content so a cancelled commit still projects after
* `activeStream` is cleared for the next user turn.
*/
function materializeAbandonedStreamRootIds(options: {
fold: SessionSnapshot['fold'];
turnId: string;
content: readonly AssistantContentPart[];
existingRootIds: readonly string[];
}): string[] {
if (options.existingRootIds.length > 0) {
return [...options.existingRootIds];
}
if (options.content.length === 0) {
return [];
}
const text = options.content
.filter((part): part is Extract<AssistantContentPart, { type: 'text' }> => part.type === 'text')
.map(part => part.text)
.join('');
const toolCalls = options.content
.filter((part): part is Extract<AssistantContentPart, { type: 'tool-call' }> => part.type === 'tool-call')
.map(part => ({
id: part.toolCallId,
type: 'function' as const,
function: {
name: part.toolName,
arguments: part.argsText,
},
}));
const modelId = `client-abandoned-${options.turnId}`;
ingestTurnEvent(options.fold, {
type: 'model.message',
id: modelId,
threadId: ROOT_THREAD_ID,
createdAt: new Date().toISOString(),
content: text.length > 0 ? text : null,
...(toolCalls.length > 0 ? { toolCalls } : {}),
});
return [modelId];
}
/**
* Force-commits an in-flight client turn (optimistic user and/or incomplete
* stream) as cancelled so a superseding user send keeps that half-baked chat
* in history. Does not call cancelSession — the backend supersedes on its own.
*/
function abandonInFlightClientTurn(snapshot: SessionSnapshot): SessionSnapshot {
const active = snapshot.activeStream;
const hasIncompleteStream = active != null && active.streamComplete !== true;
const hasPendingUser = snapshot.pendingUser != null;
if (!hasIncompleteStream && !hasPendingUser) {
return snapshot;
}
const completedAt = new Date().toISOString();
const cancelledState = buildCancelledTurnState({ completedAt });
if (active != null && active.streamComplete !== true) {
const activeSandboxIdValue = active.update.metadata?.custom?.['sandboxId'];
const activeSandboxId = typeof activeSandboxIdValue === 'string' ? activeSandboxIdValue : undefined;
const baseline = snapshot.groupRootBaseline ?? computeGroupRootBaseline(snapshot.turns);
const rootModelMessageIds = materializeAbandonedStreamRootIds({
fold: snapshot.fold,
turnId: active.turnId,
content: active.update.content,
existingRootIds: rootModelMessageIdsSinceBaseline(snapshot.fold, baseline),
});
const lastTurn = snapshot.turns.at(-1);
if (lastTurn?.id === active.turnId) {
return replaceSessionSnapshot(snapshot, {
turns: snapshot.turns.map(turn =>
turn.id === active.turnId
? {
...turn,
state: cancelledState,
rootModelMessageIds,
...(activeSandboxId != null ? { sandboxId: activeSandboxId } : {}),
}
: turn,
),
pendingUser: undefined,
activeStream: undefined,
});
}
const record: SessionTurnRecord = {
id: active.turnId,
createdAt: snapshot.pendingUser?.createdAt.toISOString() ?? completedAt,
state: cancelledState,
input: snapshot.pendingUser ? [buildUserTurnInput(snapshot.pendingUser.content)] : [],
...(snapshot.pendingUser ? { userText: userMessageContentToText(snapshot.pendingUser.content) } : {}),
rootModelMessageIds,
...(activeSandboxId != null ? { sandboxId: activeSandboxId } : {}),
};
return replaceSessionSnapshot(snapshot, {
turns: [...snapshot.turns, record],
pendingUser: undefined,
activeStream: undefined,
});
}
const pending = snapshot.pendingUser;
if (pending == null) {
return snapshot;
}
const record: SessionTurnRecord = {
id: pending.turnId,
createdAt: pending.createdAt.toISOString(),
state: cancelledState,
input: [buildUserTurnInput(pending.content)],
userText: userMessageContentToText(pending.content),
rootModelMessageIds: [],
};
return replaceSessionSnapshot(snapshot, {
turns: [...snapshot.turns, record],
pendingUser: undefined,
activeStream: undefined,
});
}
/**
* Reconstructs the pending required actions a paused in-flight update carried,
* so the pause survives `commitActiveStream`'s synthetic "done" state.
*
* `commitActiveStream` fabricates a `TurnStateDone` for the just-finished
* stream, and the projection derives an assistant message's `requires-action`
* status from `turn.state.requiredActions` (see `findApprovalRequiredInTurn` /
* `findResponseRequiredInTurn` / `findMcpAuthRequired`). If we returned an empty
* list here, the committed turn would look "complete", the projected message
* would lose its `requires-action` status, and `findCurrentPausedAssistantMessage`
* (used by `trySendCollectedRequiredActions`) would never see it — so answering
* a tool approval or an `ask_user_question` would never send the resume turn.
*
* The paused update already carries the pause state: `status` is
* `requires-action` and `metadata.custom` holds the pending thread id(s) (and,
* for MCP, the server list). Only the thread id is read downstream, so an empty
* `toolCalls` list is sufficient here — the resume inputs are collected from the
* message content, not from these reconstructed actions.
*/
export function requiredActionsFromActiveUpdate(update: TurnStreamUpdate): TurnStateDone['requiredActions'] {
const custom = update.metadata?.custom;
const requiredActions: TurnStateDone['requiredActions'] = [];
const createdAt = new Date().toISOString();
if (custom?.['pendingMcpAuth'] === true && isMcpServerAuthInfoList(custom['mcpServers'])) {
const mcpAuthRequired: McpAuthRequiredEvent = {
type: 'mcp.auth_required',
id: crypto.randomUUID(),
createdAt,
mcpServers: custom['mcpServers'],
};
requiredActions.push(mcpAuthRequired);
}
if (update.status?.type === 'requires-action') {
const approvalThreadId = custom?.[TOOL_APPROVAL_THREAD_ID_CUSTOM_KEY];
if (typeof approvalThreadId === 'string') {
const approvalRequired: ToolApprovalRequiredEvent = {
type: 'tool.approval_required',
id: crypto.randomUUID(),
createdAt,
threadId: approvalThreadId,
toolCalls: [],
};
requiredActions.push(approvalRequired);
}
const responseThreadId = custom?.[TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY];
if (typeof responseThreadId === 'string') {
const responseRequired: ToolResponseRequiredEvent = {
type: 'tool.response_required',
id: crypto.randomUUID(),
createdAt,
threadId: responseThreadId,
toolCalls: [],
};
requiredActions.push(responseRequired);
}
}
return requiredActions;
}
function buildUserTurnInput(content: UserMessageContent): TurnInputItem {
return { type: 'user.message', content };
}
function appendTurnInputs(
base: TurnInputItem[] | undefined,
continuationInputs?: RequiredActionInput[],
): TurnInputItem[] {
const existingInputs = base ?? [];
if (continuationInputs == null || continuationInputs.length === 0) {
return existingInputs;
}
return [...existingInputs, ...continuationInputs];
}
function cancelScheduledAnimationFrame(frame: number | null): void {
if (frame != null) {
cancelAnimationFrame(frame);
}
}
function commitActiveStream(snapshot: SessionSnapshot, continuationInputs?: RequiredActionInput[]): SessionSnapshot {
const active = snapshot.activeStream;
if (active?.streamComplete !== true) {
return snapshot;
}
const activeSandboxIdValue = active.update.metadata?.custom?.['sandboxId'];
const activeSandboxId = typeof activeSandboxIdValue === 'string' ? activeSandboxIdValue : undefined;
const completedState = committedStateFromActiveStream(active.update, new Date().toISOString());
const baseline = snapshot.groupRootBaseline ?? computeGroupRootBaseline(snapshot.turns);
let rootModelMessageIds = rootModelMessageIdsSinceBaseline(snapshot.fold, baseline);
// Cancelled commits clear activeStream so history rebuilds from turn.state (banner).
// Custom adapters may have only update.content — materialize into the fold first
// so clearing activeStream does not drop streamed parts.
if (completedState.status === 'cancelled' && rootModelMessageIds.length === 0) {
rootModelMessageIds = materializeAbandonedStreamRootIds({
fold: snapshot.fold,
turnId: active.turnId,
content: active.update.content,
existingRootIds: rootModelMessageIds,
});
}
const clearActiveStream = rootModelMessageIds.length > 0 || completedState.status === 'cancelled';
const lastTurn = snapshot.turns.at(-1);
if (lastTurn?.id === active.turnId) {
return replaceSessionSnapshot(snapshot, {
turns: snapshot.turns.map(turn =>
turn.id === active.turnId
? {
...turn,
state: completedState,
input: appendTurnInputs(turn.input, continuationInputs),
rootModelMessageIds,
...(activeSandboxId != null ? { sandboxId: activeSandboxId } : {}),
}
: turn,
),
pendingUser: undefined,
// Non-cancel completes with an empty fold keep activeStream so custom adapters
// that only yielded update.content stay visible until the next stream.
...(clearActiveStream ? { activeStream: undefined } : {}),
});
}
const record: SessionTurnRecord = {
id: active.turnId,
createdAt: snapshot.pendingUser?.createdAt.toISOString() ?? new Date().toISOString(),
state: completedState,
input: appendTurnInputs(
snapshot.pendingUser ? [buildUserTurnInput(snapshot.pendingUser.content)] : [],
continuationInputs,
),
...(snapshot.pendingUser ? { userText: userMessageContentToText(snapshot.pendingUser.content) } : {}),
rootModelMessageIds,
...(activeSandboxId != null ? { sandboxId: activeSandboxId } : {}),
};
return replaceSessionSnapshot(snapshot, {
turns: [...snapshot.turns, record],
pendingUser: undefined,
...(clearActiveStream ? { activeStream: undefined } : {}),
});
}
/** Bounds the older-history page-ins a sandbox lookup may trigger. */
const MAX_SANDBOX_HISTORY_PAGE_INS = 20;
/**
* sandboxId in effect as of `turnId`. An artifact can only come from a sandbox
* created at or before its own turn, so scan records backward from that turn;
* an unknown turn (e.g. projected only from the active stream) scans the whole
* loaded window.
*/
function findSandboxIdInSnapshot(snapshot: SessionSnapshot, turnId: string): string | undefined {
const active = snapshot.activeStream;
if (active?.turnId === turnId) {
const sandboxId = active.update.metadata?.custom?.['sandboxId'];
if (typeof sandboxId === 'string') {
return sandboxId;
}
}
const turns = snapshot.turns;
const turnIndex = turns.findIndex(turn => turn.id === turnId);
for (let i = turnIndex === -1 ? turns.length - 1 : turnIndex; i >= 0; i--) {
const sandboxId = turns[i]?.sandboxId;
if (sandboxId != null) {
return sandboxId;
}
}
return undefined;
}
async function resolveActiveSessionId(
remoteId: string,
resolveConversationSessionId?: (remoteId: string) => Promise<string>,
): Promise<string> {
if (resolveConversationSessionId != null) {
return resolveConversationSessionId(remoteId);
}
return remoteId;
}
function resolveTurnInput(snapshot: SessionSnapshot, turnId: string): TurnInputItem[] | undefined {
const turnRecord = snapshot.turns.find(turn => turn.id === turnId);
if (turnRecord?.input != null) {
return turnRecord.input;
}
if (snapshot.pendingUser?.turnId === turnId) {
return [{ type: 'user.message', content: snapshot.pendingUser.content }];
}
return undefined;
}
interface StreamSequenceTrack {
onSequenceNumber: (sequenceNumber: number) => void;
}
interface RunStreamReconnect {
sessionId: string;
gatewayTurnAccepted: { current: boolean };
}
export function useTrueForgeAgentMessages({
server,
sessionId,
isMain,
isInitialSession,
onError,
initializeSession,
resolveConversationSessionId,
getTurnHeaders,
}: UseTrueForgeAgentMessagesOptions) {
const [snapshot, setSnapshot] = useState<SessionSnapshot>(createEmptySessionSnapshot);
const [isRunning, setIsRunning] = useState(false);
// Existing sessions have history pending from the first render. Starting at
// false causes consumers to briefly render an empty thread before the load
// effect runs and flips this flag to true.
const [isLoading, setIsLoading] = useState(sessionId != null && (isMain !== false || isInitialSession === true));
const [isLoadingOlderHistory, setIsLoadingOlderHistory] = useState(false);
const [loadRetryTrigger, setLoadRetryTrigger] = useState(0);
const [resumeUnavailable, setResumeUnavailable] = useState(false);
const snapshotRef = useRef(snapshot);
snapshotRef.current = snapshot;
// Live session id — stale loadOlderHistory / resolveSandboxIdForTurn
// closures compare against this so a post-switch iteration cannot merge
// session A's pages onto session B's snapshot (generation alone is not
// enough: a late call captures B's generation while still closed over A).
const sessionIdRef = useRef(sessionId);
sessionIdRef.current = sessionId;
const loadOlderInflightRef = useRef<Promise<void> | null>(null);
const onErrorRef = useRef(onError);
onErrorRef.current = onError;
const resolveConversationSessionIdRef = useRef(resolveConversationSessionId);
resolveConversationSessionIdRef.current = resolveConversationSessionId;
const initializeSessionRef = useRef(initializeSession);
initializeSessionRef.current = initializeSession;
const getTurnHeadersRef = useRef(getTurnHeaders);
getTurnHeadersRef.current = getTurnHeaders;
const createdAtByMessageIdRef = useRef(new Map<string, Date>());
const abortControllerRef = useRef<AbortController | null>(null);
const activeRunRef = useRef<Promise<void> | null>(null);
// Mirrors `resumeUnavailable` for `cancel`, which reads it outside render.
const resumeUnavailableRef = useRef(false);
const runningTurnRef = useRef<Turn | undefined>(undefined);
const loadGenerationRef = useRef(0);
const streamGenerationRef = useRef(0);
// Bumped once a send has applied its message. An earlier failure must not
// discard the in-flight load or cancel the painted tip.
const sendEpochRef = useRef(0);
const streamReconnectPendingRef = useRef(false);
const cancelRequestedRef = useRef(false);
const lazilyCreatedSessionIdRef = useRef<string | undefined>(undefined);
const initialLoadStartedForRef = useRef<string | undefined>(undefined);
const skipInitialPromotionLoadForRef = useRef<string | undefined>(undefined);
/**
* A turn is running that this server cannot stream. Nothing will deliver its
* result to this client, so the UI shows a waiting state until the run is
* cancelled or the session is reloaded.
*/
const markResumeUnavailable = useCallback((value: boolean) => {
resumeUnavailableRef.current = value;
setResumeUnavailable(value);
}, []);
const projectOptions = useMemo(
() => ({
getCreatedAt: (messageId: string, fallback: Date, replace = false) => {
const cache = createdAtByMessageIdRef.current;
const existing = cache.get(messageId);
if (existing != null && (!replace || existing.getTime() === fallback.getTime())) {
return existing;
}
cache.set(messageId, fallback);
return fallback;
},
}),
[],
);
const messages = useMemo(() => projectSessionMessages(snapshot, projectOptions), [snapshot, projectOptions]);
const runStream = useCallback(
(
createStream: (signal: AbortSignal, track: StreamSequenceTrack) => AsyncGenerator<TurnStreamUpdate>,
/**
* A mutable ref whose `.current` is the turn ID to use for
* `activeStream.turnId`. Callers that capture the gateway turn ID
* via `onTurnIdAvailable` update this ref in-place so that both the
* pending-update flush and `commitActiveStream` always see the real
* gateway ID rather than the locally-generated optimistic one.
*/
turnIdRef: { current: string },
isContinuation: boolean,
reconnect: RunStreamReconnect,
): Promise<void> => {
const streamGeneration = ++streamGenerationRef.current;
abortControllerRef.current?.abort();
const abortController = new AbortController();
abortControllerRef.current = abortController;
cancelRequestedRef.current = false;
setIsRunning(true);
// This stream's `finally` owns the running flag from here on.
markResumeUnavailable(false);
const run = (async () => {
// Sub-agent turns can emit 100+ stream events per frame. Coalesce to one
// setSnapshot per animation frame so assistant-ui does not remount the whole
// message tree (UI hang). The buffer belongs to this stream only.
let pendingStreamUpdate: {
update: TurnStreamUpdate;
isContinuation: boolean;
} | null = null;
let streamUpdateRaf: number | null = null;
const lastSequenceNumberRef: { current: number | undefined } = {
current: snapshotRef.current.activeStream?.lastSequenceNumber,
};
let useSubscribe = false;
let consecutiveFailures = 0;
const track: StreamSequenceTrack = {
onSequenceNumber: sequenceNumber => {
lastSequenceNumberRef.current = sequenceNumber;
consecutiveFailures = 0;
},
};
const flushPendingStreamUpdate = () => {
streamUpdateRaf = null;
const pending = pendingStreamUpdate;
pendingStreamUpdate = null;
if (pending == null || streamGeneration !== streamGenerationRef.current) {
return;
}
const { update, isContinuation: pendingIsContinuation } = pending;
setSnapshot(prev =>
replaceSessionSnapshot(prev, {
activeStream: {
// Read from the ref so we always use the latest ID,
// including any gateway ID that arrived after the RAf
// was scheduled.
turnId: turnIdRef.current,
update,
isContinuation: pendingIsContinuation,
...(lastSequenceNumberRef.current != null ? { lastSequenceNumber: lastSequenceNumberRef.current } : {}),
},
}),
);
};
const applyStreamUpdate = (update: TurnStreamUpdate) => {
if (update.sequenceNumber != null) {
lastSequenceNumberRef.current = update.sequenceNumber;
consecutiveFailures = 0;
}
pendingStreamUpdate = { update, isContinuation };
streamUpdateRaf ??= requestAnimationFrame(flushPendingStreamUpdate);
};
const readStream = (signal: AbortSignal): AsyncGenerator<TurnStreamUpdate> => {
if (!useSubscribe) {
return createStream(signal, track);
}
return resumeTurnStream(
server,
reconnect.sessionId,
turnIdRef.current,
snapshotRef.current.fold,
signal,
lastSequenceNumberRef.current,
snapshotRef.current.groupRootBaseline,
track.onSequenceNumber,
);
};
try {
while (streamGeneration === streamGenerationRef.current) {
try {
for await (const update of readStream(abortController.signal)) {
if (streamGeneration !== streamGenerationRef.current) {
return;
}
applyStreamUpdate(update);
}
return;
} catch (error) {
if (isAbortError(error) || streamGeneration !== streamGenerationRef.current) {
return;
}
// Cancel keeps consuming a healthy live SSE for turn.done. A
// drop after cancelSession must not start subscribe-retry.
if (cancelRequestedRef.current) {
abortController.abort();
return;
}
const canSubscribe =
server.subscribeToTurn != null &&
reconnect.gatewayTurnAccepted.current &&
!(error instanceof TurnFailedError);
if (!canSubscribe || consecutiveFailures >= STREAM_RECONNECT_MAX_ATTEMPTS) {
onErrorRef.current?.(error);
throw error;
}
consecutiveFailures += 1;
useSubscribe = true;
// Stay pending through delay and the subscribe attempt so
// cancel aborts a reconnect SSE, not only the wait.
streamReconnectPendingRef.current = true;
try {
await delayReconnect(abortController.signal);
} catch (error) {
if (isAbortError(error) || streamGeneration !== streamGenerationRef.current) {
return;
}
throw error;
}
}
}
} finally {
streamReconnectPendingRef.current = false;
cancelScheduledAnimationFrame(streamUpdateRaf);
if (streamGeneration === streamGenerationRef.current) {
flushPendingStreamUpdate();
if (abortControllerRef.current === abortController) {
abortControllerRef.current = null;
}
setIsRunning(false);
if (abortController.signal.aborted) {
setSnapshot(prev => abandonInFlightClientTurn(prev));
} else {
setSnapshot(prev => {
if (prev.activeStream == null) {
return prev;
}
const marked = replaceSessionSnapshot(prev, {
activeStream: {
...prev.activeStream,
streamComplete: true,
...(lastSequenceNumberRef.current != null
? { lastSequenceNumber: lastSequenceNumberRef.current }
: {}),
},
requiredActions: {
approvals: new Map(),
toolResponses: new Map(),
},
});
return commitActiveStream(marked);
});
}
}
}
})();
activeRunRef.current = run;
void run
.catch(() => undefined)
.finally(() => {
if (activeRunRef.current === run) {
activeRunRef.current = null;
setIsRunning(false);
}
});
return run;
},
[markResumeUnavailable, server],
);
const load = useCallback(async () => {
// Reading the retry counter intentionally makes retryLoad recreate this callback.
void loadRetryTrigger;
if (sessionId == null) {
createdAtByMessageIdRef.current = new Map();
setSnapshot(createEmptySessionSnapshot());
return;
}
// Allow the URL-selected session one early load before assistant-ui marks
// it main. Suppress only that first promotion; later selections still reload.
const isEarlyInitialLoad =
isMain === false && isInitialSession === true && initialLoadStartedForRef.current !== sessionId;
if (isMain === false) {
if (!isEarlyInitialLoad) {
return;
}
initialLoadStartedForRef.current = sessionId;
skipInitialPromotionLoadForRef.current = sessionId;
} else if (isMain === true && skipInitialPromotionLoadForRef.current === sessionId) {
skipInitialPromotionLoadForRef.current = undefined;
return;
}
if (isInitialSession === true) {
initialLoadStartedForRef.current = sessionId;
}
// When we are loading a *different* session the user has navigated away
// from the lazily-created one — clear the guard so navigating back to it
// later triggers a proper reload instead of silently skipping.
if (lazilyCreatedSessionIdRef.current != null && sessionId !== lazilyCreatedSessionIdRef.current) {
lazilyCreatedSessionIdRef.current = undefined;
}
if (sessionId === lazilyCreatedSessionIdRef.current) {
return;
}
const generation = ++loadGenerationRef.current;
++streamGenerationRef.current;
const sendEpoch = sendEpochRef.current;
setIsRunning(false);
markResumeUnavailable(false);
abortControllerRef.current?.abort();
loadOlderInflightRef.current = null;
createdAtByMessageIdRef.current = new Map();
setSnapshot(createEmptySessionSnapshot());
setIsLoading(true);
setIsLoadingOlderHistory(false);
try {
const conversationSessionId = await resolveActiveSessionId(sessionId, resolveConversationSessionIdRef.current);
const loadedSnapshot = await loadSessionSnapshot(server, conversationSessionId, snap => {
if (generation !== loadGenerationRef.current) {
return;
}
// The events window is paintable before getTurn confirms the tip.
setSnapshot(snap);
setIsLoading(false);
});
if (generation !== loadGenerationRef.current || sendEpoch !== sendEpochRef.current) {
// A send applied its message while getTurn was in flight. Applying this
// snapshot would drop that message and resume the old tip.
return;
}
createdAtByMessageIdRef.current = new Map();
setSnapshot(loadedSnapshot);
runningTurnRef.current = loadedSnapshot.runningTurn;
// History (and any seeded pendingUser for the in-flight turn) is
// ready — clear loading before resuming. Awaiting the subscribe
// stream here previously kept isLoading true for the entire
// backend run, so reconnect UIs stayed on shimmers even though
// subscribe was already live.
setIsLoading(false);
if (loadedSnapshot.runningTurn != null) {
const turn = loadedSnapshot.runningTurn;
// subscribeToTurn is optional, so a server can leave us without
// a reconnect path. The turn still runs on the backend: show the
// loaded history as running and let the host explain the gap.
if (server.subscribeToTurn == null) {
setIsRunning(true);
markResumeUnavailable(true);
return;
}
const isContinuation = extractTurnUserText(turn.input) === undefined;
// Use loadedSnapshot directly — snapshotRef.current still points at
// the empty snapshot cleared above until the setSnapshot(loadedSnapshot)
// call re-renders.
void runStream(
(signal, track) =>
resumeTurnStream(
server,
conversationSessionId,
turn.id,
loadedSnapshot.fold,
signal,
loadedSnapshot.activeStream?.lastSequenceNumber,
loadedSnapshot.groupRootBaseline,
track.onSequenceNumber,
),
{ current: turn.id },
isContinuation,
{ sessionId: conversationSessionId, gatewayTurnAccepted: { current: true } },
).catch(() => undefined);
}
} catch (error) {
if (generation === loadGenerationRef.current) {
if (isEarlyInitialLoad) {
// Allow retryLoad while still backgrounded (before isMain promotion).
initialLoadStartedForRef.current = undefined;
skipInitialPromotionLoadForRef.current = undefined;
}
onErrorRef.current?.(error);
}
throw error;
} finally {
if (generation === loadGenerationRef.current) {
setIsLoading(false);
}
}
}, [server, runStream, sessionId, loadRetryTrigger, isMain, isInitialSession]);
useEffect(() => {
void load().catch(() => undefined);
}, [load]);
const sendTurn = useCallback(
async (options: SendTurnOptions) => {
// A turn.created event means the gateway registered the user message.
// Errors after that point must keep the message in chat.
const gatewayTurnAccepted = { current: false };
let pendingUserWasSet = false;
let runStreamStarted = false;
let pendingUserTurnId: string | undefined;
// Invalidate the prior client stream before any await so a buffered RAF
// cannot restore stale activeStream after the optimistic user message.
// Continuations keep today's runStream abort; they must not race a user send.
const sendGeneration = 'userMessage' in options ? ++streamGenerationRef.current : streamGenerationRef.current;
if ('userMessage' in options) {
abortControllerRef.current?.abort();
}
try {
let activeSessionId = sessionId;
if (activeSessionId == null) {
if (initializeSessionRef.current == null) {
throw new Error('Cannot send a turn without an active session.');
}
const { remoteId } = await initializeSessionRef.current();
activeSessionId = remoteId;
lazilyCreatedSessionIdRef.current = remoteId;
}
const conversationSessionId = await resolveActiveSessionId(
activeSessionId,
resolveConversationSessionIdRef.current,
);
const turnHeaders = await getTurnHeadersRef.current?.();
if (sendGeneration !== streamGenerationRef.current) {
return;
}
const streamHeaders = turnHeaders != null ? { headers: turnHeaders } : {};
const isContinuation = 'inputs' in options || ('resumeMcpAuth' in options && options.resumeMcpAuth);
const continuationTurnId = snapshotRef.current.activeStream?.turnId;
const turnId = isContinuation
? // A paused stream is usually already committed (commitActiveStream
// cleared activeStream), so continue under the committed turn's
// real id. Never mint a local id for a continuation — it leaks to
// the backend via `custom.turnId` (sandbox downloads, edit/retry)
// as a turn the gateway has never heard of.
(continuationTurnId ?? snapshotRef.current.turns.at(-1)?.id ?? crypto.randomUUID())
: crypto.randomUUID();
// First turns must send previousTurnId: "none".
const isFirstTurnInSession =
'userMessage' in options &&
options.previousTurnId === undefined &&
snapshotRef.current.turns.length === 0 &&
snapshotRef.current.pendingUser == null &&
snapshotRef.current.activeStream == null;
// Mutable ref so runStream always reads the latest ID. The local
// placeholder (optimistic `generateId()` or the previous turn's id
// for continuations) is replaced with the gateway-assigned ID once
// the first SSE event arrives.
const turnIdRef = { current: turnId };
// Renames the placeholder ID to the gateway turn ID so that
// edit/retry and sandbox downloads can resolve the turn via the
// gateway. Wired into every stream branch — continuation turns
// (approval / ask-user / MCP-auth resumes) are new gateway turns
// too, and committing them under a local id corrupts the record.
const handleGatewayTurnId = (gatewayTurnId: string) => {
const oldId = turnIdRef.current;
// turn.created proves the gateway registered the message.
gatewayTurnAccepted.current = true;
if (gatewayTurnId === oldId) {
return;
}
turnIdRef.current = gatewayTurnId;
// Rename in the ref immediately so any synchronous read
// (e.g. commitActiveStream) sees the correct ID.
const renamePendingUser = (prev: SessionSnapshot): SessionSnapshot => {
if (prev.pendingUser?.turnId !== oldId) {
return prev;
}
return replaceSessionSnapshot(prev, {
pendingUser: {
...prev.pendingUser,
turnId: gatewayTurnId,
},
});
};
snapshotRef.current = renamePendingUser(snapshotRef.current);
setSnapshot(renamePendingUser);
};
if ('inputs' in options) {
applyUserToolResponsesToFold(snapshotRef.current.fold, options.inputs);
}
const branchBase = 'userMessage' in options ? options.branchFromSnapshot : undefined;
let groupRootBaseline: readonly string[] | undefined;
if (branchBase != null && 'userMessage' in options) {
// Atomic apply: never merge pendingUser onto a stale React `prev`
// that still holds pre-branch turns (edit would show old + new).
// Commit any completed stream, then abandon incomplete in-flight chat
// into history before the new optimistic user message.
const abandoned = abandonInFlightClientTurn(commitActiveStream(branchBase));
const rootBucket = abandoned.fold.threads.get(ROOT_THREAD_ID);
groupRootBaseline = [...(rootBucket?.modelMessageIds ?? [])];
const nextSnapshot = replaceSessionSnapshot(abandoned, {
pendingUser: {
turnId,
content: options.userMessage,
createdAt: new Date(),
},
activeStream: undefined,
groupRootBaseline,
requiredActions: {
approvals: new Map(),
toolResponses: new Map(),
},
});
snapshotRef.current = nextSnapshot;
setSnapshot(nextSnapshot);
pendingUserWasSet = true;
pendingUserTurnId = turnId;
} else if ('userMessage' in options) {
// Sync from snapshotRef so groupRootBaseline is set before runStream
// (setState updaters after await are not guaranteed to flush first).
const abandoned = abandonInFlightClientTurn(commitActiveStream(snapshotRef.current));
const rootBucket = abandoned.fold.threads.get(ROOT_THREAD_ID);
groupRootBaseline = [...(rootBucket?.modelMessageIds ?? [])];
const next = replaceSessionSnapshot(abandoned, {
pendingUser: {
turnId,
content: options.userMessage,
createdAt: new Date(),
},
activeStream: undefined,
groupRootBaseline,
// Drop staged pause answers so they cannot resume behind this turn.
requiredActions: {
approvals: new Map(),
toolResponses: new Map(),
},
});
snapshotRef.current = next;
setSnapshot(next);
pendingUserWasSet = true;
pendingUserTurnId = turnId;
} else {
setSnapshot(prev => commitActiveStream(prev, 'inputs' in options ? options.inputs : undefined));
groupRootBaseline =
snapshotRef.current.groupRootBaseline ?? computeGroupRootBaseline(snapshotRef.current.turns);
}
// The message is on the snapshot. A load still awaiting getTurn must
// leave this send in place. Failures before this point do not count.
++sendEpochRef.current;
runStreamStarted = true;
await runStream(
(signal, track) => {
if ('inputs' in options) {
return streamTurnContent(
server,
conversationSessionId,
snapshotRef.current.fold,
{ inputs: options.inputs, ...streamHeaders },
signal,
groupRootBaseline,
handleGatewayTurnId,
track.onSequenceNumber,
);
}
if ('resumeMcpAuth' in options) {
return streamTurnContent(
server,
conversationSessionId,
snapshotRef.current.fold,
{ resumeMcpAuth: true, ...streamHeaders },
signal,
groupRootBaseline,
handleGatewayTurnId,
track.onSequenceNumber,
);
}
return streamTurnContent(
server,
conversationSessionId,
snapshotRef.current.fold,
{
userMessage: options.userMessage,
...(options.previousTurnId !== undefined
? { previousTurnId: options.previousTurnId ?? 'none' }
: isFirstTurnInSession
? { previousTurnId: 'none' }
: {}),
...streamHeaders,
},
signal,
groupRootBaseline,
handleGatewayTurnId,
track.onSequenceNumber,
);
},
turnIdRef,
isContinuation,
{ sessionId: conversationSessionId, gatewayTurnAccepted },
);
} catch (error) {
if (!runStreamStarted && sendGeneration !== streamGenerationRef.current) {
return;
}
if ('userMessage' in options && !gatewayTurnAccepted.current) {
const branchRollbackSnapshot = options.branchRollbackSnapshot;
const canRestoreBranch =
branchRollbackSnapshot != null &&
(snapshotRef.current === options.branchFromSnapshot ||
snapshotRef.current.pendingUser?.turnId === pendingUserTurnId);
if (canRestoreBranch) {
snapshotRef.current = branchRollbackSnapshot;
setSnapshot(branchRollbackSnapshot);
} else if (pendingUserWasSet) {
const clearPendingUser = (previous: SessionSnapshot): SessionSnapshot => {
if (previous.pendingUser?.turnId !== pendingUserTurnId) {
return previous;
}
return replaceSessionSnapshot(previous, {
pendingUser: undefined,
});
};
snapshotRef.current = clearPendingUser(snapshotRef.current);
setSnapshot(clearPendingUser);
}
options.onPreTurnFailure?.();
}
if (!runStreamStarted) {
// A supersede already aborted the live stream. A send that fails
// before it installs a message must not cancel the painted open tip.
const hasIncompleteStream =
snapshotRef.current.activeStream != null && snapshotRef.current.activeStream.streamComplete !== true;
if ('userMessage' in options && (pendingUserWasSet || hasIncompleteStream)) {
const abandoned = abandonInFlightClientTurn(commitActiveStream(snapshotRef.current));
snapshotRef.current = abandoned;
setSnapshot(abandoned);
}
if (abortControllerRef.current?.signal.aborted) {
abortControllerRef.current = null;
}
setIsRunning(false);
onErrorRef.current?.(error);
}
throw error;
}
},
[server, runStream, sessionId],
);
const cancel = useCallback(async () => {
// A turn can start before the thread list publishes `remoteId`, and that
// run still has a backend session to stop.
const activeSessionId = sessionId ?? lazilyCreatedSessionIdRef.current;
if (activeSessionId == null) {
abortControllerRef.current?.abort();
return;
}
cancelRequestedRef.current = true;
const conversationSessionId = await resolveActiveSessionId(
activeSessionId,
resolveConversationSessionIdRef.current,
);
// Drain a healthy live SSE for cancelled turn.done. Abort reconnect
// waits and reconnect subscribe so cancel cannot start or keep a new
// subscribe after the live stream dropped.
if (streamReconnectPendingRef.current) {
abortControllerRef.current?.abort();
}
await server.cancelSession({ sessionId: conversationSessionId }).catch(() => undefined);
await activeRunRef.current?.catch(() => undefined);
markResumeUnavailable(false);
setIsRunning(false);
}, [server, sessionId, markResumeUnavailable]);
const isRunningRef = useRef(isRunning);
isRunningRef.current = isRunning;
const trySendCollectedRequiredActions = useCallback(
(nextSnapshot: SessionSnapshot) => {
if (isRunningRef.current) {
return;
}
const projected = projectSessionMessages(nextSnapshot, projectOptions);
const paused = findCurrentPausedAssistantMessage(projected);
if (paused == null || messageHasPendingRequiredActions(paused)) {
return;
}
const inputs = collectRequiredActionInputs(paused);
if (inputs.length > 0) {
// sendTurn/runStream already report via onError; swallow to avoid duplicates.
void sendTurn({ inputs }).catch(() => undefined);
}
},
[projectOptions, sendTurn],
);
const respondToToolApproval = useCallback(
(response: RespondToToolApprovalOptions) => {
const prev = snapshotRef.current;
const approvals = new Map(prev.requiredActions.approvals);
approvals.set(response.approvalId, {
approved: response.approved,
...(response.reason != null ? { reason: response.reason } : {}),
});
const nextSnapshot = replaceSessionSnapshot(prev, {
requiredActions: {
...prev.requiredActions,
approvals,
},
});
setSnapshot(nextSnapshot);
trySendCollectedRequiredActions(nextSnapshot);
},
[trySendCollectedRequiredActions],
);
const respondToToolResponse = useCallback(
(response: RespondToToolResponseOptions) => {
const prev = snapshotRef.current;
const toolResponses = new Map(prev.requiredActions.toolResponses);
toolResponses.set(response.toolCallId, { content: response.content });
const nextSnapshot = replaceSessionSnapshot(prev, {
requiredActions: {
...prev.requiredActions,
toolResponses,
},
});
setSnapshot(nextSnapshot);
trySendCollectedRequiredActions(nextSnapshot);
},
[trySendCollectedRequiredActions],
);
const resumeRun = useCallback(async () => {
const turn = runningTurnRef.current;
if (turn == null) {
return;
}
if (server.subscribeToTurn == null) {
markResumeUnavailable(true);
return;
}
const resumeSessionId = turn.sessionId !== '' ? turn.sessionId : sessionId;
if (resumeSessionId == null) {
return;
}
await runStream(
(signal, track) =>
resumeTurnStream(
server,
resumeSessionId,
turn.id,
snapshotRef.current.fold,
signal,
snapshotRef.current.activeStream?.lastSequenceNumber,
snapshotRef.current.groupRootBaseline,
track.onSequenceNumber,
),
{ current: turn.id },
true,
{ sessionId: resumeSessionId, gatewayTurnAccepted: { current: true } },
);
}, [runStream, server, sessionId]);
const branchFromTurn = useCallback(
async (turnId: string, userMessage: UserMessageContent) => {
let committed: SessionSnapshot;
let previousTurnId: string;
let rewound: SessionSnapshot;
try {
const activeSessionId = sessionId;
if (activeSessionId == null) {
throw new Error('Cannot branch from a turn without an active session.');
}
committed = commitActiveStream(snapshotRef.current);
setSnapshot(committed);
await cancel();
const conversationSessionId = await resolveActiveSessionId(
activeSessionId,
resolveConversationSessionIdRef.current,
);
previousTurnId = await resolveGatewayBranchPreviousTurnIdForTurn(server, conversationSessionId, turnId);
// Rewind to the exact parent used for the new branch. Using the
// previous item from listTurns could select an abandoned branch.
rewound = await buildSnapshotThroughTurn(
server,
conversationSessionId,
previousTurnId === 'none' ? null : previousTurnId,
);
createdAtByMessageIdRef.current = new Map();
// Keep the ref aligned before awaiting sendTurn so any intermediate
// reads (and the atomic pendingUser apply) see the rewound history.
snapshotRef.current = rewound;
setSnapshot(rewound);
} catch (error) {
// Setup failures never reach sendTurn/runStream reporting.
onErrorRef.current?.(error);
throw error;
}
// sendTurn/runStream own error reporting for the turn itself.
await sendTurn({
userMessage,
previousTurnId,
branchFromSnapshot: rewound,
branchRollbackSnapshot: committed,
});
},
[cancel, server, sendTurn, sessionId],
);
const resetFromTurn = useCallback(
async (turnId: string) => {
const committed = commitActiveStream(snapshotRef.current);
const originalInput = resolveTurnInput(committed, turnId);
if (originalInput == null) {
const error = new Error(`Turn ${turnId} not found in session snapshot`);
onErrorRef.current?.(error);
throw error;
}
const userMessage = extractTurnUserMessageContent(originalInput);
await branchFromTurn(turnId, userMessage);
},
[branchFromTurn],
);
const editFromTurn = useCallback(
async (turnId: string, editedText: string) => {
const committed = commitActiveStream(snapshotRef.current);
const originalInput = resolveTurnInput(committed, turnId);
if (originalInput == null) {
const error = new Error(`Turn ${turnId} not found in session snapshot`);
onErrorRef.current?.(error);
throw error;
}
const userMessage = buildEditedUserMessageContent(editedText, originalInput);
await branchFromTurn(turnId, userMessage);
},
[branchFromTurn],
);
const retryLoad = useCallback(() => {
setLoadRetryTrigger(n => n + 1);
}, []);
const hasOlderHistory = snapshot.historyPagination?.hasOlder === true;
const loadOlderHistory = useCallback(async () => {
if (sessionId == null || isMain === false) {
return;
}
const requestedSessionId = sessionId;
// Stale closure from a prior session — do not touch the live snapshot.
if (sessionIdRef.current !== requestedSessionId) {
return;
}
if (loadOlderInflightRef.current != null) {
return loadOlderInflightRef.current;
}
const current = snapshotRef.current;
if (current.historyPagination?.hasOlder !== true) {
return;
}
if (current.historyPagination.olderPageToken == null) {
return;
}
const generation = loadGenerationRef.current;
setIsLoadingOlderHistory(true);
const run = (async () => {
const stillCurrent = () =>
generation === loadGenerationRef.current && sessionIdRef.current === requestedSessionId;
try {
const conversationSessionId = await resolveActiveSessionId(
requestedSessionId,
resolveConversationSessionIdRef.current,
);
if (!stillCurrent()) {
return;
}
const next = await prependOlderSessionHistory(server, conversationSessionId, snapshotRef.current);
if (!stillCurrent()) {
return;
}
// Keep the ref in sync before the next render so awaiting
// callers (e.g. resolveSandboxIdForTurn) see the merged history.
snapshotRef.current = next;
setSnapshot(next);
} catch (error) {
if (stillCurrent()) {
onErrorRef.current?.(error);
}
throw error;
} finally {
if (stillCurrent()) {
setIsLoadingOlderHistory(false);
}
loadOlderInflightRef.current = null;
}
})();
loadOlderInflightRef.current = run;
return run;
}, [server, isMain, sessionId]);
/**
* Resolves the sandbox that was current as of `turnId`, paging in older
* history when the `sandbox.created` reference predates the loaded window
* (deriving it from loaded messages alone caused spurious "No sandbox is
* available yet" failures on long sessions).
*/
const resolveSandboxIdForTurn = useCallback(
async (turnId: string): Promise<string | undefined> => {
const generation = loadGenerationRef.current;
const requestedSessionId = sessionId;
const stillCurrent = () =>
generation === loadGenerationRef.current && sessionIdRef.current === requestedSessionId;
if (!stillCurrent()) {
return undefined;
}
let sandboxId = findSandboxIdInSnapshot(snapshotRef.current, turnId);
// ponytail: bounded linear page-in — the gateway has no direct
// session→sandbox lookup; a backend lookup route is the upgrade path.
for (
let i = 0;
sandboxId == null &&
stillCurrent() &&
snapshotRef.current.historyPagination?.hasOlder === true &&
i < MAX_SANDBOX_HISTORY_PAGE_INS;
i++
) {
await loadOlderHistory();
if (!stillCurrent()) {
return undefined;
}
sandboxId = findSandboxIdInSnapshot(snapshotRef.current, turnId);
}
return stillCurrent() ? sandboxId : undefined;
},
[loadOlderHistory, sessionId],
);
return {
messages,
isRunning,
resumeUnavailable,
isLoading,
isLoadingOlderHistory,
hasOlderHistory,
loadOlderHistory,
resolveSandboxIdForTurn,
retryLoad,
sendTurn,
cancel,
respondToToolApproval,
respondToToolResponse,
resumeRun,
branchFromTurn,
resetFromTurn,
editFromTurn,
};
}
export { findCurrentPausedAssistantMessage, MCP_AUTH_RESUME_RUN_CUSTOM_KEY };