@frockbot/kernel-agent-loop 0.3.9 → 0.3.11

package/package.json

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

package/src/deadlines.test.ts

@@ -78,16 +78,82 @@ describe("a Turn that runs out of wall clock", () => {
     handle.agent.send("Take your time.");
     await handle.agent.whenIdle();
 
-    // The model effect is unsettled, so the Turn is owed a reconciliation
-    // rather than a clean end — but it *ended*, which is the whole point, and
-    // ADR 0028 settles it from there.
+    // The model effect is unsettled, so the uncertainty is recorded — but the
+    // deadline *settles the Turn anyway*, because a run the clock stopped will
+    // never resume to make that outcome certain. Leaving
+    // `model/reconciliation-required` as the last event of an open Turn parked
+    // the run in `reconciliation-required` and refused every later Turn on
+    // that Bot with `409` for the life of the Bot.
     const journal = handle.agent.session.events;
     expect(
       journal.some((event) => event.type === "model/reconciliation-required"),
     ).toBe(true);
+    const step = journal.findLast((event) => event.type === "step/end");
+    if (step?.type !== "step/end") throw new Error("the step never ended");
+    expect(step.outcome).toBe("interrupted");
+    const end = journal.findLast((event) => event.type === "turn/end");
+    if (end?.type !== "turn/end") throw new Error("the Turn never ended");
+    expect(end.outcome).toBe("interrupted");
+    expect(end.reason).toBe(TURN_DEADLINE_REASON_V1);
+    // The last event settles the Turn; nothing is left open behind it.
+    expect(journal[journal.length - 1]?.type).toBe("turn/end");
     expect(handle.agent.status).toBe("idle");
   });
 
