Skip to content
Mule0.2.1
API reference

effect

Import

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

Exports

Section titled “Exports”
Kind Export Description
type alias MuleRetryObservation One observed typed-retry event around a single assistant call.
type alias MulePreparedTool A decoded, authorized invocation ready to execute.
type alias MuleTool Pi tool declaration paired with its Effect-native preparation door.
type alias MuleListener Effect-native listener. Completion is part of run settlement.
type alias MuleRunInput Inputs for one complete Pi model/tool loop. Cancel a run by interrupting its fiber; the run then ends with a cancelled run_end.
type alias MuleEffect Canonical Effect-native Mule interface.
type alias ThinkingLevel Provider-neutral reasoning effort requested by a caller.
type alias ModelThinkingLevel Effective reasoning effort, including disabled thinking.
type alias KnownApi Built-in chat APIs recognized by the pinned Pi adapter.
type alias Api Built-in or caller-defined chat API identifier.
type alias ProviderId Provider identifier carried with a model or assistant message.
type alias ToolChoice Provider-neutral choice to allow or disable tools.
type alias SamplingParams Provider sampling fields passed through unchanged.
type alias SamplingParamsByThinkingLevel Sampling overrides selected by reasoning effort.
type alias ThinkingBudgets Token budgets for providers that meter reasoning separately.
type alias Transport Preferred provider stream transport.
type alias ProviderEnv Request-scoped provider environment overrides.
type alias ProviderHeaders Provider headers; null removes a default header.
type alias FetchFunction Fetch implementation supplied to the provider adapter.
type alias ProviderResponse HTTP status and headers observed before stream consumption.
type alias ProviderRequestOptions Authentication, transport and lifecycle hooks for one provider request.
type alias StreamOptions Common provider stream controls, independent of any SDK.
type alias SimpleStreamOptions Provider-neutral model request options used by Mule.
type alias TextContent Text block with an optional provider continuity signature.
type alias ThinkingContent Reasoning block, including opaque redacted provider thinking.
type alias ImageContent Base64 image bytes with their media type.
type alias ToolCall Model-requested tool invocation with JSON arguments.
type alias Usage Token counts and provider costs for one response or tool result.
type alias StopReason Provider outcome for an assistant response.
type alias JsonValue JSON data carried by messages and tool results.
type alias ProviderValue Provider request/event values, including optional fields, binary bytes and cancellation.
type alias ProviderData Parsed provider request or event fields; Pi owns the provider-specific grammar.
type alias JsonObject Named JSON properties in tool arguments or message metadata.
type alias DeferredHandle Provider receipt used to recover a deferred assistant response.
type alias SystemMessage Prompt and tool-set update at a point in the transcript.
type alias UserMessage User text and image input with its timestamp.
type alias AssistantMessage Provider response, usage and terminal reason, preserved by Mule.
type alias NestedToolCallRecord Bounded evidence of a tool invocation made inside another tool.
type alias NestedToolCalls Recorded nested invocations and whether the record is complete.
type alias ToolResultMessage Correlated tool output with optional JSON details and usage.
type alias Message One system, user, assistant or tool-result transcript entry.
type alias GrammarFormat Provider grammar formats available for constrained sampling.
type alias GrammarVariants Grammar text supplied for each supported provider format.
type alias ConstrainedSamplingConfig Provider constraint for a tool declaration.
type alias Tool Model-visible tool name, description and TypeBox argument schema.
type alias ToolReference Named tool removed by a transcript system update.
type alias Context Model request context; Pi adapters normalize it before provider dispatch.
type alias AssistantMessageEvent Partial updates and the terminal event for an assistant stream.
type alias BaseModel Catalog fields shared by chat model definitions.
type alias Model Chat model configuration accepted by Mule and its Pi adapter.
type alias DiagnosticErrorInfo Serializable diagnostic information retained with an assistant message.
type alias AssistantMessageDiagnostic Timestamped provider diagnostic with optional JSON details.
type alias AssistantMessageEventStream Only the stream operations consumed by Mule. Pi’s concrete stream satisfies this port.
type alias RetryPolicy Bounded assistant-call retries with capped exponential delays.
type alias AttributeValue Scalar or homogeneous-array telemetry attribute.
type alias SpanAttributes Named telemetry attributes, with undefined values omitted by the owner.
type alias SpanOptions Name and initial attributes of a request telemetry span.
type alias SpanStatus Successful or failed telemetry completion.
type alias TelemetryContext Parent context through which a provider opens telemetry spans.
type alias TelemetrySpan Provider telemetry span with events, attributes and completion status.
constant piCodingAgentRetryDefaults Pi coding-agent’s retry defaults (settings-manager.js getRetrySettings(), @earendil-works/pi-ai 0.99.0, the version pinned in the lockfile). Pi-ai’s own RetryPolicy has no default — an undefined policy means no retry — so a host that wants Pi coding-agent’s numbers passes this explicitly.
constant muleEffect Canonical Effect-native Mule value.
function isContextOverflow() Apply Pi’s maintained context-overflow semantics to an exact Pi message.
function run() Run Pi’s model/tool loop inside Effect without changing Pi’s values.

