@theokit/sdk 2.6.0 → 2.7.0

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

@@ -0,0 +1,31 @@
+/**
+ * `streamToCompletion` — the STREAMING continuation driver (V3-4, plan
+ * v34-stream-to-completion). The streaming twin of `runToCompletion`: it yields
+ * each round's `SDKMessage`s LIVE (the V3-4 (a) gap a UI needs) while reusing the
+ * SAME terminal policy as the M1 driver — `classifyRound` (done / step_limit /
+ * no_progress) + bounded re-prompt + `addUsage` aggregation. It is NOT a second
+ * policy (D1): the only difference from `runToCompletion` is surfacing events over
+ * `Run.stream()` instead of returning only the final `Run.wait()` result.
+ *
+ * Stateful, like `runToCompletion` (the agent's session preserves history; the
+ * continuation prompt is short). The STATELESS path stays `buildReplayHistory`
+ * (D2) — a consumer reconstructs history into a fresh session, then drives this.
+ *
+ * The `StreamToCompletionResult` is the generator's RETURN value, read via a
+ * manual `gen.next()` loop (`while (!res.done) res = await gen.next()` → `res.value`).
+ * A plain `for await...of` consumes the yielded messages but discards the return
+ * value (EC-1) — see docs.md.
+ *
+ * @internal
+ */
+import type { RunResult, SendOptions } from "../../../types/run.js";
+/** One streamed round handle: drain `stream()` (live events) then `wait()` (terminal result). */
+interface StreamRun {
+    stream(): AsyncGenerator<SDKMessage, void>;
+    wait(): Promise<RunResult>;
+}
+/** Minimal agent port the streaming driver needs — the instance `.send()` surface. */
+export interface StreamToCompletionAgent {
+    send(message: string, options?: SendOptions): Promise<StreamRun>;
+}
+export {};

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

@@ -625,7 +625,7 @@ type RunStatus = "running" | "finished" | "error" | "cancelled";
  *
  * @public
  */
-type RunOperation = "stream" | "wait" | "cancel" | "conversation" | "listArtifacts" | "downloadArtifact" | "runUntil" | "runToCompletion" | "fork" | "usePersonality" | "workflow";
+type RunOperation = "stream" | "wait" | "cancel" | "conversation" | "listArtifacts" | "downloadArtifact" | "runUntil" | "runToCompletion" | "streamToCompletion" | "fork" | "usePersonality" | "workflow";
 /**
  * Git metadata attached to cloud runs.
  *
@@ -741,6 +741,15 @@ interface RunToCompletionResult {
     /** Token usage summed across all rounds; `undefined` when no round reported usage. */
     usage?: TokenUsage;
 }
+/**
+ * Result of {@link SDKAgent.streamToCompletion} (V3-4 — the STREAMING continuation
+ * driver). Same shape + terminal semantics as {@link RunToCompletionResult}; it is
+ * the generator's RETURN value (read it via a manual `gen.next()` loop — a plain
+ * `for await...of` consumes the yielded `SDKMessage`s but discards this return value).
+ *
+ * @public
+ */
+type StreamToCompletionResult = RunToCompletionResult;
 /**
  * Structured error attached to a {@link RunResult} when the underlying run
  * transitioned to `"error"` status. `message` is always present; `code` is
@@ -893,4 +902,4 @@ interface Run {
     onDidChangeStatus(listener: (status: RunStatus) => void): () => void;
 }
 
-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 };
+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 };

package/dist/{run-BPRYG1Id.d.ts → run-D22b53SU.d.ts}

@@ -625,7 +625,7 @@ type RunStatus = "running" | "finished" | "error" | "cancelled";
  *
  * @public
  */
-type RunOperation = "stream" | "wait" | "cancel" | "conversation" | "listArtifacts" | "downloadArtifact" | "runUntil" | "runToCompletion" | "fork" | "usePersonality" | "workflow";
+type RunOperation = "stream" | "wait" | "cancel" | "conversation" | "listArtifacts" | "downloadArtifact" | "runUntil" | "runToCompletion" | "streamToCompletion" | "fork" | "usePersonality" | "workflow";
 /**
  * Git metadata attached to cloud runs.
  *
@@ -741,6 +741,15 @@ interface RunToCompletionResult {
     /** Token usage summed across all rounds; `undefined` when no round reported usage. */
     usage?: TokenUsage;
 }
