@theokit/sdk 2.1.0 → 2.3.0

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

@@ -26,4 +26,10 @@ export interface AgentLoopOutput {
      * message (the previous bug — sdk-error-packaging-fix-plan).
      */
     error?: AgentLoopErrorDetail;
+    /**
+     * M1-2 (T2.2): true when the loop stopped at its iteration ceiling with the
+     * model still wanting to call tools (silent truncation). Copied verbatim onto
+     * `RunResult.stoppedAtIterationLimit`.
+     */
+    stoppedAtIterationLimit?: boolean;
 }

package/dist/internal/runtime/budget/budget-tracker.d.ts

@@ -70,4 +70,12 @@ export interface BudgetTracker {
     check(): BudgetCheck;
     /** Snapshot of accumulated totals (for telemetry / final reporting). */
     getTotal(): BudgetTotal;
+    /**
+     * Advance the iteration counter by one. Called by the agent loop ONCE per
+     * completed turn (M1-1) so that trackers which gate on `maxIterations`
+     * (e.g. `createCounterBudgetTracker`) actually halt. OPTIONAL: trackers that
+     * only gate on tokens/USD omit it and the loop no-ops via optional chaining.
+     * MUST be synchronous and non-throwing.
+     */
+    nextIteration?(): void;
 }

package/dist/internal/runtime/lifecycle/run-to-completion.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `runToCompletion` continuation driver (M1 Phase 3 — plan m1-run-to-completion).
+ *
+ * Drives repeated `send()`s on a STATEFUL agent until a genuine terminal,
+ * consuming the `RunResult.stoppedAtIterationLimit` signal shipped in 2.2.0.
+ * The agent's session preserves conversation history across sends, so after a
+ * truncated round the driver only re-sends a short continuation prompt (it does
+ * NOT reconstruct history). Mirrors the injectable shape of `run-until.ts` and
+ * absorbs the outer-loop policy hand-rolled in `theocode/server/lib/agent-loop.ts`.
+ *
+ * The core is decision-pure + injectable (`agent` is only the `.send` port) so
+ * every terminal is unit-testable with a fake send — fixture mode never sets
+ * `stoppedAtIterationLimit`, so injection is the only deterministic path.
+ *
+ * @internal
+ */
+/** Minimal agent port the driver needs — the instance `.send()` surface. */
+export interface RunToCompletionAgent {
+    send(message: string, options?: SendOptions): Promise<{
+        wait(): Promise<RunResult>;
+    }>;
+}

package/dist/{run-DrwUpFxZ.d.cts → run-BPRYG1Id.d.cts}

@@ -625,7 +625,7 @@ type RunStatus = "running" | "finished" | "error" | "cancelled";
  *
  * @public
  */
-type RunOperation = "stream" | "wait" | "cancel" | "conversation" | "listArtifacts" | "downloadArtifact" | "runUntil" | "fork" | "usePersonality" | "workflow";
+type RunOperation = "stream" | "wait" | "cancel" | "conversation" | "listArtifacts" | "downloadArtifact" | "runUntil" | "runToCompletion" | "fork" | "usePersonality" | "workflow";
 /**
  * Git metadata attached to cloud runs.
  *
@@ -677,6 +677,69 @@ interface RunResult {
      * @public
      */
     cost?: CostBreakdown;