MuleRetryObservationtype alias

Section titled “MuleRetryObservation”
Signature
type MuleRetryObservation =
  | {
      type: "retry_scheduled";
      run: MuleIdentity;
      turn: MuleIdentity;
      attempt: number;
      maxAttempts: number;
      delayMs: number;
      errorMessage: string;
    }
  | {
      type: "retry_attempt_started";
      run: MuleIdentity;
      turn: MuleIdentity;
      attempt: number;
    }
  | {
      type: "retry_finished";
      run: MuleIdentity;
      turn: MuleIdentity;
      attempt: number;
      success: boolean;
      finalError?: string;
    };

One observed typed-retry event around a single assistant call.

MulePreparedTooltype alias

Section titled “MulePreparedTool”
Signature
type MulePreparedTool = object;

A decoded, authorized invocation ready to execute.

Properties

Section titled “Properties”

execute

Section titled “execute”
Signature
readonly execute: () => Stream.Stream<MuleToolExecutionPart, MuleError>;

Run the already-decoded and authorized tool call.

Returns
Section titled “Returns”

Stream.Stream<MuleToolExecutionPart, MuleError>

MuleTooltype alias

Section titled “MuleTool”
Signature
type MuleTool = object;

Pi tool declaration paired with its Effect-native 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) => Effect.Effect<MulePreparedTool, MuleToolRejection>;

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

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

Effect.Effect<MulePreparedTool, MuleToolRejection>

MuleListenertype alias

Section titled “MuleListener”
Signature
type MuleListener = (event) => Effect.Effect<void, MuleError>;

Effect-native listener. Completion is part of run settlement.

Parameters

Section titled “Parameters”
Parameter Type
event MuleEvent

Returns

Section titled “Returns”

Effect.Effect<void, MuleError>

MuleRunInputtype alias

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

Inputs for one complete Pi model/tool loop. Cancel a run by interrupting its fiber; the run then ends with a cancelled run_end.

Type Declaration

Section titled “Type Declaration”
Name Type Description
prepareSystemPrompt()? () => Effect.Effect<string, MuleError> Rebuild the model system prompt immediately before each provider request.
tools? readonly MuleTool[] -
resolveApiKey()? (provider) => Effect.Effect<string | undefined, MuleError> Resolve a fresh provider credential immediately before each Pi call.
getSteeringMessages()? () => Effect.Effect<readonly Message[], MuleError> Pull messages that should steer the active run at Pi’s safe point.
getFollowUpMessages()? () => Effect.Effect<readonly Message[], MuleError> Pull messages queued until the run would otherwise finish.
prepareNextTurn()? (turn) => Effect.Effect<readonly Message[] | undefined, MuleError> Pi’s between-turn point: after a turn’s tool results and before the next assistant request of the same run. Return a replacement context, such as one rebuilt after compaction, or undefined to keep the current one.
shouldStopAfterTurn()? (turn) => Effect.Effect<boolean, MuleError> Request a graceful stop after the current Pi turn has fully settled.
onRetry()? (event) => Effect.Effect<void, MuleError> Effect-native observation sink for Pi’s retry policy (retry), one call per scheduled or finished retry.

MuleEffecttype alias

Section titled “MuleEffect”
Signature
type MuleEffect = object;

Canonical Effect-native Mule interface.

Properties

Section titled “Properties”

run

Section titled “run”
Signature
readonly run: (input, listener?) => Effect.Effect<MuleRunOutcome, MuleError>;

Run one complete Pi model/tool loop.

Parameters
Section titled “Parameters”
Parameter Type
input MuleRunInput
listener? MuleListener
Returns
Section titled “Returns”

Effect.Effect<MuleRunOutcome, MuleError>

ThinkingLeveltype alias

Section titled “ThinkingLevel”
Signature
type ThinkingLevel = "minimal" | "low" | "medium" | "high" | "xhigh" | "max";

