@fungi.computer/parakeet 0.4.0 → 0.5.0

package/dist/client-contributions.d.ts

@@ -9,6 +9,7 @@ export declare function useClientActions(commands: ParakeetCommandRuntime): {
         readonly input?: {
             readonly [x: string]: import("effect/Schema").Json;
         } | undefined;
+        readonly awaiting?: "question";
     }, Readonly<{
         pending: boolean;
         error?: string;

package/dist/commands/awaiting-driver.d.ts

@@ -0,0 +1,20 @@
+import type { ClientContribution } from "../core/client-contributions.js";
+import type { ParakeetInteractions } from "./interactions.js";
+import type { ParakeetCommandRuntime } from "./use-slash-commands.js";
+/**
+ * Open the conversation of every decision the Agent is waiting on, so its
+ * first prompt can take over the composer without the person asking. Each row
+ * runs its own advertised command once; the row leaving cancels it.
+ */
+export declare function useAwaitingDriver(options: Readonly<{
+    enabled: boolean;
+    commands: ParakeetCommandRuntime;
+    store: ParakeetInteractions;
+    contributions: readonly ClientContribution[];
+    /** Session observation is live; nothing opens while it is not. */
+    online: boolean;
+    /** Counts requests to answer, which restart a conversation that failed. */
+    requests: number;
+    /** Changes whenever the runtime's commands do, so a late command is found. */
+    commandsVersion: unknown;
+}>): void;

package/dist/commands/awaiting-driver.js

@@ -0,0 +1,121 @@
+import { createWhistleInteractionHost } from "@fungi.computer/whistle/interaction";
+import { useEffect, useRef } from "react";
+/** Footer rows whose action asks the person to decide in the composer. */
+function awaitingRows(contributions) {
+    return contributions.flatMap(({ entryId, value }) => value.panel.flatMap((row) => (row.actions ?? [])
+        .filter((action) => action.awaiting !== undefined)
+        .map((action) => ({
+        key: JSON.stringify([entryId, row.id]),
+        command: { namespace: entryId, id: action.id },
+        title: row.title,
+        action,
+    }))));
+}
+function failure(outcome) {
+    if (outcome.status === "handled")
+        return undefined;
+    if (outcome.status === "failed")
+        return outcome.error.message;
+    if (outcome.status === "unavailable")
+        return outcome.reason;
+    return `The question could not be opened (${outcome.status}).`;
+}
+/**
+ * Open the conversation of every decision the Agent is waiting on, so its
+ * first prompt can take over the composer without the person asking. Each row
+ * runs its own advertised command once; the row leaving cancels it.
+ */
+export function useAwaitingDriver(options) {
+    const { enabled, commands, store, contributions, online, requests, commandsVersion, } = options;
+    const running = useRef(new Map());
+    const handled = useRef(requests);
+    useEffect(() => {
+        const wanted = new Map((enabled && online ? awaitingRows(contributions) : []).map((row) => [
+            row.key,
+            row,
+        ]));
+        const retry = handled.current !== requests;
+        handled.current = requests;
+        for (const [key, entry] of running.current)
+            if (!wanted.has(key) || (retry && entry.failed())) {
+                entry.stop();
+                running.current.delete(key);
+            }
+        for (const row of wanted.values()) {
+            if (running.current.has(row.key))
+                continue;
+            const host = createWhistleInteractionHost({ title: row.title });
+            const session = host.begin();
+            const controller = new AbortController();
+            let leave;
+            let failed = false;
+            const unsubscribe = host.subscribe(() => {
+                if (leave === undefined && host.snapshot().prompt !== undefined)
+                    leave = store.awaiting.add({
+                        key: row.key,
+                        kind: "question",
+                        arrivedAt: Date.now(),
+                        host,
+                    });
+            });
+            const base = {
+                origin: "menu",
+                signal: controller.signal,
+                interaction: session.interaction,
+            };
+            void commands
+                .execute(row.command, row.action.input === undefined
+                ? base
+                : { ...base, arguments: row.action.input })
+                .then((outcome) => {
+                unsubscribe();
+                leave?.();
+                if (outcome.status === "missing" ||
+                    outcome.status === "unavailable") {
+                    // Its command is not advertised yet; start over when it is.
+                    session.settle({ status: "cancelled" });
+                    if (running.current.get(row.key)?.failed() === false)
+                        running.current.delete(row.key);
+                    return;
+                }
+                const message = failure(outcome);
+                if (message === undefined) {
+                    session.settle({ status: "handled" });
+                    const notice = host.snapshot().message;
+                    if (notice?.type === "info")
+                        store.toast({ variant: "info", message: notice.message });
+                    return;
+                }
+                if (controller.signal.aborted) {
+                    session.settle({ status: "cancelled" });
+                    return;
+                }
+                failed = true;
+                session.settle({ status: "failed", message });
+                store.report({ tone: "error", message });
+            });
+            running.current.set(row.key, {
+                failed: () => failed,
+                stop: () => {
+                    unsubscribe();
+                    leave?.();
+                    controller.abort();
+                    host.cancel();
+                },
+            });
+        }
+    }, [
+        enabled,
+        online,
+        contributions,
+        commands,
+        store,
+        requests,
+        commandsVersion,
+    ]);
+    useEffect(() => () => {
+        for (const entry of running.current.values())
+            entry.stop();
+        running.current.clear();
+    }, [commands, store, enabled]);
+}

package/dist/commands/builtins.js

@@ -1,8 +1,10 @@
 import { keyBindings, slashRegistry } from "./slash.js";
 /** Run a chosen command after the choosing command has settled. */
-function runAfter(runtime, commandId, origin) {
+function runAfter(runtime, command, origin) {
+    if (command === undefined)
+        return;
     setTimeout(() => {
-        void runtime.execute(commandId, { origin });
+        void runtime.execute(command, { origin });
     }, 0);
 }
 /**
@@ -39,7 +41,7 @@ export function parakeetBuiltinCommands(runtime, options) {
                             : `${command.title} · ${command.keys.join(", ")}`,
                     })),
                 });
-                runAfter(runtime, chosen, input.origin);
+                runAfter(runtime, commands.find((command) => command.commandId === chosen)?.command, input.origin);
                 return undefined;
             },
         },
@@ -71,7 +73,7 @@ export function parakeetBuiltinCommands(runtime, options) {
                         description: row.keys,
                     })),
                 });
-                runAfter(runtime, chosen, input.origin);
+                runAfter(runtime, keys.find((row) => row.commandId === chosen)?.command, input.origin);
                 return undefined;
             },
         },

package/dist/commands/interactions.d.ts

@@ -1,5 +1,6 @@
 import type { WhistleInteractionEnd, WhistleRuntime } from "@fungi.computer/whistle";
 import { type WhistleInteractionHost } from "@fungi.computer/whistle/interaction";
+import type { AwaitingItem } from "../core/awaiting-answer.js";
 /** One interaction a renderer should draw as a dialog or panel. */
 export type ParakeetOpenInteraction = Readonly<{
     /** Changes whenever a different interaction opens. */
@@ -27,8 +28,21 @@ export type ParakeetToast = Readonly<{
     /** What happened. */
     message: string;
 }>;
+/** The decisions waiting on the person, which the composer takes over for. */
+export type ParakeetAwaiting = Readonly<{
+    /** Every waiting decision, in the order it joined. */
+    items: readonly AwaitingItem[];
+    /** Keys the person postponed with Later; they wait in the footer row. */
+    later: ReadonlySet<string>;
+    /** The person asked for the composer even though a draft is in it. */
+    forced: boolean;
+    /** Counts each request to answer, so a stalled item can start over. */
+    requests: number;
+}>;
 /** Everything a renderer draws for command conversations. */
 export type ParakeetInteractionState = Readonly<{
+    /** Decisions that take over the composer instead of opening a dialog. */
+    awaiting: ParakeetAwaiting;
     /** The interaction that needs the human, when one does. */
     open?: ParakeetOpenInteraction | undefined;
     /** A manually opened, live panel row from an admitted client entry. */
@@ -61,6 +75,17 @@ export type ParakeetInteractions = Readonly<{
     attach: (present: WhistleRuntime["present"]) => () => void;
     /** How the most recent interaction ended; a dismissal is not a failure to report. */
     lastEnd: () => WhistleInteractionEnd["status"] | undefined;
+    /** The queue of decisions the composer answers. */
+    awaiting: Readonly<{
+        /** Join the queue; the returned function leaves it. */
+        add: (item: AwaitingItem) => () => void;
+        /** Leave the queue. */
+        remove: (key: string) => void;
+        /** Postpone one decision: it leaves the composer but stays waiting. */
+        later: (key: string) => void;
+        /** Bring back the earliest postponed decision, even over a draft. */
+        focus: () => void;
+    }>;
 }>;
 /**
  * Own how commands talk to the human. An interaction opens only when it asks

package/dist/commands/interactions.js

@@ -5,7 +5,14 @@ import { createWhistleInteractionHost, } from "@fungi.computer/whistle/interacti
  * reports information emits a toast; ordinary success echoes are silent.
  */
 export function createParakeetInteractions() {
-    let state = {};
+    let state = {
+        awaiting: {
+            items: [],
+            later: new Set(),
+            forced: false,
+            requests: 0,
+        },
+    };
     let sequence = 0;
     let lastEnd;
     const listeners = new Set();
@@ -24,6 +31,30 @@ export function createParakeetInteractions() {
         for (const listener of listeners)
             listener();
     };
+    const setAwaiting = (next) => {
+        publish({ ...state, awaiting: { ...state.awaiting, ...next } });
+    };
+    const removeAwaiting = (key) => {
+        const { items, later } = state.awaiting;
+        if (!items.some((item) => item.key === key))
+            return;
+        setAwaiting({
+            items: items.filter((item) => item.key !== key),
+            later: new Set([...later].filter((postponed) => postponed !== key)),
+            forced: false,
+        });
+    };
+    const addAwaiting = (item) => {
+        setAwaiting({
+            items: [
+                ...state.awaiting.items.filter(({ key }) => key !== item.key),
+                item,
+            ],
+        });
+        return () => {
+            removeAwaiting(item.key);
+        };
+    };
     const closeKey = (key) => {
         if (state.open?.key === key)
             publish({ ...state, open: undefined });
@@ -36,6 +67,7 @@ export function createParakeetInteractions() {
             title,
             onEnd: (end) => {
                 lastEnd = end.status;
+                leaveQueue?.();
                 const message = host.snapshot().message;
                 if (!shown) {
                     if (end.status === "failed")
@@ -65,11 +97,28 @@ export function createParakeetInteractions() {
                     closeKey(key);
             },
         });
+        let leaveQueue;
         const unsubscribe = host.subscribe(() => {
             const current = host.snapshot();
             if (current.retryable)
                 hadRetryableFailure = true;
-            if (shown)
+            // A decision is the composer's, never a dialog's, even when the same
+            // conversation reached it through a dialog (a row action chooser).
+            if (leaveQueue === undefined &&
+                current.prompt?.request.type === "decision") {
+                if (shown) {
+                    shown = false;
+                    closeKey(key);
+                }
+                leaveQueue = addAwaiting({
+                    key: `interaction:${String(key)}`,
+                    kind: "question",
+                    arrivedAt: Date.now(),
+                    host,
+                });
+                return;
+            }
+            if (leaveQueue !== undefined || shown)
                 return;
             if (current.prompt === undefined &&
                 current.handoff === undefined &&
@@ -121,5 +170,30 @@ export function createParakeetInteractions() {
         },
         attach: (present) => present(presenter),
         lastEnd: () => lastEnd,
+        awaiting: {
+            add: addAwaiting,
+            remove: removeAwaiting,
+            later: (key) => {
+                if (!state.awaiting.items.some((item) => item.key === key))
+                    return;
+                setAwaiting({
+                    later: new Set([...state.awaiting.later, key]),
+                    forced: false,
+                });
+            },
+            focus: () => {
+                const { items, later, requests } = state.awaiting;
+                const earliest = [...items]
+                    .sort((left, right) => left.arrivedAt - right.arrivedAt)
+                    .find((item) => later.has(item.key));
+                setAwaiting({
+                    later: earliest === undefined
+                        ? later
+                        : new Set([...later].filter((key) => key !== earliest.key)),
+                    forced: items.length > 0,
+                    requests: requests + 1,
+                });
+            },
+        },
     };
 }

package/dist/commands/run.js

@@ -30,9 +30,9 @@ export async function runSlashDraft(draft, commands, send, origin, consumeDraft)
     if (command.consumesDraft && command.availability.status === "available")
         consumeDraft?.();
     if (parsed.arguments === undefined)
-        return commands.execute(command.commandId, { origin });
+        return commands.execute(command.command, { origin });
     if (requestIdField === undefined)
-        return commands.execute(command.commandId, {
+        return commands.execute(command.command, {
             origin,
             arguments: parsed.arguments,
         });
@@ -47,7 +47,7 @@ export async function runSlashDraft(draft, commands, send, origin, consumeDraft)
     };
     states.set(command.commandId, state);
     const running = commands
-        .execute(command.commandId, {
+        .execute(command.command, {
         origin,
         arguments: { ...parsed.arguments, [requestIdField]: state.requestId },
     })

package/dist/commands/slash.d.ts

@@ -1,10 +1,12 @@
-import type { WhistleAvailability, WhistleJsonObject, WhistleSlashArguments, WhistleSlashWord, WhistleSnapshot } from "@fungi.computer/whistle";
+import type { WhistleAvailability, WhistleCommandKey, WhistleJsonObject, WhistleSlashArguments, WhistleSlashWord, WhistleSnapshot } from "@fungi.computer/whistle";
 /** One slash command as every Parakeet renderer lists it. */
 export type SlashCommand = Readonly<{
     /** The alias typed after `/`. */
     alias: string;
-    /** Canonical Whistle command identity. */
+    /** Opaque Whistle render key. */
     commandId: string;
+    /** The command's typed Whistle identity; execute it by this. */
+    command: WhistleCommandKey;
     /** Consume this draft on dispatch, including for a dialog or refusal. */
     consumesDraft?: boolean | undefined;
     /** Human-facing title. */
@@ -24,8 +26,10 @@ export type SlashCommand = Readonly<{
 }>;
 /** One key binding as help and hint surfaces list it. */
 export type KeyBindingRow = Readonly<{
-    /** Canonical Whistle command identity. */
+    /** Opaque Whistle render key. */
     commandId: string;
+    /** The command's typed Whistle identity; execute it by this. */
+    command: WhistleCommandKey;
     /** Human key label, e.g. `Ctrl+O`. */
     keys: string;
     /** What the key does. */

package/dist/commands/slash.js

@@ -31,6 +31,7 @@ export function slashRegistry(snapshot) {
     return snapshot.slash.map((row) => ({
         alias: row.alias,
         commandId: row.commandId,
+        command: row.command,
         title: row.title,
         description: row.description,
         category: row.category,
@@ -48,6 +49,7 @@ export function keyBindings(snapshot) {
         const current = rows.get(row.commandId);
         rows.set(row.commandId, {
             commandId: row.commandId,
+            command: row.command,
             keys: current === undefined
                 ? keyLabel(row.binding)
                 : `${current.keys}, ${keyLabel(row.binding)}`,

package/dist/commands/use-slash-commands.d.ts

@@ -1,5 +1,6 @@
 import type { PromptDelivery } from "@fungi.computer/shiitake/client";
 import type { WhistleExecutionOrigin, WhistleRuntime } from "@fungi.computer/whistle";
+import { type AwaitingQueue } from "../core/awaiting-answer.js";
 import { type ComposerKeys, type KeyHint } from "./hints.js";
 import { type ParakeetInteractions, type ParakeetInteractionState } from "./interactions.js";
 import { type SlashCompletion } from "./slash.js";
@@ -36,6 +37,14 @@ export type SlashCommandController = Readonly<{
     interactions: ParakeetInteractionState;
     /** The conversation store, for closing and retrying dialogs. */
     store: ParakeetInteractions;
+    /**
+     * The decision the composer is answering, if any. It takes over an empty
+     * composer, or any composer once the person asked for it (`forced`).
+     */
+    awaiting: AwaitingQueue & Readonly<{
+        /** The person asked for the composer even though a draft is in it. */
+        forced: boolean;
+    }>;
     /** Move the highlight; false when no list is open. */
     move: (delta: -1 | 1) => boolean;
     /** Highlight one row (pointer hover). */
@@ -48,6 +57,10 @@ export type SlashCommandController = Readonly<{
     submit: (delivery?: PromptDelivery) => void;
     /** Run one completion row (pointer choice). */
     choose: (index: number) => void;
+    /** Whether a registered command answers this slash alias and can run now. */
+    available: (alias: string) => boolean;
+    /** Run the command behind a slash alias, as typing it would, leaving the draft alone. */
+    runCommand: (alias: string) => void;
 }>;
 /**
  * The one slash-command controller behind every Parakeet composer. It owns

package/dist/commands/use-slash-commands.js

@@ -1,5 +1,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
-import { useComposer, useClientContributions, useExtensionSlots, useParakeetSession, useParakeetInteractions, } from "../conversation.js";
+import { useComposer, useClientContributions, useExtensionSlots, useParakeetSession, useParakeetInteractions, useStatus, } from "../conversation.js";
+import { awaitingQueue } from "../core/awaiting-answer.js";
+import { useAwaitingDriver } from "./awaiting-driver.js";
 import { advertisedCommands } from "./advertised.js";
 import { parakeetBuiltinCommands } from "./builtins.js";
 import { composerHints } from "./hints.js";
@@ -39,6 +41,10 @@ export function useSlashCommands(options) {
                 entry.value.panel.some((row) => row.id === inspection.rowId && row.inspection !== undefined)))
             store.inspect(undefined);
     }, [contributions, interactions.inspection, store]);
+    const awaiting = {
+        ...awaitingQueue(interactions.awaiting.items, interactions.awaiting.later),
+        forced: interactions.awaiting.forced,
+    };
     const snapshot = useSyncExternalStore(commands.subscribe, commands.snapshot, commands.snapshot);
     const composerRef = useRef(composer);
     composerRef.current = composer;
@@ -92,6 +98,44 @@ export function useSlashCommands(options) {
                 message: `${error.extensionId} commands are unavailable: ${error.message}`,
             });
     }, [advertised, enabled, slots, contributions, store]);
+    const { observation } = useStatus();
+    useAwaitingDriver({
+        enabled,
+        commands,
+        store,
+        contributions,
+        online: observation.status === "live",
+        requests: interactions.awaiting.requests,
+        commandsVersion: snapshot,
+    });
+    const waiting = interactions.awaiting.items.length > 0;
+    useEffect(() => {
+        if (!enabled || !waiting)
+            return;
+        const lease = commands.contribute({
+            sourceId: "parakeet-awaiting",
+            namespace: "parakeet-awaiting",
+            commands: [
+                {
+                    id: "answer",
+                    title: "Answer a question",
+                    category: "Conversation",
+                    description: "Answer what the Agent is waiting on",
+                    projections: {
+                        help: { order: 5 },
+                        palette: { order: 5 },
+                        slash: { aliases: ["answer"], order: 5, consumesDraft: true },
+                    },
+                    handler: () => {
+                        store.awaiting.focus();
+                    },
+                },
+            ],
+        });
+        return () => {
+            lease.dispose();
+        };
+    }, [commands, enabled, store, waiting]);
     const registry = useMemo(() => slashRegistry(snapshot), [snapshot]);
     const [dismissed, setDismissed] = useState();
     const [highlighted, setHighlighted] = useState({ draft: "", index: 0 });
@@ -157,6 +201,7 @@ export function useSlashCommands(options) {
         hints,
         interactions,
         store,
+        awaiting,
         move: (delta) => {
             if (rowCount === 0)
                 return false;
@@ -203,5 +248,17 @@ export function useSlashCommands(options) {
             run(delivery, insert?.trimEnd());
         },
         choose,
+        available: (alias) => registry.some((command) => command.alias === alias &&
+            command.availability.status === "available"),
+        runCommand: (alias) => {
+            store.report(undefined);
+            void runSlashDraft(`/${alias}`, commands, () => undefined, origin).then((outcome) => {
+                const message = failureMessage(outcome);
+                if (message !== undefined &&
+                    store.snapshot().open === undefined &&
+                    store.lastEnd() !== "cancelled")
+                    store.report({ tone: "error", message: `/${alias}: ${message}` });
+            });
+        },
     };
 }

package/dist/components/ChatComposer.d.ts

@@ -39,6 +39,8 @@ export type ChatComposerProps = {
     context?: SessionContext | undefined;
     /** Parakeet's slash controller; the composer only draws and forwards keys. */
     slash?: SlashCommandController | undefined;
+    /** Replace the images riding with the draft; omitted, the composer offers no Attach key. */
+    onImagesChange?: ((images: ComposerController["images"]) => void) | undefined;
 };
 /** Full Session readout for announcements; the footer only draws attention states. */
 export declare function sessionReadout(status: ParakeetStatus, view: ParakeetSessionViewState): string;