whistle

Import

Import

import * as api from "@fungi.computer/whistle";

Exports

Kind	Export	Description
Cclass	WhistleActionError	An owning handler’s explicit failure code and optional structured details.
Cclass	WhistleClosedError	A valid contribution was attempted after the runtime closed.
Ttype alias	WhistleExecutionOrigin	The trusted host origin entering the single execution door.
Ttype alias	WhistleCommandHandler	A source-owned command’s execution callback, invoked only through the execution door.
Ttype alias	WhistlePromptAnswer	The answer type for one prompt kind.
Ttype alias	WhistleInteraction	A human conversation attached to one execution. prompt rejects when the human cancels; signal aborts when the whole interaction is dismissed.
Ttype alias	WhistleInteractionEnd	How an execution with an attached interaction ended.
Ttype alias	WhistleInteractionSession	One interaction a presenter opened for one execution.
Ttype alias	WhistlePresenter	A mounted client that can render interactions. Whistle opens one session per human execution that has no caller-supplied interaction.
Ttype alias	WhistleExecutionInput	The already-typed input supplied to a command handler.
Ttype alias	WhistleExecutionOutcome	The normalized result of one command execution request.
Ttype alias	WhistleCommand	One semantic command definition.
Ttype alias	WhistleContribution	One contribution of source-owned commands to a namespace.
Ttype alias	WhistleProjectionRow	Shared immutable metadata carried by each projection row.
Ttype alias	WhistleAgentProjection	Immutable agent snapshot row composed from the schema-owned action data.
Ttype alias	WhistleBindingProjection	One binding value projected from a command.
Ttype alias	WhistlePaletteProjection	One palette value projected from a command.
Ttype alias	WhistleSlashProjection	One slash alias projected from a command.
Ttype alias	WhistleHelpProjection	One help value projected from a command.
Ttype alias	WhistleMenuProjection	One menu value projected from a command.
Ttype alias	WhistleSnapshot	The six immutable views of one semantic command graph.
Ttype alias	WhistleContributionLease	An idempotent lease for one contribution generation.
Ttype alias	WhistleRuntime	The provisional Whistle semantic runtime seam.
Ttype alias	WhistleKeymapAdapter	Lifecycle operations for a projection into a maintained host keymap.
Ttype alias	WhistleKeymapBinding	One physical key string mapped to a Whistle command identifier.
Ttype alias	WhistleKeymapCommand	Host callback that executes one semantic Whistle command.
Ttype alias	WhistleKeymapLayer	Binding and command records accepted by a maintained keymap host.
Ttype alias	WhistleKeymapHost	Minimal registration surface implemented by a maintained host keymap.
fnfunction	scopeSnapshot()	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.
fnfunction	createWhistle()	Construct the provisional semantic runtime shell.
fnfunction	createWhistleKeymapAdapter()	Project Whistle bindings into a host-created maintained OpenTUI keymap.

WhistleActionErrorCclass

An owning handler’s explicit failure code and optional structured details.

Extends

• Error

Constructors

Constructor

Signature

new WhistleActionError(
   code,
   message,
   details?
): WhistleActionError;

Parameters

Parameter	Type	Description
code	string	Stable failure identity supplied by the handler owner.
message	string	-
details?	WhistleJsonValue	Optional JSON context safe to return to the caller.

Returns

WhistleActionError

Overrides

Signature

Error.constructor;

Properties

code

Signature

readonly code: string;

Stable failure identity supplied by the handler owner.

details?

Signature

readonly optional details?: WhistleJsonValue;

Optional JSON context safe to return to the caller.

---

WhistleClosedErrorCclass

A valid contribution was attempted after the runtime closed.

Extends

• Error

Constructors

Constructor

Signature

new WhistleClosedError(): WhistleClosedError;

Construct the provisional error for a valid post-close contribution.

Returns

WhistleClosedError

Overrides

Signature

Error.constructor;

WhistleExecutionOriginTtype alias

Signature

type WhistleExecutionOrigin =
  | "agent"
  | "browser"
  | "keyboard"
  | "menu"
  | "palette"
  | "programmatic"
  | "slash"
  | "terminal";

The trusted host origin entering the single execution door.

---

WhistleCommandHandlerTtype alias

Signature

type WhistleCommandHandler<Arguments, Result> = object["bivarianceHack"];

A source-owned command’s execution callback, invoked only through the execution door.

Type Parameters

Type Parameter
Arguments
Result

---

WhistlePromptAnswerTtype alias

Signature

type WhistlePromptAnswer<Prompt> = WhistlePromptAnswers[Prompt["type"]];

