Skip to content
Mule0.2.1
API reference

mule

Import

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

Exports

Section titled “Exports”
Kind Export Description
type alias MuleStreamFunction Pi’s model stream function, supplied explicitly by the caller.
type alias MuleIdentityKind Causal roles added around Pi’s model and tool loop.
type alias MuleIdentity One run-local causal identity.
type alias MuleError Expected failure from Mule’s model, tool, control, or listener work.
type alias MuleToolResult Result produced by a tool before Mule forms Pi’s correlated result message.
type alias MuleToolExecutionPart Progress or terminal output from one tool execution.
type alias MuleToolRejection A real parser or authorization rejection produced before tool execution.
type alias MuleCompletedTurn Facts from a completed Pi turn supplied to the retained stop hook.
type alias MuleEvent Lifecycle emitted around Pi values. Pi messages and events are not rewritten.
type alias MuleToolCheckpoint Durable evidence for a call in an interrupted assistant turn.
type alias MuleResume Completed assistant turn recovered by the transcript owner, before its next model call.
type alias MuleRunSettings Run inputs that are identical on the Promise and Effect roots.
type alias MuleRunOutcome Honest terminal result of one Mule invocation.
type alias MulePromiseListener Promise listener adapted once into Mule’s canonical Effect program.
type alias MuleToolPreparation Outcome of preparing one exact Pi tool call.
type alias MuleTool Pi tool declaration paired with its Promise preparation door.
type alias MuleRunInput Inputs for one complete Pi model/tool loop through the Promise facade.
type alias Mule Promise-facing Mule interface.
type alias ProviderRejection Bounded provider evidence, never response bodies, headers or error prose.
type alias ProviderStatusRecorder One provider call’s transport and parsed-event observations.
constant mule Default Promise-facing Mule interface.
constant streamModel Pi’s maintained stream behind Mule’s structural provider port.
function decodeProviderData() Decode Pi’s parsed request/event data before it enters an owned hook.
function normalizeModel() Validate a catalog model’s opaque sampling fields before it enters Mule.
function isRetryableProviderRejection() Retry only typed transient failures, never usage exhaustion or rejection.
function observeProviderStatus() Observe one call’s typed HTTP and parsed-event evidence. Pi owns stream decoding; this module retains no provider prose.

MuleStreamFunctiontype alias

Section titled “MuleStreamFunction”
Signature
type MuleStreamFunction = (
  model,
  context,
  options?,
) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;

Pi’s model stream function, supplied explicitly by the caller.

Parameters

Section titled “Parameters”
Parameter Type
model Model<Api>
context Context
options? SimpleStreamOptions

Returns

Section titled “Returns”

| AssistantMessageEventStream | Promise<AssistantMessageEventStream>

MuleIdentityKindtype alias

Section titled “MuleIdentityKind”
Signature
type MuleIdentityKind =
  "run" | "turn" | "message" | "tool_call" | "tool_result" | "terminal";

Causal roles added around Pi’s model and tool loop.

MuleIdentitytype alias

Section titled “MuleIdentity”
Signature
type MuleIdentity = object;

One run-local causal identity.

Properties

Section titled “Properties”

kind

Section titled “kind”
Signature
readonly kind: MuleIdentityKind;

value

Section titled “value”
Signature
readonly value: string;

parent?

Section titled “parent?”
Signature
readonly optional parent?: MuleIdentity;

MuleErrortype alias

Section titled “MuleError”
Signature
type MuleError = object;

Expected failure from Mule’s model, tool, control, or listener work.

Properties

Section titled “Properties”

_tag

Section titled “_tag”
Signature
readonly _tag: "MuleError";

phase

Section titled “phase”
Signature
readonly phase: "model" | "tool" | "control" | "listener";

message

Section titled “message”
Signature
readonly message: string;

cause?

Section titled “cause?”
Signature
readonly optional cause?: unknown;

The underlying rejection or thrown value, when one exists.

MuleToolResulttype alias

Section titled “MuleToolResult”
Signature
type MuleToolResult = object;

Result produced by a tool before Mule forms Pi’s correlated result message.

Properties

Section titled “Properties”

content

Section titled “content”
Signature
readonly content: (
  | TextContent
  | ImageContent)[];

data?

Section titled “data?”
Signature
readonly optional data?: JsonValue;

Application payload for listeners, never part of a model message.

usage?

Section titled “usage?”
Signature
readonly optional usage?: Usage;

