@fungi.computer/mule 0.0.2 → 0.1.1

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/THIRD_PARTY_NOTICES

@@ -1,8 +1,8 @@
-Mule's direct runtime dependencies are Effect 3.22.1, Cairn, and
-@earendil-works/pi-ai 0.84.4. Consult each dependency's distribution for its
+Mule's direct runtime dependencies are Effect 4.0.2, Cairn, and
+@earendil-works/pi-ai 1.3.0. Consult each dependency's distribution for its
 license terms.
 
-The Pi dependency is pinned from commit
+The original Pi loop source was pinned from commit
 853a80d26c90a14c1886f0ebb8ffaae133ca2185 and distributed under the MIT
 License, Copyright (c) 2025 Mario Zechner. Its independently archived source
 boundary has SHA-256
@@ -13,3 +13,8 @@ dfb11f4c1c00e47003db12765371198e944c8b640c995a1dc1cf9130bc9e49ee.
 behavior from Botanical's retained @shiit/agent-core 0.66.2 at commit
 b6eabe5dfd3cac9514025d26abbe9a92b083f10b, distributed under the MIT License,
 Copyright (c) 2024 fungi.computer.
+
+`src/types.ts` adapts the provider-neutral data declarations from
+@earendil-works/pi-ai 1.3.0, distributed under the MIT License,
+Copyright (c) 2025 Mario Zechner. Mule owns this public structural contract;
+provider implementations remain in Pi.

package/dist/contract.d.ts

@@ -1,6 +1,6 @@
-import type { Api, AssistantMessage, AssistantMessageEvent, AssistantMessageEventStream, TranscriptContext, ImageContent, JsonValue, Message, Model, RetryPolicy, SimpleStreamOptions, TextContent, ToolCall, ToolResultMessage, Usage } from "@earendil-works/pi-ai";
+import type { Api, AssistantMessage, AssistantMessageEvent, AssistantMessageEventStream, Context, ImageContent, JsonValue, Message, Model, RetryPolicy, SimpleStreamOptions, TextContent, ToolCall, ToolResultMessage, Usage } from "./types.js";
 /** Pi's model stream function, supplied explicitly by the caller. */
