@fungi.computer/parakeet 0.0.0-stage → 0.0.1

package/dist/commands/slash.js

@@ -0,0 +1,182 @@
+/** 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)) {
+    return binding
+        .split(" ")
+        .map((chord, index) => {
+        if (chord === "<leader>")
+            return "Ctrl K";
+        if (index > 0 && binding.startsWith("<leader> "))
+            return chord;
+        const parts = chord
+            .split("+")
+            .map((part) => part === "mod"
+            ? mac
+                ? "⌘"
+                : "Ctrl"
+            : part === "escape"
+                ? "Esc"
+                : part.length === 1
+                    ? part.toUpperCase()
+                    : part.charAt(0).toUpperCase() + part.slice(1));
+        return parts.join(chord === "ctrl+k" || chord === "mod+k" ? " " : "+");
+    })
+        .join(" ");
+}
+/** Every slash alias in the live graph, with the keys bound to its command. */
+export function slashRegistry(snapshot) {
+    const keys = new Map();
+    for (const row of snapshot.bindings)
+        keys.set(row.commandId, [
+            ...(keys.get(row.commandId) ?? []),
+            keyLabel(row.binding),
+        ]);
+    return snapshot.slash.map((row) => ({
+        alias: row.alias,
+        commandId: row.commandId,
+        title: row.title,
+        description: row.description,
+        category: row.category,
+        order: row.order,
+        grammar: row.arguments,
+        keys: keys.get(row.commandId) ?? [],
+        availability: row.availability,
+    }));
+}
+/** Every bound key in the live graph, grouped by command. */
+export function keyBindings(snapshot) {
+    const rows = new Map();
+    for (const row of snapshot.bindings) {
+        const current = rows.get(row.commandId);
+        rows.set(row.commandId, {
+            commandId: row.commandId,
+            keys: current === undefined
+                ? keyLabel(row.binding)
+                : `${current.keys}, ${keyLabel(row.binding)}`,
+            title: row.title,
+            order: current?.order ?? row.order,
+        });
+    }
+    return [...rows.values()];
+}
+function usage(command) {
+    const words = command.grammar?.words?.map(({ word }) => word) ?? [];
+    if (command.grammar === undefined)
+        return `/${command.alias} takes no arguments.`;
+    if (command.grammar.text !== undefined)
+        return `Use /${command.alias} ${command.grammar.hint}.`;
+    return `Use /${command.alias} ${words.join(" or ")}.`;
+}
+/** Parse one draft against the registry; only a leading `/` names a command. */
+export function parseSlashDraft(registry, draft) {
+    if (!draft.startsWith("/"))
+        return { kind: "prompt" };
+    const match = /^\/(\S*)(?:\s+([\s\S]*))?$/u.exec(draft.trimEnd());
+    const alias = match?.[1] ?? "";
+    const rest = (match?.[2] ?? "").trim();
+    const command = registry.find((candidate) => candidate.alias === alias);
+    if (command === undefined)
+        return {
+            kind: "invalid",
+            message: `Unsupported command: /${alias}. Use /help for available commands.`,
+        };
+    if (rest.length === 0)
+        return { kind: "command", command };
+    const grammar = command.grammar;
+    const word = grammar?.words?.find((candidate) => candidate.word === rest);
+    if (word !== undefined)
+        return { kind: "command", command, arguments: word.arguments };
+    if (grammar?.text === undefined)
+        return { kind: "invalid", message: usage(command) };
+    return {
+        kind: "command",
+        command,
+        arguments: { ...grammar.text.arguments, [grammar.text.field]: rest },
+        requestIdField: grammar.text.requestIdField,
+    };
+}
+/**
+ * Fuzzy match: a prefix beats a word start beats a substring beats an
+ * in-order subsequence; tighter subsequences rank first.
+ */
+export function fuzzyMatch(candidate, query) {
+    const text = candidate.toLocaleLowerCase();
+    const needle = query.toLocaleLowerCase();
+    if (needle.length === 0)
+        return { tier: 0, spread: 0, indices: [] };
+    const range = (start) => Array.from({ length: needle.length }, (_, offset) => start + offset);
+    if (text.startsWith(needle))
+        return { tier: 0, spread: text.length - needle.length, indices: range(0) };
+    const wordStart = text.search(new RegExp(`[-_\\s]${needle.replaceAll(/[.*+?^${}()|[\]\\]/gu, "\\$&")}`, "u"));
+    if (wordStart >= 0)
+        return { tier: 1, spread: wordStart, indices: range(wordStart + 1) };
+    const inside = text.indexOf(needle);
+    if (inside >= 0)
+        return { tier: 2, spread: inside, indices: range(inside) };
+    const indices = [];
+    let from = 0;
+    for (const character of needle) {
+        const found = text.indexOf(character, from);
+        if (found < 0)
+            return undefined;
+        indices.push(found);
+        from = found + 1;
+    }
+    const first = indices[0] ?? 0;
+    const last = indices.at(-1) ?? 0;
+    return { tier: 3, spread: last - first - needle.length + 1, indices };
+}
+function rank(entries, text, query, order) {
+    return entries
+        .map((entry) => ({ entry, match: fuzzyMatch(text(entry), query) }))
+        .filter((scored) => scored.match !== undefined)
+        .sort((left, right) => left.match.tier - right.match.tier ||
+        left.match.spread - right.match.spread ||
+        order(left.entry) - order(right.entry) ||
+        text(left.entry).localeCompare(text(right.entry)))
+        .map(({ entry, match }) => ({ entry, indices: match.indices }));
+}
+/** Rank completions for one draft; renderers draw exactly these rows. */
+export function completeSlash(registry, draft, options = {}) {
+    if (!draft.startsWith("/") || draft.includes("\n"))
+        return { kind: "none" };
+    const space = draft.search(/\s/u);
+    if (space < 0) {
+        const query = draft.slice(1);
+        const items = rank(registry.filter((command) => command.availability.status === "available" &&
+            (query.length === 0
+                ? command.category === (options.idleCategory ?? "Conversation")
+                : command.category !== "Advanced" ||
+                    command.alias
+                        .toLocaleLowerCase()
+                        .startsWith(query.toLocaleLowerCase()))), (command) => command.alias, query, (command) => command.order).map(({ entry, indices }) => ({
+            command: entry,
+            label: `/${entry.alias}`,
+            matches: indices.map((index) => index + 1),
+            insert: entry.grammar === undefined ? `/${entry.alias}` : `/${entry.alias} `,
+        }));
+        return { kind: "commands", query, items };
+    }
+    const alias = draft.slice(1, space);
+    const command = registry.find((candidate) => candidate.alias === alias);
+    if (command?.grammar === undefined ||
+        command.availability.status !== "available")
+        return { kind: "none" };
+    const query = draft.slice(space).trimStart();
+    // Words match by prefix only, so free text is never mistaken for a word.
+    const words = query.includes(" ") ? [] : (command.grammar.words ?? []);
+    const items = words
+        .filter((word) => word.word.toLocaleLowerCase().startsWith(query.toLocaleLowerCase()))
+        .map((word) => ({
+        word,
+        label: word.word,
+        matches: Array.from({ length: query.length }, (_, index) => index),
+        insert: `/${alias} ${word.word}`,
+    }));
+    return {
+        kind: "arguments",
+        command,
+        query,
+        hint: `/${alias} ${command.grammar.hint}`,
+        items,
+    };
+}

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

