Skip to content
Whistle0.3.0
API reference

wire

Import

Section titled “Import”
Import
import * as api from "@fungi.computer/whistle/wire";

Exports

Section titled “Exports”
Kind Export Description
type alias ReadonlySchemaValue Preserve readonly domain collections while deriving contracts from schemas.
type alias WhistleJsonValue JSON values accepted at Whistle transport boundaries.
type alias WhistleJsonObject A JSON object accepted at Whistle transport boundaries.
type alias WhistleFailure Portable failure data that crosses Whistle transports.
type alias WhistleActionSchema JSON Schema document used as an action input or output contract.
type alias WhistleAvailability Host-owned availability fact carried in agent snapshots.
type alias WhistleActionPresentation Renderer-neutral presentation data attached to an action.
type alias WhistleAction Serializable action data accepted by Whistle.
type alias WhistleSlashArguments Slash command parsing metadata accepted from transport owners.
type alias WhistleSlashWord A fixed word and its action arguments within a slash command.
type alias WhistleCommandProjections Projection membership selected by a semantic command owner.
type alias WhistleCommandDefinition Data-only command definition accepted at adapter boundaries.
type alias WhistleAgentProjectionData Decoded agent projection data as received across the wire.
type alias WhistlePrompt A renderer-neutral interaction prompt.
type alias WhistlePromptOption One selectable value in a parsed interaction prompt.
type alias WhistleNotice A renderer-neutral interaction notice.
type alias WhistleNoticeLink One link included in a parsed informational notice.
type alias WhistleDecisionAnswer The answer to a decision prompt: picked option values and/or written text.
type alias WhistleAnswerValue Every value a renderer may hand back as the answer to a prompt.
type alias WhistlePromptAnswers Answer types owned by the closed prompt vocabulary.
type alias WhistlePromptOf A prompt and its discriminator remain correlated through generic dispatch.
constant WhistleAvailabilitySchema Host-owned availability carried by every discovered agent row.
constant WhistleJsonValueSchema The JSON value grammar shared by Whistle transports and App adapters.
constant WhistleJsonObjectSchema One JSON object, used for action schemas and custom presentation data.
constant parseJsonValue Parse copied JSON data at an untrusted transport boundary.
constant parseJsonObject Parse a copied JSON object at an untrusted transport boundary.
constant WhistleFailureSchema General portable failure data for adapters that cross a transport.
constant parseFailure Parse failure data without carrying an Error or stack across the wire.
constant WhistleActionSchemaSchema The JSON object shape used by Whistle action schemas.
constant WhistleActionPresentationSchema Validate renderer-neutral presentation data attached to an action.
constant WhistleActionDataSchema Validate the serializable action contract carried by a command.
constant WhistleSlashArgumentsSchema Validate aliases and argument mapping metadata for slash commands.
constant WhistleCommandProjectionsSchema Validate explicit membership and ordering across Whistle surfaces.
constant WhistleCommandDefinitionSchema Validate data-only command definitions supplied by an adapter.
constant parseAction Parse action metadata once before an adapter constructs a Whistle command.
constant parseProjections Parse the Whistle-owned projection metadata supplied by an App.
constant parseAvailability Parse an availability fact while preserving its reason.
constant parseCommandDefinition Parse one data-only command definition before an adapter creates a command.
constant WhistleAgentProjectionSchema One neutral agent row emitted by Whistle’s snapshot.agent projection.
constant WhistleAgentProjectionsSchema A neutral Whistle agent projection collection.
constant parse Decode an untrusted agent projection collection at the wire boundary.
constant interactionTextLimit Longest prompt answer or message an interaction carries.
constant interactionTitleLimit A modal title: human words, short enough to read at a glance.
constant WhistlePromptSchema Validate renderer-neutral interaction prompts received from a host.
constant WhistleNoticeSchema Validate interaction notices received from a host.
constant parsePrompt Parse one interaction prompt at the boundary where a client renders it.
constant parseNotice Parse one interaction notice at the boundary where a client renders it.
function createPromptAnswerParser() Capture a prompt’s parsed answer contract before handing it to a renderer.
function parsePromptAnswer() Parse the answer a human gave to one prompt before the command sees it.
function createPromptAnswerDecoder() Capture a typed answer decoder; invalid input stays an explicit outcome.
function decodePromptAnswer() Decode a human answer without throwing so renderers can handle invalid input.

