@fungi.computer/mule 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamstack Consulting LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,121 @@
-# Temporary Holding Version
+# Mule (`@fungi.computer/mule`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Mule runs Pi's model and tool loop inside Effect. Use it when your host already
+owns the model, messages and tools and needs an awaited, cancellable run. Pi's
+models, messages, provider replay fields and stream events keep their original
+types.
+
+## Set up
+
+```sh
+npm install @fungi.computer/mule
+```
+
+The package ships ESM only and depends on `effect` and Pi
+(`@earendil-works/pi-ai`) at runtime, plus `@fungi.computer/cairn` for IDs. Mule
+does not require or install the MCP SDK. Consumers that type-check dependency
+declarations (`skipLibCheck: false`) must install Pi’s Google GenAI optional
+declaration dependency themselves:
+
+```sh
+npm install --save-dev @modelcontextprotocol/sdk
+```
+
+The root entrypoint exports the Promise facade, `mule.run`.
+`@fungi.computer/mule/effect` exports the canonical `muleEffect.run`. The
+Promise facade adapts tools, hooks and listeners into that same Effect program,
+so public Promise declarations do not require Effect types.
+
+## Quick start without a provider account
+
+This deterministic example uses the public testing helper. It makes no network
+request and needs no credential.
+
+```ts
+import { fauxAssistantMessage } from "@earendil-works/pi-ai/providers/faux";
+import { mule } from "@fungi.computer/mule";
+import { fauxModel } from "@fungi.computer/mule/testing";
+
+const faux = fauxModel([fauxAssistantMessage("pong")]);
+const outcome = await mule.run(
+  {
+    model: faux.model,
+    stream: faux.stream,
+    systemPrompt: "Reply once.",
+    messages: [{ role: "user", content: "ping", timestamp: 1 }],
+  },
+  () => {},
+);
+console.log(outcome.status);
+```
+
+The result is `completed`. No active stream remains when the awaited run
+settles. The [test helper](test/support.ts) uses this provider and input shape,
+and [facade tests](test/promise-facade.test.ts) compare Promise and Effect
+lifecycles. This fake provider checks orchestration rather than a real supplier.
+
+For a real model, supply Pi's `Model<Api>` and either its normal `streamSimple`
+or an explicit provider stream. The host supplies credentials and billing. Await
+the listener: its completion is part of the run's lifecycle.
+
+## Tools and control
+
+A tool pairs Pi's descriptor with `prepare(call, signal)`. Preparation decodes
+and authorizes the exact call. It returns either a typed rejection or a prepared
+executor. The Promise executor yields parts through an `AsyncIterable`. The
+Effect executor uses a Stream. Every executor must observe cancellation.
+
+Run, turn, message and tool events carry causal identities. They let the host
+record which execution produced an observation. They do not create durable
+Session storage. Hosts may select parallel or sequential tool execution, steer
+active work and queue follow-up input through the existing control interfaces.
+
+A tool opts into safe crash replay only when it is read-only or explicitly
+idempotent. The host persists the checkpoints needed to use `resume`. Declaring
+`replay: "safe"` does not make an external write idempotent. Pi's provider
+messages and replay fields pass through unchanged.
+
+## Cancellation, retries and errors
+
+Abort the Promise facade's signal or interrupt the Effect fiber. Mule aborts the
+Pi stream and running tools and records one cancelled `run_end`. The Promise
+facade preserves an `Error` abort reason and rejects with it. A non-`Error`
+reason becomes an `AbortError`. An operation that ignores abort still needs its
+host to account for the backing work.
+
+Tool preparation rejections and execution failures become model-visible error
+results, so the run can continue. Fatal model or control failures produce a
+failed `run_end`. A failed listener cannot be trusted to record that terminal
+event. Preserve the rejection and its cause when reporting it.
+
+`retry` selects Pi's bounded retry policy for each assistant call. Omitting it
+means no retry. Provider Retry-After evidence and retry observations use the
+existing run interfaces. Mule does not choose a provider policy for your host.
+`modelStreamIdleTimeoutMs` bounds silence between provider events.
+
+Mule owns no model catalog, credential store, durable Session database,
+compaction service or process-restart scheduler. Compose those in the host.
+
+## API and examples
+
+Use the [generated API reference](docs/api/README.md) and the exports in
+[package.json](package.json).
+[Cancellation parity](test/cancellation-parity.test.ts),
+[retry policy](test/retry-policy.test.ts) and
+[tool batch](test/tool-batch.test.ts) tests exercise the shared loop.
+
+[The prompt example](examples/prompt.ts) is an optional live-provider caller. It
+requires `CAMEL_API_KEY` supplied through your local environment. Its endpoint
+and model overrides belong to that example, not to Mule's API. It is not needed
+for the deterministic quick start. Do not commit credentials.
+
+## Contribute and license
+
+Add an orchestration regression using the existing faux provider. From the root:
+
+```sh
+pnpm --dir packages/mule run test
+pnpm --dir packages/mule run docs
+```
+
+MIT. See [LICENSE](LICENSE) and [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES).

