@fungi.computer/parakeet 0.0.1 → 0.2.0

package/dist/conversation-opening.js

@@ -0,0 +1,173 @@
+import { openAppAgent } from "@fungi.computer/agar/agents";
+import { seedSessionQuery } from "./headless.js";
+import { createShiitakeClient, } from "@fungi.computer/shiitake/client";
+import { ShiitakeError } from "@fungi.computer/shiitake";
+import { EventSource as EventSourceImplementation, } from "eventsource";
+/** Seed Parakeet's shared query with the bounded read before mounting its watch. */
+function prepareConversation(queryClient, session) {
+    let cancelled = false;
+    const readBaseline = async () => {
+        try {
+            return await session.read();
+        }
+        catch (cause) {
+            if (!(cause instanceof ShiitakeError) ||
+                cause.boundary !== "runtime" ||
+                cause.cause !== "unavailable")
+                throw cause;
+            await new Promise((resolve) => setTimeout(resolve, 150));
+            if (cancelled)
+                throw new Error("Conversation opening cancelled", { cause });
+            return session.read();
+        }
+    };
+    let cancel;
+    const cancelledRead = new Promise((_, reject) => {
+        cancel = () => {
+            reject(new Error("Conversation opening cancelled"));
+        };
+    });
+    const ready = Promise.race([readBaseline(), cancelledRead]).then((snapshot) => {
+        if (cancelled)
+            throw new Error("Conversation opening cancelled");
+        seedSessionQuery(queryClient, session, snapshot);
+    });
+    return {
+        ready,
+        close: () => {
+            cancelled = true;
+            cancel();
+        },
+    };
+}
+export function eventSourceFor(fetcher) {
+    return class HostEventSource {
+        #source;
+        constructor(url) {
+            this.#source = new EventSourceImplementation(url, {
+                fetch: (input, init) => fetcher(input, init),
+            });
+        }
+        get readyState() {
+            return this.#source.readyState;
+        }
+        addEventListener(type, listener, options) {
+            this.#source.addEventListener(type, listener, options);
+        }
+        close() {
+            this.#source.close();
+        }
+    };
+}
+/** Owns the selected conversation's Agent, client and Parakeet query lifetimes. */
+export function createConversationOpeningOwner(options) {
+    const { connection, queryClient, services } = options;
+    let pending = null;
+    let current = null;
+    let currentClose = null;
+    let disposed = false;
+    const same = (left, right) => left?.agentId === right.agentId && left.sessionId === right.sessionId;
+    const isCurrent = (opening) => !disposed && pending === opening;
+    const select = (agentId, sessionId, fromOpenRequest = false, waitForBaseline = true) => {
+        if (disposed)
+            return;
+        const selection = { agentId, sessionId };
+        if (same(pending, selection))
+            return;
+        pending?.close();
+        pending = null;
+        options.onPending(null);
+        options.onError(null);
+        if (same(current, selection))
+            return;
+        let openedClose = null;
+        let closed = false;
+        const opening = {
+            ...selection,
+            close: () => {
+                if (closed)
+                    return;
+                closed = true;
+                openedClose?.();
+            },
+        };
+        pending = opening;
+        options.onPending(selection);
+        void (async () => {
+            try {
+                const transport = await services.openAgent(connection.capabilities, {
+                    agentId,
+                });
+                if (!isCurrent(opening)) {
+                    await transport.close();
+                    return;
+                }
+                const client = services.createClient({
+                    baseUrl: transport.baseUrl,
+                    eventSource: eventSourceFor(transport.fetch),
+                    fetch: transport.fetch,
+                });
+                const session = client.session(sessionId);
+                const observation = prepareConversation(queryClient, session);
+                openedClose = () => {
+                    observation.close();
+                    void Promise.allSettled([client.close(), transport.close()]);
+                };
+                await observation.ready;
+                if (waitForBaseline && options.reportsSelection !== false) {
+                    await connection.ui.reportAgentSessionSelection({
+                        agentId,
+                        sessionId,
+                    });
+                }
+                if (!isCurrent(opening))
+                    return;
+                const conversation = { agentId, sessionId, session };
+                const previousClose = currentClose;
+                pending = null;
+                current = conversation;
+                currentClose = opening.close;
+                options.onConversation(conversation);
+                options.onPending(null);
+                previousClose?.();
+            }
+            catch (cause) {
+                console.error("Chat Session opening failed", cause);
+                opening.close();
+                if (isCurrent(opening)) {
+                    pending = null;
+                    options.onPending(null);
+                    options.onError(fromOpenRequest
+                        ? `That Session could not be opened. ${current ? "The current conversation remains open." : "Choose another Session from the list."}`
+                        : `Could not open this Session${cause instanceof Error ? `: ${cause.message}` : ""}. ${current ? "The previous conversation remains open." : "Try opening it again."}`);
+                }
+            }
+        })();
+    };
+    const clear = () => {
+        if (disposed)
+            return;
+        const hadSelection = pending !== null || current !== null;
+        pending?.close();
+        pending = null;
+        currentClose?.();
+        currentClose = null;
+        current = null;
+        options.onPending(null);
+        options.onConversation(null);
+        options.onError(null);
+        if (!hadSelection || options.reportsSelection === false)
+            return;
+        void connection.ui
+            .reportAgentSessionSelection(null)
+            .catch((cause) => {
+            console.error("Chat Session selection could not be reported", cause);
+            return undefined;
+        });
+    };
+    const close = () => {
+        clear();
+        disposed = true;
+    };
+    return { select, clear, close };
+}