ReadonlySchemaValuetype alias

Section titled “ReadonlySchemaValue”
Signature
type ReadonlySchemaValue<T> = T extends infer Item[] ? readonly ReadonlySchemaValue<Item>[] : T extends object ? { readonly [Key in keyof T]: ReadonlySchemaValue<T[Key]> } : T;

Preserve readonly domain collections while deriving contracts from schemas.

Type Parameters

Section titled “Type Parameters”
Type Parameter
T

WhistleJsonValuetype alias

Section titled “WhistleJsonValue”
Signature
type WhistleJsonValue = ReadonlySchemaValue<
  z.output<typeof WhistleJsonValueSchema>
>;

JSON values accepted at Whistle transport boundaries.

WhistleJsonObjecttype alias

Section titled “WhistleJsonObject”
Signature
type WhistleJsonObject = ReadonlySchemaValue<
  z.output<typeof WhistleJsonObjectSchema>
>;

A JSON object accepted at Whistle transport boundaries.

WhistleFailuretype alias

Section titled “WhistleFailure”
Signature
type WhistleFailure = ReadonlySchemaValue<
  z.output<typeof WhistleFailureSchema>
>;

Portable failure data that crosses Whistle transports.

WhistleActionSchematype alias

Section titled “WhistleActionSchema”
Signature
type WhistleActionSchema = ReadonlySchemaValue<
  z.output<typeof WhistleActionSchemaSchema>
>;

JSON Schema document used as an action input or output contract.

WhistleAvailabilitytype alias

Section titled “WhistleAvailability”
Signature
type WhistleAvailability = ReadonlySchemaValue<
  z.output<typeof WhistleAvailabilitySchema>
>;

Host-owned availability fact carried in agent snapshots.

WhistleActionPresentationtype alias

Section titled “WhistleActionPresentation”
Signature
type WhistleActionPresentation = ReadonlySchemaValue<
  z.output<typeof WhistleActionPresentationSchema>
>;

Renderer-neutral presentation data attached to an action.

WhistleActiontype alias

Section titled “WhistleAction”
Signature
type WhistleAction = ReadonlySchemaValue<
  z.output<typeof WhistleActionDataSchema>
>;

Serializable action data accepted by Whistle.

WhistleSlashArgumentstype alias

Section titled “WhistleSlashArguments”
Signature
type WhistleSlashArguments = ReadonlySchemaValue<
  z.output<typeof WhistleSlashArgumentsSchema>
>;

Slash command parsing metadata accepted from transport owners.

WhistleSlashWordtype alias

Section titled “WhistleSlashWord”
Signature
type WhistleSlashWord = ReadonlySchemaValue<
  NonNullable<z.output<typeof WhistleSlashArgumentsSchema>["words"]>[number]
>;

A fixed word and its action arguments within a slash command.

WhistleCommandProjectionstype alias

Section titled “WhistleCommandProjections”
Signature
type WhistleCommandProjections = ReadonlySchemaValue<
  z.output<typeof WhistleCommandProjectionsSchema>
>;

Projection membership selected by a semantic command owner.

WhistleCommandDefinitiontype alias

Section titled “WhistleCommandDefinition”
Signature
type WhistleCommandDefinition = ReadonlySchemaValue<
  z.output<typeof WhistleCommandDefinitionSchema>
>;

Data-only command definition accepted at adapter boundaries.

WhistleAgentProjectionDatatype alias

Section titled “WhistleAgentProjectionData”
Signature
type WhistleAgentProjectionData = z.output<typeof WhistleAgentProjectionSchema>;

Decoded agent projection data as received across the wire.

WhistlePrompttype alias

Section titled “WhistlePrompt”
Signature
type WhistlePrompt = ReadonlySchemaValue<z.output<typeof WhistlePromptSchema>>;

A renderer-neutral interaction prompt.

