@theokit/sdk 4.37.2 → 4.39.0

package/dist/skills.cjs

@@ -1,20 +1,20 @@
 'use strict';
 
-var chunkQUFSDDNU_cjs = require('./chunk-QUFSDDNU.cjs');
-require('./chunk-YBFDBOUN.cjs');
-require('./chunk-7DXLNNKH.cjs');
-require('./chunk-MHCKWQR3.cjs');
-require('./chunk-LTCOPATU.cjs');
+var chunkE4IUN3JB_cjs = require('./chunk-E4IUN3JB.cjs');
+require('./chunk-7YBJZS5P.cjs');
+require('./chunk-G2Q3ZC6C.cjs');
+require('./chunk-IHFNRNTJ.cjs');
+require('./chunk-BCQ3E2ZG.cjs');
 
 
 
 Object.defineProperty(exports, "buildSkillsBlock", {
   enumerable: true,
-  get: function () { return chunkQUFSDDNU_cjs.buildSkillsBlock; }
+  get: function () { return chunkE4IUN3JB_cjs.buildSkillsBlock; }
 });
 Object.defineProperty(exports, "discoverSkills", {
   enumerable: true,
-  get: function () { return chunkQUFSDDNU_cjs.discoverSkills; }
+  get: function () { return chunkE4IUN3JB_cjs.discoverSkills; }
 });
 //# sourceMappingURL=skills.cjs.map
 //# sourceMappingURL=skills.cjs.map

package/dist/skills.js

@@ -1,7 +1,7 @@
-export { buildSkillsBlock, discoverSkills } from './chunk-2WFB5ZOX.js';
-import './chunk-WDGCZDRG.js';
-import './chunk-UQPDFW4E.js';
-import './chunk-CD73YHEH.js';
-import './chunk-TAPQWDW2.js';
+export { buildSkillsBlock, discoverSkills } from './chunk-42IFCKQZ.js';
+import './chunk-J3UK2GMN.js';
+import './chunk-AR5MQZ3J.js';
+import './chunk-SG5ZWT6C.js';
+import './chunk-IVSD7L22.js';
 //# sourceMappingURL=skills.js.map
 //# sourceMappingURL=skills.js.map

package/dist/stream-object-4FDU76YW.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+var chunkHIQFVHC6_cjs = require('./chunk-HIQFVHC6.cjs');
+require('./chunk-FWBSDQZ7.cjs');
+require('./chunk-WJVHMTKB.cjs');
+require('./chunk-IHFNRNTJ.cjs');
+require('./chunk-BCQ3E2ZG.cjs');
+
+
+
+Object.defineProperty(exports, "StreamObjectError", {
+  enumerable: true,
+  get: function () { return chunkHIQFVHC6_cjs.StreamObjectError; }
+});
+Object.defineProperty(exports, "streamObjectImpl", {
+  enumerable: true,
+  get: function () { return chunkHIQFVHC6_cjs.streamObjectImpl; }
+});
+//# sourceMappingURL=stream-object-4FDU76YW.cjs.map
+//# sourceMappingURL=stream-object-4FDU76YW.cjs.map

