@fungi.computer/mule 0.2.0 → 0.2.2

package/README.md

@@ -12,10 +12,10 @@ npm install @fungi.computer/mule
 ```
 
 The package ships ESM only and depends on `effect` and Pi
-(`@earendil-works/pi-ai`) at runtime, plus `@fungi.computer/cairn` for IDs. Mule
-does not require or install the MCP SDK. Consumers that type-check dependency
-declarations (`skipLibCheck: false`) must install Pi’s Google GenAI optional
-declaration dependency themselves:
+(`@earendil-works/pi-ai`) at runtime, plus TypeBox and `@fungi.computer/cairn`
+for IDs. Mule does not require or install the MCP SDK. Consumers that type-check
+dependency declarations (`skipLibCheck: false`) must install Pi’s Google GenAI
+optional declaration dependency themselves:
 
 ```sh
 npm install --save-dev @modelcontextprotocol/sdk

package/dist/effect.d.ts

@@ -1,6 +1,6 @@
 export { decodeProviderData } from "./provider-data.js";
 export { streamPi as streamModel } from "./provider.js";
-export { observeProviderStatus, type ProviderRejection, type ProviderStatusRecorder, } from "./provider-status.js";
+export { isRetryableProviderRejection, observeProviderStatus, type ProviderRejection, type ProviderStatusRecorder, } from "./provider-status.js";
 export { normalizeModel } from "./provider-model.js";
 import type { AssistantMessage, Message, RetryPolicy, Tool, ToolCall } from "./types.js";
 import * as Effect from "effect/Effect";

package/dist/effect.js

@@ -2,7 +2,7 @@ import { normalizeContext } from "@earendil-works/pi-ai/utils/transcript";
 export { decodeProviderData } from "./provider-data.js";
 export { streamPi as streamModel } from "./provider.js";
 import { nanoid } from "@fungi.computer/cairn";
-export { observeProviderStatus, } from "./provider-status.js";
+export { isRetryableProviderRejection, 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.
@@ -547,12 +547,16 @@ function streamTurnWithRetry(input, context, run, turn, emit) {
                     try: () => input.retryAfterMs?.(message),
                     catch: (cause) => failure("model", "Model retry delay observation failed", cause),
                 });