The answer type for one prompt kind.

Type Parameters

Type Parameter
Prompt extends WhistlePrompt

---

WhistleInteractionTtype alias

Signature

type WhistleInteraction = Readonly<{
  signal: AbortSignal;
  prompt: <Kind>(prompt, options?) => Promise<WhistlePromptAnswers[Kind]>;
  notify: (notice) => void;
  run: <Result>(operation) => Promise<Result>;
}>;

A human conversation attached to one execution. prompt rejects when the human cancels; signal aborts when the whole interaction is dismissed.

---

WhistleInteractionEndTtype alias

Signature

type WhistleInteractionEnd =
  | Readonly<{
      status: "handled";
    }>
  | Readonly<{
      status: "cancelled";
    }>
  | Readonly<{
      status: "failed";
      message: string;
    }>;

How an execution with an attached interaction ended.

---

WhistleInteractionSessionTtype alias

Signature

type WhistleInteractionSession = Readonly<{
  interaction: WhistleInteraction;
  settle: (end) => void;
}>;

One interaction a presenter opened for one execution.

---

WhistlePresenterTtype alias

Signature

type WhistlePresenter = (request) => WhistleInteractionSession;

A mounted client that can render interactions. Whistle opens one session per human execution that has no caller-supplied interaction.

Parameters

Parameter	Type
request	Readonly<{ commandId: string; title: string; }>

Returns

WhistleInteractionSession

---

WhistleExecutionInputTtype alias

Signature

type WhistleExecutionInput<Arguments> = Readonly<{
  origin: WhistleExecutionOrigin;
  arguments?: Arguments;
  signal?: AbortSignal;
  interaction?: WhistleInteraction;
}>;

The already-typed input supplied to a command handler.

Type Parameters

Type Parameter	Default type
Arguments	unknown

---

WhistleExecutionOutcomeTtype alias

Signature

type WhistleExecutionOutcome<Result> =
  | Extract<
      WhistleAvailability,
      {
        status: "unavailable";
      }
    >
  | Readonly<{
      status: "handled";
      result?: Result;
    }>
  | Readonly<{
      status: "closed";
    }>
  | Readonly<{
      status: "missing";
    }>
  | Readonly<{
      status: "invalid";
    }>
  | Readonly<{
      error: WhistleFailure;
      status: "failed";
    }>;

The normalized result of one command execution request.

Type Parameters

Type Parameter	Default type
Result	unknown

---

WhistleCommandTtype alias

Signature

type WhistleCommand<Arguments, Result> = Readonly<{
  id: string;
  title: string;
  category: string;
  description?: string;
  projections?: WhistleCommandProjections;
  action?: WhistleAction;
  availability?: () => WhistleAvailability;
  handler: WhistleCommandHandler<Arguments, Result>;
}>;

One semantic command definition.

Type Parameters

Type Parameter	Default type
Arguments	unknown
Result	unknown

---

WhistleContributionTtype alias

Signature

type WhistleContribution = Readonly<{
  sourceId: string;
  namespace: string;
  scope?: string;
  commands: readonly WhistleCommand<never>[];
}>;

One contribution of source-owned commands to a namespace.

---

WhistleProjectionRowTtype alias

Signature

type WhistleProjectionRow = Readonly<{
  commandId: string;
  sourceId: string;
  scope?: string;
  title: string;
  category: string;
  description?: string;
  order: number;
  action?: WhistleAction;
  availability: WhistleAvailability;
}>;

Shared immutable metadata carried by each projection row.

---

WhistleAgentProjectionTtype alias

Signature

type WhistleAgentProjection = Omit<WhistleProjectionRow, "action"> &
  Readonly<{
    action?: Pick<WhistleAction, "inputSchema" | "outputSchema">;
    keybind?: string;
  }>;

Immutable agent snapshot row composed from the schema-owned action data.

---

WhistleBindingProjectionTtype alias

Signature

type WhistleBindingProjection = WhistleProjectionRow &
  Readonly<{
    binding: string;
  }>;

One binding value projected from a command.

---

WhistlePaletteProjectionTtype alias

Signature

type WhistlePaletteProjection = WhistleProjectionRow;

One palette value projected from a command.

---

WhistleSlashProjectionTtype alias

Signature

type WhistleSlashProjection = WhistleProjectionRow &
  Readonly<{
    alias: string;
    consumesDraft?: boolean;
    arguments?: WhistleSlashArguments;
  }>;

One slash alias projected from a command.

---

WhistleHelpProjectionTtype alias

Signature

type WhistleHelpProjection = WhistleProjectionRow;

