@beeuni/sdk 0.1.0

package/dist/react/use-session-send.js

@@ -0,0 +1,233 @@
+'use client';
+import { useCallback, useState } from 'react';
+import { getClient } from '../core/runtime/client.js';
+import { useSessionWorkingStore } from '../browser/stores/session-working-store.js';
+import { SESSION_SYNC_PAGE_SIZE } from '../core/session-sync/session-sync-controller.js';
+import { ascendingId, useSyncStore } from '../browser/stores/sync-store.js';
+import { classifySendError } from './use-session.js';
+import { promptRuntimeMessage, useAbortRuntimeSession, } from './use-opencode-sessions/index.js';
+import { readStartStash, writeStartStash } from './session-start-stash.js';
+import { stopWithReceipt } from './session-stop.js';
+export { applyOptimisticAbort, STOP_HOLD_DEADLINE_MS, stopWithReceipt, } from './session-stop.js';
+export function beginOptimisticSend(sessionId, messageId, text, partIds) {
+    const parts = text.trim()
+        ? [
+            {
+                id: partIds?.[0] ?? ascendingId('prt'),
+                sessionID: sessionId,
+                messageID: messageId,
+                type: 'text',
+                text,
+            },
+        ]
+        : [];
+    const info = {
+        id: messageId,
+        sessionID: sessionId,
+        role: 'user',
+        time: {},
+    };
+    useSyncStore.getState().optimisticAdd(sessionId, info, parts);
+}
+export function markOptimisticSendDispatched(sessionId, messageId) {
+    useSyncStore.getState().markOptimisticDispatched(sessionId, messageId);
+}
+export function markOptimisticSendInboxBacked(sessionId, messageId) {
+    useSyncStore.getState().markOptimisticInboxBacked(sessionId, messageId);
+}
+export function abandonOptimisticSend(sessionId, messageId) {
+    useSessionWorkingStore.getState().clearSendReceipt(sessionId, messageId);
+    useSyncStore.getState().optimisticRemove(sessionId, messageId);
+}
+export function recoverFromSendFailure(sessionId, messageId, error, options = {}) {
+    const classify = options.classify ?? classifySendError;
+    const resolveClient = options.getClient ?? getClient;
+    const classified = classify(error);
+    useSessionWorkingStore.getState().clearSendReceipt(sessionId, messageId);
+    if (options.inboxRowExists) {
+        void options
+            .inboxRowExists()
+            .then((exists) => {
+            if (!exists) {
+                useSyncStore.getState().optimisticRemove(sessionId, messageId);
+                return;
+            }
+            useSessionWorkingStore
+                .getState()
+                .noteSendReceipt(sessionId, { messageId, atMs: Date.now() });
+        })
+            .catch(() => {
+        });
+        return classified;
+    }
+    let client;
+    try {
+        client = resolveClient();
+    }
+    catch {
+        useSyncStore.getState().optimisticRemove(sessionId, messageId);
+        return classified;
+    }
+    client.session
+        .messages({ sessionID: sessionId, limit: SESSION_SYNC_PAGE_SIZE })
+        .then((res) => {
+        if (res?.data) {
+            useSyncStore.getState().hydrate(sessionId, res.data);
+        }
+        else {
+            useSyncStore.getState().optimisticRemove(sessionId, messageId);
+        }
+    })
+        .catch(() => {
+        useSyncStore.getState().optimisticRemove(sessionId, messageId);
+    });
+    return classified;
+}
+export async function sendAndRecover(args) {
+    try {
+        useSyncStore.getState().markOptimisticDispatched(args.sessionId, args.messageId);
+        await promptRuntimeMessage({
+            sessionId: args.sessionId,
+            parts: args.parts,
+            options: args.options,
+            ...(args.clientMessageId ? { clientMessageId: args.clientMessageId } : {}),
+        });
+        return { ok: true };
+    }
+    catch (cause) {
+        const error = recoverFromSendFailure(args.sessionId, args.messageId, cause, {
+            getClient: args.getClient,
+            classify: args.classify,
+        });
+        return { ok: false, error, cause };
+    }
+}
+const realStashReplayTimers = {
+    setTimeout: (handler, ms) => setTimeout(handler, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+};
+export function replayStartStash(options) {
+    const { sessionId, readStash = readStartStash, writeRaceAttempts = 5, writeRaceIntervalMs = 50, checkReadiness, readinessAttempts = 120, readinessIntervalMs = 250, onReadinessTimeout, prepare, onFailure, onSuccess, getClient: getClientOpt, classify, } = options;
+    const t = options.timers ?? realStashReplayTimers;
+    let cancelled = false;
+    let timer;
+    const fail = (stash, messageId, error) => {
+        writeStartStash(sessionId, stash);
+        const classified = recoverFromSendFailure(sessionId, messageId, error, {
+            getClient: getClientOpt,
+            classify,
+        });
+        onFailure?.(stash, error, classified);
+    };
+    const attemptSend = (stash, ready) => {
+        const prepared = prepare(stash, ready);
+        beginOptimisticSend(sessionId, prepared.messageId, prepared.optimisticText, prepared.partIds);
+        void (async () => {
+            let parts;
+            try {
+                parts = await prepared.buildParts();
+            }
+            catch (err) {
+                fail(stash, prepared.messageId, err);
+                return;
+            }
+            try {
+                useSyncStore.getState().markOptimisticDispatched(sessionId, prepared.messageId);
+                await promptRuntimeMessage({ sessionId, parts, options: prepared.sendOptions });
+                if (!cancelled)
+                    onSuccess?.(stash);
+            }
+            catch (err) {
+                if (!cancelled)
+                    fail(stash, prepared.messageId, err);
+            }
+        })();
+    };
+    const pollReadiness = (stash, attempt) => {
+        if (cancelled)
+            return;
+        const ready = checkReadiness(stash);
+        if (ready !== null) {
+            attemptSend(stash, ready);
+            return;
+        }
+        if (attempt < readinessAttempts) {
+            timer = t.setTimeout(() => pollReadiness(stash, attempt + 1), readinessIntervalMs);
+            return;
+        }
+        onReadinessTimeout?.(stash);
+    };
+    const readWithRetry = (attempt) => {
+        if (cancelled)
+            return;
+        const stash = readStash(sessionId);
+        if (!stash?.prompt) {
+            if (attempt < writeRaceAttempts) {
+                timer = t.setTimeout(() => readWithRetry(attempt + 1), writeRaceIntervalMs);
+                return;
+            }
+            return;
+        }
+        pollReadiness(stash, attempt);
+    };
+    readWithRetry(0);
+    return {
+        cancel: () => {
+            cancelled = true;
+            if (timer !== undefined)
+                t.clearTimeout(timer);
+        },
+    };
+}
+export async function sendWithReceipt(args) {
+    const workingSessionId = args.workingSessionId ?? args.sessionId;
+    useSessionWorkingStore
+        .getState()
+        .noteSendReceipt(workingSessionId, { messageId: args.messageId, atMs: Date.now() });
+    const result = await sendAndRecover(args);
+    if (result.ok) {
+        useSessionWorkingStore
+            .getState()
+            .acceptSendReceipt(workingSessionId, args.messageId, Date.now());
+    }
+    else {
+        useSessionWorkingStore.getState().clearSendReceipt(workingSessionId, args.messageId);
+    }
+    return result;
+}
+export function useSessionSend(sessionId, options = {}) {
+    const { getClient: getClientOpt, classify, workingSessionId, projectId } = options;
+    const [sendError, setSendError] = useState(null);
+    const [isSending, setIsSending] = useState(false);
+    const abortMutation = useAbortRuntimeSession();
+    const send = useCallback(async (parts, sendOptions, callOptions = {}) => {
+        setSendError(null);
+        const messageId = callOptions.messageId ?? ascendingId('msg');
+        const firstText = parts.find((p) => p.type === 'text');
+        const optimisticText = callOptions.optimisticText ?? firstText?.text ?? '';
+        beginOptimisticSend(sessionId, messageId, optimisticText, callOptions.partIds);
+        setIsSending(true);
+        const result = await sendWithReceipt({
+            sessionId,
+            ...(workingSessionId ? { workingSessionId } : {}),
+            messageId,
+            parts,
+            options: sendOptions,
+            getClient: getClientOpt,
+            classify,
+        });
+        setIsSending(false);
+        if (!result.ok)
+            setSendError(result.error);
+        return result;
+    }, [sessionId, workingSessionId, getClientOpt, classify]);
+    const stop = useCallback(() => {
+        if (!sessionId || abortMutation.isPending)
+            return Promise.resolve({ status: 'skipped' });
+        return stopWithReceipt(sessionId, () => abortMutation.mutateAsync(sessionId), {
+            ...(workingSessionId ? { workingSessionId } : {}),
+            ...(projectId ? { projectId } : {}),
+        });
+    }, [sessionId, workingSessionId, projectId, abortMutation]);
+    return { send, stop, isSending, isStopping: abortMutation.isPending, sendError };
+}

package/dist/react/use-session-start-give-up.d.ts

@@ -0,0 +1,19 @@
+import type { SessionStartResult } from '../core/rest/projects-client/index.js';
+export declare const START_INCONCLUSIVE_GIVE_UP_MS = 45000;
+export declare function hasStartGivenUp(data: SessionStartResult | null | undefined, error: unknown, inconclusiveSinceMs: number | null, nowMs: number, budgetMs?: number): boolean;
+export declare function nextInconclusiveSince(input: {
+    current: number | null;
+    enabled: boolean;
+    hasData: boolean;
+    hasError: boolean;
+    isFetching: boolean;
+    nowMs: number;
+}): number | null;
+export declare function useSessionStartGiveUp(input: {
+    identity: string;
+    enabled: boolean;
+    hasData: boolean;
+    hasError: boolean;
+    isFetching: boolean;
+    budgetMs?: number;
+}): boolean;

package/dist/react/use-session-start-give-up.js

@@ -0,0 +1,59 @@
+'use client';
+import { useEffect, useRef, useState } from 'react';
+import { startGiveUpExpiryAtMs } from './session-start-giveup.js';
+export const START_INCONCLUSIVE_GIVE_UP_MS = 45_000;
+function hasInconclusiveStartGivenUp(hasData, hasError, inconclusiveSinceMs, nowMs, budgetMs) {
+    if (hasData || hasError)
+        return false;
+    return inconclusiveSinceMs !== null && nowMs - inconclusiveSinceMs >= budgetMs;
+}
+export function hasStartGivenUp(data, error, inconclusiveSinceMs, nowMs, budgetMs = START_INCONCLUSIVE_GIVE_UP_MS) {
+    return hasInconclusiveStartGivenUp(!!data, !!error, inconclusiveSinceMs, nowMs, budgetMs);
+}
+export function nextInconclusiveSince(input) {
+    if (!input.enabled)
+        return null;
+    if (input.hasData || input.hasError)
+        return null;
+    return input.current ?? input.nowMs;
+}
+export function useSessionStartGiveUp(input) {
+    const budgetMs = input.budgetMs ?? START_INCONCLUSIVE_GIVE_UP_MS;
+    const inconclusiveSinceRef = useRef(null);
+    const [givenUp, setGivenUp] = useState(false);
+    useEffect(() => {
+        inconclusiveSinceRef.current = null;
+        setGivenUp(false);
+    }, [input.identity]);
+    useEffect(() => {
+        const nowMs = Date.now();
+        inconclusiveSinceRef.current = nextInconclusiveSince({
+            current: inconclusiveSinceRef.current,
+            enabled: input.enabled,
+            hasData: input.hasData,
+            hasError: input.hasError,
+            isFetching: input.isFetching,
+            nowMs,
+        });
+        setGivenUp(hasInconclusiveStartGivenUp(input.hasData, input.hasError, inconclusiveSinceRef.current, nowMs, budgetMs));
+        const expiryAtMs = startGiveUpExpiryAtMs({
+            inconclusiveSinceMs: inconclusiveSinceRef.current,
+            budgetMs,
+        });
+        if (expiryAtMs === null)
+            return;
+        const timer = setTimeout(() => {
+            const fireNowMs = Date.now();
+            setGivenUp(hasInconclusiveStartGivenUp(input.hasData, input.hasError, inconclusiveSinceRef.current, fireNowMs, budgetMs));
+        }, Math.max(0, expiryAtMs - Date.now()) + 1);
+        return () => clearTimeout(timer);
+    }, [
+        input.identity,
+        input.enabled,
+        input.hasData,
+        input.hasError,
+        input.isFetching,
+        budgetMs,
+    ]);
+    return givenUp;
+}

package/dist/react/use-session-stream.d.ts

@@ -0,0 +1,17 @@
+import { type QueryClient } from '@tanstack/react-query';
+import { type SessionControlFrame } from '../core/session/control-stream.js';
+export declare function useSessionStreamConnected(projectId: string, sessionId: string): boolean;
+export declare function applySessionControlFrame(queryClient: QueryClient, projectId: string, sessionId: string, frame: SessionControlFrame, memory: {
+    secretsRev?: string;
+    runtimeKey?: string;
+}, nowMs?: number): void;
+export declare function patchCachedSessionTitle(queryClient: QueryClient, projectId: string, sessionId: string, title: string): void;
+export declare function applyRuntimeStatus(status: {
+    state: 'up' | 'down';
+    reason: string | null;
+}): void;
+export declare function applyRuntimeHealth(health: Record<string, unknown>): boolean;
+export declare function useSessionStream(projectId: string, sessionId: string, options?: {
+    enabled?: boolean;
+    tabId?: string;
+}): boolean;

package/dist/react/use-session-stream.js

@@ -0,0 +1,181 @@
+'use client';
+import { useQueryClient } from '@tanstack/react-query';
+import { useEffect, useSyncExternalStore } from 'react';
+import { markInitialCheckDone, setConnectionStreamDriven, setRuntimeCapabilities, setRuntimeHealth, setSandboxStatus, } from '../browser/stores/sandbox-connection-store.js';
+import { noteSessionStopped } from '../core/http/session-stopped.js';
+import { sessionStartKey } from '../core/rest/projects-client/index.js';
+import { openSessionStream, sessionStreamConnected, subscribeSessionStreamConnections, } from '../core/session/control-stream.js';
+import { invalidateProjectProviderQueries } from './provider-refresh.js';
+import { qk } from './query-keys.js';
+export function useSessionStreamConnected(projectId, sessionId) {
+    return useSyncExternalStore(subscribeSessionStreamConnections, () => !!projectId && !!sessionId && sessionStreamConnected(projectId, sessionId), () => false);
+}
+export function applySessionControlFrame(queryClient, projectId, sessionId, frame, memory, nowMs = Date.now()) {
+    if (frame.type === 'beeuni.control.turn') {
+        const payload = frame.payload;
+        if (!payload?.known || !Array.isArray(payload.turns))
+            return;
+        const observation = {
+            turns: payload.turns,
+            ...(payload.last_ended ? { last_ended: payload.last_ended } : {}),
+            ...(payload.recent_failures ? { recent_failures: payload.recent_failures } : {}),
+            ...(payload.working ? { working: payload.working } : {}),
+            atMs: nowMs,
+        };
+        queryClient.setQueryData(qk.project.sessionTurn(projectId, sessionId), observation);
+        return;
+    }
+    if (frame.type === 'beeuni.control.session') {
+        const payload = frame.payload;
+        if (!payload?.known)
+            return;
+        if (typeof payload.title === 'string' && payload.title) {
+            patchCachedSessionTitle(queryClient, projectId, sessionId, payload.title);
+        }
+        if (typeof payload.secrets_rev === 'string') {
+            if (memory.secretsRev !== undefined && memory.secretsRev !== payload.secrets_rev) {
+                invalidateProjectProviderQueries(queryClient, projectId);
+            }
+            memory.secretsRev = payload.secrets_rev;
+        }
+        return;
+    }
+    if (frame.type === 'beeuni.control.audit') {
+        queryClient.setQueryData(qk.project.sessionAuditWatermark(projectId, sessionId), frame.payload);
+        return;
+    }
+    if (frame.type === 'beeuni.control.runtime') {
+        const payload = frame.payload;
+        queryClient.setQueryData(qk.project.sessionRuntimeControl(projectId, sessionId), payload);
+        const runtimeKey = JSON.stringify([
+            payload?.sandbox_status ?? null,
+            payload?.external_id ?? null,
+            payload?.waking ?? false,
+            payload?.stop_reason ?? null,
+        ]);
+        if (memory.runtimeKey !== undefined && memory.runtimeKey !== runtimeKey) {
+            if (payload?.sandbox_status === 'stopped' && payload?.stop_reason === 'manual') {
+                noteSessionStopped(sessionId);
+            }
+            void queryClient.invalidateQueries({ queryKey: sessionStartKey(projectId, sessionId) });
+        }
+        memory.runtimeKey = runtimeKey;
+    }
+}
+function readTitle(row) {
+    return typeof row.name === 'string' ? row.name : null;
+}
+export function patchCachedSessionTitle(queryClient, projectId, sessionId, title) {
+    const patchRow = (row) => {
+        if (!row || typeof row !== 'object')
+            return row;
+        const record = row;
+        const id = typeof record.session_id === 'string' ? record.session_id : record.sessionId;
+        if (id !== sessionId)
+            return row;
+        if (typeof record.custom_name === 'string' && record.custom_name.trim())
+            return row;
+        return readTitle(record) === title ? row : { ...record, name: title };
+    };
+    const patch = (data) => {
+        if (Array.isArray(data)) {
+            let changed = false;
+            const next = data.map((row) => {
+                const patched = patchRow(row);
+                if (patched !== row)
+                    changed = true;
+                return patched;
+            });
+            return changed ? next : data;
+        }
+        if (data && typeof data === 'object' && Array.isArray(data.pages)) {
+            const paged = data;
+            let changed = false;
+            const pages = paged.pages.map((page) => {
+                if (!Array.isArray(page?.items))
+                    return page;
+                const items = page.items.map((row) => {
+                    const patched = patchRow(row);
+                    if (patched !== row)
+                        changed = true;
+                    return patched;
+                });
+                return changed ? { ...page, items } : page;
+            });
+            return changed ? { ...paged, pages } : data;
+        }
+        return patchRow(data);
+    };
+    for (const [key, data] of queryClient.getQueriesData({ queryKey: qk.project.sessionsScope(projectId) })) {
+        const next = patch(data);
+        if (next !== data)
+            queryClient.setQueryData(key, next);
+    }
+    const detailKey = qk.project.session(projectId, sessionId);
+    const detail = queryClient.getQueryData(detailKey);
+    const nextDetail = patch(detail);
+    if (nextDetail !== detail)
+        queryClient.setQueryData(detailKey, nextDetail);
+}
+export function applyRuntimeStatus(status) {
+    if (status.state === 'down') {
+        const parked = (status.reason ?? '').startsWith('sandbox_') || status.reason === 'no_sandbox';
+        setSandboxStatus('connecting');
+        setRuntimeHealth(false, undefined, status.reason, { parked });
+        markInitialCheckDone();
+    }
+}
+export function applyRuntimeHealth(health) {
+    const harness = health.harness;
+    const ready = health.status !== 'starting' && health.status !== 'down' && health.status !== 'error' && harness?.ready !== false;
+    const version = typeof health.version === 'string'
+        ? health.version
+        : typeof harness?.version === 'string'
+            ? harness.version
+            : undefined;
+    if (Array.isArray(health.capabilities)) {
+        setRuntimeCapabilities(health.capabilities.filter((entry) => typeof entry === 'string'));
+    }
+    setRuntimeHealth(ready, version, ready ? null : typeof health.reason === 'string' ? health.reason : null);
+    if (ready)
+        setSandboxStatus('connected');
+    markInitialCheckDone();
+    return ready;
+}
+export function useSessionStream(projectId, sessionId, options = {}) {
+    const queryClient = useQueryClient();
+    const enabled = options.enabled !== false && !!projectId && !!sessionId;
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const memory = {};
+        const stream = openSessionStream({
+            projectId,
+            sessionId,
+            runtime: true,
+            ...(options.tabId ? { tabId: options.tabId } : {}),
+            onControl: (frame) => {
+                applySessionControlFrame(queryClient, projectId, sessionId, frame, memory);
+                setConnectionStreamDriven(sessionStreamConnected(projectId, sessionId));
+            },
+            onRuntimeStatus: (status) => {
+                if (status.state === 'down')
+                    memory.runtimeReady = false;
+                applyRuntimeStatus(status);
+            },
+            onRuntimeHealth: (health) => {
+                const ready = applyRuntimeHealth(health);
+                if (ready && memory.runtimeReady === false) {
+                    void queryClient.invalidateQueries({ queryKey: sessionStartKey(projectId, sessionId) });
+                }
+                memory.runtimeReady = ready;
+            },
+            onConnectionChange: () => setConnectionStreamDriven(sessionStreamConnected(projectId, sessionId)),
+        });
+        return () => {
+            stream.close();
+            setConnectionStreamDriven(false);
+        };
+    }, [enabled, projectId, sessionId, queryClient, options.tabId]);
+    return useSessionStreamConnected(projectId, sessionId);
+}

