@fungi.computer/mule

Type Aliases

MuleStreamFunction

MuleStreamFunction = (model, context, options?) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>>

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

Parameters

model

Model<Api>

context

TranscriptContext

options?

SimpleStreamOptions

Returns

AssistantMessageEventStream | Promise<AssistantMessageEventStream>

MuleIdentityKind

MuleIdentityKind = "run" | "turn" | "message" | "tool_call" | "tool_result" | "terminal"

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

MuleIdentity

MuleIdentity = object

One run-local causal identity.

Properties

kind

readonly kind: MuleIdentityKind

value

readonly value: string

parent?

readonly optional parent?: MuleIdentity

MuleError

MuleError = object

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

Properties

_tag

readonly _tag: "MuleError"

phase

readonly phase: "model" | "tool" | "control" | "listener"

message

readonly message: string

cause?

readonly optional cause?: unknown

The underlying rejection or thrown value, when one exists.

MuleToolResult

MuleToolResult = object

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

Properties

content

readonly content: (TextContent | ImageContent)[]

details?

readonly optional details?: JsonValue

usage?

readonly optional usage?: Usage

isError

readonly isError: boolean

terminate?

readonly optional terminate?: boolean

MuleToolExecutionPart

MuleToolExecutionPart = { type: "update"; result: MuleToolResult; } | { type: "result"; result: MuleToolResult; }

Progress or terminal output from one tool execution.

MuleToolRejection

MuleToolRejection = object

A real parser or authorization rejection produced before tool execution.

Properties

message

readonly message: string

terminate?

readonly optional terminate?: boolean

MuleCompletedTurn

MuleCompletedTurn = object

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

Properties

message

readonly message: AssistantMessage

toolResults

readonly toolResults: readonly ToolResultMessage[]

context

readonly context: readonly Message[]

newMessages

readonly newMessages: readonly Message[]

