@frockbot/kernel-agent-loop 0.3.3 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/kernel-agent-loop",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "private": false,
   "type": "module",
   "exports": {
@@ -12,13 +12,13 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/kernel-contracts": "0.3.3",
+    "@frockbot/kernel-contracts": "0.3.5",
     "cordis": "4.0.0-rc.8"
   },
   "devDependencies": {
-    "@frockbot/plugin-models": "0.3.3",
-    "@frockbot/plugin-prompt": "0.3.3",
-    "@frockbot/plugin-tools": "0.3.3",
+    "@frockbot/plugin-models": "0.3.5",
+    "@frockbot/plugin-prompt": "0.3.5",
+    "@frockbot/plugin-tools": "0.3.5",
     "@types/bun": "1.4.0",
     "@types/node": "26.2.0",
     "typescript": "^7.0.2"

package/src/index.test.ts

@@ -2970,4 +2970,93 @@ describe("AgentLoop", () => {
     expect(end).toMatchObject({ type: "turn/end", outcome: "completed" });
     expect(end && Object.hasOwn(end, "reason")).toBe(false);
   });
+
+  test("reaching the step limit is reported as stopping, not as a model error", async () => {
+    const provider: LlmProvider = {
+      id: "never-stops",
+      async *stream() {
+        yield {
+          type: "tool-call",
+          call: {
+            id: `call-${crypto.randomUUID()}`,
+            name: "loop_tool",
+            input: {},
+          },
+        };
+        yield { type: "finish", reason: "tool-calls" };
+      },
+    };
+    const errors: unknown[] = [];
+    const root = await mountRuntime(provider, {
+      name: "loop_tool",
+      description: "Never ends the Turn.",
+      inputSchema: { type: "object" },
+      execute: () => Promise.resolve({ content: "again", isError: false }),
+    });
+    root.on("agent/error", (_agent, error) => {
+      errors.push(error);
+    });
+    const handle = await root.agents.create({
+      ...allowEffectOptions,
+      botId: "step-limit-bot",
+      sessionId: "step-limit",
+      provider: "never-stops",
+      model: "test-model",
+    });
+
+    handle.agent.send("keep going");
+    await handle.agent.whenIdle();
+
+    expect(handle.agent.session.events.at(-1)).toMatchObject({
+      type: "turn/end",
+      outcome: "interrupted",
+      reason: "stopped after 4 steps",
+    });
+    // Nothing about the model failed, so nothing is reported as if it had.
+    expect(errors).toEqual([]);
+  });
+
+  test("a Turn whose first flush fails ends once instead of spinning", async () => {
+    let streams = 0;
+    const provider: LlmProvider = {
+      id: "persist-fails",
+      async *stream() {
+        streams += 1;
+        yield { type: "finish", reason: "completed" };
+      },
+    };
+    let writes = 0;
+    const root = await mountRuntime(
+      provider,
+      undefined,
+      // Storage that is simply gone: every durable write rejects.
+      () => {
+        writes += 1;
+        return Promise.reject(new Error("durable storage is unavailable"));
+      },
+    );
+    const handle = await root.agents.create({
+      ...allowEffectOptions,
+      botId: "persist-bot",
+      sessionId: "persist-fails",
+      provider: "persist-fails",
+      model: "test-model",
+    });
+
+    handle.agent.send("say something");
+    // The failure reaches the caller, exactly once: the input was claimed
+    // before the flush, so nothing hands it back to be started again.
+    await expect(handle.agent.whenIdle()).rejects.toThrow(
+      "durable storage is unavailable",
+    );
+    const attempts = writes;
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    expect(writes).toBe(attempts);
+    expect(streams).toBe(0);
+    expect(
+      handle.agent.session.events.filter(
+        (event) => event.type === "turn/start",
+      ),
+    ).toHaveLength(1);
+  });
 });

package/src/index.ts

@@ -88,6 +88,21 @@ class ToolEffectReconciliationRequiredError extends Error {
   }
 }
 
