@stigmer/runner 3.40.1 → 3.41.0

package/src/middleware/__tests__/execution-budget.test.ts

@@ -1,130 +1,208 @@
+/**
+ * ExecutionBudgetMiddleware: the round count, the stop it makes, and the
+ * advisories before it.
+ *
+ * Pins what `max_tool_rounds = N` means (#1113): exactly N model responses
+ * that propose tools, whatever the middleware stack; parallel calls in one
+ * response are one round; a response without tool calls, or a `Command`, is
+ * not a round; the stop replaces round N+1's model call (the handler is never
+ * called for it) and is the typed `ToolRoundLimitError` the native turn reads
+ * as `tool_call_limit`. The threshold advisory counts the same rounds, so it
+ * lands at its percentage of the budget the stop enforces. Periodic mode (the
+ * sub-agent stacks) keeps counting model calls and never stops.
+ */
+
 import { describe, it, expect, vi } from "vitest";
 import { AIMessage } from "@langchain/core/messages";
+import { Command } from "@langchain/langgraph";
 import { createExecutionBudgetMiddleware } from "../execution-budget.js";
+import type { ModelCallRequest, StigmerMiddleware } from "../types.js";
+import { ToolRoundLimitError, UNBOUNDED_ADVISORY_TOOL_ROUNDS } from "../../shared/tool-rounds.js";
+
+type ModelResponse = AIMessage | Command;
 
