@theokit/sdk 4.37.2 → 4.39.0

package/dist/{run-CwEJtLPE.d.ts → run-i2-fUohR.d.cts}

@@ -1,5 +1,174 @@
 import * as zod from 'zod';
 
+/**
+ * Type-leaf — base message types shared between `conversation.ts` and
+ * `updates.ts`. Extracted to break LOW type-only cycle #6 (audit
+ * `architecture-output/final_report.md`) per plan arch-review-fixes-2026-06-06
+ * § Phase 4 / T4.1 (D438).
+ *
+ * Public surface unchanged — `types/conversation.ts` re-exports `UserMessage`
+ * from this leaf so `import type { UserMessage } from "@theokit/sdk"` keeps
+ * resolving.
+ *
+ * @public
+ */
+/**
+ * User-authored message in a conversation history.
+ *
+ * @public
+ */
+interface UserMessage {
+    text: string;
+}
+
+/**
+ * Single tool call event. The internal `args` and `result` shapes are NOT stable.
+ *
+ * @public
+ */
+interface ToolCall {
+    callId: string;
+    name: string;
+    args?: unknown;
+    result?: unknown;
+}
+/**
+ * Incremental text token from the assistant.
+ *
+ * @public
+ */
+interface TextDeltaUpdate {
+    type: "text-delta";
+    text: string;
+}
+/**
+ * Incremental reasoning token.
+ *
+ * @public
+ */
+interface ThinkingDeltaUpdate {
+    type: "thinking-delta";
+    text: string;
+}
+/**
+ * Emitted when a reasoning block completes.
+ *
+ * @public
+ */
+interface ThinkingCompletedUpdate {
+    type: "thinking-completed";
+    thinkingDurationMs: number;
+}
+/**
+ * Tool call started — args committed.
+ *
+ * @public
+ */
+interface ToolCallStartedUpdate {
+    type: "tool-call-started";
+    callId: string;
+    toolCall: ToolCall;
+    modelCallId: string;
+}
+/**
+ * Tool call arguments streaming in incrementally.
+ *
+ * @public
+ */
+interface PartialToolCallUpdate {
+    type: "partial-tool-call";
+    callId: string;
+    toolCall: ToolCall;
+    modelCallId: string;
+}
+/**
+ * Tool call completed.
+ *
+ * @public
+ */
+interface ToolCallCompletedUpdate {
+    type: "tool-call-completed";
+    callId: string;
+    toolCall: ToolCall;
+    modelCallId: string;
+}
+/**
+ * Token count delta for usage tracking.
+ *
+ * @public
+ */
+interface TokenDeltaUpdate {
+    type: "token-delta";
+    tokens: number;
+}
+/**
+ * Conversation step started.
+ *
+ * @public
+ */
+interface StepStartedUpdate {
+    type: "step-started";
+    stepId: number;
+}
+/**
+ * Conversation step completed.
+ *
+ * @public
+ */
+interface StepCompletedUpdate {
+    type: "step-completed";
+    stepId: number;
+    stepDurationMs: number;
+}
+/**
+ * Turn ended with usage summary.
+ *
+ * @public
+ */
+interface TurnEndedUpdate {
+    type: "turn-ended";
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+    };
+}
+/**
+ * User message appended to the conversation.
+ *
+ * @public
+ */
+interface UserMessageAppendedUpdate {
+    type: "user-message-appended";
+    userMessage: UserMessage;
+}
+/** @public */
+interface SummaryUpdate {
+    type: "summary";
+    summary: string;
+}
+/** @public */
+interface SummaryStartedUpdate {
+    type: "summary-started";
+}
+/** @public */
+interface SummaryCompletedUpdate {
+    type: "summary-completed";
+}
+/** @public */
+interface ShellOutputDeltaUpdate {
+    type: "shell-output-delta";
+    event: Record<string, unknown>;
+}
+/**
+ * Lowest-level raw update from a run. Pass `onDelta` to `agent.send()` to
+ * consume these. Finer-grained than `SDKMessage` events.
+ *
+ * @public
+ */
+type InteractionUpdate = TextDeltaUpdate | ThinkingDeltaUpdate | ThinkingCompletedUpdate | ToolCallStartedUpdate | ToolCallCompletedUpdate | PartialToolCallUpdate | TokenDeltaUpdate | StepStartedUpdate | StepCompletedUpdate | TurnEndedUpdate | UserMessageAppendedUpdate | SummaryUpdate | SummaryStartedUpdate | SummaryCompletedUpdate | ShellOutputDeltaUpdate;
+
 /**
  * `PermissionEngine` — first-match permission rules for tool invocations.
  *
@@ -377,11 +546,11 @@ interface ModelSelection {
     id: string;
     params?: ModelParameterValue[];
     /**
-     * M94 — janela de contexto do modelo, em tokens. Vira o `override` do resolvedor de janela.
+     * M94 — the model's context window, in tokens. Becomes the window resolver's `override`.
      *
-     * Existe para modelos SEM entrada de catálogo: sem ela, um modelo de 400k era orçado contra o
-     * piso de 128k e compactava ~3× mais do que precisava. Um valor acima do que o catálogo conhece
-     * é clampeado — declarar 10M não estoura o provider.
+     * It exists for models with NO catalog entry: without it, a 400k model was budgeted against the
+     * 128k floor and compacted ~3x more than it needed to. A value above what the catalog knows is
+     * clamped — declaring 10M does not blow past the provider.
      */
     contextWindow?: number;
 }
