@fungi.computer/mule 0.2.2 → 0.2.3

package/dist/contract.d.ts

@@ -80,6 +80,10 @@ export type MuleEvent = {
     readonly turn: MuleIdentity;
     readonly message: MuleIdentity;
     readonly value: Message;
+    /** Commit the assistant and its retry decision together before observing retry. */
+    readonly retry?: Exclude<MuleRetryObservation, {
+        type: "retry_attempt_started";
+    }> | undefined;
     /** Application payload independent of the completed model message. */
     readonly data?: JsonValue | undefined;
 } | {
@@ -135,11 +139,24 @@ export type MuleToolCheckpoint = {
     /** 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[];
-};
+/** Transcript-owned continuation at a completed assistant or model retry boundary. */
+export type MuleResume = Readonly<{
+    kind: "assistant";
+    message: AssistantMessage;
+    tools: readonly MuleToolCheckpoint[];
+}> | (Readonly<{
+    kind: "retry";
+    /** Number of the retry waiting or already dispatched; zero is the initial request. */
+    attempt: number;
+    /** The previously recorded retry ceiling, when a retry has been scheduled. */
+    maxAttempts?: number;
+    message?: AssistantMessage;
+}> & (Readonly<{
+    phase: "waiting";
+    dueAt: number;
+}> | Readonly<{
+    phase: "dispatched";
+}>));
 /** Run inputs that are identical on the Promise and Effect roots. */
 export type MuleRunSettings = {
     readonly model: Model<Api>;
@@ -185,6 +202,7 @@ export type MuleRetryObservation = {
     readonly attempt: number;
     readonly maxAttempts: number;
     readonly delayMs: number;
+    readonly dueAt: number;
     readonly errorMessage: string;
 } | {
     readonly type: "retry_attempt_started";

package/dist/effect.d.ts

@@ -11,7 +11,7 @@ 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
+ * `@earendil-works/pi-ai` 1.3.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.
  */
@@ -40,6 +40,8 @@ export type MuleListener = (event: MuleEvent) => Effect.Effect<void, MuleError>;
  * fiber; the run then ends with a `cancelled` `run_end`.
  */
 export type MuleRunInput = MuleRunSettings & {
+    /** Notify the owner when provider cleanup was detached or failed; abort alone is not drain evidence. */
+    readonly onUndrained?: Effect.Effect<void> | undefined;
     /** Rebuild the model system prompt immediately before each provider request. */
     readonly prepareSystemPrompt?: (() => Effect.Effect<string, MuleError>) | undefined;
     readonly tools?: readonly MuleTool[] | undefined;

package/dist/effect.js

@@ -20,7 +20,7 @@ import * as Stream from "effect/Stream";
 export { Type } from "typebox";
 /**
  * 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
+ * `@earendil-works/pi-ai` 1.3.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.
  */
@@ -279,9 +279,35 @@ function streamTurn(input, context, run, turn, emit, attempt) {
             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");
-        }));
+        const provider = {};
+        yield* Effect.addFinalizer(() => Effect.tryPromise({
+            try: () => {
+                controller.abort("Mule model scope closed");
+                if (provider.response === undefined)
+                    return Promise.resolve(true);
+                // Iterator.return only closes the consumer. Pi's result is the
+                // producer's terminal, including an abort-aware provider's error.
+                const cleanup = provider.response.then(async (response) => {
+                    await Promise.all([
+                        provider.iterator?.return?.(),
+                        response.result(),
+                    ]);
+                }, () => undefined);
+                return new Promise((resolve) => {
+                    const timer = setTimeout(() => {
+                        resolve(false);
+                    }, providerIteratorReleaseGraceMs);
+                    cleanup.then(() => {
+                        clearTimeout(timer);
+                        resolve(true);
+                    }, () => {
+                        clearTimeout(timer);
+                        resolve(false);
+                    });
+                });
+            },
+            catch: (cause) => failure("model", "Pi model stream failed", cause),
+        }).pipe(Effect.orElseSucceed(() => false), Effect.flatMap((released) => released ? Effect.void : (input.onUndrained ?? Effect.void))));
         const resolvedApiKey = (input.resolveApiKey === undefined
             ? undefined
             : yield* input.resolveApiKey(input.model.provider)) ??
@@ -306,30 +332,15 @@ function streamTurn(input, context, run, turn, emit, attempt) {
         if (descriptors.length > 0)
             piContext.tools = descriptors;
         const response = yield* deadline(Effect.tryPromise({
-            try: async () => {
+            try: () => {
                 const stream = input.stream ?? streamPi;
-                return stream(input.model, normalizeContext(piContext), options);
+                provider.response = Promise.resolve(stream(input.model, normalizeContext(piContext), options));
+                return provider.response;
             },
             catch: (cause) => failure("model", "Pi model stream could not start", cause),
         }));
-        const iterator = yield* Effect.acquireRelease(Effect.sync(() => response[Symbol.asyncIterator]()), (active) => Effect.tryPromise({
-            try: () => {
-                controller.abort("Mule model stream closed");
-                // Provider iterators can ignore abort while a read is pending.
-                // Releasing a timed-out run must not await that iterator forever.
-                return new Promise((resolve) => {
-                    const timer = setTimeout(resolve, providerIteratorReleaseGraceMs);
-                    Promise.resolve(active.return?.()).then(() => {
-                        clearTimeout(timer);
-                        resolve();
-                    }, () => {
-                        clearTimeout(timer);
-                        resolve();
-                    });
-                });
-            },
-            catch: (cause) => failure("model", "Pi model stream failed", cause),
-        }).pipe(Effect.ignore));
+        const iterator = response[Symbol.asyncIterator]();
+        provider.iterator = iterator;
         const observeEvent = (event) => {
             const now = Date.now();
             maxGapMs = Math.max(maxGapMs, now - lastEventAt);
@@ -409,14 +420,7 @@ function streamTurn(input, context, run, turn, emit, attempt) {
                 value: completed,
             });
         }
-        yield* emit({
-            type: "message_end",
-            run,
-            turn,
-            message: messageIdentity,
-            value: completed,
-        });
-        return { identity: messageIdentity, message: completed };
+        return { message: completed, identity: messageIdentity };
     }).pipe(Effect.catch((error) => {
         if (error.cause !== modelLimitCause)
             return Effect.fail(error);
@@ -459,13 +463,6 @@ function streamTurn(input, context, run, turn, emit, attempt) {
             }
             else
                 context[context.length - 1] = value;
-            yield* emit({
-                type: "message_end",
-                run,
-                turn,
-                message: messageIdentity,
-                value,
-            });
             return {
                 identity: messageIdentity,
                 message: value,
@@ -483,7 +480,7 @@ function streamTurn(input, context, run, turn, emit, attempt) {
  * failed attempt's message is removed from `context` before the next
  * attempt runs, so it is never replayed into the model's next call.
  */
-function streamTurnWithRetry(input, context, run, turn, emit) {
+function streamTurnWithRetry(input, context, run, turn, emit, resume) {
     return Effect.gen(function* () {
         // One turn owns one finite budget, even if its caller updates future policy.
         const policy = input.retry === undefined ? undefined : { ...input.retry };
@@ -495,10 +492,13 @@ function streamTurnWithRetry(input, context, run, turn, emit) {
             ].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 calls = 0;
-        let retries = 0;
+        const maxRetries = Math.min(policy?.maxRetries ?? 0, resume?.maxAttempts ?? Infinity);
+        let calls = resume === undefined
+            ? 0
+            : resume.attempt + (resume.phase === "dispatched" ? 1 : 0);
+        let retries = resume?.attempt ?? 0;
         let finished = false;
-        let lastError;
+        let lastError = resume?.message?.errorMessage;
         const reportRetry = (event) => input.onRetry === undefined ? Effect.void : input.onRetry(event);
         const finish = (success, finalError) => Effect.gen(function* () {
             finished = true;
@@ -513,66 +513,130 @@ function streamTurnWithRetry(input, context, run, turn, emit) {
                     finalError,
                 });
         });
+        const waitForRetry = (dueAt) => Effect.gen(function* () {
+            yield* Effect.sleep(Math.max(0, dueAt - Date.now()));
+            yield* reportRetry({
+                type: "retry_attempt_started",
+                run,
+                turn,
+                attempt: retries,
+            });
+        });
+        const prepareRetry = (errorMessage, after) => Effect.gen(function* () {
+            if (policy === undefined)
+                return yield* Effect.fail(failure("model", "Retry policy is unavailable"));
+            retries++;
+            lastError = errorMessage;
+            const minimumDelayMs = Math.max(retryDelayMs(policy, retries), after !== undefined &&
+                Number.isSafeInteger(after) &&
+                after >= 0 &&
+                after <= 60_000
+                ? after
+                : 0);
+            // Add rather than subtract jitter: a provider's Retry-After is a floor.
+            // Jitter stops at one minute; a longer explicit host policy stays intact.
+            const jitterMs = Math.min(1_000, minimumDelayMs / 4, Math.max(0, 60_000 - minimumDelayMs));
+            const delayMs = minimumDelayMs + Math.floor(Math.random() * jitterMs);
+            const dueAt = Date.now() + delayMs;
+            return {
+                type: "retry_scheduled",
+                run,
+                turn,
+                attempt: retries,
+                maxAttempts: maxRetries,
+                delayMs,
+                dueAt,
+                errorMessage: lastError,
+            };
+        });
         return yield* Effect.gen(function* () {
+            if (resume !== undefined) {
+                if (!Number.isSafeInteger(resume.attempt) ||
+                    resume.attempt < 0 ||
+                    (resume.maxAttempts !== undefined &&
+                        (!Number.isSafeInteger(resume.maxAttempts) ||
+                            resume.maxAttempts < 0)) ||
+                    (resume.phase === "waiting" &&
+                        (!Number.isSafeInteger(resume.dueAt) || resume.dueAt < 0)))
+                    return yield* Effect.fail(failure("model", "Invalid model retry continuation"));
+                if (!policy?.enabled ||
+                    retries > maxRetries ||
+                    (resume.phase === "dispatched" && retries >= maxRetries)) {
+                    yield* finish(false, "Model retry budget exhausted after restart");
+                    return resume.message === undefined
+                        ? yield* Effect.fail(failure("model", "Model retry budget exhausted after restart"))
+                        : { message: resume.message };
+                }
+                if (resume.phase === "waiting")
+                    yield* waitForRetry(resume.dueAt);
+                else {
+                    // A restart is not provider backpressure: charge the attempt, resend now.
+                    const retry = {
+                        ...(yield* prepareRetry("Model request interrupted by a restart")),
+                        delayMs: 0,
+                        dueAt: Date.now(),
+                    };
+                    yield* reportRetry(retry);
+                    yield* waitForRetry(retry.dueAt);
+                }
+            }
             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);
+                const streamed = yield* streamTurn(input, context, run, turn, emit, ++calls);
+                latest = streamed;
+                const message = streamed.message;
+                let retry;
+                if (message.stopReason === "error" &&
+                    policy?.enabled &&
+                    retries < maxRetries) {
+                    const retryable = yield* Effect.try({
+                        try: () => streamed.limitReached === true || input.retryable(message),
+                        catch: (cause) => failure("model", "Typed model retry decision failed", cause),
+                    });
+                    if (retryable) {
+                        const after = yield* Effect.try({
+                            try: () => input.retryAfterMs?.(message),
+                            catch: (cause) => failure("model", "Model retry delay observation failed", cause),
+                        });
+                        retry = yield* prepareRetry(message.errorMessage ?? "Unknown error", after);
                     }
-                    return latest;
                 }
-                const retryable = yield* Effect.try({
-                    try: () => latest?.limitReached === true || 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;
+                if (retry === undefined &&
+                    (message.stopReason === "error" || retries > 0)) {
+                    const terminal = {
+                        type: "retry_finished",
+                        run,
+                        turn,
+                        attempt: retries,
+                        success: message.stopReason !== "error" &&
+                            message.stopReason !== "aborted",
+                    };
+                    retry =
+                        message.stopReason === "error" && message.errorMessage !== undefined
+                            ? { ...terminal, finalError: message.errorMessage }
+                            : terminal;
                 }
-                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 minimumDelayMs = Math.max(retryDelayMs(policy, retries), after !== undefined &&
-                    Number.isSafeInteger(after) &&
-                    after >= 0 &&
-                    after <= 60_000
-                    ? after
-                    : 0);
-                // Add rather than subtract jitter: a provider's Retry-After is a floor.
-                // Jitter stops at one minute; a longer explicit host policy stays intact.
-                const jitterMs = Math.min(1_000, minimumDelayMs / 4, Math.max(0, 60_000 - minimumDelayMs));
-                const delayMs = minimumDelayMs + Math.floor(Math.random() * jitterMs);
-                yield* reportRetry({
-                    type: "retry_scheduled",
-                    run,
-                    turn,
-                    attempt: retries,
-                    maxAttempts: policy.maxRetries,
-                    delayMs,
-                    errorMessage: lastError,
-                });
-                yield* Effect.sleep(delayMs);
-                yield* reportRetry({
-                    type: "retry_attempt_started",
+                // The recorder receives one decision boundary. No await can expose a
+                // completed error without the retry deadline (or terminal decision).
+                yield* emit({
+                    type: "message_end",
                     run,
                     turn,
-                    attempt: retries,
+                    message: streamed.identity,
+                    value: message,
+                    retry,
                 });
+                if (retry?.type === "retry_finished")
+                    finished = true;
+                if (retry !== undefined && retries > 0)
+                    yield* reportRetry(retry);
+                if (retry?.type !== "retry_scheduled")
+                    return latest;
+                yield* waitForRetry(retry.dueAt);
             }
         }).pipe(Effect.onInterrupt(() => retries === 0 || finished ? Effect.void : finish(false, lastError)));
     });
@@ -603,11 +667,11 @@ function emitPendingMessages(messages, context, newMessages, run, turn, emit) {
         });
     })).pipe(Effect.asVoid);
 }
-function completeLoopTurn(input, context, newMessages, run, turn, pending, emit) {
+function completeLoopTurn(input, context, newMessages, run, turn, pending, emit, retryResume) {
     return Effect.gen(function* () {
         yield* emit({ type: "turn_start", run, turn });
         yield* emitPendingMessages(pending, context, newMessages, run, turn, emit);
-        const streamed = yield* streamTurnWithRetry(input, context, run, turn, emit);
+        const streamed = yield* streamTurnWithRetry(input, context, run, turn, emit, retryResume);
         // Pi keeps partially streamed tool calls on an aborted or errored message.
         // Like Pi's loop, the turn ends there: nothing executes and no tool result
         // pretends a call ran. The run then settles with the honest terminal.
@@ -800,7 +864,8 @@ function runLoop(input, emit, runIdentity, terminalIdentity) {
         let finalMessage;
         let continueLoop;
         yield* emit({ type: "run_start", run: runIdentity });
-        if (input.resume !== undefined) {
+        let retryResume = input.resume?.kind === "retry" ? input.resume : undefined;
+        if (input.resume?.kind === "assistant") {
             const resumed = yield* resumeTurn(input, input.resume, context, newMessages, runIdentity, emit);
             const status = statusFor(resumed.message);
             const next = status === "completed"
@@ -811,7 +876,8 @@ function runLoop(input, emit, runIdentity, terminalIdentity) {
             pending.push(...next.pending);
         }
         do {
-            const completed = yield* completeLoopTurn(input, context, newMessages, runIdentity, identity("turn", runIdentity), pending, emit);
+            const completed = yield* completeLoopTurn(input, context, newMessages, runIdentity, identity("turn", runIdentity), pending, emit, retryResume);
+            retryResume = undefined;
             finalMessage = completed.message;
             const status = statusFor(completed.message);
             if (status !== "completed") {

package/docs/api/effect.md

@@ -21,6 +21,7 @@ type MuleRetryObservation =
       attempt: number;
       maxAttempts: number;
       delayMs: number;
+      dueAt: number;
       errorMessage: string;
     }
   | {
@@ -152,6 +153,7 @@ fiber; the run then ends with a `cancelled` `run_end`.
 
 | Name                     | Type                                                                                                              | Description                                                                                                                                                                                                             |
 | ------------------------ | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `onUndrained?`           | `Effect.Effect`\<`void`\>                                                                                         | Notify the owner when provider cleanup was detached or failed; abort alone is not drain evidence.                                                                                                                       |
 | `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.                                                                                                                                                    |
@@ -1849,7 +1851,7 @@ 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
+`@earendil-works/pi-ai` 1.3.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.
 

package/docs/api/index.md

@@ -281,6 +281,12 @@ type MuleEvent =
       turn: MuleIdentity;
       message: MuleIdentity;
       value: Message;
+      retry?: Exclude<
+        MuleRetryObservation,
+        {
+          type: "retry_attempt_started";
+        }
+      >;
       data?: JsonValue;
     }
   | {
@@ -409,18 +415,22 @@ Lifecycle emitted around Pi values. Pi messages and events are not rewritten.
   turn: MuleIdentity;
   message: MuleIdentity;
   value: Message;
+  retry?: Exclude<MuleRetryObservation, {
+     type: "retry_attempt_started";
+  }>;
   data?: JsonValue;
 }
 ```
 
-| Name      | Type                               | Description                                                     |
-| --------- | ---------------------------------- | --------------------------------------------------------------- |
-| `type`    | `"message_end"`                    | -                                                               |
-| `run`     | [`MuleIdentity`](#muleidentity)    | -                                                               |
-| `turn`    | [`MuleIdentity`](#muleidentity)    | -                                                               |
-| `message` | [`MuleIdentity`](#muleidentity)    | -                                                               |
-| `value`   | [`Message`](effect.md#message)     | -                                                               |
-| `data?`   | [`JsonValue`](effect.md#jsonvalue) | Application payload independent of the completed model message. |
+| Name      | Type                                                                                                            | Description                                                                  |
+| --------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `type`    | `"message_end"`                                                                                                 | -                                                                            |
+| `run`     | [`MuleIdentity`](#muleidentity)                                                                                 | -                                                                            |
+| `turn`    | [`MuleIdentity`](#muleidentity)                                                                                 | -                                                                            |
+| `message` | [`MuleIdentity`](#muleidentity)                                                                                 | -                                                                            |
+| `value`   | [`Message`](effect.md#message)                                                                                  | -                                                                            |
+| `retry?`  | `Exclude`\<[`MuleRetryObservation`](effect.md#muleretryobservation), \{ `type`: `"retry_attempt_started"`; \}\> | Commit the assistant and its retry decision together before observing retry. |
+| `data?`   | [`JsonValue`](effect.md#jsonvalue)                                                                              | Application payload independent of the completed model message.              |
 
 ---
 
@@ -574,25 +584,28 @@ Durable evidence for a call in an interrupted assistant turn.
 ### MuleResume
 
 ```ts
-type MuleResume = object;
-```
-
-Completed assistant turn recovered by the transcript owner, before its next
-model call.
-
-#### Properties
-
-##### message
-
-```ts
-readonly message: AssistantMessage;
+type MuleResume =
+  | Readonly<{
+  kind: "assistant";
+  message: AssistantMessage;
+  tools: readonly MuleToolCheckpoint[];
+}>
+  | Readonly<{
+  kind: "retry";
+  attempt: number;
+  maxAttempts?: number;
+  message?: AssistantMessage;
+}> &
+  | Readonly<{
+  phase: "waiting";
+  dueAt: number;
+}>
+  | Readonly<{
+  phase: "dispatched";
+}>;
 ```
 
-##### tools
-
-```ts
-readonly tools: readonly MuleToolCheckpoint[];
-```
+Transcript-owned continuation at a completed assistant or model retry boundary.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fungi.computer/mule",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "author": "Levi <levi@technomancy.dev>",
   "description": "Effect-native Pi model and tool loop",
   "type": "module",