WhistlePromptOptiontype alias

Section titled “WhistlePromptOption”
Signature
type WhistlePromptOption = NonNullable<
  Extract<
    WhistlePrompt,
    {
      type: "choice";
    }
  >["options"][number]
>;

One selectable value in a parsed interaction prompt.

WhistleNoticetype alias

Section titled “WhistleNotice”
Signature
type WhistleNotice = ReadonlySchemaValue<z.output<typeof WhistleNoticeSchema>>;

A renderer-neutral interaction notice.

Section titled “WhistleNoticeLink”
Signature
type WhistleNoticeLink = ReadonlySchemaValue<
  NonNullable<
    Extract<
      z.output<typeof WhistleNoticeSchema>,
      {
        type: "info";
      }
    >["links"]
  >[number]
>;

One link included in a parsed informational notice.

WhistleDecisionAnswertype alias

Section titled “WhistleDecisionAnswer”
Signature
type WhistleDecisionAnswer = object;

The answer to a decision prompt: picked option values and/or written text.

Properties

Section titled “Properties”

selected

Section titled “selected”
Signature
selected: string[];

text?

Section titled “text?”
Signature
optional text?: string;

WhistleAnswerValuetype alias

Section titled “WhistleAnswerValue”
Signature
type WhistleAnswerValue = string | boolean | WhistleDecisionAnswer;

Every value a renderer may hand back as the answer to a prompt.

WhistlePromptAnswerstype alias

Section titled “WhistlePromptAnswers”
Signature
type WhistlePromptAnswers = object;

Answer types owned by the closed prompt vocabulary.

Properties

Section titled “Properties”

confirmation

Section titled “confirmation”
Signature
confirmation: boolean;

text

Section titled “text”
Signature
text: string;

choice

Section titled “choice”
Signature
choice: string;

decision

Section titled “decision”
Signature
decision: WhistleDecisionAnswer;

WhistlePromptOftype alias

Section titled “WhistlePromptOf”
Signature
type WhistlePromptOf<Kind> = {
  [K in Kind]: Extract<WhistlePrompt, { type: K }> & { type: K };
}[Kind];

A prompt and its discriminator remain correlated through generic dispatch.

Type Parameters

Section titled “Type Parameters”
Type Parameter
Kind extends WhistlePrompt["type"]

WhistleAvailabilitySchemaconstant

Section titled “WhistleAvailabilitySchema”
Signature
const WhistleAvailabilitySchema: ZodLazy<
  ZodDiscriminatedUnion<
    [
      ZodObject<
        {
          status: ZodLiteral<"available">;
        },
        $strict
      >,
      ZodObject<
        {
          status: ZodLiteral<"unavailable">;
          reason: ZodString;
        },
        $strict
      >,
    ],
    "status"
  >
>;

Host-owned availability carried by every discovered agent row.

WhistleJsonValueSchemaconstant

Section titled “WhistleJsonValueSchema”
Signature
const WhistleJsonValueSchema: ZodJSONSchema = json;

The JSON value grammar shared by Whistle transports and App adapters.

WhistleJsonObjectSchemaconstant

Section titled “WhistleJsonObjectSchema”
Signature
const WhistleJsonObjectSchema: ZodLazy<ZodRecord<ZodString, ZodJSONSchema>>;

One JSON object, used for action schemas and custom presentation data.

parseJsonValueconstant

Section titled “parseJsonValue”
Signature
const parseJsonValue: typeof WhistleJsonValueSchema.parse;

Parse copied JSON data at an untrusted transport boundary.

parseJsonObjectconstant

Section titled “parseJsonObject”
Signature
const parseJsonObject: typeof WhistleJsonObjectSchema.parse;

Parse a copied JSON object at an untrusted transport boundary.

WhistleFailureSchemaconstant

Section titled “WhistleFailureSchema”
Signature
const WhistleFailureSchema: ZodLazy<
  ZodObject<
    {
      code: ZodString;
      message: ZodString;
      details: ZodOptional<ZodJSONSchema>;
    },
    $strict
  >
>;

General portable failure data for adapters that cross a transport.

parseFailureconstant