isError

Section titled “isError”
Signature
readonly isError: boolean;

terminate?

Section titled “terminate?”
Signature
readonly optional terminate?: boolean;

MuleToolExecutionParttype alias

Section titled “MuleToolExecutionPart”
Signature
type MuleToolExecutionPart =
  | {
      type: "update";
      result: MuleToolResult;
    }
  | {
      type: "result";
      result: MuleToolResult;
    };

Progress or terminal output from one tool execution.

MuleToolRejectiontype alias

Section titled “MuleToolRejection”
Signature
type MuleToolRejection = object;

A real parser or authorization rejection produced before tool execution.

Properties

Section titled “Properties”

message

Section titled “message”
Signature
readonly message: string;

terminate?

Section titled “terminate?”
Signature
readonly optional terminate?: boolean;

MuleCompletedTurntype alias

Section titled “MuleCompletedTurn”
Signature
type MuleCompletedTurn = object;

Facts from a completed Pi turn supplied to the retained stop hook.

Properties

Section titled “Properties”

message

Section titled “message”
Signature
readonly message: AssistantMessage;

toolResults

Section titled “toolResults”
Signature
readonly toolResults: readonly ToolResultMessage[];

context

Section titled “context”
Signature
readonly context: readonly Message[];

newMessages

Section titled “newMessages”
Signature
readonly newMessages: readonly Message[];

MuleEventtype alias

Section titled “MuleEvent”
Signature
type MuleEvent =
  | {
      type: "run_start";
      run: MuleIdentity;
    }
  | {
      type: "model_prompt";
      run: MuleIdentity;
      turn: MuleIdentity;
      attempt: number;
      systemPrompt: string;
    }
  | {
      type: "turn_start";
      run: MuleIdentity;
      turn: MuleIdentity;
    }
  | {
      type: "message_start";
      run: MuleIdentity;
      turn: MuleIdentity;
      message: MuleIdentity;
      value: Message;
    }
  | {
      type: "message_update";
      run: MuleIdentity;
      turn: MuleIdentity;
      message: MuleIdentity;
      value: AssistantMessage;
      event: AssistantMessageEvent;
    }
  | {
      type: "message_end";
      run: MuleIdentity;
      turn: MuleIdentity;
      message: MuleIdentity;
      value: Message;
      data?: JsonValue;
    }
  | {
      type: "tool_execution_start";
      replay: "safe" | "unsafe";
      run: MuleIdentity;
      turn: MuleIdentity;
      toolCall: MuleIdentity;
      call: ToolCall;
    }
  | {
      type: "tool_execution_update";
      run: MuleIdentity;
      turn: MuleIdentity;
      toolCall: MuleIdentity;
      call: ToolCall;
      result: MuleToolResult;
    }
  | {
      type: "tool_execution_end";
      run: MuleIdentity;
      turn: MuleIdentity;
      toolCall: MuleIdentity;
      call: ToolCall;
      result: MuleToolResult;
    }
  | {
      type: "turn_end";
      run: MuleIdentity;
      turn: MuleIdentity;
      message: AssistantMessage;
      toolResults: readonly ToolResultMessage[];
    }
  | {
      type: "run_end";
      run: MuleIdentity;
      terminal: MuleIdentity;
      outcome: "completed" | "cancelled" | "failed";
    };

Lifecycle emitted around Pi values. Pi messages and events are not rewritten.

Union Members

Section titled “Union Members”

Type Literal

Section titled “Type Literal”
Signature
{
  type: "run_start";
  run: MuleIdentity;
}

Type Literal

Section titled “Type Literal”
Signature
{
  type: "model_prompt";
  run: MuleIdentity;
  turn: MuleIdentity;
  attempt: number;
  systemPrompt: string;
}
Name Type Description
type "model_prompt" Exact prompt sent on this model attempt, including after a retry.
run MuleIdentity -
turn MuleIdentity -
attempt number -
systemPrompt string -

Type Literal

Section titled “Type Literal”
Signature
{
  type: "turn_start";
  run: MuleIdentity;
  turn: MuleIdentity;
}

Type Literal

Section titled “Type Literal”
Signature
{
  type: "message_start";
  run: MuleIdentity;
  turn: MuleIdentity;
  message: MuleIdentity;
  value: Message;
}

Type Literal

Section titled “Type Literal”
Signature
{
  type: "message_update";
  run: MuleIdentity;
  turn: MuleIdentity;
  message: MuleIdentity;
  value: AssistantMessage;
  event: AssistantMessageEvent;
}

