Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

53.8 KB
Raw Blame
'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 };