Provider-neutral reasoning effort requested by a caller.

ModelThinkingLeveltype alias

Section titled “ModelThinkingLevel”
Signature
type ModelThinkingLevel = "off" | ThinkingLevel;

Effective reasoning effort, including disabled thinking.

KnownApitype alias

Section titled “KnownApi”
Signature
type KnownApi =
  | "openai-completions"
  | "mistral-conversations"
  | "openai-responses"
  | "azure-openai-responses"
  | "openai-codex-responses"
  | "anthropic-messages"
  | "bedrock-converse-stream"
  | "google-generative-ai"
  | "google-vertex"
  | "pi-messages";

Built-in chat APIs recognized by the pinned Pi adapter.

Apitype alias

Section titled “Api”
Signature
type Api = KnownApi | (string & object);

Built-in or caller-defined chat API identifier.

ProviderIdtype alias

Section titled “ProviderId”
Signature
type ProviderId = string;

Provider identifier carried with a model or assistant message.

ToolChoicetype alias

Section titled “ToolChoice”
Signature
type ToolChoice = "auto" | "none";

Provider-neutral choice to allow or disable tools.

SamplingParamstype alias

Section titled “SamplingParams”
Signature
type SamplingParams = JsonObject;

Provider sampling fields passed through unchanged.

SamplingParamsByThinkingLeveltype alias

Section titled “SamplingParamsByThinkingLevel”
Signature
type SamplingParamsByThinkingLevel = Partial<
  Record<ModelThinkingLevel, SamplingParams>
>;

Sampling overrides selected by reasoning effort.

ThinkingBudgetstype alias

Section titled “ThinkingBudgets”
Signature
type ThinkingBudgets = object;

Token budgets for providers that meter reasoning separately.

Properties

Section titled “Properties”

minimal?

Section titled “minimal?”
Signature
optional minimal?: number;

low?

Section titled “low?”
Signature
optional low?: number;

medium?

Section titled “medium?”
Signature
optional medium?: number;

high?

Section titled “high?”
Signature
optional high?: number;

Transporttype alias

Section titled “Transport”
Signature
type Transport = "sse" | "websocket" | "websocket-cached" | "auto";

Preferred provider stream transport.

ProviderEnvtype alias

Section titled “ProviderEnv”
Signature
type ProviderEnv = Record<string, string>;

Request-scoped provider environment overrides.

ProviderHeaderstype alias

Section titled “ProviderHeaders”
Signature
type ProviderHeaders = Record<string, string | null>;

Provider headers; null removes a default header.

FetchFunctiontype alias

Section titled “FetchFunction”
Signature
type FetchFunction = typeof globalThis.fetch;

Fetch implementation supplied to the provider adapter.

ProviderResponsetype alias

Section titled “ProviderResponse”
Signature
type ProviderResponse = object;

HTTP status and headers observed before stream consumption.

Properties

Section titled “Properties”

status

Section titled “status”
Signature
status: number;

headers

Section titled “headers”
Signature
headers: Record<string, string>;

ProviderRequestOptionstype alias

Section titled “ProviderRequestOptions”
Signature
type ProviderRequestOptions<TModel> = object;

Authentication, transport and lifecycle hooks for one provider request.

Type Parameters

Section titled “Type Parameters”
Type Parameter Default type
TModel Model<Api>

Properties

Section titled “Properties”

signal?

Section titled “signal?”
Signature
optional signal?: AbortSignal;

telemetryContext?

Section titled “telemetryContext?”
Signature
optional telemetryContext?: TelemetryContext;

apiKey?

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

fetch?

Section titled “fetch?”
Signature
optional fetch?: FetchFunction;

Override HTTP transport for this request.

env?

Section titled “env?”
Signature
optional env?: ProviderEnv;

onPayload?

Section titled “onPayload?”
Signature
optional onPayload?: (payload, model) =>
  | ProviderData
  | undefined
| Promise<ProviderData | undefined>;

Observe or replace the provider payload before dispatch.

Parameters
Section titled “Parameters”
Parameter Type
payload ProviderData
model TModel
Returns
Section titled “Returns”

| ProviderData | undefined | Promise<ProviderData | undefined>

onResponse?

Section titled “onResponse?”
Signature
optional onResponse?: (response, model) => void | Promise<void>;

Observe status and headers before provider stream consumption.

Parameters
Section titled “Parameters”
Parameter Type
response ProviderResponse
model TModel
Returns
Section titled “Returns”

void | Promise<void>

headers?

Section titled “headers?”
Signature
optional headers?: ProviderHeaders;