+  test("settles an open tool call too, so the journal never ends over one", async () => {
+    // The deadline landing mid-tool is the other way an open Turn was left
+    // behind: a `turn/end` written over an unresolved tool occurrence is an
+    // invalid journal, so the occurrence has to be closed first.
+    const provider: LlmProvider = {
+      id: "one-tool-then-silence",
+      async *stream() {
+        yield {
+          type: "tool-call" as const,
+          call: { id: "provider-call", name: "stall", input: {} },
+        };
+        yield { type: "finish" as const, reason: "tool-calls" as const };
+      },
+    };
+    const root = await mount(provider, { turnDeadlineMs: 40 });
+    const toolPlugin: Plugin.Function = (ctx) =>
+      ctx.tools.register({
+        name: "stall",
+        description: "Never answers.",
+        inputSchema: { type: "object" },
+        execute: (_input, context) =>
+          new Promise((_resolve, reject) => {
+            context.signal.addEventListener(
+              "abort",
+              () => reject(context.signal.reason),
+              { once: true },
+            );
+          }),
+      });
+    toolPlugin.inject = ["tools"];
+    await root.plugin(toolPlugin);
+    const handle = await root.agents.create({
+      botId: "deadline-tool-bot",
+      sessionId: "deadline-tool",
+      provider: "one-tool-then-silence",
+      model: "test-model",
+      admitEffect: allowEffect,
+    });
+
+    handle.agent.send("Call the tool that never answers.");
+    await handle.agent.whenIdle();
+
+    const journal = handle.agent.session.events;
+    const result = journal.findLast((event) => event.type === "tool/result");
+    if (result?.type !== "tool/result") {
+      throw new Error("the tool call was left open");
+    }
+    expect(result.status).toBe("interrupted");
+    const end = journal.findLast((event) => event.type === "turn/end");
+    if (end?.type !== "turn/end") throw new Error("the Turn never ended");
+    expect(end.outcome).toBe("interrupted");
+    expect(journal[journal.length - 1]?.type).toBe("turn/end");
+  });
+
   test("is reported as the deadline, never as a Stop the person did not press", async () => {
     const provider: LlmProvider = {
       id: "never-reached",

package/src/index.ts

@@ -685,7 +685,10 @@ class LoopAgent implements Agent {
       }
       throw new StepLimitReachedError(this.#maxSteps);
     } catch (error) {
-      if (
+      if (this.#turnDeadlineReached) {
+        turnOutcome = "interrupted";
+        turnReason = this.#deadlineTurnReason(error);
+      } else if (
         error instanceof ModelEffectReconciliationRequiredError ||
         error instanceof ToolEffectReconciliationRequiredError ||
         error instanceof ModelOutcomeSettlementRequiredError ||
@@ -693,13 +696,6 @@ class LoopAgent implements Agent {
       ) {
         reconciliationRequired = true;
         this.#ctx.emit("agent/error", this, error);
-      } else if (this.#turnDeadlineReached) {
-        // Ahead of the cancellation branch on purpose: the deadline aborts the
-        // same controller Stop does, and a Turn the clock ended must not be
-        // reported to the person as one they stopped.
-        turnOutcome = "interrupted";
-        turnReason = turnEndReason(TURN_DEADLINE_REASON_V1);
-        this.#ctx.emit("agent/error", this, error);
       } else if (
         error instanceof EffectAdmissionFencedError ||
         signal.aborted
@@ -724,7 +720,13 @@ class LoopAgent implements Agent {
       // `kernel-do`'s `settledEventsV1`. Closing it here instead would either
       // lie about an outcome or make the run unresumable (ADR 0028).
       if (!reconciliationRequired) {
-        if (openStep !== undefined && turnOutcome === "cancelled") {
+        // A deadline settles the same way a Stop does: an open tool
+        // occurrence gets an `interrupted` result before the step closes,
+        // so the journal never carries a `turn/end` over an open call.
+        if (
+          openStep !== undefined &&
+          (turnOutcome === "cancelled" || this.#turnDeadlineReached)
+        ) {
           await this.#settleCancelledStep(openTurn, openStep);
         }
         if (openStep !== undefined) {
@@ -867,7 +869,10 @@ class LoopAgent implements Agent {
       }
       throw new StepLimitReachedError(this.#maxSteps);
     } catch (error) {
-      if (
+      if (this.#turnDeadlineReached) {
+        turnOutcome = "interrupted";
+        turnReason = this.#deadlineTurnReason(error);
+      } else if (
         error instanceof ModelEffectReconciliationRequiredError ||
         error instanceof ToolEffectReconciliationRequiredError ||
         error instanceof ModelOutcomeSettlementRequiredError ||
@@ -875,13 +880,6 @@ class LoopAgent implements Agent {
       ) {
         reconciliationRequired = true;
         this.#ctx.emit("agent/error", this, error);
-      } else if (this.#turnDeadlineReached) {
-        // Ahead of the cancellation branch on purpose: the deadline aborts the
-        // same controller Stop does, and a Turn the clock ended must not be
-        // reported to the person as one they stopped.
-        turnOutcome = "interrupted";
-        turnReason = turnEndReason(TURN_DEADLINE_REASON_V1);
-        this.#ctx.emit("agent/error", this, error);
       } else if (
         error instanceof EffectAdmissionFencedError ||
         signal.aborted
@@ -906,7 +904,13 @@ class LoopAgent implements Agent {
       // `kernel-do`'s `settledEventsV1`. Closing it here instead would either
       // lie about an outcome or make the run unresumable (ADR 0028).
       if (!reconciliationRequired) {
-        if (openStep !== undefined && turnOutcome === "cancelled") {
+        // A deadline settles the same way a Stop does: an open tool
+        // occurrence gets an `interrupted` result before the step closes,
+        // so the journal never carries a `turn/end` over an open call.
+        if (
+          openStep !== undefined &&
+          (turnOutcome === "cancelled" || this.#turnDeadlineReached)
+        ) {
           await this.#settleCancelledStep(turn, openStep);
         }
         if (openStep !== undefined) {
@@ -1385,6 +1389,29 @@ class LoopAgent implements Agent {
     return decision.kind === "stop";
   }
 
+  /**
+   * The reason a Turn the clock ended carries, and the one place that decides
+   * a deadline is not a cancellation and not a reconciliation.
+   *
+   * Its branch runs ahead of both. Ahead of cancellation, because the deadline
+   * aborts the same controller Stop does and a Turn the clock ended must not
+   * be reported to the person as one they stopped. Ahead of reconciliation,
+   * because that branch writes no `turn/end` on the promise the run may still
+   * resume — and a run the deadline stopped never will. Deferring to it left
+   * `model/reconciliation-required` as the last event of an open Turn, and
+   * every later Turn on that Bot refused with `409` for the life of the Bot.
+   *
+   * The uncertainty is still recorded: whatever the model request wrote before
+   * the clock ran out stays in the journal. What changes is that the Turn is
+   * settled — the open step's tool occurrences closed as `interrupted`, then
+   * `step/end` and `turn/end` — exactly as `kernel-do`'s `settledEventsV1`
+   * settles a Stop or a supersede.
+   */
+  #deadlineTurnReason(error: unknown): string | undefined {
+    this.#ctx.emit("agent/error", this, error);
+    return turnEndReason(TURN_DEADLINE_REASON_V1);
+  }
+
   async #settleCancelledStep(turn: number, step: number): Promise<void> {
     const assistant = this.session.events.findLast(
       (event) =>