Section titled “parseFailure”
Signature
const parseFailure: typeof WhistleFailureSchema.parse;

Parse failure data without carrying an Error or stack across the wire.

WhistleActionSchemaSchemaconstant

Section titled “WhistleActionSchemaSchema”
Signature
const WhistleActionSchemaSchema: ZodLazy<ZodRecord<ZodString, ZodJSONSchema>> =
  WhistleJsonObjectSchema;

The JSON object shape used by Whistle action schemas.

WhistleActionPresentationSchemaconstant

Section titled “WhistleActionPresentationSchema”
Signature
const WhistleActionPresentationSchema: ZodLazy<
  ZodUnion<
    readonly [
      ZodObject<
        {
          type: ZodLiteral<"action">;
        },
        $strict
      >,
      ZodObject<
        {
          type: ZodLiteral<"custom">;
          data: ZodLazy<ZodRecord<ZodString, ZodJSONSchema>>;
        },
        $strict
      >,
      ZodObject<
        {
          type: ZodLiteral<"choice">;
          options: ZodArray<
            ZodObject<
              {
                value: ZodJSONSchema;
                label: ZodLazy<ZodString>;
                description: ZodOptional<ZodLazy<ZodString>>;
              },
              $strip
            >
          >;
        },
        $strict
      >,
      ZodObject<
        {
          type: ZodLiteral<"form">;
          submitLabel: ZodOptional<ZodLazy<ZodString>>;
        },
        $strict
      >,
      ZodObject<
        {
          type: ZodLiteral<"confirmation">;
          message: ZodLazy<ZodString>;
          confirmLabel: ZodOptional<ZodLazy<ZodString>>;
          cancelLabel: ZodOptional<ZodLazy<ZodString>>;
        },
        $strict
      >,
    ]
  >
>;

Validate renderer-neutral presentation data attached to an action.

WhistleActionDataSchemaconstant

Section titled “WhistleActionDataSchema”
Signature
const WhistleActionDataSchema: ZodLazy<ZodObject<{
  inputSchema: ZodOptional<ZodLazy<ZodRecord<ZodString, ZodJSONSchema>>>;
  outputSchema: ZodOptional<ZodLazy<ZodRecord<ZodString, ZodJSONSchema>>>;
  presentation: ZodOptional<ZodLazy<ZodUnion<readonly [ZodObject<{
     type: ZodLiteral<"action">;
   }, $strict>, ZodObject<{
     type: ZodLiteral<"custom">;
     data: ZodLazy<ZodRecord<..., ...>>;
   }, $strict>, ZodObject<{
     type: ZodLiteral<"choice">;
     options: ZodArray<ZodObject<..., ...>>;
   }, $strict>, ZodObject<{
     type: ZodLiteral<"form">;
     submitLabel: ZodOptional<ZodLazy<...>>;
   }, $strict>, ZodObject<{
     type: ZodLiteral<"confirmation">;
     message: ZodLazy<ZodString>;
     confirmLabel: ZodOptional<ZodLazy<...>>;
     cancelLabel: ZodOptional<ZodLazy<...>>;
  }, $strict>]>>>;
}, $strict>>;

Validate the serializable action contract carried by a command.

WhistleSlashArgumentsSchemaconstant

Section titled “WhistleSlashArgumentsSchema”
Signature
const WhistleSlashArgumentsSchema: ZodLazy<
  ZodObject<
    {
      hint: ZodPipe<ZodLazy<ZodString>, ZodString>;
      words: ZodOptional<
        ZodArray<
          ZodObject<
            {
              word: ZodString;
              description: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
              arguments: ZodLazy<ZodRecord<ZodString, ZodJSONSchema>>;
            },
            $strict
          >
        >
      >;
      text: ZodOptional<
        ZodObject<
          {
            field: ZodPipe<ZodLazy<ZodString>, ZodString>;
            arguments: ZodLazy<ZodRecord<ZodString, ZodJSONSchema>>;
            requestIdField: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
          },
          $strict
        >
      >;
    },
    $strict
  >
>;

Validate aliases and argument mapping metadata for slash commands.

WhistleCommandProjectionsSchemaconstant