timeoutMs?

Section titled “timeoutMs?”
Signature
optional timeoutMs?: number;

maxRetries?

Section titled “maxRetries?”
Signature
optional maxRetries?: number;

maxRetryDelayMs?

Section titled “maxRetryDelayMs?”
Signature
optional maxRetryDelayMs?: number;

StreamOptionstype alias

Section titled “StreamOptions”
Signature
type StreamOptions = object & ProviderRequestOptions;

Common provider stream controls, independent of any SDK.

Type Declaration

Section titled “Type Declaration”
Name Type Description
onProviderStreamEvent()? (data, model) => void | Promise<void> Observe an adapter-parsed event before Pi normalizes it.
temperature? number -
samplingParams? SamplingParams -
maxTokens? number -
transport? Transport -
cacheRetention? CacheRetention -
sessionId? string -
websocketConnectTimeoutMs? number -
metadata? JsonObject -

SimpleStreamOptionstype alias

Section titled “SimpleStreamOptions”
Signature
type SimpleStreamOptions = object & StreamOptions;

Provider-neutral model request options used by Mule.

Type Declaration

Section titled “Type Declaration”
Name Type
toolChoice? ToolChoice
reasoning? ThinkingLevel
deferred? | boolean | { window?: "15m" | "1h" | "24h"; }
thinkingBudgets? ThinkingBudgets

TextContenttype alias

Section titled “TextContent”
Signature
type TextContent = object;

Text block with an optional provider continuity signature.

Properties

Section titled “Properties”

type

Section titled “type”
Signature
type: "text";

text

Section titled “text”
Signature
text: string;

textSignature?

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

ThinkingContenttype alias

Section titled “ThinkingContent”
Signature
type ThinkingContent = object;

Reasoning block, including opaque redacted provider thinking.

Properties

Section titled “Properties”

type

Section titled “type”
Signature
type: "thinking";

thinking

Section titled “thinking”
Signature
thinking: string;

thinkingSignature?

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

redacted?

Section titled “redacted?”
Signature
optional redacted?: boolean;

ImageContenttype alias

Section titled “ImageContent”
Signature
type ImageContent = object;

Base64 image bytes with their media type.

Properties

Section titled “Properties”

type

Section titled “type”
Signature
type: "image";

data

Section titled “data”
Signature
data: string;

mimeType

Section titled “mimeType”
Signature
mimeType: string;

ToolCalltype alias

Section titled “ToolCall”
Signature
type ToolCall = object;

Model-requested tool invocation with JSON arguments.

Properties

Section titled “Properties”

type

Section titled “type”
Signature
type: "toolCall";

id

Section titled “id”
Signature
id: string;

name

Section titled “name”
Signature
name: string;

arguments

Section titled “arguments”
Signature
arguments: JsonObject;

thoughtSignature?

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

namespace?

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

argumentsError?

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

Usagetype alias

Section titled “Usage”
Signature
type Usage = object;

Token counts and provider costs for one response or tool result.

Properties

Section titled “Properties”

input

Section titled “input”
Signature
input: number;

output

Section titled “output”
Signature
output: number;

cacheRead

Section titled “cacheRead”
Signature
cacheRead: number;

cacheWrite

Section titled “cacheWrite”
Signature
cacheWrite: number;

cacheWrite1h?

Section titled “cacheWrite1h?”
Signature
optional cacheWrite1h?: number;

reasoning?

Section titled “reasoning?”
Signature
optional reasoning?: number;

totalTokens

Section titled “totalTokens”
Signature
totalTokens: number;

cost

Section titled “cost”
Signature
cost: object;
input
Section titled “input”
Signature
input: number;
output
Section titled “output”
Signature
output: number;
cacheRead
Section titled “cacheRead”
Signature
cacheRead: number;
cacheWrite
Section titled “cacheWrite”
Signature
cacheWrite: number;
total
Section titled “total”
Signature
total: number;

StopReasontype alias

Section titled “StopReason”
Signature
type StopReason =
  "pending" | "stop" | "length" | "toolUse" | "error" | "aborted" | "deferred";

Provider outcome for an assistant response.

JsonValuetype alias

Section titled “JsonValue”
Signature
type JsonValue =
  null | boolean | number | string | readonly JsonValue[] | JsonObject;

JSON data carried by messages and tool results.

ProviderValuetype alias

Section titled “ProviderValue”
Signature
type ProviderValue =
  | undefined
  | null
  | boolean
  | number
  | string
  | Uint8Array
  | AbortSignal
  | readonly ProviderValue[]
  | ProviderData;