Type Literal

Section titled “Type Literal”
Signature
{
  type: "message_end";
  run: MuleIdentity;
  turn: MuleIdentity;
  message: MuleIdentity;
  value: Message;
  data?: JsonValue;
}
Name Type Description
type "message_end" -
run MuleIdentity -
turn MuleIdentity -
message MuleIdentity -
value Message -
data? JsonValue Application payload independent of the completed model message.

Type Literal

Section titled “Type Literal”
Signature
{
  type: "tool_execution_start";
  replay: "safe" | "unsafe";
  run: MuleIdentity;
  turn: MuleIdentity;
  toolCall: MuleIdentity;
  call: ToolCall;
}

Type Literal

Section titled “Type Literal”
Signature
{
  type: "tool_execution_update";
  run: MuleIdentity;
  turn: MuleIdentity;
  toolCall: MuleIdentity;
  call: ToolCall;
  result: MuleToolResult;
}

Type Literal

Section titled “Type Literal”
Signature
{
  type: "tool_execution_end";
  run: MuleIdentity;
  turn: MuleIdentity;
  toolCall: MuleIdentity;
  call: ToolCall;
  result: MuleToolResult;
}

Type Literal

Section titled “Type Literal”
Signature
{
  type: "turn_end";
  run: MuleIdentity;
  turn: MuleIdentity;
  message: AssistantMessage;
  toolResults: readonly ToolResultMessage[];
}

Type Literal

Section titled “Type Literal”
Signature
{
  type: "run_end";
  run: MuleIdentity;
  terminal: MuleIdentity;
  outcome: "completed" | "cancelled" | "failed";
}
Name Type Description
type "run_end" The run’s one terminal. A run interrupted after run_start ends cancelled; a run that fails with a non-listener MuleError ends failed. A listener failure ends the run without this event.
run MuleIdentity -
terminal MuleIdentity -
outcome "completed" | "cancelled" | "failed" -

MuleToolCheckpointtype alias

Section titled “MuleToolCheckpoint”
Signature
type MuleToolCheckpoint =
  | {
      call: ToolCall;
      state: "pending";
    }
  | {
      call: ToolCall;
      state: "started";
      replay: "safe" | "unsafe";
    }
  | {
      call: ToolCall;
      state: "completed";
      result: MuleToolResult;
      message?: ToolResultMessage;
    };

Durable evidence for a call in an interrupted assistant turn.

Union Members

Section titled “Union Members”

Type Literal

Section titled “Type Literal”
Signature
{
  call: ToolCall;
  state: "pending";
}

Type Literal

Section titled “Type Literal”
Signature
{
  call: ToolCall;
  state: "started";
  replay: "safe" | "unsafe";
}

Type Literal

Section titled “Type Literal”
Signature
{
  call: ToolCall;
  state: "completed";
  result: MuleToolResult;
  message?: ToolResultMessage;
}
Name Type Description
call ToolCall -
state "completed" -
result MuleToolResult -
message? ToolResultMessage Present when the transcript message was committed too.

MuleResumetype alias

Section titled “MuleResume”
Signature
type MuleResume = object;

Completed assistant turn recovered by the transcript owner, before its next model call.

Properties

Section titled “Properties”

message

Section titled “message”
Signature
readonly message: AssistantMessage;

tools

Section titled “tools”
Signature
readonly tools: readonly MuleToolCheckpoint[];

MuleRunSettingstype alias

Section titled “MuleRunSettings”
Signature
type MuleRunSettings = object;

Run inputs that are identical on the Promise and Effect roots.

Properties

Section titled “Properties”

model

Section titled “model”
Signature
readonly model: Model<Api>;

stream?

Section titled “stream?”
Signature
readonly optional stream?: MuleStreamFunction;

Override Pi’s default streamSimple, primarily for explicit providers and tests.

systemPrompt

Section titled “systemPrompt”
Signature
readonly systemPrompt: string;

messages

Section titled “messages”
Signature
readonly messages: readonly Message[];

resume?

Section titled “resume?”
Signature
readonly optional resume?: MuleResume;

Continue a durable, completed assistant turn before requesting another response.

streamOptions?

Section titled “streamOptions?”
Signature
readonly optional streamOptions?: Omit<SimpleStreamOptions, "signal" | "maxRetries">;

Provider-native retries are disabled; the typed host policy owns retry.

