@fungi.computer/parakeet 0.0.0-stage → 0.0.1

package/dist/commands/advertised.js

@@ -0,0 +1,72 @@
+import * as Schema from "effect/Schema";
+import { catalogCommands, parseCatalog } 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)));
+/**
+ * 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.
+ */
+export function advertisedCommands(runtime, session, onInspect) {
+    const live = new Map();
+    const withdraw = (id) => {
+        live.get(id)?.lease.dispose();
+        live.delete(id);
+    };
+    return {
+        update: (slots) => {
+            const errors = [];
+            for (const id of live.keys()) {
+                const slot = Object.hasOwn(slots, id) ? slots[id] : undefined;
+                if (slot?.status !== "running" || slot.catalog === undefined)
+                    withdraw(id);
+            }
+            for (const [id, slot] of Object.entries(slots)) {
+                if (slot.status !== "running" || slot.catalog === undefined)
+                    continue;
+                const encoded = JSON.stringify(slot.catalog);
+                if (live.get(id)?.catalog === encoded)
+                    continue;
+                withdraw(id);
+                try {
+                    const address = session.extension(id);
+                    const commands = catalogCommands(parseCatalog(slot.catalog), (command, args) => address.call(command, args));
+                    live.set(id, {
+                        catalog: encoded,
+                        lease: runtime.contribute({
+                            sourceId: `extension:${id}`,
+                            namespace: id,
+                            commands: commands.map((command) => ({
+                                ...command,
+                                handler: async (input) => {
+                                    const result = await command.handler(input);
+                                    if (input.origin !== "agent" &&
+                                        bare(input.arguments) &&
+                                        !cancelled(result) &&
+                                        !input.signal?.aborted &&
+                                        live.get(id)?.catalog === encoded)
+                                        onInspect?.(id, command.id);
+                                    return result;
+                                },
+                            })),
+                        }),
+                    });
+                }
+                catch (cause) {
+                    errors.push({
+                        extensionId: id,
+                        message: cause instanceof Error
+                            ? cause.message
+                            : "The advertised catalog is invalid",
+                    });
+                }
+            }
+            return errors;
+        },
+        dispose: () => {
+            for (const id of live.keys())
+                withdraw(id);
+        },
+    };
+}

package/dist/commands/builtins.d.ts

@@ -0,0 +1,14 @@
+import type { WhistleContribution, WhistleRuntime } from "@fungi.computer/whistle";
+/** The few commands every Parakeet client has, whatever the backend offers. */
+export type ParakeetBuiltinOptions = Readonly<{
+    /** Clear the composer draft and any notice. */
+    clear: () => void;
+    /** Open the renderer-owned all-command palette, when one exists. */
+    showCommands?: (() => void | Promise<void>) | undefined;
+}>;
+/**
+ * `/help` lists the live commands (built-in and advertised) and runs the one
+ * chosen; `/keys` does the same for key bindings; `/clear` empties the
+ * composer.
+ */
+export declare function parakeetBuiltinCommands(runtime: Pick<WhistleRuntime, "snapshot" | "execute">, options: ParakeetBuiltinOptions): WhistleContribution["commands"];

package/dist/commands/builtins.js

