@theokit/sdk 2.14.0 → 2.15.0

package/dist/index.cjs

@@ -2817,6 +2817,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";
@@ -6982,6 +6983,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;
 }
 
 // src/internal/runtime/cloud/cloud-run.ts
@@ -10733,6 +10735,93 @@ function evaluateBudgetGate(tracker) {
   }
 }
 
+// src/internal/agent-loop/doom-loop-tracker.ts
+init_errors();
+function createDoomLoopTracker(option) {
+  if (option === false) return void 0;
+  return new DoomLoopTracker(option);
+}
+var DEFAULT_CONFIG = { softThreshold: 3, hardThreshold: 5 };
+function assertValidThresholds(soft, hard) {
+  for (const [label, value] of [
+    ["softThreshold", soft],
+    ["hardThreshold", hard]
+  ]) {
+    if (!Number.isInteger(value) || value < 1) {
+      throw new exports.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 key2 of Object.keys(value).sort()) {
+    out[key2] = sortKeys(value[key2]);
+  }
+  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}`;
+}
+var 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;
+  }
+};
+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;
+}
+
 // src/internal/budget/usage-accumulator.ts
 var UsageAccumulator = class {
   input = 0;
@@ -10913,6 +11002,7 @@ async function initLoopContext(inputs) {
     tools,
     finalText: "",
     finalStatus: "finished",
+    doomLoop: createDoomLoopTracker(inputs.doomLoop),
     usage: new UsageAccumulator(),
     nudgeAttempts: 0,
     stopFeedbackAttempts: 0,
@@ -11937,6 +12027,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 });
     }
@@ -11963,7 +12054,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) {
@@ -12122,8 +12214,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";
+}
 
 // src/internal/llm/fallback-client.ts
 init_errors();
@@ -14684,6 +14794,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 } : {},
@@ -14816,6 +14928,7 @@ var RealLocalRun = class extends FixtureRunBase {
     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,