@@ -0,0 +1,57 @@
+import type { PromptDelivery } from "@fungi.computer/shiitake/client";
+import type { WhistleExecutionOrigin, WhistleRuntime } from "@fungi.computer/whistle";
+import { type ComposerKeys, type KeyHint } from "./hints.js";
+import { type ParakeetInteractions, type ParakeetInteractionState } from "./interactions.js";
+import { type SlashCompletion } from "./slash.js";
+/** The Whistle runtime a Parakeet composer runs commands through. */
+export type ParakeetCommandRuntime = Pick<WhistleRuntime, "contribute" | "snapshot" | "subscribe" | "execute" | "present">;
+/** Inputs for one composer's command controller. */
+export type SlashCommandOptions = Readonly<{
+    /** Disable command registration, completion and execution for visitor conversations. */
+    enabled?: boolean;
+    /** The runtime holding host, built-in and advertised commands. */
+    commands: ParakeetCommandRuntime;
+    /** Execution origin for commands typed in this composer. */
+    origin: WhistleExecutionOrigin;
+    /** The renderer's composer keys, for hints. */
+    keys: ComposerKeys;
+    /** Whether a run is active. */
+    busy: boolean;
+    /** Host-owned interaction store shared with client activity observers. */
+    interactionStore?: ParakeetInteractions | undefined;
+    /** Use the host palette for /help instead of a separate slash-command list. */
+    showCommands?: (() => void | Promise<void>) | undefined;
+}>;
+/** Everything a renderer needs to draw and drive slash commands. */
+export type SlashCommandController = Readonly<{
+    /** What to show for the current draft. */
+    completion: SlashCompletion;
+    /** Whether the completion popover is visible. */
+    open: boolean;
+    /** Index of the highlighted completion row. */
+    selected: number;
+    /** Key hints for the current state, most useful first when fitted. */
+    hints: readonly KeyHint[];
+    /** The command conversation state. */
+    interactions: ParakeetInteractionState;
+    /** The conversation store, for closing and retrying dialogs. */
+    store: ParakeetInteractions;
+    /** Move the highlight; false when no list is open. */
+    move: (delta: -1 | 1) => boolean;
+    /** Highlight one row (pointer hover). */
+    highlight: (index: number) => void;
+    /** Complete the highlighted row into the draft; false when nothing to complete. */
+    complete: () => boolean;
+    /** Dismiss the open interaction, then the completion, then the notice. */
+    dismiss: () => boolean;
+    /** Run the highlighted row, a command draft, or send a prompt. */
+    submit: (delivery?: PromptDelivery) => void;
+    /** Run one completion row (pointer choice). */
+    choose: (index: number) => void;
+}>;
+/**
+ * The one slash-command controller behind every Parakeet composer. It owns
+ * the registry, completion, hints, execution and conversations; renderers
+ * only draw its state and forward keys.
+ */
+export declare function useSlashCommands(options: SlashCommandOptions): SlashCommandController;

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