Provider request/event values, including optional fields, binary bytes and cancellation.

ProviderDatatype alias

Section titled “ProviderData”
Signature
type ProviderData = object;

Parsed provider request or event fields; Pi owns the provider-specific grammar.

Index Signature

Section titled “Index Signature”
Signature
[key: string]: ProviderValue

JsonObjecttype alias

Section titled “JsonObject”
Signature
type JsonObject = object;

Named JSON properties in tool arguments or message metadata.

Index Signature

Section titled “Index Signature”
Signature
[key: string]: JsonValue

DeferredHandletype alias

Section titled “DeferredHandle”
Signature
type DeferredHandle = object;

Provider receipt used to recover a deferred assistant response.

Properties

Section titled “Properties”

provider

Section titled “provider”
Signature
provider: string;

modelId

Section titled “modelId”
Signature
modelId: string;

api

Section titled “api”
Signature
api: string;

id

Section titled “id”
Signature
id: string;

expiresAt?

Section titled “expiresAt?”
Signature
optional expiresAt?: number;

pollAfterMs?

Section titled “pollAfterMs?”
Signature
optional pollAfterMs?: number;

data?

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

SystemMessagetype alias

Section titled “SystemMessage”
Signature
type SystemMessage = object;

Prompt and tool-set update at a point in the transcript.

Properties

Section titled “Properties”

role

Section titled “role”
Signature
role: "system";

content

Section titled “content”
Signature
content: string | TextContent[];

sections?

Section titled “sections?”
Signature
optional sections?: Record<string, string | null>;

toolsAdded?

Section titled “toolsAdded?”
Signature
optional toolsAdded?: Tool[];

toolsRemoved?

Section titled “toolsRemoved?”
Signature
optional toolsRemoved?: ToolReference[];

timestamp

Section titled “timestamp”
Signature
timestamp: number;

UserMessagetype alias

Section titled “UserMessage”
Signature
type UserMessage = object;

User text and image input with its timestamp.

Properties

Section titled “Properties”

role

Section titled “role”
Signature
role: "user";

content

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

timestamp

Section titled “timestamp”
Signature
timestamp: number;

AssistantMessagetype alias

Section titled “AssistantMessage”
Signature
type AssistantMessage = object;

Provider response, usage and terminal reason, preserved by Mule.

Properties

Section titled “Properties”

role

Section titled “role”
Signature
role: "assistant";

content

Section titled “content”
Signature
content: (
  | TextContent
  | ThinkingContent
  | ToolCall)[];

api

Section titled “api”
Signature
api: Api;

provider

Section titled “provider”
Signature
provider: ProviderId;

model

Section titled “model”
Signature
model: string;

responseModel?

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

responseId?

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

providerThinkingLevel?

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

thinkingLevel?

Section titled “thinkingLevel?”
Signature
optional thinkingLevel?: ModelThinkingLevel;

diagnostics?

Section titled “diagnostics?”
Signature
optional diagnostics?: AssistantMessageDiagnostic[];

usage

Section titled “usage”
Signature
usage: Usage;

stopReason

Section titled “stopReason”
Signature
stopReason: StopReason;

deferred?

Section titled “deferred?”
Signature
optional deferred?: DeferredHandle;

errorMessage?

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

providerError?

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

Provider prose for the failed conversation turn, never a diagnostic.

rawStopReason?

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

endTurn?

Section titled “endTurn?”
Signature
optional endTurn?: boolean;

timestamp

Section titled “timestamp”
Signature
timestamp: number;

durationMs?

Section titled “durationMs?”
Signature
optional durationMs?: number;

NestedToolCallRecordtype alias

Section titled “NestedToolCallRecord”
Signature
type NestedToolCallRecord = object;

Bounded evidence of a tool invocation made inside another tool.

Properties

Section titled “Properties”

id

Section titled “id”
Signature
id: string;

name

Section titled “name”
Signature
name: string;

arguments?

Section titled “arguments?”
Signature
optional arguments?: JsonObject;

argumentsBytes?

Section titled “argumentsBytes?”
Signature
optional argumentsBytes?: number;

status

Section titled “status”
Signature
status: "ok" | "error" | "unfinished";

durationMs?

Section titled “durationMs?”
Signature
optional durationMs?: number;

error?

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

NestedToolCallstype alias

Section titled “NestedToolCalls”
Signature
type NestedToolCalls = object;

Recorded nested invocations and whether the record is complete.

Properties

Section titled “Properties”

calls