@@ -0,0 +1,91 @@
+import { keyBindings, slashRegistry } from "./slash.js";
+/** Run a chosen command after the choosing command has settled. */
+function runAfter(runtime, commandId, origin) {
+    setTimeout(() => {
+        void runtime.execute(commandId, { origin });
+    }, 0);
+}
+/**
+ * `/help` lists the live commands (built-in and advertised) and runs the one
+ * chosen; `/keys` does the same for key bindings; `/clear` empties the
+ * composer.
+ */
+export function parakeetBuiltinCommands(runtime, options) {
+    return [
+        {
+            id: "help",
+            title: "Show commands",
+            category: "Advanced",
+            projections: {
+                help: { order: -3 },
+                slash: { aliases: ["help"], order: -3 },
+            },
+            handler: async (input) => {
+                if (options.showCommands !== undefined) {
+                    await options.showCommands();
+                    return undefined;
+                }
+                const commands = slashRegistry(runtime.snapshot()).filter((command) => command.alias !== "help");
+                if (input.interaction === undefined)
+                    return commands.map((command) => `/${command.alias}`);
+                const chosen = await input.interaction.prompt({
+                    type: "choice",
+                    message: "Commands",
+                    options: commands.map((command) => ({
+                        value: command.commandId,
+                        label: `/${command.alias}`,
+                        description: command.keys.length === 0
+                            ? command.title
+                            : `${command.title} · ${command.keys.join(", ")}`,
+                    })),
+                });
+                runAfter(runtime, chosen, input.origin);
+                return undefined;
+            },
+        },
+        {
+            id: "keys",
+            title: "Show key bindings",
+            category: "Advanced",
+            projections: {
+                help: { order: -2 },
+                slash: { aliases: ["keys"], order: -2 },
+            },
+            handler: async (input) => {
+                const keys = keyBindings(runtime.snapshot());
+                if (input.interaction === undefined)
+                    return keys.map((row) => `${row.keys} ${row.title}`);
+                if (keys.length === 0) {
+                    input.interaction.notify({
+                        type: "info",
+                        message: "No key bindings are active.",
+                    });
+                    return undefined;
+                }
+                const chosen = await input.interaction.prompt({
+                    type: "choice",
+                    message: "Key bindings",
+                    options: keys.map((row) => ({
+                        value: row.commandId,
+                        label: row.title,
+                        description: row.keys,
+                    })),
+                });
+                runAfter(runtime, chosen, input.origin);
+                return undefined;
+            },
+        },
+        {
+            id: "clear",
+            title: "Clear the composer",
+            category: "Advanced",
+            projections: {
+                help: { order: -1 },
+                slash: { aliases: ["clear"], order: -1 },
+            },
+            handler: () => {
+                options.clear();
+            },
+        },
+    ];
+}

package/dist/commands/hints.d.ts

@@ -0,0 +1,36 @@
+import type { KeyBindingRow, SlashCompletion } from "./slash.js";
+/** One key hint: the keys, what they do, and how much it matters (0 first). */
+export type KeyHint = Readonly<{
+    /** Key label, e.g. `Enter`. */
+    keys: string;
+    /** What the key does. */
+    label: string;
+    /** Lower numbers survive narrow widths. */
+    priority: number;
+}>;
+/** The composer's physical keys, which differ slightly between renderers. */
+export type ComposerKeys = Readonly<{
+    /** Key that inserts a newline, e.g. `Shift+Enter`. */
+    newline?: string | undefined;
+    /** Optional transcript scroll keys, e.g. `PgUp/PgDn`. */
+    scroll?: string | undefined;
+    /** Optional key that queues a follow-up during a run, e.g. `Tab`. */
+    queue?: string | undefined;
+}>;
+/** What the composer is doing right now. */
+export type ComposerHintContext = Readonly<{
+    /** The current slash completion. */
+    completion: SlashCompletion;
+    /** Whether a run is active (Tab queues, Esc cancels). */
+    busy: boolean;
+    /** Live Whistle key bindings. */
+    bindings: readonly KeyBindingRow[];
+    /** The renderer's composer keys. */
+    keys: ComposerKeys;
+}>;
+/** Hints for the current composer state, in display order. */
+export declare function composerHints(context: ComposerHintContext): readonly KeyHint[];
+/** One line of hints. */
+export declare function formatHints(hints: readonly KeyHint[]): string;
+/** Keep the most important hints that fit `width` characters, in order. */
+export declare function fitHints(hints: readonly KeyHint[], width: number): readonly KeyHint[];

package/dist/commands/hints.js

