@fungi.computer/parakeet 0.1.0 → 0.2.0

package/README.md

@@ -126,17 +126,56 @@ It owns parsing, completion, stable request identities and interaction state.
 The browser and terminal render the same questions, choices and notices.
 `/model` and `/thinking` use that interaction path.
 
+`ParakeetProvider` accepts `onToast` for transient command information. The host
+renders it through its existing toast owner: the terminal's shared toast
+viewport or Grove's `ui.showToast`. `ParakeetInteractions.toast` and
+`subscribeToasts` expose the same renderer-neutral seam. Ordinary first-success
+echoes are silent, including after a dialog completes. Progress, questions and
+handoffs remain in their interaction while active; failures retain their retry
+or attention UI rather than expiring as information.
+
+After Try again, a final information or success notice stays in that
+interaction's existing result row until Done/close, without an extra toast. A
+producer that supplies no completion notice does not gain a fabricated result.
+
 Account commands are provider-neutral. The host's account owner and policy
 decide which login methods are available. The presentation layer does not gain a
 credential store or make an advertised command authorized.
 
+Queued timeline rows offer Cancel through
+`useTimeline().cancelQueued(commandId)`. The row disappears immediately while
+the existing Session owner decides the pending-only cancellation. This never
+stops the running turn or restores text to the composer. TooLate or an
+unconfirmed response produces a warning and restores any row still reported as
+queued; an accepted response stays hidden through stale queued snapshots until
+the owner projection catches up. Only one queued gesture waits for its owner at
+a time, and switching conversations discards its presentation state. Recall
+remains a separate restore-to-composer gesture.
+
 The composer reconciles optimistic prompts with owner facts by request identity.
-Retrying a failed admission preserves its request identity. Retrying failed or
-interrupted durable work submits a new request identity. Failed observation
-shows connection failure; reconnecting does not prove pending work failed or
-resubmit it automatically. Typed command errors remain visible and retryable.
-The host remains responsible for the Session transport, current permissions and
-operator diagnostics.
+Submitting clears the draft immediately and adds a faded pending message.
+Acceptance restores normal emphasis; owner-queued messages remain faded. If
+admission fails, the exact submitted text returns to the composer and the host
+receives an error toast. Any newer draft stays first, followed by a blank line
+and the restored text; acceptance never clears newer typing. An uncertain
+admission retains its request identity while the owner resolves it. An accepted
+resolution confirms the admitted command or recorded entry; only confirmed
+withdrawal restores the draft and permits retry with a new request identity,
+because the old identity is durably fenced. Retrying failed or interrupted
+durable work also submits a new request identity, preserving the failed prompt's
+text and image cargo, including image-only prompts after live-page eviction. It
+does not consume a newer unsent draft. Failed observation shows connection
+failure; reconnecting does not prove pending work failed or resubmit it
+automatically. Typed command errors remain visible and retryable. The host
+remains responsible for the Session transport, current permissions and operator
+diagnostics.
+
+An owner's accepted withdrawal receipt can name a run-free recorded entry:
+`receipt.commandId === message.id` even though `message.commandId === null`.
+That receipt confirms durable recording, not cancellation or model admission. A
+translating host retains the original composer identity in its durable metadata
+and projects it as `messages[].requestId` or `pending.prompts[].requestId`; its
+internal admission key is not that identity.
 
 ## API and examples
 

package/dist/account-commands.js

@@ -91,17 +91,13 @@ export async function signInProvider(owner, provider, interaction, request = {})
         type: "progress",
         message: `Signing in to ${provider.name}…`,
     });