Section titled “calls”
Signature
calls: NestedToolCallRecord[];

complete

Section titled “complete”
Signature
complete: boolean;

ToolResultMessagetype alias

Section titled “ToolResultMessage”
Signature
type ToolResultMessage = object;

Correlated tool output with optional JSON details and usage.

Properties

Section titled “Properties”

role

Section titled “role”
Signature
role: "toolResult";

toolCallId

Section titled “toolCallId”
Signature
toolCallId: string;

toolName

Section titled “toolName”
Signature
toolName: string;

content

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

details?

Section titled “details?”
Signature
optional details?: JsonValue;

usage?

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

nestedCalls?

Section titled “nestedCalls?”
Signature
optional nestedCalls?: NestedToolCalls;

isError

Section titled “isError”
Signature
isError: boolean;

timestamp

Section titled “timestamp”
Signature
timestamp: number;

durationMs?

Section titled “durationMs?”
Signature
optional durationMs?: number;

Messagetype alias

Section titled “Message”
Signature
type Message =
  SystemMessage | UserMessage | AssistantMessage | ToolResultMessage;

One system, user, assistant or tool-result transcript entry.

GrammarFormattype alias

Section titled “GrammarFormat”
Signature
type GrammarFormat = "openai_lark" | "openai_regex";

Provider grammar formats available for constrained sampling.

GrammarVariantstype alias

Section titled “GrammarVariants”
Signature
type GrammarVariants = Partial<Record<GrammarFormat, string>>;

Grammar text supplied for each supported provider format.

ConstrainedSamplingConfigtype alias

Section titled “ConstrainedSamplingConfig”
Signature
type ConstrainedSamplingConfig =
  | {
      type: "json_schema";
      strict: "prefer" | "require";
    }
  | {
      type: "grammar";
      variants: GrammarVariants;
    };

Provider constraint for a tool declaration.

Tooltype alias

Section titled “Tool”
Signature
type Tool<TParameters> = object;

Model-visible tool name, description and TypeBox argument schema.

Type Parameters

Section titled “Type Parameters”
Type Parameter Default type
TParameters extends TSchema TSchema

Properties

Section titled “Properties”

name

Section titled “name”
Signature
name: string;

description

Section titled “description”
Signature
description: string;

parameters

Section titled “parameters”
Signature
parameters: TParameters;

constrainedSampling?

Section titled “constrainedSampling?”
Signature
optional constrainedSampling?: false | ConstrainedSamplingConfig;

ToolReferencetype alias

Section titled “ToolReference”
Signature
type ToolReference = object;

Named tool removed by a transcript system update.

Properties

Section titled “Properties”

name

Section titled “name”
Signature
name: string;

Contexttype alias

Section titled “Context”
Signature
type Context = object;

Model request context; Pi adapters normalize it before provider dispatch.

Properties

Section titled “Properties”

systemPrompt?

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

messages

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

tools?

Section titled “tools?”
Signature
optional tools?: Tool[];

AssistantMessageEventtype alias

Section titled “AssistantMessageEvent”
Signature
type AssistantMessageEvent =
  | {
      type: "start";
      partial: AssistantMessage;
    }
  | {
      type: "text_start";
      contentIndex: number;
      partial: AssistantMessage;
    }
  | {
      type: "text_delta";
      contentIndex: number;
      delta: string;
      partial: AssistantMessage;
    }
  | {
      type: "text_end";
      contentIndex: number;
      content: string;
      partial: AssistantMessage;
    }
  | {
      type: "thinking_start";
      contentIndex: number;
      partial: AssistantMessage;
    }
  | {
      type: "thinking_delta";
      contentIndex: number;
      delta: string;
      partial: AssistantMessage;
    }
  | {
      type: "thinking_end";
      contentIndex: number;
      content: string;
      partial: AssistantMessage;
    }
  | {
      type: "toolcall_start";
      contentIndex: number;
      partial: AssistantMessage;
    }
  | {
      type: "toolcall_delta";
      contentIndex: number;
      delta: string;
      partial: AssistantMessage;
    }
  | {
      type: "toolcall_end";
      contentIndex: number;
      toolCall: ToolCall;
      partial: AssistantMessage;
    }
  | {
      type: "done";
      reason: Extract<StopReason, "stop" | "length" | "toolUse" | "deferred">;
      message: AssistantMessage;
    }
  | {
      type: "error";
      reason: Extract<StopReason, "aborted" | "error">;
      error: AssistantMessage;
    };

Partial updates and the terminal event for an assistant stream.

BaseModeltype alias

