@theokit/sdk 2.14.0 → 2.15.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 2.15.1
+
+### Patch Changes
+
+- bec2077: Make the leaked-dialect recovery **request-scoped (R5)**. The opt-in `extractToolCallsFromContent` recovery previously promoted ANY `<function=NAME>` block leaked into assistant text on an enabled route, so a code assistant printing a literal `<function=example>` in a fenced code block could be wrongly turned into a tool call. Recovery now gates on an exact, case-sensitive allowlist derived automatically from the current request's declared tools (`request.tools`): the per-route flag stays the coarse enable, and the allowlist is the precise false-positive guard. A request with no tools recovers nothing; a gated-out block keeps its text visible (it is not silently deleted). No public API change — the allowlist is derived from the tools you already pass. Mirrors openclaw's `@openclaw/tool-call-repair` allowlist.
+
+## 2.15.0
+
+### Minor Changes
+
+- d7057f2: Add a **doom-loop / no-progress guard** to the agent loop. The loop now detects when the model repeats IDENTICAL tool calls (same name + same canonical input) that make no progress — the qwen3-coder `read_file`/`not_found` failure mode where the model retries the same failing call and the run grinds to the iteration ceiling — and stops early with a typed `no_progress` terminal instead of hanging. A pure `DoomLoopTracker` (canonical key-sorted-JSON signature + a consecutive-identical counter) escalates from a one-time guidance nudge at a soft threshold to a hard stop; the hard stop surfaces on `RunResult.stoppedByDoomLoop` and, through the continuation driver, as `terminal: "no_progress"` (so the outer loop does not re-send). It complements — does not replace — the existing empty-round `no_progress` (a different failure mode: model stuck repeating vs model gone silent). On by default with generous thresholds (soft 3 / hard 5); tune or disable per send via `SendOptions.doomLoop` (`false` to disable, or `{ softThreshold, hardThreshold }` to tune). Dependency-free. Grounded in a SOTA study of cline's LoopDetectionTracker + opencode's doom-loop.
+
 ## 2.14.0
 
 ### Minor Changes

package/dist/a2a/index.cjs

