@beeuni/sdk 0.1.0

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

@@ -0,0 +1,65 @@
+'use client';
+import { useEffect, useState } from 'react';
+export const EMPTY_SESSION_PICKS = { model: null, agent: null, variant: null };
+const storageKey = (sessionId) => `beeuni:picks:${sessionId}`;
+function stringOrNull(value) {
+    return typeof value === 'string' && value !== '' ? value : null;
+}
+function modelKeyOrNull(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const bag = value;
+    const providerID = stringOrNull(bag.providerID);
+    const modelID = stringOrNull(bag.modelID);
+    if (!providerID || !modelID)
+        return null;
+    const provider = stringOrNull(bag.provider);
+    return { providerID, modelID, ...(provider ? { provider } : {}) };
+}
+export function parseSessionPicks(raw) {
+    if (!raw)
+        return { ...EMPTY_SESSION_PICKS };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ...EMPTY_SESSION_PICKS };
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { ...EMPTY_SESSION_PICKS };
+    }
+    const bag = parsed;
+    return {
+        model: modelKeyOrNull(bag.model),
+        agent: stringOrNull(bag.agent),
+        variant: stringOrNull(bag.variant),
+    };
+}
+export function useSessionPicks(sessionId) {
+    const [picks, setPicks] = useState({ ...EMPTY_SESSION_PICKS });
+    useEffect(() => {
+        try {
+            setPicks(parseSessionPicks(localStorage.getItem(storageKey(sessionId))));
+        }
+        catch {
+            setPicks({ ...EMPTY_SESSION_PICKS });
+        }
+    }, [sessionId]);
+    const update = (patch) => setPicks((prev) => {
+        const next = { ...prev, ...patch };
+        try {
+            localStorage.setItem(storageKey(sessionId), JSON.stringify(next));
+        }
+        catch { }
+        return next;
+    });
+    return {
+        model: picks.model,
+        agent: picks.agent,
+        variant: picks.variant,
+        setModel: (model) => update({ model }),
+        setAgent: (agent) => update({ agent }),
+        setVariant: (variant) => update({ variant }),
+    };
+}

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

@@ -0,0 +1,6 @@
+import { type Session } from './use-opencode-sessions/index.js';
+export declare function prefetchSession(sessionId: string, runtimeUrl?: string): Promise<void>;
+export declare function resetPrefetchState(): void;
+export declare function useBackgroundSessionPrefetch(_sessions: Session[] | undefined): {
+    prefetchOnHover: (sessionId: string) => void;
+};

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

@@ -0,0 +1,22 @@
+'use client';
+import { useCallback } from 'react';
+import { ACTIVE_SESSION_PREFETCH_SOURCE, clearActiveSessionPrefetches, prefetchSessionSyncOnce, } from '../browser/session-sync/session-sync-registry.js';
+import { useSandboxConnectionStore } from '../browser/stores/sandbox-connection-store.js';
+import { getClientForUrl } from '../core/runtime/client.js';
+import { canQueryRuntimeSession } from './use-opencode-sessions/index.js';
+export async function prefetchSession(sessionId, runtimeUrl) {
+    if (!canQueryRuntimeSession(sessionId))
+        return;
+    if (!runtimeUrl && useSandboxConnectionStore.getState().healthy !== true)
+        return;
+    await prefetchSessionSyncOnce(sessionId, runtimeUrl ?? ACTIVE_SESSION_PREFETCH_SOURCE, runtimeUrl ? getClientForUrl(runtimeUrl) : undefined);
+}
+export function resetPrefetchState() {
+    clearActiveSessionPrefetches();
+}
+export function useBackgroundSessionPrefetch(_sessions) {
+    const prefetchOnHover = useCallback((sessionId) => {
+        void prefetchSession(sessionId);
+    }, []);
+    return { prefetchOnHover };
+}

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

