@beeuni/sdk 0.1.0

package/dist/react/use-session.js

@@ -0,0 +1,893 @@
+'use client';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { useOpenCodeCompactionStore } from '../browser/stores/opencode-compaction-store.js';
+import { useSessionWorkingStore } from '../browser/stores/session-working-store.js';
+import { compactionExpiryAtMs, projectCompacting, serverCompactionRevalidateAtMs, } from '../core/session/compaction.js';
+import { useRuntimePendingStore } from '../browser/stores/opencode-pending-store.js';
+import { markRuntimeReadyVerified, seedConnectionFromReadyStart, } from '../browser/stores/sandbox-connection-store.js';
+import { getSandboxUrlForExternalId } from '../browser/stores/server-store.js';
+import { getBackendUrl } from '../core/session/server-store/url-helpers.js';
+import { ascendingId, useSyncStore } from '../browser/stores/sync-store.js';
+import { BillingError, parseBillingError } from '../core/http/api/errors.js';
+import { isSessionFresh } from '../core/http/fresh-sessions.js';
+import { onSessionStopped } from '../core/http/session-stopped.js';
+import { formatRuntimeError } from '../core/http/runtime-errors.js';
+import { createSessionPrompt, isSessionStartError, sessionStartKey, startProjectSession, } from '../core/rest/projects-client/index.js';
+import { RuntimeNotReadyError, getClient } from '../core/runtime/client.js';
+import { setCurrentRuntime } from '../core/session/current-runtime.js';
+import { onRuntimeGone } from '../core/session/runtime-gone.js';
+import { openSessionBundle } from '../core/session/open-bundle.js';
+import { messagesBeforeRewind } from '../core/session/rewind.js';
+import { extractGatewayErrorDetails, unwrapError } from '../core/turns/errors.js';
+import { holdLiveStart, liveStartPollMode } from './hold-live-start.js';
+import { clearStartStash, readStartStash } from './session-start-stash.js';
+import { reconcileHydratedSessionTitle } from './session-title-sync.js';
+import { seedModelDefaultsFromOpenBundle } from './prefetch-session-open.js';
+import { useSessionTranscriptHistory } from './use-session-transcript-history.js';
+import { useCanonicalRuntimeSession } from './use-canonical-opencode-session.js';
+import { useRuntimeEventStream } from './use-opencode-events/index.js';
+import { useSessionStream } from './use-session-stream.js';
+import { sessionStreamConnected } from '../core/session/control-stream.js';
+import { presenceReporter, watchHumanPresence } from './human-presence.js';
+import { formatModelString } from './use-opencode-local.js';
+import { runtimeKeys, rejectQuestion as rejectQuestionApi, replyToPermission, replyToQuestion, useAbortRuntimeSession, useExecuteRuntimeCommand, useRuntimeSession, } from './use-opencode-sessions/index.js';
+import { mintSessionWireMessageId } from './use-opencode-sessions/messages.js';
+import { unwrap } from './use-opencode-sessions/shared.js';
+import { usePermissionSelfHeal } from './use-permission-self-heal.js';
+import { useProjectConfig } from './use-project-config.js';
+import { useProjectModels } from './use-project-models.js';
+import { useQuestionSelfHeal } from './use-question-self-heal.js';
+import { useRuntimePhase } from './use-runtime-phase.js';
+import { useSessionPicks } from './use-session-picks.js';
+import { derivePhase } from './use-session-phase.js';
+import { isEmptyConversation, resolveSavedTranscript } from '../core/session-sync/saved-transcript.js';
+import { useSessionSync } from './use-session-sync.js';
+import { selectTranscriptShapeKey } from './session-transcript-subscription.js';
+import { useSessionStartGiveUp } from './use-session-start-give-up.js';
+import { useSessionTurnOutcome, useSessionWorking } from './use-session-working.js';
+import { cancelSessionTurn } from './session-stop.js';
+import { useVisibleAgents } from './use-visible-agents.js';
+import { createBeeuni } from '../core/client/beeuni.js';
+import { platformConfig } from '../core/http/config.js';
+const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+const FRESH_START_404_RETRIES = 12;
+const FRESH_START_404_RETRY_DELAY_MS = 800;
+export function shouldRetrySessionStart(failureCount, error, sessionId) {
+    if (isSessionStartError(error) && error.status === 404 && isSessionFresh(sessionId)) {
+        return failureCount < FRESH_START_404_RETRIES;
+    }
+    return !isSessionStartError(error) && failureCount < 3;
+}
+export const SESSION_START_POLL_MS = 1_500;
+export function resolveSessionRuntimeUrl(start) {
+    if (!start || start.stage !== 'ready')
+        return null;
+    const externalId = start.sandbox?.external_id;
+    if (externalId)
+        return getSandboxUrlForExternalId(externalId);
+    const path = start.runtime_url;
+    if (!path)
+        return null;
+    if (/^https?:\/\//i.test(path))
+        return path;
+    return `${getBackendUrl()}${path.startsWith('/') ? '' : '/'}${path}`;
+}
+export function resolveSendOptions(picks, override) {
+    const model = override?.model ?? picks.model;
+    const agent = override?.agent ?? picks.agent;
+    const variant = override?.variant ?? picks.variant;
+    return {
+        ...(model ? { model } : {}),
+        ...(agent ? { agent } : {}),
+        ...(variant ? { variant } : {}),
+        ...(override?.directory ? { directory: override.directory } : {}),
+    };
+}
+export function sessionPromptFromParts(runtimeSessionId, parts, options, clientMessageId, nowMs = Date.now()) {
+    const messageId = mintSessionWireMessageId(runtimeSessionId, clientMessageId);
+    const wireParts = parts.map((part) => {
+        if (part.type === 'file') {
+            return {
+                type: 'file',
+                mime: part.mime,
+                url: part.url,
+                ...(part.filename ? { filename: part.filename } : {}),
+                ...(part.source ? { source: part.source } : {}),
+            };
+        }
+        if (part.type === 'agent')
+            return { type: 'agent', name: part.name, ...(part.source ? { source: part.source } : {}) };
+        return { type: 'text', text: part.text };
+    });
+    const overrides = {
+        ...(options.model ? { model: options.model } : {}),
+        ...(options.agent ? { agent: options.agent } : {}),
+        ...(options.variant ? { variant: options.variant } : {}),
+        ...(options.directory ? { directory: options.directory } : {}),
+    };
+    return {
+        clientMessageId: clientMessageId ?? messageId,
+        messageId,
+        parts: wireParts,
+        ...(Object.keys(overrides).length ? { overrides } : {}),
+        remintOnDelivery: true,
+        clientSentAtMs: nowMs,
+    };
+}
+export function shouldPollSessionStart(error, data, now = Date.now()) {
+    if (isSessionStartError(error))
+        return false;
+    if (data?.retriable === false)
+        return false;
+    const stage = data?.stage;
+    if (stage === 'ready' || stage === 'failed' || stage === 'stopped')
+        return false;
+    const retryPause = sessionStartRetryPauseMs(data, now);
+    return retryPause ?? SESSION_START_POLL_MS;
+}
+function sessionStartRetryPauseMs(data, now) {
+    const nextRetryAt = data?.failure?.evidence?.next_retry_at;
+    if (!nextRetryAt)
+        return null;
+    const atMs = Date.parse(nextRetryAt);
+    if (!Number.isFinite(atMs))
+        return null;
+    return Math.max(SESSION_START_POLL_MS, Math.min(atMs - now + 1_000, 60_000));
+}
+export { START_INCONCLUSIVE_GIVE_UP_MS, hasStartGivenUp, nextInconclusiveSince, } from './use-session-start-give-up.js';
+export function computeStartSettled(input) {
+    if (!input.enabled)
+        return true;
+    if (input.hasGivenUp)
+        return true;
+    if (input.isFetching)
+        return false;
+    return !shouldPollSessionStart(input.error, input.data);
+}
+export const SESSION_START_FRESH_MS = 30_000;
+const RUNTIME_GONE_REFETCH_MIN_MS = 3_000;
+export function sessionStartStaleTime(query) {
+    return query.state.data?.stage === 'ready' ? SESSION_START_FRESH_MS : 0;
+}
+export function cachedStartResultIsReady(cachedState) {
+    return cachedState?.data?.stage === 'ready';
+}
+function startPollSignature(data) {
+    return [
+        data?.stage ?? '',
+        data?.reason ?? '',
+        data?.failure?.evidence?.next_retry_at ?? '',
+    ].join('|');
+}
+const SESSION_START_POLL_BACKOFF_STEPS = [
+    { afterMs: 30_000, pollMs: 5_000 },
+    { afterMs: 90_000, pollMs: 15_000 },
+    { afterMs: 240_000, pollMs: 30_000 },
+];
+const START_POLL_PACE_TTL_MS = 300_000;
+const startPollPaceByQuery = new WeakMap();
+function sessionStartRefetchIntervalMs(query, now) {
+    if (query.state.data?.stage === 'ready')
+        return 60_000;
+    const base = shouldPollSessionStart(query.state.error, query.state.data, now);
+    if (base === false) {
+        startPollPaceByQuery.delete(query);
+        return false;
+    }
+    const signature = startPollSignature(query.state.data);
+    const previous = startPollPaceByQuery.get(query);
+    const pace = previous &&
+        previous.signature === signature &&
+        now - previous.touchedAt <= START_POLL_PACE_TTL_MS
+        ? previous
+        : { signature, unchangedSince: now, touchedAt: now };
+    pace.touchedAt = now;
+    startPollPaceByQuery.set(query, pace);
+    const unchangedMs = now - pace.unchangedSince;
+    const stretched = [...SESSION_START_POLL_BACKOFF_STEPS]
+        .reverse()
+        .find((step) => unchangedMs >= step.afterMs)?.pollMs;
+    return stretched ? Math.max(base, stretched) : base;
+}
+export const SESSION_START_POLL_OPTIONS = {
+    refetchInterval: (query) => sessionStartRefetchIntervalMs(query, Date.now()),
+    refetchIntervalInBackground: true,
+};
+const RUNTIME_NOT_READY_MARKER = 'Server URL not ready';
+export function markDispatchedForPartIds(sessionId, parts) {
+    const partIds = new Set(parts
+        .map((p) => p.id)
+        .filter((id) => typeof id === 'string' && !!id));
+    if (partIds.size === 0)
+        return;
+    const store = useSyncStore.getState();
+    for (const message of store.messages[sessionId] ?? []) {
+        if (message.role !== 'user')
+            continue;
+        const owns = (store.parts[message.id] ?? []).some((p) => partIds.has(p.id));
+        if (owns)
+            store.markOptimisticDispatched(sessionId, message.id);
+    }
+}
+export function beginOptimisticPlainTextSend(sessionId, text) {
+    const messageId = ascendingId('msg');
+    const partId = ascendingId('prt');
+    const optimisticParts = text.trim()
+        ? [
+            {
+                id: partId,
+                sessionID: sessionId,
+                messageID: messageId,
+                type: 'text',
+                text,
+            },
+        ]
+        : [];
+    const info = {
+        id: messageId,
+        sessionID: sessionId,
+        role: 'user',
+        time: {},
+    };
+    useSyncStore.getState().optimisticAdd(sessionId, info, optimisticParts);
+    return { messageId, parts: [{ type: 'text', text, id: partId }] };
+}
+function errorBody(error) {
+    if (!error || typeof error !== 'object')
+        return null;
+    const holder = error;
+    for (const key of ['data', 'details', 'body']) {
+        const candidate = holder[key];
+        if (candidate && typeof candidate === 'object')
+            return candidate;
+    }
+    return holder;
+}
+function errorBodyMessage(error) {
+    const body = errorBody(error);
+    for (const key of ['message', 'error']) {
+        const value = body?.[key];
+        if (typeof value === 'string' && value.trim())
+            return value.trim();
+    }
+    return null;
+}
+function connectorRefusalConnections(error) {
+    const body = errorBody(error);
+    if (body?.code !== 'CONNECTOR_CONNECTION_REQUIRED')
+        return null;
+    const listed = [body.connector_connections, body.connectorConnections].find(Array.isArray);
+    const connections = [];
+    for (const entry of listed ?? []) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const connection = entry;
+        const strategy = connection.authorization_strategy ?? connection.authorizationStrategy;
+        if (typeof connection.id !== 'string' || typeof connection.slug !== 'string')
+            continue;
+        if (strategy !== 'project' && strategy !== 'user')
+            continue;
+        connections.push({
+            id: connection.id,
+            slug: connection.slug,
+            name: typeof connection.name === 'string' && connection.name ? connection.name : connection.slug,
+            authorization_strategy: strategy,
+        });
+    }
+    return connections.length > 0 ? connections : null;
+}
+export function classifySendError(error) {
+    if (error instanceof RuntimeNotReadyError ||
+        (error instanceof Error && error.message.includes(RUNTIME_NOT_READY_MARKER))) {
+        return {
+            kind: 'runtime-not-ready',
+            message: 'The session runtime is still starting — try again in a moment.',
+            cause: error,
+        };
+    }
+    if (error && typeof error === 'object') {
+        const parsed = parseBillingError(error);
+        if (parsed instanceof BillingError) {
+            return {
+                kind: 'billing',
+                message: parsed.message,
+                billing: parsed,
+                cause: error,
+            };
+        }
+        const connectors = connectorRefusalConnections(error);
+        if (connectors) {
+            return {
+                kind: 'connector',
+                message: errorBodyMessage(error) ??
+                    'Connect the required connectors before continuing this session.',
+                connectors,
+                cause: error,
+            };
+        }
+    }
+    const gateway = extractGatewayErrorDetails(error);
+    const formatted = formatRuntimeError(error);
+    return {
+        kind: 'runtime-error',
+        message: gateway?.message || unwrapError(formatted.message),
+        ...(gateway
+            ? {
+                gateway: {
+                    provider: gateway.provider,
+                    code: gateway.code,
+                    suggestion: gateway.suggestion,
+                    upstreamStatus: gateway.upstreamStatus,
+                    requestId: gateway.requestId,
+                },
+            }
+            : {}),
+        cause: error,
+    };
+}
+export function buildSessionCommandInput(sessionId, command, args, options = {}) {
+    return {
+        sessionId,
+        command,
+        args,
+        ...(options.agent ? { agent: options.agent } : {}),
+        ...(options.model ? { model: formatModelString(options.model) } : {}),
+        ...(options.variant ? { variant: options.variant } : {}),
+    };
+}
+const IDLE_SEND_STATE = { pending: null, sendError: null };
+export function sendStateOnStart(text) {
+    return { pending: text, sendError: null };
+}
+export function sendStateOnError(error) {
+    return { pending: null, sendError: classifySendError(error) };
+}
+export function sendReceiptId(sessionId, parts, clientMessageId) {
+    const identified = parts.find((part) => 'id' in part && typeof part.id === 'string');
+    return clientMessageId ?? identified?.id ?? sessionId;
+}
+export async function rewindOpenCodeSession(sessionId, messageId) {
+    if (!messageId)
+        throw new Error('Session rewind requires a message id');
+    unwrap(await getClient().session.revert({
+        sessionID: sessionId,
+        messageID: messageId,
+    }));
+}
+export async function restoreOpenCodeSessionRewind(sessionId) {
+    unwrap(await getClient().session.unrevert({ sessionID: sessionId }));
+}
+export async function answerQuestion(requestId, answers) {
+    try {
+        await replyToQuestion(requestId, answers);
+    }
+    catch (error) {
+        throw classifySendError(error);
+    }
+    useRuntimePendingStore.getState().removeQuestion(requestId);
+}
+export async function rejectQuestion(requestId) {
+    try {
+        await rejectQuestionApi(requestId);
+    }
+    catch (error) {
+        throw classifySendError(error);
+    }
+    useRuntimePendingStore.getState().removeQuestion(requestId);
+}
+export async function answerPermission(requestId, reply, message) {
+    try {
+        await replyToPermission(requestId, reply, message);
+    }
+    catch (error) {
+        throw classifySendError(error);
+    }
+    useRuntimePendingStore.getState().removePermission(requestId);
+}
+const DISABLED_CHAT_ENGINE_SYNC = {
+    messages: [],
+    status: { type: 'idle' },
+    freshness: 'idle',
+    retryTranscript: () => { },
+    isBusy: false,
+    isLoading: false,
+    mirrorState: 'idle',
+    diffs: [],
+    todos: [],
+    hasOlder: false,
+    isLoadingOlder: false,
+    loadOlder: async () => { },
+};
+export function useSession(projectId, sessionId, options = {}) {
+    const queryClient = useQueryClient();
+    const titleRefreshAbortRef = useRef(null);
+    const { waitMs = 15_000, repositoryMode, replayStartStash = true, enabled = true, chatEngine = true, initialRuntimeSessionId = options.initialOpenCodeSessionId ?? null, subscribeMessages = true, browserPresence = false, presenceAlerts = false, presencePageExit = false, } = options;
+    const [presenceTabId] = useState(() => (browserPresence ? crypto.randomUUID() : null));
+    const presenceAlertsRef = useRef(presenceAlerts);
+    const presencePageExitRef = useRef(presencePageExit);
+    const presenceReporterRef = useRef(null);
+    useEffect(() => {
+        if (!browserPresence || !presenceTabId || !projectId || !sessionId)
+            return;
+        const tab_id = presenceTabId;
+        const handle = createBeeuni(platformConfig()).session(projectId, sessionId);
+        const reporter = presenceReporter(({ active, alerts }) => {
+            const keepalive = !active && presencePageExitRef.current;
+            void handle.presence({ tab_id, active, alerts }, { keepalive }).catch(() => { });
+        }, presenceAlertsRef.current);
+        presenceReporterRef.current = reporter;
+        const stop = watchHumanPresence({ doc: document, win: window }, reporter.report, () => sessionStreamConnected(projectId, sessionId), () => presencePageExitRef.current);
+        return () => {
+            presenceReporterRef.current = null;
+            stop();
+        };
+    }, [browserPresence, presenceTabId, projectId, sessionId]);
+    useEffect(() => {
+        presenceAlertsRef.current = presenceAlerts;
+        presenceReporterRef.current?.setAlerts(presenceAlerts);
+    }, [presenceAlerts]);
+    useEffect(() => {
+        presencePageExitRef.current = presencePageExit;
+    }, [presencePageExit]);
+    const startEnabled = enabled && !!projectId && !!sessionId;
+    const streamConnectedRef = useRef(false);
+    const stoppedByUserRef = useRef(null);
+    const openedAtRef = useRef(null);
+    const start = useQuery({
+        queryKey: sessionStartKey(projectId, sessionId),
+        queryFn: async () => {
+            const previous = queryClient.getQueryData(sessionStartKey(projectId, sessionId));
+            if (openedAtRef.current?.sessionId !== sessionId)
+                openedAtRef.current = { sessionId, at: Date.now() };
+            const heldByStop = stoppedByUserRef.current === sessionId;
+            const mode = heldByStop
+                ? 'keep-stopped'
+                : liveStartPollMode(previous, typeof document !== 'undefined' && document.hidden);
+            if (mode === 'skip' && previous)
+                return previous;
+            const next = await startProjectSession(projectId, sessionId, {
+                waitMs,
+                repositoryMode,
+                keepStopped: mode === 'keep-stopped',
+                intentAgeMs: Date.now() - openedAtRef.current.at,
+            });
+            if (heldByStop && next && next.stage !== 'stopped' && stoppedByUserRef.current === sessionId) {
+                stoppedByUserRef.current = null;
+                openedAtRef.current = { sessionId, at: Date.now() };
+            }
+            return holdLiveStart(previous, next);
+        },
+        enabled: startEnabled,
+        retry: (failureCount, error) => shouldRetrySessionStart(failureCount, error, sessionId),
+        retryDelay: (failureCount, error) => isSessionStartError(error) && error.status === 404
+            ? FRESH_START_404_RETRY_DELAY_MS
+            : Math.min(1000 * 2 ** failureCount, 5000),
+        staleTime: sessionStartStaleTime,
+        ...SESSION_START_POLL_OPTIONS,
+        refetchInterval: (query) => streamConnectedRef.current && query.state.data?.stage === 'ready'
+            ? false
+            : SESSION_START_POLL_OPTIONS.refetchInterval(query),
+    });
+    useEffect(() => {
+        if (!startEnabled)
+            return;
+        return onSessionStopped((stoppedId) => {
+            if (stoppedId !== sessionId)
+                return;
+            stoppedByUserRef.current = sessionId;
+            void queryClient.invalidateQueries({ queryKey: sessionStartKey(projectId, sessionId) });
+        });
+    }, [startEnabled, projectId, sessionId, queryClient]);
+    const startData = start.data ?? null;
+    const startError = isSessionStartError(start.error) ? start.error : null;
+    const stage = startData?.stage ?? null;
+    const sandbox = startData?.sandbox ?? null;
+    const startReady = stage === 'ready';
+    const terminal = stage === 'failed' || stage === 'stopped';
+    useIsomorphicLayoutEffect(() => {
+        if (!startEnabled)
+            return;
+        const cached = queryClient.getQueryState(sessionStartKey(projectId, sessionId));
+        if (cachedStartResultIsReady(cached))
+            markRuntimeReadyVerified();
+    }, [projectId, sessionId]);
+    useIsomorphicLayoutEffect(() => {
+        if (!startEnabled)
+            return;
+        openSessionBundle(projectId, sessionId);
+        seedModelDefaultsFromOpenBundle(queryClient, projectId, sessionId);
+    }, [projectId, sessionId]);
+    const streamConnected = useSessionStream(projectId, sessionId, {
+        enabled: startEnabled,
+        tabId: presenceTabId ?? undefined,
+    });
+    streamConnectedRef.current = streamConnected;
+    const startGivenUp = useSessionStartGiveUp({
+        identity: `${projectId}\u0000${sessionId}`,
+        enabled: startEnabled,
+        hasData: !!start.data,
+        hasError: !!start.error,
+        isFetching: start.isFetching,
+    });
+    const startSettled = computeStartSettled({
+        enabled: startEnabled,
+        isFetching: start.isFetching,
+        data: start.data,
+        error: start.error,
+        hasGivenUp: startGivenUp,
+    });
+    const [switchedBoxId, setSwitchedBoxId] = useState(null);
+    useEffect(() => {
+        if (!startReady || !sandbox?.external_id || switchedBoxId === sandbox.external_id)
+            return;
+        setCurrentRuntime(getSandboxUrlForExternalId(sandbox.external_id), sandbox.external_id, sandbox.sandbox_id);
+        setSwitchedBoxId(sandbox.external_id);
+    }, [startReady, sandbox, switchedBoxId]);
+    useEffect(() => () => setCurrentRuntime(null), []);
+    const switched = startReady && !!sandbox?.external_id && switchedBoxId === sandbox.external_id;
+    useEffect(() => {
+        if (!switched || !sandbox?.external_id)
+            return;
+        seedConnectionFromReadyStart(getSandboxUrlForExternalId(sandbox.external_id), startData?.capabilities);
+    }, [switched, switchedBoxId]);
+    const refetchStart = start.refetch;
+    useEffect(() => {
+        if (!startEnabled || !switchedBoxId)
+            return;
+        const switchedUrl = getSandboxUrlForExternalId(switchedBoxId);
+        let lastAt = 0;
+        return onRuntimeGone((runtimeUrl) => {
+            if (runtimeUrl !== switchedUrl)
+                return;
+            const now = Date.now();
+            if (now - lastAt < RUNTIME_GONE_REFETCH_MIN_MS)
+                return;
+            lastAt = now;
+            void refetchStart();
+        });
+    }, [startEnabled, switchedBoxId, refetchStart]);
+    useRuntimeEventStream({ enabled: switched, projectId, sessionId });
+    const transcriptHistoryEnabled = startEnabled && chatEngine;
+    const transcriptHistory = useSessionTranscriptHistory(projectId, sessionId, transcriptHistoryEnabled);
+    const canonicalSession = useCanonicalRuntimeSession({
+        projectId,
+        sessionId,
+        pinFromStart: startData?.runtime_session_id ?? startData?.opencode_session_id ?? null,
+        initialPin: transcriptHistory.rootSessionId ?? initialRuntimeSessionId,
+        listRuntimeSessions: switched,
+    });
+    const { rootSessionId } = canonicalSession;
+    const ocSessionId = rootSessionId ?? '';
+    useEffect(() => () => {
+        titleRefreshAbortRef.current?.abort();
+        titleRefreshAbortRef.current = null;
+    }, [projectId, sessionId]);
+    const working = useSessionWorking(projectId, sessionId, {
+        enabled,
+        runtimeSessionId: ocSessionId,
+    });
+    const { noteSendReceipt, acceptSendReceipt, clearSendReceipt } = useSessionWorkingStore.getState();
+    const rawSync = useSessionSync(chatEngine ? ocSessionId : '', {
+        beeuniSessionScope: `${projectId}/${sessionId}`,
+        streamConnected,
+        mirror: transcriptHistory.envelope ?? undefined,
+        networkEnabled: switched,
+        working: working.state === 'working',
+        serverHoldsTurn: working.serverOpenTurnToken !== null,
+        subscribeMessages,
+    });
+    useSyncStore((state) => !subscribeMessages && chatEngine && ocSessionId
+        ? selectTranscriptShapeKey(state, ocSessionId)
+        : '');
+    const sync = chatEngine ? rawSync : DISABLED_CHAT_ENGINE_SYNC;
+    const runtimePhase = useRuntimePhase();
+    const restRewind = useSyncStore((s) => s.sessionRevert[ocSessionId] ?? null);
+    const [rewindPending, setRewindPending] = useState(false);
+    const [rewindError, setRewindError] = useState(null);
+    const rewindMessageId = restRewind?.staged ? restRewind.messageId : null;
+    const messages = useMemo(() => messagesBeforeRewind(sync.messages, restRewind), [sync.messages, restRewind]);
+    const turnOutcome = useSessionTurnOutcome(projectId, sessionId);
+    const turnRead = typeof turnOutcome.atMs === 'number';
+    const savedEmptyRoot = transcriptHistoryEnabled ? transcriptHistory.emptyRootSessionId : null;
+    const emptyProvenForRoot = savedEmptyRoot !== null && savedEmptyRoot === ocSessionId;
+    const savedTranscript = resolveSavedTranscript({
+        enabled: startEnabled && chatEngine,
+        hasMessages: sync.messages.length > 0,
+        history: !transcriptHistoryEnabled
+            ? 'off'
+            : transcriptHistory.isLoading
+                ? 'loading'
+                : transcriptHistory.envelope
+                    ? 'present'
+                    : 'absent',
+        mirror: sync.mirrorState,
+        root: ocSessionId ? 'known' : canonicalSession.pinSettled ? 'unknown' : 'pending',
+        emptyAwaitingTurnRead: emptyProvenForRoot && !turnRead,
+    });
+    const conversationEmpty = isEmptyConversation({
+        savedEmptyRoot,
+        rootSessionId: ocSessionId,
+        turnRead,
+        hasEndedTurn: turnOutcome.last_ended != null,
+        hasOpenOrQueuedTurn: working.state === 'working' ||
+            working.pendingDelivery === true ||
+            working.serverOpenTurnToken !== null,
+    });
+    useEffect(() => {
+        setRewindPending(false);
+        setRewindError(null);
+    }, [sessionId, ocSessionId]);
+    useQuestionSelfHeal(ocSessionId, sync.messages, {
+        enabled: switched && chatEngine && !!ocSessionId && !streamConnected,
+    });
+    usePermissionSelfHeal(ocSessionId, sync.messages, {
+        enabled: switched && chatEngine && !!ocSessionId && !streamConnected,
+    });
+    const questionMap = useRuntimePendingStore((s) => s.questions);
+    const permissionMap = useRuntimePendingStore((s) => s.permissions);
+    const optimisticCompactionAtMs = useOpenCodeCompactionStore((state) => switched ? (state.compactingBySession[ocSessionId] ?? null) : null);
+    const runtimeSessionRow = useRuntimeSession(switched ? ocSessionId : '');
+    const compactionInputs = {
+        optimisticAtMs: optimisticCompactionAtMs,
+        serverCompactingAtMs: runtimeSessionRow.data?.time?.compacting ?? null,
+        nowMs: Date.now(),
+    };
+    const isCompacting = projectCompacting(compactionInputs);
+    const [, setCompactionTick] = useState(0);
+    const compactionExpiry = compactionExpiryAtMs(compactionInputs);
+    useEffect(() => {
+        if (compactionExpiry === null)
+            return;
+        const timer = setTimeout(() => setCompactionTick((tick) => tick + 1), Math.max(0, compactionExpiry - Date.now()) + 1);
+        return () => clearTimeout(timer);
+    }, [compactionExpiry]);
+    const serverCompactionRevalidateAt = serverCompactionRevalidateAtMs(compactionInputs);
+    useEffect(() => {
+        if (serverCompactionRevalidateAt === null || !switched || !ocSessionId)
+            return;
+        const timer = setTimeout(() => {
+            void queryClient.invalidateQueries({ queryKey: runtimeKeys.runtimeSession(ocSessionId) });
+        }, Math.max(0, serverCompactionRevalidateAt - Date.now()));
+        return () => clearTimeout(timer);
+    }, [serverCompactionRevalidateAt, switched, ocSessionId, queryClient]);
+    const removeQuestion = useRuntimePendingStore((s) => s.removeQuestion);
+    const removePermission = useRuntimePendingStore((s) => s.removePermission);
+    const questions = useMemo(() => (switched ? Object.values(questionMap).filter((q) => q.sessionID === ocSessionId) : []), [questionMap, ocSessionId, switched]);
+    const permissions = useMemo(() => (switched ? Object.values(permissionMap).filter((p) => p.sessionID === ocSessionId) : []), [permissionMap, ocSessionId, switched]);
+    const runtimeActionReady = switched && !!rootSessionId;
+    const models = useProjectModels(projectId);
+    const agents = useVisibleAgents({ projectId });
+    const config = useProjectConfig(projectId);
+    const picks = useSessionPicks(sessionId);
+    const sendMutation = useMutation({
+        mutationFn: (input) => createSessionPrompt(projectId, sessionId, input),
+        retry: false,
+    });
+    const abortMutation = useAbortRuntimeSession();
+    const commandMutation = useExecuteRuntimeCommand();
+    const userMsgCount = useMemo(() => messages.filter((m) => m.info.role === 'user').length, [messages]);
+    const hasUserMessages = userMsgCount > 0;
+    useEffect(() => {
+        if (!chatEngine || !hasUserMessages || streamConnected)
+            return;
+        titleRefreshAbortRef.current?.abort();
+        const controller = new AbortController();
+        titleRefreshAbortRef.current = controller;
+        void reconcileHydratedSessionTitle(queryClient, projectId, sessionId, 1, {
+            signal: controller.signal,
+        }).finally(() => {
+            if (titleRefreshAbortRef.current === controller) {
+                titleRefreshAbortRef.current = null;
+            }
+        });
+        return () => controller.abort();
+    }, [chatEngine, projectId, queryClient, sessionId, hasUserMessages, streamConnected]);
+    const [sendState, setSendState] = useState(IDLE_SEND_STATE);
+    const pending = sendState.pending;
+    const pendingBaseCount = useRef(0);
+    useEffect(() => {
+        if (pending && userMsgCount > pendingBaseCount.current) {
+            setSendState((s) => (s.pending ? { ...s, pending: null } : s));
+        }
+    }, [userMsgCount, pending]);
+    const sendParts = async (parts, override) => {
+        if (!runtimeActionReady)
+            throw new RuntimeNotReadyError();
+        const opts = resolveSendOptions(picks, override);
+        markDispatchedForPartIds(ocSessionId, parts);
+        const receipt = {
+            messageId: sendReceiptId(ocSessionId, parts, override?.clientMessageId),
+            atMs: Date.now(),
+        };
+        noteSendReceipt(sessionId, receipt);
+        try {
+            const result = await sendMutation.mutateAsync(sessionPromptFromParts(ocSessionId, parts, opts, override?.clientMessageId));
+            if (result.state === 'failed') {
+                throw new Error('This prompt was refused: its earlier delivery already failed.');
+            }
+            acceptSendReceipt(sessionId, receipt.messageId, Date.now());
+        }
+        catch (error) {
+            clearSendReceipt(sessionId, receipt.messageId);
+            throw error;
+        }
+        useSyncStore.getState().commitSessionRevert(ocSessionId);
+    };
+    const send = (text, override) => {
+        if (!runtimeActionReady)
+            return;
+        pendingBaseCount.current = userMsgCount;
+        setSendState(sendStateOnStart(text));
+        const { messageId, parts } = beginOptimisticPlainTextSend(ocSessionId, text);
+        void sendParts(parts, override).catch((error) => {
+            useSyncStore.getState().optimisticRemove(ocSessionId, messageId);
+            setSendState(sendStateOnError(error));
+        });
+    };
+    const runCommand = (command, args, options = {}) => {
+        if (!runtimeActionReady)
+            return Promise.resolve();
+        return commandMutation.mutateAsync(buildSessionCommandInput(ocSessionId, command, args, options));
+    };
+    const rewind = async (messageId) => {
+        if (!runtimeActionReady)
+            throw new RuntimeNotReadyError();
+        if (!messageId)
+            throw new Error('Session rewind requires a message id');
+        if (working.state === 'working' || rewindPending) {
+            throw new Error('Cannot rewind a busy session');
+        }
+        setRewindPending(true);
+        setRewindError(null);
+        try {
+            await rewindOpenCodeSession(ocSessionId, messageId);
+            useSyncStore.getState().stageSessionRevert(ocSessionId, messageId);
+        }
+        catch (error) {
+            const classified = classifySendError(error);
+            setRewindError(classified);
+            throw classified;
+        }
+        finally {
+            setRewindPending(false);
+        }
+    };
+    const restoreRewind = async () => {
+        if (!runtimeActionReady)
+            throw new RuntimeNotReadyError();
+        if (!rewindMessageId || rewindPending)
+            return;
+        setRewindPending(true);
+        setRewindError(null);
+        try {
+            await restoreOpenCodeSessionRewind(ocSessionId);
+            useSyncStore.getState().clearSessionRevert(ocSessionId);
+        }
+        catch (error) {
+            const classified = classifySendError(error);
+            setRewindError(classified);
+            throw classified;
+        }
+        finally {
+            setRewindPending(false);
+        }
+    };
+    const cancel = () => {
+        const settlement = cancelSessionTurn({
+            projectId,
+            sessionId,
+            runtimeSessionId: ocSessionId,
+            runtimeActionReady,
+            runAbort: () => abortMutation.mutateAsync(ocSessionId),
+        });
+        questions.forEach((q) => removeQuestion(q.id));
+        permissions.forEach((p) => removePermission(p.id));
+        setSendState(IDLE_SEND_STATE);
+        return settlement;
+    };
+    const runtimeSessionError = canonicalSession.error;
+    const phase = derivePhase({
+        terminal,
+        startError,
+        runtimeError: runtimeSessionError,
+        startSettled,
+        switched,
+    });
+    const startedRef = useRef(false);
+    useEffect(() => {
+        if (!replayStartStash || !chatEngine)
+            return;
+        if (startedRef.current || phase !== 'ready' || sync.isLoading)
+            return;
+        const stash = readStartStash(sessionId);
+        if (!stash)
+            return;
+        startedRef.current = true;
+        clearStartStash(sessionId);
+        if (sync.messages.length > 0)
+            return;
+        if (stash.model)
+            picks.setModel(stash.model);
+        if (stash.agent)
+            picks.setAgent(stash.agent);
+        if (!stash.prompt.trim())
+            return;
+        send(stash.prompt, {
+            model: stash.model,
+            agent: stash.agent,
+            variant: stash.variant,
+        });
+    }, [phase, sync.isLoading, sync.messages.length, sessionId, replayStartStash, chatEngine]);
+    return {
+        projectId,
+        sessionId,
+        runtimeSessionId: rootSessionId ?? null,
+        opencodeSessionId: rootSessionId ?? null,
+        runtimeTransport: 'rest',
+        runtimeSessions: canonicalSession.sessions,
+        runtimeSessionsLoading: canonicalSession.isLoading,
+        runtimeSessionsListed: canonicalSession.listed,
+        runtimeError: runtimeSessionError,
+        messages,
+        status: sync.status,
+        freshness: sync.freshness,
+        retryTranscript: sync.retryTranscript,
+        questions,
+        permissions,
+        diffs: sync.diffs,
+        todos: sync.todos,
+        hasOlder: sync.hasOlder,
+        isLoadingOlder: sync.isLoadingOlder,
+        loadOlder: sync.loadOlder,
+        phase,
+        stage,
+        agentName: startData?.agent_name && startData.agent_name !== 'default'
+            ? startData.agent_name
+            : null,
+        sandbox,
+        runtimeUrl: resolveSessionRuntimeUrl(startData),
+        switched,
+        retriable: startData?.retriable ?? false,
+        activelyStarting: startData?.boot?.actively_starting ?? false,
+        startError,
+        failure: startData?.failure ?? null,
+        runtimePhase,
+        working,
+        isBusy: working.state === 'working',
+        isCompacting,
+        isLoading: sync.isLoading,
+        savedTranscript,
+        conversationEmpty,
+        isError: terminal || !!startError || !!runtimeSessionError,
+        hasPending: questions.length > 0 || permissions.length > 0,
+        reason: startData?.reason ?? null,
+        pending,
+        isSending: sendMutation.isPending,
+        sendError: sendState.sendError,
+        rewindMessageId,
+        rewindPending,
+        rewindError,
+        models,
+        agents,
+        defaultAgent: config?.default_agent ?? config?.open_code_default_agent ?? null,
+        commands: config?.commands ?? [],
+        picks,
+        send,
+        sendParts,
+        rewind,
+        restoreRewind,
+        cancel,
+        runCommand,
+        answerQuestion,
+        rejectQuestion,
+        answerPermission,
+        removeQuestion,
+        removePermission,
+        retry: () => {
+            stoppedByUserRef.current = null;
+            openedAtRef.current = { sessionId, at: Date.now() };
+            void start.refetch();
+        },
+    };
+}