@@ -448,175 +617,6 @@ interface CustomTool {
     }) => string | ToolResultContentBlock[] | Promise<string | ToolResultContentBlock[]>;
 }
 
-/**
- * Type-leaf — base message types shared between `conversation.ts` and
- * `updates.ts`. Extracted to break LOW type-only cycle #6 (audit
- * `architecture-output/final_report.md`) per plan arch-review-fixes-2026-06-06
- * § Phase 4 / T4.1 (D438).
- *
- * Public surface unchanged — `types/conversation.ts` re-exports `UserMessage`
- * from this leaf so `import type { UserMessage } from "@theokit/sdk"` keeps
- * resolving.
- *
- * @public
- */
-/**
- * User-authored message in a conversation history.
- *
- * @public
- */
-interface UserMessage {
-    text: string;
-}
-
-/**
- * Single tool call event. The internal `args` and `result` shapes are NOT stable.
- *
- * @public
- */
-interface ToolCall {
-    callId: string;
-    name: string;
-    args?: unknown;
-    result?: unknown;
-}
-/**
- * Incremental text token from the assistant.
- *
- * @public
- */
-interface TextDeltaUpdate {
-    type: "text-delta";
-    text: string;
-}
-/**
- * Incremental reasoning token.
- *
- * @public
- */
-interface ThinkingDeltaUpdate {
-    type: "thinking-delta";
-    text: string;
-}
-/**
- * Emitted when a reasoning block completes.
- *
- * @public
- */
-interface ThinkingCompletedUpdate {
-    type: "thinking-completed";
-    thinkingDurationMs: number;
-}
-/**
- * Tool call started — args committed.
- *
- * @public
- */
-interface ToolCallStartedUpdate {
-    type: "tool-call-started";
-    callId: string;
-    toolCall: ToolCall;
-    modelCallId: string;
-}
-/**
- * Tool call arguments streaming in incrementally.
- *
- * @public
- */
-interface PartialToolCallUpdate {
-    type: "partial-tool-call";
-    callId: string;
-    toolCall: ToolCall;
-    modelCallId: string;
-}
-/**
- * Tool call completed.
- *
- * @public
- */
-interface ToolCallCompletedUpdate {
-    type: "tool-call-completed";
-    callId: string;
-    toolCall: ToolCall;
-    modelCallId: string;
-}
-/**
- * Token count delta for usage tracking.
- *
- * @public
- */
-interface TokenDeltaUpdate {
-    type: "token-delta";
-    tokens: number;
-}
-/**
- * Conversation step started.
- *
- * @public
- */
-interface StepStartedUpdate {
-    type: "step-started";
-    stepId: number;
-}
-/**
- * Conversation step completed.
- *
- * @public
- */
-interface StepCompletedUpdate {
-    type: "step-completed";
-    stepId: number;
-    stepDurationMs: number;
-}
-/**
- * Turn ended with usage summary.
- *
- * @public
- */
-interface TurnEndedUpdate {
-    type: "turn-ended";
-    usage?: {
-        inputTokens: number;
-        outputTokens: number;
-        cacheReadTokens: number;
-        cacheWriteTokens: number;
-    };
-}
-/**
- * User message appended to the conversation.
- *
- * @public
- */
-interface UserMessageAppendedUpdate {
-    type: "user-message-appended";
-    userMessage: UserMessage;
-}
-/** @public */
-interface SummaryUpdate {
-    type: "summary";
-    summary: string;
-}
-/** @public */
-interface SummaryStartedUpdate {
-    type: "summary-started";
-}
-/** @public */
-interface SummaryCompletedUpdate {
-    type: "summary-completed";
-}
-/** @public */
-interface ShellOutputDeltaUpdate {
-    type: "shell-output-delta";
-    event: Record<string, unknown>;
-}
-/**
- * Lowest-level raw update from a run. Pass `onDelta` to `agent.send()` to
- * consume these. Finer-grained than `SDKMessage` events.
- *
- * @public
- */
-type InteractionUpdate = TextDeltaUpdate | ThinkingDeltaUpdate | ThinkingCompletedUpdate | ToolCallStartedUpdate | ToolCallCompletedUpdate | PartialToolCallUpdate | TokenDeltaUpdate | StepStartedUpdate | StepCompletedUpdate | TurnEndedUpdate | UserMessageAppendedUpdate | SummaryUpdate | SummaryStartedUpdate | SummaryCompletedUpdate | ShellOutputDeltaUpdate;
-
 /**
  * Plain assistant message in a conversation history.
  *
@@ -633,6 +633,13 @@ interface AssistantMessage {
 interface ThinkingMessage {
     text: string;
     thinkingDurationMs?: number;
+    /**
+     * theokit#122 — the provider's cryptographic signature for this thinking block, when it issued
+     * one. Persisted with the block so a resumed conversation can replay it byte-identically;
+     * Anthropic rejects a modified or unsigned thinking block with
+     * `400 "thinking blocks cannot be modified"`.
+     */
+    signature?: string;
 }
 /**
  * Shell command executed during a run.
@@ -885,6 +892,15 @@ interface SDKThinkingMessage {
     run_id: string;
     text: string;
     thinking_duration_ms?: number;
+    /**
+     * theokit#122 — the provider's cryptographic signature for this thinking block, when it issued
+     * one. Anthropic requires a resumed conversation to replay each thinking block WITH its
+     * signature; without it the next request fails with `400 "thinking blocks cannot be modified"`,
+     * which made an extended-thinking session unresumable.
+     *
+     * Absent for providers that stream reasoning text unsigned (the OpenAI-compatible wire).
+     */
+    signature?: string;
 }
 /**
  * Tool invocation lifecycle event. Emitted at start with `args`, then again on
@@ -1546,6 +1562,21 @@ interface CompletionCheckResult {
  *
  * @public
  */