@@ -0,0 +1,53 @@
+import { type CreateSessionPromptInput, type CreateSessionPromptResult, type RemovedSessionPrompt, type SessionPrompt, type SessionPromptOverrides, type SessionPromptPart, createSessionPrompt } from '../core/rest/projects-client/sessions.js';
+export declare const SESSION_PROMPTS_POLL_MS = 1000;
+export declare const SESSION_PROMPTS_IDLE_POLL_MS = 15000;
+export declare function sessionPromptsPollMs(count: number, pollMs?: number, believedPending?: number): number;
+export declare function noteInboxObservation(sessionId: string, prompts: readonly SessionPrompt[], atMs: number, serverAtMs?: number, drainedAtMs?: number): void;
+export declare function inboxDrained(previous: readonly SessionPrompt[] | undefined, next: readonly SessionPrompt[]): boolean;
+export declare function applyInboxObservation(sessionId: string, cached: readonly SessionPrompt[] | undefined, prompts: readonly SessionPrompt[], atMs: number, serverAtMs?: number): SessionPrompt[];
+export declare function releaseHeldPrompts(prompts: readonly SessionPrompt[]): SessionPrompt[];
+export declare function withEditedPromptText(prompts: readonly SessionPrompt[], promptId: string, text: string): SessionPrompt[];
+export declare function withInterruptedPrompt(prompts: readonly SessionPrompt[], promptId: string): SessionPrompt[];
+export declare const EDITED_PROMPT_OVERLAY_MS = 15000;
+export declare function overlayEditedPrompt(sessionId: string, promptId: string, text: string, nowMs?: number): void;
+export declare function releaseEditedPromptOverlay(sessionId: string, promptId: string): void;
+export declare function withEditedPromptOverlays(sessionId: string, prompts: readonly SessionPrompt[], nowMs?: number): SessionPrompt[];
+export declare const REMOVED_PROMPT_TOMBSTONE_MS = 15000;
+export declare function tombstoneRemovedPrompt(sessionId: string, promptId: string, nowMs?: number): void;
+export declare function releaseRemovedPromptTombstone(sessionId: string, promptId: string): void;
+export declare function withoutRemovedPrompts(sessionId: string, prompts: readonly SessionPrompt[], nowMs?: number): SessionPrompt[];
+export declare function removeFailureKeepsRow(error: unknown): boolean;
+export declare const OPTIMISTIC_PROMPT_PREFIX = "optimistic:";
+export declare function isOptimisticSessionPrompt(prompt: Pick<SessionPrompt, 'prompt_id'>): boolean;
+export declare function optimisticSessionPrompt(input: CreateSessionPromptInput, nowMs: number): SessionPrompt;
+export declare function applyOptimisticPrompt(prompts: readonly SessionPrompt[], input: CreateSessionPromptInput, nowMs: number): SessionPrompt[];
+export declare function settleOptimisticPrompt(prompts: readonly SessionPrompt[], clientMessageId: string, result: CreateSessionPromptResult): SessionPrompt[];
+export declare function removeOptimisticPrompt(prompts: readonly SessionPrompt[], clientMessageId: string): SessionPrompt[];
+export declare function reconcileOptimisticPrompts(cached: readonly SessionPrompt[] | undefined, server: readonly SessionPrompt[]): SessionPrompt[];
+export declare function readSessionPromptsInbox(projectId: string | undefined, sessionId: string | undefined, cached: readonly SessionPrompt[] | undefined): Promise<SessionPrompt[]>;
+export interface UseSessionPromptsResult {
+    prompts: SessionPrompt[];
+    isLoading: boolean;
+    enqueue: (input: CreateSessionPromptInput) => Promise<CreateSessionPromptResult>;
+    remove: (promptId: string) => Promise<RemovedSessionPrompt>;
+    retry: (promptId: string) => Promise<SessionPrompt>;
+    edit: (promptId: string, text: string) => Promise<SessionPrompt>;
+    interrupt: (promptId: string) => Promise<SessionPrompt>;
+    hold: (held: boolean) => Promise<{
+        prompts: SessionPrompt[];
+    }>;
+    refetch: () => Promise<unknown>;
+}
+export declare function useSessionPrompts(projectId: string | undefined, sessionId: string | undefined, options?: {
+    pollMs?: number;
+    enabled?: boolean;
+}): UseSessionPromptsResult;
+export interface StartSessionWithPromptAdapters {
+    create?: typeof createSessionPrompt;
+    nowMs?: () => number;
+}
+export declare function startSessionWithPrompt(projectId: string, sessionId: string, input: {
+    parts: SessionPromptPart[];
+    overrides?: SessionPromptOverrides;
+    clientSentAtMs?: number;
+}, adapters?: StartSessionWithPromptAdapters): Promise<CreateSessionPromptResult>;

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