package/THIRD_PARTY_NOTICES

@@ -0,0 +1,15 @@
+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
+license terms.
+
+The Pi dependency is pinned from commit
+853a80d26c90a14c1886f0ebb8ffaae133ca2185 and distributed under the MIT
+License, Copyright (c) 2025 Mario Zechner. Its independently archived source
+boundary has SHA-256
+dfb11f4c1c00e47003db12765371198e944c8b640c995a1dc1cf9130bc9e49ee.
+
+`src/effect.ts` is an Effect-language adaptation of the model/tool loop in
+@earendil-works/pi-agent-core 0.84.4 at that commit. It also preserves reviewed
+behavior from Botanical's retained @shiit/agent-core 0.66.2 at commit
+b6eabe5dfd3cac9514025d26abbe9a92b083f10b, distributed under the MIT License,
+Copyright (c) 2024 fungi.computer.

package/dist/contract.d.ts

@@ -0,0 +1,192 @@
+import type { Api, AssistantMessage, AssistantMessageEvent, AssistantMessageEventStream, TranscriptContext, ImageContent, JsonValue, Message, Model, RetryPolicy, SimpleStreamOptions, TextContent, ToolCall, ToolResultMessage, Usage } from "@earendil-works/pi-ai";
+/** Pi's model stream function, supplied explicitly by the caller. */
+export type MuleStreamFunction = (model: Model<Api>, context: TranscriptContext, 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. */
+export type MuleIdentity = {
+    readonly kind: MuleIdentityKind;
+    readonly value: string;
+    readonly parent?: MuleIdentity | undefined;
+};
+/** Expected failure from Mule's model, tool, control, or listener work. */
+export type MuleError = {
+    readonly _tag: "MuleError";
+    readonly phase: "model" | "tool" | "control" | "listener";
+    readonly message: string;
+    /** The underlying rejection or thrown value, when one exists. */
+    readonly cause?: unknown;
+};
+/** Result produced by a tool before Mule forms Pi's correlated result message. */
+export type MuleToolResult = {
+    readonly content: (TextContent | ImageContent)[];
+    readonly details?: JsonValue | undefined;
+    readonly usage?: Usage | undefined;
+    readonly isError: boolean;
+    readonly terminate?: boolean | undefined;
+};
+/** Progress or terminal output from one tool execution. */
+export type MuleToolExecutionPart = {
+    readonly type: "update";
+    readonly result: MuleToolResult;
+} | {
+    readonly type: "result";
+    readonly result: MuleToolResult;
+};
+/** A real parser or authorization rejection produced before tool execution. */
+export type MuleToolRejection = {
+    readonly message: string;
+    readonly terminate?: boolean | undefined;
+};
+/** Facts from a completed Pi turn supplied to the retained stop hook. */
+export type MuleCompletedTurn = {
+    readonly message: AssistantMessage;
+    readonly toolResults: readonly ToolResultMessage[];
+    readonly context: readonly Message[];
+    readonly newMessages: readonly Message[];
+};
+/** Lifecycle emitted around Pi values. Pi messages and events are not rewritten. */
+export type MuleEvent = {
+    readonly type: "run_start";
+    readonly run: MuleIdentity;
+} | {
+    /** Exact prompt sent on this model attempt, including after a retry. */
+    readonly type: "model_prompt";
+    readonly run: MuleIdentity;
+    readonly turn: MuleIdentity;
+    readonly attempt: number;
+    readonly systemPrompt: string;
+} | {
+    readonly type: "turn_start";
+    readonly run: MuleIdentity;
+    readonly turn: MuleIdentity;
+} | {
+    readonly type: "message_start";
+    readonly run: MuleIdentity;
+    readonly turn: MuleIdentity;
+    readonly message: MuleIdentity;
+    readonly value: Message;
+} | {
+    readonly type: "message_update";
+    readonly run: MuleIdentity;
+    readonly turn: MuleIdentity;
+    readonly message: MuleIdentity;
+    readonly value: AssistantMessage;
+    readonly event: AssistantMessageEvent;
+} | {
+    readonly type: "message_end";
+    readonly run: MuleIdentity;
+    readonly turn: MuleIdentity;
+    readonly message: MuleIdentity;
+    readonly value: Message;
+} | {
+    readonly type: "tool_execution_start";
+    readonly replay: "safe" | "unsafe";
+    readonly run: MuleIdentity;
+    readonly turn: MuleIdentity;
+    readonly toolCall: MuleIdentity;
+    readonly call: ToolCall;
+} | {
+    readonly type: "tool_execution_update";
+    readonly run: MuleIdentity;
+    readonly turn: MuleIdentity;
+    readonly toolCall: MuleIdentity;
+    readonly call: ToolCall;
+    readonly result: MuleToolResult;
+} | {
+    readonly type: "tool_execution_end";
+    readonly run: MuleIdentity;
+    readonly turn: MuleIdentity;
+    readonly toolCall: MuleIdentity;
+    readonly call: ToolCall;
+    readonly result: MuleToolResult;
+} | {
+    readonly type: "turn_end";
+    readonly run: MuleIdentity;
+    readonly turn: MuleIdentity;
+    readonly message: AssistantMessage;
+    readonly toolResults: readonly ToolResultMessage[];
+} | {
+    /**
+     * The run's one terminal. A run interrupted after `run_start` ends
+     * `cancelled`; a run that fails with a non-listener `MuleError` ends
+     * `failed`. A listener failure ends the run without this event.
+     */
+    readonly type: "run_end";
+    readonly run: MuleIdentity;
+    readonly terminal: MuleIdentity;
+    readonly outcome: "completed" | "cancelled" | "failed";
+};
+/** Durable evidence for a call in an interrupted assistant turn. */
+export type MuleToolCheckpoint = {
+    readonly call: ToolCall;
+    readonly state: "pending";
+} | {
+    readonly call: ToolCall;
+    readonly state: "started";
+    readonly replay: "safe" | "unsafe";
+} | {
+    readonly call: ToolCall;
+    readonly state: "completed";
+    readonly result: MuleToolResult;
+    /** Present when the transcript message was committed too. */
+    readonly message?: ToolResultMessage | undefined;
+};
+/** Completed assistant turn recovered by the transcript owner, before its next model call. */
+export type MuleResume = {
+    readonly message: AssistantMessage;
+    readonly tools: readonly MuleToolCheckpoint[];
+};
+/** Run inputs that are identical on the Promise and Effect roots. */
+export type MuleRunSettings = {
+    readonly model: Model<Api>;
+    /** Override Pi's default `streamSimple`, primarily for explicit providers and tests. */
+    readonly stream?: MuleStreamFunction | undefined;
+    readonly systemPrompt: string;
+    readonly messages: readonly Message[];
+    /** 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;
+    /** 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`).
+     * Undefined means no retry, matching pi-ai's own default. Hosts that want
+     * Pi coding-agent's numbers pass `piCodingAgentRetryDefaults`.
+     */
+    readonly retry?: RetryPolicy | undefined;
+    /** 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. */
+export type MuleRetryObservation = {
+    readonly type: "retry_scheduled";
+    readonly run: MuleIdentity;
+    readonly turn: MuleIdentity;
+    readonly attempt: number;
+    readonly maxAttempts: number;
+    readonly delayMs: number;
+    readonly errorMessage: string;
+} | {
+    readonly type: "retry_attempt_started";
+    readonly run: MuleIdentity;
+    readonly turn: MuleIdentity;
+    readonly attempt: number;
+} | {
+    readonly type: "retry_finished";
+    readonly run: MuleIdentity;
+    readonly turn: MuleIdentity;
+    readonly attempt: number;
+    readonly success: boolean;
+    readonly finalError?: string;
+};
+/** Honest terminal result of one Mule invocation. */
+export type MuleRunOutcome = {
+    readonly status: "completed" | "cancelled" | "failed";
+    readonly run: MuleIdentity;
+    readonly terminal: MuleIdentity;
+    readonly message: AssistantMessage;
+    readonly messages: readonly Message[];
+};

package/dist/contract.js

@@ -0,0 +1 @@
+export {};

package/dist/effect.d.ts

@@ -0,0 +1,73 @@
+import type { AssistantMessage, Message, RetryPolicy, Tool, ToolCall } from "@earendil-works/pi-ai";
+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 "typebox";
+export type { MuleRetryObservation } from "./contract.js";
+/**
+ * Pi coding-agent's retry defaults (`settings-manager.js` `getRetrySettings()`,
+ * `@earendil-works/pi-ai` 0.99.0, the version pinned in the lockfile). Pi-ai's
+ * own `RetryPolicy` has no default — an undefined policy means no retry — so
+ * 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";
+/** A decoded, authorized invocation ready to execute. */
+export type MulePreparedTool = {
+    /** Run the already-decoded and authorized tool call. */
+    readonly execute: () => Stream.Stream<MuleToolExecutionPart, MuleError>;
+};
+/** Pi tool declaration paired with its Effect-native preparation door. */
+export type MuleTool = {
+    readonly descriptor: Tool;
+    /** Only read-only or explicitly idempotent tools may opt into crash replay. */
+    readonly replay?: "safe" | "unsafe" | undefined;
+    readonly executionMode?: "parallel" | "sequential" | undefined;
+    /** Decode and authorize one exact Pi tool call before it can execute. */
+    readonly prepare: (call: ToolCall) => Effect.Effect<MulePreparedTool, MuleToolRejection>;
+};
+/** Effect-native listener. Completion is part of run settlement. */
+export type MuleListener = (event: MuleEvent) => Effect.Effect<void, MuleError>;
+/**
+ * Inputs for one complete Pi model/tool loop. Cancel a run by interrupting its
+ * fiber; the run then ends with a `cancelled` `run_end`.
+ */
+export type MuleRunInput = MuleRunSettings & {
+    /** Rebuild the model system prompt immediately before each provider request. */
+    readonly prepareSystemPrompt?: (() => Effect.Effect<string, MuleError>) | undefined;
+    readonly tools?: readonly MuleTool[] | undefined;
+    /** Resolve a fresh provider credential immediately before each Pi call. */
+    readonly resolveApiKey?: ((provider: string) => Effect.Effect<string | undefined, MuleError>) | undefined;
+    /** Pull messages that should steer the active run at Pi's safe point. */
+    readonly getSteeringMessages?: (() => Effect.Effect<readonly Message[], MuleError>) | undefined;
+    /** Pull messages queued until the run would otherwise finish. */
+    readonly getFollowUpMessages?: (() => Effect.Effect<readonly Message[], MuleError>) | undefined;
+    /**
+     * Pi's between-turn point: after a turn's tool results and before the next
+     * assistant request of the same run. Return a replacement context, such as
+     * one rebuilt after compaction, or `undefined` to keep the current one.
+     */
+    readonly prepareNextTurn?: ((turn: MuleCompletedTurn) => Effect.Effect<readonly Message[] | undefined, MuleError>) | undefined;
+    /** Request a graceful stop after the current Pi turn has fully settled. */
+    readonly shouldStopAfterTurn?: ((turn: MuleCompletedTurn) => Effect.Effect<boolean, MuleError>) | undefined;
+    /** Effect-native observation sink for Pi's retry policy (`retry`), one call per scheduled or finished retry. */
+    readonly onRetry?: ((event: MuleRetryObservation) => Effect.Effect<void, MuleError>) | undefined;
+};
+/** Run Pi's model/tool loop inside Effect without changing Pi's values. */
+export declare function run(input: MuleRunInput, listener?: MuleListener): Effect.Effect<MuleRunOutcome, MuleError>;
+/** Canonical Effect-native Mule interface. */
+export type MuleEffect = {
+    /** Run one complete Pi model/tool loop. */
+    readonly run: (input: MuleRunInput, listener?: MuleListener) => Effect.Effect<MuleRunOutcome, MuleError>;
+};
+/** Canonical Effect-native Mule value. */
+export declare const muleEffect: MuleEffect;