@stigmer/runner 3.1.17 → 3.2.1

package/src/shared/__tests__/tool-rounds.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it, vi, afterEach } from "vitest";
+import {
+  MAX_TOOL_ROUNDS,
+  MIN_TOOL_ROUNDS,
+  SUPER_STEPS_PER_ROUND,
+  resolveRecursionLimit,
+} from "../tool-rounds.js";
+
+describe("resolveRecursionLimit", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("returns null for unset (proto contract: 0 = unlimited)", () => {
+    expect(resolveRecursionLimit(undefined)).toBeNull();
+    expect(resolveRecursionLimit(0)).toBeNull();
+  });
+
+  it("returns null for negative values (treated as unset, never a tiny limit)", () => {
+    expect(resolveRecursionLimit(-5)).toBeNull();
+  });
+
+  it("converts rounds to super-steps at the contract's x6 factor", () => {
+    expect(resolveRecursionLimit(10)).toBe(60);
+    expect(resolveRecursionLimit(100)).toBe(600);
+    expect(resolveRecursionLimit(MAX_TOOL_ROUNDS)).toBe(MAX_TOOL_ROUNDS * SUPER_STEPS_PER_ROUND);
+  });
+
+  it("clamps below-range values up to the minimum with a warning", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    expect(resolveRecursionLimit(3)).toBe(MIN_TOOL_ROUNDS * SUPER_STEPS_PER_ROUND);
+
+    expect(warn).toHaveBeenCalledOnce();
+    expect(warn.mock.calls[0][0]).toContain("max_tool_rounds=3");
+    expect(warn.mock.calls[0][0]).toContain("clamping to 10");
+  });
+
+  it("clamps above-range values down to the maximum with a warning", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    expect(resolveRecursionLimit(5000)).toBe(MAX_TOOL_ROUNDS * SUPER_STEPS_PER_ROUND);
+
+    expect(warn).toHaveBeenCalledOnce();
+    expect(warn.mock.calls[0][0]).toContain("max_tool_rounds=5000");
+    expect(warn.mock.calls[0][0]).toContain("clamping to 1000");
+  });
+
+  it("does not warn for in-range values", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    resolveRecursionLimit(MIN_TOOL_ROUNDS);
+    resolveRecursionLimit(MAX_TOOL_ROUNDS);
+
+    expect(warn).not.toHaveBeenCalled();
+  });
+});

package/src/shared/tool-rounds.ts

@@ -0,0 +1,56 @@
+/**
+ * ExecutionConfig.max_tool_rounds → LangGraph recursion_limit resolution.
+ *
+ * Implements the proto contract (agentexecution/v1/spec.proto):
+ *   - 0 / unset = unlimited — no recursionLimit is placed on the invoke
+ *     config, preserving the run-until-done + loop-detection posture.
+ *   - When set, valid range is 10–1000 rounds; out-of-range values are
+ *     clamped to the nearest bound with a warning log.
+ *   - recursion_limit = rounds × 6: each model-tool round consumes multiple
+ *     graph super-steps because every active middleware hook is its own
+ *     node; ×6 is the contract's floor estimate.
+ *
+ * The SAME resolved limit must feed both LangGraph's hard stop (the invoke
+ * config) and the ExecutionBudgetMiddleware's wrap-up advisory, so the
+ * "~80% of budget" warning and the enforcement point can never disagree.
+ */
+
+export const SUPER_STEPS_PER_ROUND = 6;
+export const MIN_TOOL_ROUNDS = 10;
+export const MAX_TOOL_ROUNDS = 1000;
+
+/**
+ * The advisory-only budget used when max_tool_rounds is unset: high enough
+ * to never fire on a healthy run. Deliberately NOT enforced as a hard
+ * recursionLimit — unset means unlimited per the proto contract.
+ */
+export const UNBOUNDED_ADVISORY_RECURSION_LIMIT = 6000;
+
+/**
+ * The recursionLimit for the invoke config, or null when the execution is
+ * unbounded (max_tool_rounds 0/unset — the pre-existing default posture).
+ */
+export function resolveRecursionLimit(maxToolRounds: number | undefined): number | null {
+  if (!maxToolRounds || maxToolRounds <= 0) {
+    return null;
+  }
+  return clampToolRounds(maxToolRounds) * SUPER_STEPS_PER_ROUND;
+}
+
+function clampToolRounds(requested: number): number {
+  if (requested < MIN_TOOL_ROUNDS) {
+    console.warn(
+      `[tool-rounds] max_tool_rounds=${requested} below the valid range ` +
+      `(${MIN_TOOL_ROUNDS}-${MAX_TOOL_ROUNDS}); clamping to ${MIN_TOOL_ROUNDS}`,
+    );
+    return MIN_TOOL_ROUNDS;
+  }
+  if (requested > MAX_TOOL_ROUNDS) {
+    console.warn(
+      `[tool-rounds] max_tool_rounds=${requested} above the valid range ` +
+      `(${MIN_TOOL_ROUNDS}-${MAX_TOOL_ROUNDS}); clamping to ${MAX_TOOL_ROUNDS}`,
+    );
+    return MAX_TOOL_ROUNDS;
+  }
+  return requested;
+}