@theokit/sdk 2.14.0 → 2.15.0

package/dist/internal/agent-loop/doom-loop-tracker.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Doom-loop guard — detects consecutive IDENTICAL tool calls (same name + same canonical input)
+ * and escalates `ok` → `soft` (one-time nudge) → `hard` (stop). Inspection is TOTAL — `signatureOf`
+ * and `inspect` never throw on any tool-call input. The constructor validates thresholds and throws
+ * a typed `ConfigurationError` on invalid config (fail-fast at the boundary — a 0/negative/non-integer
+ * threshold is a caller bug, not a loop input). Ported in shape from cline `LoopDetectionTracker`.
+ * Complements the empty-round `no_progress` terminal (a DIFFERENT failure mode: model stuck repeating
+ * vs model gone silent).
+ * @internal
+ */
+/** Verdict from {@link DoomLoopTracker.inspect}. `soft` carries a guidance message, `hard` a stop message. */
+export interface DoomLoopVerdict {
+    kind: "ok" | "soft" | "hard";
+    message?: string;
+}
+/** Consecutive-identical thresholds. `soft` fires once (at exactly the count); `hard` stops. */
+export interface DoomLoopConfig {
+    softThreshold: number;
+    hardThreshold: number;
+}
+/** Public config on a send: `false` disables the guard; an object tunes the thresholds; absent = on. */
+export type DoomLoopOption = false | Partial<DoomLoopConfig>;

package/dist/internal/agent-loop/loop-types.d.ts

@@ -32,4 +32,10 @@ export interface AgentLoopOutput {
      * `RunResult.stoppedAtIterationLimit`.
      */
     stoppedAtIterationLimit?: boolean;
+    /**
+     * Doom-loop guard: true when the loop stopped because the model repeated IDENTICAL tool calls to
+     * the hard threshold. Copied verbatim onto `RunResult.stoppedByDoomLoop`; the continuation driver
+     * classifies it as a `no_progress` terminal (a controlled stop, not a truncation to re-send).
+     */
+    stoppedByDoomLoop?: boolean;
 }

package/dist/{run-TMdc7gmo.d.cts → run-DXy_MVwz.d.cts}

