@fungi.computer/mule 0.0.0-stage → 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+import type { Message, Tool, ToolCall } from "@earendil-works/pi-ai";
+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. */
+export type MulePromiseListener = (event: MuleEvent, signal: AbortSignal) => Promise<void> | void;
+/** Outcome of preparing one exact Pi tool call. */
+export type MuleToolPreparation = {
+    readonly status: "prepared";
+    /** Run the already-decoded and authorized call; abort ends it early. */
+    readonly execute: (signal: AbortSignal) => AsyncIterable<MuleToolExecutionPart>;
+} | ({
+    readonly status: "rejected";
+} & MuleToolRejection);
+/** Pi tool declaration paired with its Promise 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, signal: AbortSignal) => Promise<MuleToolPreparation>;
+};
+/** Inputs for one complete Pi model/tool loop through the Promise facade. */
+export type MuleRunInput = MuleRunSettings & {
+    readonly tools?: readonly MuleTool[] | undefined;
+    /** Resolve a fresh provider credential immediately before each Pi call. */
+    readonly resolveApiKey?: ((provider: string, signal: AbortSignal) => Promise<string | undefined>) | undefined;
+    /** Pull messages that should steer the active run at Pi's safe point. */
+    readonly getSteeringMessages?: ((signal: AbortSignal) => Promise<readonly Message[]>) | undefined;
+    /** Pull messages queued until the run would otherwise finish. */
+    readonly getFollowUpMessages?: ((signal: AbortSignal) => Promise<readonly Message[]>) | undefined;
+    /** Request a graceful stop after the current Pi turn has fully settled. */
+    readonly shouldStopAfterTurn?: ((turn: MuleCompletedTurn, signal: AbortSignal) => Promise<boolean>) | undefined;
+};
+/** Promise-facing Mule interface. */
+export type Mule = {
+    /**
+     * Run one complete Pi model/tool loop. Rejects with the `MuleError` that
+     * failed the run, or with the abort reason (an `AbortError` when the reason
+     * is not an `Error`) after the caller aborts `signal`.
+     */
+    readonly run: (input: MuleRunInput, listener?: MulePromiseListener, signal?: AbortSignal) => Promise<MuleRunOutcome>;
+};
+/** Default Promise-facing Mule interface. */
+export declare const mule: Mule;

package/dist/index.js

