@fungi.computer/mule 0.0.0-stage → 0.0.1

package/docs/api/index.md

@@ -0,0 +1,889 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/mule**](README.md)
+
+---
+
+[@fungi.computer/mule](README.md) / index
+
+# index
+
+## Type Aliases
+
+### MuleStreamFunction
+
+```ts
+type MuleStreamFunction = (
+  model,
+  context,
+  options?,
+) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;
+```
+
+Pi's model stream function, supplied explicitly by the caller.
+
+#### Parameters
+
+| Parameter  | Type                  |
+| ---------- | --------------------- |
+| `model`    | `Model`\<`Api`\>      |
+| `context`  | `TranscriptContext`   |
+| `options?` | `SimpleStreamOptions` |
+
+#### Returns
+
+\| `AssistantMessageEventStream` \| `Promise`\<`AssistantMessageEventStream`\>
+
+---
+
+### MuleIdentityKind
+
+```ts
+type MuleIdentityKind =
+  "run" | "turn" | "message" | "tool_call" | "tool_result" | "terminal";
+```
+
+Causal roles added around Pi's model and tool loop.
+
+---
+
+### MuleIdentity
+
+```ts
+type MuleIdentity = object;
+```
+
+One run-local causal identity.
+
+#### Properties
+
+##### kind
+
+```ts
+readonly kind: MuleIdentityKind;
+```
+
+##### value
+
+```ts
+readonly value: string;
+```
+
+##### parent?
+
+```ts
+readonly optional parent?: MuleIdentity;
+```
+
+---
+
+### MuleError
+
+```ts
+type MuleError = object;
+```
+
+Expected failure from Mule's model, tool, control, or listener work.
+
+#### Properties
+
+##### \_tag
+
+```ts
+readonly _tag: "MuleError";
+```
+
+##### phase
+
+```ts
+readonly phase: "model" | "tool" | "control" | "listener";
+```
+
+##### message
+
+```ts
+readonly message: string;
+```
+
+##### cause?
+
+```ts
+readonly optional cause?: unknown;
+```
+
+The underlying rejection or thrown value, when one exists.
+
+---
+
+### MuleToolResult
+
+```ts
+type MuleToolResult = object;
+```
+
+Result produced by a tool before Mule forms Pi's correlated result message.
+
+#### Properties
+
+##### content
+
+```ts
+readonly content: (TextContent | ImageContent)[];
+```
+
+##### details?
+
+```ts
+readonly optional details?: JsonValue;
+```
+
+##### usage?
+
+```ts
+readonly optional usage?: Usage;
+```
+
+##### isError
+
+```ts
+readonly isError: boolean;
+```
+
+##### terminate?
+
+```ts
+readonly optional terminate?: boolean;
+```
+
+---
+
+### MuleToolExecutionPart
+
+```ts
+type MuleToolExecutionPart =
+  | {
+      type: "update";
+      result: MuleToolResult;
+    }
+  | {
+      type: "result";
+      result: MuleToolResult;
+    };
+```
+
+Progress or terminal output from one tool execution.
+
+---
+
+### MuleToolRejection
+
+```ts
+type MuleToolRejection = object;
+```
+
+A real parser or authorization rejection produced before tool execution.
+
+#### Properties
+
+##### message
+
+```ts
+readonly message: string;
+```
+
+##### terminate?
+
+```ts
+readonly optional terminate?: boolean;
+```
+
+---
+
+### MuleCompletedTurn
+
+```ts
+type MuleCompletedTurn = object;
+```
+
+Facts from a completed Pi turn supplied to the retained stop hook.
+
+#### Properties
+
+##### message
+
+```ts
+readonly message: AssistantMessage;
+```
+
+##### toolResults
+
+```ts
+readonly toolResults: readonly ToolResultMessage[];
+```
+
+##### context
+
+```ts
+readonly context: readonly Message[];
+```
+
+##### newMessages
+
+```ts
+readonly newMessages: readonly Message[];
+```
+
+---
+
+### MuleEvent
+
+```ts
+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;
+    }
+  | {
+      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
+
+```ts
+{
+  type: "run_start";
+  run: MuleIdentity;
+}
+```
+
+---
+
+##### Type Literal
+
+```ts
+{
+  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`](#muleidentity) | -                                                                 |
+| `turn`         | [`MuleIdentity`](#muleidentity) | -                                                                 |
+| `attempt`      | `number`                        | -                                                                 |
+| `systemPrompt` | `string`                        | -                                                                 |
+
+---
+
+##### Type Literal
+
+```ts
+{
+  type: "turn_start";
+  run: MuleIdentity;
+  turn: MuleIdentity;
+}
+```
+
+---
+
+##### Type Literal
+
+```ts
+{
+  type: "message_start";
+  run: MuleIdentity;
+  turn: MuleIdentity;
+  message: MuleIdentity;
+  value: Message;
+}
+```
+
+---
+
+##### Type Literal
+
+```ts
+{
+  type: "message_update";
+  run: MuleIdentity;
+  turn: MuleIdentity;
+  message: MuleIdentity;
+  value: AssistantMessage;
+  event: AssistantMessageEvent;
+}
+```
+
+---
+
+##### Type Literal
+
+```ts
+{
+  type: "message_end";
+  run: MuleIdentity;
+  turn: MuleIdentity;
+  message: MuleIdentity;
+  value: Message;
+}
+```
+
+---
+
+##### Type Literal
+
+```ts
+{
+  type: "tool_execution_start";
+  replay: "safe" | "unsafe";
+  run: MuleIdentity;
+  turn: MuleIdentity;
+  toolCall: MuleIdentity;
+  call: ToolCall;
+}
+```
+
+---
+
+##### Type Literal
+
+```ts
+{
+  type: "tool_execution_update";
+  run: MuleIdentity;
+  turn: MuleIdentity;
+  toolCall: MuleIdentity;
+  call: ToolCall;
+  result: MuleToolResult;
+}
+```
+
+---
+
+##### Type Literal
+
+```ts
+{
+  type: "tool_execution_end";
+  run: MuleIdentity;
+  turn: MuleIdentity;
+  toolCall: MuleIdentity;
+  call: ToolCall;
+  result: MuleToolResult;
+}
+```
+
+---
+
+##### Type Literal
+
+```ts
+{
+  type: "turn_end";
+  run: MuleIdentity;
+  turn: MuleIdentity;
+  message: AssistantMessage;
+  toolResults: readonly ToolResultMessage[];
+}
+```
+
+---
+
+##### Type Literal
+
+```ts
+{
+  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`](#muleidentity)              | -                                                                                                                                                                                                 |
+| `terminal` | [`MuleIdentity`](#muleidentity)              | -                                                                                                                                                                                                 |
+| `outcome`  | `"completed"` \| `"cancelled"` \| `"failed"` | -                                                                                                                                                                                                 |
+
+---
+
+### MuleToolCheckpoint
+
+```ts
+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
+
+##### Type Literal
+
+```ts
+{
+  call: ToolCall;
+  state: "pending";
+}
+```
+
+---
+
+##### Type Literal
+
+```ts
+{
+  call: ToolCall;
+  state: "started";
+  replay: "safe" | "unsafe";
+}
+```
+
+---
+
+##### Type Literal
+
+```ts
+{
+  call: ToolCall;
+  state: "completed";
+  result: MuleToolResult;
+  message?: ToolResultMessage;
+}
+```
+
+| Name       | Type                                | Description                                            |
+| ---------- | ----------------------------------- | ------------------------------------------------------ |
+| `call`     | `ToolCall`                          | -                                                      |
+| `state`    | `"completed"`                       | -                                                      |
+| `result`   | [`MuleToolResult`](#muletoolresult) | -                                                      |
+| `message?` | `ToolResultMessage`                 | Present when the transcript message was committed too. |
+
+---
+
+### MuleResume
+
+```ts
+type MuleResume = object;
+```
+
+Completed assistant turn recovered by the transcript owner, before its next
+model call.
+
+#### Properties
+
+##### message
+
+```ts
+readonly message: AssistantMessage;
+```
+
+##### tools
+
+```ts
+readonly tools: readonly MuleToolCheckpoint[];
+```
+
+---
+
+### MuleRunSettings
+
+```ts
+type MuleRunSettings = object;
+```
+
+Run inputs that are identical on the Promise and Effect roots.
+
+#### Properties
+
+##### model
+
+```ts
+readonly model: Model<Api>;
+```
+
+##### stream?
+
+```ts
+readonly optional stream?: MuleStreamFunction;
+```
+
+Override Pi's default `streamSimple`, primarily for explicit providers and
+tests.
+
+##### systemPrompt
+
+```ts
+readonly systemPrompt: string;
+```
+
+##### messages
+
+```ts
+readonly messages: readonly Message[];
+```
+
+##### resume?
+
+```ts
+readonly optional resume?: MuleResume;
+```
+
+Continue a durable, completed assistant turn before requesting another response.
+
+##### streamOptions?
+
+```ts
+readonly optional streamOptions?: Omit<SimpleStreamOptions, "signal">;
+```
+
+Pi stream options. Cancellation is the run's interruption, never a signal here.
+
+##### modelStreamIdleTimeoutMs?
+
+```ts
+readonly optional modelStreamIdleTimeoutMs?: number;
+```
+
+Maximum silence between provider stream events, in milliseconds.
+
+##### toolExecution?
+
+```ts
+readonly optional toolExecution?: "parallel" | "sequential";
+```
+
+##### retry?
+
+```ts
+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?
+
+```ts
+readonly optional retryAfterMs?: (message) => number | undefined;
+```
+
+Provider's bounded Retry-After evidence for the last assistant error.
+
+###### Parameters
+
+| Parameter | Type               |
+| --------- | ------------------ |
+| `message` | `AssistantMessage` |
+
+###### Returns
+
+`number` \| `undefined`
+
+---
+
+### MuleRunOutcome
+
+```ts
+type MuleRunOutcome = object;
+```
+
+Honest terminal result of one Mule invocation.
+
+#### Properties
+
+##### status
+
+```ts
+readonly status: "completed" | "cancelled" | "failed";
+```
+
+##### run
+
+```ts
+readonly run: MuleIdentity;
+```
+
+##### terminal
+
+```ts
+readonly terminal: MuleIdentity;
+```
+
+##### message
+
+```ts
+readonly message: AssistantMessage;
+```
+
+##### messages
+
+```ts
+readonly messages: readonly Message[];
+```
+
+---
+
+### MulePromiseListener
+
+```ts
+type MulePromiseListener = (event, signal) => Promise<void> | void;
+```
+
+Promise listener adapted once into Mule's canonical Effect program.
+
+#### Parameters
+
+| Parameter | Type                      |
+| --------- | ------------------------- |
+| `event`   | [`MuleEvent`](#muleevent) |
+| `signal`  | `AbortSignal`             |
+
+#### Returns
+
+`Promise`\<`void`\> \| `void`
+
+---
+
+### MuleToolPreparation
+
+```ts
+type MuleToolPreparation =
+  | {
+      status: "prepared";
+      execute: (signal) => AsyncIterable<MuleToolExecutionPart>;
+    }
+  | (object & MuleToolRejection);
+```
+
+Outcome of preparing one exact Pi tool call.
+
+#### Union Members
+
+##### Type Literal
+
+```ts
+{
+  status: "prepared";
+  execute: (signal) => AsyncIterable<MuleToolExecutionPart>;
+}
+```
+
+| Name        | Type                                                                               | Description                                                       |
+| ----------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `status`    | `"prepared"`                                                                       | -                                                                 |
+| `execute()` | (`signal`) => `AsyncIterable`\<[`MuleToolExecutionPart`](#muletoolexecutionpart)\> | Run the already-decoded and authorized call; abort ends it early. |
+
+---
+
+`object` & [`MuleToolRejection`](#muletoolrejection)
+
+---
+
+### MuleTool
+
+```ts
+type MuleTool = object;
+```
+
+Pi tool declaration paired with its Promise preparation door.
+
+#### Properties
+
+##### descriptor
+
+```ts
+readonly descriptor: Tool;
+```
+
+##### replay?
+
+```ts
+readonly optional replay?: "safe" | "unsafe";
+```
+
+Only read-only or explicitly idempotent tools may opt into crash replay.
+
+##### executionMode?
+
+```ts
+readonly optional executionMode?: "parallel" | "sequential";
+```
+
+##### prepare
+
+```ts
+readonly prepare: (call, signal) => Promise<MuleToolPreparation>;
+```
+
+Decode and authorize one exact Pi tool call before it can execute.
+
+###### Parameters
+
+| Parameter | Type          |
+| --------- | ------------- |
+| `call`    | `ToolCall`    |
+| `signal`  | `AbortSignal` |
+
+###### Returns
+
+`Promise`\<[`MuleToolPreparation`](#muletoolpreparation)\>
+
+---
+
+### MuleRunInput
+
+```ts
+type MuleRunInput = MuleRunSettings & object;
+```
+
+Inputs for one complete Pi model/tool loop through the Promise facade.
+
+#### Type Declaration
+
+| Name                     | Type                                                           | Description                                                          |
+| ------------------------ | -------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `tools?`                 | readonly [`MuleTool`](#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. |
+
+---
+
+### Mule
+
+```ts
+type Mule = object;
+```
+
+Promise-facing Mule interface.
+
+#### Properties
+
+##### run
+
+```ts
+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
+
+| Parameter   | Type                                          |
+| ----------- | --------------------------------------------- |
+| `input`     | [`MuleRunInput`](#muleruninput)               |
+| `listener?` | [`MulePromiseListener`](#mulepromiselistener) |
+| `signal?`   | `AbortSignal`                                 |
+
+###### Returns
+
+`Promise`\<[`MuleRunOutcome`](#mulerunoutcome)\>
+
+## Variables
+
+### mule
+
+```ts
+const mule: Mule;
+```
+
+Default Promise-facing Mule interface.