-                const delayMs = Math.max(retryDelayMs(policy, retries), after !== undefined &&
+                const minimumDelayMs = Math.max(retryDelayMs(policy, retries), after !== undefined &&
                     Number.isSafeInteger(after) &&
                     after >= 0 &&
                     after <= 60_000
                     ? after
                     : 0);
+                // Add rather than subtract jitter: a provider's Retry-After is a floor.
+                // Jitter stops at one minute; a longer explicit host policy stays intact.
+                const jitterMs = Math.min(1_000, minimumDelayMs / 4, Math.max(0, 60_000 - minimumDelayMs));
+                const delayMs = minimumDelayMs + Math.floor(Math.random() * jitterMs);
                 yield* reportRetry({
                     type: "retry_scheduled",
                     run,

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { decodeProviderData } from "./provider-data.js";
 export { streamPi as streamModel } from "./provider.js";
 export { normalizeModel } from "./provider-model.js";
 import type { Message, Tool, ToolCall } from "./types.js";
-export { observeProviderStatus, type ProviderRejection, type ProviderStatusRecorder, } from "./provider-status.js";
+export { isRetryableProviderRejection, 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,7 +1,7 @@
 export { decodeProviderData } from "./provider-data.js";
 export { streamPi as streamModel } from "./provider.js";
 export { normalizeModel } from "./provider-model.js";
-export { observeProviderStatus, } from "./provider-status.js";
+export { isRetryableProviderRejection, 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

@@ -1,7 +1,15 @@
-import type { SimpleStreamOptions } from "./types.js";
+import type { AssistantMessage, SimpleStreamOptions } from "./types.js";
 /** Bounded provider evidence, never response bodies, headers or error prose. */
 export type ProviderRejection = Readonly<{
     code: "usage-limit-reached";
+    /** Provider-declared epoch milliseconds, absent when unknown. */
+    resetAt?: number;
+    limit?: "five_hour" | "seven_day" | "seven_day_opus" | "seven_day_sonnet";
+}> | Readonly<{
+    code: "rate-limit";
+    retryAfterMs?: number;
+}> | Readonly<{
+    code: "overloaded";
 }> | Readonly<{
     code: "provider_unavailable";
     status?: number;
@@ -9,6 +17,8 @@ export type ProviderRejection = Readonly<{
     code: "provider_rejected";
     status: number;
 }>;
+/** Retry only typed transient failures, never usage exhaustion or rejection. */
+export declare function isRetryableProviderRejection(rejection: ProviderRejection | undefined): boolean;
 /** One provider call's transport and parsed-event observations. */
 export type ProviderStatusRecorder = Readonly<{
     /** Request-local fetch observer, retaining the supplied transport. */
@@ -16,7 +26,7 @@ export type ProviderStatusRecorder = Readonly<{
     /** 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;
+    rejection: (message?: AssistantMessage) => ProviderRejection | undefined;
 }>;
 /**
  * Observe one call's typed HTTP and parsed-event evidence. Pi owns stream

package/dist/provider-status.js

@@ -1,8 +1,9 @@
-import { Option, Schema } from "effect";
+import { DateTime, Option, Schema } from "effect";
 const usageLimitCode = "subscription_sharing_usage_limit_exceeded";
 const providerError = Schema.Struct({
     error: Schema.Struct({
-        code: Schema.String,
+        code: Schema.optional(Schema.String),
+        type: Schema.optional(Schema.String),
     }),
 });
 const decodeFailedEvent = Schema.decodeUnknownOption(Schema.Struct({
@@ -10,15 +11,80 @@ const decodeFailedEvent = Schema.decodeUnknownOption(Schema.Struct({
     response: providerError,
 }));
 const decodeErrorReply = Schema.decodeUnknownOption(Schema.fromJsonString(providerError));
+const decodeErrorEvent = Schema.decodeUnknownOption(Schema.Struct({
+    type: Schema.Literal("error"),
+    status: Schema.optional(Schema.Number.check(Schema.isInt(), Schema.isBetween({ minimum: 100, maximum: 599 }))),
+    code: Schema.optional(Schema.String),
+    error: Schema.optional(providerError.fields.error),
+}));
 const decodeBodyChunk = Schema.decodeUnknownSync(Schema.instanceOf(Uint8Array));
 const errorBodyBytes = 16 * 1024;
+const decodeSeconds = Schema.decodeUnknownOption(Schema.NumberFromString.check(Schema.isBetween({ minimum: 0, maximum: 60 })));
+const decodeReset = Schema.decodeUnknownOption(Schema.NumberFromString.check(Schema.isInt(), Schema.isBetween({ minimum: 0, maximum: 8_640_000_000_000 })));
+const decodeLimit = Schema.decodeUnknownOption(Schema.Literals([
+    "five_hour",
+    "seven_day",
+    "seven_day_opus",
+    "seven_day_sonnet",
+]));
+const decodeRejected = Schema.decodeUnknownOption(Schema.Literal("rejected"));
+const decodeExhausted = Schema.decodeUnknownOption(Schema.Literal("0"));
+const decodeDate = Schema.decodeUnknownOption(Schema.DateTimeUtcFromString);
+const decodeOverloaded = Schema.decodeUnknownOption(
+// https://docs.anthropic.com/en/api/errors#http-errors
+Schema.Struct({
+    type: Schema.Literal("error"),
+    error: Schema.Struct({ type: Schema.Literal("overloaded_error") }),
+}));
+function resetDelay(value, now) {
+    const date = decodeDate(value);
+    if (Option.isNone(date))
+        return undefined;
+    const delay = DateTime.toEpochMillis(date.value) - now;
+    return delay >= 0 && delay <= 60_000 ? Math.ceil(delay) : undefined;
+}
+function rateLimit(headers) {
+    const now = Date.now();
+    const header = headers.get("retry-after");
+    const seconds = decodeSeconds(header);
+    let delay = Option.isSome(seconds)
+        ? Math.ceil(seconds.value * 1000)
+        : resetDelay(header, now);
+    // API-key rate windows are not subscription caps. Only an explicitly
+    // exhausted dimension supplies a retry floor; missing facts stay unknown.
+    for (const dimension of [
+        "requests",
+        "tokens",
+        "input-tokens",
+        "output-tokens",
+    ]) {
+        if (Option.isNone(decodeExhausted(headers.get(`anthropic-ratelimit-${dimension}-remaining`))))
+            continue;
+        const reset = resetDelay(headers.get(`anthropic-ratelimit-${dimension}-reset`), now);
+        if (reset !== undefined)
+            delay = Math.max(delay ?? 0, reset);
+    }
+    return delay !== undefined
+        ? { code: "rate-limit", retryAfterMs: delay }
+        : { code: "rate-limit" };
+}
+function usageLimit(headers) {
+    const reset = decodeReset(headers.get("anthropic-ratelimit-unified-reset"));
+    const limit = decodeLimit(headers.get("anthropic-ratelimit-unified-representative-claim"));
+    let result = { code: "usage-limit-reached" };
+    if (Option.isSome(reset))
+        result = { ...result, resetAt: reset.value * 1000 };
+    if (Option.isSome(limit))
+        result = { ...result, limit: limit.value };
+    return result;
+}
 /** 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) {
+async function providerErrorKind(response) {
     const body = response.clone().body;
     if (body === null)
         return undefined;
@@ -39,7 +105,9 @@ async function providerErrorCode(response) {
         }
         text += decoder.decode();
         const decoded = decodeErrorReply(text);
-        return Option.isSome(decoded) ? decoded.value.error.code : undefined;
+        return Option.isSome(decoded)
+            ? (decoded.value.error.code ?? decoded.value.error.type)
+            : undefined;
     }
     finally {
         // A tee's cancellation may await the original consumer. Do not hold Pi's
@@ -50,6 +118,20 @@ async function providerErrorCode(response) {
         reader.releaseLock();
     }
 }
+/** Retry only typed transient failures, never usage exhaustion or rejection. */
+export function isRetryableProviderRejection(rejection) {
+    if (rejection === undefined)
+        return false;
+    switch (rejection.code) {
+        case "provider_unavailable":
+        case "rate-limit":
+        case "overloaded":
+            return true;
+        case "usage-limit-reached":
+        case "provider_rejected":
+            return false;
+    }
+}
 /**
  * Observe one call's typed HTTP and parsed-event evidence. Pi owns stream
  * decoding; this module retains no provider prose.
@@ -69,15 +151,25 @@ export function observeProviderStatus(options) {
             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 };
+        const code = status === 429 || status === 529
+            ? await providerErrorKind(response)
+            : undefined;
+        const subscriptionRejected = status === 429 &&
+            Option.isSome(decodeRejected(response.headers.get("anthropic-ratelimit-unified-status")));
+        if (status < 400 || status > 599)
+            rejection = undefined;
+        else if (subscriptionRejected)
+            rejection = usageLimit(response.headers);
+        else if (code === usageLimitCode)
+            rejection = { code: "usage-limit-reached" };
+        else if (code === "overloaded_error")
+            rejection = { code: "overloaded" };
+        else if (status === 429 && code !== "insufficient_quota")
+            rejection = rateLimit(response.headers);
+        else if (transientStatus(status) && code !== "insufficient_quota")
+            rejection = { code: "provider_unavailable", status };
+        else
+            rejection = { code: "provider_rejected", status };
         return response;
     };
     return {
@@ -87,8 +179,43 @@ export function observeProviderStatus(options) {
             if (Option.isSome(failed) &&
                 failed.value.response.error.code === usageLimitCode)
                 rejection = { code: "usage-limit-reached" };
+            // OpenAI's Responses error code, not an inference from overload prose:
+            // https://platform.openai.com/docs/api-reference/responses/object#responses/object-error
+            if (Option.isSome(failed) &&
+                failed.value.response.error.code === "server_error")
+                rejection = { code: "provider_unavailable" };
+            // WebSocket API errors retain HTTP status in the parsed event:
+            // https://developers.openai.com/api/docs/guides/websocket-mode/#handling-errors
+            const error = decodeErrorEvent(data);
+            if (Option.isSome(error)) {
+                const status = error.value.status;
+                if (status !== undefined && status >= 500)
+                    rejection = { code: "provider_unavailable", status };
+                else if (status === undefined &&
+                    (error.value.code ?? error.value.error?.code) === "server_error")
+                    rejection = { code: "provider_unavailable" };
+            }
+            if (Option.isSome(decodeOverloaded(data)))
+                rejection = { code: "overloaded" };
             await options?.onProviderStreamEvent?.(data, model);
         },
-        rejection: () => rejection,
+        rejection: (message) => {
+            if (rejection !== undefined)
+                return rejection;
+            // Pi throws Anthropic event:error before its parsed-event hook and
+            // retains that JSON envelope verbatim as the terminal errorMessage.
+            // Decode that maintained producer's representation, never match prose.
+            const text = message?.errorMessage;
+            if (message?.stopReason !== "error" ||
+                text === undefined ||
+                text.length > errorBodyBytes ||
+                new TextEncoder().encode(text).byteLength > errorBodyBytes)
+                return undefined;
+            const decoded = decodeErrorReply(text);
+            return Option.isSome(decoded) &&
+                decoded.value.error.type === "overloaded_error"
+                ? { code: "overloaded" }
+                : undefined;
+        },
     };
 }

package/docs/api/effect.md

@@ -1091,6 +1091,14 @@ optional deferred?: DeferredHandle;
 optional errorMessage?: string;
 ```
 
+##### providerError?
+
+```ts
+optional providerError?: string;
+```
+
+Provider prose for the failed conversation turn, never a diagnostic.
+
 ##### rawStopReason?
 
 ```ts
@@ -1912,6 +1920,12 @@ Re-exports [streamModel](index.md#streammodel)
 
 ---
 
+### isRetryableProviderRejection
+
+Re-exports [isRetryableProviderRejection](index.md#isretryableproviderrejection)
+
+---
+
 ### observeProviderStatus
 
 Re-exports [observeProviderStatus](index.md#observeproviderstatus)

package/docs/api/index.md

@@ -943,6 +943,15 @@ the run, or with the abort reason (an `AbortError` when the reason is not an
 type ProviderRejection =
   | Readonly<{
       code: "usage-limit-reached";
+      resetAt?: number;
+      limit?: "five_hour" | "seven_day" | "seven_day_opus" | "seven_day_sonnet";
+    }>
+  | Readonly<{
+      code: "rate-limit";
+      retryAfterMs?: number;
+    }>
+  | Readonly<{
+      code: "overloaded";
     }>
   | Readonly<{
       code: "provider_unavailable";
@@ -966,7 +975,7 @@ type ProviderStatusRecorder = Readonly<{
   onProviderStreamEvent: NonNullable<
     SimpleStreamOptions["onProviderStreamEvent"]
   >;
-  rejection: () => ProviderRejection | undefined;
+  rejection: (message?) => ProviderRejection | undefined;
 }>;
 ```
 
@@ -1040,6 +1049,26 @@ Validate a catalog model's opaque sampling fields before it enters Mule.
 
 ---
 
+### isRetryableProviderRejection()
+
+```ts
+function isRetryableProviderRejection(rejection): boolean;
+```
+
+Retry only typed transient failures, never usage exhaustion or rejection.
+
+#### Parameters
+
+| Parameter   | Type                                                     |
+| ----------- | -------------------------------------------------------- |
+| `rejection` | [`ProviderRejection`](#providerrejection) \| `undefined` |
+
+#### Returns
+
+`boolean`
+
+---
+
 ### observeProviderStatus()
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fungi.computer/mule",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "author": "Levi <levi@technomancy.dev>",
   "description": "Effect-native Pi model and tool loop",
   "type": "module",