@fungi.computer/mule 0.1.1 → 0.2.0

package/dist/contract.d.ts

@@ -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

@@ -16,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

@@ -30,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);
@@ -235,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");
@@ -273,17 +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 ?? 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");
@@ -303,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);
@@ -345,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 {
@@ -376,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.
@@ -430,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) {
@@ -529,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. */
@@ -630,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. */
@@ -702,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/types.d.ts

@@ -177,6 +177,8 @@ export type AssistantMessage = {
     stopReason: StopReason;
     deferred?: DeferredHandle;
     errorMessage?: string;
+    /** Provider prose for the failed conversation turn, never a diagnostic. */
+    providerError?: string;
     rawStopReason?: string;
     endTurn?: boolean;
     timestamp: number;

package/docs/api/effect.md

@@ -1847,18 +1847,6 @@ 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

package/docs/api/index.md

@@ -657,6 +657,18 @@ readonly optional modelStreamIdleTimeoutMs?: number;
 
 Maximum silence between provider stream events, in milliseconds.
 
+##### modelStreamLimits?
+
+```ts
+readonly optional modelStreamLimits?: Partial<{
+  firstEventMs: number;
+  attemptMs: number;
+  outputBytes: number;
+}>;
+```
+
+Trusted per-attempt safety limits may only tighten Mule's defaults.
+
 ##### toolExecution?
 
 ```ts
@@ -754,6 +766,14 @@ readonly message: AssistantMessage;
 readonly messages: readonly Message[];
 ```
 
+##### modelLimitReason?
+
+```ts
+readonly optional modelLimitReason?: string;
+```
+
+Mule-owned limit diagnostic, not untrusted provider prose.
+
 ---
 
 ### MulePromiseListener

package/package.json

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