+    /**
+     * M1-2: `true` when the run stopped because the agent loop hit its iteration
+     * ceiling (`SendOptions.maxIterations` or the default of 8) while the model
+     * still wanted to call tools — i.e. the work was silently truncated rather
+     * than finished. `undefined`/absent on a clean finish. A continuation driver
+     * (or a careful caller) inspects this to decide whether to send again.
+     *
+     * @public
+     */
+    stoppedAtIterationLimit?: boolean;
+}
+/**
+ * Options for {@link SDKAgent.runToCompletion} (M1 Phase 3 — continuation driver).
+ *
+ * @public
+ */
+interface RunToCompletionOptions {
+    /**
+     * Maximum number of continuation rounds (re-sends) before giving up with
+     * `terminal: "step_limit"`. Default 5. A hard ceiling that prevents a
+     * runaway loop when the model keeps truncating.
+     */
+    maxRounds?: number;
+    /**
+     * The short prompt re-sent after a truncated round to make the (stateful)
+     * agent resume. Defaults to a generic "continue" instruction. The original
+     * conversation is preserved by the agent's session, so this need not repeat
+     * the task.
+     */
+    continuationPrompt?: string;
+    /** Called once per truncated round that triggers a re-send (for metrics/logging). */
+    onTruncated?: (event: {
+        round: number;
+    }) => void | Promise<void>;
+    /** Abort signal; checked between rounds — once aborted, no further round starts. */
+    signal?: AbortSignal;
+    /** Per-send options forwarded to each underlying `send()` (e.g. `maxIterations`). */
+    sendOptions?: SendOptions;
+}
+/**
+ * Result of {@link SDKAgent.runToCompletion}.
+ *
+ * @public
+ */
+interface RunToCompletionResult {
+    /**
+     * Why the driver stopped:
+     * - `"done"` — a round finished without truncating (the model is done).
+     * - `"step_limit"` — `maxRounds` exhausted (or aborted) while still truncating.
+     * - `"no_progress"` — two consecutive rounds produced empty output.
+     */
+    terminal: "done" | "step_limit" | "no_progress";
+    /**
+     * Index of the final round. Round 0 is the initial `send`; rounds ≥ 1 are
+     * continuation re-sends. So `terminal: "done"` with `rounds: 0` means the
+     * first send finished without truncating; `rounds: N` means N continuation
+     * re-sends happened. For `step_limit`, `rounds` equals `maxRounds`.
+     */
+    rounds: number;
+    /** The `RunResult` of the final round. */
+    lastResult: RunResult;
+    /** Token usage summed across all rounds; `undefined` when no round reported usage. */
+    usage?: TokenUsage;
 }
 /**
  * Structured error attached to a {@link RunResult} when the underlying run
@@ -789,6 +852,16 @@ interface SendOptions {
         id?: string;
         meta?: Record<string, unknown>;
     };
+    /**
+     * Per-send ceiling on the agent loop's tool-calling turns (M1-2). Raises (or
+     * lowers) the default cap of 8 for this single send — useful when one heavy
+     * task needs more rounds than the agent's default. Must be a positive
+     * integer; invalid values throw `ConfigurationError` at the boundary. When
+     * unset, the loop uses the default of 8.
+     *
+     * @public
+     */
+    maxIterations?: number;
 }
 /**
  * Handle to a single prompt submission.
@@ -820,4 +893,4 @@ interface Run {
     onDidChangeStatus(listener: (status: RunStatus) => void): () => void;
 }
 
-export type { ToolCall as $, AgentConversationTurn as A, SDKToolUseMessage as B, CustomTool as C, SDKUserMessage as D, SDKUserMessageEvent as E, SendOptions as F, ShellCommand as G, ShellConversationTurn as H, InteractionUpdate as I, ShellOutput as J, ShellOutputDeltaUpdate as K, StepCompletedUpdate as L, ModelSelection as M, StepStartedUpdate as N, SummaryCompletedUpdate as O, PartialToolCallUpdate as P, SummaryStartedUpdate as Q, RunResult as R, SDKMessage as S, SummaryUpdate as T, TextBlock as U, TextDeltaUpdate as V, ThinkingCompletedUpdate as W, ThinkingDeltaUpdate as X, ThinkingMessage as Y, TokenDeltaUpdate as Z, TokenUsage as _, McpServerConfig as a, ToolCallCompletedUpdate as a0, ToolCallStartedUpdate as a1, ToolResult as a2, ToolUseBlock as a3, TurnEndedUpdate as a4, UserMessage as a5, UserMessageAppendedUpdate as a6, 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, SDKAssistantMessage as r, SDKImage as s, SDKImageDimension as t, SDKObjectDelta as u, SDKRequestMessage as v, SDKStatusMessage as w, SDKSystemMessage as x, SDKTaskMessage as y, SDKThinkingMessage as z };
+export type { TokenDeltaUpdate 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, SummaryCompletedUpdate as T, SummaryStartedUpdate as U, SummaryUpdate as V, TextBlock as W, TextDeltaUpdate as X, ThinkingCompletedUpdate as Y, ThinkingDeltaUpdate as Z, ThinkingMessage as _, McpServerConfig as a, TokenUsage as a0, ToolCall as a1, ToolCallCompletedUpdate as a2, ToolCallStartedUpdate as a3, ToolResult as a4, ToolUseBlock as a5, TurnEndedUpdate as a6, UserMessage as a7, UserMessageAppendedUpdate as a8, 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-DrwUpFxZ.d.ts → run-BPRYG1Id.d.ts}

@@ -625,7 +625,7 @@ type RunStatus = "running" | "finished" | "error" | "cancelled";
  *
  * @public
  */