@@ -2336,6 +2336,7 @@ function applyScriptMetrics(base, script) {
   if (script.usage !== void 0) base.usage = script.usage;
   if (script.cost !== void 0) base.cost = script.cost;
   if (script.stoppedAtIterationLimit === true) base.stoppedAtIterationLimit = true;
+  if (script.stoppedByDoomLoop === true) base.stoppedByDoomLoop = true;
 }
 var FixtureRunBase;
 var init_fixture_run_base = __esm({
@@ -6812,6 +6813,98 @@ var init_budget_gate = __esm({
   }
 });
 
+// src/internal/agent-loop/doom-loop-tracker.ts
+function createDoomLoopTracker(option) {
+  if (option === false) return void 0;
+  return new DoomLoopTracker(option);
+}
+function assertValidThresholds(soft, hard) {
+  for (const [label, value] of [
+    ["softThreshold", soft],
+    ["hardThreshold", hard]
+  ]) {
+    if (!Number.isInteger(value) || value < 1) {
+      throw new ConfigurationError(
+        `doomLoop.${label} must be a positive integer (received ${value}).`,
+        { code: "invalid_doom_loop_threshold" }
+      );
+    }
+  }
+}
+function sortKeys(value) {
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map(sortKeys);
+  const out = {};
+  for (const key of Object.keys(value).sort()) {
+    out[key] = sortKeys(value[key]);
+  }
+  return out;
+}
+function signatureOf(call) {
+  const { input } = call;
+  let inputSig;
+  if (input === null || input === void 0) inputSig = "null";
+  else if (typeof input !== "object") inputSig = String(input);
+  else {
+    try {
+      inputSig = JSON.stringify(sortKeys(input)) ?? "null";
+    } catch {
+      inputSig = String(input);
+    }
+  }
+  return `${call.name}\0${inputSig}`;
+}
+function firstDoomLoopVerdict(tracker, calls) {
+  let escalation = { kind: "ok" };
+  for (const call of calls) {
+    const v = tracker.inspect(call);
+    if (v.kind === "hard") return v;
+    if (v.kind === "soft" && escalation.kind === "ok") escalation = v;
+  }
+  return escalation;
+}
+var DEFAULT_CONFIG, DoomLoopTracker;
+var init_doom_loop_tracker = __esm({
+  "src/internal/agent-loop/doom-loop-tracker.ts"() {
+    init_errors();
+    DEFAULT_CONFIG = { softThreshold: 3, hardThreshold: 5 };
+    DoomLoopTracker = class {
+      #config;
+      #lastSignature = "";
+      #count = 0;
+      constructor(config) {
+        const softThreshold = config?.softThreshold ?? DEFAULT_CONFIG.softThreshold;
+        const hardThreshold = config?.hardThreshold ?? DEFAULT_CONFIG.hardThreshold;
+        assertValidThresholds(softThreshold, hardThreshold);
+        this.#config = { softThreshold, hardThreshold };
+      }
+      inspect(call) {
+        const signature = signatureOf(call);
+        this.#count = signature === this.#lastSignature ? this.#count + 1 : 1;
+        this.#lastSignature = signature;
+        const count = this.#count;
+        if (count >= this.#config.hardThreshold) {
+          return {
+            kind: "hard",
+            message: `Detected ${count} consecutive identical calls to \`${call.name}\`; stopping to avoid a loop.`
+          };
+        }
+        if (count === this.#config.softThreshold) {
+          return {
+            kind: "soft",
+            message: `Detected ${count} consecutive identical calls to \`${call.name}\`; try a different approach.`
+          };
+        }
+        return { kind: "ok" };
+      }
+      reset() {
+        this.#lastSignature = "";
+        this.#count = 0;
+      }
+    };
+  }
+});
+
 // src/internal/budget/usage-accumulator.ts
 var UsageAccumulator;
 var init_usage_accumulator = __esm({
@@ -7001,6 +7094,7 @@ async function initLoopContext(inputs) {
     tools,
     finalText: "",
     finalStatus: "finished",
+    doomLoop: createDoomLoopTracker(inputs.doomLoop),
     usage: new UsageAccumulator(),
     nudgeAttempts: 0,
     stopFeedbackAttempts: 0,
@@ -7053,6 +7147,7 @@ function sanitize(name) {
 var init_loop_context_init = __esm({
   "src/internal/agent-loop/loop-context-init.ts"() {
     init_usage_accumulator();
+    init_doom_loop_tracker();
     init_message_builders();
   }
 });
@@ -8165,6 +8260,7 @@ async function runAgentLoop(inputs) {
       ctx.finalStatus = "error";
     }
     sendSpan?.setAttribute("status", ctx.finalStatus);
+    if (ctx.stoppedByDoomLoop === true) sendSpan?.setAttribute("stoppedByDoomLoop", true);
     if (inputs.telemetry?.includeContent === true && ctx.finalText.length > 0) {
       sendSpan?.addEvent("response", { content: ctx.finalText });
     }
@@ -8191,7 +8287,8 @@ async function runAgentLoop(inputs) {
       ...usage !== void 0 ? { usage } : {},
       ...cost !== void 0 ? { cost } : {},
       ...ctx.error !== void 0 ? { error: ctx.error } : {},
-      ...ctx.stoppedAtIterationLimit === true ? { stoppedAtIterationLimit: true } : {}
+      ...ctx.stoppedAtIterationLimit === true ? { stoppedAtIterationLimit: true } : {},
+      ...ctx.stoppedByDoomLoop === true ? { stoppedByDoomLoop: true } : {}
     };
   } finally {
     if (ctxRef !== void 0 && ctxRef.memoryProviderHandle !== void 0 && inputs.memoryProvider !== void 0) {
@@ -8350,8 +8447,26 @@ async function continueOrTerminate(inputs, ctx, llmOutput) {
     }
   }
   pushToolConversationSteps(ctx, llmOutput.toolCalls, toolResults);
+  if (await inspectDoomLoop(inputs, ctx, llmOutput.toolCalls) === "stop") return "done";
   return handleToolErrorContinuation(inputs, ctx, toolResults);
 }
+async function inspectDoomLoop(inputs, ctx, toolCalls) {
+  if (ctx.doomLoop === void 0) return "continue";
+  const verdict = firstDoomLoopVerdict(ctx.doomLoop, toolCalls);
+  if (verdict.kind === "hard") {
+    ctx.stoppedByDoomLoop = true;
+    await emitAssistantTextStep(
+      inputs,
+      ctx,
+      verdict.message ?? "Stopped: repeated identical tool calls made no progress."
+    );
+    return "stop";
+  }
+  if (verdict.kind === "soft") {
+    ctx.messages.push({ role: "user", content: [{ type: "text", text: verdict.message ?? "" }] });
+  }
+  return "continue";
+}
 var MAX_NUDGE_ATTEMPTS, MAX_STOP_FEEDBACK_ATTEMPTS;
 var init_loop = __esm({
   "src/internal/agent-loop/loop.ts"() {
@@ -8359,6 +8474,7 @@ var init_loop = __esm({
     init_safe_call();
     init_validate_response();
     init_budget_gate();
+    init_doom_loop_tracker();
     init_loop_context_init();
     init_loop_llm_stream();
     init_message_builders();
@@ -10216,11 +10332,16 @@ var init_sanitize_tool_input = __esm({
 });
 
 // src/internal/llm/hermes-tool-extract.ts
-function extractHermesToolCalls(content, makeId) {
+function extractHermesToolCalls(content, makeId, allowedToolNames) {
+  const isPromoted = (name) => name.length > 0 && (allowedToolNames === void 0 || allowedToolNames.has(name));
   const toolCalls = [];
+  const droppedNames = [];
   for (const block of content.matchAll(HERMES_BLOCK)) {
     const name = (block[1] ?? "").trim();
-    if (name.length === 0) continue;
+    if (!isPromoted(name)) {
+      if (name.length > 0 && allowedToolNames !== void 0) droppedNames.push(name);
+      continue;
+    }
     toolCalls.push({
       type: "tool_use",
       id: makeId(),
@@ -10228,8 +10349,11 @@ function extractHermesToolCalls(content, makeId) {
       input: parseHermesParams(block[2] ?? "")
     });
   }
-  const residualText = toolCalls.length === 0 ? content : content.replace(HERMES_BLOCK, "").trim();
-  return { toolCalls, residualText };
+  const residualText = toolCalls.length === 0 ? content : content.replace(
+    HERMES_BLOCK,
+    (full, rawName) => isPromoted((rawName ?? "").trim()) ? "" : full
+  ).trim();
+  return { toolCalls, residualText, droppedNames };
 }
 function parseHermesParams(inner) {
   const input = {};
@@ -10434,7 +10558,10 @@ var init_openai2 = __esm({
         }
         const accumulator = new OpenAIStreamAccumulator(
           this.options.extractToolCallsFromContent ?? false,
-          providerId
+          providerId,
+          // R5: request-scoped allowlist — leaked recovery only promotes a block whose name is a tool the
+          // model was actually given. Empty set (no tools) recovers nothing.
+          new Set(request.tools?.map((tool) => tool.name) ?? [])
         );
         for await (const record of parseSseStream(response.body, signal)) {
           if (record.data === "[DONE]") break;
@@ -10464,13 +10591,18 @@ var init_openai2 = __esm({
       /**
        * @param extractFromContent opt-in leaked-dialect safe-parse (theokit#58). Default false.
        * @param providerName provider id, used only to label the recovery log line.
+       * @param allowedToolNames R5 request-scoped allowlist — built from `request.tools` at `stream()`;
+       *   leaked recovery in `finish()` only promotes a block whose name is in this set. `undefined`
+       *   (direct construction) recovers all (back-compat); an empty set recovers nothing.
        */
-      constructor(extractFromContent = false, providerName = "openai") {
+      constructor(extractFromContent = false, providerName = "openai", allowedToolNames) {
         this.extractFromContent = extractFromContent;
         this.providerName = providerName;
+        this.allowedToolNames = allowedToolNames;
       }
       extractFromContent;
       providerName;
+      allowedToolNames;
       text = "";
       stopReason = "end_turn";
       inputTokens;
@@ -10541,7 +10673,8 @@ var init_openai2 = __esm({
         if (this.extractFromContent && toolCalls.length === 0) {
           const recovered = extractHermesToolCalls(
             this.text,
-            () => `hermes-${globalThis.crypto.randomUUID()}`
+            () => `hermes-${globalThis.crypto.randomUUID()}`,
+            this.allowedToolNames
           );
           if (recovered.toolCalls.length > 0) {
             toolCalls.push(...recovered.toolCalls);
@@ -10549,6 +10682,12 @@ var init_openai2 = __esm({
             stopReason = "tool_use";
             process.stderr.write(
               `[theokit-sdk] recovered ${recovered.toolCalls.length} leaked tool call(s) from assistant content (provider="${this.providerName}", names=${recovered.toolCalls.map((c) => c.name).join(",")})
+`
+            );
+          }
+          if (recovered.droppedNames.length > 0) {
+            process.stderr.write(
+              `[theokit-sdk] dropped ${recovered.droppedNames.length} leaked block(s) whose name is not a tool in the request (provider="${this.providerName}", names=${recovered.droppedNames.join(",")})
 `
             );
           }
@@ -11443,6 +11582,8 @@ function buildLoopInputs(options, runId, userText) {
     // M1-2: per-send iteration ceiling (validated above). The loop reads
     // inputs.maxIterations (default 8 when unset).
     ...maxIterations !== void 0 ? { maxIterations } : {},
+    // Doom-loop guard config (default on; `false` disables, object tunes thresholds).
+    ...options.sendOptions.doomLoop !== void 0 ? { doomLoop: options.sendOptions.doomLoop } : {},
     // D315-D317 — tool lifecycle hooks (cost tracking + audit + retry/alert)
     ...options.agentOptions.onToolStart !== void 0 ? { onToolStart: options.agentOptions.onToolStart } : {},
     ...options.agentOptions.onToolEnd !== void 0 ? { onToolEnd: options.agentOptions.onToolEnd } : {},
@@ -11591,6 +11732,7 @@ var init_real_local_run = __esm({
         if (output.usage !== void 0) this.script.usage = output.usage;
         if (output.cost !== void 0) this.script.cost = output.cost;
         if (output.stoppedAtIterationLimit === true) this.script.stoppedAtIterationLimit = true;
+        if (output.stoppedByDoomLoop === true) this.script.stoppedByDoomLoop = true;
         if (output.error !== void 0 && this.script.errorDetail === void 0) {
           this.script.errorDetail = {
             message: output.error.message,
@@ -14582,6 +14724,7 @@ function isEmptyRound(result) {
   return (result.result ?? "").trim() === "";
 }
 function classifyRound(result, round, maxRounds, emptyStreak) {
+  if (result.stoppedByDoomLoop === true) return "no_progress";
   if (result.stoppedAtIterationLimit !== true) return "done";
   if (isEmptyRound(result) && emptyStreak >= 1) return "no_progress";
   if (round >= maxRounds) return "step_limit";