@fungi.computer/whistle 0.0.0-stage → 0.0.1

package/dist/interaction.d.ts

@@ -0,0 +1,59 @@
+import type { WhistleInteractionEnd, WhistleInteractionSession, WhistleNotice, WhistleNoticeLink, WhistlePrompt } from "./index.js";
+/** Where one interaction is in its life. */
+export type WhistleInteractionStatus = "working" | "prompting" | "failed" | "done" | "cancelled";
+/** The one pending question, with the sequence its answer must name. */
+export type WhistlePendingPrompt = Readonly<{
+    /** Identity the answer must name; a stale answer is ignored. */
+    sequence: number;
+    /** The parsed question. */
+    request: WhistlePrompt;
+}>;
+/** A notice that carries a message line. */
+export type WhistleMessageNotice = Extract<WhistleNotice, Readonly<{
+    /** Notice kinds that carry a message line. */
+    type: "info" | "progress" | "success";
+}>>;
+/** A "continue elsewhere" notice. */
+export type WhistleHandoffNotice = Extract<WhistleNotice, Readonly<{
+    /** The handoff notice kind. */
+    type: "handoff";
+}>>;
+/** Everything a renderer needs to draw one interaction. */
+export type WhistleInteractionSnapshot = Readonly<{
+    /** The command title. */
+    title: string;
+    /** Where the interaction is in its life. */
+    status: WhistleInteractionStatus;
+    /** Latest info, progress or success message. */
+    message?: WhistleMessageNotice | undefined;
+    /** Latest "continue elsewhere" step, kept until the interaction ends. */
+    handoff?: WhistleHandoffNotice | undefined;
+    /** Links from the latest info notice. */
+    links: readonly WhistleNoticeLink[];
+    /** The question waiting for an answer. */
+    prompt?: WhistlePendingPrompt | undefined;
+    /** Failure message while status is "failed". */
+    failure?: string | undefined;
+}>;
+/** A renderer-neutral store behind one interaction dialog or panel. */
+export type WhistleInteractionHost = Readonly<{
+    /** The current immutable snapshot. */
+    snapshot: () => WhistleInteractionSnapshot;
+    /** Observe snapshot changes. */
+    subscribe: (listener: () => void) => () => void;
+    /** Start one attempt; a retry calls this again. */
+    begin: () => WhistleInteractionSession;
+    /** Answer the pending prompt; a stale sequence or invalid value is ignored. */
+    answer: (sequence: number, value: string | boolean) => boolean;
+    /** Dismiss: abort the attempt, or close a settled failure. */
+    cancel: () => void;
+}>;
+/**
+ * Own one interaction's state for any renderer. Prompts and notices are
+ * parsed here, at the boundary where command-supplied data becomes UI.
+ */
+export declare function createWhistleInteractionHost(options: Readonly<{
+    title: string;
+    onEnd?: (end: WhistleInteractionEnd) => void;
+}>): WhistleInteractionHost;
+export { interactionTextLimit } from "./wire.js";

package/dist/interaction.js