@@ -687,6 +687,28 @@ interface RunResult {
      * @public
      */
     stoppedAtIterationLimit?: boolean;
+    /**
+     * `true` when the run stopped because the **doom-loop guard** detected the model repeating
+     * IDENTICAL tool calls (same name + same input) to the hard threshold — making no progress (e.g.
+     * a tool that keeps failing and is retried unchanged). `undefined`/absent otherwise. Through the
+     * continuation driver this surfaces as `terminal: "no_progress"` (a controlled stop, NOT a
+     * truncation to re-send). Tune or disable via {@link SendOptions.doomLoop}.
+     *
+     * @public
+     */
+    stoppedByDoomLoop?: boolean;
+}
+/**
+ * Doom-loop guard thresholds (see {@link SendOptions.doomLoop}). Both are counts of CONSECUTIVE
+ * identical tool calls: `softThreshold` injects a one-time guidance nudge; `hardThreshold` stops.
+ *
+ * @public
+ */
+interface DoomLoopThresholds {
+    /** Consecutive-identical count at which a one-time guidance nudge is injected. Default 3. */
+    softThreshold?: number;
+    /** Consecutive-identical count at which the run stops (`no_progress`). Default 5. */
+    hardThreshold?: number;
 }
 /**
  * Options for {@link SDKAgent.runToCompletion} (M1 Phase 3 — continuation driver).
@@ -803,6 +825,12 @@ interface SDKUserMessage {
  */
 interface SendOptions {
     model?: ModelSelection;
+    /**
+     * Doom-loop guard config. The loop stops (with `terminal: "no_progress"`, `RunResult.stoppedByDoomLoop`)
+     * when the model repeats IDENTICAL tool calls to the hard threshold. On by default with generous
+     * thresholds (soft 3 / hard 5). Set `false` to disable, or an object to tune the thresholds.
+     */
+    doomLoop?: false | DoomLoopThresholds;
     /**
      * Per-call system prompt override. Wins over `AgentOptions.systemPrompt`.
      * String only — for dynamic resolvers, configure on `AgentOptions`. An
@@ -909,4 +937,4 @@ interface Run {
     onDidChangeStatus(listener: (status: RunStatus) => void): () => void;
 }
 
-export type { ThinkingMessage as $, AgentConversationTurn as A, SDKTaskMessage as B, CustomTool as C, SDKThinkingMessage as D, SDKToolUseMessage as E, SDKUserMessage as F, SDKUserMessageEvent as G, SendOptions as H, InteractionUpdate as I, ShellCommand as J, ShellConversationTurn as K, ShellOutput as L, ModelSelection as M, ShellOutputDeltaUpdate as N, StepCompletedUpdate as O, PartialToolCallUpdate as P, StepStartedUpdate as Q, RunResult as R, SDKMessage as S, StreamToCompletionResult as T, SummaryCompletedUpdate as U, SummaryStartedUpdate as V, SummaryUpdate as W, TextBlock as X, TextDeltaUpdate as Y, ThinkingCompletedUpdate as Z, ThinkingDeltaUpdate as _, McpServerConfig as a, TokenDeltaUpdate as a0, TokenUsage as a1, ToolCall as a2, ToolCallCompletedUpdate as a3, ToolCallStartedUpdate as a4, ToolResult as a5, ToolUseBlock as a6, TurnEndedUpdate as a7, UserMessage as a8, UserMessageAppendedUpdate as a9, Run as b, AssistantMessage as c, ConversationStep as d, ConversationTurn as e, CostBreakdown as f, CostSource as g, CostStatus as h, McpAuthConfig as i, McpHttpServerConfig as j, McpOAuthConfig as k, McpStdioServerConfig as l, ModelParameterValue as m, RunErrorDetail as n, RunGitInfo as o, RunOperation as p, RunStatus as q, RunToCompletionOptions as r, RunToCompletionResult as s, SDKAssistantMessage as t, SDKImage as u, SDKImageDimension as v, SDKObjectDelta as w, SDKRequestMessage as x, SDKStatusMessage as y, SDKSystemMessage as z };
+export type { ThinkingDeltaUpdate as $, AgentConversationTurn as A, SDKTaskMessage as B, CustomTool as C, DoomLoopThresholds as D, SDKThinkingMessage as E, SDKToolUseMessage as F, SDKUserMessage as G, SDKUserMessageEvent as H, InteractionUpdate as I, SendOptions as J, ShellCommand as K, ShellConversationTurn as L, ModelSelection as M, ShellOutput as N, ShellOutputDeltaUpdate as O, PartialToolCallUpdate as P, StepCompletedUpdate as Q, RunResult as R, SDKMessage as S, StepStartedUpdate as T, StreamToCompletionResult as U, SummaryCompletedUpdate as V, SummaryStartedUpdate as W, SummaryUpdate as X, TextBlock as Y, TextDeltaUpdate as Z, ThinkingCompletedUpdate as _, McpServerConfig as a, ThinkingMessage as a0, TokenDeltaUpdate as a1, TokenUsage as a2, ToolCall as a3, ToolCallCompletedUpdate as a4, ToolCallStartedUpdate as a5, ToolResult as a6, ToolUseBlock as a7, TurnEndedUpdate as a8, UserMessage as a9, UserMessageAppendedUpdate as aa, Run as b, AssistantMessage as c, ConversationStep as d, ConversationTurn as e, CostBreakdown as f, CostSource as g, CostStatus as h, McpAuthConfig as i, McpHttpServerConfig as j, McpOAuthConfig as k, McpStdioServerConfig as l, ModelParameterValue as m, RunErrorDetail as n, RunGitInfo as o, RunOperation as p, RunStatus as q, RunToCompletionOptions as r, RunToCompletionResult as s, SDKAssistantMessage as t, SDKImage as u, SDKImageDimension as v, SDKObjectDelta as w, SDKRequestMessage as x, SDKStatusMessage as y, SDKSystemMessage as z };

package/dist/{run-TMdc7gmo.d.ts → run-DXy_MVwz.d.ts}

@@ -687,6 +687,28 @@ interface RunResult {
      * @public
      */
     stoppedAtIterationLimit?: boolean;
+    /**
+     * `true` when the run stopped because the **doom-loop guard** detected the model repeating
+     * IDENTICAL tool calls (same name + same input) to the hard threshold — making no progress (e.g.
+     * a tool that keeps failing and is retried unchanged). `undefined`/absent otherwise. Through the
+     * continuation driver this surfaces as `terminal: "no_progress"` (a controlled stop, NOT a
+     * truncation to re-send). Tune or disable via {@link SendOptions.doomLoop}.
+     *
+     * @public
+     */
+    stoppedByDoomLoop?: boolean;
+}
+/**
+ * Doom-loop guard thresholds (see {@link SendOptions.doomLoop}). Both are counts of CONSECUTIVE
+ * identical tool calls: `softThreshold` injects a one-time guidance nudge; `hardThreshold` stops.
+ *
+ * @public
+ */
+interface DoomLoopThresholds {
+    /** Consecutive-identical count at which a one-time guidance nudge is injected. Default 3. */
+    softThreshold?: number;
+    /** Consecutive-identical count at which the run stops (`no_progress`). Default 5. */
+    hardThreshold?: number;
 }
 /**
  * Options for {@link SDKAgent.runToCompletion} (M1 Phase 3 — continuation driver).
@@ -803,6 +825,12 @@ interface SDKUserMessage {
  */
 interface SendOptions {
     model?: ModelSelection;
+    /**
+     * Doom-loop guard config. The loop stops (with `terminal: "no_progress"`, `RunResult.stoppedByDoomLoop`)
+     * when the model repeats IDENTICAL tool calls to the hard threshold. On by default with generous
+     * thresholds (soft 3 / hard 5). Set `false` to disable, or an object to tune the thresholds.
+     */
+    doomLoop?: false | DoomLoopThresholds;
     /**
      * Per-call system prompt override. Wins over `AgentOptions.systemPrompt`.
      * String only — for dynamic resolvers, configure on `AgentOptions`. An
@@ -909,4 +937,4 @@ interface Run {
     onDidChangeStatus(listener: (status: RunStatus) => void): () => void;
 }
 
-export type { ThinkingMessage as $, AgentConversationTurn as A, SDKTaskMessage as B, CustomTool as C, SDKThinkingMessage as D, SDKToolUseMessage as E, SDKUserMessage as F, SDKUserMessageEvent as G, SendOptions as H, InteractionUpdate as I, ShellCommand as J, ShellConversationTurn as K, ShellOutput as L, ModelSelection as M, ShellOutputDeltaUpdate as N, StepCompletedUpdate as O, PartialToolCallUpdate as P, StepStartedUpdate as Q, RunResult as R, SDKMessage as S, StreamToCompletionResult as T, SummaryCompletedUpdate as U, SummaryStartedUpdate as V, SummaryUpdate as W, TextBlock as X, TextDeltaUpdate as Y, ThinkingCompletedUpdate as Z, ThinkingDeltaUpdate as _, McpServerConfig as a, TokenDeltaUpdate as a0, TokenUsage as a1, ToolCall as a2, ToolCallCompletedUpdate as a3, ToolCallStartedUpdate as a4, ToolResult as a5, ToolUseBlock as a6, TurnEndedUpdate as a7, UserMessage as a8, UserMessageAppendedUpdate as a9, Run as b, AssistantMessage as c, ConversationStep as d, ConversationTurn as e, CostBreakdown as f, CostSource as g, CostStatus as h, McpAuthConfig as i, McpHttpServerConfig as j, McpOAuthConfig as k, McpStdioServerConfig as l, ModelParameterValue as m, RunErrorDetail as n, RunGitInfo as o, RunOperation as p, RunStatus as q, RunToCompletionOptions as r, RunToCompletionResult as s, SDKAssistantMessage as t, SDKImage as u, SDKImageDimension as v, SDKObjectDelta as w, SDKRequestMessage as x, SDKStatusMessage as y, SDKSystemMessage as z };
+export type { ThinkingDeltaUpdate as $, AgentConversationTurn as A, SDKTaskMessage as B, CustomTool as C, DoomLoopThresholds as D, SDKThinkingMessage as E, SDKToolUseMessage as F, SDKUserMessage as G, SDKUserMessageEvent as H, InteractionUpdate as I, SendOptions as J, ShellCommand as K, ShellConversationTurn as L, ModelSelection as M, ShellOutput as N, ShellOutputDeltaUpdate as O, PartialToolCallUpdate as P, StepCompletedUpdate as Q, RunResult as R, SDKMessage as S, StepStartedUpdate as T, StreamToCompletionResult as U, SummaryCompletedUpdate as V, SummaryStartedUpdate as W, SummaryUpdate as X, TextBlock as Y, TextDeltaUpdate as Z, ThinkingCompletedUpdate as _, McpServerConfig as a, ThinkingMessage as a0, TokenDeltaUpdate as a1, TokenUsage as a2, ToolCall as a3, ToolCallCompletedUpdate as a4, ToolCallStartedUpdate as a5, ToolResult as a6, ToolUseBlock as a7, TurnEndedUpdate as a8, UserMessage as a9, UserMessageAppendedUpdate as aa, Run as b, AssistantMessage as c, ConversationStep as d, ConversationTurn as e, CostBreakdown as f, CostSource as g, CostStatus as h, McpAuthConfig as i, McpHttpServerConfig as j, McpOAuthConfig as k, McpStdioServerConfig as l, ModelParameterValue as m, RunErrorDetail as n, RunGitInfo as o, RunOperation as p, RunStatus as q, RunToCompletionOptions as r, RunToCompletionResult as s, SDKAssistantMessage as t, SDKImage as u, SDKImageDimension as v, SDKObjectDelta as w, SDKRequestMessage as x, SDKStatusMessage as y, SDKSystemMessage as z };

package/dist/types/run.d.ts

@@ -81,6 +81,28 @@ export interface RunResult {
      * @public
      */
     stoppedAtIterationLimit?: boolean;
+    /**
+     * `true` when the run stopped because the **doom-loop guard** detected the model repeating
+     * IDENTICAL tool calls (same name + same input) to the hard threshold — making no progress (e.g.
+     * a tool that keeps failing and is retried unchanged). `undefined`/absent otherwise. Through the
+     * continuation driver this surfaces as `terminal: "no_progress"` (a controlled stop, NOT a
+     * truncation to re-send). Tune or disable via {@link SendOptions.doomLoop}.
+     *
+     * @public
+     */
+    stoppedByDoomLoop?: boolean;
+}
+/**
+ * Doom-loop guard thresholds (see {@link SendOptions.doomLoop}). Both are counts of CONSECUTIVE
+ * identical tool calls: `softThreshold` injects a one-time guidance nudge; `hardThreshold` stops.
+ *
+ * @public
+ */
+export interface DoomLoopThresholds {
+    /** Consecutive-identical count at which a one-time guidance nudge is injected. Default 3. */
+    softThreshold?: number;
+    /** Consecutive-identical count at which the run stops (`no_progress`). Default 5. */
+    hardThreshold?: number;
 }
 /**
  * Options for {@link SDKAgent.runToCompletion} (M1 Phase 3 — continuation driver).
@@ -197,6 +219,12 @@ export interface SDKUserMessage {
  */
 export interface SendOptions {
     model?: ModelSelection;
+    /**
+     * Doom-loop guard config. The loop stops (with `terminal: "no_progress"`, `RunResult.stoppedByDoomLoop`)
+     * when the model repeats IDENTICAL tool calls to the hard threshold. On by default with generous
+     * thresholds (soft 3 / hard 5). Set `false` to disable, or an object to tune the thresholds.
+     */
+    doomLoop?: false | DoomLoopThresholds;
     /**
      * Per-call system prompt override. Wins over `AgentOptions.systemPrompt`.
      * String only — for dynamic resolvers, configure on `AgentOptions`. An

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "2.14.0",
+  "version": "2.15.0",
   "description": "TypeScript SDK for the Theo agent harness — same surface, local or cloud.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/usetheo/theokit-sdk#readme",