package/dist/{stream-object-Y7YCX3BI.cjs.map → stream-object-4FDU76YW.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"stream-object-Y7YCX3BI.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"stream-object-4FDU76YW.cjs"}

package/dist/stream-object-HWDEEQN4.js

@@ -0,0 +1,7 @@
+export { StreamObjectError, streamObjectImpl } from './chunk-DU7DE543.js';
+import './chunk-JZUPMTJY.js';
+import './chunk-4VPXM6UU.js';
+import './chunk-SG5ZWT6C.js';
+import './chunk-IVSD7L22.js';
+//# sourceMappingURL=stream-object-HWDEEQN4.js.map
+//# sourceMappingURL=stream-object-HWDEEQN4.js.map

package/dist/{stream-object-OFM66VUT.js.map → stream-object-HWDEEQN4.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"stream-object-OFM66VUT.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"stream-object-HWDEEQN4.js"}

package/dist/subagents-loader-A4W6C3QP.cjs

@@ -0,0 +1,15 @@
+'use strict';
+
+var chunkW4WKVOOQ_cjs = require('./chunk-W4WKVOOQ.cjs');
+require('./chunk-G2Q3ZC6C.cjs');
+require('./chunk-IHFNRNTJ.cjs');
+require('./chunk-BCQ3E2ZG.cjs');
+
+
+
+Object.defineProperty(exports, "loadSubagents", {
+  enumerable: true,
+  get: function () { return chunkW4WKVOOQ_cjs.loadSubagents; }
+});
+//# sourceMappingURL=subagents-loader-A4W6C3QP.cjs.map
+//# sourceMappingURL=subagents-loader-A4W6C3QP.cjs.map

package/dist/subagents-loader-A4W6C3QP.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-A4W6C3QP.cjs"}

package/dist/subagents-loader-X33KH2SZ.js

@@ -0,0 +1,6 @@
+export { loadSubagents } from './chunk-YRXY2A5L.js';
+import './chunk-AR5MQZ3J.js';
+import './chunk-SG5ZWT6C.js';
+import './chunk-IVSD7L22.js';
+//# sourceMappingURL=subagents-loader-X33KH2SZ.js.map
+//# sourceMappingURL=subagents-loader-X33KH2SZ.js.map

package/dist/subagents-loader-X33KH2SZ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-X33KH2SZ.js"}

package/dist/subagents-loader.cjs

@@ -1,9 +1,9 @@
 'use strict';
 
-var chunkGM7QDQ24_cjs = require('./chunk-GM7QDQ24.cjs');
-require('./chunk-7DXLNNKH.cjs');
-var chunkMHCKWQR3_cjs = require('./chunk-MHCKWQR3.cjs');
-require('./chunk-LTCOPATU.cjs');
+var chunkW4WKVOOQ_cjs = require('./chunk-W4WKVOOQ.cjs');
+require('./chunk-G2Q3ZC6C.cjs');
+var chunkIHFNRNTJ_cjs = require('./chunk-IHFNRNTJ.cjs');
+require('./chunk-BCQ3E2ZG.cjs');
 
 // src/subagents-loader.ts
 var FONTES_ACEITAS = ["project"];
@@ -12,7 +12,7 @@ function resolverFontes(options) {
   if (declaradas === void 0) return FONTES_ACEITAS;
   for (const fonte of declaradas) {
     if (!FONTES_ACEITAS.includes(fonte)) {
-      throw new chunkMHCKWQR3_cjs.ConfigurationError(
+      throw new chunkIHFNRNTJ_cjs.ConfigurationError(
         `Unknown subagent setting source "${String(fonte)}" (accepted: ${FONTES_ACEITAS.join(", ")})`,
         { code: "subagent_unknown_setting_source" }
       );
@@ -22,7 +22,7 @@ function resolverFontes(options) {
 }
 async function discoverSubagents(cwd, options) {
   const fontes = resolverFontes(options);
-  return chunkGM7QDQ24_cjs.loadSubagents(cwd, fontes.includes("project"), void 0);
+  return chunkW4WKVOOQ_cjs.loadSubagents(cwd, fontes.includes("project"), void 0);
 }
 async function loadSubagentDefinition(name, cwd, options) {
   return (await discoverSubagents(cwd, options))[name];

package/dist/subagents-loader.d.cts

@@ -1,5 +1,5 @@
-import { a as AgentDefinition } from './agent-DGv1-d81.cjs';
-import './run-CwEJtLPE.cjs';
+import { a as AgentDefinition } from './agent-D7bRK9Kg.cjs';
+import './run-i2-fUohR.cjs';
 import 'zod';
 
 /**

package/dist/subagents-loader.d.ts

@@ -1,5 +1,5 @@
-import { a as AgentDefinition } from './agent-SmxntivO.js';
-import './run-CwEJtLPE.js';
+import { a as AgentDefinition } from './agent-ZCZa7YQv.js';
+import './run-i2-fUohR.js';
 import 'zod';
 
 /**

package/dist/subagents-loader.js

@@ -1,7 +1,7 @@
-import { loadSubagents } from './chunk-YCXMSDSP.js';
-import './chunk-UQPDFW4E.js';
-import { ConfigurationError } from './chunk-CD73YHEH.js';
-import './chunk-TAPQWDW2.js';
+import { loadSubagents } from './chunk-YRXY2A5L.js';
+import './chunk-AR5MQZ3J.js';
+import { ConfigurationError } from './chunk-SG5ZWT6C.js';
+import './chunk-IVSD7L22.js';
 
 // src/subagents-loader.ts
 var FONTES_ACEITAS = ["project"];

package/dist/subscription/index.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkMHCKWQR3_cjs = require('../chunk-MHCKWQR3.cjs');
-require('../chunk-LTCOPATU.cjs');
+var chunkIHFNRNTJ_cjs = require('../chunk-IHFNRNTJ.cjs');
+require('../chunk-BCQ3E2ZG.cjs');
 
 // src/subscription/define-subscription.ts
 function defineSubscription(opts) {
@@ -138,7 +138,7 @@ function tracked(id, payload) {
   }
   return [id, payload];
 }
-var SubscriptionError = class extends chunkMHCKWQR3_cjs.TheokitAgentError {
+var SubscriptionError = class extends chunkIHFNRNTJ_cjs.TheokitAgentError {
   name = "SubscriptionError";
   constructor(message, options = {}) {
     super(message, { ...options, isRetryable: false });

package/dist/subscription/index.js

@@ -1,5 +1,5 @@
-import { TheokitAgentError } from '../chunk-CD73YHEH.js';
-import '../chunk-TAPQWDW2.js';
+import { TheokitAgentError } from '../chunk-SG5ZWT6C.js';
+import '../chunk-IVSD7L22.js';
 
 // src/subscription/define-subscription.ts
 function defineSubscription(opts) {

package/dist/task-store.cjs

@@ -1,23 +1,23 @@
 'use strict';
 
-var chunkW4QN5CMG_cjs = require('./chunk-W4QN5CMG.cjs');
-require('./chunk-ICYBIC6N.cjs');
-require('./chunk-MHCKWQR3.cjs');
-require('./chunk-LTCOPATU.cjs');
+var chunkDWY25VLP_cjs = require('./chunk-DWY25VLP.cjs');
+require('./chunk-DGLLVCNB.cjs');
+require('./chunk-IHFNRNTJ.cjs');
+require('./chunk-BCQ3E2ZG.cjs');
 
 
 
 Object.defineProperty(exports, "InMemoryTaskStore", {
   enumerable: true,
-  get: function () { return chunkW4QN5CMG_cjs.InMemoryTaskStore; }
+  get: function () { return chunkDWY25VLP_cjs.InMemoryTaskStore; }
 });
 Object.defineProperty(exports, "JsonFileTaskStore", {
   enumerable: true,
-  get: function () { return chunkW4QN5CMG_cjs.JsonFileTaskStore; }
+  get: function () { return chunkDWY25VLP_cjs.JsonFileTaskStore; }
 });
 Object.defineProperty(exports, "getTaskStoreFor", {
   enumerable: true,
-  get: function () { return chunkW4QN5CMG_cjs.getTaskStoreFor; }
+  get: function () { return chunkDWY25VLP_cjs.getTaskStoreFor; }
 });
 //# sourceMappingURL=task-store.cjs.map
 //# sourceMappingURL=task-store.cjs.map

package/dist/task-store.js

@@ -1,6 +1,6 @@
-export { InMemoryTaskStore, JsonFileTaskStore, getTaskStoreFor } from './chunk-CSZRJ4RE.js';
-import './chunk-56OXYUZE.js';
-import './chunk-CD73YHEH.js';
-import './chunk-TAPQWDW2.js';
+export { InMemoryTaskStore, JsonFileTaskStore, getTaskStoreFor } from './chunk-6EEYRFJC.js';
+import './chunk-KX7JV5KM.js';
+import './chunk-SG5ZWT6C.js';
+import './chunk-IVSD7L22.js';
 //# sourceMappingURL=task-store.js.map
 //# sourceMappingURL=task-store.js.map

package/dist/types/agent-prims.d.ts

@@ -30,11 +30,11 @@ export 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;
 }

package/dist/types/agent.d.ts

@@ -337,9 +337,11 @@ export interface AgentOptions {
      *
      * `'run'` (DEFAULT, and the historical behaviour) spawns a client per `send` and drops it when the
      * run ends. `'session'` pools clients per `(agentId, server, config)` and keeps them across turns,
-     * which is what the reference does — Codex holds its connection manager in `SessionServices`
-     * (`core/src/state/service.rs:116`). Measured cost of the per-run path: 193 / 138 / 134 ms of
-     * spawn + handshake on every turn.
+     * which is what the reference does — Codex holds its MCP runtime in `SessionServices`
+     * (`codex-rs/core/src/state/service.rs:51-58`; theokit#155 corrected the earlier
+     * `core/src/state/service.rs:116`, which named a parameter of `install_mcp_runtime`, not the
+     * owning field). Measured cost of the per-run path: 193 / 138 / 134 ms of spawn + handshake on
+     * every turn.
      *
      * Opt-in rather than default because it changes the FAILURE model: a server that dies mid-session
      * becomes a reachable state. One-shot and cron runs gain nothing from pooling and would pay that
@@ -607,6 +609,69 @@ export type SDKAgentInfo = {
     env?: CloudEnv;
     repos?: string[];
 });
+/**
+ * theokit#123 — one tool of a registered agent, as a reflection surface sees it.
+ *
+ * A projection, not the `CustomTool` itself: the handler is an executable that cannot cross a
+ * process boundary and has no meaning to a caller enumerating a registry.
+ *
+ * @public
+ */
+export interface AgentToolDescription {
+    name: string;
+    description: string;
+    /** The JSON Schema sent to the model verbatim — the tool's callable signature. */
+    inputSchema: Record<string, unknown>;
+}
+/**
+ * theokit#123 — one subagent of a registered agent (what theokit-studio calls a workflow).
+ *
+ * `prompt` is deliberately absent. Enumeration asks what a subagent IS and what it may call; its
+ * system prompt is instructions, not signature, and a reflection endpoint that serializes it
+ * publishes the agent's behaviour to anyone who can reach the endpoint.
+ *
+ * @public
+ */
+export interface AgentSubagentDescription {
+    /** The key under `AgentOptions.agents` — how the parent addresses it. */
+    name: string;
+    description: string;
+    /** `"inherit"` (or absent) means it runs on the parent's model. */
+    model?: ModelSelection | "inherit";
+    /** Tool whitelist, when the subagent is scoped to a subset of the parent's tools. */
+    tools?: string[];
+}
+/**
+ * theokit#123 — the read-only introspection of a registered agent, returned by `Agent.describe()`.
+ *
+ * `Agent.list()` / `Agent.get()` enumerate agents and `agent.skills.list()` covers skills; this
+ * fills the remaining gap, so a reflection endpoint can report the live registry instead of
+ * degrading to empty lists.
+ *
+ * `tools` and `subagents` are always arrays — never `undefined` — so a caller can distinguish
+ * "this agent has none" from "the SDK did not say".
+ *
+ * @public
+ */
+export interface AgentDescription {
+    agentId: string;
+    /** Inlined rather than imported from the registry contract: `types/` stays a leaf (theokit#146). */
+    runtime: "local" | "cloud";
+    model?: ModelSelection;
+    /**
+     * The agent's DECLARED tool catalog.
+     *
+     * Plugin-contributed tools and the internal `think` tool (added when `reasoning` is on) are
+     * assembled per run and are not knowable from the registry, so they are absent here. Stated
+     * rather than implied: a reflection endpoint should not present this as the complete runtime set.
+     */
+    tools: readonly AgentToolDescription[];
+    /**
+     * Every subagent the runtime would resolve — file-based roles from `.theokit/agents/*.md` merged
+     * with the inline `agentOptions.agents`, the same set `loadSubagents` builds for a run.
+     */
+    subagents: readonly AgentSubagentDescription[];
+}
 /**
  * Options for `Agent.list()`.
  *

package/dist/types/conversation.d.ts

@@ -17,6 +17,13 @@ export interface AssistantMessage {
 export 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.

package/dist/types/goal-events.d.ts

@@ -1,22 +1,22 @@
 /**
- * M80 — os verdicts terminais que um judge pode devolver.
+ * M80 — the terminal verdicts a judge can return.
  *
- * `"blocked"` entrou aqui neste milestone. `GoalResult.status` já o carregava, mas o judge não tinha
- * como EMITI-LO: seu vocabulário era `done | continue | skipped`, então diante de um bloqueio real
- * ele só podia dizer `continue` — e o loop repetia o mesmo turno até estourar o orçamento,
- * reportando `failed` por limite em vez de `blocked` por impossibilidade. Duas causas diferentes com
- * o mesmo desfecho visível.
+ * `"blocked"` was added here in this milestone. `GoalResult.status` already carried it, but the
+ * judge had no way to EMIT it: its vocabulary was `done | continue | skipped`, so facing a real
+ * blocker it could only say `continue` — and the loop repeated the same turn until it blew the
+ * budget, reporting `failed` on a limit rather than `blocked` on impossibility. Two different causes
+ * with the same visible outcome.
  *
  * @public
  */
 export type Verdict = "done" | "continue" | "skipped" | "blocked";
 /**
- * M80 — resultado de uma chamada ao judge, agora público.
+ * M80 — the result of a judge call, now public.
  *
- * Era `internal/`, então um consumidor que quisesse tipar o retorno — para reagir a `blocked` sem
- * string mágica — precisava redeclarar a forma. É a mesma duplicação que o M78 fechou para a
- * hierarquia de erro: sem superfície pública, reimplementar é a única saída legal para quem está
- * atrás da fronteira de camadas.
+ * It was `internal/`, so a consumer wanting to type the return — to react to `blocked` without a
+ * magic string — had to redeclare the shape. It is the same duplication M78 closed for the error
+ * hierarchy: without a public surface, reimplementing is the only legal way out for anyone behind
+ * the layer boundary.
  *
  * @public
  */
@@ -24,9 +24,9 @@ export interface JudgeResult {
     verdict: Verdict;
     reason: string;
     /**
-     * `true` quando o texto não começou com um dos prefixos canônicos. O verdict vira `"continue"`
-     * (fail-safe) para não parar cedo demais; o chamador conta falhas consecutivas e desiste via
-     * `maxConsecutiveJudgeFailures`.
+     * `true` when the text did not start with one of the canonical prefixes. The verdict becomes
+     * `"continue"` (fail-safe) so the loop does not stop too early; the caller counts consecutive
+     * failures and gives up via `maxConsecutiveJudgeFailures`.
      */
     parseFailed: boolean;
 }
@@ -72,7 +72,7 @@ export type GoalEvent = {
 } | {
     type: "judge_verdict";
     turn: number;
-    /** M80 — `"blocked"` entrou: o judge pode declarar impossibilidade, não só "continue". */
+    /** M80 — `"blocked"` was added: the judge can declare impossibility, not just "continue". */
     verdict: "done" | "continue" | "skipped" | "blocked";
     reason: string;
     parseFailed: boolean;
@@ -94,7 +94,7 @@ export type GoalEvent = {
 export interface GoalResult {
     status: "completed" | "failed" | "paused" | "budget_limited" | "blocked";
     turnsUsed: number;
-    /** M55 — tokens somados ao longo do loop (0 quando `usage` esteve ausente — fail-open). */
+    /** M55 — tokens summed across the loop (0 when `usage` was absent — fail-open). */
     tokensUsed: number;
     finalResponse: string | undefined;
 }
@@ -114,9 +114,9 @@ export interface GoalOptions {
     /** Hard cap on iterations (safety net against runaway). Default `20`. */
     maxTurns?: number;
     /**
-     * M55 — token budget (Codex ext/goal parity, tool.rs:454-465). Soma `run.wait().usage.totalTokens`
-     * por turno; ao cruzar, o loop para com status `budget_limited`. Omitido ⇒ ilimitado (só maxTurns).
-     * `usage` ausente nunca estoura o budget (fail-open).
+     * M55 — token budget (Codex ext/goal parity, tool.rs:454-465). Sums `run.wait().usage.totalTokens`
+     * per turn; on crossing it, the loop stops with status `budget_limited`. Omitted => unlimited (only
+     * maxTurns). A missing `usage` never blows the budget (fail-open).
      */
     tokenBudget?: number;
     /** Bail after N consecutive judge parse failures. Default `3` (ADR D121). */
@@ -126,11 +126,12 @@ export interface GoalOptions {
     /** Override env for the judge auxiliary agent. Default `OPENROUTER_API_KEY` (EC-A). */
     judgeApiKey?: string;
     /**
-     * M80 — o modelo do agente CONDUZIDO, base da derivação do judge quando `judgeModel` é omitido.
+     * M80 — the model of the DRIVEN agent, the basis for deriving the judge when `judgeModel` is
+     * omitted.
      *
-     * Existe porque o default fixo (`openai/gpt-4o-mini`) só resolve em OpenRouter: com chave
-     * Anthropic dá 404, com bearer OAuth dá 401, e o goal queimava 3 turnos antes de falhar com razão
-     * enganosa. Um judge que roda no mesmo modelo do chat funciona onde o chat funciona.
+     * It exists because the fixed default (`openai/gpt-4o-mini`) only resolves on OpenRouter: an
+     * Anthropic key gives 404, an OAuth bearer gives 401, and the goal burned 3 turns before failing
+     * with a misleading reason. A judge running on the chat's own model works wherever chat works.
      */
     agentModel?: string;
     /** Optional subgoals fed to the judge prompt. */

package/dist/types/messages.d.ts

@@ -65,6 +65,15 @@ export 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

package/dist/types/run.d.ts

@@ -522,6 +522,21 @@ export 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
+ */
+export type RunTimelineEvent = {
+    kind: "message";
+    message: SDKMessage;
+} | {
+    kind: "delta";
+    update: import("./updates.js").InteractionUpdate;
+};
 export interface Run {
     readonly id: string;
     readonly agentId: string;
@@ -533,6 +548,18 @@ export 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. */

package/dist/types/session-message.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The shape of a persisted session turn, as a HOST reads it.
+ *
+ * Lives in `types/` because it is public contract — `Agent.transcript()` returns it (theokit#146).
+ * `internal/session/session-types.ts` re-exports it so the runtime and the store keep importing
+ * from the leaf they always did.
+ *
+ * @public
+ */
+import type { ToolResultContentBlock } from "./content-blocks.js";
+/**
+ * One turn of a session.
+ *
+ * Two projections of the same turn, and they answer different questions:
+ *
+ * - `text` is the flat rendering the model replay uses. A tool call folds to `[tool call] NAME` and
+ *   a result to `[tool result] <body>`.
+ * - `parts` is the same turn unflattened, for a host that draws tool CARDS: the call id, the tool
+ *   name, the arguments, and the `toolUseId` that ties a result back to its call — none of which
+ *   survive the flat form.
+ *
+ * `parts` was added in theokit#146 and is additive: `text` is byte-identical to what it always was,
+ * so every existing reader is untouched.
+ *
+ * @public
+ */
+export interface SessionMessage {
+    role: "user" | "assistant";
+    text: string;
+    /**
+     * The structured view. Optional because a `SessionMessage` can also be built in memory during a
+     * live turn, where only the text projection exists. Absent means "this projection carries no
+     * structure", never "this turn had none".
+     */
+    parts?: readonly SessionMessagePart[];
+}
+/**
+ * One structured element of a {@link SessionMessage}.
+ *
+ * Deliberately a session-DISPLAY shape rather than a re-export of the internal LLM part union: the
+ * two answer different questions (what to send a provider vs. what to draw), and coupling them
+ * would make every provider-wire change a change to what hosts render.
+ *
+ * @public
+ */
+export type SessionMessagePart = {
+    readonly type: "text";
+    readonly text: string;
+} | {
+    readonly type: "tool_use";
+    readonly id: string;
+    readonly name: string;
+    readonly input: Record<string, unknown>;
+} | {
+    readonly type: "tool_result";
+    readonly toolUseId: string;
+    readonly content: string | ReadonlyArray<ToolResultContentBlock>;
+    readonly isError?: boolean;
+};