@@ -0,0 +1,64 @@
+const cancelBindings = new Set(["Esc", "Ctrl+C"]);
+/** Hints for the current composer state, in display order. */
+export function composerHints(context) {
+    const { completion } = context;
+    if (completion.kind === "commands" && completion.items.length > 0)
+        return [
+            { keys: "↑↓", label: "choose", priority: 1 },
+            { keys: "Tab", label: "complete", priority: 0 },
+            { keys: "Enter", label: "run", priority: 0 },
+            { keys: "Esc", label: "dismiss", priority: 2 },
+        ];
+    if (completion.kind === "arguments")
+        return completion.items.length > 0
+            ? [
+                { keys: "↑↓", label: "choose", priority: 1 },
+                { keys: "Tab", label: "complete", priority: 0 },
+                { keys: "Enter", label: "run", priority: 0 },
+                { keys: "Esc", label: "dismiss", priority: 2 },
+            ]
+            : [
+                { keys: "Enter", label: "run", priority: 0 },
+                { keys: "Esc", label: "dismiss", priority: 2 },
+            ];
+    const hints = [{ keys: "Enter", label: "send", priority: 0 }];
+    if (context.busy && context.keys.queue !== undefined)
+        hints.push({ keys: context.keys.queue, label: "queue", priority: 0 });
+    if (context.keys.newline !== undefined)
+        hints.push({ keys: context.keys.newline, label: "newline", priority: 1 });
+    if (context.keys.scroll !== undefined)
+        hints.push({ keys: context.keys.scroll, label: "scroll", priority: 2 });
+    for (const binding of context.bindings) {
+        const cancel = binding.keys
+            .split(", ")
+            .some((key) => cancelBindings.has(key));
+        if (cancel && !context.busy)
+            continue;
+        hints.push({
+            keys: binding.keys,
+            label: binding.title.toLocaleLowerCase(),
+            priority: cancel ? 0 : 3,
+        });
+    }
+    hints.push({ keys: "/", label: "commands", priority: 4 });
+    return hints;
+}
+const separator = " · ";
+/** One line of hints. */
+export function formatHints(hints) {
+    return hints.map((hint) => `${hint.keys} ${hint.label}`).join(separator);
+}
+/** Keep the most important hints that fit `width` characters, in order. */
+export function fitHints(hints, width) {
+    const kept = new Set();
+    let used = 0;
+    const byPriority = [...hints].sort((left, right) => left.priority - right.priority);
+    for (const hint of byPriority) {
+        const length = hint.keys.length + 1 + hint.label.length + (kept.size === 0 ? 0 : 3);
+        if (used + length > width)
+            continue;
+        kept.add(hint);
+        used += length;
+    }
+    return hints.filter((hint) => kept.has(hint));
+}

package/dist/commands/interactions.d.ts

@@ -0,0 +1,55 @@
+import type { WhistleInteractionEnd, WhistleRuntime } from "@fungi.computer/whistle";
+import { type WhistleInteractionHost } from "@fungi.computer/whistle/interaction";
+/** One interaction a renderer should draw as a dialog or panel. */
+export type ParakeetOpenInteraction = Readonly<{
+    /** Changes whenever a different interaction opens. */
+    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. */
+export type ParakeetNotice = Readonly<{
+    /** How to color it. */
+    tone: "info" | "success" | "error";
+    /** What happened. */
+    message: string;
+}>;
+/** Everything a renderer draws for command conversations. */
+export type ParakeetInteractionState = Readonly<{
+    /** The interaction that needs the human, when one does. */
+    open?: ParakeetOpenInteraction | undefined;
+    /** A manually opened, live panel row from an admitted client entry. */
+    inspection?: Readonly<{
+        /** Composition-root identity of the admitted client entry. */
+        entryId: string;
+        /** Stable identity of the panel row being inspected. */
+        rowId: string;
+    }> | undefined;
+    /** The latest one-line result. */
+    notice?: ParakeetNotice | undefined;
+}>;
+/** Parakeet's command conversation store, shared by every renderer. */
+export type ParakeetInteractions = Readonly<{
+    /** Current state. */
+    snapshot: () => ParakeetInteractionState;
+    /** Observe changes. */
+    subscribe: (listener: () => void) => () => void;
+    /** Dismiss the open interaction, cancelling it if it is still running. */
+    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. */
+    report: (notice: ParakeetNotice | undefined) => 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. */
+    lastEnd: () => WhistleInteractionEnd["status"] | undefined;
+}>;
+/**
+ * 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.
+ */
+export declare function createParakeetInteractions(): ParakeetInteractions;

package/dist/commands/interactions.js

@@ -0,0 +1,101 @@
+import { createWhistleInteractionHost, } from "@fungi.computer/whistle/interaction";
+/**
+ * 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.
+ */
+export function createParakeetInteractions() {
+    let state = {};
+    let sequence = 0;
+    let lastEnd;
+    const listeners = new Set();
+    const publish = (next) => {
+        state = next;
+        for (const listener of listeners)
+            listener();
+    };
+    const closeKey = (key) => {
+        if (state.open?.key === key)
+            publish({ ...state, open: undefined });
+    };
+    const presenter = ({ title, retry }) => {
+        const key = ++sequence;
+        let shown = false;
+        const host = createWhistleInteractionHost({
+            title,
+            onEnd: (end) => {
+                lastEnd = end.status;
+                const message = host.snapshot().message;
+                if (!shown) {
+                    if (end.status === "failed")
+                        publish({
+                            ...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,
+                            },
+                        });
+                    return;
+                }
+                const lingers = end.status === "failed" ||
+                    (end.status === "handled" &&
+                        message !== undefined &&
+                        message.type !== "progress");
+                if (!lingers)
+                    closeKey(key);
+            },
+        });
+        const unsubscribe = host.subscribe(() => {
+            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 });
+            previous?.host.cancel();
+        });
+        const session = host.begin();
+        return {
+            interaction: session.interaction,
+            settle: (end) => {
+                unsubscribe();
+                session.settle(end);
+            },
+        };
+    };
+    return {
+        snapshot: () => state,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        close: () => {
+            const open = state.open;
+            if (open === undefined)
+                return;
+            publish({ ...state, open: undefined });
+            open.host.cancel();
+        },
+        inspect: (inspection) => {
+            publish({ ...state, inspection });
+        },
+        report: (notice) => {
+            // A new report starts a new turn: forget how the last interaction ended.
+            lastEnd = undefined;
+            publish({ ...state, notice });
+        },
+        attach: (present) => present(presenter),
+        lastEnd: () => lastEnd,
+    };
+}