-type RunOperation = "stream" | "wait" | "cancel" | "conversation" | "listArtifacts" | "downloadArtifact" | "runUntil" | "fork" | "usePersonality" | "workflow";
+type RunOperation = "stream" | "wait" | "cancel" | "conversation" | "listArtifacts" | "downloadArtifact" | "runUntil" | "runToCompletion" | "fork" | "usePersonality" | "workflow";
 /**
  * Git metadata attached to cloud runs.
  *
@@ -677,6 +677,69 @@ interface RunResult {
      * @public
      */
     cost?: CostBreakdown;
+    /**
+     * M1-2: `true` when the run stopped because the agent loop hit its iteration
+     * ceiling (`SendOptions.maxIterations` or the default of 8) while the model
+     * still wanted to call tools — i.e. the work was silently truncated rather
+     * than finished. `undefined`/absent on a clean finish. A continuation driver
+     * (or a careful caller) inspects this to decide whether to send again.
+     *
+     * @public
+     */
+    stoppedAtIterationLimit?: boolean;
+}
+/**
+ * Options for {@link SDKAgent.runToCompletion} (M1 Phase 3 — continuation driver).
+ *
+ * @public
+ */
+interface RunToCompletionOptions {
+    /**
+     * Maximum number of continuation rounds (re-sends) before giving up with
+     * `terminal: "step_limit"`. Default 5. A hard ceiling that prevents a
+     * runaway loop when the model keeps truncating.
+     */
+    maxRounds?: number;
+    /**
+     * The short prompt re-sent after a truncated round to make the (stateful)
+     * agent resume. Defaults to a generic "continue" instruction. The original
+     * conversation is preserved by the agent's session, so this need not repeat
+     * the task.
+     */
+    continuationPrompt?: string;
+    /** Called once per truncated round that triggers a re-send (for metrics/logging). */
+    onTruncated?: (event: {
+        round: number;
+    }) => void | Promise<void>;
+    /** Abort signal; checked between rounds — once aborted, no further round starts. */
+    signal?: AbortSignal;
+    /** Per-send options forwarded to each underlying `send()` (e.g. `maxIterations`). */
+    sendOptions?: SendOptions;
+}
+/**
+ * Result of {@link SDKAgent.runToCompletion}.
+ *
+ * @public
+ */
+interface RunToCompletionResult {
+    /**
+     * Why the driver stopped:
+     * - `"done"` — a round finished without truncating (the model is done).
+     * - `"step_limit"` — `maxRounds` exhausted (or aborted) while still truncating.
+     * - `"no_progress"` — two consecutive rounds produced empty output.
+     */
+    terminal: "done" | "step_limit" | "no_progress";
+    /**
+     * Index of the final round. Round 0 is the initial `send`; rounds ≥ 1 are
+     * continuation re-sends. So `terminal: "done"` with `rounds: 0` means the
+     * first send finished without truncating; `rounds: N` means N continuation
+     * re-sends happened. For `step_limit`, `rounds` equals `maxRounds`.
+     */
+    rounds: number;
+    /** The `RunResult` of the final round. */
+    lastResult: RunResult;
+    /** Token usage summed across all rounds; `undefined` when no round reported usage. */
+    usage?: TokenUsage;
 }
 /**
  * Structured error attached to a {@link RunResult} when the underlying run
@@ -789,6 +852,16 @@ interface SendOptions {
         id?: string;
         meta?: Record<string, unknown>;
     };
+    /**
+     * Per-send ceiling on the agent loop's tool-calling turns (M1-2). Raises (or
+     * lowers) the default cap of 8 for this single send — useful when one heavy
+     * task needs more rounds than the agent's default. Must be a positive
+     * integer; invalid values throw `ConfigurationError` at the boundary. When
+     * unset, the loop uses the default of 8.
+     *
+     * @public
+     */
+    maxIterations?: number;
 }
 /**
  * Handle to a single prompt submission.
@@ -820,4 +893,4 @@ interface Run {
     onDidChangeStatus(listener: (status: RunStatus) => void): () => void;
 }
 
-export type { ToolCall as $, AgentConversationTurn as A, SDKToolUseMessage as B, CustomTool as C, SDKUserMessage as D, SDKUserMessageEvent as E, SendOptions as F, ShellCommand as G, ShellConversationTurn as H, InteractionUpdate as I, ShellOutput as J, ShellOutputDeltaUpdate as K, StepCompletedUpdate as L, ModelSelection as M, StepStartedUpdate as N, SummaryCompletedUpdate as O, PartialToolCallUpdate as P, SummaryStartedUpdate as Q, RunResult as R, SDKMessage as S, SummaryUpdate as T, TextBlock as U, TextDeltaUpdate as V, ThinkingCompletedUpdate as W, ThinkingDeltaUpdate as X, ThinkingMessage as Y, TokenDeltaUpdate as Z, TokenUsage as _, McpServerConfig as a, ToolCallCompletedUpdate as a0, ToolCallStartedUpdate as a1, ToolResult as a2, ToolUseBlock as a3, TurnEndedUpdate as a4, UserMessage as a5, UserMessageAppendedUpdate as a6, 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, SDKAssistantMessage as r, SDKImage as s, SDKImageDimension as t, SDKObjectDelta as u, SDKRequestMessage as v, SDKStatusMessage as w, SDKSystemMessage as x, SDKTaskMessage as y, SDKThinkingMessage as z };
+export type { TokenDeltaUpdate 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, SummaryCompletedUpdate as T, SummaryStartedUpdate as U, SummaryUpdate as V, TextBlock as W, TextDeltaUpdate as X, ThinkingCompletedUpdate as Y, ThinkingDeltaUpdate as Z, ThinkingMessage as _, McpServerConfig as a, TokenUsage as a0, ToolCall as a1, ToolCallCompletedUpdate as a2, ToolCallStartedUpdate as a3, ToolResult as a4, ToolUseBlock as a5, TurnEndedUpdate as a6, UserMessage as a7, UserMessageAppendedUpdate as a8, 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/agent.d.ts

@@ -608,6 +608,20 @@ export interface SDKAgent {
      * @public
      */
     fork?(options: import("./fork.js").ForkOptions): Promise<import("./fork.js").ForkResult>;