Section titled “BaseModel”
Signature
type BaseModel<TApi> = object;

Catalog fields shared by chat model definitions.

Type Parameters

Section titled “Type Parameters”
Type Parameter
TApi extends string

Properties

Section titled “Properties”

id

Section titled “id”
Signature
id: string;

name

Section titled “name”
Signature
name: string;

api

Section titled “api”
Signature
api: TApi;

provider

Section titled “provider”
Signature
provider: ProviderId;

baseUrl

Section titled “baseUrl”
Signature
baseUrl: string;

input

Section titled “input”
Signature
input: ModelInputModality[];

inputLimits?

Section titled “inputLimits?”
Signature
optional inputLimits?: ModelInputLimits;

cost

Section titled “cost”
Signature
cost: ModelCost;

headers?

Section titled “headers?”
Signature
optional headers?: Record<string, string>;

Modeltype alias

Section titled “Model”
Signature
type Model<TApi> = object & BaseModel<TApi>;

Chat model configuration accepted by Mule and its Pi adapter.

Type Declaration

Section titled “Type Declaration”
Name Type
type? "chat"
reasoning boolean
thinkingLevelMap? ThinkingLevelMap
promptCache? ModelPromptCache
contextWindow number
maxTokens number
samplingParams? SamplingParams
samplingParamsByThinkingLevel? SamplingParamsByThinkingLevel
compat? TApi extends "openai-completions" ? OpenAICompletionsCompat : TApi extends | "openai-responses" | "azure-openai-responses" | "openai-codex-responses" ? OpenAIResponsesCompat : TApi extends "anthropic-messages" ? AnthropicMessagesCompat : TApi extends "bedrock-converse-stream" ? BedrockCompat : TApi extends "mistral-conversations" ? MistralConversationsCompat : never

Type Parameters

Section titled “Type Parameters”
Type Parameter
TApi extends Api

DiagnosticErrorInfotype alias

Section titled “DiagnosticErrorInfo”
Signature
type DiagnosticErrorInfo = object;

Serializable diagnostic information retained with an assistant message.

Properties

Section titled “Properties”

name?

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

message

Section titled “message”
Signature
message: string;

stack?

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

code?

Section titled “code?”
Signature
optional code?: string | number;

AssistantMessageDiagnostictype alias

Section titled “AssistantMessageDiagnostic”
Signature
type AssistantMessageDiagnostic = object;

Timestamped provider diagnostic with optional JSON details.

Properties

Section titled “Properties”

type

Section titled “type”
Signature
type: string;

timestamp

Section titled “timestamp”
Signature
timestamp: number;

error?

Section titled “error?”
Signature
optional error?: DiagnosticErrorInfo;

details?

Section titled “details?”
Signature
optional details?: JsonObject;

AssistantMessageEventStreamtype alias

Section titled “AssistantMessageEventStream”
Signature
type AssistantMessageEventStream = object &
  AsyncIterable<AssistantMessageEvent>;

Only the stream operations consumed by Mule. Pi’s concrete stream satisfies this port.

Type Declaration

Section titled “Type Declaration”
Name Type Description
result() () => Promise<AssistantMessage> Await the authoritative final assistant message.

RetryPolicytype alias

Section titled “RetryPolicy”
Signature
type RetryPolicy = object;

Bounded assistant-call retries with capped exponential delays.

Properties

Section titled “Properties”

enabled

Section titled “enabled”
Signature
enabled: boolean;

maxRetries

Section titled “maxRetries”
Signature
maxRetries: number;

baseDelayMs

Section titled “baseDelayMs”
Signature
baseDelayMs: number;

maxAgentDelayMs?

Section titled “maxAgentDelayMs?”
Signature
optional maxAgentDelayMs?: number;

AttributeValuetype alias

Section titled “AttributeValue”
Signature
type AttributeValue =
  | string
  | number
  | boolean
  | readonly string[]
  | readonly number[]
  | readonly boolean[];

Scalar or homogeneous-array telemetry attribute.

SpanAttributestype alias

Section titled “SpanAttributes”
Signature
type SpanAttributes = Record<string, AttributeValue | undefined>;

Named telemetry attributes, with undefined values omitted by the owner.

SpanOptionstype alias

Section titled “SpanOptions”
Signature
type SpanOptions = object;

Name and initial attributes of a request telemetry span.

Properties

Section titled “Properties”

name

Section titled “name”
Signature
name: string;

attributes?

Section titled “attributes?”
Signature
optional attributes?: SpanAttributes;

SpanStatustype alias