-function makeAIMessage(content = "hello"): AIMessage {
+const REQUEST: ModelCallRequest = { model: {}, messages: [], state: {}, runtime: {} };
+
+function textResponse(content = "hello"): AIMessage {
   return new AIMessage({ content });
 }
 
+/** A response proposing `calls` tool calls: one round, however many calls. */
+function toolResponse(round: number, calls = 1): AIMessage {
+  return new AIMessage({
+    content: `round ${round}`,
+    tool_calls: Array.from({ length: calls }, (_, i) => ({ id: `call-${round}-${i}`, name: "read_file", args: { file_path: `/f${round}-${i}.md` } })),
+  });
+}
+
+function handlerOf(respond: (call: number) => ModelResponse) {
+  let calls = 0;
+  return vi.fn(async (_request: ModelCallRequest): Promise<ModelResponse> => respond(calls++));
+}
+
+async function callModel(mw: StigmerMiddleware, handler: ReturnType<typeof handlerOf>): Promise<ModelResponse> {
+  return mw.wrapModelCall!(REQUEST, handler);
+}
+
+/** The requests the handler saw that carried an advisory (the base request has no messages). */
+function advisedCalls(handler: ReturnType<typeof handlerOf>): number[] {
+  return handler.mock.calls.flatMap((call, index) => (call[0].messages.length > 0 ? [index] : []));
+}
+
 describe("ExecutionBudgetMiddleware", () => {
-  describe("threshold mode", () => {
-    it("does not warn before threshold", async () => {
-      const mw = createExecutionBudgetMiddleware({
-        recursionLimit: 60,
-        warningPct: 80,
-      });
-      // 60/6 = 10 estimated rounds, 80% = round 8
-      const handler = vi.fn().mockResolvedValue(makeAIMessage());
-      const request = { model: {}, messages: [], state: {}, runtime: {} } as any;
-
-      for (let i = 0; i < 7; i++) {
-        await mw.wrapModelCall!(request, handler);
-      }
-
-      // All calls should pass through without modification
-      expect(handler).toHaveBeenCalledTimes(7);
-      for (const call of handler.mock.calls) {
-        expect(call[0]).toBe(request);
-      }
+  describe("the round limit", () => {
+    it("runs exactly N tool rounds, then throws ToolRoundLimitError in place of the next model call", async () => {
+      const mw = createExecutionBudgetMiddleware({ maxToolRounds: 10, warningPct: 80 });
+      const handler = handlerOf((call) => toolResponse(call));
+
+      for (let i = 0; i < 10; i++) await callModel(mw, handler);
+      const stop = callModel(mw, handler);
+
+      await expect(stop).rejects.toBeInstanceOf(ToolRoundLimitError);
+      await expect(stop).rejects.toMatchObject({ toolRoundLimit: 10 });
+      expect(handler, "round 11's model call never happens").toHaveBeenCalledTimes(10);
     });
 
-    it("injects warning at threshold", async () => {
-      const mw = createExecutionBudgetMiddleware({
-        recursionLimit: 60,
-        warningPct: 80,
-      });
-      const handler = vi.fn().mockResolvedValue(makeAIMessage());
-      const request = { model: {}, messages: [], state: {}, runtime: {} } as any;
-
-      // Round 8 should trigger warning for round 9
-      for (let i = 0; i < 8; i++) {
-        await mw.wrapModelCall!(request, handler);
-      }
-
-      // Round 9 — handler should receive the advisory in messages
-      await mw.wrapModelCall!(request, handler);
-      const lastCall = handler.mock.calls[8][0];
-      expect(lastCall.messages.length).toBeGreaterThan(0);
+    it("counts parallel tool calls in one response as one round", async () => {
+      const mw = createExecutionBudgetMiddleware({ maxToolRounds: 10, warningPct: 80 });
+      const handler = handlerOf((call) => toolResponse(call, 3));
+
+      for (let i = 0; i < 10; i++) await callModel(mw, handler);
+
+      await expect(callModel(mw, handler)).rejects.toBeInstanceOf(ToolRoundLimitError);
+      expect(handler).toHaveBeenCalledTimes(10);
+    });
+
+    it("does not count a response without tool calls, nor a Command, as a round", async () => {
+      const mw = createExecutionBudgetMiddleware({ maxToolRounds: 10, warningPct: 80 });
+      const handler = handlerOf((call) => (call % 3 === 0 ? toolResponse(call) : call % 3 === 1 ? textResponse() : new Command({ goto: "tools" })));
+
+      // Calls 0, 3, …, 27 are the 10 tool rounds; the 18 between them are text
+      // responses and Commands. Call 28 is the first after round 10.
+      for (let i = 0; i < 28; i++) await callModel(mw, handler);
+
+      await expect(callModel(mw, handler)).rejects.toBeInstanceOf(ToolRoundLimitError);
+      expect(handler).toHaveBeenCalledTimes(28);
     });
 
-    it("fires warning only once in threshold mode", async () => {
-      const mw = createExecutionBudgetMiddleware({
-        recursionLimit: 60,
-        warningPct: 80,
-      });
-      const handler = vi.fn().mockResolvedValue(makeAIMessage());
-      const request = { model: {}, messages: [], state: {}, runtime: {} } as any;
-
-      for (let i = 0; i < 12; i++) {
-        await mw.wrapModelCall!(request, handler);
-      }
-
-      // Only round 9 should have the advisory
-      const callsWithAdvisory = handler.mock.calls.filter(
-        (call: unknown[]) => (call[0] as { messages: unknown[] }).messages.length > 0,
-      );
-      expect(callsWithAdvisory.length).toBe(1);
+    it("never stops an unlimited turn (maxToolRounds null, the proto's 0/unset)", async () => {
+      const mw = createExecutionBudgetMiddleware({ maxToolRounds: null, warningPct: 80 });
+      const handler = handlerOf((call) => toolResponse(call));
+
+      for (let i = 0; i < UNBOUNDED_ADVISORY_TOOL_ROUNDS + 50; i++) await callModel(mw, handler);
+
+      expect(handler).toHaveBeenCalledTimes(UNBOUNDED_ADVISORY_TOOL_ROUNDS + 50);
+    });
+
+    it("gives a new message a fresh budget: beforeAgent resets the count", async () => {
+      const mw = createExecutionBudgetMiddleware({ maxToolRounds: 10, warningPct: 80 });
+      const handler = handlerOf((call) => toolResponse(call));
+
+      for (let i = 0; i < 10; i++) await callModel(mw, handler);
+      await expect(callModel(mw, handler)).rejects.toBeInstanceOf(ToolRoundLimitError);
+
+      mw.beforeAgent!({}, {});
+      await callModel(mw, handler);
+      expect(handler).toHaveBeenCalledTimes(11);
+    });
+
+    it("rejects a non-positive limit (unlimited is null, never 0)", () => {
+      expect(() => createExecutionBudgetMiddleware({ maxToolRounds: 0 })).toThrow("maxToolRounds");
     });
   });
 
-  describe("periodic mode", () => {
-    it("injects advisory every N rounds", async () => {
-      const mw = createExecutionBudgetMiddleware({
-        warningInterval: 3,
-        maxWarnings: 4,
-      });
-      const handler = vi.fn().mockResolvedValue(makeAIMessage());
-      const request = { model: {}, messages: [], state: {}, runtime: {} } as any;
-
-      for (let i = 0; i < 12; i++) {
-        await mw.wrapModelCall!(request, handler);
-      }
-
-      // Advisories queued at rounds 3, 6, 9 (delivered at rounds 4, 7, 10)
-      const callsWithAdvisory = handler.mock.calls.filter(
-        (call: unknown[]) => (call[0] as { messages: unknown[] }).messages.length > 0,
-      );
-      expect(callsWithAdvisory.length).toBeGreaterThanOrEqual(3);
+  describe("threshold mode", () => {
+    it("does not warn before the threshold", async () => {
+      const mw = createExecutionBudgetMiddleware({ maxToolRounds: 10, warningPct: 80 });
+      const handler = handlerOf((call) => toolResponse(call));
+
+      for (let i = 0; i < 8; i++) await callModel(mw, handler);
+
+      expect(advisedCalls(handler)).toEqual([]);
+      for (const call of handler.mock.calls) expect(call[0]).toBe(REQUEST);
     });
 
-    it("stops after maxWarnings", async () => {
-      const mw = createExecutionBudgetMiddleware({
-        warningInterval: 2,
-        maxWarnings: 2,
-      });
-      const handler = vi.fn().mockResolvedValue(makeAIMessage());
-      const request = { model: {}, messages: [], state: {}, runtime: {} } as any;
-
-      for (let i = 0; i < 20; i++) {
-        await mw.wrapModelCall!(request, handler);
-      }
-
-      const callsWithAdvisory = handler.mock.calls.filter(
-        (call: unknown[]) => (call[0] as { messages: unknown[] }).messages.length > 0,
-      );
-      expect(callsWithAdvisory.length).toBe(2);
+    it("warns on the model call after the threshold's tool round, with the exact rounds left", async () => {
+      const mw = createExecutionBudgetMiddleware({ maxToolRounds: 10, warningPct: 80 });
+      const handler = handlerOf((call) => toolResponse(call));
+
+      for (let i = 0; i < 9; i++) await callModel(mw, handler);
+
+      // 80% of 10 = round 8, so the 9th call (index 8) carries the advisory.
+      expect(advisedCalls(handler)).toEqual([8]);
+      const advisory = handler.mock.calls[8][0].messages[0];
+      expect(advisory).toMatchObject({ content: expect.stringContaining("8 of 10 tool rounds used, 2 remaining") });
+    });
+
+    it("counts tool rounds, not model calls, toward the threshold", async () => {
+      const mw = createExecutionBudgetMiddleware({ maxToolRounds: 10, warningPct: 80 });
+      const handler = handlerOf(() => textResponse());
+
+      for (let i = 0; i < 12; i++) await callModel(mw, handler);
+
+      expect(advisedCalls(handler)).toEqual([]);
+    });
+
+    it("fires the warning only once", async () => {
+      const mw = createExecutionBudgetMiddleware({ maxToolRounds: 20, warningPct: 80 });
+      const handler = handlerOf((call) => toolResponse(call));
+
+      for (let i = 0; i < 20; i++) await callModel(mw, handler);
+
+      expect(advisedCalls(handler)).toEqual([16]);
+    });
+
+    it("warns toward the unbounded advisory figure when the turn has no limit", async () => {
+      const mw = createExecutionBudgetMiddleware({ maxToolRounds: null, warningPct: 80 });
+      const handler = handlerOf((call) => toolResponse(call));
+      const threshold = Math.floor(UNBOUNDED_ADVISORY_TOOL_ROUNDS * 0.8);
+
+      for (let i = 0; i < threshold + 1; i++) await callModel(mw, handler);
+
+      expect(advisedCalls(handler)).toEqual([threshold]);
+    });
+
+    it("resets on beforeAgent", async () => {
+      const mw = createExecutionBudgetMiddleware({ maxToolRounds: 10, warningPct: 50 });
+      const handler = handlerOf((call) => toolResponse(call));
+
+      for (let i = 0; i < 6; i++) await callModel(mw, handler);
+      mw.beforeAgent!({}, {});
+      handler.mockClear();
+
+      await callModel(mw, handler);
+      expect(handler.mock.calls[0][0]).toBe(REQUEST);
     });
   });
 
-  it("resets on beforeAgent", async () => {
-    const mw = createExecutionBudgetMiddleware({
-      recursionLimit: 18,
-      warningPct: 50,
+  describe("periodic mode", () => {
+    it("injects advisory every N model calls", async () => {
+      const mw = createExecutionBudgetMiddleware({ warningInterval: 3, maxWarnings: 4 });
+      const handler = handlerOf(() => textResponse());
+
+      for (let i = 0; i < 12; i++) await callModel(mw, handler);
+
+      // Advisories queued at calls 3, 6, 9, 12 (delivered at calls 4, 7, 10).
+      expect(advisedCalls(handler)).toEqual([3, 6, 9]);
     });
-    // 18/6 = 3 rounds, 50% = round 1 (min 3)
-    const handler = vi.fn().mockResolvedValue(makeAIMessage());
-    const request = { model: {}, messages: [], state: {}, runtime: {} } as any;
 
-    for (let i = 0; i < 5; i++) {
-      await mw.wrapModelCall!(request, handler);
-    }
+    it("stops advising after maxWarnings", async () => {
+      const mw = createExecutionBudgetMiddleware({ warningInterval: 2, maxWarnings: 2 });
+      const handler = handlerOf(() => textResponse());
 
-    mw.beforeAgent!({}, {});
-    handler.mockClear();
+      for (let i = 0; i < 20; i++) await callModel(mw, handler);
+
+      expect(advisedCalls(handler)).toHaveLength(2);
+    });
 
-    // After reset, first calls should not have advisory
-    await mw.wrapModelCall!(request, handler);
-    expect(handler.mock.calls[0][0]).toBe(request);
+    it("never stops a turn when no limit is configured (the sub-agent stacks)", async () => {
+      const mw = createExecutionBudgetMiddleware({ warningInterval: 30, maxWarnings: 4 });
+      const handler = handlerOf((call) => toolResponse(call));
+
+      for (let i = 0; i < 200; i++) await callModel(mw, handler);
+
+      expect(handler).toHaveBeenCalledTimes(200);
+    });
   });
 
   it("rejects invalid warningPct", () => {

package/src/middleware/cost-advisory.ts

@@ -7,9 +7,12 @@
  * usage delta the adapter reports moves the runtime's estimate, and when the
  * estimate crosses the cap the runtime stops the turn and settles TERMINATED
  * with the cost-limit copy. The graph learns of the stop through its abort
- * signal, the same way it learns of a platform STOP or a stall. This is the
- * shape `execution-budget.ts` already has beside LangGraph's `recursionLimit`:
- * the middleware warns inside the graph, the engine's own limit enforces.
+ * signal, the same way it learns of a platform STOP or a stall. The
+ * middleware warns inside the graph; the runtime enforces, because the
+ * running estimate advances only in its usage accumulator. The round budget
+ * is the one budget enforced where it is counted (`execution-budget.ts`): a
+ * round is visible only at the model call, and stopping there is what makes
+ * it exact.
  *
  * Until #1096 this module was `cost-cap.ts` and did both: it also
  * blocked every tool call once the running cost passed the cap and gave the

package/src/middleware/execution-budget.ts

@@ -1,26 +1,41 @@
 /**
- * Execution budget middleware for autonomous agents.
+ * Execution budget middleware for autonomous agents: `max_tool_rounds`' own
+ * enforcement, and the advisories that warn the model before it.
  *
- * Two operating modes:
+ * The stop (whenever `maxToolRounds` is set):
+ *   A round is one model response that proposes one or more tool calls
+ *   (parallel calls are one round), counted here as each response returns.
+ *   Once N rounds have been proposed, the next model call does not happen:
+ *   `wrapModelCall` throws `ToolRoundLimitError` in its place, the graph
+ *   ends on round N's tool results, and the native turn reads the error as
+ *   the `tool_call_limit` outcome (`shared/tool-rounds.ts`
+ *   `isToolCallBudgetStop`). Stopping before a model call, never between a
+ *   model call and its tools, is what makes N exact and leaves no proposed
+ *   call unexecuted in the checkpoint. It is the one stop a middleware makes
+ *   (`middleware/index.ts`): the runtime still sees it, as an outcome.
+ *
+ * Two advisory modes:
  *
  * Threshold mode (default, warningInterval=null):
- *   Fires a single SystemMessage at a computed percentage of the
- *   LangGraph recursion limit.
+ *   Fires a single SystemMessage at a percentage of the round budget
+ *   (`maxToolRounds`, or the unbounded advisory figure when unset).
  *
  * Periodic mode (warningInterval set):
- *   Fires a SystemMessage every N model rounds with escalating urgency,
- *   up to maxWarnings times.
+ *   Fires a SystemMessage every N model calls with escalating urgency,
+ *   up to maxWarnings times. Sub-agent stacks use it, with no stop.
  *
  * Uses wrapModelCall (not afterModel) to safely prepend advisory
  * messages to the model's input, avoiding the AIMessage/ToolMessage
  * ordering violation that would occur if we injected between a
- * tool_use AIMessage and its corresponding ToolMessage.
+ * tool_use AIMessage and its corresponding ToolMessage, and so that the
+ * count and the stop add no graph node of their own: a node per round is
+ * exactly the cost that made the old super-step budget drift.
  */
 
-import { SystemMessage } from "@langchain/core/messages";
+import { AIMessage, SystemMessage } from "@langchain/core/messages";
 import type { StigmerMiddleware, ExecutionBudgetConfig } from "./types.js";
+import { ToolRoundLimitError, UNBOUNDED_ADVISORY_TOOL_ROUNDS } from "../shared/tool-rounds.js";
 
-const DEFAULT_RECURSION_LIMIT = 6000;
 const DEFAULT_WARNING_PCT = 80;
 const MIN_WARNING_PCT = 50;
 const MAX_WARNING_PCT = 95;
@@ -46,46 +61,51 @@ const PERIODIC_MESSAGES: readonly string[] = [
     "unless absolutely essential to your conclusion.",
 ];
 
-function computeWarningRound(recursionLimit: number, warningPct: number): number {
-  const estimatedTotalRounds = Math.floor(recursionLimit / 6);
-  const threshold = Math.floor(estimatedTotalRounds * warningPct / 100);
+function computeWarningRound(roundBudget: number, warningPct: number): number {
+  const threshold = Math.floor(roundBudget * warningPct / 100);
   return Math.max(threshold, MIN_ROUNDS_BEFORE_WARNING);
 }
 
+/** Whether a model call's response proposed tools: the round definition (a `Command` response is not one). */
+function isToolRound(response: unknown): boolean {
+  return AIMessage.isInstance(response) && (response.tool_calls?.length ?? 0) > 0;
+}
+
 export function createExecutionBudgetMiddleware(
   config: Partial<ExecutionBudgetConfig> = {},
 ): StigmerMiddleware {
-  const recursionLimit = config.recursionLimit ?? DEFAULT_RECURSION_LIMIT;
+  const maxToolRounds = config.maxToolRounds ?? null;
+  const roundBudget = maxToolRounds ?? UNBOUNDED_ADVISORY_TOOL_ROUNDS;
   const warningPct = config.warningPct ?? DEFAULT_WARNING_PCT;
   const warningInterval = config.warningInterval ?? null;
   const maxWarnings = config.maxWarnings ?? 4;
 
   const isPeriodic = warningInterval !== null;
 
+  if (maxToolRounds !== null && maxToolRounds <= 0) {
+    throw new Error(`maxToolRounds must be positive or null, got ${maxToolRounds}`);
+  }
   if (isPeriodic) {
     if (warningInterval <= 0) throw new Error(`warningInterval must be positive, got ${warningInterval}`);
     if (maxWarnings <= 0) throw new Error(`maxWarnings must be positive, got ${maxWarnings}`);
-  } else {
-    if (warningPct < MIN_WARNING_PCT || warningPct > MAX_WARNING_PCT) {
-      throw new Error(`warningPct must be between ${MIN_WARNING_PCT} and ${MAX_WARNING_PCT}, got ${warningPct}`);
-    }
-    if (recursionLimit <= 0) throw new Error(`recursionLimit must be positive, got ${recursionLimit}`);
+  } else if (warningPct < MIN_WARNING_PCT || warningPct > MAX_WARNING_PCT) {
+    throw new Error(`warningPct must be between ${MIN_WARNING_PCT} and ${MAX_WARNING_PCT}, got ${warningPct}`);
   }
 
   let modelRoundCount = 0;
+  let toolRoundCount = 0;
   let warningCount = 0;
   let nextWarningRound = isPeriodic
     ? warningInterval!
-    : computeWarningRound(recursionLimit, warningPct);
+    : computeWarningRound(roundBudget, warningPct);
   let pendingAdvisory: SystemMessage | null = null;
 
   function createThresholdWarning(): SystemMessage {
-    const estimatedTotal = Math.floor(recursionLimit / 6);
-    const remaining = Math.max(estimatedTotal - modelRoundCount, 0);
+    const remaining = Math.max(roundBudget - toolRoundCount, 0);
     return new SystemMessage({
       content:
-        `You are approaching the step limit for this message ` +
-        `(approximately ${warningPct}% used, ~${remaining} rounds remaining). ` +
+        `You are approaching the tool-round limit for this message ` +
+        `(${toolRoundCount} of ${roundBudget} tool rounds used, ${remaining} remaining). ` +
         `Prioritize completing your current task. Summarize results ` +
         `and any remaining work so the user can continue in the next message.`,
     });
@@ -113,12 +133,11 @@ export function createExecutionBudgetMiddleware(
       }
     } else {
       if (warningCount > 0) return;
-      if (modelRoundCount >= nextWarningRound) {
+      if (toolRoundCount >= nextWarningRound) {
         warningCount = 1;
-        const estimatedTotal = Math.floor(recursionLimit / 6);
         console.warn(
-          `[ExecutionBudget] WARNING: round ${modelRoundCount} of ~${estimatedTotal} ` +
-          `(~${warningPct}% of recursion_limit=${recursionLimit})`,
+          `[ExecutionBudget] WARNING: tool round ${toolRoundCount} of ${roundBudget} ` +
+          `(${warningPct}% threshold)`,
         );
         pendingAdvisory = createThresholdWarning();
       }
@@ -130,14 +149,23 @@ export function createExecutionBudgetMiddleware(
 
     beforeAgent() {
       modelRoundCount = 0;
+      toolRoundCount = 0;
       warningCount = 0;
       pendingAdvisory = null;
       nextWarningRound = isPeriodic
         ? warningInterval!
-        : computeWarningRound(recursionLimit, warningPct);
+        : computeWarningRound(roundBudget, warningPct);
     },
 
     async wrapModelCall(request, handler) {
+      if (maxToolRounds !== null && toolRoundCount >= maxToolRounds) {
+        console.log(
+          `[ExecutionBudget] Tool-round limit reached: ${toolRoundCount}/${maxToolRounds}; ` +
+          `ending the turn before the next model call`,
+        );
+        throw new ToolRoundLimitError(maxToolRounds);
+      }
+
       let effectiveRequest = request;
 
       if (pendingAdvisory !== null) {
@@ -150,6 +178,7 @@ export function createExecutionBudgetMiddleware(
       const response = await handler(effectiveRequest);
 
       modelRoundCount++;
+      if (isToolRound(response)) toolRoundCount++;
       evaluateBudget();
 
       return response;
@@ -162,13 +191,10 @@ export function createExecutionBudgetMiddleware(
           `${warningCount}/${maxWarnings} advisories (interval=${warningInterval})`,
         );
       } else {
-        const estimatedTotal = Math.floor(recursionLimit / 6);
-        const pctUsed = estimatedTotal > 0
-          ? Math.floor(modelRoundCount * 100 / estimatedTotal)
-          : 0;
+        const pctUsed = Math.floor(toolRoundCount * 100 / roundBudget);
         console.log(
-          `[ExecutionBudget] Summary (threshold): ${modelRoundCount} rounds ` +
-          `of ~${estimatedTotal} (~${pctUsed}% used), warnings=${warningCount}`,
+          `[ExecutionBudget] Summary (threshold): ${toolRoundCount} tool rounds ` +
+          `of ${roundBudget} (${pctUsed}% used), warnings=${warningCount}`,
         );
       }
     },

package/src/middleware/index.ts

@@ -8,8 +8,8 @@
  *      since issue #754 — FIRST, so every downstream middleware observes
  *      canonical workspace-absolute paths)
  *   1. Loop detection (always)
- *   2. Execution budget (always — advises at ~80% of the tool-round budget
- *      that LangGraph's `recursionLimit` enforces)
+ *   2. Execution budget (always — counts tool rounds, advises at ~80% of
+ *      `max_tool_rounds` and ends the turn at it)
  *   3. Tool intent (always — bind-time shell schema extension, issue #276)
  *   4. Tool truncation (always)
  *   5. Approval gate (conditional: absent under the global bypass)
@@ -19,11 +19,14 @@
  *   8. OTel spans (always, no-op when OTel not configured)
  *
  * Every middleware here either shapes the graph's tool surface or ADVISES
- * the model; none of them stops the run. A stop — the platform's, the
- * cost cap's, a stall's — is the turn runtime's, delivered to the graph
- * through its abort signal (since #1096; until then a
- * graceful-stop middleware and the cost cap's tool block were second stops
- * inside the graph that the runtime could not see).
+ * the model; none of them stops the run, except the execution budget, which
+ * is `max_tool_rounds`' own enforcement: it ends the turn as the adapter's
+ * `tool_call_limit` outcome, the job LangGraph's recursion limit held until
+ * #1113, so the runtime sees it as an outcome and never as a completion.
+ * Every other stop — the platform's, the cost cap's, a stall's — is the turn
+ * runtime's, delivered to the graph through its abort signal (since #1096;
+ * until then a graceful-stop middleware and the cost cap's tool block were
+ * second stops inside the graph that the runtime could not see).
  *
  * Ahead of this stack the parent graph adds the framework's to-do list
  * middleware (`execute-deep-agent/turn-setup.ts`): it is langchain's, not

package/src/middleware/types.ts

@@ -71,7 +71,12 @@ export interface LoopDetectionConfig {
 }
 
 export interface ExecutionBudgetConfig {
-  readonly recursionLimit: number;
+  /**
+   * The turn's round budget, already clamped (`shared/tool-rounds.ts`
+   * `resolveToolRoundLimit`); the middleware ends the turn when it is spent.
+   * `null` is unlimited: the advisory still fires, nothing is stopped.
+   */
+  readonly maxToolRounds: number | null;
   readonly warningPct: number;
   readonly warningInterval: number | null;
   readonly maxWarnings: number;

package/src/runner-manager.ts

@@ -722,9 +722,10 @@ export function mapManagerOptionsToConfig(
     temporalConnection:
       options.temporalConnection ?? loadTemporalConnectionConfig(getRunnerSecret),
     stigmerBackendEndpoint: normalizeEndpoint(options.stigmerEndpoint),
-    // Env-only like the env-loaded path (loadConfig): the bridge endpoint
-    // is deployment topology, not per-session state.
+    // Env-only like the env-loaded path (loadConfig): the bridge and public
+    // endpoints are deployment topology, not per-session state.
     mcpBridgeEndpoint: process.env.STIGMER_MCP_BRIDGE_ENDPOINT ?? null,
+    mcpPublicEndpoint: process.env.STIGMER_MCP_PUBLIC_ENDPOINT || null,
     stigmerTokenRef: tokenRef,
     stigmerRunnerTokenRef: runnerTokenRef,
     // The manager's proxy credential is the minted runner token once adopted