@fungi.computer/mule 0.0.2 → 0.1.0

package/README.md

@@ -40,6 +40,7 @@ const faux = fauxModel([fauxAssistantMessage("pong")]);
 const outcome = await mule.run(
   {
     model: faux.model,
+    retryable: faux.retryable,
     stream: faux.stream,
     systemPrompt: "Reply once.",
     messages: [{ role: "user", content: "ping", timestamp: 1 }],

package/dist/contract.d.ts

@@ -20,7 +20,8 @@ export type MuleError = {
 /** Result produced by a tool before Mule forms Pi's correlated result message. */
 export type MuleToolResult = {
     readonly content: (TextContent | ImageContent)[];
-    readonly details?: JsonValue | undefined;
+    /** Application payload for listeners, never part of a model message. */
+    readonly data?: JsonValue | undefined;
     readonly usage?: Usage | undefined;
     readonly isError: boolean;
     readonly terminate?: boolean | undefined;
@@ -79,6 +80,8 @@ export type MuleEvent = {
     readonly turn: MuleIdentity;
     readonly message: MuleIdentity;
     readonly value: Message;
+    /** Application payload independent of the completed model message. */
+    readonly data?: JsonValue | undefined;
 } | {
     readonly type: "tool_execution_start";
     readonly replay: "safe" | "unsafe";
@@ -147,20 +150,28 @@ export type MuleRunSettings = {
     /** Continue a durable, completed assistant turn before requesting another response. */
     readonly resume?: MuleResume | undefined;
     /** Pi stream options. Cancellation is the run's interruption, never a signal here. */
-    readonly streamOptions?: Omit<SimpleStreamOptions, "signal"> | undefined;
+    /** Provider-native retries are disabled; the typed host policy owns retry. */
+    readonly streamOptions?: Omit<SimpleStreamOptions, "signal" | "maxRetries"> | undefined;
     /** Maximum silence between provider stream events, in milliseconds. */
     readonly modelStreamIdleTimeoutMs?: number | undefined;
     readonly toolExecution?: "parallel" | "sequential" | undefined;
     /**
-     * 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`.
+     * Enabled policy counts and delays must be non-negative safe integers.
+     * Each assistant turn captures its policy before requesting the model.
      */
     readonly retry?: RetryPolicy | undefined;
+    /**
+     * Host-owned typed decision for this exact assistant message. Only true
+     * permits retry; unknown messages return false, never a decision from prose.
+     */
+    readonly retryable: (message: AssistantMessage) => boolean;
     /** Provider's bounded Retry-After evidence for the last assistant error. */
     readonly retryAfterMs?: ((message: AssistantMessage) => number | undefined) | undefined;
 };
-/** One observed Pi-retry event around a single assistant call. */
+/** One observed typed-retry event around a single assistant call. */
 export type MuleRetryObservation = {
     readonly type: "retry_scheduled";
     readonly run: MuleIdentity;

package/dist/effect.d.ts

@@ -1,3 +1,4 @@
+export { observeProviderStatus, type ProviderRejection, type ProviderStatusRecorder, } from "./provider-status.js";
 import type { AssistantMessage, Message, RetryPolicy, Tool, ToolCall } from "@earendil-works/pi-ai";
 import * as Effect from "effect/Effect";
 import * as Stream from "effect/Stream";

package/dist/effect.js

@@ -1,16 +1,15 @@
 import { nanoid } from "@fungi.computer/cairn";
+export { observeProviderStatus, } from "./provider-status.js";
 // Pi's root entry also evaluates its TypeBox validator compiler and model
 // stores; Mule needs only these leaf helpers, so it imports them directly and
 // keeps that work out of every host's startup.
 import { isContextOverflow as piIsContextOverflow } from "@earendil-works/pi-ai/utils/overflow";
-import { retryAssistantCall } from "@earendil-works/pi-ai/utils/retry";
+import { DEFAULT_MAX_AGENT_RETRY_DELAY_MS, retryDelayMs, } from "@earendil-works/pi-ai/utils/retry";
 import { normalizeContext } from "@earendil-works/pi-ai/utils/transcript";
 import * as Effect from "effect/Effect";
-import * as Schema from "effect/Schema";
 import * as Cause from "effect/Cause";
 import * as Result from "effect/Result";
 import * as Exit from "effect/Exit";
-import * as Fiber from "effect/Fiber";
 import * as Option from "effect/Option";
 import * as Semaphore from "effect/Semaphore";
 import * as Stream from "effect/Stream";
@@ -44,13 +43,6 @@ export function isContextOverflow(message, contextWindow) {
     return piIsContextOverflow(message, contextWindow);
 }
 const failure = (phase, message, cause) => ({ _tag: "MuleError", phase, message, cause });
-const muleErrorSchema = Schema.Struct({
-    _tag: Schema.Literal("MuleError"),
-    phase: Schema.Literals(["model", "tool", "control", "listener"]),
-    message: Schema.String,
-    cause: Schema.optionalKey(Schema.Unknown),
-});
-const isMuleError = (value) => Schema.is(muleErrorSchema)(value);
 const identity = (kind, parent) => ({ kind, value: `mule_${kind}_${nanoid()}`, parent });
 const noListener = () => Effect.void;
 function resultMessage(call, result) {
@@ -62,8 +54,6 @@ function resultMessage(call, result) {
         isError: result.isError,
         timestamp: Date.now(),
     };
-    if (result.details !== undefined)
-        message.details = result.details;
     if (result.usage !== undefined)
         message.usage = result.usage;
     return message;
@@ -174,6 +164,7 @@ function emitToolResult(executed, run, turn, emit) {
             turn,
             message: messageIdentity,
             value: message,
+            data: executed.result.data,
         });
         return message;
     });
@@ -261,6 +252,7 @@ function streamTurn(input, context, run, turn, emit, attempt) {
             input.streamOptions?.apiKey;
         const options = {
             ...input.streamOptions,
+            maxRetries: 0,
             signal: controller.signal,
         };
         if (resolvedApiKey !== undefined)
@@ -384,9 +376,8 @@ function streamTurn(input, context, run, turn, emit, attempt) {
     }));
 }
 /**
- * Run one assistant call with Pi's bounded retry (`retryAssistantCall`)
- * around it. `input.retry` undefined or disabled means `retryAssistantCall`
- * calls `streamTurn` exactly once and returns its result unchanged.
+ * Retry only the host's typed transient decision, using Pi's maintained delay.
+ * Effect owns interruption of both the active stream and the backoff sleep.
  *
  * Each attempt streams and is recorded exactly like any other turn (so a
  * failed attempt stays in the retained event log for inspection), but a
@@ -395,123 +386,91 @@ function streamTurn(input, context, run, turn, emit, attempt) {
  */
 function streamTurnWithRetry(input, context, run, turn, emit) {
     return Effect.gen(function* () {
-        const services = yield* Effect.context();
-        const runFork = Effect.runForkWith(services);
-        const runPromise = Effect.runPromiseWith(services);
+        // One turn owns one finite budget, even if its caller updates future policy.
+        const policy = input.retry === undefined ? undefined : { ...input.retry };
+        if (policy?.enabled &&
+            [
+                policy.maxRetries,
+                policy.baseDelayMs,
+                policy.maxAgentDelayMs ?? DEFAULT_MAX_AGENT_RETRY_DELAY_MS,
+            ].some((value) => !Number.isSafeInteger(value) || value < 0))
+            return yield* Effect.fail(failure("model", "Retry policy requires non-negative safe-integer counts and delays"));
         let latest;
-        let attempt = 0;
-        let retrySignal;
-        const reportRetry = (event) => input.onRetry === undefined
-            ? undefined
-            : runPromise(input.onRetry(event));
-        const callbacks = {
-            onRetryScheduled: async (attempt, maxAttempts, delayMs, errorMessage) => {
-                // Pi owns the only retry loop and its exponential schedule. A clean
-                // gateway 429 can request a longer delay; extend that same scheduled
-                // sleep (capped), never dispatch a second transport-level retry.
-                const after = latest === undefined
-                    ? undefined
-                    : input.retryAfterMs?.(latest.message);
-                const extra = after !== undefined &&
+        let calls = 0;
+        let retries = 0;
+        let finished = false;
+        let lastError;
+        const reportRetry = (event) => input.onRetry === undefined ? Effect.void : input.onRetry(event);
+        const finish = (success, finalError) => Effect.gen(function* () {
+            finished = true;
+            yield* reportRetry(finalError === undefined
+                ? { type: "retry_finished", run, turn, attempt: retries, success }
+                : {
+                    type: "retry_finished",
+                    run,
+                    turn,
+                    attempt: retries,
+                    success,
+                    finalError,
+                });
+        });
+        return yield* Effect.gen(function* () {
+            for (;;) {
+                if (latest !== undefined) {
+                    const index = context.indexOf(latest.message);
+                    if (index !== -1)
+                        context.splice(index, 1);
+                }
+                latest = yield* streamTurn(input, context, run, turn, emit, ++calls);
+                const message = latest.message;
+                if (message.stopReason !== "error" ||
+                    policy === undefined ||
+                    !policy.enabled ||
+                    retries >= policy.maxRetries) {
+                    if (retries > 0)
+                        yield* finish(message.stopReason !== "error" &&
+                            message.stopReason !== "aborted", message.stopReason === "error" ? message.errorMessage : undefined);
+                    return latest;
+                }
+                const retryable = yield* Effect.try({
+                    try: () => input.retryable(message),
+                    catch: (cause) => failure("model", "Typed model retry decision failed", cause),
+                });
+                if (!retryable) {
+                    if (retries > 0)
+                        yield* finish(false, message.errorMessage);
+                    return latest;
+                }
+                retries++;
+                lastError = message.errorMessage ?? "Unknown error";
+                const after = yield* Effect.try({
+                    try: () => input.retryAfterMs?.(message),
+                    catch: (cause) => failure("model", "Model retry delay observation failed", cause),
+                });
+                const delayMs = Math.max(retryDelayMs(policy, retries), after !== undefined &&
                     Number.isSafeInteger(after) &&
                     after >= 0 &&
                     after <= 60_000
-                    ? Math.max(0, after - delayMs)
-                    : 0;
-                await reportRetry({
+                    ? after
+                    : 0);
+                yield* reportRetry({
                     type: "retry_scheduled",
                     run,
                     turn,
-                    attempt,
-                    maxAttempts,
-                    delayMs: delayMs + extra,
-                    errorMessage,
+                    attempt: retries,
+                    maxAttempts: policy.maxRetries,
+                    delayMs,
+                    errorMessage: lastError,
                 });
-                if (extra > 0)
-                    await new Promise((resolve) => {
-                        const timer = setTimeout(() => {
-                            retrySignal?.removeEventListener("abort", abort);
-                            resolve();
-                        }, extra);
-                        const abort = () => {
-                            clearTimeout(timer);
-                            resolve();
-                        };
-                        retrySignal?.addEventListener("abort", abort, { once: true });
-                        if (retrySignal?.aborted)
-                            abort();
-                    });
-            },
-            onRetryAttemptStart: () => reportRetry({ type: "retry_attempt_started", run, turn, attempt }),
-            onRetryFinished: (success, attempt, finalError) => reportRetry(finalError === undefined
-                ? { type: "retry_finished", run, turn, attempt, success }
-                : {
-                    type: "retry_finished",
+                yield* Effect.sleep(delayMs);
+                yield* reportRetry({
+                    type: "retry_attempt_started",
                     run,
                     turn,
-                    attempt,
-                    success,
-                    finalError,
-                }),
-        };
-        const result = yield* Effect.tryPromise({
-            try: (signal) => {
-                retrySignal = signal;
-                // `retryAssistantCall` only threads `signal` through its own
-                // backoff sleep, never into an in-flight `produce`. Fork `streamTurn`
-                // as its own fiber and interrupt it on `signal` so a cancellation
-                // reaches an active call too, exactly like interrupting this fiber
-                // reached `streamTurn` before retry wrapped it.
-                const produce = async () => {
-                    if (latest !== undefined) {
-                        const index = context.indexOf(latest.message);
-                        if (index !== -1)
-                            context.splice(index, 1);
-                    }
-                    const fiber = runFork(streamTurn(input, context, run, turn, emit, ++attempt));
-                    const interrupt = () => {
-                        runFork(Fiber.interrupt(fiber));
-                    };
-                    if (signal.aborted)
-                        interrupt();
-                    else
-                        signal.addEventListener("abort", interrupt, { once: true });
-                    const exit = await runPromise(Fiber.await(fiber));
-                    signal.removeEventListener("abort", interrupt);
-                    // `streamTurn`'s own Effect failures (a transport exception, a
-                    // listener failure, or this fiber's own interruption) are not
-                    // Pi-protocol error messages for `retryAssistantCall` to classify:
-                    // unwrap and rethrow the original so the surrounding
-                    // `Effect.tryPromise` reports it unchanged, not behind a new
-                    // "Pi retry loop failed" layer.
-                    if (Exit.isFailure(exit)) {
-                        const error = Cause.findErrorOption(exit.cause);
-                        throw Option.isSome(error) ? error.value : Cause.squash(exit.cause);
-                    }
-                    latest = exit.value;
-                    return latest.message;
-                };
-                return retryAssistantCall(produce, input.retry, signal, callbacks);
-            },
-            catch: (cause) => isMuleError(cause)
-                ? cause
-                : failure("model", "Pi retry loop failed", cause),
-        });
-        // `produce` always runs at least once before `retryAssistantCall`
-        // settles, so `latest` is always set here.
-        if (latest === undefined)
-            return yield* Effect.die("streamTurnWithRetry: retryAssistantCall settled without calling produce");
-        const settled = latest;
-        if (result !== settled.message) {
-            // Pi normalizes an abort during backoff sleep into a fresh
-            // AssistantMessage (the failed attempt's content, `stopReason`
-            // forced to "aborted") instead of replaying `produce`. Reconcile the
-            // dangling failed entry `context` is still holding with that value.
-            const index = context.indexOf(settled.message);
-            if (index !== -1)
-                context[index] = result;
-        }
-        return { identity: settled.identity, message: result };
+                    attempt: retries,
+                });
+            }
+        }).pipe(Effect.onInterrupt(() => retries === 0 || finished ? Effect.void : finish(false, lastError)));
     });
 }
 const statusFor = (message) => message.stopReason === "aborted"

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import type { Message, Tool, ToolCall } from "@earendil-works/pi-ai";
+export { observeProviderStatus, type ProviderRejection, type ProviderStatusRecorder, } from "./provider-status.js";
 import type { MuleCompletedTurn, MuleEvent, MuleRunOutcome, MuleRunSettings, MuleToolExecutionPart, MuleToolRejection } from "./contract.js";
 export type { MuleCompletedTurn, MuleResume, MuleToolCheckpoint, MuleError, MuleEvent, MuleIdentity, MuleIdentityKind, MuleRunOutcome, MuleRunSettings, MuleStreamFunction, MuleToolExecutionPart, MuleToolRejection, MuleToolResult, } from "./contract.js";
 /** Promise listener adapted once into Mule's canonical Effect program. */

package/dist/index.js

@@ -1,3 +1,4 @@
+export { observeProviderStatus, } from "./provider-status.js";
 import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";

package/dist/provider-status.d.ts

@@ -0,0 +1,25 @@
+import type { SimpleStreamOptions } from "@earendil-works/pi-ai";
+/** Bounded provider evidence, never response bodies, headers or error prose. */
+export type ProviderRejection = Readonly<{
+    code: "usage-limit-reached";
+}> | Readonly<{
+    code: "provider_unavailable";
+    status?: number;
+}> | Readonly<{
+    code: "provider_rejected";
+    status: number;
+}>;
+/** One provider call's transport and parsed-event observations. */
+export type ProviderStatusRecorder = Readonly<{
+    /** Request-local fetch observer, retaining the supplied transport. */
+    fetch: typeof globalThis.fetch;
+    /** Pi's maintained parsed-event hook, composed with the supplied observer. */
+    onProviderStreamEvent: NonNullable<SimpleStreamOptions["onProviderStreamEvent"]>;
+    /** Latest typed failure evidence for this call, or no observed failure. */
+    rejection: () => ProviderRejection | undefined;
+}>;
+/**
+ * Observe one call's typed HTTP and parsed-event evidence. Pi owns stream
+ * decoding; this module retains no provider prose.
+ */
+export declare function observeProviderStatus(options?: Pick<SimpleStreamOptions, "fetch" | "onProviderStreamEvent">): ProviderStatusRecorder;

package/dist/provider-status.js

@@ -0,0 +1,94 @@
+import { Option, Schema } from "effect";
+const usageLimitCode = "subscription_sharing_usage_limit_exceeded";
+const providerError = Schema.Struct({
+    error: Schema.Struct({
+        code: Schema.String,
+    }),
+});
+const decodeFailedEvent = Schema.decodeUnknownOption(Schema.Struct({
+    type: Schema.Literal("response.failed"),
+    response: providerError,
+}));
+const decodeErrorReply = Schema.decodeUnknownOption(Schema.fromJsonString(providerError));
+const decodeBodyChunk = Schema.decodeUnknownSync(Schema.instanceOf(Uint8Array));
+const errorBodyBytes = 16 * 1024;
+/** Pi's pinned provider-request transient classes, kept as typed evidence. */
+const transientStatus = (status) => status === 408 ||
+    status === 409 ||
+    status === 429 ||
+    (status >= 500 && status <= 599);
+/** Retain Local's bounded error-copy observation; Pi still owns its response. */
+async function providerErrorCode(response) {
+    const body = response.clone().body;
+    if (body === null)
+        return undefined;
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let bytes = 0;
+    let text = "";
+    try {
+        for (;;) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            const value = decodeBodyChunk(chunk.value);
+            bytes += value.byteLength;
+            if (bytes > errorBodyBytes)
+                return undefined;
+            text += decoder.decode(value, { stream: true });
+        }
+        text += decoder.decode();
+        const decoded = decodeErrorReply(text);
+        return Option.isSome(decoded) ? decoded.value.error.code : undefined;
+    }
+    finally {
+        // A tee's cancellation may await the original consumer. Do not hold Pi's
+        // response hostage to that consumer; dispose only our observation branch.
+        void reader.cancel().catch((cause) => {
+            console.error("Provider error-copy cancellation failed", cause);
+        });
+        reader.releaseLock();
+    }
+}
+/**
+ * Observe one call's typed HTTP and parsed-event evidence. Pi owns stream
+ * decoding; this module retains no provider prose.
+ */
+export function observeProviderStatus(options) {
+    let rejection;
+    const upstream = options?.fetch ?? globalThis.fetch;
+    const observed = async (input, init) => {
+        rejection = undefined;
+        let response;
+        try {
+            response = await upstream(input, init);
+        }
+        catch (cause) {
+            if (init?.signal?.aborted !== true)
+                rejection = { code: "provider_unavailable" };
+            throw cause;
+        }
+        const status = response.status;
+        const code = status === 429 ? await providerErrorCode(response) : undefined;
+        rejection =
+            status < 400 || status > 599
+                ? undefined
+                : code === usageLimitCode
+                    ? { code: "usage-limit-reached" }
+                    : transientStatus(status) && code !== "insufficient_quota"
+                        ? { code: "provider_unavailable", status }
+                        : { code: "provider_rejected", status };
+        return response;
+    };
+    return {
+        fetch: Object.assign(observed, upstream),
+        onProviderStreamEvent: async (data, model) => {
+            const failed = decodeFailedEvent(data);
+            if (Option.isSome(failed) &&
+                failed.value.response.error.code === usageLimitCode)
+                rejection = { code: "usage-limit-reached" };
+            await options?.onProviderStreamEvent?.(data, model);
+        },
+        rejection: () => rejection,
+    };
+}

package/dist/testing.d.ts

@@ -1,11 +1,13 @@
 import { type FauxProviderHandle, type FauxResponseStep, type RegisterFauxProviderOptions } from "@earendil-works/pi-ai/providers/faux";
-import type { Api, Model } from "@earendil-works/pi-ai";
+import type { Api, AssistantMessage, Model } from "@earendil-works/pi-ai";
 /** Deterministic model and stream with Pi's observable response state. */
 export type FauxModel = Readonly<{
     /** Model supplied to Mule's run input. */
     model: Model<Api>;
     /** Bound Pi faux stream; never calls a remote provider. */
     stream: FauxProviderHandle["provider"]["streamSimple"];
+    /** Scripted replies have no typed provider failure; opt into retry explicitly. */
+    retryable: (message: AssistantMessage) => boolean;
     /** Replace the responses consumed by subsequent assistant calls. */
     setResponses: (replies: readonly FauxResponseStep[]) => void;
     /** Pi's call history and counters for deterministic assertions. */

package/dist/testing.js

@@ -6,6 +6,7 @@ export function fauxModel(replies, options = {}) {
     return {
         model: faux.getModel(),
         stream: faux.provider.streamSimple.bind(faux.provider),
+        retryable: () => false,
         setResponses: (responses) => {
             faux.setResponses([...responses]);
         },

package/docs/api/effect.md

@@ -39,7 +39,7 @@ type MuleRetryObservation =
     };
 ```
 
-One observed Pi-retry event around a single assistant call.
+One observed typed-retry event around a single assistant call.
 
 ---
 
@@ -273,6 +273,24 @@ Run Pi's model/tool loop inside Effect without changing Pi's values.
 
 ## References
 
+### observeProviderStatus
+
+Re-exports [observeProviderStatus](index.md#observeproviderstatus)
+
+---
+
+### ProviderRejection
+
+Re-exports [ProviderRejection](index.md#providerrejection)
+
+---
+
+### ProviderStatusRecorder
+
+Re-exports [ProviderStatusRecorder](index.md#providerstatusrecorder)
+
+---
+
 ### MuleCompletedTurn
 
 Re-exports [MuleCompletedTurn](index.md#mulecompletedturn)

package/docs/api/index.md

@@ -131,12 +131,14 @@ Result produced by a tool before Mule forms Pi's correlated result message.
 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 +278,7 @@ type MuleEvent =
       turn: MuleIdentity;
       message: MuleIdentity;
       value: Message;
+      data?: JsonValue;
     }
   | {
       type: "tool_execution_start";
@@ -403,9 +406,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`                       | -                                                               |
+| `data?`   | `JsonValue`                     | Application payload independent of the completed model message. |
+
 ---
 
 ##### Type Literal
@@ -628,10 +641,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 +666,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` |
+
+###### Returns
+
+`boolean`
 
 ##### retryAfterMs?
 
@@ -878,6 +912,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 +958,24 @@ const mule: Mule;
 ```
 
 Default Promise-facing Mule interface.
+
+## Functions
+
+### 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`, `"onProviderStreamEvent"` \| `"fetch"`\> |
+
+#### Returns
+
+[`ProviderStatusRecorder`](#providerstatusrecorder)

package/docs/api/testing.md

@@ -16,6 +16,7 @@
 type FauxModel = Readonly<{
   model: Model<Api>;
   stream: FauxProviderHandle["provider"]["streamSimple"];
+  retryable: (message) => boolean;
   setResponses: (replies) => void;
   state: FauxProviderHandle["state"];
 }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fungi.computer/mule",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "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"
   },