@@ -0,0 +1,207 @@
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
+import { useComposer, useClientContributions, useExtensionSlots, useParakeetSession, useParakeetInteractions, } from "../conversation.js";
+import { advertisedCommands } from "./advertised.js";
+import { parakeetBuiltinCommands } from "./builtins.js";
+import { composerHints } from "./hints.js";
+import {} from "./interactions.js";
+import { runSlashDraft } from "./run.js";
+import { completeSlash, keyBindings, slashRegistry, } from "./slash.js";
+function failureMessage(outcome) {
+    if (outcome === undefined || outcome.status === "handled")
+        return undefined;
+    if (outcome.status === "failed")
+        return outcome.error.message;
+    if (outcome.status === "unavailable")
+        return outcome.reason;
+    return `Command ${outcome.status}`;
+}
+/**
+ * The one slash-command controller behind every Parakeet composer. It owns
+ * the registry, completion, hints, execution and conversations; renderers
+ * only draw its state and forward keys.
+ */
+export function useSlashCommands(options) {
+    const { commands, origin } = options;
+    const enabled = options.enabled ?? true;
+    const session = useParakeetSession();
+    const composer = useComposer();
+    const slots = useExtensionSlots();
+    const contributions = useClientContributions();
+    const contributionsRef = useRef(contributions);
+    contributionsRef.current = contributions;
+    const scopedInteractions = useParakeetInteractions();
+    const store = useMemo(() => options.interactionStore ?? scopedInteractions, [options.interactionStore, scopedInteractions]);
+    const interactions = useSyncExternalStore(store.subscribe, store.snapshot, store.snapshot);
+    useEffect(() => {
+        const inspection = interactions.inspection;
+        if (inspection !== undefined &&
+            !contributions.some((entry) => entry.entryId === inspection.entryId &&
+                entry.value.panel.some((row) => row.id === inspection.rowId && row.inspection !== undefined)))
+            store.inspect(undefined);
+    }, [contributions, interactions.inspection, store]);
+    const snapshot = useSyncExternalStore(commands.subscribe, commands.snapshot, commands.snapshot);
+    const composerRef = useRef(composer);
+    composerRef.current = composer;
+    const showCommandsRef = useRef(options.showCommands);
+    showCommandsRef.current = options.showCommands;
+    const hasCommandPalette = options.showCommands !== undefined;
+    useEffect(() => {
+        if (!enabled)
+            return undefined;
+        return store.attach(commands.present);
+    }, [commands, enabled, store]);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const lease = commands.contribute({
+            sourceId: "parakeet",
+            namespace: "parakeet",
+            commands: parakeetBuiltinCommands(commands, {
+                showCommands: hasCommandPalette
+                    ? () => showCommandsRef.current?.()
+                    : undefined,
+                clear: () => {
+                    composerRef.current.setDraft("");
+                    store.report(undefined);
+                },
+            }),
+        });
+        return () => {
+            lease.dispose();
+        };
+    }, [commands, enabled, store, hasCommandPalette]);
+    const advertised = useMemo(() => advertisedCommands(commands, session, (entryId, commandId) => {
+        const row = contributionsRef.current
+            .find((entry) => entry.entryId === entryId)
+            ?.value.panel.find((row) => row.inspection?.commandId === commandId);
+        if (row !== undefined)
+            store.inspect({ entryId, rowId: row.id });
+    }), [commands, session, store]);
+    useEffect(() => () => {
+        advertised.dispose();
+    }, [advertised]);
+    useEffect(() => {
+        if (!enabled) {
+            advertised.dispose();
+            return;
+        }
+        const [error] = advertised.update(slots);
+        if (error !== undefined)
+            store.report({
+                tone: "error",
+                message: `${error.extensionId} commands are unavailable: ${error.message}`,
+            });
+    }, [advertised, enabled, slots, store]);
+    const registry = useMemo(() => slashRegistry(snapshot), [snapshot]);
+    const [dismissed, setDismissed] = useState();
+    const [highlighted, setHighlighted] = useState({ draft: "", index: 0 });
+    const draft = composer.draft;
+    const completion = !enabled || dismissed === draft || interactions.open !== undefined
+        ? { kind: "none" }
+        : completeSlash(registry, draft);
+    const rowCount = completion.kind === "none" ? 0 : completion.items.length;
+    const open = completion.kind === "arguments" ||
+        (completion.kind === "commands" && rowCount > 0);
+    const selected = highlighted.draft === draft
+        ? Math.min(highlighted.index, Math.max(0, rowCount - 1))
+        : 0;
+    const hints = composerHints({
+        completion,
+        busy: options.busy,
+        bindings: keyBindings(snapshot),
+        keys: options.keys,
+    });
+    const run = useCallback((delivery, replacement) => {
+        const current = composerRef.current;
+        if (!enabled) {
+            current.send(delivery);
+            return;
+        }
+        if (replacement !== undefined)
+            current.setDraft(replacement);
+        const submitted = replacement ?? current.draft;
+        store.report(undefined);
+        setDismissed(submitted);
+        void current
+            .submitCommand((captured) => runSlashDraft(captured, commands, () => {
+            current.send(delivery);
+        }, origin))
+            .then((outcome) => {
+            const message = failureMessage(outcome);
+            if (message !== undefined &&
+                store.snapshot().open === undefined &&
+                store.lastEnd() !== "cancelled")
+                store.report({
+                    tone: "error",
+                    message: `${submitted}: ${message}`,
+                });
+        });
+    }, [commands, enabled, origin, store]);
+    const insertAt = (index) => {
+        if (completion.kind === "commands")
+            return completion.items[index]?.insert;
+        if (completion.kind === "arguments")
+            return completion.items[index]?.insert;
+        return undefined;
+    };
+    const choose = (index) => {
+        const insert = insertAt(index);
+        if (insert === undefined)
+            return;
+        run(options.busy ? "followUp" : "steer", insert.trimEnd());
+    };
+    return {
+        completion,
+        open,
+        selected,
+        hints,
+        interactions,
+        store,
+        move: (delta) => {
+            if (rowCount === 0)
+                return false;
+            setHighlighted({
+                draft,
+                index: (selected + delta + rowCount) % rowCount,
+            });
+            return true;
+        },
+        highlight: (index) => {
+            setHighlighted({ draft, index });
+        },
+        complete: () => {
+            const insert = insertAt(selected);
+            if (insert === undefined)
+                return false;
+            composer.setDraft(insert);
+            return true;
+        },
+        dismiss: () => {
+            if (interactions.open !== undefined) {
+                store.close();
+                return true;
+            }
+            if (interactions.inspection !== undefined) {
+                store.inspect(undefined);
+                return true;
+            }
+            if (open) {
+                setDismissed(draft);
+                return true;
+            }
+            if (interactions.notice !== undefined) {
+                store.report(undefined);
+                return true;
+            }
+            return false;
+        },
+        submit: (delivery = options.busy ? "followUp" : "steer") => {
+            // A bare `/alias ` runs the alias; a typed word prefix runs its word.
+            const accepts = completion.kind === "commands" ||
+                (completion.kind === "arguments" && completion.query.length > 0);
+            const insert = accepts && rowCount > 0 ? insertAt(selected) : undefined;
+            run(delivery, insert?.trimEnd());
+        },
+        choose,
+    };
+}