package/dist/commands/run.d.ts

@@ -0,0 +1,11 @@
+import type { WhistleExecutionOrigin, WhistleExecutionOutcome, WhistleRuntime } from "@fungi.computer/whistle";
+/** The Whistle surface a composer needs to run drafts. */
+export type SlashRuntime = Pick<WhistleRuntime, "snapshot" | "execute">;
+/** Whether a handled command declined its input (for example a refused replacement). */
+export declare function isCancelledOutcome(outcome: WhistleExecutionOutcome): boolean;
+/**
+ * Run one composer draft: a prompt goes to `send`, a `/command` runs through
+ * Whistle. A grammar that asks for a request id keeps the same id across
+ * retries of the same draft until the command is handled.
+ */
+export declare function runSlashDraft(draft: string, commands: SlashRuntime, send: () => void, origin: WhistleExecutionOrigin): Promise<WhistleExecutionOutcome | undefined>;

package/dist/commands/run.js

@@ -0,0 +1,61 @@
+import { nanoid } from "@fungi.computer/cairn";
+import { z } from "zod";
+import { parseSlashDraft, slashRegistry } from "./slash.js";
+const pendingByRuntime = new WeakMap();
+/** Whether a handled command declined its input (for example a refused replacement). */
+export function isCancelledOutcome(outcome) {
+    if (outcome.status !== "handled")
+        return false;
+    return z.looseObject({ cancelled: z.literal(true) }).safeParse(outcome.result)
+        .success;
+}
+/**
+ * Run one composer draft: a prompt goes to `send`, a `/command` runs through
+ * Whistle. A grammar that asks for a request id keeps the same id across
+ * retries of the same draft until the command is handled.
+ */
+export async function runSlashDraft(draft, commands, send, origin) {
+    const parsed = parseSlashDraft(slashRegistry(commands.snapshot()), draft);
+    if (parsed.kind === "prompt") {
+        send();
+        return undefined;
+    }
+    if (parsed.kind === "invalid")
+        return {
+            status: "failed",
+            error: { code: "invalid_arguments", message: parsed.message },
+        };
+    const { command, requestIdField } = parsed;
+    if (parsed.arguments === undefined)
+        return commands.execute(command.commandId, { origin });
+    if (requestIdField === undefined)
+        return commands.execute(command.commandId, {
+            origin,
+            arguments: parsed.arguments,
+        });
+    const states = pendingByRuntime.get(commands) ?? new Map();
+    pendingByRuntime.set(commands, states);
+    const previous = states.get(command.commandId);
+    if (previous?.draft === draft && previous.running !== undefined)
+        return previous.running;
+    const state = {
+        draft,
+        requestId: previous?.draft === draft ? previous.requestId : nanoid(),
+    };
+    states.set(command.commandId, state);
+    const running = commands
+        .execute(command.commandId, {
+        origin,
+        arguments: { ...parsed.arguments, [requestIdField]: state.requestId },
+    })
+        .then((outcome) => {
+        if (states.get(command.commandId) !== state)
+            return outcome;
+        state.running = undefined;
+        if (outcome.status === "handled" && !isCancelledOutcome(outcome))
+            states.delete(command.commandId);
+        return outcome;
+    });
+    state.running = running;
+    return running;
+}

package/dist/commands/slash.d.ts

