@fungi.computer/mule 0.1.1 → 0.2.1

package/dist/contract.d.ts

@@ -154,6 +154,12 @@ export type MuleRunSettings = {
     readonly streamOptions?: Omit<SimpleStreamOptions, "signal" | "maxRetries"> | undefined;
     /** Maximum silence between provider stream events, in milliseconds. */
     readonly modelStreamIdleTimeoutMs?: number | undefined;
+    /** Trusted per-attempt safety limits may only tighten Mule's defaults. */
+    readonly modelStreamLimits?: Partial<{
+        firstEventMs: number;
+        attemptMs: number;
+        outputBytes: number;
+    }> | undefined;
     readonly toolExecution?: "parallel" | "sequential" | undefined;
     /**
      * Bounded retry around each assistant call, using Pi's exponential delay.
@@ -200,4 +206,6 @@ export type MuleRunOutcome = {
     readonly terminal: MuleIdentity;
     readonly message: AssistantMessage;
     readonly messages: readonly Message[];
+    /** Mule-owned limit diagnostic, not untrusted provider prose. */
+    readonly modelLimitReason?: string;
 };

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";
@@ -16,12 +16,6 @@ export type { MuleRetryObservation } from "./contract.js";
  * a host that wants Pi coding-agent's numbers passes this explicitly.
  */
 export declare const piCodingAgentRetryDefaults: RetryPolicy;
-/**
- * Pi coding-agent's default stream idle timeout (`DEFAULT_HTTP_IDLE_TIMEOUT_MS`,
- * `settings-manager.js`). A host that wants Pi's number for
- * `modelStreamIdleTimeoutMs` passes this explicitly.
- */
-export declare const piHttpIdleTimeoutMs = 300000;
 /** Apply Pi's maintained context-overflow semantics to an exact Pi message. */
 export declare function isContextOverflow(message: AssistantMessage, contextWindow?: number): boolean;
 export type { MuleCompletedTurn, MuleResume, MuleToolCheckpoint, MuleError, MuleEvent, MuleIdentity, MuleIdentityKind, MuleRunOutcome, MuleRunSettings, MuleStreamFunction, MuleToolExecutionPart, MuleToolRejection, MuleToolResult, } from "./contract.js";

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.
@@ -30,18 +30,20 @@ export const piCodingAgentRetryDefaults = {
     baseDelayMs: 2000,
     maxAgentDelayMs: 60_000,
 };
-/**
- * Pi coding-agent's default stream idle timeout (`DEFAULT_HTTP_IDLE_TIMEOUT_MS`,
- * `settings-manager.js`). A host that wants Pi's number for
- * `modelStreamIdleTimeoutMs` passes this explicitly.
- */
-export const piHttpIdleTimeoutMs = 300_000;
+/** Starting safety limits for one provider attempt; hosts may tighten them. Not public: the values are starting points, not a contract. */
+const modelStreamLimits = {
+    firstEventMs: 60_000,
+    idleMs: 120_000,
+    attemptMs: 600_000,
+    outputBytes: 2 * 1024 * 1024,
+};
 /**
  * Grace period a release waits for a provider iterator that ignores abort,
  * so a timed-out run's scope close never hangs. This is a Mule transport
  * detail with no Pi equivalent, so it stays a constant, not host config.
  */
 const providerIteratorReleaseGraceMs = 1_000;
+const modelLimitCause = Symbol("Mule model limit");
 /** Apply Pi's maintained context-overflow semantics to an exact Pi message. */
 export function isContextOverflow(message, contextWindow) {
     return piIsContextOverflow(message, contextWindow);
@@ -235,17 +237,47 @@ function pullPiEvent(iterator, controller) {
         catch: (cause) => failure("model", "Pi model stream failed", cause),
     });
 }