Section titled “WhistleCommandProjectionsSchema”
Signature
const WhistleCommandProjectionsSchema: ZodLazy<ZodObject<{
  bindings: ZodOptional<ZodObject<{
     order: ZodOptional<ZodLazy<ZodNumber>>;
     values: ZodArray<ZodLazy<ZodString>>;
  }, $strict>>;
  agent: ZodOptional<ZodObject<{
     keybind: ZodOptional<ZodLazy<ZodString>>;
     order: ZodOptional<ZodLazy<ZodNumber>>;
  }, $strict>>;
  help: ZodOptional<ZodLazy<ZodObject<{
     order: ZodOptional<ZodLazy<ZodNumber>>;
  }, $strict>>>;
  menu: ZodOptional<ZodLazy<ZodObject<{
     order: ZodOptional<ZodLazy<ZodNumber>>;
  }, $strict>>>;
  palette: ZodOptional<ZodLazy<ZodObject<{
     order: ZodOptional<ZodLazy<ZodNumber>>;
  }, $strict>>>;
  slash: ZodOptional<ZodObject<{
     aliases: ZodArray<ZodLazy<ZodString>>;
     consumesDraft: ZodOptional<ZodBoolean>;
     order: ZodOptional<ZodLazy<ZodNumber>>;
     arguments: ZodOptional<ZodLazy<ZodObject<{
        hint: ZodPipe<..., ...>;
        words: ZodOptional<...>;
        text: ZodOptional<...>;
     }, $strict>>>;
  }, $strict>>;
}, $strict>>;

Validate explicit membership and ordering across Whistle surfaces.

WhistleCommandDefinitionSchemaconstant

Section titled “WhistleCommandDefinitionSchema”
Signature
const WhistleCommandDefinitionSchema: ZodLazy<ZodObject<{
  id: ZodLazy<ZodString>;
  title: ZodLazy<ZodString>;
  category: ZodLazy<ZodString>;
  description: ZodOptional<ZodLazy<ZodString>>;
  projections: ZodOptional<ZodLazy<ZodObject<{
     bindings: ZodOptional<ZodObject<{
        order: ZodOptional<...>;
        values: ZodArray<...>;
     }, $strict>>;
     agent: ZodOptional<ZodObject<{
        keybind: ZodOptional<...>;
        order: ZodOptional<...>;
     }, $strict>>;
     help: ZodOptional<ZodLazy<ZodObject<{
        order: ...;
     }, $strict>>>;
     menu: ZodOptional<ZodLazy<ZodObject<{
        order: ...;
     }, $strict>>>;
     palette: ZodOptional<ZodLazy<ZodObject<{
        order: ...;
     }, $strict>>>;
     slash: ZodOptional<ZodObject<{
        aliases: ZodArray<...>;
        consumesDraft: ZodOptional<...>;
        order: ZodOptional<...>;
        arguments: ZodOptional<...>;
     }, $strict>>;
  }, $strict>>>;
  action: ZodOptional<ZodLazy<ZodObject<{
     inputSchema: ZodOptional<ZodLazy<ZodRecord<ZodString, ZodJSONSchema>>>;
     outputSchema: ZodOptional<ZodLazy<ZodRecord<ZodString, ZodJSONSchema>>>;
     presentation: ZodOptional<ZodLazy<ZodUnion<readonly [..., ..., ..., ..., ...]>>>;
  }, $strict>>>;
  availability: ZodOptional<ZodLazy<ZodDiscriminatedUnion<[ZodObject<{
     status: ZodLiteral<"available">;
   }, $strict>, ZodObject<{
     status: ZodLiteral<"unavailable">;
     reason: ZodString;
  }, $strict>], "status">>>;
}, $strict>>;

Validate data-only command definitions supplied by an adapter.

parseActionconstant

Section titled “parseAction”
Signature
const parseAction: typeof WhistleActionDataSchema.parse;

Parse action metadata once before an adapter constructs a Whistle command.

parseProjectionsconstant

Section titled “parseProjections”
Signature
const parseProjections: typeof WhistleCommandProjectionsSchema.parse;