+/**
+ * The Turn used every step it was allowed.
+ *
+ * Not a model error: nothing failed, and everything the Turn did in those
+ * steps is durable. It is reported as what it is — a Turn that stopped after
+ * so many steps — so the person is told the Bot ran out of room rather than
+ * that their model broke.
+ */
+class StepLimitReachedError extends Error {
+  constructor(readonly steps: number) {
+    super(`stopped after ${steps} steps`);
+    this.name = "StepLimitReachedError";
+  }
+}
+
 /** Durable Stop won the final effect-admission transaction. */
 class EffectAdmissionFencedError extends Error {
   constructor(readonly effectId: string) {
@@ -272,11 +287,23 @@ class LoopAgent implements Agent {
     }
     this.#controller = new AbortController();
     this.#setStatus("running");
-    const activity = this.#drive(this.#controller.signal).finally(() => {
-      this.#controller = undefined;
-      if (!this.#disposeRequested) this.#setStatus("idle");
-      if (!this.#disposeRequested && this.#inbox.length > 0) this.#wake();
-    });
+    let failed = false;
+    const activity = this.#drive(this.#controller.signal)
+      .catch((error: unknown) => {
+        // A Turn that could not even journal its own start throws out of
+        // `#drive`. Re-waking on the inbox it left behind would append another
+        // `turn/start`, fail the same way, and spin — so the failure ends the
+        // waking and reaches whoever is awaiting this Turn.
+        failed = true;
+        throw error;
+      })
+      .finally(() => {
+        this.#controller = undefined;
+        if (!this.#disposeRequested) this.#setStatus("idle");
+        if (!this.#disposeRequested && !failed && this.#inbox.length > 0) {
+          this.#wake();
+        }
+      });
     this.#activity = activity;
   }
 
@@ -580,7 +607,7 @@ class LoopAgent implements Agent {
           }
         }
       }
-      throw new Error(`agent exceeded ${this.#maxSteps} steps`);
+      throw new StepLimitReachedError(this.#maxSteps);
     } catch (error) {
       if (
         error instanceof ModelEffectReconciliationRequiredError ||
@@ -596,6 +623,10 @@ class LoopAgent implements Agent {
       ) {
         turnOutcome = "cancelled";
         turnReason = this.#cancelDetail;
+      } else if (error instanceof StepLimitReachedError) {
+        // The Turn ran out of room, which is not a failure of the model.
+        turnOutcome = "interrupted";
+        turnReason = turnEndReason(error.message);
       } else {
         turnOutcome = "model-error";
         turnReason = turnEndReason(modelFailureMessage(error));
@@ -643,8 +674,11 @@ class LoopAgent implements Agent {
       { type: "turn/admission", turn, turnType: this.#turnType },
       { type: "input/admitted", messageId: input.messageId, turn },
     ]);
-    await this.session.flush();
+    // Claimed before the flush, not after: the input has been journaled as
+    // admitted, and leaving it in the inbox while the write settles meant a
+    // failed first flush handed it straight back to `#wake`.
     this.#inbox.shift();
+    await this.session.flush();
     this.#ctx.emit("agent/inbox/claimed", this, [input], turn);
 
     let openStep: number | undefined;
@@ -740,7 +774,7 @@ class LoopAgent implements Agent {
         }
         inputs = [];
       }
-      throw new Error(`agent exceeded ${this.#maxSteps} steps`);
+      throw new StepLimitReachedError(this.#maxSteps);
     } catch (error) {
       if (
         error instanceof ModelEffectReconciliationRequiredError ||
@@ -756,6 +790,10 @@ class LoopAgent implements Agent {
       ) {
         turnOutcome = "cancelled";
         turnReason = this.#cancelDetail;
+      } else if (error instanceof StepLimitReachedError) {
+        // The Turn ran out of room, which is not a failure of the model.
+        turnOutcome = "interrupted";
+        turnReason = turnEndReason(error.message);
       } else {
         turnOutcome = "model-error";
         turnReason = turnEndReason(modelFailureMessage(error));