@fungi.computer/mule 0.0.2 → 0.1.1

package/docs/api/index.md

@@ -24,15 +24,16 @@ Pi's model stream function, supplied explicitly by the caller.
 
 #### Parameters
 
-| Parameter  | Type                  |
-| ---------- | --------------------- |
-| `model`    | `Model`\<`Api`\>      |
-| `context`  | `TranscriptContext`   |
-| `options?` | `SimpleStreamOptions` |
+| Parameter  | Type                                                   |
+| ---------- | ------------------------------------------------------ |
+| `model`    | [`Model`](effect.md#model-1)\<[`Api`](effect.md#api)\> |
+| `context`  | [`Context`](effect.md#context)                         |
+| `options?` | [`SimpleStreamOptions`](effect.md#simplestreamoptions) |
 
 #### Returns
 
-\| `AssistantMessageEventStream` \| `Promise`\<`AssistantMessageEventStream`\>
+\| [`AssistantMessageEventStream`](effect.md#assistantmessageeventstream) \|
+`Promise`\<[`AssistantMessageEventStream`](effect.md#assistantmessageeventstream)\>
 
 ---
 
@@ -128,15 +129,19 @@ Result produced by a tool before Mule forms Pi's correlated result message.
 ##### content
 
 ```ts
-readonly content: (TextContent | ImageContent)[];
+readonly content: (
+  | TextContent
+  | ImageContent)[];
 ```
 
-##### details?
+##### data?
 
 ```ts
-readonly optional details?: JsonValue;
+readonly optional data?: JsonValue;
 ```
 
+Application payload for listeners, never part of a model message.
+
 ##### usage?
 
 ```ts
@@ -276,6 +281,7 @@ type MuleEvent =
       turn: MuleIdentity;
       message: MuleIdentity;
       value: Message;
+      data?: JsonValue;
     }
   | {
       type: "tool_execution_start";
@@ -403,9 +409,19 @@ Lifecycle emitted around Pi values. Pi messages and events are not rewritten.
   turn: MuleIdentity;
   message: MuleIdentity;
   value: Message;
+  data?: JsonValue;
 }
 ```
 
+| Name      | Type                               | Description                                                     |
+| --------- | ---------------------------------- | --------------------------------------------------------------- |
+| `type`    | `"message_end"`                    | -                                                               |
+| `run`     | [`MuleIdentity`](#muleidentity)    | -                                                               |
+| `turn`    | [`MuleIdentity`](#muleidentity)    | -                                                               |
+| `message` | [`MuleIdentity`](#muleidentity)    | -                                                               |
+| `value`   | [`Message`](effect.md#message)     | -                                                               |
+| `data?`   | [`JsonValue`](effect.md#jsonvalue) | Application payload independent of the completed model message. |
+
 ---
 
 ##### Type Literal
@@ -546,12 +562,12 @@ Durable evidence for a call in an interrupted assistant turn.
 }
 ```
 
-| Name       | Type                                | Description                                            |
-| ---------- | ----------------------------------- | ------------------------------------------------------ |
-| `call`     | `ToolCall`                          | -                                                      |
-| `state`    | `"completed"`                       | -                                                      |
-| `result`   | [`MuleToolResult`](#muletoolresult) | -                                                      |
-| `message?` | `ToolResultMessage`                 | Present when the transcript message was committed too. |
+| Name       | Type                                               | Description                                            |
+| ---------- | -------------------------------------------------- | ------------------------------------------------------ |
+| `call`     | [`ToolCall`](effect.md#toolcall)                   | -                                                      |
+| `state`    | `"completed"`                                      | -                                                      |
+| `result`   | [`MuleToolResult`](#muletoolresult)                | -                                                      |
+| `message?` | [`ToolResultMessage`](effect.md#toolresultmessage) | Present when the transcript message was committed too. |
 
 ---
 
@@ -628,10 +644,10 @@ Continue a durable, completed assistant turn before requesting another response.
 ##### streamOptions?
 
 ```ts
-readonly optional streamOptions?: Omit<SimpleStreamOptions, "signal">;
+readonly optional streamOptions?: Omit<SimpleStreamOptions, "signal" | "maxRetries">;
 ```
 
-Pi stream options. Cancellation is the run's interruption, never a signal here.
+Provider-native retries are disabled; the typed host policy owns retry.
 
 ##### modelStreamIdleTimeoutMs?
 
@@ -653,9 +669,30 @@ readonly optional toolExecution?: "parallel" | "sequential";
 readonly optional retry?: RetryPolicy;
 ```
 
-Pi's bounded retry policy around each assistant call (`retryAssistantCall`).
+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`.
+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
+
+```ts
+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
+
+| Parameter | Type                                             |
+| --------- | ------------------------------------------------ |
+| `message` | [`AssistantMessage`](effect.md#assistantmessage) |
+
+###### Returns
+
+`boolean`
 
 ##### retryAfterMs?
 
@@ -667,9 +704,9 @@ Provider's bounded Retry-After evidence for the last assistant error.
 
 ###### Parameters
 
-| Parameter | Type               |
-| --------- | ------------------ |
-| `message` | `AssistantMessage` |
+| Parameter | Type                                             |
+| --------- | ------------------------------------------------ |
+| `message` | [`AssistantMessage`](effect.md#assistantmessage) |
 
 ###### Returns
 
@@ -815,10 +852,10 @@ Decode and authorize one exact Pi tool call before it can execute.
 
 ###### Parameters
 
-| Parameter | Type          |
-| --------- | ------------- |
-| `call`    | `ToolCall`    |
-| `signal`  | `AbortSignal` |
+| Parameter | Type                             |
+| --------- | -------------------------------- |
+| `call`    | [`ToolCall`](effect.md#toolcall) |
+| `signal`  | `AbortSignal`                    |
 
 ###### Returns
 
@@ -836,13 +873,13 @@ 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. |
+| 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`](effect.md#message)[]\> | Pull messages that should steer the active run at Pi's safe point.   |
+| `getFollowUpMessages()?` | (`signal`) => `Promise`\<readonly [`Message`](effect.md#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. |
 
 ---
 
@@ -878,6 +915,43 @@ the run, or with the abort reason (an `AbortError` when the reason is not an
 
 `Promise`\<[`MuleRunOutcome`](#mulerunoutcome)\>
 
+---
+
+### ProviderRejection
+
+```ts
+type ProviderRejection =
+  | Readonly<{
+      code: "usage-limit-reached";
+    }>
+  | Readonly<{
+      code: "provider_unavailable";
+      status?: number;
+    }>
+  | Readonly<{
+      code: "provider_rejected";
+      status: number;
+    }>;
+```
+
+Bounded provider evidence, never response bodies, headers or error prose.
+
+---
+
+### ProviderStatusRecorder
+
+```ts
+type ProviderStatusRecorder = Readonly<{
+  fetch: typeof globalThis.fetch;
+  onProviderStreamEvent: NonNullable<
+    SimpleStreamOptions["onProviderStreamEvent"]
+  >;
+  rejection: () => ProviderRejection | undefined;
+}>;
+```
+
+One provider call's transport and parsed-event observations.
+
 ## Variables
 
 ### mule
@@ -887,3 +961,80 @@ const mule: Mule;
 ```
 
 Default Promise-facing Mule interface.
+
+---
+
+### streamModel
+
+```ts
+const streamModel: MuleStreamFunction;
+```
+
+Pi's maintained stream behind Mule's structural provider port.
+
+## Functions
+
+### decodeProviderData()
+
+```ts
+function decodeProviderData(data): ProviderData;
+```
+
+Decode Pi's parsed request/event data before it enters an owned hook.
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `data`    | `unknown` |
+
+#### Returns
+
+[`ProviderData`](effect.md#providerdata)
+
+---
+
+### normalizeModel()
+
+```ts
+function normalizeModel<TApi>(model): Model<TApi>;
+```
+
+Validate a catalog model's opaque sampling fields before it enters Mule.
+
+#### Type Parameters
+
+| Type Parameter                          |
+| --------------------------------------- |
+| `TApi` _extends_ [`Api`](effect.md#api) |
+
+#### Parameters
+
+| Parameter | Type                                                                                                      |
+| --------- | --------------------------------------------------------------------------------------------------------- |
+| `model`   | `Omit`\<[`Model`](effect.md#model-1)\<`TApi`\>, `"samplingParams"` \| `"samplingParamsByThinkingLevel"`\> |
+
+#### Returns
+
+[`Model`](effect.md#model-1)\<`TApi`\>
+
+---
+
+### observeProviderStatus()
+
+```ts
+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
+
+| Parameter  | Type                                                                                                     |
+| ---------- | -------------------------------------------------------------------------------------------------------- |
+| `options?` | `Pick`\<[`SimpleStreamOptions`](effect.md#simplestreamoptions), `"onProviderStreamEvent"` \| `"fetch"`\> |
+
+#### Returns
+
+[`ProviderStatusRecorder`](#providerstatusrecorder)

package/docs/api/testing.md

@@ -10,14 +10,241 @@
 
 ## Type Aliases
 
+### FauxModelDefinition
+
+```ts
+type FauxModelDefinition = object;
+```
+
+Credential-free model definition for the scripted provider.
+
+#### Properties
+
+##### id
+
+```ts
+id: string;
+```
+
+##### name?
+
+```ts
+optional name?: string;
+```
+
+##### reasoning?
+
+```ts
+optional reasoning?: boolean;
+```
+
+##### input?
+
+```ts
+optional input?: ("text" | "image")[];
+```
+
+##### inputLimits?
+
+```ts
+optional inputLimits?: Model<Api>["inputLimits"];
+```
+
+##### cost?
+
+```ts
+optional cost?: object;
+```
+
+###### input
+
+```ts
+input: number;
+```
+
+###### output
+
+```ts
+output: number;
+```
+
+###### cacheRead
+
+```ts
+cacheRead: number;
+```
+
+###### cacheWrite
+
+```ts
+cacheWrite: number;
+```
+
+##### contextWindow?
+
+```ts
+optional contextWindow?: number;
+```
+
+##### maxTokens?
+
+```ts
+optional maxTokens?: number;
+```
+
+---
+
+### RegisterFauxProviderOptions
+
+```ts
+type RegisterFauxProviderOptions = object;
+```
+
+Scripted provider configuration, independent of provider SDK declarations.
+
+#### Properties
+
+##### api?
+
+```ts
+optional api?: string;
+```
+
+##### provider?
+
+```ts
+optional provider?: string;
+```
+
+##### models?
+
+```ts
+optional models?: FauxModelDefinition[];
+```
+
+##### deferred?
+
+```ts
+optional deferred?: object;
+```
+
+###### pendingFetches?
+
+```ts
+optional pendingFetches?: number;
+```
+
+###### pollAfterMs?
+
+```ts
+optional pollAfterMs?: number;
+```
+
+##### tokensPerSecond?
+
+```ts
+optional tokensPerSecond?: number;
+```
+
+##### tokenSize?
+
+```ts
+optional tokenSize?: object;
+```
+
+###### min?
+
+```ts
+optional min?: number;
+```
+
+###### max?
+
+```ts
+optional max?: number;
+```
+
+---
+
+### FauxProviderState
+
+```ts
+type FauxProviderState = object;
+```
+
+Counters retained by the scripted provider.
+
+#### Properties
+
+##### callCount
+
+```ts
+callCount: number;
+```
+
+##### deferredFetchCount
+
+```ts
+deferredFetchCount: number;
+```
+
+##### cancelledDeferred
+
+```ts
+cancelledDeferred: NonNullable < AssistantMessage["deferred"] > [];
+```
+
+---
+
+### FauxResponseFactory
+
+```ts
+type FauxResponseFactory = (
+  context,
+  options,
+  state,
+  model,
+) => AssistantMessage | Promise<AssistantMessage>;
+```
+
+Function that observes a model request and supplies a scripted reply.
+
+#### Parameters
+
+| Parameter | Type                                                                       |
+| --------- | -------------------------------------------------------------------------- |
+| `context` | [`Context`](effect.md#context)                                             |
+| `options` | `Parameters`\<[`MuleStreamFunction`](index.md#mulestreamfunction)\>\[`2`\] |
+| `state`   | [`FauxProviderState`](#fauxproviderstate)                                  |
+| `model`   | [`Model`](effect.md#model-1)\<[`Api`](effect.md#api)\>                     |
+
+#### Returns
+
+\| [`AssistantMessage`](effect.md#assistantmessage) \|
+`Promise`\<[`AssistantMessage`](effect.md#assistantmessage)\>
+
+---
+
+### FauxResponseStep
+
+```ts
+type FauxResponseStep = AssistantMessage | FauxResponseFactory;
+```
+
+A scripted reply or a factory that observes the normalized request.
+
+---
+
 ### FauxModel
 
 ```ts
 type FauxModel = Readonly<{
   model: Model<Api>;
-  stream: FauxProviderHandle["provider"]["streamSimple"];
+  stream: (...args) => AssistantMessageEventStream;
+  retryable: (message) => boolean;
   setResponses: (replies) => void;
-  state: FauxProviderHandle["state"];
+  state: FauxProviderState;
+  getPendingResponseCount: () => number;
 }>;
 ```
 
@@ -35,10 +262,10 @@ Create a credential-free model for tests and runnable examples.
 
 #### Parameters
 
-| Parameter | Type                          |
-| --------- | ----------------------------- |
-| `replies` | readonly `FauxResponseStep`[] |
-| `options` | `RegisterFauxProviderOptions` |
+| Parameter | Type                                                          |
+| --------- | ------------------------------------------------------------- |
+| `replies` | readonly [`FauxResponseStep`](#fauxresponsestep)[]            |
+| `options` | [`RegisterFauxProviderOptions`](#registerfauxprovideroptions) |
 
 #### Returns
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fungi.computer/mule",
-  "version": "0.0.2",
+  "version": "0.1.1",
   "author": "Levi <levi@technomancy.dev>",
   "description": "Effect-native Pi model and tool loop",
   "type": "module",
@@ -28,8 +28,8 @@
     "THIRD_PARTY_NOTICES"
   ],
   "dependencies": {
-    "@earendil-works/pi-ai": "0.99.2",
-    "@fungi.computer/cairn": "0.0.1",
+    "@earendil-works/pi-ai": "1.3.0",
+    "@fungi.computer/cairn": "0.1.0",
     "effect": "4.0.2",
     "typebox": "1.3.27"
   },