Parse the Whistle-owned projection metadata supplied by an App.

parseAvailabilityconstant

Section titled “parseAvailability”
Signature
const parseAvailability: typeof availabilitySchema.parse;

Parse an availability fact while preserving its reason.

parseCommandDefinitionconstant

Section titled “parseCommandDefinition”
Signature
const parseCommandDefinition: typeof WhistleCommandDefinitionSchema.parse;

Parse one data-only command definition before an adapter creates a command.

WhistleAgentProjectionSchemaconstant

Section titled “WhistleAgentProjectionSchema”
Signature
const WhistleAgentProjectionSchema: ZodLazy<
  ZodObject<
    {
      commandId: ZodString;
      sourceId: ZodString;
      scope: ZodOptional<ZodString>;
      title: ZodString;
      category: ZodString;
      description: ZodOptional<ZodString>;
      order: ZodNumber;
      availability: ZodLazy<
        ZodDiscriminatedUnion<
          [
            ZodObject<
              {
                status: ZodLiteral<"available">;
              },
              $strict
            >,
            ZodObject<
              {
                status: ZodLiteral<"unavailable">;
                reason: ZodString;
              },
              $strict
            >,
          ],
          "status"
        >
      >;
      action: ZodOptional<
        ZodLazy<
          ZodObject<
            {
              inputSchema: ZodOptional<
                ZodLazy<ZodRecord<ZodString, ZodJSONSchema>>
              >;
              outputSchema: ZodOptional<
                ZodLazy<ZodRecord<ZodString, ZodJSONSchema>>
              >;
            },
            $strict
          >
        >
      >;
      keybind: ZodOptional<ZodString>;
    },
    $strict
  >
>;

One neutral agent row emitted by Whistle’s snapshot.agent projection.

WhistleAgentProjectionsSchemaconstant

Section titled “WhistleAgentProjectionsSchema”
Signature
const WhistleAgentProjectionsSchema: ZodArray<ZodLazy<ZodObject<{
  commandId: ZodString;
  sourceId: ZodString;
  scope: ZodOptional<ZodString>;
  title: ZodString;
  category: ZodString;
  description: ZodOptional<ZodString>;
  order: ZodNumber;
  availability: ZodLazy<ZodDiscriminatedUnion<[ZodObject<{
     status: ZodLiteral<"available">;
   }, $strict>, ZodObject<{
     status: ZodLiteral<"unavailable">;
     reason: ZodString;
  }, $strict>], "status">>;
  action: ZodOptional<ZodLazy<ZodObject<{
     inputSchema: ZodOptional<ZodLazy<ZodRecord<..., ...>>>;
     outputSchema: ZodOptional<ZodLazy<ZodRecord<..., ...>>>;
  }, $strict>>>;
  keybind: ZodOptional<ZodString>;
}, $strict>>>;

A neutral Whistle agent projection collection.

parseconstant

Section titled “parse”
Signature
const parse: typeof WhistleAgentProjectionsSchema.parse;

Decode an untrusted agent projection collection at the wire boundary.

interactionTextLimitconstant

Section titled “interactionTextLimit”
Signature
const interactionTextLimit: 8192 = 8192;

Longest prompt answer or message an interaction carries.

interactionTitleLimitconstant

Section titled “interactionTitleLimit”
Signature
const interactionTitleLimit: 60 = 60;

A modal title: human words, short enough to read at a glance.

WhistlePromptSchemaconstant