modelStreamIdleTimeoutMs?

Section titled “modelStreamIdleTimeoutMs?”
Signature
readonly optional modelStreamIdleTimeoutMs?: number;

Maximum silence between provider stream events, in milliseconds.

modelStreamLimits?

Section titled “modelStreamLimits?”
Signature
readonly optional modelStreamLimits?: Partial<{
  firstEventMs: number;
  attemptMs: number;
  outputBytes: number;
}>;

Trusted per-attempt safety limits may only tighten Mule’s defaults.

toolExecution?

Section titled “toolExecution?”
Signature
readonly optional toolExecution?: "parallel" | "sequential";

retry?

Section titled “retry?”
Signature
readonly optional retry?: RetryPolicy;

Bounded retry around each assistant call, using Pi’s exponential delay. Undefined means no retry, matching pi-ai’s own default. Hosts that want Pi coding-agent’s numbers pass piCodingAgentRetryDefaults. Enabled policy counts and delays must be non-negative safe integers. Each assistant turn captures its policy before requesting the model.

retryable

Section titled “retryable”
Signature
readonly retryable: (message) => boolean;

Host-owned typed decision for this exact assistant message. Only true permits retry; unknown messages return false, never a decision from prose.

Parameters
Section titled “Parameters”
Parameter Type
message AssistantMessage
Returns
Section titled “Returns”

boolean

retryAfterMs?

Section titled “retryAfterMs?”
Signature
readonly optional retryAfterMs?: (message) => number | undefined;

Provider’s bounded Retry-After evidence for the last assistant error.

Parameters
Section titled “Parameters”
Parameter Type
message AssistantMessage
Returns
Section titled “Returns”

number | undefined

MuleRunOutcometype alias

Section titled “MuleRunOutcome”
Signature
type MuleRunOutcome = object;

Honest terminal result of one Mule invocation.

Properties

Section titled “Properties”

status

Section titled “status”
Signature
readonly status: "completed" | "cancelled" | "failed";

run

Section titled “run”
Signature
readonly run: MuleIdentity;

terminal

Section titled “terminal”
Signature
readonly terminal: MuleIdentity;

message

Section titled “message”
Signature
readonly message: AssistantMessage;

messages

Section titled “messages”
Signature
readonly messages: readonly Message[];

modelLimitReason?

Section titled “modelLimitReason?”
Signature
readonly optional modelLimitReason?: string;

Mule-owned limit diagnostic, not untrusted provider prose.

MulePromiseListenertype alias

Section titled “MulePromiseListener”
Signature
type MulePromiseListener = (event, signal) => Promise<void> | void;

Promise listener adapted once into Mule’s canonical Effect program.

Parameters

Section titled “Parameters”
Parameter Type
event MuleEvent
signal AbortSignal

Returns

Section titled “Returns”

Promise<void> | void

MuleToolPreparationtype alias

Section titled “MuleToolPreparation”
Signature
type MuleToolPreparation =
  | {
      status: "prepared";
      execute: (signal) => AsyncIterable<MuleToolExecutionPart>;
    }
  | (object & MuleToolRejection);

Outcome of preparing one exact Pi tool call.

Union Members

Section titled “Union Members”

Type Literal

Section titled “Type Literal”
Signature
{
  status: "prepared";
  execute: (signal) => AsyncIterable<MuleToolExecutionPart>;
}
Name Type Description
status "prepared" -
execute() (signal) => AsyncIterable<MuleToolExecutionPart> Run the already-decoded and authorized call; abort ends it early.

object & MuleToolRejection

MuleTooltype alias

Section titled “MuleTool”
Signature
type MuleTool = object;

Pi tool declaration paired with its Promise preparation door.

Properties

Section titled “Properties”

descriptor

Section titled “descriptor”
Signature
readonly descriptor: Tool;

replay?

Section titled “replay?”
Signature
readonly optional replay?: "safe" | "unsafe";

Only read-only or explicitly idempotent tools may opt into crash replay.

executionMode?

Section titled “executionMode?”
Signature
readonly optional executionMode?: "parallel" | "sequential";

prepare

Section titled “prepare”
Signature
readonly prepare: (call, signal) => Promise<MuleToolPreparation>;

Decode and authorize one exact Pi tool call before it can execute.

Parameters
Section titled “Parameters”
Parameter Type
call ToolCall
signal AbortSignal
Returns
Section titled “Returns”

Promise<MuleToolPreparation>

