@fungi.computer/whistle 0.0.0-stage → 0.0.1

package/dist/catalog.d.ts

@@ -0,0 +1,459 @@
+import * as z from "zod";
+import { type WhistleCommand, type WhistleJsonObject, type WhistleJsonValue } from "./index.js";
+import type { ReadonlySchemaValue } from "./wire.js";
+/** The one catalog protocol this Whistle understands. */
+export declare const whistleCatalogProtocol = "whistle.catalog/v1";
+/**
+ * A backend's advertised command catalog: data-only command definitions a
+ * client turns into Whistle commands. Every command runs through the backend's
+ * own call door; the client never names a command in code.
+ */
+/** Call one advertised command at its backend; resolves to a raw step. */
+export type WhistleCatalogInvoke = (commandId: string, args: WhistleJsonObject, signal: AbortSignal) => Promise<WhistleJsonValue>;
+/** Validate one complete Whistle catalog and its unique command ids. */
+export declare const WhistleCatalogSchema: z.ZodPipe<z.ZodObject<{
+    protocol: z.ZodLiteral<"whistle.catalog/v1">;
+    commands: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        category: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        projections: z.ZodOptional<z.ZodObject<{
+            bindings: z.ZodOptional<z.ZodObject<{
+                order: z.ZodOptional<z.ZodNumber>;
+                values: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>>;
+            agent: z.ZodOptional<z.ZodObject<{
+                keybind: z.ZodOptional<z.ZodString>;
+                order: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>>;
+            help: z.ZodOptional<z.ZodObject<{
+                order: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>>;
+            menu: z.ZodOptional<z.ZodObject<{
+                order: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>>;
+            palette: z.ZodOptional<z.ZodObject<{
+                order: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>>;
+            slash: z.ZodOptional<z.ZodObject<{
+                aliases: z.ZodArray<z.ZodString>;
+                order: z.ZodOptional<z.ZodNumber>;
+                arguments: z.ZodOptional<z.ZodObject<{
+                    hint: z.ZodPipe<z.ZodString, z.ZodString>;
+                    words: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        word: z.ZodString;
+                        description: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodString>>;
+                        arguments: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+                    }, z.core.$strict>>>;
+                    text: z.ZodOptional<z.ZodObject<{
+                        field: z.ZodPipe<z.ZodString, z.ZodString>;
+                        arguments: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+                        requestIdField: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodString>>;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        action: z.ZodOptional<z.ZodObject<{
+            inputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+            outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+            presentation: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+                type: z.ZodLiteral<"action">;
+            }, z.core.$strict>, z.ZodObject<{
+                type: z.ZodLiteral<"custom">;
+                data: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+            }, z.core.$strict>, z.ZodObject<{
+                type: z.ZodLiteral<"choice">;
+                options: z.ZodArray<z.ZodObject<{
+                    value: z.ZodJSONSchema;
+                    label: z.ZodString;
+                    description: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strict>, z.ZodObject<{
+                type: z.ZodLiteral<"form">;
+                submitLabel: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                type: z.ZodLiteral<"confirmation">;
+                message: z.ZodString;
+                confirmLabel: z.ZodOptional<z.ZodString>;
+                cancelLabel: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>;
+        }, z.core.$strict>>;
+        availability: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            status: z.ZodLiteral<"available">;
+        }, z.core.$strict>, z.ZodObject<{
+            status: z.ZodLiteral<"unavailable">;
+            reason: z.ZodString;
+        }, z.core.$strict>], "status">>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodTransform<Readonly<{
+    protocol: "whistle.catalog/v1";
+    commands: readonly {
+        id: string;
+        title: string;
+        category: string;
+        description?: string | undefined;
+        projections?: {
+            bindings?: {
+                values: string[];
+                order?: number | undefined;
+            } | undefined;
+            agent?: {
+                keybind?: string | undefined;
+                order?: number | undefined;
+            } | undefined;
+            help?: {
+                order?: number | undefined;
+            } | undefined;
+            menu?: {
+                order?: number | undefined;
+            } | undefined;
+            palette?: {
+                order?: number | undefined;
+            } | undefined;
+            slash?: {
+                aliases: string[];
+                order?: number | undefined;
+                arguments?: {
+                    hint: string;
+                    words?: {
+                        word: string;
+                        arguments: Record<string, z.core.util.JSONType>;
+                        description?: string | undefined;
+                    }[] | undefined;
+                    text?: {
+                        field: string;
+                        arguments: Record<string, z.core.util.JSONType>;
+                        requestIdField?: string | undefined;
+                    } | undefined;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+        action?: {
+            inputSchema?: Record<string, z.core.util.JSONType> | undefined;
+            outputSchema?: Record<string, z.core.util.JSONType> | undefined;
+            presentation?: {
+                type: "action";
+            } | {
+                type: "custom";
+                data: Record<string, z.core.util.JSONType>;
+            } | {
+                type: "choice";
+                options: {
+                    value: z.core.util.JSONType;
+                    label: string;
+                    description?: string | undefined;
+                }[];
+            } | {
+                type: "form";
+                submitLabel?: string | undefined;
+            } | {
+                type: "confirmation";
+                message: string;
+                confirmLabel?: string | undefined;
+                cancelLabel?: string | undefined;
+            } | undefined;
+        } | undefined;
+        availability?: {
+            status: "available";
+        } | {
+            status: "unavailable";
+            reason: string;
+        } | undefined;
+    }[];
+}>, {
+    protocol: "whistle.catalog/v1";
+    commands: {
+        id: string;
+        title: string;
+        category: string;
+        description?: string | undefined;
+        projections?: {
+            bindings?: {
+                values: string[];
+                order?: number | undefined;
+            } | undefined;
+            agent?: {
+                keybind?: string | undefined;
+                order?: number | undefined;
+            } | undefined;
+            help?: {
+                order?: number | undefined;
+            } | undefined;
+            menu?: {
+                order?: number | undefined;
+            } | undefined;
+            palette?: {
+                order?: number | undefined;
+            } | undefined;
+            slash?: {
+                aliases: string[];
+                order?: number | undefined;
+                arguments?: {
+                    hint: string;
+                    words?: {
+                        word: string;
+                        arguments: Record<string, z.core.util.JSONType>;
+                        description?: string | undefined;
+                    }[] | undefined;
+                    text?: {
+                        field: string;
+                        arguments: Record<string, z.core.util.JSONType>;
+                        requestIdField?: string | undefined;
+                    } | undefined;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+        action?: {
+            inputSchema?: Record<string, z.core.util.JSONType> | undefined;
+            outputSchema?: Record<string, z.core.util.JSONType> | undefined;
+            presentation?: {
+                type: "action";
+            } | {
+                type: "custom";
+                data: Record<string, z.core.util.JSONType>;
+            } | {
+                type: "choice";
+                options: {
+                    value: z.core.util.JSONType;
+                    label: string;
+                    description?: string | undefined;
+                }[];
+            } | {
+                type: "form";
+                submitLabel?: string | undefined;
+            } | {
+                type: "confirmation";
+                message: string;
+                confirmLabel?: string | undefined;
+                cancelLabel?: string | undefined;
+            } | undefined;
+        } | undefined;
+        availability?: {
+            status: "available";
+        } | {
+            status: "unavailable";
+            reason: string;
+        } | undefined;
+    }[];
+}>>;
+/** An advertised command catalog decoded by the maintained catalog schema. */
+export type WhistleCatalogV1 = ReadonlySchemaValue<z.output<typeof WhistleCatalogSchema>>;
+/** Parse an advertised catalog at the client boundary. */
+export declare const parseCatalog: typeof WhistleCatalogSchema.parse;
+/** Validate one response step before it reaches an interaction renderer. */
+export declare const WhistleCatalogStepSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"done">;
+    notice: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"info">;
+        message: z.ZodPipe<z.ZodString, z.ZodString>;
+        links: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            url: z.ZodURL;
+            label: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodString>>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"progress">;
+        message: z.ZodPipe<z.ZodString, z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"handoff">;
+        url: z.ZodURL;
+        code: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodString>>;
+        message: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"success">;
+        message: z.ZodPipe<z.ZodString, z.ZodString>;
+    }, z.core.$strict>], "type">>;
+    result: z.ZodOptional<z.ZodJSONSchema>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"prompt">;
+    prompt: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"choice">;
+        message: z.ZodPipe<z.ZodString, z.ZodString>;
+        collapsedGroup: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodString>>;
+        options: z.ZodArray<z.ZodObject<{
+            value: z.ZodPipe<z.ZodString, z.ZodString>;
+            label: z.ZodPipe<z.ZodString, z.ZodString>;
+            description: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodString>>;
+            group: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodString>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        message: z.ZodPipe<z.ZodString, z.ZodString>;
+        placeholder: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodString>>;
+        secret: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"confirmation">;
+        message: z.ZodPipe<z.ZodString, z.ZodString>;
+        confirmLabel: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodString>>;
+        cancelLabel: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>], "type">;
+    notice: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"info">;
+        message: z.ZodPipe<z.ZodString, z.ZodString>;
+        links: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            url: z.ZodURL;
+            label: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodString>>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"progress">;
+        message: z.ZodPipe<z.ZodString, z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"handoff">;
+        url: z.ZodURL;
+        code: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodString>>;
+        message: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"success">;
+        message: z.ZodPipe<z.ZodString, z.ZodString>;
+    }, z.core.$strict>], "type">>;
+    next: z.ZodObject<{
+        arguments: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+        answer: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>], "type">, z.ZodTransform<Readonly<{
+    type: "done";
+    notice?: {
+        type: "info";
+        message: string;
+        links?: {
+            url: string;
+            label?: string | undefined;
+        }[] | undefined;
+    } | {
+        type: "progress";
+        message: string;
+    } | {
+        type: "handoff";
+        url: string;
+        code?: string | undefined;
+        message?: string | undefined;
+    } | {
+        type: "success";
+        message: string;
+    } | undefined;
+    result?: z.core.util.JSONType | undefined;
+}> | Readonly<{
+    type: "prompt";
+    prompt: {
+        type: "choice";
+        message: string;
+        options: {
+            value: string;
+            label: string;
+            description?: string | undefined;
+            group?: string | undefined;
+        }[];
+        collapsedGroup?: string | undefined;
+    } | {
+        type: "text";
+        message: string;
+        placeholder?: string | undefined;
+        secret?: boolean | undefined;
+    } | {
+        type: "confirmation";
+        message: string;
+        confirmLabel?: string | undefined;
+        cancelLabel?: string | undefined;
+    };
+    next: {
+        arguments: Record<string, z.core.util.JSONType>;
+        answer: string;
+    };
+    notice?: {
+        type: "info";
+        message: string;
+        links?: {
+            url: string;
+            label?: string | undefined;
+        }[] | undefined;
+    } | {
+        type: "progress";
+        message: string;
+    } | {
+        type: "handoff";
+        url: string;
+        code?: string | undefined;
+        message?: string | undefined;
+    } | {
+        type: "success";
+        message: string;
+    } | undefined;
+}>, {
+    type: "done";
+    notice?: {
+        type: "info";
+        message: string;
+        links?: {
+            url: string;
+            label?: string | undefined;
+        }[] | undefined;
+    } | {
+        type: "progress";
+        message: string;
+    } | {
+        type: "handoff";
+        url: string;
+        code?: string | undefined;
+        message?: string | undefined;
+    } | {
+        type: "success";
+        message: string;
+    } | undefined;
+    result?: z.core.util.JSONType | undefined;
+} | {
+    type: "prompt";
+    prompt: {
+        type: "choice";
+        message: string;
+        options: {
+            value: string;
+            label: string;
+            description?: string | undefined;
+            group?: string | undefined;
+        }[];
+        collapsedGroup?: string | undefined;
+    } | {
+        type: "text";
+        message: string;
+        placeholder?: string | undefined;
+        secret?: boolean | undefined;
+    } | {
+        type: "confirmation";
+        message: string;
+        confirmLabel?: string | undefined;
+        cancelLabel?: string | undefined;
+    };
+    next: {
+        arguments: Record<string, z.core.util.JSONType>;
+        answer: string;
+    };
+    notice?: {
+        type: "info";
+        message: string;
+        links?: {
+            url: string;
+            label?: string | undefined;
+        }[] | undefined;
+    } | {
+        type: "progress";
+        message: string;
+    } | {
+        type: "handoff";
+        url: string;
+        code?: string | undefined;
+        message?: string | undefined;
+    } | {
+        type: "success";
+        message: string;
+    } | undefined;
+}>>;
+/** A decoded catalog response step derived from its maintained schema. */
+export type WhistleCatalogStepV1 = ReadonlySchemaValue<z.output<typeof WhistleCatalogStepSchema>>;
+/** Parse one backend reply before any of it reaches a renderer. */
+export declare const parseCatalogStep: typeof WhistleCatalogStepSchema.parse;
+/**
+ * Turn an advertised catalog into Whistle commands. Each handler runs the
+ * backend's step conversation through the caller's interaction; an Agent,
+ * which has no interaction, can run only commands that finish in one step.
+ */
+export declare function catalogCommands(catalog: WhistleCatalogV1, invoke: WhistleCatalogInvoke): readonly WhistleCommand<never>[];

package/dist/catalog.js

@@ -0,0 +1,147 @@
+import * as z from "zod";
+import { WhistleActionError, } from "./index.js";
+import { parseJsonObject, WhistleCommandDefinitionSchema, WhistleJsonObjectSchema, WhistleJsonValueSchema, WhistleNoticeSchema, WhistlePromptSchema, } from "./wire.js";
+/** The one catalog protocol this Whistle understands. */
+export const whistleCatalogProtocol = "whistle.catalog/v1";
+const maximumCatalogCommands = 128;
+const maximumSteps = 16;
+/** Validate one complete Whistle catalog and its unique command ids. */
+export const WhistleCatalogSchema = z
+    .object({
+    protocol: z.literal(whistleCatalogProtocol),
+    commands: z
+        .array(WhistleCommandDefinitionSchema)
+        .max(maximumCatalogCommands),
+})
+    .strict()
+    .transform((catalog) => {
+    const ids = new Set();
+    for (const command of catalog.commands) {
+        if (ids.has(command.id))
+            throw new Error(`Catalog command ${command.id} is repeated`);
+        ids.add(command.id);
+    }
+    return Object.freeze({
+        protocol: whistleCatalogProtocol,
+        commands: Object.freeze(catalog.commands),
+    });
+});
+/** Parse an advertised catalog at the client boundary. */
+export const parseCatalog = (value) => WhistleCatalogSchema.parse(value);
+/** Validate one response step before it reaches an interaction renderer. */
+export const WhistleCatalogStepSchema = z
+    .discriminatedUnion("type", [
+    z
+        .object({
+        type: z.literal("done"),
+        notice: WhistleNoticeSchema.optional(),
+        result: WhistleJsonValueSchema.optional(),
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal("prompt"),
+        prompt: WhistlePromptSchema,
+        notice: WhistleNoticeSchema.optional(),
+        next: z
+            .object({
+            arguments: WhistleJsonObjectSchema,
+            answer: z.string().min(1).max(120),
+        })
+            .strict(),
+    })
+        .strict(),
+])
+    .transform((step) => Object.freeze(step));
+/** Parse one backend reply before any of it reaches a renderer. */
+export const parseCatalogStep = (value) => WhistleCatalogStepSchema.parse(value);
+function initialArguments(definition, input) {
+    if (input.arguments !== undefined) {
+        try {
+            return parseJsonObject(input.arguments);
+        }
+        catch {
+            throw new WhistleActionError("invalid_arguments", `${definition.title}: arguments must be an object`);
+        }
+    }
+    const presentation = definition.action?.presentation;
+    const interaction = input.interaction;
+    if (interaction === undefined || presentation === undefined)
+        return {};
+    if (presentation.type === "choice") {
+        const options = presentation.options;
+        return interaction
+            .prompt({
+            type: "choice",
+            message: definition.title,
+            options: options.map((option, index) => {
+                const choice = {
+                    value: String(index),
+                    label: option.label,
+                };
+                return option.description === undefined
+                    ? choice
+                    : { ...choice, description: option.description };
+            }),
+        })
+            .then((answer) => parseJsonObject(options[Number(answer)]?.value));
+    }
+    if (presentation.type === "confirmation") {
+        const confirmation = {
+            type: "confirmation",
+            message: presentation.message,
+        };
+        if (presentation.confirmLabel !== undefined)
+            confirmation.confirmLabel = presentation.confirmLabel;
+        if (presentation.cancelLabel !== undefined)
+            confirmation.cancelLabel = presentation.cancelLabel;
+        return interaction
+            .prompt(confirmation)
+            .then((confirmed) => (confirmed ? {} : undefined));
+    }
+    return {};
+}
+/**
+ * Turn an advertised catalog into Whistle commands. Each handler runs the
+ * backend's step conversation through the caller's interaction; an Agent,
+ * which has no interaction, can run only commands that finish in one step.
+ */
+export function catalogCommands(catalog, invoke) {
+    return catalog.commands.map((definition) => {
+        const { availability, ...rest } = definition;
+        const command = {
+            id: rest.id,
+            title: rest.title,
+            category: rest.category,
+            handler: async (input) => {
+                const signal = input.signal ?? new AbortController().signal;
+                const interaction = input.interaction;
+                let args = await initialArguments(definition, input);
+                if (args === undefined)
+                    return { cancelled: true };
+                for (let step = 0; step < maximumSteps; step += 1) {
+                    signal.throwIfAborted();
+                    const reply = parseCatalogStep(await invoke(definition.id, args, signal));
+                    if (reply.notice !== undefined)
+                        interaction?.notify(reply.notice);
+                    if (reply.type === "done")
+                        return reply.result;
+                    if (interaction === undefined)
+                        throw new WhistleActionError("interaction_required", `${definition.title} needs a person to answer: ${reply.prompt.message}`);
+                    const answer = await interaction.prompt(reply.prompt);
+                    args = { ...reply.next.arguments, [reply.next.answer]: answer };
+                }
+                throw new WhistleActionError("flow_too_long", `${definition.title} asked too many questions.`);
+            },
+        };
+        if (rest.description !== undefined)
+            command.description = rest.description;
+        if (rest.projections !== undefined)
+            command.projections = rest.projections;
+        if (rest.action !== undefined)
+            command.action = rest.action;
+        if (availability !== undefined)
+            command.availability = () => availability;
+        return command;
+    });
+}

package/dist/html.d.ts

@@ -0,0 +1,14 @@
+import { createDefaultHtmlKeymap } from "@opentui/keymap/html";
+import { type WhistleExecutionOrigin, type WhistleRuntime } from "./index.js";
+/** Maintained document keymap plus disposable Whistle command projection. */
+export type HtmlWhistleBinding = Readonly<{
+    /** The host keymap, also available for the application's other layers. */
+    keymap: ReturnType<typeof createDefaultHtmlKeymap>;
+    /** Remove Whistle's layer and subscription; the HTML host belongs to the document. */
+    dispose: () => void;
+}>;
+/**
+ * Bind Whistle commands to the maintained OpenTUI HTML keymap. The root owns
+ * the host's document lifetime; dispose removes the command projection only.
+ */
+export declare function bindHtmlKeymap(root: HTMLElement, whistle: Pick<WhistleRuntime, "snapshot" | "subscribe" | "execute">, origin: WhistleExecutionOrigin): HtmlWhistleBinding;

package/dist/html.js

@@ -0,0 +1,11 @@
+import { createDefaultHtmlKeymap } from "@opentui/keymap/html";
+import { createWhistleKeymapAdapter, } from "./index.js";
+/**
+ * Bind Whistle commands to the maintained OpenTUI HTML keymap. The root owns
+ * the host's document lifetime; dispose removes the command projection only.
+ */
+export function bindHtmlKeymap(root, whistle, origin) {
+    const keymap = createDefaultHtmlKeymap(root);
+    const adapter = createWhistleKeymapAdapter(keymap, whistle, origin);
+    return { keymap, dispose: adapter.cleanup };
+}