@fungi.computer/parakeet 0.0.0-stage → 0.0.1

package/dist/parakeet.js

@@ -0,0 +1,276 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Button } from "@fungi.computer/caps/components/button";
+import { Dialog, DialogContent } from "@fungi.computer/caps/components/dialog";
+import { ScrollToBottomBlob } from "@fungi.computer/caps/components/scroll-to-bottom-blob";
+import { createWhistle } from "@fungi.computer/whistle";
+import { useVirtualizer } from "@tanstack/react-virtual";
+import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
+import { ParakeetProvider, useComposer, useClientContributions, useDismissFailedPrompt, useStatus, useTimeline, } from "./conversation.js";
+import { initialToolDisclosure, toggleDisclosure } from "./core/tool-groups.js";
+import { authorDisplayNames, } from "./core/author-labels.js";
+import { ChatComposer, sessionReadout, } from "./components/ChatComposer.js";
+import { ClientRows } from "./components/ClientRows.js";
+import { useClientActions } from "./client-contributions.js";
+import { placeClientTimeline } from "./core/client-timeline.js";
+import { InteractionPanel } from "./components/InteractionPanel.js";
+import { WaitingNotice } from "./components/WaitingNotice.js";
+import { useSlashCommands, } from "./commands/use-slash-commands.js";
+import { TimelineItem } from "./components/TimelineItem.js";
+import { MarkdownPolicyContext } from "./components/MarkdownRenderer.js";
+/** Render the retained conversation surface within one Parakeet provider. */
+export function ParakeetView({ disambiguateAuthors, visitor, composerActionVariant, empty, commands, renderToolActions, renderAssistantAttachment, formatAssistantText, onLink, onOpen, }) {
+    const textareaRef = useRef(null);
+    const [ownCommands] = useState(() => createWhistle());
+    const slash = useSlashCommands({
+        enabled: visitor === undefined,
+        commands: commands ?? ownCommands,
+        origin: "browser",
+        keys: { newline: "Shift+Enter" },
+        busy: useBusy(),
+    });
+    const clientActions = useClientActions(commands ?? ownCommands);
+    const contributions = useClientContributions();
+    const timelineController = useTimeline();
+    const placed = useMemo(() => placeClientTimeline(contributions, timelineController.commandAnchors), [contributions, timelineController.commandAnchors]);
+    return (_jsxs("div", { className: "parakeet flex h-full flex-col items-stretch", "data-parakeet": "standalone", "data-testid": "parakeet-view", onClickCapture: (event) => {
+            const anchor = event.target instanceof Element
+                ? event.target.closest("a[href]")
+                : null;
+            if (anchor instanceof HTMLAnchorElement && onLink?.(anchor.href))
+                event.preventDefault();
+        }, children: [_jsxs("div", { className: "flex h-full w-full flex-col border-r border-base-300", children: [_jsx(ConversationTimeline, { disambiguateAuthors: visitor === undefined && disambiguateAuthors === true, clientActions: clientActions, onOpen: onOpen, focusAfterJump: textareaRef, empty: empty, renderToolActions: renderToolActions, renderAssistantAttachment: renderAssistantAttachment, formatAssistantText: formatAssistantText }), contributions.some(({ value }) => value.panel.length > 0) ? (_jsx("section", { "aria-label": "Session extension controls", className: "w-full shrink-0 border-t border-base-300 bg-base-100", children: contributions.map(({ entryId, value }) => {
+                            // An extension's retained-event notice and null-anchor rows
+                            // join its own footer entry; one with no panel row here keeps
+                            // none of this, rather than growing a section just to show it.
+                            const omittedHere = value.panel.length === 0
+                                ? undefined
+                                : placed.omitted.find((entry) => entry.entryId === entryId);
+                            const unanchoredHere = value.panel.length === 0
+                                ? []
+                                : placed.unanchored
+                                    .filter((entry) => entry.entryId === entryId)
+                                    .flatMap(({ cell }) => cell.rows.map((row) => ({
+                                    ...row,
+                                    id: `unanchored:${cell.id}:${row.id}`,
+                                })));
+                            return (_jsx(ClientRows, { entryId: entryId, rows: [
+                                    ...value.panel,
+                                    ...(omittedHere === undefined
+                                        ? []
+                                        : [
+                                            {
+                                                id: `omitted:${entryId}`,
+                                                title: `${String(omittedHere.count)} earlier change${omittedHere.count === 1 ? "" : "s"} omitted`,
+                                                tone: "muted",
+                                            },
+                                        ]),
+                                    ...unanchoredHere,
+                                ], actions: clientActions, onOpen: onOpen }, entryId));
+                        }) })) : null, _jsx(ConversationWaiting, { clientActions: clientActions }), _jsx(ConversationComposer, { visitor: visitor, textareaRef: textareaRef, composerActionVariant: composerActionVariant, slash: slash })] }), visitor === undefined ? _jsx(ConversationInteraction, { slash: slash }) : null] }));
+}
+const busyStatuses = new Set([
+    "cancelling",
+    "queued",
+    "retrying",
+    "sending",
+    "streaming",
+    "thinking",
+]);
+function useBusy() {
+    return busyStatuses.has(useStatus().status);
+}
+/** The browser renderer of Parakeet's open command conversation. */
+function ConversationInteraction({ slash, }) {
+    const open = slash.interactions.open;
+    return (_jsx(Dialog, { open: open !== undefined, onOpenChange: (next) => {
+            if (!next)
+                slash.store.close();
+        }, children: _jsx(DialogContent, { className: "w-[min(32rem,calc(100vw-2rem))] rounded-box bg-base-100 p-md shadow-lg", keepMounted: false, children: open === undefined ? null : (_jsx(InteractionPanel, { host: open.host, onClose: slash.store.close, onRetry: () => {
+                    slash.store.close();
+                    open.retry();
+                } }, open.key)) }) }));
+}
+function ConversationTimeline({ disambiguateAuthors, clientActions, onOpen, focusAfterJump, empty, renderToolActions, renderAssistantAttachment, formatAssistantText, }) {
+    const dismissFailed = useDismissFailedPrompt();
+    const timelineController = useTimeline();
+    const authorNames = useMemo(() => authorDisplayNames(disambiguateAuthors
+        ? [...timelineController.settled, ...timelineController.tail].flatMap((item) => ("author" in item && item.author ? [item.author] : []))
+        : []), [disambiguateAuthors, timelineController.settled, timelineController.tail]);
+    const contributions = useClientContributions();
+    const placed = placeClientTimeline(contributions, timelineController.commandAnchors);
+    // View-only: kept above the virtualizer so off-screen groups remember it.
+    const [toolDisclosure, setToolDisclosure] = useState(initialToolDisclosure);
+    const toggleTool = useCallback((id, defaultOpen) => {
+        setToolDisclosure((current) => toggleDisclosure(current, id, defaultOpen));
+    }, []);
+    const sessionStatus = useStatus();
+    const scrollerRef = useRef(null);
+    const previousScrollTop = useRef(undefined);
+    const count = timelineController.settled.length + timelineController.tail.length;
+    const itemAt = useCallback((index) => index < timelineController.settled.length
+        ? timelineController.settled[index]
+        : timelineController.tail[index - timelineController.settled.length], [timelineController.settled, timelineController.tail]);
+    const getItemKey = useCallback((index) => {
+        const item = itemAt(index);
+        if (item === undefined)
+            return index;
+        // One submitted prompt keeps one row from submit to durable: no remount.
+        return item.kind === "user_message" && item.requestId !== undefined
+            ? item.requestId
+            : item.id;
+    }, [itemAt]);
+    const timeline = useVirtualizer({
+        anchorTo: "end",
+        count,
+        estimateSize: () => 72,
+        followOnAppend: "auto",
+        getItemKey,
+        getScrollElement: () => scrollerRef.current,
+        initialRect: { height: 800, width: 800 },
+        overscan: 6,
+        useFlushSync: false,
+    });
+    const virtualItems = timeline.getVirtualItems();
+    const atBottom = timeline.isAtEnd();
+    const [unread, setUnread] = useState(0);
+    const lastItem = count > 0 ? itemAt(count - 1)?.id : undefined;
+    const observedTail = useRef({ count, lastItem });
+    useEffect(() => {
+        const previous = observedTail.current;
+        observedTail.current = { count, lastItem };
+        if (atBottom)
+            setUnread(0);
+        else if (previous.lastItem !== undefined && lastItem !== previous.lastItem)
+            setUnread((value) => value + Math.max(1, count - previous.count));
+    }, [atBottom, count, lastItem]);
+    const nearTop = (virtualItems[0]?.index ?? Number.POSITIVE_INFINITY) < 3;
+    const { hasMoreHistory, hasNewerHistory, loadingOlderHistory, loadOlderHistory, loadNewerHistory, } = timelineController;
+    const requestedAtTop = useRef(false);
+    useEffect(() => {
+        if (!nearTop) {
+            requestedAtTop.current = false;
+            return;
+        }
+        if (hasMoreHistory && !loadingOlderHistory && !requestedAtTop.current) {
+            requestedAtTop.current = true;
+            loadOlderHistory();
+        }
+    }, [hasMoreHistory, loadOlderHistory, loadingOlderHistory, nearTop]);
+    const jumpToBottom = useCallback(() => {
+        setUnread(0);
+        previousScrollTop.current = undefined;
+        timelineController.jumpToLatest();
+        timeline.scrollToEnd({ behavior: "smooth" });
+    }, [timeline, timelineController]);
+    return (_jsxs("div", { className: "prose relative min-h-0 flex-1", children: [_jsx("div", { "aria-live": "polite", "aria-atomic": "true", className: "sr-only", children: sessionReadout(sessionStatus.status, sessionStatus.viewState) }), sessionStatus.observation.status === "unavailable" ? (_jsxs("div", { className: "flex items-center justify-between gap-2 px-3 py-1 text-xs text-dim", role: "status", children: [_jsx("span", { children: sessionStatus.observation.reason }), _jsx("button", { className: "underline", onClick: () => void sessionStatus.reconnect(), type: "button", children: "Reconnect" })] })) : null, _jsx("div", { className: "h-full min-h-0 overflow-y-auto", "data-chat-scroller": true, ref: scrollerRef, onScroll: (event) => {
+                    const top = event.currentTarget.scrollTop;
+                    if (previousScrollTop.current !== undefined &&
+                        top < previousScrollTop.current)
+                        timelineController.pinVisibleHistory();
+                    previousScrollTop.current = top;
+                }, onWheel: (event) => {
+                    const scroller = scrollerRef.current;
+                    if (scroller === null || loadingOlderHistory)
+                        return;
+                    if (event.deltaY < 0)
+                        timelineController.pinVisibleHistory();
+                    if (event.deltaY < 0 && scroller.scrollTop <= 1 && hasMoreHistory)
+                        loadOlderHistory();
+                    if (event.deltaY > 0 &&
+                        scroller.scrollTop + scroller.clientHeight >=
+                            scroller.scrollHeight - 1 &&
+                        hasNewerHistory)
+                        loadNewerHistory();
+                }, style: { overscrollBehavior: "contain" }, children: count > 0 ? (_jsx("div", { className: "relative w-full", style: { height: `${String(timeline.getTotalSize())}px` }, children: virtualItems.map((virtualItem) => {
+                        const item = itemAt(virtualItem.index);
+                        if (item === undefined)
+                            return null;
+                        return (_jsxs("div", { "data-index": virtualItem.index, "data-parakeet-entry": item.kind === "user_message" ? "user" : item.kind, "data-parakeet-id": item.id, "data-status": item.kind === "assistant_message"
+                                ? item.isError
+                                    ? "error"
+                                    : undefined
+                                : item.kind === "compaction_divider" ||
+                                    item.kind === "compaction_notice"
+                                    ? undefined
+                                    : item.status, "data-tone": item.kind === "assistant_message" && item.isError
+                                ? "error"
+                                : undefined, ref: timeline.measureElement, style: {
+                                left: 0,
+                                position: "absolute",
+                                top: 0,
+                                transform: `translateY(${String(virtualItem.start)}px)`,
+                                width: "100%",
+                            }, children: [_jsx(TimelineItem, { item: "author" in item &&
+                                        item.author &&
+                                        authorNames.has(item.author.id)
+                                        ? {
+                                            ...item,
+                                            author: {
+                                                ...item.author,
+                                                name: authorNames.get(item.author.id) ??
+                                                    item.author.name,
+                                            },
+                                        }
+                                        : item, onDismissFailed: dismissFailed, onToggleTool: toggleTool, renderToolActions: renderToolActions, renderAssistantAttachment: renderAssistantAttachment, formatAssistantText: formatAssistantText, toolDisclosure: toolDisclosure }), placed.after.get(item.id)?.map(({ entryId, cell }) => (_jsx(ClientRows, { entryId: entryId, rows: cell.rows, actions: clientActions, onOpen: onOpen }, `${entryId}:${cell.id}`)))] }, virtualItem.key));
+                    }) })) : ((empty ?? (_jsx("div", { className: "flex h-full items-center justify-center text-center", children: _jsxs("div", { children: [_jsx("p", { className: "mb-1 text-xs text-base-content", children: "Ready" }), _jsx("p", { className: "text-[10px] text-dim", children: "What would you like to build?" })] }) })))) }), count > 0 ? (_jsx(ScrollToBottomBlob, { direction: "forward", unread: unread, focusAfterJump: focusAfterJump, onJump: jumpToBottom, scrollerRef: scrollerRef })) : null] }));
+}
+/** The owner's queued state and independently contributed waiting controls. */
+function ConversationWaiting({ clientActions, }) {
+    const { viewState } = useStatus();
+    const contributions = useClientContributions();
+    const extensionWaiting = viewState.kind === "idle"
+        ? contributions.find(({ value }) => value.waiting !== null)
+        : undefined;
+    const waiting = viewState.kind === "queued" ? viewState : null;
+    return (_jsxs(_Fragment, { children: [extensionWaiting?.value.waiting === undefined ||
+                extensionWaiting.value.waiting === null ? null : (_jsxs("div", { className: "flex items-center gap-2 px-3 text-xs", children: [_jsx("span", { children: extensionWaiting.value.waiting.summary }), _jsx(Button, { size: "xs", variant: "outline", disabled: !clientActions.enabled ||
+                            clientActions.state.get(extensionWaiting.value.waiting.cancel)
+                                ?.pending === true, onClick: () => {
+                            if (extensionWaiting.value.waiting !== null)
+                                void clientActions.execute(extensionWaiting.entryId, extensionWaiting.value.waiting.cancel, true);
+                        }, children: extensionWaiting.value.waiting.cancel.label })] })), _jsx(WaitingNotice, { waiting: waiting })] }));
+}
+function ConversationComposer({ visitor, textareaRef, composerActionVariant, slash, }) {
+    const composer = useComposer();
+    const sessionStatus = useStatus();
+    const contributions = useClientContributions();
+    const timeline = useTimeline();
+    useEffect(() => {
+        if (composer.failure !== undefined)
+            textareaRef.current?.focus();
+    }, [composer.failure, textareaRef]);
+    const abort = useCallback(() => {
+        void composer.cancel();
+    }, [composer.cancel]);
+    const composerProps = {
+        statusChips: contributions
+            .flatMap(({ value }) => value.chips)
+            .sort((left, right) => left.order - right.order)
+            .map(({ row }) => row.title),
+        actionVariant: composerActionVariant,
+        draft: composer.draft,
+        failure: composer.failure,
+        failureCause: sessionStatus.viewState.kind === "error"
+            ? sessionStatus.viewState.cause
+            : undefined,
+        admissionError: composer.admissionError,
+        onAbort: abort,
+        onChange: composer.setDraft,
+        onRetry: composer.retry,
+        onSend: slash.submit,
+        slash: visitor === undefined ? slash : undefined,
+        placeholder: visitor === undefined ? undefined : `Ask ${visitor.agentName}…`,
+        showFooter: visitor === undefined,
+        status: sessionStatus.status,
+        viewState: sessionStatus.viewState,
+        textareaRef,
+        model: timeline.model,
+        usage: timeline.usage,
+        context: sessionStatus.context,
+    };
+    return _jsx(ChatComposer, { ...composerProps });
+}
+/** Standalone typed composer and exact-message timeline. */
+export function Parakeet({ authorOf, disambiguateAuthors, visitor, markdownPolicy = "session", composerActionVariant, empty, session, clients, renderToolActions, renderAssistantAttachment, formatAssistantText, commands, onLink, onOpen, }) {
+    return (_jsx(MarkdownPolicyContext.Provider, { value: markdownPolicy, children: _jsx(ParakeetProvider, { session: session, clients: clients, authorOf: authorOf, children: _jsx(ParakeetView, { disambiguateAuthors: disambiguateAuthors, visitor: visitor, composerActionVariant: composerActionVariant, empty: empty, renderToolActions: renderToolActions, renderAssistantAttachment: renderAssistantAttachment, formatAssistantText: formatAssistantText, commands: commands, onLink: onLink, onOpen: onOpen }) }) }));
+}

