@fungi.computer/parakeet 0.0.0-stage → 0.1.0

package/dist/conversation.js

@@ -0,0 +1,762 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { noAuthor } from "./core/author-labels.js";
+import { nanoid } from "@fungi.computer/cairn";
+import {} from "@fungi.computer/shiitake/client";
+import { createClientContributions, } from "./core/client-contributions.js";
+import { createParakeetInteractions, } from "./commands/interactions.js";
+import { CancelledError, useQueryClient, } from "@tanstack/react-query";
+import { atom, createStore, } from "jotai/vanilla";
+import { atomWithInfiniteQuery, atomWithMutation, atomWithQuery, } from "jotai-tanstack-query";
+import { createContext, useCallback, useContext, useEffect, useMemo, useSyncExternalStore, } from "react";
+import { buildDurableTimeline, buildTimelineTail, } from "./core/build-timeline.js";
+import { mergeCompactionNotices, mergeCompactions, mergeMessages, } from "./core/session-projection.js";
+import { sessionHistoryQueryOptions, sessionQueryOptions, } from "./core/session-query.js";
+import { sameSessionViewState, sessionActivityStatus, sessionViewState, } from "./core/session-view-state.js";
+import { isCancelledOutcome } from "./commands/run.js";
+import { reportFailure } from "./lib/failure.js";
+const noMessages = Object.freeze([]);
+const noCompactions = Object.freeze([]);
+const noCompactionNotices = Object.freeze([]);
+const noClients = Object.freeze([]);
+const noContributions = Object.freeze([]);
+const noSlots = Object.freeze({});
+const noPending = Object.freeze({
+    total: 0,
+    hasMore: false,
+    prompts: Object.freeze([]),
+});
+const connecting = Object.freeze({ status: "connecting" });
+const live = Object.freeze({ status: "live" });
+const MAX_UNRESOLVED_LOCAL_ADMISSIONS = 32;
+function errorMessage(cause) {
+    return cause instanceof Error && cause.message.trim().length > 0
+        ? cause.message
+        : "Prompt admission failed";
+}
+function observationCause(cause) {
+    const message = cause instanceof Error && cause.message.trim().length > 0
+        ? cause.message.trim()
+        : "Session history is unavailable";
+    return message.slice(0, 500);
+}
+/**
+ * Show Shiitake's Session status as-is; local admission state only refines an
+ * owner-reported `idle`.
+ */
+function composerStatus(snapshot, admissions, failure) {
+    if (snapshot === undefined)
+        return "connecting";
+    const view = sessionViewState(snapshot);
+    const status = sessionActivityStatus(view);
+    if (status !== "idle")
+        return status;
+    if (failure !== undefined || view.kind === "error")
+        return "error";
+    if (admissions.some(({ status: state }) => state === "accepted"))
+        return "queued";
+    if (admissions.some(({ status: state }) => state === "admitting"))
+        return "sending";
+    return status;
+}
+function newestDurableCommandId(messages) {
+    if (messages === undefined)
+        return undefined;
+    let newest;
+    for (const message of messages) {
+        if (message.value.role !== "user" || message.commandId === null)
+            continue;
+        if (newest === undefined || message.sequence > newest.sequence)
+            newest = { commandId: message.commandId, sequence: message.sequence };
+    }
+    return newest?.commandId;
+}
+function newestDurablePrompt(messages, commandId) {
+    const message = messages.find((candidate) => candidate.commandId === commandId && candidate.value.role === "user");
+    if (message?.value.role !== "user")
+        return undefined;
+    const content = message.value.content;
+    const text = Array.isArray(content)
+        ? content
+            .flatMap((part) => (part.type === "text" ? [part.text] : []))
+            .join("\n")
+        : content;
+    return text.trim() === "" ? undefined : text;
+}
+function createConversationAtoms(session, queryClient, authorOf) {
+    const queryAtom = atomWithQuery(() => sessionQueryOptions(session), () => queryClient);
+    const snapshotAtom = atom((get) => get(queryAtom).data?.snapshot);
+    const pinnedHistoryAtom = atom(undefined);
+    const historyBeforeAtom = atom((get) => (get(pinnedHistoryAtom) ?? get(snapshotAtom))?.oldestCursor ?? null);
+    const historyAtom = atomWithInfiniteQuery((get) => sessionHistoryQueryOptions(session, get(historyBeforeAtom)), () => queryClient);
+    const hasMoreHistoryAtom = atom((get) => {
+        const history = get(historyAtom);
+        return history.data === undefined
+            ? get(historyBeforeAtom) !== null
+            : history.hasNextPage;
+    });
+    const loadingOlderHistoryAtom = atom((get) => get(historyAtom).isFetching);
+    const hasNewerHistoryAtom = atom((get) => {
+        const history = get(historyAtom);
+        return history.hasPreviousPage || history.data?.newerOverflow === true;
+    });
+    const loadOlderHistoryAtom = atom(null, (get) => {
+        if (!get(hasMoreHistoryAtom) || get(loadingOlderHistoryAtom))
+            return;
+        void get(historyAtom)
+            .fetchNextPage({ cancelRefetch: false, throwOnError: true })
+            .catch((cause) => {
+            if (!(cause instanceof CancelledError))
+                reportFailure("read older Session history", cause);
+        });
+    });
+    const jumpToLatestAtom = atom(null, (_get, set) => {
+        set(pinnedHistoryAtom, undefined);
+        void queryClient.resetQueries({
+            queryKey: sessionHistoryQueryOptions(session).queryKey,
+            exact: true,
+        });
+    });
+    const loadNewerHistoryAtom = atom(null, (get, set) => {
+        const history = get(historyAtom);
+        if (history.isFetching)
+            return;
+        if (!history.hasPreviousPage) {
+            if (get(hasNewerHistoryAtom))
+                set(jumpToLatestAtom);
+            return;
+        }
+        void history
+            .fetchPreviousPage({ cancelRefetch: false, throwOnError: true })
+            .catch((cause) => {
+            if (!(cause instanceof CancelledError))
+                reportFailure("read newer Session history", cause);
+        });
+    });
+    const pinVisibleHistoryAtom = atom(null, (get, set) => {
+        if (get(pinnedHistoryAtom) === undefined)
+            set(pinnedHistoryAtom, get(snapshotAtom));
+    });
+    const messagesAtom = atom((get) => {
+        const history = get(historyAtom);
+        const live = get(snapshotAtom)?.messages ?? noMessages;
+        const pages = history.data?.pages.flatMap((page) => page.messages) ?? noMessages;
+        const pinned = get(pinnedHistoryAtom)?.messages ?? noMessages;
+        if (pages.length === 0)
+            return pinned.length === 0 ? live : mergeMessages(pinned, live);
+        return get(hasNewerHistoryAtom)
+            ? pages
+            : mergeMessages(mergeMessages(pages, pinned), live);
+    });
+    const compactionsAtom = atom((get) => {
+        const history = get(historyAtom);
+        const live = get(snapshotAtom)?.compactions ?? noCompactions;
+        const pages = history.data?.pages.flatMap((page) => page.compactions ?? noCompactions) ?? noCompactions;
+        const pinned = get(pinnedHistoryAtom)?.compactions ?? noCompactions;
+        if (pages.length === 0)
+            return pinned.length === 0 ? live : mergeCompactions(pinned, live);
+        return get(hasNewerHistoryAtom)
+            ? pages
+            : mergeCompactions(mergeCompactions(pages, pinned), live);
+    });
+    const compactionNoticesAtom = atom((get) => {
+        const history = get(historyAtom);
+        const live = get(snapshotAtom)?.compactionNotices ?? noCompactionNotices;
+        const pages = history.data?.pages.flatMap((page) => page.compactionNotices ?? noCompactionNotices) ?? noCompactionNotices;
+        const pinned = get(pinnedHistoryAtom)?.compactionNotices ?? noCompactionNotices;
+        if (pages.length === 0)
+            return pinned.length === 0 ? live : mergeCompactionNotices(pinned, live);
+        return get(hasNewerHistoryAtom)
+            ? pages
+            : mergeCompactionNotices(mergeCompactionNotices(pages, pinned), live);
+    });
+    const newestCommandAtom = atom((get) => get(queryAtom).data?.latestPrompt?.[0] ??
+        newestDurableCommandId(get(messagesAtom)));
+    const pendingAtom = atom((get) => get(snapshotAtom)?.pending ?? noPending);
+    const extensionsAtom = atom((get) => get(snapshotAtom)?.extensions ?? noSlots);
+    let liveToolActivity;
+    const toolActivityAtom = atom((get) => {
+        const query = get(queryAtom);
+        const activity = get(snapshotAtom)?.activity;
+        if (query.isError ||
+            query.data?.observation !== "live" ||
+            activity?.queue.state !== "running" ||
+            activity.activeTool === null) {
+            liveToolActivity = undefined;
+            return undefined;
+        }
+        if (liveToolActivity?.queue.state === "running" &&
+            liveToolActivity.queue.commandId === activity.queue.commandId &&
+            liveToolActivity.activeTool === activity.activeTool)
+            return liveToolActivity;
+        liveToolActivity = activity;
+        return liveToolActivity;
+    });
+    /** Each accepted local prompt's request identity, by its owner command. */
+    const promptRequestIdsAtom = atom(new Map());
+    const requestIdOfAtom = atom((get) => {
+        const requestIds = get(promptRequestIdsAtom);
+        return (commandId) => requestIds.get(commandId);
+    });
+    const durableAtom = atom((get) => buildDurableTimeline(get(messagesAtom), get(compactionsAtom), get(toolActivityAtom), authorOf, get(requestIdOfAtom), get(compactionNoticesAtom)));
+    const draftAtom = atom("");
+    const draftRevisionAtom = atom(0);
+    const rawAdmissionsAtom = atom([]);
+    const latestSubmissionIdAtom = atom(undefined);
+    const observedCommandIdsAtom = atom((get) => new Set([
+        ...get(durableAtom).commandIds,
+        ...get(pendingAtom).prompts.map(({ commandId }) => commandId),
+        ...(get(snapshotAtom)?.terminals.map(({ commandId }) => commandId) ??
+            []),
+    ]));
+    const admissionsAtom = atom((get) => {
+        const knownCommandIds = get(observedCommandIdsAtom);
+        return get(rawAdmissionsAtom).filter((admission) => admission.status === "failed" ||
+            admission.commandId === undefined ||
+            !knownCommandIds.has(admission.commandId));
+    });
+    /** Retire a successful local admission only after owner identity is observed. */
+    const reconcileAdmissionsAtom = atom(null, (get, set) => {
+        const knownCommandIds = get(observedCommandIdsAtom);
+        set(rawAdmissionsAtom, (current) => {
+            const unresolved = current.filter(({ status, commandId }) => status !== "accepted" ||
+                commandId === undefined ||
+                !knownCommandIds.has(commandId));
+            return unresolved.length === current.length ? current : unresolved;
+        });
+    });
+    const admissionErrorAtom = atom(undefined);
+    const setDraftAtom = atom(null, (get, set, value) => {
+        if (get(draftAtom) !== value)
+            set(draftRevisionAtom, (revision) => revision + 1);
+        set(draftAtom, value);
+        set(admissionErrorAtom, undefined);
+    });
+    /** The one owner of "clear the draft after submit" for prompts and commands. */
+    const clearSubmittedDraftAtom = atom(null, (get, set, submitted) => {
+        if (get(draftRevisionAtom) !== submitted.revision)
+            return;
+        set(draftAtom, (current) => (current === submitted.draft ? "" : current));
+    });
+    const abortAtom = atomWithMutation(() => ({
+        mutationFn: (commandId) => session.command({ type: "cancel", commandId }),
+    }), () => queryClient);
+    const tailAtom = atom((get) => {
+        if (get(hasNewerHistoryAtom))
+            return [];
+        const snapshot = get(snapshotAtom);
+        const pending = get(pendingAtom);
+        return buildTimelineTail(get(durableAtom), snapshot?.progress ?? null, pending.prompts, get(admissionsAtom), authorOf, get(requestIdOfAtom));
+    });
+    const timelineAtom = atom((get) => {
+        const durable = get(durableAtom);
+        const base = {
+            pendingHasMore: get(pendingAtom).hasMore,
+            queued: get(pendingAtom),
+            commandAnchors: durable.commandAnchors,
+            hasMoreHistory: get(hasMoreHistoryAtom),
+            hasNewerHistory: get(hasNewerHistoryAtom),
+            loadingOlderHistory: get(loadingOlderHistoryAtom),
+            settled: durable.items,
+            tail: get(tailAtom),
+        };
+        return durable.model === undefined || durable.usage === undefined
+            ? base
+            : { ...base, model: durable.model, usage: durable.usage };
+    });
+    const failureAtom = atom((get) => {
+        const admissions = get(admissionsAtom);
+        const snapshot = get(snapshotAtom);
+        const pending = get(pendingAtom);
+        const latestSubmission = get(rawAdmissionsAtom).find(({ requestId }) => requestId === get(latestSubmissionIdAtom));
+        const promptPending = pending.prompts.length > 0 ||
+            admissions.some(({ status }) => status !== "failed");
+        if (latestSubmission?.status === "failed" &&
+            snapshot !== undefined &&
+            sessionActivityStatus(sessionViewState(snapshot)) === "idle" &&
+            !promptPending)
+            return "admission";
+        if (latestSubmission?.status === "admitting" ||
+            (latestSubmission?.status === "accepted" &&
+                !get(durableAtom).commandIds.has(latestSubmission.commandId ?? "") &&
+                !pending.prompts.some(({ commandId }) => commandId === latestSubmission.commandId) &&
+                !snapshot?.terminals.some(({ commandId }) => commandId === latestSubmission.commandId)))
+            return undefined;
+        if (promptPending)
+            return undefined;
+        const newestCommandId = get(newestCommandAtom);
+        const outcome = snapshot?.terminals.find(({ commandId }) => commandId === newestCommandId)?.outcome;
+        return outcome === "completed" ? undefined : outcome;
+    });
+    const observationAtom = atom((get) => {
+        const query = get(queryAtom);
+        if (query.isError)
+            return {
+                status: "unavailable",
+                reason: query.error instanceof Error && query.error.message.trim().length > 0
+                    ? query.error.message
+                    : "Session history is unavailable",
+            };
+        return query.data?.observation === "live" ? live : connecting;
+    });
+    const statusAtom = atom((get) => {
+        if (get(observationAtom).status === "unavailable")
+            return "disconnected";
+        if (get(observationAtom).status === "connecting")
+            return "connecting";
+        return composerStatus(get(snapshotAtom), get(admissionsAtom), get(failureAtom));
+    });
+    const contextAtom = atom((get) => get(snapshotAtom)?.context);
+    const commandIdAtom = atom((get) => {
+        const queue = get(snapshotAtom)?.activity.queue;
+        return queue?.state === "idle" ? undefined : queue?.commandId;
+    });
+    let ownerView;
+    const viewStateAtom = atom((get) => {
+        const observation = get(observationAtom);
+        if (observation.status === "unavailable")
+            return { kind: "disconnected", cause: observation.reason };
+        if (observation.status === "connecting")
+            return { kind: "connecting" };
+        if (get(failureAtom) === "admission") {
+            const failed = [...get(rawAdmissionsAtom)]
+                .reverse()
+                .find((admission) => admission.status === "failed");
+            return {
+                kind: "error",
+                cause: (failed?.error ?? "Prompt admission failed").slice(0, 200),
+            };
+        }
+        const snapshot = get(snapshotAtom);
+        if (snapshot === undefined)
+            return { kind: "connecting" };
+        const next = sessionViewState(snapshot);
+        // Keep the readout stable while its meaning is unchanged.
+        if (ownerView !== undefined && sameSessionViewState(ownerView, next))
+            return ownerView;
+        ownerView = next;
+        return next;
+    });
+    const dispatchAdmissionAtom = atom(null, (get, set, admission) => {
+        void session
+            .command({
+            type: "prompt",
+            text: admission.content,
+            requestId: admission.requestId,
+            delivery: admission.delivery,
+        })
+            .then((accepted) => {
+            if (accepted.status === "recorded") {
+                set(rawAdmissionsAtom, (current) => current.filter((candidate) => candidate.requestId !== admission.requestId));
+                set(clearSubmittedDraftAtom, {
+                    draft: admission.submittedDraft,
+                    revision: admission.submittedDraftRevision,
+                });
+                return;
+            }
+            set(promptRequestIdsAtom, (current) => new Map(current).set(accepted.commandId, admission.requestId));
+            set(rawAdmissionsAtom, (current) => current.map((candidate) => candidate.requestId === admission.requestId
+                ? {
+                    requestId: candidate.requestId,
+                    content: candidate.content,
+                    submittedDraft: candidate.submittedDraft,
+                    submittedDraftRevision: candidate.submittedDraftRevision,
+                    delivery: candidate.delivery,
+                    commandId: accepted.commandId,
+                    status: "accepted",
+                }
+                : candidate));
+            const admissions = get(rawAdmissionsAtom);
+            const admissionIndex = admissions.findIndex((candidate) => candidate.requestId === admission.requestId);
+            const hasNewerMatchingAdmission = admissions
+                .slice(admissionIndex + 1)
+                .some((candidate) => candidate.status === "admitting" &&
+                candidate.submittedDraft === admission.submittedDraft);
+            set(reconcileAdmissionsAtom);
+            if (!hasNewerMatchingAdmission)
+                set(clearSubmittedDraftAtom, {
+                    draft: admission.submittedDraft,
+                    revision: admission.submittedDraftRevision,
+                });
+        })
+            .catch((cause) => {
+            set(rawAdmissionsAtom, (current) => current.map((candidate) => candidate.requestId === admission.requestId
+                ? {
+                    ...candidate,
+                    status: "failed",
+                    error: errorMessage(cause),
+                }
+                : candidate));
+        });
+    });
+    const sendAtom = atom(null, (get, set, delivery = "steer") => {
+        const draft = get(draftAtom);
+        const content = draft.trim();
+        if (content === "")
+            return;
+        const admissions = get(admissionsAtom);
+        const draftRevision = get(draftRevisionAtom);
+        const rawAdmissions = get(rawAdmissionsAtom);
+        if (rawAdmissions.some((admission) => admission.status === "admitting" &&
+            admission.submittedDraft === draft &&
+            admission.submittedDraftRevision === draftRevision))
+            return;
+        const unresolved = admissions.filter(({ status }) => status !== "failed");
+        if (unresolved.length >= MAX_UNRESOLVED_LOCAL_ADMISSIONS) {
+            set(admissionErrorAtom, "queue_full");
+            return;
+        }
+        const admission = {
+            content,
+            delivery,
+            requestId: nanoid(),
+            submittedDraft: draft,
+            submittedDraftRevision: draftRevision,
+            status: "admitting",
+        };
+        set(rawAdmissionsAtom, [...admissions, admission]);
+        set(latestSubmissionIdAtom, admission.requestId);
+        set(admissionErrorAtom, undefined);
+        set(dispatchAdmissionAtom, admission);
+    });
+    const submitCommandAtom = atom(null, async (get, set, run) => {
+        const submitted = {
+            draft: get(draftAtom),
+            revision: get(draftRevisionAtom),
+        };
+        const outcome = await run(submitted.draft, () => {
+            set(clearSubmittedDraftAtom, submitted);
+        });
+        if (outcome?.status === "handled" && !isCancelledOutcome(outcome))
+            set(clearSubmittedDraftAtom, submitted);
+        return outcome;
+    });
+    const retryAtom = atom(null, (get, set) => {
+        const admissions = get(admissionsAtom);
+        if (get(failureAtom) === "interrupted" || get(failureAtom) === "failed") {
+            const snapshot = get(snapshotAtom);
+            const commandId = get(newestCommandAtom);
+            if (snapshot === undefined || commandId === undefined)
+                return;
+            const content = newestDurablePrompt(snapshot.messages, commandId) ??
+                get(queryAtom).data?.latestPrompt?.[1];
+            if (content === undefined)
+                return;
+            if (admissions.filter(({ status }) => status !== "failed").length >=
+                MAX_UNRESOLVED_LOCAL_ADMISSIONS) {
+                set(admissionErrorAtom, "queue_full");
+                return;
+            }
+            const retry = {
+                content,
+                delivery: "followUp",
+                requestId: nanoid(),
+                submittedDraft: content,
+                submittedDraftRevision: get(draftRevisionAtom),
+                status: "admitting",
+            };
+            set(rawAdmissionsAtom, [...get(rawAdmissionsAtom), retry]);
+            set(latestSubmissionIdAtom, retry.requestId);
+            set(admissionErrorAtom, undefined);
+            set(dispatchAdmissionAtom, retry);
+            return;
+        }
+        const admission = admissions
+            .filter((candidate) => candidate.status === "failed")
+            .at(-1);
+        if (admission === undefined)
+            return;
+        if (admissions.filter(({ status }) => status !== "failed").length >=
+            MAX_UNRESOLVED_LOCAL_ADMISSIONS) {
+            set(admissionErrorAtom, "queue_full");
+            return;
+        }
+        const retry = {
+            content: admission.content,
+            delivery: admission.delivery,
+            requestId: admission.requestId,
+            submittedDraft: admission.submittedDraft,
+            submittedDraftRevision: admission.submittedDraftRevision,
+            status: "admitting",
+        };
+        set(rawAdmissionsAtom, (current) => current.map((candidate) => candidate.requestId === admission.requestId ? retry : candidate));
+        set(latestSubmissionIdAtom, retry.requestId);
+        set(admissionErrorAtom, undefined);
+        set(dispatchAdmissionAtom, retry);
+    });
+    const dismissFailedAtom = atom(null, (get, set, requestId) => {
+        const admissions = get(rawAdmissionsAtom);
+        const remaining = admissions.filter((admission) => admission.requestId !== requestId || admission.status !== "failed");
+        if (remaining.length === admissions.length)
+            return;
+        set(rawAdmissionsAtom, remaining);
+        if (get(latestSubmissionIdAtom) === requestId)
+            set(latestSubmissionIdAtom, remaining.at(-1)?.requestId);
+    });
+    let cancellation;
+    const cancelAtom = atom(null, (get) => {
+        if (cancellation !== undefined)
+            return cancellation;
+        const queue = get(snapshotAtom)?.activity.queue;
+        if (queue?.state !== "running")
+            return Promise.resolve();
+        const operation = get(abortAtom)
+            .mutateAsync(queue.commandId)
+            .then(() => undefined);
+        const tracked = operation.finally(() => {
+            if (cancellation === tracked)
+                cancellation = undefined;
+        });
+        cancellation = tracked;
+        return tracked;
+    });
+    let reconnecting;
+    const reconnectAtom = atom(null, (get) => {
+        const observation = get(observationAtom);
+        if (observation.status !== "unavailable")
+            return Promise.resolve({
+                kind: "nothing_to_reconnect",
+                state: observation.status === "live" ? "connected" : "connecting",
+            });
+        if (reconnecting !== undefined)
+            return reconnecting;
+        const query = queryClient.getQueryCache().find({
+            queryKey: sessionQueryOptions(session).queryKey,
+        });
+        if (query === undefined)
+            return Promise.resolve({
+                kind: "failed",
+                cause: "Session observation is unavailable",
+            });
+        const priorData = query.state.dataUpdateCount;
+        const priorError = query.state.errorUpdateCount;
+        const retry = new Promise((resolve) => {
+            let unsubscribe = () => undefined;
+            let settled = false;
+            const finish = (outcome) => {
+                if (settled)
+                    return;
+                settled = true;
+                unsubscribe();
+                clearTimeout(timeout);
+                resolve(outcome);
+            };
+            const inspect = () => {
+                if (query.state.dataUpdateCount > priorData &&
+                    queryClient.getQueryData(sessionQueryOptions(session).queryKey)
+                        ?.observation === "live") {
+                    finish({ kind: "reconnected" });
+                    return;
+                }
+                if (query.state.errorUpdateCount > priorError)
+                    finish({
+                        kind: "failed",
+                        cause: observationCause(query.state.error),
+                    });
+            };
+            unsubscribe = queryClient.getQueryCache().subscribe((event) => {
+                if (event.query === query)
+                    inspect();
+            });
+            const timeout = setTimeout(() => {
+                finish({
+                    kind: "failed",
+                    cause: "Session history did not reopen within 10 seconds",
+                });
+            }, 10_000);
+            // A live stream does not settle its refetch promise until the watch closes.
+            // The first new snapshot above is the reconnect acknowledgment.
+            void get(queryAtom)
+                .refetch({ cancelRefetch: true })
+                .catch((cause) => {
+                finish({ kind: "failed", cause: observationCause(cause) });
+            });
+            inspect();
+        });
+        reconnecting = retry.finally(() => {
+            reconnecting = undefined;
+        });
+        return reconnecting;
+    });
+    return {
+        abortAtom,
+        commandIdAtom,
+        contextAtom,
+        admissionErrorAtom,
+        admissionsAtom,
+        cancelAtom,
+        draftAtom,
+        dismissFailedAtom,
+        extensionsAtom,
+        failureAtom,
+        jumpToLatestAtom,
+        loadOlderHistoryAtom,
+        loadNewerHistoryAtom,
+        observationAtom,
+        observedCommandIdsAtom,
+        pinVisibleHistoryAtom,
+        queryAtom,
+        reconcileAdmissionsAtom,
+        reconnectAtom,
+        retryAtom,
+        setDraftAtom,
+        sendAtom,
+        snapshotAtom,
+        statusAtom,
+        viewStateAtom,
+        submitCommandAtom,
+        timelineAtom,
+    };
+}
+const ConversationContext = createContext(null);
+function useConversationScope() {
+    const scope = useContext(ConversationContext);
+    if (scope === null)
+        throw new Error("Parakeet hooks require a ParakeetProvider");
+    return scope;
+}
+function useStoreAtom(atom) {
+    const { store } = useConversationScope();
+    const subscribe = useCallback((listener) => store.sub(atom, listener), [atom, store]);
+    const snapshot = useCallback(() => store.get(atom), [atom, store]);
+    return useSyncExternalStore(subscribe, snapshot, snapshot);
+}
+function useStoreSetter(atom) {
+    const { store } = useConversationScope();
+    return useCallback((...args) => store.set(atom, ...args), [atom, store]);
+}
+/** Own one renderer-neutral conversation scope over the existing query cache. */
+export function ParakeetProvider({ children, session, clients = noClients, interactionStore, authorOf = noAuthor, }) {
+    const queryClient = useQueryClient();
+    const scope = useMemo(() => ({
+        atoms: createConversationAtoms(session, queryClient, authorOf),
+        session,
+        store: createStore(),
+        contributions: atom(noContributions),
+        interactions: interactionStore ?? createParakeetInteractions(),
+    }), [queryClient, session, interactionStore, authorOf]);
+    useEffect(() => {
+        // The live page is bounded: after a later reset an observed command may no
+        // longer be present. Retire its local row once, not just while it is visible.
+        const reconcile = () => {
+            scope.store.set(scope.atoms.reconcileAdmissionsAtom);
+        };
+        const unobserve = scope.store.sub(scope.atoms.observedCommandIdsAtom, reconcile);
+        reconcile();
+        return () => {
+            unobserve();
+        };
+    }, [scope]);
+    useEffect(() => {
+        const owner = createClientContributions(clients, (entryId, error) => {
+            reportFailure(`client contribution ${entryId}`, error);
+            scope.interactions.report({ tone: "error", message: error.message });
+        });
+        const publish = () => {
+            scope.store.set(scope.contributions, owner.snapshot());
+        };
+        const unsubscribe = owner.subscribe(publish);
+        const update = () => {
+            owner.update(scope.store.get(scope.atoms.extensionsAtom));
+        };
+        const unobserve = scope.store.sub(scope.atoms.extensionsAtom, update);
+        update();
+        return () => {
+            unobserve();
+            owner.dispose();
+            unsubscribe();
+        };
+    }, [clients, scope]);
+    return (_jsx(ConversationContext.Provider, { value: scope, children: children }));
+}
+/** Read stable history and replaceable live work. */
+export function useTimeline() {
+    const { atoms } = useConversationScope();
+    const base = useStoreAtom(atoms.timelineAtom);
+    const loadOlderHistory = useStoreSetter(atoms.loadOlderHistoryAtom);
+    const loadNewerHistory = useStoreSetter(atoms.loadNewerHistoryAtom);
+    const jumpToLatest = useStoreSetter(atoms.jumpToLatestAtom);
+    const pinVisibleHistory = useStoreSetter(atoms.pinVisibleHistoryAtom);
+    return useMemo(() => ({
+        ...base,
+        jumpToLatest,
+        loadNewerHistory,
+        loadOlderHistory,
+        pinVisibleHistory,
+    }), [base, jumpToLatest, loadNewerHistory, loadOlderHistory, pinVisibleHistory]);
+}
+/** Read and mutate the current conversation draft and prompt. */
+export function useComposer() {
+    const { atoms } = useConversationScope();
+    const draft = useStoreAtom(atoms.draftAtom);
+    const failure = useStoreAtom(atoms.failureAtom);
+    const admissionError = useStoreAtom(atoms.admissionErrorAtom);
+    const setDraft = useStoreSetter(atoms.setDraftAtom);
+    const send = useStoreSetter(atoms.sendAtom);
+    const submitCommand = useStoreSetter(atoms.submitCommandAtom);
+    const retry = useStoreSetter(atoms.retryAtom);
+    const retryLatest = useCallback(() => {
+        retry();
+    }, [retry]);
+    const dismissFailed = useStoreSetter(atoms.dismissFailedAtom);
+    const cancel = useStoreSetter(atoms.cancelAtom);
+    return useMemo(() => ({
+        admissionError,
+        cancel,
+        draft,
+        dismissFailed,
+        failure,
+        retry: retryLatest,
+        send,
+        setDraft,
+        submitCommand,
+    }), [
+        admissionError,
+        cancel,
+        draft,
+        dismissFailed,
+        failure,
+        retryLatest,
+        send,
+        setDraft,
+        submitCommand,
+    ]);
+}
+/** Dismiss a failed prompt without subscribing the timeline to composer edits. */
+export function useDismissFailedPrompt() {
+    const { atoms } = useConversationScope();
+    return useStoreSetter(atoms.dismissFailedAtom);
+}
+/** The Session this conversation observes. */
+export function useParakeetSession() {
+    return useConversationScope().session;
+}
+/** Read the Session's extension slots, including advertised command catalogs. */
+export function useExtensionSlots() {
+    return useStoreAtom(useConversationScope().atoms.extensionsAtom);
+}
+/** Read Session activity and operate its observation. */
+export function useStatus() {
+    const { atoms } = useConversationScope();
+    const commandId = useStoreAtom(atoms.commandIdAtom);
+    const status = useStoreAtom(atoms.statusAtom);
+    const viewState = useStoreAtom(atoms.viewStateAtom);
+    const observation = useStoreAtom(atoms.observationAtom);
+    const reconnect = useStoreSetter(atoms.reconnectAtom);
+    const context = useStoreAtom(atoms.contextAtom);
+    return useMemo(() => ({
+        commandId,
+        context,
+        observation,
+        reconnect,
+        status,
+        viewState,
+    }), [commandId, context, observation, reconnect, status, viewState]);
+}
+/** Presentation admitted once from the selected Session's already observed slots. */
+export function useClientContributions() {
+    return useStoreAtom(useConversationScope().contributions);
+}
+/** The selected Session's ordinary command interaction owner. */
+export function useParakeetInteractions() {
+    return useConversationScope().interactions;
+}