-function withModelStreamDeadline(effect, timeoutMs) {
-    if (timeoutMs === undefined)
-        return effect;
+function withModelStreamDeadline(effect, timeoutMs, reason) {
     return effect.pipe(Effect.timeoutOrElse({
         duration: timeoutMs,
-        orElse: () => Effect.fail(failure("model", `Model stream was idle for ${String(timeoutMs)} ms; the provider connection stopped responding. Retry the run.`)),
+        orElse: () => Effect.fail(failure("model", reason(), modelLimitCause)),
     }));
 }
 function streamTurn(input, context, run, turn, emit, attempt) {
     const messageIdentity = identity("message", turn);
+    let partial;
+    const streamState = { started: false, terminal: undefined };
     return Effect.scoped(Effect.gen(function* () {
+        const limits = input.modelStreamLimits;
+        const firstEventMs = Math.min(limits?.firstEventMs ?? modelStreamLimits.firstEventMs, modelStreamLimits.firstEventMs);
+        const attemptMs = Math.min(limits?.attemptMs ?? modelStreamLimits.attemptMs, modelStreamLimits.attemptMs);
+        const outputLimit = Math.min(limits?.outputBytes ?? modelStreamLimits.outputBytes, modelStreamLimits.outputBytes);
+        if ([
+            firstEventMs,
+            attemptMs,
+            outputLimit,
+            input.modelStreamIdleTimeoutMs ?? 1,
+        ].some((value) => !Number.isSafeInteger(value) || value <= 0))
+            return yield* Effect.fail(failure("model", "Model stream limits must be positive safe integers"));
+        const startedAt = Date.now();
+        let lastEventAt = startedAt;
+        let maxGapMs = 0;
+        let outputBytes = 0;
+        const encoder = new TextEncoder();
+        let hasEvent = false;
+        const limitError = (kind) => failure("model", `Model ${kind} after ${String(Date.now() - startedAt)} ms (max provider gap ${String(Math.max(maxGapMs, Date.now() - lastEventAt))} ms, streamed ${String(outputBytes)} bytes)`, modelLimitCause);
+        const deadline = (effect) => {
+            const elapsed = Date.now() - startedAt;
+            const wholeRemaining = attemptMs - elapsed;
+            const gapLimit = Math.min(hasEvent ? modelStreamLimits.idleMs : firstEventMs, input.modelStreamIdleTimeoutMs ?? modelStreamLimits.idleMs);
+            const gapRemaining = gapLimit - (Date.now() - lastEventAt);
+            const kind = wholeRemaining <= gapRemaining
+                ? "attempt timed out"
+                : hasEvent
+                    ? "stream timed out (silence)"
+                    : "first event timed out";
+            return withModelStreamDeadline(effect, Math.max(0, Math.min(wholeRemaining, gapRemaining)), () => limitError(kind).message);
+        };
         const controller = new AbortController();
         yield* Effect.addFinalizer(() => Effect.sync(() => {
             controller.abort("Mule model scope closed");
@@ -273,17 +305,13 @@ function streamTurn(input, context, run, turn, emit, attempt) {
         const descriptors = (input.tools ?? []).map((tool) => tool.descriptor);
         if (descriptors.length > 0)
             piContext.tools = descriptors;
-        const response = yield* withModelStreamDeadline(Effect.tryPromise({
+        const response = yield* deadline(Effect.tryPromise({
             try: async () => {
                 const stream = input.stream ?? streamPi;
                 return stream(input.model, normalizeContext(piContext), options);
             },
             catch: (cause) => failure("model", "Pi model stream could not start", cause),
-        }), input.modelStreamIdleTimeoutMs);
-        const streamState = {
-            started: false,
-            terminal: undefined,
-        };
+        }));
         const iterator = yield* Effect.acquireRelease(Effect.sync(() => response[Symbol.asyncIterator]()), (active) => Effect.tryPromise({
             try: () => {
                 controller.abort("Mule model stream closed");
@@ -303,6 +331,19 @@ function streamTurn(input, context, run, turn, emit, attempt) {
             catch: (cause) => failure("model", "Pi model stream failed", cause),
         }).pipe(Effect.ignore));
         const observeEvent = (event) => {
+            const now = Date.now();
+            maxGapMs = Math.max(maxGapMs, now - lastEventAt);
+            lastEventAt = now;
+            hasEvent = true;
+            if (event.type === "text_delta" ||
+                event.type === "thinking_delta" ||
+                event.type === "toolcall_delta") {
+                outputBytes += encoder.encode(event.delta).byteLength;
+                if (outputBytes > outputLimit)
+                    return Effect.fail(limitError("output limit exceeded"));
+            }
+            if ("partial" in event)
+                partial = event.partial;
             switch (event.type) {
                 case "start": {
                     context.push(event.partial);
@@ -345,17 +386,17 @@ function streamTurn(input, context, run, turn, emit, attempt) {
                 }
             }
         };
-        const pull = () => withModelStreamDeadline(pullPiEvent(iterator, controller), input.modelStreamIdleTimeoutMs);
+        const pull = () => deadline(pullPiEvent(iterator, controller));
         let next = yield* pull();
         while (!next.done) {
             yield* observeEvent(next.value);
             next = yield* pull();
         }
         const completed = streamState.terminal ??
-            (yield* withModelStreamDeadline(Effect.tryPromise({
+            (yield* deadline(Effect.tryPromise({
                 try: () => response.result(),
                 catch: (cause) => failure("model", "Pi model stream did not settle", cause),
-            }), input.modelStreamIdleTimeoutMs));
+            })));
         if (streamState.started)
             context[context.length - 1] = completed;
         else {
@@ -376,7 +417,62 @@ function streamTurn(input, context, run, turn, emit, attempt) {
             value: completed,
         });
         return { identity: messageIdentity, message: completed };
-    }));
+    }).pipe(Effect.catch((error) => {
+        if (error.cause !== modelLimitCause)
+            return Effect.fail(error);
+        const value = {
+            role: "assistant",
+            content: partial?.content ?? [],
+            api: input.model.api,
+            provider: input.model.provider,
+            model: input.model.id,
+            usage: partial?.usage ?? {
+                input: 0,
+                output: 0,
+                cacheRead: 0,
+                cacheWrite: 0,
+                totalTokens: 0,
+                cost: {
+                    input: 0,
+                    output: 0,
+                    cacheRead: 0,
+                    cacheWrite: 0,
+                    total: 0,
+                },
+            },
+            stopReason: "error",
+            timestamp: Date.now(),
+            errorMessage: input.retry?.enabled && attempt > input.retry.maxRetries
+                ? `The model failed ${String(attempt)} times on this conversation: ${error.message}`
+                : error.message,
+        };
+        return Effect.gen(function* () {
+            if (!streamState.started) {
+                context.push(value);
+                yield* emit({
+                    type: "message_start",
+                    run,
+                    turn,
+                    message: messageIdentity,
+                    value,
+                });
+            }
+            else
+                context[context.length - 1] = value;
+            yield* emit({
+                type: "message_end",
+                run,
+                turn,
+                message: messageIdentity,
+                value,
+            });
+            return {
+                identity: messageIdentity,
+                message: value,
+                limitReached: true,
+            };
+        });
+    })));
 }
 /**
  * Retry only the host's typed transient decision, using Pi's maintained delay.
@@ -430,13 +526,14 @@ function streamTurnWithRetry(input, context, run, turn, emit) {
                     policy === undefined ||
                     !policy.enabled ||
                     retries >= policy.maxRetries) {
-                    if (retries > 0)
+                    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),
+                    try: () => latest?.limitReached === true || input.retryable(message),
                     catch: (cause) => failure("model", "Typed model retry decision failed", cause),
                 });
                 if (!retryable) {
@@ -450,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,
@@ -529,11 +630,14 @@ function completeLoopTurn(input, context, newMessages, run, turn, pending, emit)
             message: streamed.message,
             toolResults: batch.messages,
         });
-        return {
+        const completed = {
             message: streamed.message,
             toolResults: batch.messages,
             terminate: batch.terminate,
         };
+        if (streamed.limitReached && streamed.message.errorMessage !== undefined)
+            return { ...completed, modelLimitReason: streamed.message.errorMessage };
+        return completed;
     });
 }
 /** Resolve only missing results. A stored and current safe policy are both required. */
@@ -630,10 +734,19 @@ function selectNextTurn(input, turn, context, newMessages) {
         return { continue: followUps.length > 0, pending: followUps };
     });
 }
-function finishRun(run, terminal, message, messages, status, emit) {
+function finishRun(run, terminal, message, messages, status, emit, modelLimitReason) {
     return Effect.gen(function* () {
         yield* emit({ type: "run_end", run, terminal, outcome: status });
-        return { status, run, terminal, message, messages };
+        const outcome = {
+            status,
+            run,
+            terminal,
+            message,
+            messages,
+        };
+        if (modelLimitReason !== undefined)
+            return { ...outcome, modelLimitReason };
+        return outcome;
     });
 }
 /** Run Pi's model/tool loop inside Effect without changing Pi's values. */
@@ -702,7 +815,7 @@ function runLoop(input, emit, runIdentity, terminalIdentity) {
             finalMessage = completed.message;
             const status = statusFor(completed.message);
             if (status !== "completed") {
-                return yield* finishRun(runIdentity, terminalIdentity, completed.message, newMessages, status, emit);
+                return yield* finishRun(runIdentity, terminalIdentity, completed.message, newMessages, status, emit, completed.modelLimitReason);
             }
             // Tool results always continue the run: this is where Pi checks its
             // context before the next assistant response (Pi 0.84.4+).

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({
@@ -12,13 +13,70 @@ const decodeFailedEvent = Schema.decodeUnknownOption(Schema.Struct({
 const decodeErrorReply = Schema.decodeUnknownOption(Schema.fromJsonString(providerError));
 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(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 +97,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 +110,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 +143,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 +171,27 @@ export function observeProviderStatus(options) {
             if (Option.isSome(failed) &&
                 failed.value.response.error.code === usageLimitCode)
                 rejection = { code: "usage-limit-reached" };
+            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/dist/types.d.ts

@@ -177,6 +177,8 @@ export type AssistantMessage = {
     stopReason: StopReason;
     deferred?: DeferredHandle;
     errorMessage?: string;
+    /** Provider prose for the failed conversation turn, never a diagnostic. */
+    providerError?: string;
     rawStopReason?: string;
     endTurn?: boolean;
     timestamp: number;

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
@@ -1847,18 +1855,6 @@ that wants Pi coding-agent's numbers passes this explicitly.
 
 ---
 
-### piHttpIdleTimeoutMs
-
-```ts
-const piHttpIdleTimeoutMs: 300000 = 300_000;
-```
-
-Pi coding-agent's default stream idle timeout (`DEFAULT_HTTP_IDLE_TIMEOUT_MS`,
-`settings-manager.js`). A host that wants Pi's number for
-`modelStreamIdleTimeoutMs` passes this explicitly.
-
----
-
 ### muleEffect
 
 ```ts
@@ -1924,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

@@ -657,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
@@ -754,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
@@ -923,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";
@@ -946,7 +975,7 @@ type ProviderStatusRecorder = Readonly<{
   onProviderStreamEvent: NonNullable<
     SimpleStreamOptions["onProviderStreamEvent"]
   >;
-  rejection: () => ProviderRejection | undefined;
+  rejection: (message?) => ProviderRejection | undefined;
 }>;
 ```
 
@@ -1020,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.1.1",
+  "version": "0.2.1",
   "author": "Levi <levi@technomancy.dev>",
   "description": "Effect-native Pi model and tool loop",
   "type": "module",