Section titled “WhistlePromptSchema”
Signature
const WhistlePromptSchema: ZodDiscriminatedUnion<
  [
    ZodObject<
      {
        summary: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
        facts: ZodOptional<
          ZodArray<
            ZodObject<
              {
                label: ZodPipe<ZodLazy<ZodString>, ZodString>;
                value: ZodPipe<ZodLazy<ZodString>, ZodString>;
              },
              $strict
            >
          >
        >;
        body: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
        bodyLabel: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
        details: ZodOptional<
          ZodArray<
            ZodObject<
              {
                label: ZodPipe<ZodLazy<ZodString>, ZodString>;
                value: ZodPipe<ZodLazy<ZodString>, ZodString>;
              },
              $strict
            >
          >
        >;
        type: ZodLiteral<"choice">;
        message: ZodPipe<ZodLazy<ZodString>, ZodString>;
        current: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
        collapsedGroup: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
        options: ZodArray<
          ZodObject<
            {
              value: ZodPipe<ZodLazy<ZodString>, ZodString>;
              label: ZodPipe<ZodLazy<ZodString>, ZodString>;
              description: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
              group: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
              destructive: ZodOptional<ZodLiteral<true>>;
            },
            $strict
          >
        >;
      },
      $strict
    >,
    ZodObject<
      {
        summary: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
        facts: ZodOptional<
          ZodArray<
            ZodObject<
              {
                label: ZodPipe<ZodLazy<ZodString>, ZodString>;
                value: ZodPipe<ZodLazy<ZodString>, ZodString>;
              },
              $strict
            >
          >
        >;
        body: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
        bodyLabel: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
        details: ZodOptional<
          ZodArray<
            ZodObject<
              {
                label: ZodPipe<ZodLazy<ZodString>, ZodString>;
                value: ZodPipe<ZodLazy<ZodString>, ZodString>;
              },
              $strict
            >
          >
        >;
        type: ZodLiteral<"text">;
        message: ZodPipe<ZodLazy<ZodString>, ZodString>;
        placeholder: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
        secret: ZodOptional<ZodBoolean>;
      },
      $strict
    >,
    ZodObject<
      {
        summary: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
        facts: ZodOptional<
          ZodArray<
            ZodObject<
              {
                label: ZodPipe<ZodLazy<ZodString>, ZodString>;
                value: ZodPipe<ZodLazy<ZodString>, ZodString>;
              },
              $strict
            >
          >
        >;
        body: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
        bodyLabel: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
        details: ZodOptional<
          ZodArray<
            ZodObject<
              {
                label: ZodPipe<ZodLazy<ZodString>, ZodString>;
                value: ZodPipe<ZodLazy<ZodString>, ZodString>;
              },
              $strict
            >
          >
        >;
        type: ZodLiteral<"confirmation">;
        message: ZodPipe<ZodLazy<ZodString>, ZodString>;
        confirmLabel: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
        cancelLabel: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
        destructive: ZodOptional<ZodLiteral<true>>;
      },
      $strict
    >,
    ZodObject<
      {
        summary: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
        facts: ZodOptional<
          ZodArray<
            ZodObject<
              {
                label: ZodPipe<ZodLazy<ZodString>, ZodString>;
                value: ZodPipe<ZodLazy<ZodString>, ZodString>;
              },
              $strict
            >
          >
        >;
        body: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
        bodyLabel: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
        details: ZodOptional<
          ZodArray<
            ZodObject<
              {
                label: ZodPipe<ZodLazy<ZodString>, ZodString>;
                value: ZodPipe<ZodLazy<ZodString>, ZodString>;
              },
              $strict
            >
          >
        >;
        type: ZodLiteral<"decision">;
        message: ZodPipe<ZodLazy<ZodString>, ZodString>;
        options: ZodArray<
          ZodObject<
            {
              value: ZodPipe<ZodLazy<ZodString>, ZodString>;
              label: ZodPipe<ZodLazy<ZodString>, ZodString>;
              description: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
              destructive: ZodOptional<ZodLiteral<true>>;
            },
            $strict
          >
        >;
        multiple: ZodOptional<ZodBoolean>;
        other: ZodOptional<
          ZodObject<
            {
              label: ZodPipe<ZodLazy<ZodString>, ZodString>;
              placeholder: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
              maxLength: ZodNumber;
              blank: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
            },
            $strict
          >
        >;
        escape: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
      },
      $strict
    >,
  ],
  "type"
>;

Validate renderer-neutral interaction prompts received from a host.

WhistleNoticeSchemaconstant