@@ -0,0 +1,378 @@
+'use client';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { useCallback, useEffect, useState } from 'react';
+import { createSessionPrompt, deleteSessionPrompt, holdSessionPrompts, listSessionPrompts, retrySessionPrompt, editSessionPrompt, interruptSessionPrompt, } from '../core/rest/projects-client/sessions.js';
+import { useSessionWorkingStore } from '../browser/stores/session-working-store.js';
+import { countLiveInboxPrompts, inboxObservationSupersedes } from '../core/session/working.js';
+import { claimOpenBundle, openBundleQueue } from '../core/session/open-bundle.js';
+import { createTickSingleFlight } from '../core/session/single-flight.js';
+import { openSessionControlStream } from '../core/session/control-stream.js';
+import { qk } from './query-keys.js';
+import { usePollOwner } from './use-poll-owner.js';
+import { mintSessionWireMessageId } from './use-opencode-sessions/messages.js';
+export const SESSION_PROMPTS_POLL_MS = 1_000;
+export const SESSION_PROMPTS_IDLE_POLL_MS = 15_000;
+const SESSION_PROMPTS_STREAM_RENOTE_MS = 3_000;
+export function sessionPromptsPollMs(count, pollMs, believedPending = 0) {
+    const live = Math.max(count, believedPending);
+    return live > 0 ? (pollMs ?? SESSION_PROMPTS_POLL_MS) : SESSION_PROMPTS_IDLE_POLL_MS;
+}
+export function noteInboxObservation(sessionId, prompts, atMs, serverAtMs, drainedAtMs) {
+    useSessionWorkingStore
+        .getState()
+        .noteInboxPending(sessionId, countLiveInboxPrompts(prompts), atMs, serverAtMs, drainedAtMs);
+}
+export function inboxDrained(previous, next) {
+    if (!previous || previous.length === 0)
+        return false;
+    const listed = new Set(next.map((p) => p.prompt_id));
+    return previous.some((p) => (p.state === 'queued' || p.state === 'delivering') &&
+        !isOptimisticSessionPrompt(p) &&
+        !listed.has(p.prompt_id));
+}
+export function applyInboxObservation(sessionId, cached, prompts, atMs, serverAtMs) {
+    const current = useSessionWorkingStore.getState().inbox[sessionId];
+    const candidate = {
+        pending: countLiveInboxPrompts(prompts),
+        atMs,
+        ...(serverAtMs != null ? { serverAtMs } : {}),
+    };
+    if (!inboxObservationSupersedes(candidate, current))
+        return [...(cached ?? [])];
+    noteInboxObservation(sessionId, prompts, atMs, serverAtMs, inboxDrained(cached, prompts) ? atMs : undefined);
+    return reconcileOptimisticPrompts(cached, prompts);
+}
+export function releaseHeldPrompts(prompts) {
+    return prompts.map((prompt) => (prompt.reason === 'held' ? { ...prompt, reason: null } : prompt));
+}
+export function withEditedPromptText(prompts, promptId, text) {
+    return prompts.map((prompt) => prompt.prompt_id === promptId ? { ...prompt, text, full_text: text } : prompt);
+}
+export function withInterruptedPrompt(prompts, promptId) {
+    return prompts.map((prompt) => prompt.prompt_id === promptId
+        ? { ...prompt, placement: 'transcript', delivery: 'interrupt' }
+        : prompt);
+}
+export const EDITED_PROMPT_OVERLAY_MS = 15_000;
+const editedPromptOverlays = new Map();
+export function overlayEditedPrompt(sessionId, promptId, text, nowMs = Date.now()) {
+    let session = editedPromptOverlays.get(sessionId);
+    if (!session) {
+        session = new Map();
+        editedPromptOverlays.set(sessionId, session);
+    }
+    session.set(promptId, { text, expiresAtMs: nowMs + EDITED_PROMPT_OVERLAY_MS });
+}
+export function releaseEditedPromptOverlay(sessionId, promptId) {
+    const session = editedPromptOverlays.get(sessionId);
+    if (!session)
+        return;
+    session.delete(promptId);
+    if (session.size === 0)
+        editedPromptOverlays.delete(sessionId);
+}
+export function withEditedPromptOverlays(sessionId, prompts, nowMs = Date.now()) {
+    const session = editedPromptOverlays.get(sessionId);
+    if (!session)
+        return [...prompts];
+    let edited = [...prompts];
+    for (const [promptId, overlay] of session) {
+        if (overlay.expiresAtMs <= nowMs)
+            session.delete(promptId);
+        else
+            edited = withEditedPromptText(edited, promptId, overlay.text);
+    }
+    if (session.size === 0)
+        editedPromptOverlays.delete(sessionId);
+    return edited;
+}
+export const REMOVED_PROMPT_TOMBSTONE_MS = 15_000;
+const removedPromptTombstones = new Map();
+export function tombstoneRemovedPrompt(sessionId, promptId, nowMs = Date.now()) {
+    let session = removedPromptTombstones.get(sessionId);
+    if (!session) {
+        session = new Map();
+        removedPromptTombstones.set(sessionId, session);
+    }
+    session.set(promptId, nowMs + REMOVED_PROMPT_TOMBSTONE_MS);
+}
+export function releaseRemovedPromptTombstone(sessionId, promptId) {
+    const session = removedPromptTombstones.get(sessionId);
+    if (!session)
+        return;
+    session.delete(promptId);
+    if (session.size === 0)
+        removedPromptTombstones.delete(sessionId);
+}
+export function withoutRemovedPrompts(sessionId, prompts, nowMs = Date.now()) {
+    const session = removedPromptTombstones.get(sessionId);
+    if (!session)
+        return [...prompts];
+    for (const [promptId, expiresAtMs] of session) {
+        if (expiresAtMs <= nowMs)
+            session.delete(promptId);
+    }
+    if (session.size === 0) {
+        removedPromptTombstones.delete(sessionId);
+        return [...prompts];
+    }
+    return prompts.filter((prompt) => !session.has(prompt.prompt_id));
+}
+export function removeFailureKeepsRow(error) {
+    return error?.status !== 404;
+}
+export const OPTIMISTIC_PROMPT_PREFIX = 'optimistic:';
+export function isOptimisticSessionPrompt(prompt) {
+    return prompt.prompt_id.startsWith(OPTIMISTIC_PROMPT_PREFIX);
+}
+export function optimisticSessionPrompt(input, nowMs) {
+    const text = input.parts
+        .filter((part) => part.type === 'text' && typeof part.text === 'string')
+        .map((part) => part.text)
+        .join('\n')
+        .trim();
+    const at = new Date(nowMs).toISOString();
+    return {
+        prompt_id: `${OPTIMISTIC_PROMPT_PREFIX}${input.clientMessageId}`,
+        placement: input.placement ??
+            (input.delivery ? (input.delivery === 'interrupt' ? 'transcript' : 'composer') : undefined),
+        ...(input.delivery ? { delivery: input.delivery } : {}),
+        full_text: text,
+        client_message_id: input.clientMessageId,
+        message_id: input.messageId,
+        state: 'queued',
+        reason: null,
+        text,
+        attempts: 0,
+        last_error: null,
+        created_at: at,
+        available_at: at,
+    };
+}
+export function applyOptimisticPrompt(prompts, input, nowMs) {
+    if (prompts.some((p) => p.client_message_id === input.clientMessageId))
+        return [...prompts];
+    return [...prompts, optimisticSessionPrompt(input, nowMs)];
+}
+export function settleOptimisticPrompt(prompts, clientMessageId, result) {
+    return prompts.map((p) => p.client_message_id === clientMessageId && isOptimisticSessionPrompt(p)
+        ? { ...p, prompt_id: result.prompt_id, state: result.state, message_id: result.message_id }
+        : p);
+}
+export function removeOptimisticPrompt(prompts, clientMessageId) {
+    return prompts.filter((p) => !(p.client_message_id === clientMessageId && isOptimisticSessionPrompt(p)));
+}
+export function reconcileOptimisticPrompts(cached, server) {
+    const listed = new Set(server.map((p) => p.client_message_id).filter(Boolean));
+    const pending = (cached ?? []).filter((p) => isOptimisticSessionPrompt(p) && !listed.has(p.client_message_id));
+    return pending.length ? [...server, ...pending] : [...server];
+}
+export async function readSessionPromptsInbox(projectId, sessionId, cached) {
+    if (!projectId || !sessionId)
+        return [...(cached ?? [])];
+    const claimed = cached === undefined ? claimOpenBundle(projectId, sessionId) : null;
+    if (claimed) {
+        const bundle = await claimed;
+        const bundledRows = bundle ? openBundleQueue(bundle) : null;
+        const bundled = bundledRows
+            ? withEditedPromptOverlays(sessionId, withoutRemovedPrompts(sessionId, bundledRows))
+            : null;
+        if (bundled) {
+            const observedAtMs = Date.parse(bundle.observed_at);
+            return applyInboxObservation(sessionId, cached, bundled, Date.now(), Number.isFinite(observedAtMs) ? observedAtMs : undefined);
+        }
+    }
+    const { atMs, prompts, observed_at } = await promptReads(`${projectId}/${sessionId}`, async () => {
+        const issuedAtMs = Date.now();
+        const listed = await listSessionPrompts(projectId, sessionId);
+        return { atMs: issuedAtMs, prompts: listed.prompts, observed_at: listed.observed_at };
+    });
+    const serverAtMs = observed_at ? Date.parse(observed_at) : Number.NaN;
+    return applyInboxObservation(sessionId, cached, withEditedPromptOverlays(sessionId, withoutRemovedPrompts(sessionId, prompts)), atMs, Number.isFinite(serverAtMs) ? serverAtMs : undefined);
+}
+const promptReads = createTickSingleFlight();
+export function useSessionPrompts(projectId, sessionId, options) {
+    const queryClient = useQueryClient();
+    const enabled = options?.enabled !== false && !!projectId && !!sessionId;
+    const key = qk.project.sessionPrompts(projectId ?? '', sessionId ?? '');
+    const believedPending = useSessionWorkingStore((state) => (sessionId ? (state.inbox[sessionId]?.pending ?? 0) : 0));
+    const pollOwner = usePollOwner(`prompts:${projectId ?? ''}/${sessionId ?? ''}`, enabled);
+    const [streamConnected, setStreamConnected] = useState(false);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        let hadConnection = false;
+        const stream = openSessionControlStream({
+            projectId: projectId,
+            sessionId: sessionId,
+            onQueue: (queue) => {
+                const serverAtMs = queue.observed_at ? Date.parse(queue.observed_at) : Number.NaN;
+                queryClient.setQueryData(key, (cached) => applyInboxObservation(sessionId, cached, withEditedPromptOverlays(sessionId, withoutRemovedPrompts(sessionId, queue.prompts)), Date.now(), Number.isFinite(serverAtMs) ? serverAtMs : undefined));
+            },
+            onConnectionChange: (connected) => {
+                setStreamConnected(connected);
+                if (connected && hadConnection)
+                    void queryClient.invalidateQueries({ queryKey: key });
+                hadConnection ||= connected;
+            },
+        });
+        setStreamConnected(stream.connected());
+        return () => {
+            stream.close();
+            setStreamConnected(false);
+        };
+    }, [enabled, projectId, sessionId, queryClient]);
+    useEffect(() => {
+        if (!enabled || !pollOwner || !streamConnected)
+            return;
+        const stream = openSessionControlStream({ projectId: projectId, sessionId: sessionId });
+        const timer = setInterval(() => {
+            const last = stream.lastQueue();
+            if (!last || !stream.connected())
+                return;
+            const serverAtMs = last.observed_at ? Date.parse(last.observed_at) : Number.NaN;
+            noteInboxObservation(sessionId, withoutRemovedPrompts(sessionId, last.prompts), Date.now(), Number.isFinite(serverAtMs) ? serverAtMs : undefined);
+        }, SESSION_PROMPTS_STREAM_RENOTE_MS);
+        return () => {
+            clearInterval(timer);
+            stream.close();
+        };
+    }, [enabled, pollOwner, streamConnected, projectId, sessionId]);
+    const query = useQuery({
+        queryKey: key,
+        enabled,
+        queryFn: () => readSessionPromptsInbox(projectId, sessionId, queryClient.getQueryData(key)),
+        refetchInterval: (q) => pollOwner && !streamConnected
+            ? sessionPromptsPollMs(q.state.data?.length ?? 0, options?.pollMs, believedPending)
+            : false,
+        refetchOnWindowFocus: true,
+    });
+    const queryRefetch = query.refetch;
+    const refetch = useCallback(() => (enabled ? queryRefetch() : Promise.resolve(undefined)), [enabled, queryRefetch]);
+    const invalidate = useCallback(() => queryClient.invalidateQueries({ queryKey: key }), [queryClient, projectId, sessionId]);
+    const enqueueMutation = useMutation({
+        onMutate: async (input) => {
+            queryClient.setQueryData(key, (prev) => applyOptimisticPrompt(prev ?? [], input, Date.now()));
+            useSessionWorkingStore.getState().notePromptAccepted(sessionId, Date.now());
+            await queryClient.cancelQueries({ queryKey: key });
+        },
+        mutationFn: async (input) => {
+            const result = await createSessionPrompt(projectId, sessionId, input);
+            if (result.state !== 'failed') {
+                const serverAtMs = result.observed_at ? Date.parse(result.observed_at) : Number.NaN;
+                useSessionWorkingStore
+                    .getState()
+                    .notePromptAccepted(sessionId, Date.now(), Number.isFinite(serverAtMs) ? serverAtMs : undefined);
+            }
+            return result;
+        },
+        onSuccess: (result, input) => {
+            queryClient.setQueryData(key, (prev) => result.state === 'failed'
+                ? removeOptimisticPrompt(prev ?? [], input.clientMessageId)
+                : settleOptimisticPrompt(prev ?? [], input.clientMessageId, result));
+        },
+        onError: (_error, input) => {
+            queryClient.setQueryData(key, (prev) => removeOptimisticPrompt(prev ?? [], input.clientMessageId));
+        },
+        onSettled: invalidate,
+    });
+    const removeMutation = useMutation({
+        onMutate: async (promptId) => {
+            tombstoneRemovedPrompt(sessionId, promptId);
+            queryClient.setQueryData(key, (prev) => (prev ?? []).filter((prompt) => prompt.prompt_id !== promptId));
+            await queryClient.cancelQueries({ queryKey: key });
+        },
+        mutationFn: (promptId) => deleteSessionPrompt(projectId, sessionId, promptId),
+        onError: (error, promptId) => {
+            if (removeFailureKeepsRow(error))
+                releaseRemovedPromptTombstone(sessionId, promptId);
+        },
+        onSettled: invalidate,
+    });
+    const retryMutation = useMutation({
+        mutationFn: (promptId) => retrySessionPrompt(projectId, sessionId, promptId),
+        onError: () => { },
+        onSettled: invalidate,
+    });
+    const editMutation = useMutation({
+        onMutate: async ({ promptId, text }) => {
+            overlayEditedPrompt(sessionId, promptId, text);
+            await queryClient.cancelQueries({ queryKey: key });
+            queryClient.setQueryData(key, (prev) => withEditedPromptText(prev ?? [], promptId, text));
+        },
+        mutationFn: ({ promptId, text }) => editSessionPrompt(projectId, sessionId, promptId, text),
+        onError: (_error, { promptId }) => releaseEditedPromptOverlay(sessionId, promptId),
+        onSettled: async (_data, _error, { promptId }) => {
+            await invalidate();
+            releaseEditedPromptOverlay(sessionId, promptId);
+        },
+    });
+    const interruptMutation = useMutation({
+        onMutate: async (promptId) => {
+            await queryClient.cancelQueries({ queryKey: key });
+            queryClient.setQueryData(key, (prev) => withInterruptedPrompt(prev ?? [], promptId));
+        },
+        mutationFn: (promptId) => interruptSessionPrompt(projectId, sessionId, promptId),
+        onError: () => { },
+        onSettled: invalidate,
+    });
+    const holdMutation = useMutation({
+        onMutate: async (held) => {
+            if (held)
+                return;
+            await queryClient.cancelQueries({ queryKey: key });
+            queryClient.setQueryData(key, (prev) => releaseHeldPrompts(prev ?? []));
+        },
+        mutationFn: (held) => holdSessionPrompts(projectId, sessionId, held),
+        onSuccess: (result) => {
+            const serverAtMs = result.observed_at ? Date.parse(result.observed_at) : Number.NaN;
+            queryClient.setQueryData(key, (prev) => applyInboxObservation(sessionId, prev, withEditedPromptOverlays(sessionId, withoutRemovedPrompts(sessionId, result.prompts)), Date.now(), Number.isFinite(serverAtMs) ? serverAtMs : undefined));
+        },
+        onError: () => { },
+        onSettled: invalidate,
+    });
+    return {
+        prompts: query.data ?? [],
+        isLoading: query.isLoading,
+        enqueue: enqueueMutation.mutateAsync,
+        remove: removeMutation.mutateAsync,
+        retry: retryMutation.mutateAsync,
+        edit: (promptId, text) => editMutation.mutateAsync({ promptId, text }),
+        interrupt: interruptMutation.mutateAsync,
+        hold: holdMutation.mutateAsync,
+        refetch,
+    };
+}
+export async function startSessionWithPrompt(projectId, sessionId, input, adapters) {
+    const create = adapters?.create ?? createSessionPrompt;
+    const now = adapters?.nowMs ?? Date.now;
+    const clientMessageId = typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+        ? `start_${crypto.randomUUID()}`
+        : `start_${now()}_${Math.random().toString(36).slice(2, 10)}`;
+    const store = useSessionWorkingStore.getState();
+    store.noteSendReceipt(sessionId, { messageId: clientMessageId, atMs: now() });
+    try {
+        const result = await create(projectId, sessionId, {
+            clientMessageId,
+            messageId: mintSessionWireMessageId(sessionId, clientMessageId),
+            parts: input.parts,
+            clientSentAtMs: input.clientSentAtMs ?? now(),
+            ...(input.overrides ? { overrides: input.overrides } : {}),
+            remintOnDelivery: true,
+        });
+        if (result.state === 'failed') {
+            throw new Error('This prompt was refused — its earlier delivery already failed.');
+        }
+        const acceptedAt = now();
+        const serverAtMs = result.observed_at ? Date.parse(result.observed_at) : Number.NaN;
+        useSessionWorkingStore.getState().acceptSendReceipt(sessionId, clientMessageId, acceptedAt);
+        useSessionWorkingStore
+            .getState()
+            .notePromptAccepted(sessionId, acceptedAt, Number.isFinite(serverAtMs) ? serverAtMs : undefined);
+        return result;
+    }
+    catch (error) {
+        useSessionWorkingStore.getState().clearSendReceipt(sessionId, clientMessageId);
+        throw error;
+    }
+}

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