package/dist/provider-choices.d.ts

@@ -0,0 +1,8 @@
+import type { WhistlePrompt } from "@fungi.computer/whistle";
+import type { LoginProvider, ProviderAccess } from "./account-commands.js";
+/** Whistle-owned choice options returned by the provider grouping helper. */
+export type ChoiceOptions = Extract<WhistlePrompt, {
+    type: "choice";
+}>["options"];
+/** Group the existing registry or model providers without owning another catalog. */
+export declare function providerChoices(providers: readonly LoginProvider[], access: readonly ProviderAccess[], popularProviderIds: readonly string[], screen: "login" | "model"): ChoiceOptions;

package/dist/provider-choices.js

@@ -0,0 +1,43 @@
+/** Group the existing registry or model providers without owning another catalog. */
+export function providerChoices(providers, access, popularProviderIds, screen) {
+    const signedIn = new Map(access.map((provider) => [provider.providerId, provider]));
+    const popular = new Map(popularProviderIds.map((id, index) => [id, index]));
+    const group = (id) => signedIn.has(id) ? 0 : screen === "login" && popular.has(id) ? 1 : 2;
+    const isDefault = (id) => screen === "model" && id === "fungi";
+    return [
+        ...new Map(providers.map((provider) => [provider.id, provider])).values(),
+    ]
+        .sort((left, right) => Number(isDefault(right.id)) - Number(isDefault(left.id)) ||
+        group(left.id) - group(right.id) ||
+        (group(left.id) < 2
+            ? (popular.get(left.id) ?? popularProviderIds.length) -
+                (popular.get(right.id) ?? popularProviderIds.length)
+            : 0) ||
+        left.name.localeCompare(right.name) ||
+        left.id.localeCompare(right.id))
+        .map((provider) => {
+        const methods = provider.methods.map((method) => method.kind === "api_key" ? "API key" : "Subscription");
+        const credential = signedIn.get(provider.id);
+        const description = methods.length > 0
+            ? methods.join(" or ")
+            : credential?.type === "oauth"
+                ? "Subscription"
+                : credential?.type === "api_key"
+                    ? "API key"
+                    : undefined;
+        const choice = {
+            value: provider.id,
+            label: provider.name,
+            group: isDefault(provider.id) && !signedIn.has(provider.id)
+                ? "Default"
+                : group(provider.id) === 0
+                    ? "Signed in"
+                    : group(provider.id) === 1
+                        ? "Popular"
+                        : "More providers",
+        };
+        if (description === undefined)
+            return choice;
+        return { ...choice, description };
+    });
+}