+/**
+ * theokit#140 - one element of {@link Run.events}: either a structural SDK message or a live delta.
+ *
+ * A discriminated union rather than a widened `SDKMessage`, because a token delta is not a message
+ * and pretending otherwise would force every consumer to guess which of the two it is holding.
+ *
+ * @public
+ */
+type RunTimelineEvent = {
+    kind: "message";
+    message: SDKMessage;
+} | {
+    kind: "delta";
+    update: InteractionUpdate;
+};
 interface Run {
     readonly id: string;
     readonly agentId: string;
@@ -1557,6 +1588,18 @@ interface Run {
     readonly createdAt?: number;
     /** AsyncGenerator of normalized stream events. Discriminate on `event.type`. */
     stream(): AsyncGenerator<SDKMessage, void>;
+    /**
+     * theokit#140 - every event of this run in TRUE order, from one source: structural messages and
+     * live token/tool deltas interleaved as they occurred.
+     *
+     * Use this instead of fusing `stream()` with `SendOptions.onDelta` by hand. Neither of those is
+     * complete alone - `onDelta` carries no `run_started`/`system`, `stream()` carries no token
+     * granularity - and reconciling them in the consumer is what produced the ordering and dedup
+     * bugs this replaces.
+     *
+     * `stream()` is unchanged and remains the SDKMessage-only view.
+     */
+    events(): AsyncGenerator<RunTimelineEvent, void>;
     /** Resolves to the terminal {@link RunResult}. */
     wait(): Promise<RunResult>;
     /** Move status to `"cancelled"`, abort the stream, stop in-flight tool calls. */
@@ -1613,4 +1656,4 @@ interface GenerateRunResult<O> {
     };
 }
 
-export { type RunToCompletionResult as $, type AgentConversationTurn as A, type ProcessorControls as B, type CustomTool as C, type DoomLoopThresholds as D, type ProcessorTripwire as E, type ProcessorViolation as F, type GenerateOptions as G, type RunCompactBoundaryEvent as H, type ImageBlock as I, type RunCompletionCheckEvent as J, type RunErrorDetail as K, type RunEvent as L, type ModelSelection as M, type RunGitInfo as N, type OutputProcessorContext as O, type Processor as P, type RunOperation as Q, type RunResult as R, type SDKMessage as S, type ToolResultContentBlock as T, type RunPermissionDeniedEvent as U, type RunRateLimitEvent as V, type RunStatus as W, type RunTaskCompletedEvent as X, type RunTaskStartedEvent as Y, type RunTaskUpdatedEvent as Z, type RunToCompletionOptions as _, type McpServerConfig as a, type RunToolProgressEvent as a0, type RunTripwireEvent as a1, type SDKAssistantMessage as a2, type SDKImage as a3, type SDKImageDimension as a4, type SDKObjectDelta as a5, type SDKRequestMessage as a6, type SDKStatusMessage as a7, type SDKSystemMessage as a8, type SDKTaskMessage as a9, type ToolResult as aA, type ToolResultGuardOptions as aB, type ToolUseBlock as aC, type TurnEndedUpdate as aD, type UserMessage as aE, type UserMessageAppendedUpdate as aF, applyMode as aG, emitRunEvent as aH, type SDKThinkingMessage as aa, type SDKToolUseMessage as ab, type SDKUserMessage as ac, type SDKUserMessageEvent as ad, type SendOptions as ae, type ShellCommand as af, type ShellConversationTurn as ag, type ShellOutput as ah, type ShellOutputDeltaUpdate as ai, type StepCompletedUpdate as aj, type StepStartedUpdate as ak, type StreamToCompletionResult as al, type SummaryCompletedUpdate as am, type SummaryStartedUpdate as an, type SummaryUpdate as ao, type TextBlock as ap, type TextDeltaUpdate as aq, type ThinkingCompletedUpdate as ar, type ThinkingDeltaUpdate as as, type ThinkingMessage as at, type TokenDeltaUpdate as au, type TokenUsage as av, type ToolCall as aw, type ToolCallCompletedUpdate as ax, type ToolCallStartedUpdate as ay, type ToolContextMessage as az, type Run as b, type PermissionMode as c, PermissionEngine as d, type RunEventSink as e, type AssistantMessage as f, type CompletionCheck as g, type CompletionCheckResult as h, type ConversationStep as i, type ConversationTurn as j, type CostBreakdown as k, type CostSource as l, type CostStatus as m, type GenerateRunResult as n, type InputProcessorContext as o, type InteractionUpdate as p, type McpAuthConfig as q, type McpHttpServerConfig as r, type McpOAuthConfig as s, type McpStdioServerConfig as t, type MessageOrigin as u, type ModelParameterValue as v, type PartialToolCallUpdate as w, type PermissionAction as x, type PermissionEngineOptions as y, type PermissionRule as z };
+export { type RunToCompletionOptions as $, type AgentConversationTurn as A, type ProcessorControls as B, type CustomTool as C, type DoomLoopThresholds as D, type ProcessorTripwire as E, type ProcessorViolation as F, type GenerateOptions as G, type RunCompactBoundaryEvent as H, type ImageBlock as I, type RunCompletionCheckEvent as J, type RunErrorDetail as K, type RunEvent as L, type ModelSelection as M, type RunGitInfo as N, type OutputProcessorContext as O, type Processor as P, type RunOperation as Q, type RunResult as R, type SDKMessage as S, type ToolResultContentBlock as T, type RunPermissionDeniedEvent as U, type RunRateLimitEvent as V, type RunStatus as W, type RunTaskCompletedEvent as X, type RunTaskStartedEvent as Y, type RunTaskUpdatedEvent as Z, type RunTimelineEvent as _, type McpServerConfig as a, type RunToCompletionResult as a0, type RunToolProgressEvent as a1, type RunTripwireEvent as a2, type SDKAssistantMessage as a3, type SDKImage as a4, type SDKImageDimension as a5, type SDKObjectDelta as a6, type SDKRequestMessage as a7, type SDKStatusMessage as a8, type SDKSystemMessage as a9, type ToolContextMessage as aA, type ToolResult as aB, type ToolResultGuardOptions as aC, type ToolUseBlock as aD, type TurnEndedUpdate as aE, type UserMessage as aF, type UserMessageAppendedUpdate as aG, applyMode as aH, emitRunEvent as aI, type SDKTaskMessage as aa, type SDKThinkingMessage as ab, type SDKToolUseMessage as ac, type SDKUserMessage as ad, type SDKUserMessageEvent as ae, type SendOptions as af, type ShellCommand as ag, type ShellConversationTurn as ah, type ShellOutput as ai, type ShellOutputDeltaUpdate as aj, type StepCompletedUpdate as ak, type StepStartedUpdate as al, type StreamToCompletionResult as am, type SummaryCompletedUpdate as an, type SummaryStartedUpdate as ao, type SummaryUpdate as ap, type TextBlock as aq, type TextDeltaUpdate as ar, type ThinkingCompletedUpdate as as, type ThinkingDeltaUpdate as at, type ThinkingMessage as au, type TokenDeltaUpdate as av, type TokenUsage as aw, type ToolCall as ax, type ToolCallCompletedUpdate as ay, type ToolCallStartedUpdate as az, type Run as b, type PermissionMode as c, PermissionEngine as d, type RunEventSink as e, type AssistantMessage as f, type CompletionCheck as g, type CompletionCheckResult as h, type ConversationStep as i, type ConversationTurn as j, type CostBreakdown as k, type CostSource as l, type CostStatus as m, type GenerateRunResult as n, type InputProcessorContext as o, type InteractionUpdate as p, type McpAuthConfig as q, type McpHttpServerConfig as r, type McpOAuthConfig as s, type McpStdioServerConfig as t, type MessageOrigin as u, type ModelParameterValue as v, type PartialToolCallUpdate as w, type PermissionAction as x, type PermissionEngineOptions as y, type PermissionRule as z };