package/dist/conversation.d.ts

@@ -1,13 +1,15 @@
 import { type ParakeetAuthorOf } from "./core/author-labels.js";
-import { type PromptDelivery, type SessionContext, type SessionExtensionSlots, type SessionPendingPrompts } from "@fungi.computer/shiitake/client";
+import { type PromptDelivery, type PromptCommand, type SessionContext, type SessionExtensionSlots, type SessionPendingPrompts } from "@fungi.computer/shiitake/client";
 import type { ClientEntryV1 } from "@fungi.computer/shiitake/client-entry";
 import { type ClientContribution } from "./core/client-contributions.js";
-import { type ParakeetInteractions } from "./commands/interactions.js";
+import { type ParakeetInteractions, type ParakeetToast } from "./commands/interactions.js";
 import type { WhistleExecutionOutcome } from "@fungi.computer/whistle";
 import { type ReactNode } from "react";
 import { type SessionViewState } from "./core/session-view-state.js";
 import type { ParakeetSession } from "./session.js";
 import type { TimelineItem } from "./store/types.js";
+import { type QueuedRecallState, type QueuedRecallOutcome } from "./core/queued-recall.js";
+import { type ParakeetDraftIdentity, type ParakeetDraftStorage } from "./core/draft-storage.js";
 /** Stable model identity presented by the current Session. */
 export type ParakeetModel = Readonly<{
     /** Provider model identifier. */
@@ -49,10 +51,16 @@ export type ParakeetObservation = Readonly<{
 }>;
 /** Stable history and replaceable work rendered by a conversation client. */
 export type TimelineController = Readonly<{
+    /** Remove one owner-admitted queued prompt, never the running turn or draft. */
+    cancelQueued: (commandId: string) => Promise<void>;
+    /** A queued-input gesture is waiting for its owner. */
+    cancellingQueued: boolean;
     /** Durable-backed rows whose identity is stable across progress revisions. */
     settled: readonly TimelineItem[];
     /** Replaceable progress, queued, and optimistic rows. */
     tail: readonly TimelineItem[];
+    /** Fixed committed Session positions resolved within the loaded history. */
+    positionAnchors: ReadonlyMap<number, string | null>;
     /** Last actually rendered durable row for each loaded command. */
     commandAnchors: ReadonlyMap<string, string>;
     /** Current owner-admitted prompts, independent of the visible history page. */
@@ -78,12 +86,35 @@ export type TimelineController = Readonly<{
     /** Accumulated durable usage. */
     usage?: ParakeetUsage | undefined;
 }>;
+/** A host may proceed with restart only after the current journal committed. */
+export type ParakeetDraftCheckpoint = Readonly<{
+    /** The latest draft is committed and restart may proceed. */
+    status: "saved";
+}> | Readonly<{
+    /** Draft persistence failed; the host must not proceed with restart. */
+    status: "failed";
+    /** Storage failure explanation for the host. */
+    reason: string;
+}>;
 /** Draft and prompt operations for the current conversation. */
 export type ComposerController = Readonly<{
     /** Stop the current turn. Queued prompts keep draining; the draft is unchanged. */
     cancel: () => Promise<void>;
     /** Current local input. */
     draft: string;
+    /** Image cargo restored with a queued prompt, carried through the same journal. */
+    images: PromptCommand["images"];
+    /** Shared composer reservation and recall outcome. */
+    recallState: QueuedRecallState;
+    /** Recall only when the host accepted a plain Up on empty, focused input. */
+    recall: () => Promise<QueuedRecallOutcome>;
+    /**
+     * Commit the latest draft and pending admissions synchronously, even through
+     * a callback captured before newer typing. Does not consume, send or withdraw.
+     * A resumed provider reads the same Session journal; never replay a copied
+     * draft over its newer state. A failed commit leaves the live draft untouched.
+     */
+    checkpointDraft: () => ParakeetDraftCheckpoint;
     /** Typed reason the latest prompt did not complete. */
     failure: "admission" | "failed" | "cancelled" | "interrupted" | undefined;
     /** Current send could not enter the bounded local admission queue. */
@@ -98,9 +129,10 @@ export type ComposerController = Readonly<{
      * Run a host command, such as Whistle slash dispatch, for the current draft.
      * Parakeet clears the draft only when the command handled it without
      * declining (a refused replacement keeps the text) and the draft was
-     * not edited while the command ran.
+     * not edited while the command ran. The callback can consume that exact
+     * draft on dispatch when the command definition requests it.
      */
-    submitCommand: (run: (draft: string) => Promise<WhistleExecutionOutcome | undefined>) => Promise<WhistleExecutionOutcome | undefined>;
+    submitCommand: (run: (draft: string, consumeDraft: () => void) => Promise<WhistleExecutionOutcome | undefined>) => Promise<WhistleExecutionOutcome | undefined>;
     /** Replace the local input. */
     setDraft: (value: string) => void;
 }>;
@@ -135,11 +167,24 @@ export type ParakeetReconnectOutcome = Readonly<{
     cause: string;
 }>;
 /** Own one renderer-neutral conversation scope over the existing query cache. */
-export declare function ParakeetProvider({ children, session, clients, interactionStore, authorOf, }: Readonly<{
+export declare function ParakeetProvider({ children, session, clients, interactionStore, authorOf, onToast, draftStorage, draftIdentity, }: Readonly<{
     children: ReactNode;
     session: ParakeetSession;
     clients?: readonly ClientEntryV1[] | undefined;
     interactionStore?: ParakeetInteractions | undefined;
+    /** Show a transient message; the host owns the toast surface. */
+    onToast?: ((toast: ParakeetToast) => void) | undefined;
+    /**
+     * Browser localStorage when accessible, otherwise session-only drafts.
+     * Native hosts supply an atomic file adapter.
+     */
+    draftStorage?: ParakeetDraftStorage | undefined;
+    /**
+     * Hosts replacing transport endpoints must supply the durable owner pair.
+     * Otherwise the Session's logical address names its journal.
+     * Exactly one key is used; no previous-address lookup or migration occurs.
+     */
+    draftIdentity?: ParakeetDraftIdentity | undefined;
     /**
      * Read the author to show from a message's opaque host metadata. Absent,
      * lines show no author.