@@ -0,0 +1,131 @@
+import { parseNotice, parsePrompt, createPromptAnswerDecoder, } from "./wire.js";
+/**
+ * Own one interaction's state for any renderer. Prompts and notices are
+ * parsed here, at the boundary where command-supplied data becomes UI.
+ */
+export function createWhistleInteractionHost(options) {
+    const listeners = new Set();
+    let state = {
+        title: options.title,
+        status: "working",
+        links: [],
+    };
+    let attempt;
+    let waiting;
+    let sequence = 0;
+    const publish = (next) => {
+        state = { ...state, ...next };
+        for (const listener of listeners)
+            listener();
+    };
+    const end = (result) => {
+        waiting = undefined;
+        if (result.status === "failed")
+            publish({ status: "failed", failure: result.message, prompt: undefined });
+        else
+            publish({
+                status: result.status === "handled" ? "done" : "cancelled",
+                prompt: undefined,
+            });
+        options.onEnd?.(result);
+    };
+    return {
+        snapshot: () => state,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        begin: () => {
+            attempt?.abort();
+            const controller = new AbortController();
+            attempt = controller;
+            const signal = controller.signal;
+            waiting = undefined;
+            state = { title: options.title, status: "working", links: [] };
+            publish({});
+            const current = () => attempt === controller && !signal.aborted;
+            const interaction = {
+                signal,
+                prompt: (raw, promptOptions) => {
+                    const promptSignal = promptOptions?.signal === undefined
+                        ? signal
+                        : AbortSignal.any([signal, promptOptions.signal]);
+                    promptSignal.throwIfAborted();
+                    const request = parsePrompt(raw);
+                    const decodeAnswer = createPromptAnswerDecoder(raw);
+                    const answer = Promise.withResolvers();
+                    const own = ++sequence;
+                    const abort = () => {
+                        if (waiting?.sequence === own) {
+                            waiting = undefined;
+                            if (current())
+                                publish({ status: "working", prompt: undefined });
+                        }
+                        answer.reject(promptSignal.reason);
+                    };
+                    promptSignal.addEventListener("abort", abort, { once: true });
+                    waiting = {
+                        sequence: own,
+                        request,
+                        resolve: (value) => {
+                            const outcome = decodeAnswer(value);
+                            if (outcome.kind === "invalid")
+                                return false;
+                            promptSignal.removeEventListener("abort", abort);
+                            answer.resolve(outcome.value);
+                            return true;
+                        },
+                    };
+                    publish({
+                        status: "prompting",
+                        prompt: { sequence: own, request },
+                    });
+                    return answer.promise;
+                },
+                notify: (raw) => {
+                    if (!current())
+                        return;
+                    const notice = parseNotice(raw);
+                    if (notice.type === "handoff")
+                        publish({ handoff: notice });
+                    else
+                        publish({
+                            message: notice,
+                            links: notice.type === "info" ? (notice.links ?? []) : state.links,
+                        });
+                },
+            };
+            return {
+                interaction,
+                settle: (result) => {
+                    if (attempt !== controller)
+                        return;
+                    attempt = undefined;
+                    end(signal.aborted ? { status: "cancelled" } : result);
+                },
+            };
+        },
+        answer: (own, value) => {
+            const pending = waiting;
+            if (pending?.sequence !== own)
+                return false;
+            if (!pending.resolve(value))
+                return false;
+            waiting = undefined;
+            publish({ status: "working", prompt: undefined });
+            return true;
+        },
+        cancel: () => {
+            if (attempt !== undefined) {
+                publish({ prompt: undefined });
+                attempt.abort(new Error("Interaction cancelled"));
+                return;
+            }
+            if (state.status === "failed")
+                end({ status: "cancelled" });
+        },
+    };
+}
+export { interactionTextLimit } from "./wire.js";

package/dist/keymap.d.ts

@@ -0,0 +1,34 @@
+import type { WhistleExecutionOrigin, WhistleRuntime } from "./index.js";
+/** Lifecycle operations for a projection into a maintained host keymap. */
+export type WhistleKeymapAdapter = Readonly<{
+    /** Remove the projected layer from the host. */
+    cleanup: () => void;
+}>;
+/** One physical key string mapped to a Whistle command identifier. */
+export type WhistleKeymapBinding = Readonly<{
+    /** Whistle command identifier. */
+    cmd: string;
+    /** Host key notation. */
+    key: string;
+}>;
+/** Host callback that executes one semantic Whistle command. */
+export type WhistleKeymapCommand = Readonly<{
+    /** Whistle command identifier. */
+    name: string;
+    /** Execute the command and report whether the host handled it. */
+    run: () => Promise<boolean>;
+}>;
+/** Binding and command records accepted by a maintained keymap host. */
+export type WhistleKeymapLayer = Readonly<{
+    /** Physical bindings mapped to Whistle command identifiers. */
+    bindings: readonly WhistleKeymapBinding[];
+    /** Host callbacks that execute the semantic commands. */
+    commands: readonly WhistleKeymapCommand[];
+}>;
+/** Minimal registration surface implemented by a maintained host keymap. */
+export type WhistleKeymapHost = Readonly<{
+    /** Register one projected layer and return its disposal function. */
+    registerLayer: (layer: WhistleKeymapLayer) => () => void;
+}>;
+/** Project Whistle bindings into a host-created maintained OpenTUI keymap. */
+export declare function createWhistleKeymapAdapter(keymap: WhistleKeymapHost, whistle: Pick<WhistleRuntime, "snapshot" | "subscribe" | "execute">, origin: WhistleExecutionOrigin): WhistleKeymapAdapter;