@@ -0,0 +1,97 @@
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Option from "effect/Option";
+import * as Stream from "effect/Stream";
+import { run as runEffect, } from "./effect.js";
+function fromPromise(phase, message, evaluate) {
+    return Effect.tryPromise({
+        try: (signal) => Promise.resolve(evaluate(signal)),
+        catch: (cause) => ({ _tag: "MuleError", phase, message, cause }),
+    });
+}
+function executionStream(call, execute) {
+    // Effect closes the iterator with `return()`, which an async generator only
+    // honours at its next yield. Abort first so a tool awaiting its signal can
+    // reach that point instead of holding interruption open.
+    const execution = {
+        [Symbol.asyncIterator]() {
+            const controller = new AbortController();
+            const iterator = execute(controller.signal)[Symbol.asyncIterator]();
+            return {
+                next: () => iterator.next(),
+                return: async () => {
+                    controller.abort();
+                    return ((await iterator.return?.()) ?? { done: true, value: undefined });
+                },
+            };
+        },
+    };
+    return Stream.fromAsyncIterable(execution, (cause) => ({
+        _tag: "MuleError",
+        phase: "tool",
+        message: `Tool "${call.name}" failed`,
+        cause,
+    }));
+}
+function liftTool(tool) {
+    return {
+        descriptor: tool.descriptor,
+        executionMode: tool.executionMode,
+        replay: tool.replay,
+        prepare: (call) => Effect.tryPromise({
+            try: (signal) => tool.prepare(call, signal),
+            catch: () => ({
+                message: `Tool "${call.name}" could not be prepared`,
+            }),
+        }).pipe(Effect.flatMap((preparation) => preparation.status === "rejected"
+            ? Effect.fail({
+                message: preparation.message,
+                terminate: preparation.terminate,
+            })
+            : Effect.succeed({
+                execute: () => executionStream(call, preparation.execute),
+            }))),
+    };
+}
+/** Adapt the complete Promise port set once into the canonical Effect ports. */
+function liftInput(input) {
+    const { tools, resolveApiKey, getSteeringMessages, getFollowUpMessages, shouldStopAfterTurn, ...settings } = input;
+    return {
+        ...settings,
+        tools: tools?.map(liftTool),
+        resolveApiKey: resolveApiKey &&
+            ((provider) => fromPromise("model", "Mule could not resolve the API key", (signal) => resolveApiKey(provider, signal))),
+        getSteeringMessages: getSteeringMessages &&
+            (() => fromPromise("control", "Mule could not read steering messages", getSteeringMessages)),
+        getFollowUpMessages: getFollowUpMessages &&
+            (() => fromPromise("control", "Mule could not read follow-up messages", getFollowUpMessages)),
+        shouldStopAfterTurn: shouldStopAfterTurn &&
+            ((turn) => fromPromise("control", "Mule stop hook failed", (signal) => shouldStopAfterTurn(turn, signal))),
+    };
+}
+const noListener = () => undefined;
+async function run(input, listener = noListener, signal) {
+    if (signal?.aborted === true)
+        throw abortReason(signal);
+    const program = runEffect(liftInput(input), (event) => fromPromise("listener", "Mule listener failed", (listenerSignal) => listener(event, listenerSignal)));
+    const exit = await Effect.runPromiseExit(program, signal === undefined ? undefined : { signal });
+    if (Exit.isSuccess(exit))
+        return exit.value;
+    const error = Cause.findErrorOption(exit.cause);
+    // Preserve the facade's documented typed MuleError rejection.
+    if (Option.isSome(error))
+        return Effect.runPromise(Effect.fail(error.value));
+    if (signal !== undefined && Cause.hasInterruptsOnly(exit.cause))
+        throw abortReason(signal);
+    throw Cause.squash(exit.cause);
+}
+/** The caller's abort reason, as `fetch` rejects; never a non-Error value. */
+function abortReason(signal) {
+    const reason = signal.reason;
+    return reason instanceof Error
+        ? reason
+        : new DOMException("The operation was aborted", "AbortError");
+}
+/** Default Promise-facing Mule interface. */
+export const mule = { run };

package/dist/testing.d.ts

@@ -0,0 +1,15 @@
+import { type FauxProviderHandle, type FauxResponseStep, type RegisterFauxProviderOptions } from "@earendil-works/pi-ai/providers/faux";
+import type { Api, Model } from "@earendil-works/pi-ai";
+/** 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"];
+    /** 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"];
+}>;
+/** Create a credential-free model for tests and runnable examples. */
+export declare function fauxModel(replies: readonly FauxResponseStep[], options?: RegisterFauxProviderOptions): FauxModel;

package/dist/testing.js

@@ -0,0 +1,14 @@
+import { fauxProvider, } from "@earendil-works/pi-ai/providers/faux";
+/** Create a credential-free model for tests and runnable examples. */
+export function fauxModel(replies, options = {}) {
+    const faux = fauxProvider(options);
+    faux.setResponses([...replies]);
+    return {
+        model: faux.getModel(),
+        stream: faux.provider.streamSimple.bind(faux.provider),
+        setResponses: (responses) => {
+            faux.setResponses([...responses]);
+        },
+        state: faux.state,
+    };
+}

package/docs/api/README.md

@@ -0,0 +1,15 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+**@fungi.computer/mule**
+
+---
+
+# @fungi.computer/mule
+
+## Modules
+
+| Module                | Description |
+| --------------------- | ----------- |
+| [effect](effect.md)   | -           |
+| [index](index.md)     | -           |
+| [testing](testing.md) | -           |

package/docs/api/effect.md