Section titled “WhistleNoticeSchema”
Signature
const WhistleNoticeSchema: ZodLazy<ZodDiscriminatedUnion<[ZodObject<{
  type: ZodLiteral<"info">;
  message: ZodPipe<ZodLazy<ZodString>, ZodString>;
  links: ZodOptional<ZodArray<ZodObject<{
     url: ZodURL;
     label: ZodOptional<ZodPipe<..., ...>>;
  }, $strict>>>;
}, $strict>, ZodObject<{
  type: ZodLiteral<"progress">;
  message: ZodPipe<ZodLazy<ZodString>, ZodString>;
}, $strict>, ZodObject<{
  type: ZodLiteral<"handoff">;
  url: ZodURL;
  code: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
  message: ZodOptional<ZodPipe<ZodLazy<ZodString>, ZodString>>;
}, $strict>, ZodObject<{
  type: ZodLiteral<"success">;
  message: ZodPipe<ZodLazy<ZodString>, ZodString>;
}, $strict>], "type">>;

Validate interaction notices received from a host.

parsePromptconstant

Section titled “parsePrompt”
Signature
const parsePrompt: typeof WhistlePromptSchema.parse;

Parse one interaction prompt at the boundary where a client renders it.

parseNoticeconstant

Section titled “parseNotice”
Signature
const parseNotice: typeof WhistleNoticeSchema.parse;

Parse one interaction notice at the boundary where a client renders it.

createPromptAnswerParser()function

Section titled “createPromptAnswerParser()”
Signature
function createPromptAnswerParser<Kind>(
  prompt,
): (value) => WhistlePromptAnswers[Kind];

Capture a prompt’s parsed answer contract before handing it to a renderer.

Type Parameters

Section titled “Type Parameters”
Type Parameter
Kind extends "text" | "choice" | "confirmation" | "decision"

Parameters

Section titled “Parameters”
Parameter Type
prompt WhistlePromptOf<Kind>

Returns

Section titled “Returns”

(value) => WhistlePromptAnswers[Kind]

parsePromptAnswer()function

Section titled “parsePromptAnswer()”
Signature
function parsePromptAnswer<Kind>(prompt, value): WhistlePromptAnswers[Kind];

Parse the answer a human gave to one prompt before the command sees it.

Type Parameters

Section titled “Type Parameters”
Type Parameter
Kind extends "text" | "choice" | "confirmation" | "decision"

Parameters

Section titled “Parameters”
Parameter Type
prompt WhistlePromptOf<Kind>
value WhistleAnswerValue

Returns

Section titled “Returns”

WhistlePromptAnswers[Kind]

createPromptAnswerDecoder()function

Section titled “createPromptAnswerDecoder()”
Signature
function createPromptAnswerDecoder<Kind>(prompt): (value) =>
  | Readonly<{
      kind: "accepted";
      value: WhistlePromptAnswers[Kind];
    }>
  | Readonly<{
      kind: "invalid";
      cause: ZodError;
    }>;

Capture a typed answer decoder; invalid input stays an explicit outcome.

Type Parameters

Section titled “Type Parameters”
Type Parameter
Kind extends "text" | "choice" | "confirmation" | "decision"

Parameters

Section titled “Parameters”
Parameter Type
prompt WhistlePromptOf<Kind>

Returns

Section titled “Returns”

(value) => | Readonly<{ kind: "accepted"; value: WhistlePromptAnswers[Kind]; }> | Readonly<{ kind: "invalid"; cause: ZodError; }>

decodePromptAnswer()function

Section titled “decodePromptAnswer()”
Signature
function decodePromptAnswer<Kind>(
  prompt,
  value,
):
  | Readonly<{
      kind: "invalid";
      cause: ZodError;
    }>
  | Readonly<{
      kind: "accepted";
      value: WhistlePromptAnswers[Kind];
    }>;

Decode a human answer without throwing so renderers can handle invalid input.

Type Parameters

Section titled “Type Parameters”
Type Parameter
Kind extends "text" | "choice" | "confirmation" | "decision"

Parameters

Section titled “Parameters”
Parameter Type
prompt WhistlePromptOf<Kind>
value WhistleAnswerValue

Returns

Section titled “Returns”

| Readonly<{ kind: "invalid"; cause: ZodError; }> | Readonly<{ kind: "accepted"; value: WhistlePromptAnswers[Kind]; }>