-export type MuleStreamFunction = (model: Model<Api>, context: TranscriptContext, options?: SimpleStreamOptions) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;
+export type MuleStreamFunction = (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;
 /** Causal roles added around Pi's model and tool loop. */
 export type MuleIdentityKind = "run" | "turn" | "message" | "tool_call" | "tool_result" | "terminal";
 /** One run-local causal identity. */
@@ -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,8 +1,12 @@
-import type { AssistantMessage, Message, RetryPolicy, Tool, ToolCall } from "@earendil-works/pi-ai";
+export { decodeProviderData } from "./provider-data.js";
+export { streamPi as streamModel } from "./provider.js";
+export { 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";
 import * as Stream from "effect/Stream";
 import type { MuleCompletedTurn, MuleError, MuleEvent, MuleRetryObservation, MuleRunOutcome, MuleRunSettings, MuleToolExecutionPart, MuleToolRejection } from "./contract.js";
-export type { Api, AssistantMessage, AssistantMessageEvent, Context, ImageContent, JsonValue, Message, Model, RetryPolicy, SimpleStreamOptions, SystemMessage, TextContent, ThinkingContent, ToolCall, ToolResultMessage, Usage, UserMessage, } from "@earendil-works/pi-ai";
+export type * from "./types.js";
 export { Type } from "typebox";
 export type { MuleRetryObservation } from "./contract.js";
 /**

package/dist/effect.js

@@ -1,16 +1,19 @@
+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";
 // 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 { normalizeContext } from "@earendil-works/pi-ai/utils/transcript";
+import { DEFAULT_MAX_AGENT_RETRY_DELAY_MS, retryDelayMs, } from "@earendil-works/pi-ai/utils/retry";
+import { streamPi } from "./provider.js";
+export { normalizeModel } from "./provider-model.js";
 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 +47,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 +58,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 +168,7 @@ function emitToolResult(executed, run, turn, emit) {
             turn,
             message: messageIdentity,
             value: message,
+            data: executed.result.data,
         });
         return message;
     });
@@ -261,6 +256,7 @@ function streamTurn(input, context, run, turn, emit, attempt) {
             input.streamOptions?.apiKey;
         const options = {
             ...input.streamOptions,
+            maxRetries: 0,
             signal: controller.signal,
         };
         if (resolvedApiKey !== undefined)
@@ -279,8 +275,7 @@ function streamTurn(input, context, run, turn, emit, attempt) {
             piContext.tools = descriptors;
         const response = yield* withModelStreamDeadline(Effect.tryPromise({
             try: async () => {
-                const stream = input.stream ??
-                    (await import("@earendil-works/pi-ai/compat")).streamSimple;
+                const stream = input.stream ?? streamPi;
                 return stream(input.model, normalizeContext(piContext), options);
             },
             catch: (cause) => failure("model", "Pi model stream could not start", cause),
@@ -384,9 +379,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 +389,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,8 @@
-import type { Message, Tool, ToolCall } from "@earendil-works/pi-ai";
+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";
 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,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";
 import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";

package/dist/pi-options.d.ts

@@ -0,0 +1,6 @@
+import type { SimpleStreamOptions as PiOptions } from "@earendil-works/pi-ai";
+import type { SimpleStreamOptions } from "./types.js";
+/** Adapt Pi's parsed payload and event boundary before invoking owned hooks. */
+export declare function piOptions(options: SimpleStreamOptions | undefined): PiOptions | undefined;
+/** Restore the owned options shape when Pi calls a scripted provider factory. */
+export declare function muleOptions(options: PiOptions | undefined): SimpleStreamOptions | undefined;

package/dist/pi-options.js

@@ -0,0 +1,35 @@
+import * as Schema from "effect/Schema";
+import { decodeProviderData } from "./provider-data.js";
+import { normalizeModel } from "./provider-model.js";
+/** Adapt Pi's parsed payload and event boundary before invoking owned hooks. */
+export function piOptions(options) {
+    if (options === undefined)
+        return undefined;
+    const { onPayload, onProviderStreamEvent, onResponse, ...rest } = options;
+    const adapted = { ...rest };
+    if (onPayload !== undefined)
+        adapted.onPayload = (payload, model) => onPayload(decodeProviderData(payload), normalizeModel(model));
+    if (onProviderStreamEvent !== undefined)
+        adapted.onProviderStreamEvent = (event, model) => onProviderStreamEvent(decodeProviderData(event), normalizeModel(model));
+    if (onResponse !== undefined)
+        adapted.onResponse = (response, model) => onResponse(response, normalizeModel(model));
+    return adapted;
+}
+/** Restore the owned options shape when Pi calls a scripted provider factory. */
+export function muleOptions(options) {
+    if (options === undefined)
+        return undefined;
+    const { samplingParams, metadata, onPayload, ...rest } = options;
+    const adapted = { ...rest };
+    const decodeObject = Schema.decodeUnknownSync(Schema.Record(Schema.String, Schema.Json));
+    if (samplingParams !== undefined)
+        adapted.samplingParams = decodeObject(samplingParams);
+    if (metadata !== undefined)
+        adapted.metadata = decodeObject(metadata);
+    if (onPayload !== undefined)
+        adapted.onPayload = async (payload, model) => {
+            const result = await onPayload(payload, model);
+            return result === undefined ? undefined : decodeProviderData(result);
+        };
+    return adapted;
+}

package/dist/provider-data.d.ts

@@ -0,0 +1,3 @@
+import type { ProviderData } from "./types.js";
+/** Decode Pi's parsed request/event data before it enters an owned hook. */
+export declare function decodeProviderData(data: unknown): ProviderData;

package/dist/provider-data.js

@@ -0,0 +1,17 @@
+import * as Schema from "effect/Schema";
+const providerValue = Schema.suspend(() => Schema.Union([
+    Schema.Undefined,
+    Schema.Null,
+    Schema.Boolean,
+    Schema.Number,
+    Schema.String,
+    Schema.Uint8Array,
+    Schema.instanceOf(AbortSignal),
+    Schema.Array(providerValue),
+    providerData,
+]));
+const providerData = Schema.Record(Schema.String, providerValue);
+/** Decode Pi's parsed request/event data before it enters an owned hook. */
+export function decodeProviderData(data) {
+    return Schema.decodeUnknownSync(providerData)(data);
+}

package/dist/provider-model.d.ts

@@ -0,0 +1,3 @@
+import type { Api, Model } from "./types.js";
+/** Validate a catalog model's opaque sampling fields before it enters Mule. */
+export declare function normalizeModel<TApi extends Api>(model: Omit<Model<TApi>, "samplingParams" | "samplingParamsByThinkingLevel">): Model<TApi>;

package/dist/provider-model.js

@@ -0,0 +1,18 @@
+import * as Schema from "effect/Schema";
+const sampling = Schema.Record(Schema.String, Schema.Json);
+const decodeSampling = Schema.decodeUnknownSync(Schema.Struct({
+    samplingParams: Schema.optionalKey(sampling),
+    samplingParamsByThinkingLevel: Schema.optionalKey(Schema.Struct({
+        off: Schema.optionalKey(sampling),
+        minimal: Schema.optionalKey(sampling),
+        low: Schema.optionalKey(sampling),
+        medium: Schema.optionalKey(sampling),
+        high: Schema.optionalKey(sampling),
+        xhigh: Schema.optionalKey(sampling),
+        max: Schema.optionalKey(sampling),
+    })),
+}));
+/** Validate a catalog model's opaque sampling fields before it enters Mule. */
+export function normalizeModel(model) {
+    return { ...model, ...decodeSampling(model) };
+}

package/dist/provider-status.d.ts

@@ -0,0 +1,25 @@
+import type { SimpleStreamOptions } from "./types.js";
+/** 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/provider.d.ts

@@ -0,0 +1,3 @@
+import type { MuleStreamFunction } from "./contract.js";
+/** Pi's maintained stream behind Mule's structural provider port. */
+export declare const streamPi: MuleStreamFunction;

package/dist/provider.js

@@ -0,0 +1,7 @@
+import { normalizeContext } from "@earendil-works/pi-ai/utils/transcript";
+import { piOptions } from "./pi-options.js";
+/** Pi's maintained stream behind Mule's structural provider port. */
+export const streamPi = async (model, context, options) => {
+    const { streamSimple } = await import("@earendil-works/pi-ai/compat");
+    return streamSimple(model, normalizeContext(context), piOptions(options));
+};