@fungi.computer/mule 0.1.0 → 0.2.0

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,7 +129,9 @@ Result produced by a tool before Mule forms Pi's correlated result message.
 ##### content
 
 ```ts
-readonly content: (TextContent | ImageContent)[];
+readonly content: (
+  | TextContent
+  | ImageContent)[];
 ```
 
 ##### data?
@@ -410,14 +413,14 @@ Lifecycle emitted around Pi values. Pi messages and events are not rewritten.
 }
 ```
 
-| Name      | Type                            | Description                                                     |
-| --------- | ------------------------------- | --------------------------------------------------------------- |
-| `type`    | `"message_end"`                 | -                                                               |
-| `run`     | [`MuleIdentity`](#muleidentity) | -                                                               |
-| `turn`    | [`MuleIdentity`](#muleidentity) | -                                                               |
-| `message` | [`MuleIdentity`](#muleidentity) | -                                                               |
-| `value`   | `Message`                       | -                                                               |
-| `data?`   | `JsonValue`                     | Application payload independent of the completed model message. |
+| 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. |
 
 ---
 
@@ -559,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. |
 
 ---
 
@@ -654,6 +657,18 @@ readonly optional modelStreamIdleTimeoutMs?: number;
 
 Maximum silence between provider stream events, in milliseconds.
 
+##### modelStreamLimits?
+
+```ts
+readonly optional modelStreamLimits?: Partial<{
+  firstEventMs: number;
+  attemptMs: number;
+  outputBytes: number;
+}>;
+```
+
+Trusted per-attempt safety limits may only tighten Mule's defaults.
+
 ##### toolExecution?
 
 ```ts
@@ -683,9 +698,9 @@ retry; unknown messages return false, never a decision from prose.
 
 ###### Parameters
 
-| Parameter | Type               |
-| --------- | ------------------ |
-| `message` | `AssistantMessage` |
+| Parameter | Type                                             |
+| --------- | ------------------------------------------------ |
+| `message` | [`AssistantMessage`](effect.md#assistantmessage) |
 
 ###### Returns
 
@@ -701,9 +716,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
 
@@ -751,6 +766,14 @@ readonly message: AssistantMessage;
 readonly messages: readonly Message[];
 ```
 
+##### modelLimitReason?
+
+```ts
+readonly optional modelLimitReason?: string;
+```
+
+Mule-owned limit diagnostic, not untrusted provider prose.
+
 ---
 
 ### MulePromiseListener
@@ -849,10 +872,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
 
@@ -870,13 +893,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. |
 
 ---
 
@@ -959,8 +982,64 @@ 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
@@ -972,9 +1051,9 @@ decoding; this module retains no provider prose.
 
 #### Parameters
 
-| Parameter  | Type                                                                    |
-| ---------- | ----------------------------------------------------------------------- |
-| `options?` | `Pick`\<`SimpleStreamOptions`, `"onProviderStreamEvent"` \| `"fetch"`\> |
+| Parameter  | Type                                                                                                     |
+| ---------- | -------------------------------------------------------------------------------------------------------- |
+| `options?` | `Pick`\<[`SimpleStreamOptions`](effect.md#simplestreamoptions), `"onProviderStreamEvent"` \| `"fetch"`\> |
 
 #### Returns
 

package/docs/api/testing.md

@@ -10,15 +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;
 }>;
 ```
 
@@ -36,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.1.0",
+  "version": "0.2.0",
   "author": "Levi <levi@technomancy.dev>",
   "description": "Effect-native Pi model and tool loop",
   "type": "module",