@@ -0,0 +1,124 @@
+import type { WhistleAvailability, 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. */
+    commandId: string;
+    /** Human-facing title. */
+    title: string;
+    /** Optional longer explanation. */
+    description?: string | undefined;
+    /** Human-facing category. */
+    category: string;
+    /** Surface order supplied by the command owner. */
+    order: number;
+    /** The argument grammar, when the command takes text after its alias. */
+    grammar?: WhistleSlashArguments | undefined;
+    /** Key labels bound to the same command, e.g. `Ctrl+O`. */
+    keys: readonly string[];
+    /** Unavailable commands stay listed with their reason. */
+    availability: WhistleAvailability;
+}>;
+/** One key binding as help and hint surfaces list it. */
+export type KeyBindingRow = Readonly<{
+    /** Canonical Whistle command identity. */
+    commandId: string;
+    /** Human key label, e.g. `Ctrl+O`. */
+    keys: string;
+    /** What the key does. */
+    title: string;
+    /** Surface order supplied by the command owner. */
+    order: number;
+}>;
+/** Human key labels from Whistle bindings, with the platform's modifier name. */
+export declare function keyLabel(binding: string, mac?: boolean): string;
+/** Every slash alias in the live graph, with the keys bound to its command. */
+export declare function slashRegistry(snapshot: WhistleSnapshot): readonly SlashCommand[];
+/** Every bound key in the live graph, grouped by command. */
+export declare function keyBindings(snapshot: WhistleSnapshot): readonly KeyBindingRow[];
+/** How one composer draft maps to a command. */
+export type SlashParse = Readonly<{
+    /** Not a command: send it as a prompt. */
+    kind: "prompt";
+}> | Readonly<{
+    /** Run this command. */
+    kind: "command";
+    /** The command. */
+    command: SlashCommand;
+    /** Arguments decoded by the command's grammar; absent for a bare alias. */
+    arguments?: WhistleJsonObject | undefined;
+    /** Field that must receive a stable per-draft request id. */
+    requestIdField?: string | undefined;
+}> | Readonly<{
+    /** Refuse the draft without running anything. */
+    kind: "invalid";
+    /** Why, for the human. */
+    message: string;
+}>;
+/** Parse one draft against the registry; only a leading `/` names a command. */
+export declare function parseSlashDraft(registry: readonly SlashCommand[], draft: string): SlashParse;
+/** One command offered while the alias is being typed. */
+export type SlashCommandItem = Readonly<{
+    /** The command. */
+    command: SlashCommand;
+    /** `/alias`. */
+    label: string;
+    /** Indices of `label` characters that matched the query, for emphasis. */
+    matches: readonly number[];
+    /** Draft text after accepting this item. */
+    insert: string;
+}>;
+/** One argument word offered after the alias. */
+export type SlashWordItem = Readonly<{
+    /** The word. */
+    word: WhistleSlashWord;
+    /** The word as displayed. */
+    label: string;
+    /** Indices of `label` characters that matched the query. */
+    matches: readonly number[];
+    /** Draft text after accepting this item. */
+    insert: string;
+}>;
+/** What a composer shows for the current draft. */
+export type SlashCompletion = Readonly<{
+    /** Nothing to complete. */
+    kind: "none";
+}> | Readonly<{
+    /** Choosing a command. */
+    kind: "commands";
+    /** Text typed after `/`. */
+    query: string;
+    /** Ranked matches, best first. */
+    items: readonly SlashCommandItem[];
+}> | Readonly<{
+    /** Typing a command's arguments. */
+    kind: "arguments";
+    /** The command whose arguments are being typed. */
+    command: SlashCommand;
+    /** Text typed after the alias. */
+    query: string;
+    /** Usage hint, e.g. `/goal <objective>`. */
+    hint: string;
+    /** Ranked matching words, best first. */
+    items: readonly SlashWordItem[];
+}>;
+/** How well one candidate matched a query; lower tiers and spreads rank first. */
+export type FuzzyMatch = Readonly<{
+    /** 0 prefix, 1 word start, 2 substring, 3 in-order subsequence. */
+    tier: number;
+    /** Characters skipped within the tier (distance or gaps). */
+    spread: number;
+    /** Candidate indices that matched the query, for emphasis. */
+    indices: number[];
+}>;
+/**
+ * Fuzzy match: a prefix beats a word start beats a substring beats an
+ * in-order subsequence; tighter subsequences rank first.
+ */
+export declare function fuzzyMatch(candidate: string, query: string): FuzzyMatch | undefined;
+/** Rank completions for one draft; renderers draw exactly these rows. */
+export declare function completeSlash(registry: readonly SlashCommand[], draft: string, options?: Readonly<{
+    /** Category offered for a bare `/`; conversations use `Conversation`. */
+    idleCategory?: string;
+}>): SlashCompletion;