package/dist/reload-command.d.ts

@@ -0,0 +1,43 @@
+import type { WhistleContribution, WhistleRuntime } from "@fungi.computer/whistle";
+/**
+ * One category a host can account for in `/reload`, described by the owner
+ * that already holds it. Nothing here caches, restarts or replaces anything:
+ * `now` re-reads through the owner's own refresh, `next_turn` names a source
+ * the owner already re-reads at the start of every turn, and `unsupported`
+ * names a category with no safe re-read or replace lifecycle today.
+ */
+export type ReloadSource = Readonly<{
+    /** The category the report names, such as "model catalog". */
+    name: string;
+} & ({
+    /** Re-read now, while the command runs. */
+    effect: "now";
+    /** Re-read this category; a rejection is reported, never thrown. */
+    reload: (signal: AbortSignal) => Promise<void>;
+} | {
+    /** The owner already re-reads it at the start of every turn. */
+    effect: "next_turn";
+} | {
+    /** No safe re-read or replace lifecycle exists for it today. */
+    effect: "unsupported";
+    /** Why it cannot be reloaded, shown in the report. */
+    reason: string;
+})>;
+/** Where one `/reload` contribution comes from and what it can report. */
+export type ReloadCommandOptions = Readonly<{
+    /** Host source that owns the contribution lease. */
+    sourceId: string;
+    /** Namespace for the reload command. */
+    namespace: string;
+    /** Read at execution so the report names the categories mounted right now. */
+    sources: () => readonly ReloadSource[];
+}>;
+/** Refresh what supports it and report every category honestly. */
+export declare function reloadSources(sources: readonly ReloadSource[], signal: AbortSignal): Promise<string>;
+/** The shared `/reload` definition over host-described reload sources. */
+export declare function reloadCommandDefinitions(options: Pick<ReloadCommandOptions, "sources">): WhistleContribution["commands"];
+/** Contribute `/reload` to one Whistle host. */
+export declare function contributeReloadCommand(commands: Pick<WhistleRuntime, "contribute">, options: ReloadCommandOptions): Readonly<{
+    update: (commands: WhistleContribution["commands"]) => void;
+    dispose: () => void;
+}>;