+/**
+ * Result of {@link SDKAgent.streamToCompletion} (V3-4 — the STREAMING continuation
+ * driver). Same shape + terminal semantics as {@link RunToCompletionResult}; it is
+ * the generator's RETURN value (read it via a manual `gen.next()` loop — a plain
+ * `for await...of` consumes the yielded `SDKMessage`s but discards this return value).
+ *
+ * @public
+ */
+type StreamToCompletionResult = RunToCompletionResult;
 /**
  * Structured error attached to a {@link RunResult} when the underlying run
  * transitioned to `"error"` status. `message` is always present; `code` is
@@ -893,4 +902,4 @@ interface Run {
     onDidChangeStatus(listener: (status: RunStatus) => void): () => void;
 }
 
-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 };
+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 };

package/dist/types/agent.d.ts

@@ -630,6 +630,24 @@ export interface SDKAgent {
      * @public
      */
     runToCompletion?(message: string, options?: import("./run.js").RunToCompletionOptions): Promise<import("./run.js").RunToCompletionResult>;
+    /**
+     * STREAMING continuation driver (V3-4) — the streaming twin of
+     * {@link SDKAgent.runToCompletion}. Returns an `AsyncGenerator` that yields each
+     * round's {@link import("./messages.js").SDKMessage}s LIVE (for a UI), reusing the
+     * same terminal policy (`done`/`step_limit`/`no_progress` + bounded re-prompt).
+     *
+     * The {@link import("./run.js").StreamToCompletionResult} is the generator's RETURN
+     * value — read it via a manual `gen.next()` loop (`while (!res.done) res = await
+     * gen.next()` → `res.value`); a plain `for await...of` consumes the yielded
+     * messages but discards the return value. For the STATELESS path, reconstruct
+     * history with `buildReplayHistory` into a fresh session first.
+     *
+     * Local agents only. Cloud agents throw
+     * {@link import("../errors.js").UnsupportedRunOperationError}.
+     *
+     * @public
+     */
+    streamToCompletion?(message: string, options?: import("./run.js").RunToCompletionOptions): AsyncGenerator<import("./messages.js").SDKMessage, import("./run.js").StreamToCompletionResult>;
     /**
      * Direct API to third-party memory adapter(s) registered via
      * `plugins: [...]` (ADR D141 / D142). Returns `null` when no adapter

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" | "runToCompletion" | "fork" | "usePersonality" | "workflow";
+export type RunOperation = "stream" | "wait" | "cancel" | "conversation" | "listArtifacts" | "downloadArtifact" | "runUntil" | "runToCompletion" | "streamToCompletion" | "fork" | "usePersonality" | "workflow";
 /**
  * Git metadata attached to cloud runs.
  *
@@ -135,6 +135,15 @@ export interface RunToCompletionResult {
     /** Token usage summed across all rounds; `undefined` when no round reported usage. */
     usage?: TokenUsage;
 }
+/**
+ * Result of {@link SDKAgent.streamToCompletion} (V3-4 — the STREAMING continuation
+ * driver). Same shape + terminal semantics as {@link RunToCompletionResult}; it is
+ * the generator's RETURN value (read it via a manual `gen.next()` loop — a plain
+ * `for await...of` consumes the yielded `SDKMessage`s but discards this return value).
+ *
+ * @public
+ */
+export type StreamToCompletionResult = RunToCompletionResult;
 /**
  * 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.6.0",
+  "version": "2.7.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",
@@ -298,6 +298,15 @@
     "**/agent.js",
     "**/agent.cjs"
   ],
+  "scripts": {
+    "build": "tsup && cp src/internal/providers/provider-catalog.json dist/provider-catalog.json",
+    "test": "vitest run --no-file-parallelism",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "docs:json": "typedoc --options typedoc.json",
+    "docs:drift": "tsx scripts/check-docs-drift.ts"
+  },
   "peerDependencies": {
     "@lancedb/lancedb": "^0.30.0",
     "@types/ws": ">=8.0.0",
@@ -354,6 +363,8 @@
   "devDependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/sdk-trace-base": "^1.30.1",
+    "@theokit/sdk-handoff": "workspace:*",
+    "@theokit/sdk-memory": "workspace:*",
     "@types/better-sqlite3": "^7.6.13",
     "@types/proper-lockfile": "^4.1.4",
     "@types/ws": "^8.18.0",
@@ -363,17 +374,6 @@
     "sqlite-vec": "^0.1.9",
     "typedoc": "^0.28.19",
     "ws": "^8.18.0",
-    "zod": "^4.0.0",
-    "@theokit/sdk-handoff": "0.1.0",
-    "@theokit/sdk-memory": "0.2.0"
-  },
-  "scripts": {
-    "build": "tsup && cp src/internal/providers/provider-catalog.json dist/provider-catalog.json",
-    "test": "vitest run --no-file-parallelism",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist",
-    "docs:json": "typedoc --options typedoc.json",
-    "docs:drift": "tsx scripts/check-docs-drift.ts"
+    "zod": "^4.0.0"
   }
-}
+}