@fungi.computer/whistle 0.0.0-stage → 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,253 @@
+import type { WhistleAction, WhistleAvailability, WhistleCommandProjections, WhistleFailure, WhistleJsonValue, WhistleNotice, WhistlePrompt, WhistlePromptOf, WhistlePromptAnswers, WhistleSlashArguments } from "./wire.js";
+export type { WhistleAction, WhistleActionPresentation, WhistleActionSchema, WhistleAvailability, WhistleCommandProjections, WhistleCommandDefinition, WhistleFailure, WhistleJsonObject, WhistleJsonValue, WhistleNotice, WhistleNoticeLink, WhistlePrompt, WhistlePromptOption, WhistleSlashArguments, WhistleSlashWord, } from "./wire.js";
+/** The trusted host origin entering the single execution door. */
+export type WhistleExecutionOrigin = "agent" | "browser" | "keyboard" | "menu" | "palette" | "programmatic" | "slash" | "terminal";
+/** A source-owned command's execution callback, invoked only through the execution door. */
+export type WhistleCommandHandler<Arguments, Result> = {
+    /** Runs the command for one execution input and returns its result. */
+    bivarianceHack(input: WhistleExecutionInput<Arguments>): Result | undefined | Promise<Result | undefined>;
+}["bivarianceHack"];
+/** The answer type for one prompt kind. */
+export type WhistlePromptAnswer<Prompt extends WhistlePrompt> = WhistlePromptAnswers[Prompt["type"]];
+/**
+ * A human conversation attached to one execution. `prompt` rejects when the
+ * human cancels; `signal` aborts when the whole interaction is dismissed.
+ */
+export type WhistleInteraction = Readonly<{
+    /** Aborted when the human dismisses the interaction. */
+    signal: AbortSignal;
+    /**
+     * Ask one question and wait for its answer. `signal` withdraws just this
+     * question, e.g. when an out-of-band callback answers it first.
+     */
+    prompt: <Kind extends WhistlePrompt["type"]>(prompt: WhistlePromptOf<Kind>, options?: Readonly<{
+        signal?: AbortSignal;
+    }>) => Promise<WhistlePromptAnswers[Kind]>;
+    /** Show one status update. */
+    notify: (notice: WhistleNotice) => void;
+}>;
+/** How an execution with an attached interaction ended. */
+export type WhistleInteractionEnd = Readonly<{
+    /** The handler finished. */
+    status: "handled";
+}> | Readonly<{
+    /** The human dismissed the interaction. */
+    status: "cancelled";
+}> | Readonly<{
+    /** The handler failed. */
+    status: "failed";
+    /** Portable failure message for the human. */
+    message: string;
+}>;
+/** One interaction a presenter opened for one execution. */
+export type WhistleInteractionSession = Readonly<{
+    /** The interaction handed to the command handler. */
+    interaction: WhistleInteraction;
+    /** Called exactly once when the handler settles. */
+    settle: (end: WhistleInteractionEnd) => void;
+}>;
+/**
+ * A mounted client that can render interactions. Whistle opens one session per
+ * human execution that has no caller-supplied interaction.
+ */
+export type WhistlePresenter = (request: Readonly<{
+    /** Canonical namespace-local command identity. */
+    commandId: string;
+    /** Human-facing command title. */
+    title: string;
+    /** Execute the same command again with the same input. */
+    retry: () => void;
+}>) => WhistleInteractionSession;
+/** The already-typed input supplied to a command handler. */
+export type WhistleExecutionInput<Arguments = unknown> = Readonly<{
+    /** The host origin requesting execution. */
+    origin: WhistleExecutionOrigin;
+    /** Typed action arguments, when this execution carries user input. */
+    arguments?: Arguments;
+    /** Host-owned cancellation for this invocation; never part of projections. */
+    signal?: AbortSignal;
+    /**
+     * Human conversation for this invocation. Supplied by the caller, or by the
+     * runtime's registered presenter for human origins; absent for agents.
+     */
+    interaction?: WhistleInteraction;
+}>;
+/** An owning handler's explicit failure code and optional structured details. */
+export declare class WhistleActionError extends Error {
+    /** Stable failure identity supplied by the handler owner. */
+    readonly code: string;
+    /** Optional JSON context safe to return to the caller. */
+    readonly details?: WhistleJsonValue | undefined;
+    constructor(
+    /** Stable failure identity supplied by the handler owner. */
+    code: string, message: string, 
+    /** Optional JSON context safe to return to the caller. */
+    details?: WhistleJsonValue | undefined);
+}
+/** The normalized result of one command execution request. */
+export type WhistleExecutionOutcome<Result = unknown> = Extract<WhistleAvailability, {
+    /** Current host facts prevented dispatch to the handler. */
+    status: "unavailable";
+}> | Readonly<{
+    /** The admitted handler completed synchronously or asynchronously. */
+    status: "handled";
+    /** The typed handler result, when it produced one. */
+    result?: Result;
+}> | Readonly<{
+    /** The runtime was closed before this execution began. */
+    status: "closed";
+}> | Readonly<{
+    /** No currently admitted command has the requested identity. */
+    status: "missing";
+}> | Readonly<{
+    /** The requested command identity is blank. */
+    status: "invalid";
+}> | Readonly<{
+    /** The normalized error raised by the admitted handler. */
+    error: WhistleFailure;
+    /** The admitted handler failed. */
+    status: "failed";
+}>;
+/** A valid contribution was attempted after the runtime closed. */
+export declare class WhistleClosedError extends Error {
+    /** Construct the provisional error for a valid post-close contribution. */
+    constructor();
+}
+/** One semantic command definition. */
+export type WhistleCommand<Arguments = unknown, Result = unknown> = Readonly<{
+    /** The source-local command identity segment. */
+    id: string;
+    /** Human-facing command title. */
+    title: string;
+    /** Human-facing command category. */
+    category: string;
+    /** Optional human-facing command description. */
+    description?: string | undefined;
+    /** Explicit projection membership and per-surface metadata. */
+    projections?: WhistleCommandProjections;
+    /** Typed action contract and renderer-neutral presentation hint. */
+    action?: WhistleAction;
+    /** Read current host facts on discovery and immediately before dispatch. */
+    availability?: () => WhistleAvailability;
+    /** Host-owned callback invoked only through the execution door. */
+    handler: WhistleCommandHandler<Arguments, Result>;
+}>;
+/** One contribution of source-owned commands to a namespace. */
+export type WhistleContribution = Readonly<{
+    /** Source authority identity for this contribution. */
+    sourceId: string;
+    /** Namespace receiving this contribution. */
+    namespace: string;
+    /**
+     * Focus scope, e.g. one mounted App window. Omitted means global. Slash
+     * aliases are unique within one scope; {@link scopeSnapshot} lets a focused
+     * scope's alias or binding shadow the same global one.
+     */
+    scope?: string;
+    /** Ordered command definitions in this contribution. */
+    commands: readonly WhistleCommand<never>[];
+}>;
+/** Shared immutable metadata carried by each projection row. */
+export type WhistleProjectionRow = Readonly<{
+    /** Canonical namespace-local command identity. */
+    commandId: string;
+    /** Source authority identity. */
+    sourceId: string;
+    /** Focus scope of the contribution; omitted for global rows. */
+    scope?: string;
+    /** Human-facing command title. */
+    title: string;
+    /** Human-facing command category. */
+    category: string;
+    /** Optional human-facing command description. */
+    description?: string | undefined;
+    /** Explicit order within the containing surface. */
+    order: number;
+    /** Typed action contract and renderer-neutral presentation hint. */
+    action?: WhistleAction;
+    /** An unavailable command stays discoverable with its explanation. */
+    availability: WhistleAvailability;
+}>;
+/** Immutable agent snapshot row composed from the schema-owned action data. */
+export type WhistleAgentProjection = Omit<WhistleProjectionRow, "action"> & Readonly<{
+    /** Semantic inputs and outputs; client presentation stays local. */
+    action?: Pick<WhistleAction, "inputSchema" | "outputSchema">;
+    /** Optional host-owned key label. */
+    keybind?: string;
+}>;
+/** One binding value projected from a command. */
+export type WhistleBindingProjection = WhistleProjectionRow & Readonly<{
+    /** One binding value exposed for the command. */
+    binding: string;
+}>;
+/** One palette value projected from a command. */
+export type WhistlePaletteProjection = WhistleProjectionRow;
+/** One slash alias projected from a command. */
+export type WhistleSlashProjection = WhistleProjectionRow & Readonly<{
+    /** One slash alias exposed for the command. */
+    alias: string;
+    /** How text after the alias becomes arguments, when the command takes any. */
+    arguments?: WhistleSlashArguments;
+}>;
+/** One help value projected from a command. */
+export type WhistleHelpProjection = WhistleProjectionRow;
+/** One menu value projected from a command. */
+export type WhistleMenuProjection = WhistleProjectionRow;
+/** The six immutable views of one semantic command graph. */
+export type WhistleSnapshot = Readonly<{
+    /** Binding rows derived from the semantic graph. */
+    bindings: readonly WhistleBindingProjection[];
+    /** Palette rows derived from the semantic graph. */
+    palette: readonly WhistlePaletteProjection[];
+    /** Slash rows derived from the semantic graph. */
+    slash: readonly WhistleSlashProjection[];
+    /** Help rows derived from the semantic graph. */
+    help: readonly WhistleHelpProjection[];
+    /** Menu rows derived from the semantic graph. */
+    menu: readonly WhistleMenuProjection[];
+    /** Agent rows derived from the semantic graph. */
+    agent: readonly WhistleAgentProjection[];
+}>;
+/** An idempotent lease for one contribution generation. */
+export type WhistleContributionLease = Readonly<{
+    /** Atomically replace this generation's commands without changing ownership. */
+    update: (commands: WhistleContribution["commands"]) => void;
+    /** Dispose this contribution generation. */
+    dispose: () => void;
+}>;
+/** The provisional Whistle semantic runtime seam. */
+export type WhistleRuntime = Readonly<{
+    /** Admit one source-owned contribution. */
+    contribute: (contribution: WhistleContribution) => WhistleContributionLease;
+    /**
+     * Synchronously release the live graph into the shared empty closed snapshot.
+     * Repeated calls are no-ops.
+     *
+     * @returns `undefined`; close produces no value.
+     */
+    close: () => undefined;
+    /** Execute one currently admitted command through the shared door. */
+    execute: (commandId: string, input: WhistleExecutionInput) => Promise<WhistleExecutionOutcome>;
+    /** Pull the current immutable semantic snapshot. */
+    snapshot: () => WhistleSnapshot;
+    /** Observe coherent semantic graph changes. */
+    subscribe: (listener: () => void) => () => void;
+    /**
+     * Register the mounted client that renders interactions for human
+     * executions. The newest registration wins until its disposer runs.
+     */
+    present: (presenter: WhistlePresenter) => () => void;
+}>;
+export { createWhistleKeymapAdapter, type WhistleKeymapAdapter, type WhistleKeymapBinding, type WhistleKeymapCommand, type WhistleKeymapHost, type WhistleKeymapLayer, } from "./keymap.js";
+/**
+ * The projection for one focused scope: global rows plus the focused
+ * scope's rows. A focused slash alias or binding shadows the same global one.
+ * Agent rows follow the same scope filter; the complete runtime remains whole.
+ *
+ * @param snapshot - A complete runtime snapshot.
+ * @param scope - The focused scope, or `null` when nothing scoped is focused.
+ * @returns A frozen snapshot of globals plus the selected scope.
+ */
+export declare function scopeSnapshot(snapshot: WhistleSnapshot, scope: string | null): WhistleSnapshot;
+/** Construct the provisional semantic runtime shell. */
+export declare function createWhistle(): WhistleRuntime;