package/dist/reload-command.js

@@ -0,0 +1,72 @@
+function failure(cause) {
+    return cause instanceof Error && cause.message.length > 0
+        ? cause.message.slice(0, 200)
+        : "refresh failed";
+}
+/** Refresh what supports it and report every category honestly. */
+export async function reloadSources(sources, signal) {
+    const refreshed = [];
+    const failed = [];
+    const nextTurn = [];
+    const unsupported = [];
+    const reloadable = [];
+    for (const source of sources) {
+        if (source.effect === "next_turn")
+            nextTurn.push(source.name);
+        else if (source.effect === "unsupported")
+            unsupported.push(`${source.name} (${source.reason})`);
+        else
+            reloadable.push(source);
+    }
+    // Each refresh settles on its own: one failure is reported, never thrown,
+    // and never stops the others. A synchronous throw settles as a rejection.
+    const settled = await Promise.allSettled(reloadable.map((source) => Promise.resolve().then(() => source.reload(signal))));
+    reloadable.forEach((source, index) => {
+        const result = settled[index];
+        if (result?.status === "fulfilled")
+            refreshed.push(source.name);
+        else
+            failed.push(`${source.name} (${failure(result?.reason)})`);
+    });
+    const order = (names) => names.sort((left, right) => left.localeCompare(right)).join(", ");
+    const lines = [
+        `Refreshed now: ${refreshed.length === 0 ? "nothing" : order(refreshed)}.`,
+    ];
+    if (failed.length > 0)
+        lines.push(`Failed: ${order(failed)}.`);
+    if (nextTurn.length > 0)
+        lines.push(`Re-read at the next turn: ${order(nextTurn)}.`);
+    if (unsupported.length > 0)
+        lines.push(`Not reloadable: ${order(unsupported)}.`);
+    lines.push("Active work and its captured context were not changed.");
+    return lines.join("\n");
+}
+/** The shared `/reload` definition over host-described reload sources. */
+export function reloadCommandDefinitions(options) {
+    return [
+        {
+            id: "reload",
+            title: "Reload",
+            category: "Settings",
+            description: "Re-read settings that support it",
+            projections: {
+                help: {},
+                palette: {},
+                slash: { aliases: ["reload"] },
+            },
+            handler: async ({ interaction }) => {
+                const report = await reloadSources(options.sources(), interaction?.signal ?? new AbortController().signal);
+                interaction?.notify({ type: "info", message: report });
+                return report;
+            },
+        },
+    ];
+}
+/** Contribute `/reload` to one Whistle host. */
+export function contributeReloadCommand(commands, options) {
+    return commands.contribute({
+        sourceId: options.sourceId,
+        namespace: options.namespace,
+        commands: reloadCommandDefinitions(options),
+    });
+}

