@fungi.computer/mule 0.1.0 → 0.2.0

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. */
@@ -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,9 +1,12 @@
+export { decodeProviderData } from "./provider-data.js";
+export { streamPi as streamModel } from "./provider.js";
 export { observeProviderStatus, type ProviderRejection, type ProviderStatusRecorder, } from "./provider-status.js";
-import type { AssistantMessage, Message, RetryPolicy, Tool, ToolCall } from "@earendil-works/pi-ai";
+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";
 /**
@@ -13,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

@@ -1,3 +1,6 @@
+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
@@ -5,7 +8,8 @@ export { observeProviderStatus, } from "./provider-status.js";
 // keeps that work out of every host's startup.
 import { isContextOverflow as piIsContextOverflow } from "@earendil-works/pi-ai/utils/overflow";
 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 { streamPi } from "./provider.js";
+export { normalizeModel } from "./provider-model.js";
 import * as Effect from "effect/Effect";
 import * as Cause from "effect/Cause";
 import * as Result from "effect/Result";
@@ -26,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);
@@ -231,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");
@@ -269,18 +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 ??
-                    (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),
-        }), 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");
@@ -300,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);
@@ -342,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 {
@@ -373,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.
@@ -427,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) {
@@ -526,11 +626,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. */
@@ -627,10 +730,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. */
@@ -699,7 +811,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

@@ -1,4 +1,7 @@
-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";

package/dist/index.js

@@ -1,3 +1,6 @@
+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";

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

@@ -1,4 +1,4 @@
-import type { SimpleStreamOptions } from "@earendil-works/pi-ai";
+import type { SimpleStreamOptions } from "./types.js";
 /** Bounded provider evidence, never response bodies, headers or error prose. */
 export type ProviderRejection = Readonly<{
     code: "usage-limit-reached";

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));
+};

package/dist/testing.d.ts

@@ -1,17 +1,60 @@
-import { type FauxProviderHandle, type FauxResponseStep, type RegisterFauxProviderOptions } from "@earendil-works/pi-ai/providers/faux";
-import type { Api, AssistantMessage, Model } from "@earendil-works/pi-ai";
+import type { Api, AssistantMessage, AssistantMessageEventStream, Context, Model } from "./types.js";
+import type { MuleStreamFunction } from "./contract.js";
+/** Credential-free model definition for the scripted provider. */
+export type FauxModelDefinition = {
+    id: string;
+    name?: string;
+    reasoning?: boolean;
+    input?: ("text" | "image")[];
+    inputLimits?: Model<Api>["inputLimits"];
+    cost?: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    contextWindow?: number;
+    maxTokens?: number;
+};
+/** Scripted provider configuration, independent of provider SDK declarations. */
+export type RegisterFauxProviderOptions = {
+    api?: string;
+    provider?: string;
+    models?: FauxModelDefinition[];
+    deferred?: {
+        pendingFetches?: number;
+        pollAfterMs?: number;
+    };
+    tokensPerSecond?: number;
+    tokenSize?: {
+        min?: number;
+        max?: number;
+    };
+};
+/** Counters retained by the scripted provider. */
+export type FauxProviderState = {
+    callCount: number;
+    deferredFetchCount: number;
+    cancelledDeferred: NonNullable<AssistantMessage["deferred"]>[];
+};
+/** Function that observes a model request and supplies a scripted reply. */
+export type FauxResponseFactory = (context: Context, options: Parameters<MuleStreamFunction>[2], state: FauxProviderState, model: Model<Api>) => AssistantMessage | Promise<AssistantMessage>;
+/** A scripted reply or a factory that observes the normalized request. */
+export type FauxResponseStep = AssistantMessage | FauxResponseFactory;
 /** 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"];
+    stream: (...args: Parameters<MuleStreamFunction>) => AssistantMessageEventStream;
     /** 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. */
-    state: FauxProviderHandle["state"];
+    state: FauxProviderState;
+    /** Scripted replies not yet consumed, supplied by Pi's maintained queue. */
+    getPendingResponseCount: () => number;
 }>;
 /** Create a credential-free model for tests and runnable examples. */
 export declare function fauxModel(replies: readonly FauxResponseStep[], options?: RegisterFauxProviderOptions): FauxModel;

package/dist/testing.js

@@ -1,15 +1,23 @@
-import { fauxProvider, } from "@earendil-works/pi-ai/providers/faux";
+import { isFunction } from "effect/Predicate";
+import { muleOptions, piOptions } from "./pi-options.js";
+import { normalizeModel } from "./provider-model.js";
+import { fauxProvider } from "@earendil-works/pi-ai/providers/faux";
+import { normalizeContext } from "@earendil-works/pi-ai/utils/transcript";
 /** Create a credential-free model for tests and runnable examples. */
 export function fauxModel(replies, options = {}) {
     const faux = fauxProvider(options);
-    faux.setResponses([...replies]);
+    const setResponses = (responses) => {
+        faux.setResponses(responses.map((step) => isFunction(step)
+            ? (context, options, state, model) => step(context, muleOptions(options), state, normalizeModel(model))
+            : step));
+    };
+    setResponses(replies);
     return {
-        model: faux.getModel(),
-        stream: faux.provider.streamSimple.bind(faux.provider),
+        model: normalizeModel(faux.getModel()),
+        stream: (model, context, streamOptions) => faux.provider.streamSimple(model, normalizeContext(context), piOptions(streamOptions)),
         retryable: () => false,
-        setResponses: (responses) => {
-            faux.setResponses([...responses]);
-        },
+        setResponses,
         state: faux.state,
+        getPendingResponseCount: () => faux.getPendingResponseCount(),
     };
 }