-    await owner.login(request.option === undefined
+    await interaction.run(() => owner.login(request.option === undefined
         ? { providerId: provider.id, method: method.kind }
         : {
             providerId: provider.id,
             method: method.kind,
             option: request.option,
-        }, interaction);
-    interaction.notify({
-        type: "success",
-        message: `Signed in to ${provider.name}.`,
-    });
+        }, interaction));
 }
 async function signOutProvider(owner, provider, interaction) {
     const confirmed = await interaction.prompt({
@@ -112,11 +108,7 @@ async function signOutProvider(owner, provider, interaction) {
     });
     if (!confirmed)
         return;
-    await owner.logout(provider.id, interaction);
-    interaction.notify({
-        type: "success",
-        message: `Signed out of ${provider.name}.`,
-    });
+    await interaction.run(() => owner.logout(provider.id, interaction));
 }
 /** Cancelling a sign-in is an ordinary ending, not a failure. */
 async function unlessCancelled(interaction, work) {

package/dist/commands/advertised.d.ts

@@ -1,6 +1,7 @@
 import type { SessionExtensionSlots } from "@fungi.computer/shiitake/client";
 import type { WhistleRuntime } from "@fungi.computer/whistle";
 import type { ParakeetSession } from "../session.js";
+import type { ClientContribution } from "../core/client-contributions.js";
 /** Why one advertised catalog could not become commands. */
 export type AdvertisedCatalogError = Readonly<{
     /** The extension that advertised it. */
@@ -19,5 +20,6 @@ export type AdvertisedCommands = Readonly<{
  * Turn each running extension's advertised `whistle.catalog/v1` catalog into
  * Whistle commands that call that extension's own door. The client names no
  * command: a new extension's catalog appears as new commands.
+ * @param contributions - Current admitted panels that own unanswered prompts.
  */
-export declare function advertisedCommands(runtime: Pick<WhistleRuntime, "contribute">, session: Pick<ParakeetSession, "extension">, onInspect?: (entryId: string, commandId: string) => void): AdvertisedCommands;
+export declare function advertisedCommands(runtime: Pick<WhistleRuntime, "contribute">, session: Pick<ParakeetSession, "extension">, contributions: () => readonly ClientContribution[], onInspect?: (entryId: string, commandId: string) => void): AdvertisedCommands;

package/dist/commands/advertised.js

@@ -1,5 +1,5 @@
 import * as Schema from "effect/Schema";
-import { catalogCommands, parseCatalog } from "@fungi.computer/whistle/catalog";
+import { catalogCommands, parseCatalog, parseCatalogStep, } from "@fungi.computer/whistle/catalog";
 const cancelled = Schema.is(Schema.Struct({ cancelled: Schema.Literal(true) }));
 /** A bare invocation views; one carrying action arguments (`/plan clear`) acts. */
 const bare = Schema.is(Schema.UndefinedOr(Schema.Record(Schema.String, Schema.Never)));
@@ -7,9 +7,28 @@ const bare = Schema.is(Schema.UndefinedOr(Schema.Record(Schema.String, Schema.Ne
  * Turn each running extension's advertised `whistle.catalog/v1` catalog into
  * Whistle commands that call that extension's own door. The client names no
  * command: a new extension's catalog appears as new commands.
+ * @param contributions - Current admitted panels that own unanswered prompts.
  */
-export function advertisedCommands(runtime, session, onInspect) {
+export function advertisedCommands(runtime, session, contributions, onInspect) {
     const live = new Map();
+    const panelActions = (id, command) => contributions()
+        .find((entry) => entry.entryId === id)
+        ?.value.panel.flatMap((row) => row.actions ?? [])
+        .filter((action) => action.id === command) ?? [];
+    const intent = (action) => JSON.stringify([action.id, action.input ?? {}]);
+    // A prompt borrows its panel intent, not the entire backend operation.
+    // Once answered, its pending response must retain its ordinary lifetime.
+    const prompts = new Set();
+    const refreshPrompts = () => {
+        for (const prompt of prompts) {
+            const visible = new Set(panelActions(prompt.entryId, prompt.commandId).map(intent));
+            if (live.has(prompt.entryId) &&
+                prompt.intents.every((id) => visible.has(id)))
+                continue;
+            prompt.execution.withdrawn = true;
+            prompt.controller.abort();
+        }
+    };
     const withdraw = (id) => {
         live.get(id)?.lease.dispose();
         live.delete(id);
@@ -31,7 +50,8 @@ export function advertisedCommands(runtime, session, onInspect) {
                 withdraw(id);
                 try {
                     const address = session.extension(id);
-                    const commands = catalogCommands(parseCatalog(slot.catalog), (command, args) => address.call(command, args));
+                    const catalog = parseCatalog(slot.catalog);
+                    const commands = catalogCommands(catalog, (command, args) => address.call(command, args));
                     live.set(id, {
                         catalog: encoded,
                         lease: runtime.contribute({
@@ -40,7 +60,70 @@ export function advertisedCommands(runtime, session, onInspect) {
                             commands: commands.map((command) => ({
                                 ...command,
                                 handler: async (input) => {
-                                    const result = await command.handler(input);
+                                    const actions = panelActions(id, command.id);
+                                    const execution = {
+                                        intents: actions.map(intent),
+                                        withdrawn: false,
+                                    };
+                                    // Invocation-local closures retain admitted identities only.
+                                    // A caller may share its signal and pass secret arguments.
+                                    const scopedCommand = catalogCommands(catalog, async (name, args) => {
+                                        const reply = await address.call(name, args);
+                                        const step = parseCatalogStep(reply);
+                                        if (step.type === "prompt") {
+                                            const selected = actions.filter((action) => Object.entries(action.input ?? {}).every(([key, value]) => JSON.stringify(Object.hasOwn(step.next.arguments, key)
+                                                ? step.next.arguments[key]
+                                                : args[key]) === JSON.stringify(value)));
+                                            // Before selection, a chooser borrows all its candidates.
+                                            execution.intents = (selected.length > 0 ? selected : actions).map(intent);
+                                        }
+                                        return reply;
+                                    }).find((candidate) => candidate.id === command.id);
+                                    if (scopedCommand === undefined)
+                                        throw new Error("The advertised command is unavailable");
+                                    let scoped = input;
+                                    const interaction = input.interaction;
+                                    if (interaction !== undefined) {
+                                        const bound = {
+                                            ...interaction,
+                                            prompt: (request, options) => {
+                                                const prompt = {
+                                                    entryId: id,
+                                                    commandId: command.id,
+                                                    intents: execution.intents,
+                                                    execution,
+                                                    controller: new AbortController(),
+                                                };
+                                                prompts.add(prompt);
+                                                refreshPrompts();
+                                                return interaction
+                                                    .prompt(request, {
+                                                    signal: options?.signal === undefined
+                                                        ? prompt.controller.signal
+                                                        : AbortSignal.any([
+                                                            options.signal,
+                                                            prompt.controller.signal,
+                                                        ]),
+                                                })
+                                                    .finally(() => prompts.delete(prompt));
+                                            },
+                                        };
+                                        scoped = { ...scoped, interaction: bound };
+                                    }
+                                    let result;
+                                    try {
+                                        result = await scopedCommand.handler(scoped);
+                                    }
+                                    catch (cause) {
+                                        if (execution.withdrawn)
+                                            return { cancelled: true };
+                                        throw cause;
+                                    }
+                                    finally {
+                                        for (const prompt of prompts)
+                                            if (prompt.execution === execution)
+                                                prompts.delete(prompt);
+                                    }
                                     if (input.origin !== "agent" &&
                                         bare(input.arguments) &&
                                         !cancelled(result) &&
@@ -62,11 +145,13 @@ export function advertisedCommands(runtime, session, onInspect) {
                     });
                 }
             }
+            refreshPrompts();
             return errors;
         },
         dispose: () => {
             for (const id of live.keys())
                 withdraw(id);
+            refreshPrompts();
         },
     };
 }

package/dist/commands/interactions.d.ts

@@ -6,13 +6,24 @@ export type ParakeetOpenInteraction = Readonly<{
     key: number;
     /** The renderer-neutral interaction store to draw. */
     host: WhistleInteractionHost;
-    /** Run the same command again with the same input. */
-    retry: () => void;
 }>;
-/** A one-line result shown beside the composer instead of a dialog. */
+/**
+ * An attention item shown beside the composer until it is resolved: something
+ * failed or waits on the person. Everything else is a toast.
+ */
 export type ParakeetNotice = Readonly<{
     /** How to color it. */
-    tone: "info" | "success" | "error";
+    tone: "info" | "error";
+    /** What happened. */
+    message: string;
+}>;
+/**
+ * A transient message a renderer shows as a toast. A command's confirmation of
+ * what the person just did is never one: it is an echo and is not announced.
+ */
+export type ParakeetToast = Readonly<{
+    /** How to color it. */
+    variant: "info" | "warning" | "error";
     /** What happened. */
     message: string;
 }>;
@@ -27,7 +38,7 @@ export type ParakeetInteractionState = Readonly<{
         /** Stable identity of the panel row being inspected. */
         rowId: string;
     }> | undefined;
-    /** The latest one-line result. */
+    /** The latest attention item: it stays until the person resolves it. */
     notice?: ParakeetNotice | undefined;
 }>;
 /** Parakeet's command conversation store, shared by every renderer. */
@@ -40,8 +51,12 @@ export type ParakeetInteractions = Readonly<{
     close: () => void;
     /** Open or dismiss an admitted panel inspection without starting a command. */
     inspect: (inspection: ParakeetInteractionState["inspection"]) => void;
-    /** Replace or clear the one-line notice, starting a new command turn. */
+    /** Replace or clear the attention notice, starting a new command turn. */
     report: (notice: ParakeetNotice | undefined) => void;
+    /** Announce a transient message to every toast subscriber. */
+    toast: (toast: ParakeetToast) => void;
+    /** Receive transient messages; the renderer decides how to show them. */
+    subscribeToasts: (listener: (toast: ParakeetToast) => void) => () => void;
     /** Become the runtime's presenter until the returned disposer runs. */
     attach: (present: WhistleRuntime["present"]) => () => void;
     /** How the most recent interaction ended; a dismissal is not a failure to report. */
@@ -50,6 +65,6 @@ export type ParakeetInteractions = Readonly<{
 /**
  * Own how commands talk to the human. An interaction opens only when it asks
  * a question, hands off to a URL or shows progress; a command that just
- * reports a result leaves a one-line notice instead of a dialog.
+ * reports information emits a toast; ordinary success echoes are silent.
  */
 export declare function createParakeetInteractions(): ParakeetInteractions;

package/dist/commands/interactions.js

@@ -2,13 +2,23 @@ import { createWhistleInteractionHost, } from "@fungi.computer/whistle/interacti
 /**
  * Own how commands talk to the human. An interaction opens only when it asks
  * a question, hands off to a URL or shows progress; a command that just
- * reports a result leaves a one-line notice instead of a dialog.
+ * reports information emits a toast; ordinary success echoes are silent.
  */
 export function createParakeetInteractions() {
     let state = {};
     let sequence = 0;
     let lastEnd;
     const listeners = new Set();
+    const toastListeners = new Set();
+    const toast = (next) => {
+        for (const listener of toastListeners)
+            listener(next);
+    };
+    /** Information is a toast; a success only echoes what the person did. */
+    const announce = (message) => {
+        if (message.type === "info")
+            toast({ variant: "info", message: message.message });
+    };
     const publish = (next) => {
         state = next;
         for (const listener of listeners)
@@ -18,9 +28,10 @@ export function createParakeetInteractions() {
         if (state.open?.key === key)
             publish({ ...state, open: undefined });
     };
-    const presenter = ({ title, retry }) => {
+    const presenter = ({ title }) => {
         const key = ++sequence;
         let shown = false;
+        let hadRetryableFailure = false;
         const host = createWhistleInteractionHost({
             title,
             onEnd: (end) => {
@@ -32,35 +43,41 @@ export function createParakeetInteractions() {
                             ...state,
                             notice: { tone: "error", message: end.message },
                         });
-                    else if (message !== undefined && message.type !== "progress")
-                        publish({
-                            ...state,
-                            notice: {
-                                tone: message.type === "success" ? "success" : "info",
-                                message: message.message,
-                            },
-                        });
+                    else if (message !== undefined)
+                        announce(message);
                     return;
                 }
-                const lingers = end.status === "failed" ||
-                    (end.status === "handled" &&
-                        message !== undefined &&
-                        message.type !== "progress");
-                if (!lingers)
+                // A retried result stays in the same notice row until Done. A
+                // progress-only ending is not a completion notice to manufacture.
+                if (end.status === "handled" &&
+                    hadRetryableFailure &&
+                    message !== undefined &&
+                    message.type !== "progress")
+                    return;
+                const closing = host.snapshot().closing;
+                if (end.status === "cancelled" && closing !== undefined)
+                    announce(closing);
+                if (end.status === "handled" && message !== undefined)
+                    announce(message);
+                // Failed interactions retain their failure UI; ordinary results never
+                // leave a dialog behind just to confirm the completed action.
+                if (end.status !== "failed")
                     closeKey(key);
             },
         });
         const unsubscribe = host.subscribe(() => {
+            const current = host.snapshot();
+            if (current.retryable)
+                hadRetryableFailure = true;
             if (shown)
                 return;
-            const current = host.snapshot();
             if (current.prompt === undefined &&
                 current.handoff === undefined &&
                 current.message?.type !== "progress")
                 return;
             shown = true;
             const previous = state.open;
-            publish({ ...state, open: { key, host, retry }, notice: undefined });
+            publish({ ...state, open: { key, host }, notice: undefined });
             previous?.host.cancel();
         });
         const session = host.begin();
@@ -95,6 +112,13 @@ export function createParakeetInteractions() {
             lastEnd = undefined;
             publish({ ...state, notice });
         },
+        toast,
+        subscribeToasts: (listener) => {
+            toastListeners.add(listener);
+            return () => {
+                toastListeners.delete(listener);
+            };
+        },
         attach: (present) => present(presenter),
         lastEnd: () => lastEnd,
     };

package/dist/commands/slash.js

@@ -1,12 +1,10 @@
 /** Human key labels from Whistle bindings, with the platform's modifier name. */
 export function keyLabel(binding, mac = /Mac|iPhone|iPad/u.test(globalThis.navigator.userAgent)) {
+    if (binding.startsWith("<leader>"))
+        return `Ctrl K ${binding.slice("<leader>".length)}`;
     return binding
         .split(" ")
-        .map((chord, index) => {
-        if (chord === "<leader>")
-            return "Ctrl K";
-        if (index > 0 && binding.startsWith("<leader> "))
-            return chord;
+        .map((chord) => {
         const parts = chord
             .split("+")
             .map((part) => part === "mod"

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

@@ -70,7 +70,7 @@ export function useSlashCommands(options) {
             lease.dispose();
         };
     }, [commands, enabled, store, hasCommandPalette]);
-    const advertised = useMemo(() => advertisedCommands(commands, session, (entryId, commandId) => {
+    const advertised = useMemo(() => advertisedCommands(commands, session, () => contributionsRef.current, (entryId, commandId) => {
         const row = contributionsRef.current
             .find((entry) => entry.entryId === entryId)
             ?.value.panel.find((row) => row.inspection?.commandId === commandId);
@@ -91,7 +91,7 @@ export function useSlashCommands(options) {
                 tone: "error",
                 message: `${error.extensionId} commands are unavailable: ${error.message}`,
             });
-    }, [advertised, enabled, slots, store]);
+    }, [advertised, enabled, slots, contributions, store]);
     const registry = useMemo(() => slashRegistry(snapshot), [snapshot]);
     const [dismissed, setDismissed] = useState();
     const [highlighted, setHighlighted] = useState({ draft: "", index: 0 });

package/dist/components/AgentHead.d.ts

@@ -9,6 +9,8 @@ export type AgentHeadActivity = "idle" | "thinking" | "speaking";
  * idle head shows its real look without animating.
  */
 export declare const AgentHead: import("react").NamedExoticComponent<{
+    /** External animation clock in milliseconds; omitted uses live motion. */
+    timeMs?: number;
     /** Motion presented by the head; defaults to idle. */
     activity?: AgentHeadActivity;
     /** The Agent's avatar, from its Agent record. */

package/dist/components/AgentHead.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Monogram } from "@fungi.computer/caps/components/monogram";
-import { Sprite } from "@fungi.computer/sprite/react";
+import { Sprite, useAnimationTime } from "@fungi.computer/sprite/react";
 import { memo, useMemo, useState } from "react";
 import { avatarPresentation } from "./avatar-presentation.js";
 import { shiitakeSprite } from "./sprite-service.js";
@@ -11,10 +11,11 @@ import { shiitakeSprite } from "./sprite-service.js";
  * canvas stays mounted and is paused unless `thinking` or `speaking`, so an
  * idle head shows its real look without animating.
  */
-export const AgentHead = memo(function AgentHead({ activity = "idle", avatar, className, name, size = 24, }) {
+export const AgentHead = memo(function AgentHead({ activity = "idle", avatar, className, name, size = 24, timeMs: explicitTimeMs, }) {
+    const timeMs = useAnimationTime(explicitTimeMs);
     const [ready, setReady] = useState(false);
     const presentation = useMemo(() => avatarPresentation(avatar), [avatar]);
-    return (_jsxs("span", { "aria-hidden": "true", className: `relative inline-block shrink-0 ${className ?? ""}`, "data-agent-head": ready ? "ready" : "loading", style: { height: size, width: size }, children: [ready ? null : (_jsx(Monogram, { className: "absolute inset-0", name: name, seed: name })), _jsx(Sprite, { activity: activity, appearance: presentation.appearance, className: "absolute inset-0", expression: presentation.expression, onState: (state) => {
+    return (_jsxs("span", { "aria-hidden": "true", className: `relative inline-block shrink-0 ${className ?? ""}`, "data-agent-head": ready ? "ready" : "loading", style: { height: size, width: size }, children: [ready ? null : (_jsx(Monogram, { className: "absolute inset-0", name: name, seed: name })), _jsx(Sprite, { activity: activity, ...(timeMs === undefined ? {} : { timeMs }), appearance: presentation.appearance, className: "absolute inset-0", expression: presentation.expression, onState: (state) => {
                     setReady(state.status === "ready");
-                }, paused: activity === "idle", renderStyle: presentation.renderStyle, service: shiitakeSprite, src: presentation.src })] }));
+                }, paused: timeMs !== undefined || activity === "idle", renderStyle: presentation.renderStyle, service: shiitakeSprite, src: presentation.src })] }));
 });

package/dist/components/ChatComposer.d.ts

@@ -11,6 +11,8 @@ export type ChatComposerUsage = Readonly<{
     tokens: number;
 }>;
 export type ChatComposerProps = {
+    /** Undefined for visitor composers without a caller-owned pending queue. */
+    queuedRecall: Pick<ComposerController, "recall" | "recallState" | "images"> | undefined;
     /** Caller-owned prompt hint; omitted for the ordinary Session composer. */
     placeholder?: string | undefined;
     /** Hide internal model, usage and status readouts for visitors. */
@@ -38,6 +40,6 @@ export type ChatComposerProps = {
     /** Parakeet's slash controller; the composer only draws and forwards keys. */
     slash?: SlashCommandController | undefined;
 };
-/** Shared visible and screen-reader readout of the observed Session state. */
+/** Full Session readout for announcements; the footer only draws attention states. */
 export declare function sessionReadout(status: ParakeetStatus, view: ParakeetSessionViewState): string;
 export declare const ChatComposer: import("react").NamedExoticComponent<ChatComposerProps>;