@theokit/sdk 2.2.0 → 2.3.0

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-ekGKZlmg.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.
  *
@@ -688,6 +688,59 @@ interface RunResult {
      */
     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
  * transitioned to `"error"` status. `message` is always present; `code` is
@@ -840,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-ekGKZlmg.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.
  *
@@ -688,6 +688,59 @@ interface RunResult {
      */
     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
  * transitioned to `"error"` status. `message` is always present; `code` is
@@ -840,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.
  *
@@ -82,6 +82,59 @@ export interface RunResult {
      */
     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
  * transitioned to `"error"` status. `message` is always present; `code` is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "2.2.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",