package/dist/components/AgentHead.d.ts

@@ -0,0 +1,27 @@
+import type { Avatar } from "@fungi.computer/sprite/avatar";
+/** What the head is doing: at rest, working something out, or talking. */
+export type AgentHeadActivity = "idle" | "thinking" | "speaking";
+/**
+ * An Agent's head at avatar size. Renders the Agent's own avatar when given
+ * one; otherwise the pre-avatar seeded mushroom cap, byte-identical to
+ * before avatars existed. The letter shows until a frame is ready. It holds
+ * still unless `thinking` or `speaking`: an idle head whose render style is
+ * "plain" and already has a cached still frame for its look never mounts a
+ * live canvas, so a long rail is not a wall of animation. A render style
+ * other than "plain" is a CSS filter over the live canvas, not part of the
+ * captured pixels, so a styled head always stays live.
+ */
+export declare const AgentHead: import("react").NamedExoticComponent<{
+    /** Motion presented by the head; defaults to idle. */
+    activity?: AgentHeadActivity;
+    /** The Agent's stored avatar; omitted or `null` falls back to the seed. */
+    avatar?: Avatar | null;
+    /** Host classes applied to the head container. */
+    className?: string;
+    /** The name whose first letter stands in until a frame is ready. */
+    name: string;
+    /** Stable identity that picks the fallback cap colour. */
+    seed: string;
+    /** Width and height in pixels. */
+    size?: number;
+}>;