Section titled “SpanStatus”
Signature
type SpanStatus =
  | {
      status: "ok";
    }
  | {
      status: "error";
      error?: {
        name: string;
        message: string;
      };
    };

Successful or failed telemetry completion.

TelemetryContexttype alias

Section titled “TelemetryContext”
Signature
type TelemetryContext = object;

Parent context through which a provider opens telemetry spans.

Methods

Section titled “Methods”

startSpan()

Section titled “startSpan()”
Signature
startSpan<T>(options, callback): Promise<T>;

Run provider work under a child span.

Type Parameters
Section titled “Type Parameters”
Type Parameter
T
Parameters
Section titled “Parameters”
Parameter Type
options SpanOptions
callback (span) => T | Promise<T>
Returns
Section titled “Returns”

Promise<T>

TelemetrySpantype alias

Section titled “TelemetrySpan”
Signature
type TelemetrySpan = object & TelemetryContext;

Provider telemetry span with events, attributes and completion status.

Type Declaration

Section titled “Type Declaration”
Name Type Description
addEvent() (name, attributes?) => void Record a timestamped event on this span.
setAttributes() (attributes) => void Add or replace attributes on this span.
setStatus() (status) => void Record the completion status of this span.

piCodingAgentRetryDefaultsconstant

Section titled “piCodingAgentRetryDefaults”
Signature
const piCodingAgentRetryDefaults: RetryPolicy;

Pi coding-agent’s retry defaults (settings-manager.js getRetrySettings(), @earendil-works/pi-ai 0.99.0, the version pinned in the lockfile). Pi-ai’s own RetryPolicy has no default — an undefined policy means no retry — so a host that wants Pi coding-agent’s numbers passes this explicitly.

muleEffectconstant

Section titled “muleEffect”
Signature
const muleEffect: MuleEffect;

Canonical Effect-native Mule value.

isContextOverflow()function

Section titled “isContextOverflow()”
Signature
function isContextOverflow(message, contextWindow?): boolean;

Apply Pi’s maintained context-overflow semantics to an exact Pi message.

Parameters

Section titled “Parameters”
Parameter Type
message AssistantMessage
contextWindow? number

Returns

Section titled “Returns”

boolean

run()function

Section titled “run()”
Signature
function run(input, listener?): Effect<MuleRunOutcome, MuleError>;

Run Pi’s model/tool loop inside Effect without changing Pi’s values.

Parameters

Section titled “Parameters”
Parameter Type Default value
input MuleRunInput undefined
listener MuleListener noListener

Returns

Section titled “Returns”

Effect<MuleRunOutcome, MuleError>

References

Section titled “References”

decodeProviderData

Section titled “decodeProviderData”

Re-exports decodeProviderData

streamModel

Section titled “streamModel”

Re-exports streamModel

isRetryableProviderRejection

Section titled “isRetryableProviderRejection”

Re-exports isRetryableProviderRejection

observeProviderStatus

Section titled “observeProviderStatus”

Re-exports observeProviderStatus

ProviderRejection

Section titled “ProviderRejection”

Re-exports ProviderRejection

ProviderStatusRecorder

Section titled “ProviderStatusRecorder”

Re-exports ProviderStatusRecorder

normalizeModel

Section titled “normalizeModel”

Re-exports normalizeModel

MuleCompletedTurn

Section titled “MuleCompletedTurn”

Re-exports MuleCompletedTurn

MuleResume

Section titled “MuleResume”

Re-exports MuleResume

MuleToolCheckpoint

Section titled “MuleToolCheckpoint”

Re-exports MuleToolCheckpoint

MuleError

Section titled “MuleError”

Re-exports MuleError

MuleEvent

Section titled “MuleEvent”

Re-exports MuleEvent

MuleIdentity

Section titled “MuleIdentity”

Re-exports MuleIdentity

MuleIdentityKind

Section titled “MuleIdentityKind”

Re-exports MuleIdentityKind

MuleRunOutcome

Section titled “MuleRunOutcome”

Re-exports MuleRunOutcome

MuleRunSettings

Section titled “MuleRunSettings”

Re-exports MuleRunSettings

MuleStreamFunction

Section titled “MuleStreamFunction”

Re-exports MuleStreamFunction

MuleToolExecutionPart

Section titled “MuleToolExecutionPart”

Re-exports MuleToolExecutionPart

MuleToolRejection

Section titled “MuleToolRejection”

Re-exports MuleToolRejection

MuleToolResult

Section titled “MuleToolResult”

Re-exports MuleToolResult