MuleRunInputtype alias

Section titled “MuleRunInput”
Signature
type MuleRunInput = MuleRunSettings & object;

Inputs for one complete Pi model/tool loop through the Promise facade.

Type Declaration

Section titled “Type Declaration”
Name Type Description
tools? readonly MuleTool[] -
resolveApiKey()? (provider, signal) => Promise<string | undefined> Resolve a fresh provider credential immediately before each Pi call.
getSteeringMessages()? (signal) => Promise<readonly Message[]> Pull messages that should steer the active run at Pi’s safe point.
getFollowUpMessages()? (signal) => Promise<readonly Message[]> Pull messages queued until the run would otherwise finish.
shouldStopAfterTurn()? (turn, signal) => Promise<boolean> Request a graceful stop after the current Pi turn has fully settled.

Muletype alias

Section titled “Mule”
Signature
type Mule = object;

Promise-facing Mule interface.

Properties

Section titled “Properties”

run

Section titled “run”
Signature
readonly run: (input, listener?, signal?) => Promise<MuleRunOutcome>;

Run one complete Pi model/tool loop. Rejects with the MuleError that failed the run, or with the abort reason (an AbortError when the reason is not an Error) after the caller aborts signal.

Parameters
Section titled “Parameters”
Parameter Type
input MuleRunInput
listener? MulePromiseListener
signal? AbortSignal
Returns
Section titled “Returns”

Promise<MuleRunOutcome>

ProviderRejectiontype alias

Section titled “ProviderRejection”
Signature
type ProviderRejection =
  | Readonly<{
      code: "usage-limit-reached";
      resetAt?: number;
      limit?: "five_hour" | "seven_day" | "seven_day_opus" | "seven_day_sonnet";
    }>
  | Readonly<{
      code: "rate-limit";
      retryAfterMs?: number;
    }>
  | Readonly<{
      code: "overloaded";
    }>
  | Readonly<{
      code: "provider_unavailable";
      status?: number;
    }>
  | Readonly<{
      code: "provider_rejected";
      status: number;
    }>;

Bounded provider evidence, never response bodies, headers or error prose.

ProviderStatusRecordertype alias

Section titled “ProviderStatusRecorder”
Signature
type ProviderStatusRecorder = Readonly<{
  fetch: typeof globalThis.fetch;
  onProviderStreamEvent: NonNullable<
    SimpleStreamOptions["onProviderStreamEvent"]
  >;
  rejection: (message?) => ProviderRejection | undefined;
}>;

One provider call’s transport and parsed-event observations.

muleconstant

Section titled “mule”
Signature
const mule: Mule;

Default Promise-facing Mule interface.

streamModelconstant

Section titled “streamModel”
Signature
const streamModel: MuleStreamFunction;

Pi’s maintained stream behind Mule’s structural provider port.

decodeProviderData()function

Section titled “decodeProviderData()”
Signature
function decodeProviderData(data): ProviderData;

Decode Pi’s parsed request/event data before it enters an owned hook.

Parameters

Section titled “Parameters”
Parameter Type
data unknown

Returns

Section titled “Returns”

ProviderData

normalizeModel()function

Section titled “normalizeModel()”
Signature
function normalizeModel<TApi>(model): Model<TApi>;

Validate a catalog model’s opaque sampling fields before it enters Mule.

Type Parameters

Section titled “Type Parameters”
Type Parameter
TApi extends Api

Parameters

Section titled “Parameters”
Parameter Type
model Omit<Model<TApi>, "samplingParams" | "samplingParamsByThinkingLevel">

Returns

Section titled “Returns”

Model<TApi>

isRetryableProviderRejection()function

Section titled “isRetryableProviderRejection()”
Signature
function isRetryableProviderRejection(rejection): boolean;

Retry only typed transient failures, never usage exhaustion or rejection.

Parameters

Section titled “Parameters”
Parameter Type
rejection ProviderRejection | undefined

Returns

Section titled “Returns”

boolean

observeProviderStatus()function

Section titled “observeProviderStatus()”
Signature
function observeProviderStatus(options?): ProviderStatusRecorder;

Observe one call’s typed HTTP and parsed-event evidence. Pi owns stream decoding; this module retains no provider prose.

Parameters

Section titled “Parameters”
Parameter Type
options? Pick<SimpleStreamOptions, "onProviderStreamEvent" | "fetch">

Returns

Section titled “Returns”

ProviderStatusRecorder