@fungi.computer/mule 0.1.0 → 0.1.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. */

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";
 /**

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";
@@ -271,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),

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(),
     };
 }