MuleEvent

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; } | { 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

Type Literal

{ type: "run_start"; run: MuleIdentity; }

Type Literal

{ type: "model_prompt"; run: MuleIdentity; turn: MuleIdentity; attempt: number; systemPrompt: string; }

type

readonly type: "model_prompt"

Exact prompt sent on this model attempt, including after a retry.

run

readonly run: MuleIdentity

turn

readonly turn: MuleIdentity

attempt

readonly attempt: number

systemPrompt

readonly systemPrompt: string

Type Literal

{ type: "turn_start"; run: MuleIdentity; turn: MuleIdentity; }

Type Literal

{ type: "message_start"; run: MuleIdentity; turn: MuleIdentity; message: MuleIdentity; value: Message; }

Type Literal

{ type: "message_update"; run: MuleIdentity; turn: MuleIdentity; message: MuleIdentity; value: AssistantMessage; event: AssistantMessageEvent; }

Type Literal

{ type: "message_end"; run: MuleIdentity; turn: MuleIdentity; message: MuleIdentity; value: Message; }

Type Literal

{ type: "tool_execution_start"; replay: "safe" | "unsafe"; run: MuleIdentity; turn: MuleIdentity; toolCall: MuleIdentity; call: ToolCall; }

Type Literal

{ type: "tool_execution_update"; run: MuleIdentity; turn: MuleIdentity; toolCall: MuleIdentity; call: ToolCall; result: MuleToolResult; }

Type Literal

{ type: "tool_execution_end"; run: MuleIdentity; turn: MuleIdentity; toolCall: MuleIdentity; call: ToolCall; result: MuleToolResult; }

Type Literal

{ type: "turn_end"; run: MuleIdentity; turn: MuleIdentity; message: AssistantMessage; toolResults: readonly ToolResultMessage[]; }

Type Literal

{ type: "run_end"; run: MuleIdentity; terminal: MuleIdentity; outcome: "completed" | "cancelled" | "failed"; }

type

readonly 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

readonly run: MuleIdentity

terminal

readonly terminal: MuleIdentity

outcome

readonly outcome: "completed" | "cancelled" | "failed"

MuleToolCheckpoint

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

Type Literal

{ call: ToolCall; state: "pending"; }

Type Literal

{ call: ToolCall; state: "started"; replay: "safe" | "unsafe"; }

Type Literal

{ call: ToolCall; state: "completed"; result: MuleToolResult; message?: ToolResultMessage; }

call

readonly call: ToolCall

state

readonly state: "completed"

result

readonly result: MuleToolResult

message?

readonly optional message?: ToolResultMessage

Present when the transcript message was committed too.

MuleResume

MuleResume = object

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

Properties

message

readonly message: AssistantMessage

tools

readonly tools: readonly MuleToolCheckpoint[]

MuleRunSettings

MuleRunSettings = object

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

Properties

model

readonly model: Model<Api>>

stream?

readonly optional stream?: MuleStreamFunction

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

systemPrompt

readonly systemPrompt: string

messages

readonly messages: readonly Message[]

resume?

readonly optional resume?: MuleResume

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

streamOptions?

readonly optional streamOptions?: Omit<SimpleStreamOptions, "signal">>

Pi stream options. Cancellation is the run’s interruption, never a signal here.

modelStreamIdleTimeoutMs?

readonly optional modelStreamIdleTimeoutMs?: number

Maximum silence between provider stream events, in milliseconds.

toolExecution?

readonly optional toolExecution?: "parallel" | "sequential"

retry?

readonly optional retry?: RetryPolicy

Pi’s bounded retry policy around each assistant call (retryAssistantCall). Undefined means no retry, matching pi-ai’s own default. Hosts that want Pi coding-agent’s numbers pass piCodingAgentRetryDefaults.

retryAfterMs?

readonly optional retryAfterMs?: (message) => number | undefined

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

Parameters

message

AssistantMessage

Returns

number | undefined

MuleRunOutcome

MuleRunOutcome = object

Honest terminal result of one Mule invocation.

Properties

status

readonly status: "completed" | "cancelled" | "failed"

run

readonly run: MuleIdentity

terminal

readonly terminal: MuleIdentity

message

readonly message: AssistantMessage

messages

readonly messages: readonly Message[]

MulePromiseListener

MulePromiseListener = (event, signal) => Promise<void> > | void

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

Parameters

event

MuleEvent

signal

AbortSignal

Returns

Promise<void> | void

MuleToolPreparation

MuleToolPreparation = { status: "prepared"; execute: (signal) => AsyncIterable<MuleToolExecutionPart>>; } | object & MuleToolRejection

Outcome of preparing one exact Pi tool call.

Union Members

Type Literal

{ status: "prepared"; execute: (signal) => AsyncIterable<MuleToolExecutionPart>; }

status

readonly status: "prepared"

execute

readonly execute: (signal) => AsyncIterable<MuleToolExecutionPart>>

Run the already-decoded and authorized call; abort ends it early.

Parameters

signal

AbortSignal

Returns

AsyncIterable<MuleToolExecutionPart>

object & MuleToolRejection

MuleTool

MuleTool = object

Pi tool declaration paired with its Promise preparation door.

Properties

descriptor

readonly descriptor: Tool

replay?

readonly optional replay?: "safe" | "unsafe"

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

executionMode?

readonly optional executionMode?: "parallel" | "sequential"

prepare

readonly prepare: (call, signal) => Promise<MuleToolPreparation>>

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

Parameters

call

ToolCall

signal

AbortSignal

Returns

Promise<MuleToolPreparation>

MuleRunInput

MuleRunInput = MuleRunSettings & object

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

Type Declaration

tools?

readonly optional tools?: readonly MuleTool[]

resolveApiKey?

readonly optional resolveApiKey?: (provider, signal) => Promise<string | undefined>>

Resolve a fresh provider credential immediately before each Pi call.

Parameters

provider

string

signal

AbortSignal

Returns

Promise<string | undefined>

getSteeringMessages?

readonly optional getSteeringMessages?: (signal) => Promise<readonly Message[]>

Pull messages that should steer the active run at Pi’s safe point.

Parameters

signal

AbortSignal

Returns

Promise<readonly Message[]>

getFollowUpMessages?

readonly optional getFollowUpMessages?: (signal) => Promise<readonly Message[]>

Pull messages queued until the run would otherwise finish.

Parameters

signal

AbortSignal

Returns

Promise<readonly Message[]>

shouldStopAfterTurn?

readonly optional shouldStopAfterTurn?: (turn, signal) => Promise<boolean>>

Request a graceful stop after the current Pi turn has fully settled.

Parameters

turn

MuleCompletedTurn

signal

AbortSignal

Returns

Promise<boolean>

Mule

Mule = object

Promise-facing Mule interface.

Properties

run

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

input

MuleRunInput

listener?

MulePromiseListener

signal?

AbortSignal

Returns

Promise<MuleRunOutcome>

Variables

mule

const mule: Mule

Default Promise-facing Mule interface.