+    /**
+     * Drive `send` to completion across iteration-ceiling truncations (M1 Phase 3).
+     * When a `send` stops at the loop's iteration cap (`RunResult.stoppedAtIterationLimit`),
+     * this re-sends a short continuation prompt — the agent's stateful session
+     * preserves the conversation — until a genuine terminal: `done` (finished),
+     * `step_limit` (`maxRounds` exhausted), or `no_progress` (two empty rounds).
+     *
+     * Local agents only. Cloud agents throw
+     * {@link import("../errors.js").UnsupportedRunOperationError} (the cloud
+     * runtime manages its own continuation policy server-side).
+     *
+     * @public
+     */
+    runToCompletion?(message: string, options?: import("./run.js").RunToCompletionOptions): Promise<import("./run.js").RunToCompletionResult>;
     /**
      * Direct API to third-party memory adapter(s) registered via
      * `plugins: [...]` (ADR D141 / D142). Returns `null` when no adapter

package/dist/types/conversation-storage.d.ts

@@ -20,7 +20,11 @@
  * @public
  */
 export interface StoredMessage {
-    /** Origin of the message. `tool_call` / `tool_result` reserved for forward compat. */
+    /**
+     * Origin of the message. `tool_call` / `tool_result` are produced by
+     * `buildReplayHistory` (M1-3) for stateless replay; a consumer feeding a
+     * `user`/`assistant`-only wire-mapper must map those two roles itself.
+     */
     role: "user" | "assistant" | "system" | "tool_call" | "tool_result";
     /** UTF-8 payload. May be empty string (e.g., a tool with no return value). */
     content: string;

package/dist/types/run.d.ts

@@ -19,7 +19,7 @@ export type RunStatus = "running" | "finished" | "error" | "cancelled";
  *
  * @public
  */
-export type RunOperation = "stream" | "wait" | "cancel" | "conversation" | "listArtifacts" | "downloadArtifact" | "runUntil" | "fork" | "usePersonality" | "workflow";
+export type RunOperation = "stream" | "wait" | "cancel" | "conversation" | "listArtifacts" | "downloadArtifact" | "runUntil" | "runToCompletion" | "fork" | "usePersonality" | "workflow";
 /**
  * Git metadata attached to cloud runs.
  *
@@ -71,6 +71,69 @@ export interface RunResult {
      * @public
      */
     cost?: CostBreakdown;
+    /**
+     * M1-2: `true` when the run stopped because the agent loop hit its iteration
+     * ceiling (`SendOptions.maxIterations` or the default of 8) while the model
+     * still wanted to call tools — i.e. the work was silently truncated rather
+     * than finished. `undefined`/absent on a clean finish. A continuation driver
+     * (or a careful caller) inspects this to decide whether to send again.
+     *
+     * @public
+     */
+    stoppedAtIterationLimit?: boolean;
+}
+/**
+ * Options for {@link SDKAgent.runToCompletion} (M1 Phase 3 — continuation driver).
+ *
+ * @public
+ */
+export interface RunToCompletionOptions {
+    /**
+     * Maximum number of continuation rounds (re-sends) before giving up with
+     * `terminal: "step_limit"`. Default 5. A hard ceiling that prevents a
+     * runaway loop when the model keeps truncating.
+     */
+    maxRounds?: number;
+    /**
+     * The short prompt re-sent after a truncated round to make the (stateful)
+     * agent resume. Defaults to a generic "continue" instruction. The original
+     * conversation is preserved by the agent's session, so this need not repeat
+     * the task.
+     */
+    continuationPrompt?: string;
+    /** Called once per truncated round that triggers a re-send (for metrics/logging). */
+    onTruncated?: (event: {
+        round: number;
+    }) => void | Promise<void>;
+    /** Abort signal; checked between rounds — once aborted, no further round starts. */
+    signal?: AbortSignal;
+    /** Per-send options forwarded to each underlying `send()` (e.g. `maxIterations`). */
+    sendOptions?: SendOptions;
+}
+/**
+ * Result of {@link SDKAgent.runToCompletion}.
+ *
+ * @public
+ */
+export interface RunToCompletionResult {
+    /**
+     * Why the driver stopped:
+     * - `"done"` — a round finished without truncating (the model is done).
+     * - `"step_limit"` — `maxRounds` exhausted (or aborted) while still truncating.
+     * - `"no_progress"` — two consecutive rounds produced empty output.
+     */
+    terminal: "done" | "step_limit" | "no_progress";
+    /**
+     * Index of the final round. Round 0 is the initial `send`; rounds ≥ 1 are
+     * continuation re-sends. So `terminal: "done"` with `rounds: 0` means the
+     * first send finished without truncating; `rounds: N` means N continuation
+     * re-sends happened. For `step_limit`, `rounds` equals `maxRounds`.
+     */
+    rounds: number;
+    /** The `RunResult` of the final round. */
+    lastResult: RunResult;
+    /** Token usage summed across all rounds; `undefined` when no round reported usage. */
+    usage?: TokenUsage;
 }
 /**
  * Structured error attached to a {@link RunResult} when the underlying run
@@ -183,6 +246,16 @@ export interface SendOptions {
         id?: string;
         meta?: Record<string, unknown>;
     };
+    /**
+     * Per-send ceiling on the agent loop's tool-calling turns (M1-2). Raises (or
+     * lowers) the default cap of 8 for this single send — useful when one heavy
+     * task needs more rounds than the agent's default. Must be a positive
+     * integer; invalid values throw `ConfigurationError` at the boundary. When
+     * unset, the loop uses the default of 8.
+     *
+     * @public
+     */
+    maxIterations?: number;
 }
 /**
  * Handle to a single prompt submission.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "2.1.0",
+  "version": "2.3.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",
@@ -294,8 +294,8 @@
     "typedoc": "^0.28.19",
     "ws": "^8.18.0",
     "zod": "^4.0.0",
-    "@theokit/sdk-handoff": "0.1.0",
-    "@theokit/sdk-memory": "0.1.0"
+    "@theokit/sdk-memory": "0.1.0",
+    "@theokit/sdk-handoff": "0.1.0"
   },
   "scripts": {
     "build": "tsup && cp src/internal/providers/provider-catalog.json dist/provider-catalog.json",