@@ -0,0 +1,97 @@
+import { type BeeuniSendError } from './use-session.js';
+import { type AbortSettlement, type PromptPart, type SendMessageOptions } from './use-opencode-sessions/index.js';
+import { type StartStash } from './session-start-stash.js';
+export { applyOptimisticAbort, STOP_HOLD_DEADLINE_MS, stopWithReceipt, type StopWithReceiptOptions, } from './session-stop.js';
+export declare function beginOptimisticSend(sessionId: string, messageId: string, text: string, partIds?: string[]): void;
+export declare function markOptimisticSendDispatched(sessionId: string, messageId: string): void;
+export declare function markOptimisticSendInboxBacked(sessionId: string, messageId: string): void;
+export declare function abandonOptimisticSend(sessionId: string, messageId: string): void;
+export interface RuntimeMessagesClient {
+    session: {
+        messages: (args: {
+            sessionID: string;
+            limit?: number;
+        }) => Promise<{
+            data?: unknown;
+        }>;
+    };
+}
+export interface SendRecoveryOptions {
+    getClient?: () => RuntimeMessagesClient;
+    classify?: (error: unknown) => BeeuniSendError;
+    inboxRowExists?: () => Promise<boolean>;
+}
+export declare function recoverFromSendFailure(sessionId: string, messageId: string, error: unknown, options?: SendRecoveryOptions): BeeuniSendError;
+export interface SendAndRecoverArgs {
+    sessionId: string;
+    messageId: string;
+    parts: PromptPart[];
+    options?: SendMessageOptions;
+    clientMessageId?: string;
+    getClient?: () => RuntimeMessagesClient;
+    classify?: (error: unknown) => BeeuniSendError;
+}
+export type SendAndRecoverResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: BeeuniSendError;
+    cause: unknown;
+};
+export declare function sendAndRecover(args: SendAndRecoverArgs): Promise<SendAndRecoverResult>;
+export type StashReplayTimerHandle = unknown;
+export interface StashReplayTimers {
+    setTimeout: (handler: () => void, ms: number) => StashReplayTimerHandle;
+    clearTimeout: (handle: StashReplayTimerHandle | undefined) => void;
+}
+export interface PreparedStashSend {
+    messageId: string;
+    optimisticText: string;
+    partIds?: string[];
+    sendOptions?: SendMessageOptions;
+    buildParts: () => Promise<PromptPart[]>;
+}
+export interface StartStashReplayOptions<TReady> {
+    sessionId: string;
+    readStash?: (sessionId: string) => StartStash | null;
+    writeRaceAttempts?: number;
+    writeRaceIntervalMs?: number;
+    checkReadiness: (stash: StartStash) => TReady | null;
+    readinessAttempts?: number;
+    readinessIntervalMs?: number;
+    onReadinessTimeout?: (stash: StartStash) => void;
+    prepare: (stash: StartStash, ready: TReady) => PreparedStashSend;
+    onFailure?: (stash: StartStash, error: unknown, classified: BeeuniSendError) => void;
+    onSuccess?: (stash: StartStash) => void;
+    getClient?: () => RuntimeMessagesClient;
+    classify?: (error: unknown) => BeeuniSendError;
+    timers?: StashReplayTimers;
+}
+export interface StartStashReplayHandle {
+    cancel: () => void;
+}
+export declare function replayStartStash<TReady>(options: StartStashReplayOptions<TReady>): StartStashReplayHandle;
+export interface SendWithReceiptArgs extends SendAndRecoverArgs {
+    workingSessionId?: string;
+}
+export declare function sendWithReceipt(args: SendWithReceiptArgs): Promise<SendAndRecoverResult>;
+export interface UseSessionSendOptions {
+    getClient?: () => RuntimeMessagesClient;
+    classify?: (error: unknown) => BeeuniSendError;
+    workingSessionId?: string;
+    projectId?: string;
+}
+export interface SendCallOptions {
+    messageId?: string;
+    optimisticText?: string;
+    partIds?: string[];
+}
+export interface UseSessionSendResult {
+    send: (parts: PromptPart[], options?: SendMessageOptions, callOptions?: SendCallOptions) => Promise<SendAndRecoverResult>;
+    stop: () => Promise<AbortSettlement>;
+    isSending: boolean;
+    isStopping: boolean;
+    sendError: BeeuniSendError | null;
+}
+export declare function useSessionSend(sessionId: string, options?: UseSessionSendOptions): UseSessionSendResult;
+export type OpenCodeMessagesClient = RuntimeMessagesClient;