package/dist/keymap.js

@@ -0,0 +1,36 @@
+/** Project Whistle bindings into a host-created maintained OpenTUI keymap. */
+export function createWhistleKeymapAdapter(keymap, whistle, origin) {
+    const hostKeymap = keymap;
+    let dispose = () => undefined;
+    let cleaned = false;
+    const update = () => {
+        if (cleaned)
+            return;
+        dispose();
+        const snapshot = whistle.snapshot();
+        const commandIds = new Set(snapshot.bindings.map((row) => row.commandId));
+        const bindings = snapshot.bindings.map((row) => ({
+            cmd: row.commandId,
+            key: row.binding,
+        }));
+        const commands = [...commandIds].map((commandId) => ({
+            name: commandId,
+            run: () => whistle.execute(commandId, { origin }).then(executionResult),
+        }));
+        dispose = hostKeymap.registerLayer({ bindings, commands });
+    };
+    update();
+    const unsubscribe = whistle.subscribe(update);
+    return Object.freeze({
+        cleanup: () => {
+            if (cleaned)
+                return;
+            cleaned = true;
+            unsubscribe();
+            dispose();
+        },
+    });
+}
+function executionResult(outcome) {
+    return outcome.status === "handled";
+}

package/dist/wire.d.ts

@@ -0,0 +1,380 @@
+import * as z from "zod";
+/** Preserve readonly domain collections while deriving contracts from schemas. */
+export type ReadonlySchemaValue<T> = T extends (infer Item)[] ? readonly ReadonlySchemaValue<Item>[] : T extends object ? {
+    readonly [Key in keyof T]: ReadonlySchemaValue<T[Key]>;
+} : T;
+/** Host-owned availability carried by every discovered agent row. */
+export declare const WhistleAvailabilitySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodLiteral<"available">;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"unavailable">;
+    reason: z.ZodString;
+}, z.core.$strict>], "status">;
+/** The JSON value grammar shared by Whistle transports and App adapters. */
+export declare const WhistleJsonValueSchema: z.ZodJSONSchema;
+/** JSON values accepted at Whistle transport boundaries. */
+export type WhistleJsonValue = ReadonlySchemaValue<z.output<typeof WhistleJsonValueSchema>>;
+/** One JSON object, used for action schemas and custom presentation data. */
+export declare const WhistleJsonObjectSchema: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+/** A JSON object accepted at Whistle transport boundaries. */
+export type WhistleJsonObject = ReadonlySchemaValue<z.output<typeof WhistleJsonObjectSchema>>;
+/** Parse copied JSON data at an untrusted transport boundary. */
+export declare const parseJsonValue: typeof WhistleJsonValueSchema.parse;
+/** Parse a copied JSON object at an untrusted transport boundary. */
+export declare const parseJsonObject: typeof WhistleJsonObjectSchema.parse;
+/** General portable failure data for adapters that cross a transport. */
+export declare const WhistleFailureSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+    details: z.ZodOptional<z.ZodJSONSchema>;
+}, z.core.$strict>;
+/** Portable failure data that crosses Whistle transports. */
+export type WhistleFailure = ReadonlySchemaValue<z.output<typeof WhistleFailureSchema>>;
+/** Parse failure data without carrying an Error or stack across the wire. */
+export declare const parseFailure: typeof WhistleFailureSchema.parse;
+/** The JSON object shape used by Whistle action schemas. */
+export declare const WhistleActionSchemaSchema: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+/** JSON Schema document used as an action input or output contract. */
+export type WhistleActionSchema = ReadonlySchemaValue<z.output<typeof WhistleActionSchemaSchema>>;
+declare const availabilitySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodLiteral<"available">;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"unavailable">;
+    reason: z.ZodString;
+}, z.core.$strict>], "status">;
+/** Host-owned availability fact carried in agent snapshots. */
+export type WhistleAvailability = ReadonlySchemaValue<z.output<typeof WhistleAvailabilitySchema>>;
+/** Validate renderer-neutral presentation data attached to an action. */
+export declare const WhistleActionPresentationSchema: 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>]>;
+/** Renderer-neutral presentation data attached to an action. */
+export type WhistleActionPresentation = ReadonlySchemaValue<z.output<typeof WhistleActionPresentationSchema>>;
+/** Validate the serializable action contract carried by a command. */
+export declare const WhistleActionDataSchema: 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>;
+/** Serializable action data accepted by Whistle. */
+export type WhistleAction = ReadonlySchemaValue<z.output<typeof WhistleActionDataSchema>>;
+/** Validate aliases and argument mapping metadata for slash commands. */
+export declare const WhistleSlashArgumentsSchema: 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>;
+/** Slash command parsing metadata accepted from transport owners. */
+export type WhistleSlashArguments = ReadonlySchemaValue<z.output<typeof WhistleSlashArgumentsSchema>>;
+/** A fixed word and its action arguments within a slash command. */
+export type WhistleSlashWord = ReadonlySchemaValue<NonNullable<z.output<typeof WhistleSlashArgumentsSchema>["words"]>[number]>;
+/** Validate explicit membership and ordering across Whistle surfaces. */
+export declare const WhistleCommandProjectionsSchema: 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>;
+/** Projection membership selected by a semantic command owner. */
+export type WhistleCommandProjections = ReadonlySchemaValue<z.output<typeof WhistleCommandProjectionsSchema>>;
+/** Validate data-only command definitions supplied by an adapter. */
+export declare const WhistleCommandDefinitionSchema: 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>;
+/** Data-only command definition accepted at adapter boundaries. */
+export type WhistleCommandDefinition = ReadonlySchemaValue<z.output<typeof WhistleCommandDefinitionSchema>>;
+/** Parse action metadata once before an adapter constructs a Whistle command. */
+export declare const parseAction: typeof WhistleActionDataSchema.parse;
+/** Parse the Whistle-owned projection metadata supplied by an App. */
+export declare const parseProjections: typeof WhistleCommandProjectionsSchema.parse;
+/** Parse an availability fact while preserving its reason. */
+export declare const parseAvailability: typeof availabilitySchema.parse;
+/** Parse one data-only command definition before an adapter creates a command. */
+export declare const parseCommandDefinition: typeof WhistleCommandDefinitionSchema.parse;
+/** One neutral agent row emitted by Whistle's `snapshot.agent` projection. */
+export declare const WhistleAgentProjectionSchema: z.ZodObject<{
+    commandId: z.ZodString;
+    sourceId: z.ZodString;
+    scope: z.ZodOptional<z.ZodString>;
+    title: z.ZodString;
+    category: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    order: z.ZodNumber;
+    availability: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        status: z.ZodLiteral<"available">;
+    }, z.core.$strict>, z.ZodObject<{
+        status: z.ZodLiteral<"unavailable">;
+        reason: z.ZodString;
+    }, z.core.$strict>], "status">;
+    action: z.ZodOptional<z.ZodObject<{
+        inputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    }, z.core.$strict>>;
+    keybind: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Decoded agent projection data as received across the wire. */
+export type WhistleAgentProjectionData = z.output<typeof WhistleAgentProjectionSchema>;
+/** A neutral Whistle agent projection collection. */
+export declare const WhistleAgentProjectionsSchema: z.ZodArray<z.ZodObject<{
+    commandId: z.ZodString;
+    sourceId: z.ZodString;
+    scope: z.ZodOptional<z.ZodString>;
+    title: z.ZodString;
+    category: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    order: z.ZodNumber;
+    availability: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        status: z.ZodLiteral<"available">;
+    }, z.core.$strict>, z.ZodObject<{
+        status: z.ZodLiteral<"unavailable">;
+        reason: z.ZodString;
+    }, z.core.$strict>], "status">;
+    action: z.ZodOptional<z.ZodObject<{
+        inputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    }, z.core.$strict>>;
+    keybind: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+/** Decode an untrusted agent projection collection at the wire boundary. */
+export declare const parse: typeof WhistleAgentProjectionsSchema.parse;
+/** Longest prompt answer or message an interaction carries. */
+export declare const interactionTextLimit = 8192;
+/** Validate renderer-neutral interaction prompts received from a host. */
+export declare const WhistlePromptSchema: 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">;
+/** A renderer-neutral interaction prompt. */
+export type WhistlePrompt = ReadonlySchemaValue<z.output<typeof WhistlePromptSchema>>;
+/** One selectable value in a parsed interaction prompt. */
+export type WhistlePromptOption = NonNullable<Extract<WhistlePrompt, {
+    type: "choice";
+}>["options"][number]>;
+/** Validate interaction notices received from a host. */
+export declare const WhistleNoticeSchema: 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">;
+/** A renderer-neutral interaction notice. */
+export type WhistleNotice = ReadonlySchemaValue<z.output<typeof WhistleNoticeSchema>>;
+/** One link included in a parsed informational notice. */
+export type WhistleNoticeLink = ReadonlySchemaValue<NonNullable<Extract<z.output<typeof WhistleNoticeSchema>, {
+    type: "info";
+}>["links"]>[number]>;
+/** Parse one interaction prompt at the boundary where a client renders it. */
+export declare const parsePrompt: typeof WhistlePromptSchema.parse;
+/** Parse one interaction notice at the boundary where a client renders it. */
+export declare const parseNotice: typeof WhistleNoticeSchema.parse;
+/** Answer types owned by the closed prompt vocabulary. */
+export type WhistlePromptAnswers = {
+    confirmation: boolean;
+    text: string;
+    choice: string;
+};
+/** A prompt and its discriminator remain correlated through generic dispatch. */
+export type WhistlePromptOf<Kind extends WhistlePrompt["type"]> = {
+    [K in Kind]: Extract<WhistlePrompt, {
+        type: K;
+    }> & {
+        readonly type: K;
+    };
+}[Kind];
+/** Capture a prompt's parsed answer contract before handing it to a renderer. */
+export declare function createPromptAnswerParser<Kind extends WhistlePrompt["type"]>(prompt: WhistlePromptOf<Kind>): (value: string | boolean) => WhistlePromptAnswers[Kind];
+/** Parse the answer a human gave to one prompt before the command sees it. */
+export declare function parsePromptAnswer<Kind extends WhistlePrompt["type"]>(prompt: WhistlePromptOf<Kind>, value: string | boolean): WhistlePromptAnswers[Kind];
+/** Capture a typed answer decoder; invalid input stays an explicit outcome. */
+export declare function createPromptAnswerDecoder<Kind extends WhistlePrompt["type"]>(prompt: WhistlePromptOf<Kind>): (value: string | boolean) => Readonly<{
+    kind: "accepted";
+    value: WhistlePromptAnswers[Kind];
+}> | Readonly<{
+    kind: "invalid";
+    cause: z.ZodError;
+}>;
+/** Decode a human answer without throwing so renderers can handle invalid input. */
+export declare function decodePromptAnswer<Kind extends WhistlePrompt["type"]>(prompt: WhistlePromptOf<Kind>, value: string | boolean): Readonly<{
+    kind: "invalid";
+    cause: z.ZodError;
+}> | Readonly<{
+    kind: "accepted";
+    value: WhistlePromptAnswers[Kind];
+}>;
+export {};