One help value projected from a command.

---

WhistleMenuProjectionTtype alias

Signature

type WhistleMenuProjection = WhistleProjectionRow;

One menu value projected from a command.

---

WhistleSnapshotTtype alias

Signature

type WhistleSnapshot = Readonly<{
  bindings: readonly WhistleBindingProjection[];
  palette: readonly WhistlePaletteProjection[];
  slash: readonly WhistleSlashProjection[];
  help: readonly WhistleHelpProjection[];
  menu: readonly WhistleMenuProjection[];
  agent: readonly WhistleAgentProjection[];
}>;

The six immutable views of one semantic command graph.

---

WhistleContributionLeaseTtype alias

Signature

type WhistleContributionLease = Readonly<{
  update: (commands) => void;
  dispose: () => void;
}>;

An idempotent lease for one contribution generation.

---

WhistleRuntimeTtype alias

Signature

type WhistleRuntime = Readonly<{
  contribute: (contribution) => WhistleContributionLease;
  close: () => undefined;
  execute: (commandId, input) => Promise<WhistleExecutionOutcome>;
  snapshot: () => WhistleSnapshot;
  subscribe: (listener) => () => void;
  present: (presenter) => () => void;
}>;

The provisional Whistle semantic runtime seam.

---

WhistleKeymapAdapterTtype alias

Signature

type WhistleKeymapAdapter = Readonly<{
  cleanup: () => void;
}>;

Lifecycle operations for a projection into a maintained host keymap.

---

WhistleKeymapBindingTtype alias

Signature

type WhistleKeymapBinding = Readonly<{
  cmd: string;
  key: string;
}>;

One physical key string mapped to a Whistle command identifier.

---

WhistleKeymapCommandTtype alias

Signature

type WhistleKeymapCommand = Readonly<{
  name: string;
  run: () => Promise<boolean>;
}>;

Host callback that executes one semantic Whistle command.

---

WhistleKeymapLayerTtype alias

Signature

type WhistleKeymapLayer = Readonly<{
  bindings: readonly WhistleKeymapBinding[];
  commands: readonly WhistleKeymapCommand[];
}>;

Binding and command records accepted by a maintained keymap host.

---

WhistleKeymapHostTtype alias

Signature

type WhistleKeymapHost = Readonly<{
  registerLayer: (layer) => () => void;
}>;

Minimal registration surface implemented by a maintained host keymap.

scopeSnapshot()fnfunction

Signature

function scopeSnapshot(snapshot, scope): WhistleSnapshot;

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.

Parameters

Parameter	Type	Description
snapshot	WhistleSnapshot	A complete runtime snapshot.
scope	string | null	The focused scope, or null when nothing scoped is focused.

Returns

WhistleSnapshot

A frozen snapshot of globals plus the selected scope.

---

createWhistle()fnfunction

Signature

function createWhistle(): WhistleRuntime;

Construct the provisional semantic runtime shell.

Returns

WhistleRuntime

---

createWhistleKeymapAdapter()fnfunction

Signature

function createWhistleKeymapAdapter(
  keymap,
  whistle,
  origin,
): WhistleKeymapAdapter;

Project Whistle bindings into a host-created maintained OpenTUI keymap.

Parameters

Parameter	Type
keymap	WhistleKeymapHost
whistle	Pick<WhistleRuntime, "snapshot" | "subscribe" | "execute">
origin	WhistleExecutionOrigin

Returns

WhistleKeymapAdapter

References

WhistleAction

Re-exports WhistleAction

---

WhistleActionPresentation

Re-exports WhistleActionPresentation

---

WhistleActionSchema

Re-exports WhistleActionSchema

---

WhistleAnswerValue

Re-exports WhistleAnswerValue

---

WhistleAvailability

Re-exports WhistleAvailability

---

WhistleCommandProjections

Re-exports WhistleCommandProjections

---

WhistleCommandDefinition

Re-exports WhistleCommandDefinition

---

WhistleDecisionAnswer

Re-exports WhistleDecisionAnswer

---

WhistleFailure

Re-exports WhistleFailure

---

WhistleJsonObject

Re-exports WhistleJsonObject

---

WhistleJsonValue

Re-exports WhistleJsonValue

---

WhistleNotice

Re-exports WhistleNotice

---

WhistleNoticeLink

Re-exports WhistleNoticeLink

---

WhistlePrompt

Re-exports WhistlePrompt

---

WhistlePromptOption

Re-exports WhistlePromptOption

---

WhistleSlashArguments

Re-exports WhistleSlashArguments

---

WhistleSlashWord

Re-exports WhistleSlashWord