@@ -0,0 +1,350 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/mule**](README.md)
+
+---
+
+[@fungi.computer/mule](README.md) / effect
+
+# effect
+
+## Type Aliases
+
+### MuleRetryObservation
+
+```ts
+type MuleRetryObservation =
+  | {
+      type: "retry_scheduled";
+      run: MuleIdentity;
+      turn: MuleIdentity;
+      attempt: number;
+      maxAttempts: number;
+      delayMs: number;
+      errorMessage: string;
+    }
+  | {
+      type: "retry_attempt_started";
+      run: MuleIdentity;
+      turn: MuleIdentity;
+      attempt: number;
+    }
+  | {
+      type: "retry_finished";
+      run: MuleIdentity;
+      turn: MuleIdentity;
+      attempt: number;
+      success: boolean;
+      finalError?: string;
+    };
+```
+
+One observed Pi-retry event around a single assistant call.
+
+---
+
+### MulePreparedTool
+
+```ts
+type MulePreparedTool = object;
+```
+
+A decoded, authorized invocation ready to execute.
+
+#### Properties
+
+##### execute
+
+```ts
+readonly execute: () => Stream.Stream<MuleToolExecutionPart, MuleError>;
+```
+
+Run the already-decoded and authorized tool call.
+
+###### Returns
+
+`Stream.Stream`\<[`MuleToolExecutionPart`](index.md#muletoolexecutionpart),
+[`MuleError`](index.md#muleerror)\>
+
+---
+
+### MuleTool
+
+```ts
+type MuleTool = object;
+```
+
+Pi tool declaration paired with its Effect-native preparation door.
+
+#### Properties
+
+##### descriptor
+
+```ts
+readonly descriptor: Tool;
+```
+
+##### replay?
+
+```ts
+readonly optional replay?: "safe" | "unsafe";
+```
+
+Only read-only or explicitly idempotent tools may opt into crash replay.
+
+##### executionMode?
+
+```ts
+readonly optional executionMode?: "parallel" | "sequential";
+```
+
+##### prepare
+
+```ts
+readonly prepare: (call) => Effect.Effect<MulePreparedTool, MuleToolRejection>;
+```
+
+Decode and authorize one exact Pi tool call before it can execute.
+
+###### Parameters
+
+| Parameter | Type       |
+| --------- | ---------- |
+| `call`    | `ToolCall` |
+
+###### Returns
+
+`Effect.Effect`\<[`MulePreparedTool`](#mulepreparedtool),
+[`MuleToolRejection`](index.md#muletoolrejection)\>
+
+---
+
+### MuleListener
+
+```ts
+type MuleListener = (event) => Effect.Effect<void, MuleError>;
+```
+
+Effect-native listener. Completion is part of run settlement.
+
+#### Parameters
+
+| Parameter | Type                              |
+| --------- | --------------------------------- |
+| `event`   | [`MuleEvent`](index.md#muleevent) |
+
+#### Returns
+
+`Effect.Effect`\<`void`, [`MuleError`](index.md#muleerror)\>
+
+---
+
+### MuleRunInput
+
+```ts
+type MuleRunInput = MuleRunSettings & object;
+```
+
+Inputs for one complete Pi model/tool loop. Cancel a run by interrupting its
+fiber; the run then ends with a `cancelled` `run_end`.
+
+#### Type Declaration
+
+| Name                     | Type                                                                                                  | Description                                                                                                                                                                                                             |
+| ------------------------ | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `prepareSystemPrompt()?` | () => `Effect.Effect`\<`string`, [`MuleError`](index.md#muleerror)\>                                  | Rebuild the model system prompt immediately before each provider request.                                                                                                                                               |
+| `tools?`                 | readonly [`MuleTool`](#muletool)[]                                                                    | -                                                                                                                                                                                                                       |
+| `resolveApiKey()?`       | (`provider`) => `Effect.Effect`\<`string` \| `undefined`, [`MuleError`](index.md#muleerror)\>         | Resolve a fresh provider credential immediately before each Pi call.                                                                                                                                                    |
+| `getSteeringMessages()?` | () => `Effect.Effect`\<readonly `Message`[], [`MuleError`](index.md#muleerror)\>                      | Pull messages that should steer the active run at Pi's safe point.                                                                                                                                                      |
+| `getFollowUpMessages()?` | () => `Effect.Effect`\<readonly `Message`[], [`MuleError`](index.md#muleerror)\>                      | Pull messages queued until the run would otherwise finish.                                                                                                                                                              |
+| `prepareNextTurn()?`     | (`turn`) => `Effect.Effect`\<readonly `Message`[] \| `undefined`, [`MuleError`](index.md#muleerror)\> | 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. |
+| `shouldStopAfterTurn()?` | (`turn`) => `Effect.Effect`\<`boolean`, [`MuleError`](index.md#muleerror)\>                           | Request a graceful stop after the current Pi turn has fully settled.                                                                                                                                                    |
+| `onRetry()?`             | (`event`) => `Effect.Effect`\<`void`, [`MuleError`](index.md#muleerror)\>                             | Effect-native observation sink for Pi's retry policy (`retry`), one call per scheduled or finished retry.                                                                                                               |
+
+---
+
+### MuleEffect
+
+```ts
+type MuleEffect = object;
+```
+
+Canonical Effect-native Mule interface.
+
+#### Properties
+
+##### run
+
+```ts
+readonly run: (input, listener?) => Effect.Effect<MuleRunOutcome, MuleError>;
+```
+
+Run one complete Pi model/tool loop.
+
+###### Parameters
+
+| Parameter   | Type                            |
+| ----------- | ------------------------------- |
+| `input`     | [`MuleRunInput`](#muleruninput) |
+| `listener?` | [`MuleListener`](#mulelistener) |
+
+###### Returns
+
+`Effect.Effect`\<[`MuleRunOutcome`](index.md#mulerunoutcome),
+[`MuleError`](index.md#muleerror)\>
+
+## Variables
+
+### piCodingAgentRetryDefaults
+
+```ts
+const piCodingAgentRetryDefaults: RetryPolicy;
+```
+
+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.
+
+---
+
+### piHttpIdleTimeoutMs
+
+```ts
+const piHttpIdleTimeoutMs: 300000 = 300_000;
+```
+
+Pi coding-agent's default stream idle timeout (`DEFAULT_HTTP_IDLE_TIMEOUT_MS`,
+`settings-manager.js`). A host that wants Pi's number for
+`modelStreamIdleTimeoutMs` passes this explicitly.
+
+---
+
+### muleEffect
+
+```ts
+const muleEffect: MuleEffect;
+```
+
+Canonical Effect-native Mule value.
+
+## Functions
+
+### isContextOverflow()
+
+```ts
+function isContextOverflow(message, contextWindow?): boolean;
+```
+
+Apply Pi's maintained context-overflow semantics to an exact Pi message.
+
+#### Parameters
+
+| Parameter        | Type               |
+| ---------------- | ------------------ |
+| `message`        | `AssistantMessage` |
+| `contextWindow?` | `number`           |
+
+#### Returns
+
+`boolean`
+
+---
+
+### run()
+
+```ts
+function run(input, listener?): Effect<MuleRunOutcome, MuleError>;
+```
+
+Run Pi's model/tool loop inside Effect without changing Pi's values.
+
+#### Parameters
+
+| Parameter  | Type                            | Default value |
+| ---------- | ------------------------------- | ------------- |
+| `input`    | [`MuleRunInput`](#muleruninput) | `undefined`   |
+| `listener` | [`MuleListener`](#mulelistener) | `noListener`  |
+
+#### Returns
+
+`Effect`\<[`MuleRunOutcome`](index.md#mulerunoutcome),
+[`MuleError`](index.md#muleerror)\>
+
+## References
+
+### MuleCompletedTurn
+
+Re-exports [MuleCompletedTurn](index.md#mulecompletedturn)
+
+---
+
+### MuleResume
+
+Re-exports [MuleResume](index.md#muleresume)
+
+---
+
+### MuleToolCheckpoint
+
+Re-exports [MuleToolCheckpoint](index.md#muletoolcheckpoint)
+
+---
+
+### MuleError
+
+Re-exports [MuleError](index.md#muleerror)
+
+---
+
+### MuleEvent
+
+Re-exports [MuleEvent](index.md#muleevent)
+
+---
+
+### MuleIdentity
+
+Re-exports [MuleIdentity](index.md#muleidentity)
+
+---
+
+### MuleIdentityKind
+
+Re-exports [MuleIdentityKind](index.md#muleidentitykind)
+
+---
+
+### MuleRunOutcome
+
+Re-exports [MuleRunOutcome](index.md#mulerunoutcome)
+
+---
+
+### MuleRunSettings
+
+Re-exports [MuleRunSettings](index.md#mulerunsettings)
+
+---
+
+### MuleStreamFunction
+
+Re-exports [MuleStreamFunction](index.md#mulestreamfunction)
+
+---
+
+### MuleToolExecutionPart
+
+Re-exports [MuleToolExecutionPart](index.md#muletoolexecutionpart)
+
+---
+
+### MuleToolRejection
+
+Re-exports [MuleToolRejection](index.md#muletoolrejection)
+
+---
+
+### MuleToolResult
+
+Re-exports [MuleToolResult](index.md#muletoolresult)