package/dist/components/AgentHead.js

@@ -0,0 +1,53 @@
+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 { memo, useEffect, useMemo, useRef, useState } from "react";
+import { avatarPresentation } from "./avatar-presentation.js";
+import { shiitakeSprite } from "./sprite-service.js";
+import { captureStillFrame, getStillFrame, setStillFrame, stillFrameKey, } from "./still-frame-cache.js";
+/**
+ * An Agent's head at avatar size. Renders the Agent's own avatar when given
+ * one; otherwise the pre-avatar seeded mushroom cap, byte-identical to
+ * before avatars existed. The letter shows until a frame is ready. It holds
+ * still unless `thinking` or `speaking`: an idle head whose render style is
+ * "plain" and already has a cached still frame for its look never mounts a
+ * live canvas, so a long rail is not a wall of animation. A render style
+ * other than "plain" is a CSS filter over the live canvas, not part of the
+ * captured pixels, so a styled head always stays live.
+ */
+export const AgentHead = memo(function AgentHead({ activity = "idle", avatar, className, name, seed, size = 24, }) {
+    const [ready, setReady] = useState(false);
+    const host = useRef(null);
+    const presentation = useMemo(() => avatarPresentation(avatar, seed), [avatar, seed]);
+    const dpr = window.devicePixelRatio;
+    const cacheKey = useMemo(() => stillFrameKey(presentation, size, dpr), [presentation, size, dpr]);
+    const [frame, setFrame] = useState(() => getStillFrame(cacheKey));
+    useEffect(() => {
+        setFrame(getStillFrame(cacheKey));
+    }, [cacheKey]);
+    // A render style is a CSS filter on the live stage (render-style.ts), not
+    // part of the captured canvas pixels, so a styled head must stay live;
+    // only a "plain" idle head can be replaced by its cached still frame.
+    const live = activity !== "idle" ||
+        frame === undefined ||
+        presentation.renderStyle !== "plain";
+    useEffect(() => {
+        // A cached idle head has no player; its next player must become ready anew.
+        if (!live)
+            setReady(false);
+    }, [live]);
+    return (_jsxs("span", { "aria-hidden": "true", className: `relative inline-block shrink-0 ${className ?? ""}`, "data-agent-head": frame !== undefined || ready ? "ready" : "loading", style: { height: size, width: size }, children: [frame === undefined && !ready ? (_jsx(Monogram, { className: "absolute inset-0", name: name, seed: seed })) : null, frame !== undefined &&
+                presentation.renderStyle === "plain" &&
+                (!live || !ready) ? (_jsx("img", { alt: "", className: "absolute inset-0 h-full w-full", src: frame })) : null, live ? (_jsx(Sprite, { activity: activity, appearance: presentation.appearance, className: "absolute inset-0", expression: presentation.expression, onState: (state) => {
+                    setReady(state.status === "ready");
+                    if (state.status === "ready" &&
+                        activity === "idle" &&
+                        presentation.renderStyle === "plain") {
+                        const captured = captureStillFrame(host.current);
+                        if (captured !== undefined) {
+                            setStillFrame(cacheKey, captured);
+                            setFrame(captured);
+                        }
+                    }
+                }, paused: activity === "idle", ref: host, renderStyle: presentation.renderStyle, service: shiitakeSprite, src: presentation.src })) : null] }));
+});

