index

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

Context

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

addedToolNames?

readonly optional addedToolNames?: string[]

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: "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"; 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: "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"; 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"

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[]

streamOptions?

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

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

toolExecution?

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

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

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.