package/dist/react/use-session-sync.d.ts

@@ -0,0 +1,43 @@
+import type { SessionTranscriptSyncEnvelope } from '../core/rest/projects-client/sessions.js';
+import { loadSessionRuntimeStatus, loadSessionTranscriptMessages } from '../browser/session-sync/session-sync-registry.js';
+export { loadSessionRuntimeStatus, loadSessionTranscriptMessages };
+type FileDiff = Omit<import('../core/runtime/runtime-types.js').SnapshotFileDiff, 'patch'> & {
+    patch?: string;
+    before?: string;
+    after?: string;
+};
+interface UseSessionSyncOptions {
+    streamConnected?: boolean;
+    mirror?: SessionTranscriptSyncEnvelope | null;
+    beeuniSessionScope?: string;
+    networkEnabled?: boolean;
+    working?: boolean;
+    serverHoldsTurn?: boolean;
+    subscribeMessages?: boolean;
+    savedChild?: boolean;
+}
+export declare function sessionSyncBusy(input: {
+    working: boolean | undefined;
+    streamBusy: boolean;
+}): boolean;
+export declare function livenessBusy(input: {
+    networkEnabled: boolean;
+    runtimeHealthy?: boolean;
+    working: boolean | undefined;
+    streamBusy: boolean;
+    serverHoldsTurn?: boolean;
+}): boolean;
+export declare function useSessionSync(sessionId: string, options?: UseSessionSyncOptions): {
+    messages: import("../internal/sync-store.js").MessageWithParts[];
+    status: import("../index.js").BeeuniSessionStatus;
+    freshness: import("../core/session-sync/session-sync-controller.js").SessionSyncFreshness;
+    retryTranscript: () => void;
+    isBusy: boolean;
+    isLoading: boolean;
+    mirrorState: "idle" | "loading" | "absent" | "painted";
+    hasOlder: boolean;
+    isLoadingOlder: boolean;
+    loadOlder: () => Promise<void>;
+    diffs: FileDiff[];
+    todos: import("../index.js").BeeuniTodo[];
+};