package/dist/components/ChatComposer.d.ts

@@ -0,0 +1,43 @@
+import { type RefObject } from "react";
+import type { PromptDelivery, SessionContext } from "@fungi.computer/shiitake/client";
+import type { SlashCommandController } from "../commands/use-slash-commands.js";
+import type { ComposerController, ParakeetStatus, ParakeetSessionViewState } from "../conversation.js";
+export type ChatComposerModel = Readonly<{
+    model: string;
+    provider: string;
+}>;
+export type ChatComposerUsage = Readonly<{
+    cost: number;
+    tokens: number;
+}>;
+export type ChatComposerProps = {
+    /** Caller-owned prompt hint; omitted for the ordinary Session composer. */
+    placeholder?: string | undefined;
+    /** Hide internal model, usage and status readouts for visitors. */
+    showFooter?: boolean;
+    /** Display-only status text supplied by the conversation's admitted entries. */
+    statusChips?: readonly string[] | undefined;
+    actionVariant?: "primary" | "outline" | undefined;
+    draft: string;
+    failure: ComposerController["failure"];
+    failureCause?: string | undefined;
+    model?: ChatComposerModel | undefined;
+    onAbort: () => void;
+    onChange: (value: string) => void;
+    onRetry: () => void;
+    /** Submit the draft; `followUp` while a run is active, otherwise `steer`. */
+    onSend: (delivery: PromptDelivery) => void;
+    admissionError?: ComposerController["admissionError"];
+    status: ParakeetStatus;
+    /** Session owner readout, separate from local prompt admission. */
+    viewState: ParakeetSessionViewState;
+    textareaRef: RefObject<HTMLTextAreaElement>;
+    usage?: ChatComposerUsage | undefined;
+    /** Context use the Session's compaction measures, once known. */
+    context?: SessionContext | undefined;
+    /** 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. */
+export declare function sessionReadout(status: ParakeetStatus, view: ParakeetSessionViewState): string;
+export declare const ChatComposer: import("react").NamedExoticComponent<ChatComposerProps>;