package/dist/session-commands.d.ts

@@ -0,0 +1,53 @@
+import type { CancelResult } from "@fungi.computer/shiitake/client";
+import type { ParakeetSessionCommand } from "./session.js";
+import type { WhistleRuntime } from "@fungi.computer/whistle";
+import { buildDurableTimeline } from "./core/build-timeline.js";
+import { type SessionViewFacts } from "./core/session-view-state.js";
+export type SessionCommandRuntime = Pick<WhistleRuntime, "contribute">;
+export type SessionCommandSession = Readonly<{
+    read: () => Promise<Readonly<{
+        sessionId: string;
+        messages?: Parameters<typeof buildDurableTimeline>[0];
+        compactions?: Parameters<typeof buildDurableTimeline>[1];
+        pending: Readonly<{
+            hasMore?: boolean;
+            prompts: readonly Readonly<{
+                commandId: string;
+                text: string;
+                delivery: "steer" | "followUp";
+            }>[];
+        }>;
+    }> & SessionViewFacts>;
+    cancel?: ((input: Readonly<{
+        commandId: string;
+        onlyIfPending?: boolean;
+    }>) => Promise<CancelResult>) | undefined;
+    /** Execute a type-discriminated Session command, including `fork`. */
+    command: ParakeetSessionCommand;
+}>;
+/** Shared Session actions with optional human presentation callbacks. */
+export type ParakeetSessionCommandOptions = Readonly<{
+    /** Host source that owns the contribution lease. */
+    sourceId: string;
+    /** Namespace for the Session commands. */
+    namespace: string;
+    /** Open the host's saved-Session chooser. */
+    sessionResume?: (() => void | Promise<void>) | undefined;
+    /** Whether this host currently supports saved-Session selection. */
+    sessionResumeAvailable: boolean;
+    /** Restore an owner-withdrawn queued prompt into the host composer. */
+    onEditQueued?: (text: string) => void;
+    /** Refuse withdrawal while the host has a draft that must be preserved. */
+    canEditQueued?: () => boolean;
+    /** Navigate to the Session a fork just created. */
+    onForked?: ((sessionId: string) => void | Promise<void>) | undefined;
+    /** Whether this host currently supports navigating to a forked Session. */
+    forkAvailable: boolean;
+    /** Show a title the owner just saved; null means the derived title is back. */
+    onTitled?: ((title: string | null) => void | Promise<void>) | undefined;
+}>;
+/** Contribute the shared Session command vocabulary to one Whistle host. */
+export declare function contributeSessionCommands(commands: Pick<SessionCommandRuntime, "contribute">, session: SessionCommandSession, options: ParakeetSessionCommandOptions): Readonly<{
+    update: (commands: import("@fungi.computer/whistle").WhistleContribution["commands"]) => void;
+    dispose: () => void;
+}>;