@theokit/sdk 4.37.2 → 4.39.0

package/dist/{chunk-VYJSHGAY.js → chunk-GIRD3RWH.js}

@@ -1,32 +1,33 @@
 import { extractCodePlugins } from './chunk-2SFBB54R.js';
-import { submit, emitRunEvent } from './chunk-HEN5WXXI.js';
-import { enqueueSessionWrite, hydrateSession, persistTurnToTranscript, flushSessionWrites, appendSessionMessage, getSessionMessages, descartarSessao, clearSession } from './chunk-5SB4V74H.js';
-import { FsSessionStore } from './chunk-YVTNFKZO.js';
-import { discoverProviderPlugins, getConfiguredBaseUrl, httpRequest, isFixtureApiKey, shouldUseRealLocalRuntime, CircuitBreaker, buildDefaultSummarizer, parseSseStream, resolveProviderChain, inferProviderFromApiKey, detectPrimaryProvider, tryFirstEvent, relayStream, mapOpenAICompatibleError, renderToolResultContentText } from './chunk-GL7CFBVC.js';
-import { IndexManager, writeSessionSummary, memoryDir, globalEmbeddingCache, appendFact, readFacts, legacyMemoryJsonPath, memoryMdPath, appendFactToMarkdown } from './chunk-DCJ5MCJ3.js';
-import { loadHookConfig, warnOnce, currentPersonalityContext, warnPersonalitySwitchInsideFork } from './chunk-F6Y4IEQM.js';
+import { submit, emitRunEvent } from './chunk-LJX2SQV2.js';
+import { enqueueSessionWrite, hydrateSession, persistTurnToTranscript, flushSessionWrites, appendSessionMessage, getSessionMessages, discardSession, clearSession } from './chunk-E2FFG33C.js';
+import { FsSessionStore } from './chunk-KGRIHEDT.js';
+import { discoverProviderPlugins, getConfiguredBaseUrl, httpRequest, isFixtureApiKey, shouldUseRealLocalRuntime, CircuitBreaker, buildDefaultSummarizer, parseSseStream, resolveProviderChain, inferProviderFromApiKey, detectPrimaryProvider, tryFirstEvent, relayStream, renderToolResultContentText } from './chunk-ZYB6B7QJ.js';
+import { IndexManager, writeSessionSummary, memoryDir, appendFact, readFacts, legacyMemoryJsonPath, memoryMdPath, appendFactToMarkdown } from './chunk-4F7JQZOX.js';
+import { loadHookConfig, warnOnce, currentPersonalityContext, warnPersonalitySwitchInsideFork } from './chunk-ML5A5DOJ.js';
 import { resolveChildEnv } from './chunk-7GFX45DD.js';
-import { readVersionedJson, getTheokitHome, writeVersionedJson } from './chunk-ZW345YOI.js';
+import { readVersionedJson, getTheokitHome, writeVersionedJson } from './chunk-YP67XZES.js';
+import { createOpenAiCompatibleRuntime } from './chunk-QKE556YD.js';
 import { sanitizeToolInput } from './chunk-U54XCYG3.js';
-import { subAgentToolsFromDefinitions, inheritSubAgentCredentials } from './chunk-FV3YEMQ7.js';
+import { withInheritedSubAgentCredentials, subAgentToolsFromDefinitions } from './chunk-RP5HQVLD.js';
 import { setAgentFacade } from './chunk-6X6ID4MO.js';
 import { findGitRoot, DEFAULT_DISCOVERY_SPECS, walkUpForFile, walkUpForGlob } from './chunk-UJ7IQJAG.js';
 import { withToolWhitelist, checkToolWhitelist } from './chunk-7AD3ZTZL.js';
-import { mapWithConcurrency } from './chunk-QGDKZDPN.js';
-import { withFileLock } from './chunk-YHZXBDAW.js';
+import { mapWithConcurrency } from './chunk-LGILIGV3.js';
+import { defaultBaseDir, expandTilde } from './chunk-JRLXEYR4.js';
+import { withFileLock } from './chunk-BQDUEG4C.js';
 import { withCwdMutex } from './chunk-2XLKLVVR.js';
-import { defaultBaseDir, expandTilde } from './chunk-XAEAMI5H.js';
 import { toJsonSchema } from './chunk-4VPXM6UU.js';
-import { atomicWriteJson } from './chunk-56OXYUZE.js';
-import { loadSubagents } from './chunk-YCXMSDSP.js';
-import { resolveEffectiveContextWindow, CONTEXT_WINDOW_FLOOR, CONTEXT_WINDOW_MARGIN } from './chunk-6VP3XGEK.js';
+import { atomicWriteJson } from './chunk-KX7JV5KM.js';
+import { loadSubagents } from './chunk-YRXY2A5L.js';
+import { resolveEffectiveContextWindow, CONTEXT_WINDOW_FLOOR, CONTEXT_WINDOW_MARGIN } from './chunk-65ONFZWM.js';
 import { parseModelId } from './chunk-X2FR4OIT.js';
-import { getCatalogModelInfo, registerBuiltins, getProviderProfile, registerProvider, isPatchedModelKey } from './chunk-77WHPVXE.js';
-import { escapeBlockBody, buildSkillsBlock, discoverSkills, stripSkillFrontmatter } from './chunk-2WFB5ZOX.js';
-import { validateArtifactPath, PathTraversalError, safePathJoin } from './chunk-WDGCZDRG.js';
-import { readWorkspaceDir, parseSimpleYaml } from './chunk-UQPDFW4E.js';
-import { AgentRunError, coerceToKnownAgentRunErrorCode, UnknownAgentError, ConfigurationError, AuthenticationError, UnsupportedRunOperationError, AgentDisposedError, NetworkError, TheokitAgentError } from './chunk-CD73YHEH.js';
-import { diag, redactSecrets } from './chunk-TAPQWDW2.js';
+import { getCatalogModelInfo, registerBuiltins, getProviderProfile, registerProvider, isPatchedModelKey } from './chunk-TOTP24P6.js';
+import { escapeBlockBody, buildSkillsBlock, discoverSkills, stripSkillFrontmatter } from './chunk-42IFCKQZ.js';
+import { validateArtifactPath, PathTraversalError, safePathJoin } from './chunk-J3UK2GMN.js';
+import { readWorkspaceDir, parseSimpleYaml } from './chunk-AR5MQZ3J.js';
+import { AgentRunError, coerceToKnownAgentRunErrorCode, UnknownAgentError, ConfigurationError, AuthenticationError, UnsupportedRunOperationError, AgentDisposedError, NetworkError, TheokitAgentError } from './chunk-SG5ZWT6C.js';
+import { diag, redactSecrets } from './chunk-IVSD7L22.js';
 import { stat, mkdir, readFile, readdir, access, unlink } from 'fs/promises';
 import { randomUUID, createHash } from 'crypto';
 import { join, dirname, resolve, relative, isAbsolute } from 'path';
@@ -221,7 +222,7 @@ async function agentGenerate(agent, agentModel, agentApiKey, agentLocal, input,
   const { output, maxRetries, errorStrategy, ...sendOptions } = options;
   const run = await agent.send(input, sendOptions);
   const result = await run.wait();
-  const { generateObjectImpl, GenerateObjectError } = await import('./generate-object-I7UD4NWN.js');
+  const { generateObjectImpl, GenerateObjectError } = await import('./generate-object-XDCBYVK3.js');
   const answer = structurableAnswerOrThrow(result, GenerateObjectError);
   const { getAgentFacade } = await import('./agent-factory-registry-ZVTABLEY.js');
   const facade = getAgentFacade();
@@ -1320,6 +1321,16 @@ var FixtureRunBase = class {
   resolveTermination;
   terminated = false;
   eventNotifier;
+  /**
+   * theokit#140 - the run's single ordered timeline: structural events and live token/tool deltas,
+   * in the order they actually occurred.
+   *
+   * Kept alongside `script.events` rather than replacing it. `stream()` is the SDKMessage view and
+   * stays byte-identical for every existing consumer; this is the complete view, and a consumer
+   * picks one. Merging them would have changed `stream()`'s element type - a breaking change for
+   * an additive feature.
+   */
+  timeline = [];
   constructor(options) {
     this.id = options.id;
     this.agentId = options.agentId;
@@ -1343,6 +1354,46 @@ var FixtureRunBase = class {
     this.eventNotifier = makeNotifier();
     current.resolve();
   }
+  /**
+   * theokit#140 - every event of this run, in true order, from ONE source.
+   *
+   * ## The defect this replaces
+   *
+   * A consumer that needed tool calls interleaved with tokens had to fuse two surfaces by hand:
+   * `stream()`, which was batched and post-completion, and `SendOptions.onDelta`, which was live.
+   * Neither was complete alone - `onDelta` has no `run_started`/`system`, and `stream()` had no
+   * token granularity - so the entire reconciliation, including its dedup, lived in the consumer.
+   * `@theokit/agents` carried ~200 lines of exactly that, and it is the documented root of its
+   * ordering bug (theokit#47), its namespace-dedup bug (#138) and its missing terminal frame (#142).
+   *
+   * The ordering is not reconstructed here. Both kinds are appended by the loop AS THEY HAPPEN, so
+   * arrival order IS model order - there is nothing to sort, and no timestamp heuristic to get
+   * wrong.
+   *
+   * `callId` is whatever the SDK's own `tool_call` events carry, so a consumer no longer holds two
+   * id namespaces and no longer has to correlate them.
+   */
+  async *events() {
+    let index = 0;
+    while (!this.terminated) {
+      while (index < this.timeline.length) {
+        yield this.timeline[index++];
+      }
+      if (this.terminated) break;
+      await Promise.race([this.eventNotifier.promise, this.terminationPromise]);
+    }
+    while (index < this.timeline.length) {
+      yield this.timeline[index++];
+    }
+    for await (const message of this.terminalErrorEvent()) {
+      yield { kind: "message", message };
+    }
+  }
+  /** theokit#140 - append to the timeline and wake `events()`. */
+  pushTimeline(event) {
+    this.timeline.push(event);
+    this.notifyNewEvents();
+  }
   async *stream() {
     let index = 0;
     while (!this.terminated) {
@@ -1358,22 +1409,22 @@ var FixtureRunBase = class {
     yield* this.terminalErrorEvent();
   }
   /**
-   * theokit#101 — quando o run termina em erro, `stream()` tem de DIZER.
+   * theokit#101 — when the run ends in error, `stream()` has to SAY SO.
    *
-   * O erro sempre existiu: o loop o registra em `ctx.error` e `wait()` devolve
-   * `status: 'error'` com a mensagem. Só o `stream()` não o mencionava — ele drena
-   * `script.events` e para. Uma falha de provider (404 "No endpoints found", auth, timeout)
-   * produzia um turno que parecia bem-sucedido e vazio, em TODA superfície que consome o
+   * The error always existed: the loop records it in `ctx.error` and `wait()` returns
+   * `status: 'error'` with the message. Only `stream()` failed to mention it — it drains
+   * `script.events` and stops. A provider failure (404 "No endpoints found", auth, timeout)
+   * produced a turn that looked successful and empty, on EVERY surface consuming the
    * stream: HTTP web, MCP, stdio, TUI in-process.
    *
-   * Erro silencioso é o pior tipo (Regra Inquebrável 8). E a assimetria era o que o tornava
-   * difícil de diagnosticar: quem depurasse por `wait()` via o erro e não reproduziria o
-   * relato de quem depurava pelo stream.
+   * A silent error is the worst kind (Unbreakable Rule 8). And the asymmetry was what made it
+   * hard to diagnose: anyone debugging via `wait()` saw the error and would not reproduce the
+   * report of anyone debugging via the stream.
    *
-   * Emite `SDKStatusMessage` com `status: "ERROR"` — o tipo JÁ EXISTE na união `SDKMessage`
-   * e já é esperado por quem consome. Um tipo novo seria breaking para todo consumidor que
-   * faz switch exaustivo; este é aditivo, e um consumidor que ignore `status` simplesmente
-   * segue como antes — nunca pior que hoje.
+   * It emits `SDKStatusMessage` with `status: "ERROR"` — the type ALREADY EXISTS in the `SDKMessage` union
+   * and is already expected by consumers. A new type would be breaking for every consumer doing
+   * an exhaustive switch; this one is additive, and a consumer ignoring `status` simply
+   * behaves as before — never worse than today.
    */
   *terminalErrorEvent() {
     if (this.status !== "error") return;
@@ -1383,7 +1434,7 @@ var FixtureRunBase = class {
       agent_id: this.agentId,
       run_id: this.id,
       status: "ERROR",
-      // Sem mensagem, o consumidor sabe QUE falhou e não O QUÊ — que é metade do defeito.
+      // Without a message, the consumer knows THAT it failed and not WHAT — which is half the defect.
       ...detail?.message !== void 0 ? { message: detail.message } : {}
     };
   }
@@ -2643,7 +2694,7 @@ async function runPostRunLifecycle(inputs) {
   }
   const conversation = await safeConversation(run);
   const resolvedWindow = resolveWindowForRun(model, contextWindow);
-  const janelaEfetiva = resolvedWindow.window;
+  const effectiveWindow = resolvedWindow.window;
   const budgetEvent = buildContextBudgetEvent(model, resolvedWindow);
   if (budgetEvent !== void 0 && onRunEvent !== void 0) {
     emitRunEvent(onRunEvent, budgetEvent);
@@ -2659,9 +2710,9 @@ async function runPostRunLifecycle(inputs) {
       conversation,
       autoCompact: {
         usageTotal: usageForTrigger,
-        // A janela EFETIVA (após override, clamp e margem) — não a declarada. Trocar por
-        // `contextWindow` aqui orçaria contra um número que o clamp já rejeitou.
-        contextWindow: janelaEfetiva,
+        // The EFFECTIVE window (after override, clamp and margin) — not the declared one. Swapping for
+        // `contextWindow` here would budget against a number the clamp already rejected.
+        contextWindow: effectiveWindow,
         summarize: buildDefaultSummarizer({
           agentModel: model,
           ...inputs.apiKey !== void 0 ? { apiKey: inputs.apiKey } : {}
@@ -4939,6 +4990,35 @@ var UsageAccumulator = class {
   }
 };
 
+// src/internal/agent-loop/live-events.ts
+var LiveEventLog = class extends Array {
+  /**
+   * Not readonly, and not a constructor parameter — `Array` subclasses are re-instantiated by
+   * `map`/`filter`/`slice` with a length argument, so a constructor with a different signature
+   * breaks those. The sink is attached after construction instead.
+   */
+  #sink;
+  /** Attach the live subscriber. One sink: the run that owns this loop. */
+  subscribe(sink) {
+    this.#sink = sink;
+  }
+  push(...events) {
+    const length = super.push(...events);
+    for (const event of events) {
+      try {
+        this.#sink?.(event);
+      } catch {
+      }
+    }
+    return length;
+  }
+};
+function createEventLog(seed) {
+  const log = new LiveEventLog();
+  log.push(...seed);
+  return log;
+}
+
 // src/internal/agent-loop/message-builders.ts
 function buildSystemEvent(inputs, toolNames) {
   return {
@@ -4966,7 +5046,7 @@ function buildAssistantEvent(inputs, text) {
     message: { role: "assistant", content: [{ type: "text", text }] }
   };
 }
-function buildThinkingEvent(inputs, text, thinkingDurationMs) {
+function buildThinkingEvent(inputs, text, thinkingDurationMs, signature) {
   const event = {
     type: "thinking",
     agent_id: inputs.agentId,
@@ -4976,10 +5056,12 @@ function buildThinkingEvent(inputs, text, thinkingDurationMs) {
   if (thinkingDurationMs !== void 0 && thinkingDurationMs >= 0) {
     event.thinking_duration_ms = thinkingDurationMs;
   }
+  if (signature !== void 0) event.signature = signature;
   return event;
 }
-function buildAssistantTurn(text, toolCalls) {
+function buildAssistantTurn(text, toolCalls, thinking) {
   const content = [];
+  if (thinking !== void 0) content.push(thinking);
   if (text.length > 0) content.push({ type: "text", text });
   for (const call of toolCalls) content.push(call);
   return { role: "assistant", content };
@@ -5048,13 +5130,14 @@ async function initLoopContext(inputs) {
       });
     }
   }
-  const events = [
+  const events = createEventLog([
     buildSystemEvent(
       inputs,
       tools.map((t) => t.name)
     ),
     buildUserEvent(inputs)
-  ];
+  ]);
+  if (inputs.onLoopEvent !== void 0) events.subscribe(inputs.onLoopEvent);
   const priorMessages = (inputs.priorMessages ?? []).map((msg) => ({
     role: msg.role,
     content: [{ type: "text", text: msg.text }]
@@ -5233,6 +5316,7 @@ async function streamLlmTurn(inputs, ctx) {
   emitLlmMetrics(inputs, result, startAt);
   llmSpan?.end();
   const stripped = stripThinkBlocks(collected.accumulatedText);
+  const thinking = result.thinking ?? collected.thinking;
   return {
     text: stripped.visible,
     toolCalls: result.toolCalls,
@@ -5242,18 +5326,21 @@ async function streamLlmTurn(inputs, ctx) {
     outputTokens: result.outputTokens,
     cacheReadTokens: result.cacheReadTokens,
     cacheWriteTokens: result.cacheWriteTokens,
-    reasoningTokens: result.reasoningTokens
+    reasoningTokens: result.reasoningTokens,
+    ...thinking !== void 0 ? { thinking } : {}
   };
 }
 async function collectLlmEvents(generator, inputs, ctx) {
   let accumulatedText = "";
   let errored = false;
   let finishValue;
+  let thinking;
   try {
     const result = await runCollectorLoop(generator, inputs, ctx);
     accumulatedText = result.accumulatedText;
     errored = result.errored;
     finishValue = result.finishValue;
+    thinking = result.thinking;
   } catch (cause) {
     if (inputs.signal?.aborted === true) {
       ctx.finalText = "[aborted]";
@@ -5264,7 +5351,12 @@ async function collectLlmEvents(generator, inputs, ctx) {
     }
     errored = true;
   }
-  return { accumulatedText, errored, finishValue };
+  return {
+    accumulatedText,
+    errored,
+    finishValue,
+    ...thinking !== void 0 ? { thinking } : {}
+  };
 }
 function registerLoopError(ctx, cause) {
   if (ctx.error !== void 0) return;
@@ -5275,11 +5367,26 @@ function registerLoopError(ctx, cause) {
   const code = typeof metaCode === "string" ? metaCode : typeof rawCode === "string" ? rawCode : void 0;
   ctx.error = code !== void 0 ? { message, code, cause } : { message, cause };
 }
+async function consumeStreamEvent(inputs, reasoning, event) {
+  if (event.type === "text_delta") {
+    const text = event.text ?? "";
+    await emitTextDeltaCallback(inputs, text);
+    return text;
+  }
+  if (event.type === "reasoning_delta") {
+    await consumeReasoningDelta(inputs, reasoning, {
+      text: event.text ?? "",
+      ...event.signature !== void 0 ? { signature: event.signature } : {}
+    });
+  }
+  return "";
+}
 async function runCollectorLoop(generator, inputs, ctx) {
   let accumulatedText = "";
-  const reasoning = { text: "", startedAt: void 0 };
+  const reasoning = { text: "", startedAt: void 0, signature: void 0 };
   let errored = false;
   let finishValue;
+  let thinking;
   try {
     while (true) {
       const next = await generator.next();
@@ -5287,24 +5394,22 @@ async function runCollectorLoop(generator, inputs, ctx) {
         finishValue = next;
         break;
       }
-      if (next.value.type === "text_delta") {
-        accumulatedText += next.value.text;
-        await emitTextDeltaCallback(inputs, next.value.text);
-      }
-      if (next.value.type === "reasoning_delta") {
-        await accumulateReasoning(inputs, reasoning, next.value.text);
-      }
       if (next.value.type === "error") {
         registerLoopError(ctx, next.value);
         ctx.finalText = "";
         errored = true;
         break;
       }
+      accumulatedText += await consumeStreamEvent(inputs, reasoning, next.value);
     }
   } finally {
-    await finalizeReasoning(inputs, ctx, reasoning);
+    thinking = await finalizeReasoning(inputs, ctx, reasoning);
   }
-  return { accumulatedText, errored, finishValue };
+  return { accumulatedText, errored, finishValue, ...thinking !== void 0 ? { thinking } : {} };
+}
+async function consumeReasoningDelta(inputs, reasoning, delta) {
+  if (delta.signature !== void 0) reasoning.signature = delta.signature;
+  await accumulateReasoning(inputs, reasoning, delta.text);
 }
 async function accumulateReasoning(inputs, reasoning, text) {
   if (reasoning.startedAt === void 0) reasoning.startedAt = Date.now();
@@ -5312,10 +5417,17 @@ async function accumulateReasoning(inputs, reasoning, text) {
   await emitReasoningDeltaCallback(inputs, text);
 }
 async function finalizeReasoning(inputs, ctx, reasoning) {
-  if (reasoning.text.length === 0) return;
+  if (reasoning.text.length === 0) return void 0;
   const thinkingDurationMs = reasoning.startedAt === void 0 ? 0 : Date.now() - reasoning.startedAt;
-  ctx.events.push(buildThinkingEvent(inputs, reasoning.text, thinkingDurationMs));
+  ctx.events.push(
+    buildThinkingEvent(inputs, reasoning.text, thinkingDurationMs, reasoning.signature)
+  );
   await emitThinkingCompletedCallback(inputs, thinkingDurationMs);
+  return {
+    type: "thinking",
+    text: reasoning.text,
+    ...reasoning.signature !== void 0 ? { signature: reasoning.signature } : {}
+  };
 }
 async function emitTextDeltaCallback(inputs, text) {
   if (inputs.onDelta === void 0) return;
@@ -5345,6 +5457,24 @@ async function emitThinkingCompletedCallback(inputs, thinkingDurationMs) {
   );
 }
 
+// src/internal/agent-loop/loop-thinking-steps.ts
+function thinkingStep(thinking) {
+  return {
+    type: "thinkingMessage",
+    message: {
+      text: thinking.text,
+      ...thinking.signature !== void 0 ? { signature: thinking.signature } : {}
+    }
+  };
+}
+function recordThinkingOnSilentToolRound(ctx, text, thinking) {
+  if (text.length > 0 || thinking === void 0) return;
+  ctx.conversation.push({
+    type: "agentConversationTurn",
+    turn: { steps: [thinkingStep(thinking)] }
+  });
+}
+
 // src/internal/tool-dispatch/repair-middleware.ts
 var DECIMAL_RE = /^-?\d+(\.\d+)?$/;
 function repairToolCall(raw, registry) {
@@ -6396,12 +6526,13 @@ async function runAgentLoop(inputs) {
     sendSpan?.end();
   }
 }
-async function emitAssistantTextStep(inputs, ctx, text) {
+async function emitAssistantTextStep(inputs, ctx, text, thinking) {
   ctx.events.push(buildAssistantEvent(inputs, text));
-  ctx.conversation.push({
-    type: "agentConversationTurn",
-    turn: { steps: [{ type: "assistantMessage", message: { text } }] }
-  });
+  const steps = [
+    ...thinking !== void 0 ? [thinkingStep(thinking)] : [],
+    { type: "assistantMessage", message: { text } }
+  ];
+  ctx.conversation.push({ type: "agentConversationTurn", turn: { steps } });
   ctx.finalText = text;
   if (inputs.onStep === void 0) return;
   const cb = inputs.onStep;
@@ -6537,13 +6668,15 @@ async function continueOrTerminate(inputs, ctx, llmOutput) {
   if (llmOutput.errored) return "error";
   const tCtx = { agentId: inputs.agentId, runId: inputs.runId };
   const text = llmOutput.text.length > 0 ? await transformLlmOutputText(inputs, llmOutput.text, tCtx) : llmOutput.text;
+  const thinking = llmOutput.thinking;
   if (text.length > 0) {
-    await emitAssistantTextStep(inputs, ctx, text);
+    await emitAssistantTextStep(inputs, ctx, text, thinking);
   }
   if (llmOutput.stopReason !== "tool_use" || llmOutput.toolCalls.length === 0) {
     return finishOrReflect(inputs, ctx, llmOutput);
   }
-  ctx.messages.push(buildAssistantTurn(text, llmOutput.toolCalls));
+  recordThinkingOnSilentToolRound(ctx, text, thinking);
+  ctx.messages.push(buildAssistantTurn(text, llmOutput.toolCalls, thinking));
   const rawResults = await dispatchTools(
     // SE12 — forward a read-only text projection of the transcript-so-far to tool
     // handlers via `ctx.messages` (consumed by defineSubAgent's messageFilter).
@@ -6579,7 +6712,9 @@ async function inspectDoomLoop(inputs, ctx, toolCalls) {
     await emitAssistantTextStep(
       inputs,
       ctx,
-      verdict.message ?? "Stopped: repeated identical tool calls made no progress."
+      verdict.message ?? "Stopped: repeated identical tool calls made no progress.",
+      // The doom-loop stop message is the SDK's own text, not a model turn — it has no thinking.
+      void 0
     );
     return "stop";
   }
@@ -6726,7 +6861,20 @@ var StdioMcpClient = class extends BaseMcpClient {
       );
     });
   }
+  /**
+   * theokit#155 — idempotent while the child is LIVE.
+   *
+   * Under `mcpLifecycle: 'session'` the pool hands the same client back on the next turn, and
+   * `initializeMcp` runs every turn. An unconditional `spawnChild()` would overwrite `this.child`,
+   * orphaning a healthy process (its `exit` handler is skipped by the `this.child === child` guard)
+   * and paying the ~146 ms spawn + handshake the option exists to avoid.
+   *
+   * This does NOT touch the #59 reconnect path: `reconnect()` calls `spawnChild()` and
+   * `super.initialize()` directly, so it re-spawns exactly as before. After `close()` — or after a
+   * drop, which clears `child` — this method spawns again, as it must.
+   */
   async initialize() {
+    if (this.child !== void 0) return;
     this.spawnChild();
     await super.initialize();
   }
@@ -6915,12 +7063,12 @@ var HttpMcpClient = class extends BaseMcpClient {
   async readBody(response) {
     const tipo = response.headers.get("content-type") ?? "";
     if (!tipo.includes("text/event-stream")) return await response.json();
-    const texto = await response.text();
-    for (const linha of texto.split(/\r?\n/)) {
-      if (!linha.startsWith("data:")) continue;
-      const carga = linha.slice(5).trim();
-      if (carga === "") continue;
-      return JSON.parse(carga);
+    const text = await response.text();
+    for (const line of text.split(/\r?\n/)) {
+      if (!line.startsWith("data:")) continue;
+      const payload = line.slice(5).trim();
+      if (payload === "") continue;
+      return JSON.parse(payload);
     }
     throw new NetworkError(`MCP ${this.name} returned an event stream with no data payload`, {
       code: "mcp_http_error"
@@ -7097,16 +7245,15 @@ function declarativeSubagentTools(agents2, parentTools) {
   if (agents2 === void 0 || Object.keys(agents2).length === 0) return [];
   return subAgentToolsFromDefinitions(agents2, parentTools);
 }
-function bindParentCredentials(tools, agentOptions) {
+function resolveInheritedCredentials(agentOptions) {
   const parentPlugins = Array.isArray(agentOptions.plugins) ? agentOptions.plugins : void 0;
   const parentSandbox = agentOptions.local?.sandboxOptions?.enabled;
-  const credentials = {
+  return {
     ...agentOptions.apiKey !== void 0 ? { apiKey: agentOptions.apiKey } : {},
     ...typeof agentOptions.model === "object" ? { model: agentOptions.model } : {},
     ...parentPlugins !== void 0 ? { plugins: parentPlugins } : {},
     ...parentSandbox !== void 0 ? { sandbox: parentSandbox } : {}
   };
-  for (const tool of tools) inheritSubAgentCredentials(tool, credentials);
 }
 function buildCustomToolsInput(agentOptions, sendOptions, pluginManager, personalityToolWhitelist, agentId, personalityName, subagents, effectiveModel) {
   const baseTools = sendOptions?.tools ?? agentOptions.tools ?? [];
@@ -7118,7 +7265,6 @@ function buildCustomToolsInput(agentOptions, sendOptions, pluginManager, persona
     return {};
   }
   const allTools = [...baseTools, ...subagentTools, ...pluginTools, ...reasoningTools];
-  bindParentCredentials(allTools, agentOptions);
   const merged = allTools.map((tool) => ({
     name: tool.name,
     description: tool.description,
@@ -7154,7 +7300,9 @@ function createRealLocalRun(options) {
       supportedOps: supported,
       startTime
     },
-    () => buildLoopInputs(options, id, userText, userImages)
+    () => buildLoopInputs(options, id, userText, userImages),
+    runOwnsMcpClients(options.agentOptions),
+    resolveInheritedCredentials(options.agentOptions)
   );
   handle.bootstrap();
   registerRun(handle);
@@ -7293,11 +7441,14 @@ function disposeSessionMcpClients(agentId) {
     void client.close();
   });
 }
+function runOwnsMcpClients(agentOptions) {
+  return agentOptions.mcpLifecycle !== "session";
+}
 function buildMcpMap(options) {
   const map = /* @__PURE__ */ new Map();
   const inline = options.sendOptions.mcpServers ?? options.agentOptions.mcpServers;
   if (inline === void 0) return map;
-  const pooled = options.agentOptions.mcpLifecycle === "session";
+  const pooled = !runOwnsMcpClients(options.agentOptions);
   if (pooled) sessionMcpPool.reapIdle((c) => void c.close());
   for (const [name, config] of Object.entries(inline)) {
     map.set(
@@ -7309,9 +7460,15 @@ function buildMcpMap(options) {
 }
 var RealLocalRun = class extends FixtureRunBase {
   buildInputs;
-  constructor(options, buildInputs) {
+  /** theokit#155 — whether this turn releases its MCP clients, or the session pool does. */
+  ownsMcpClients;
+  /** theokit#148 — what a delegated child inherits from this parent, scoped to the loop. */
+  inheritedCredentials;
+  constructor(options, buildInputs, ownsMcpClients, inheritedCredentials) {
     super(options);
     this.buildInputs = buildInputs;
+    this.ownsMcpClients = ownsMcpClients;
+    this.inheritedCredentials = inheritedCredentials;
   }
   bootstrap() {
     setTimeout(() => {
@@ -7351,17 +7508,39 @@ var RealLocalRun = class extends FixtureRunBase {
       }
     }
   }
+  /**
+   * theokit#140 - events already handed to stream() by the live subscriber.
+   *
+   * The loop still RETURNS its full event list, and that batch path is deliberately kept: it is the
+   * fallback if a live event is ever lost, and removing it would make the live channel a single
+   * point of failure for the whole transcript.
+   */
+  liveDelivered = /* @__PURE__ */ new Set();
   async executeAgentLoop(inputs) {
+    inputs.onLoopEvent = (event) => {
+      this.liveDelivered.add(event);
+      this.script.events.push(event);
+      this.pushTimeline({ kind: "message", message: event });
+      this.notifyNewEvents();
+    };
+    const callerOnDelta = inputs.onDelta;
+    inputs.onDelta = (delta) => {
+      callerOnDelta?.(delta);
+      this.pushTimeline({ kind: "delta", update: delta.update });
+    };
     try {
-      const output = inputs.activeTools !== void 0 ? await withToolWhitelist(new Set(inputs.activeTools), () => runAgentLoop(inputs)) : await runAgentLoop(inputs);
+      const runLoop = () => inputs.activeTools !== void 0 ? withToolWhitelist(new Set(inputs.activeTools), () => runAgentLoop(inputs)) : runAgentLoop(inputs);
+      const output = await withInheritedSubAgentCredentials(this.inheritedCredentials, runLoop);
       this.applyAgentLoopOutput(output);
       this.transitionTo(output.finalStatus);
     } catch (cause) {
       this.emitErrorEvent(cause, "Agent loop failed", "", "agent_loop_failed");
       this.transitionTo("error");
     } finally {
-      for (const client of inputs.mcp.values()) {
-        await client.close().catch(() => void 0);
+      if (this.ownsMcpClients) {
+        for (const client of inputs.mcp.values()) {
+          await client.close().catch(() => void 0);
+        }
       }
     }
   }
@@ -7374,10 +7553,7 @@ var RealLocalRun = class extends FixtureRunBase {
    * Finding-B fix (sdk-error-packaging v1.1): set-once errorDetail copy.
    */
   applyAgentLoopOutput(output) {
-    for (const event of output.events) {
-      this.script.events.push(event);
-      this.notifyNewEvents();
-    }
+    this.deliverUndeliveredEvents(output.events);
     this.script.conversation.push(...output.conversation);
     if (output.result.length > 0) this.script.result = output.result;
     if (output.usage !== void 0) this.script.usage = output.usage;
@@ -7392,6 +7568,25 @@ var RealLocalRun = class extends FixtureRunBase {
       };
     }
   }
+  /**
+   * theokit#140 - deliver only what the live subscriber has NOT already handed to `stream()`.
+   *
+   * The loop now reports each event as it happens, so this batch is the SAME list, replayed.
+   * Without the guard every event would reach `stream()` twice: once live, once here.
+   *
+   * Identity, not deep equality: these are the very objects the live sink saw, and two genuinely
+   * distinct events can be structurally identical (the same tool called twice with the same args
+   * is not a duplicate).
+   *
+   * Extracted because the guard pushed `applyAgentLoopOutput` past the cognitive-complexity cap.
+   */
+  deliverUndeliveredEvents(events) {
+    for (const event of events) {
+      if (this.liveDelivered.has(event)) continue;
+      this.script.events.push(event);
+      this.notifyNewEvents();
+    }
+  }
   emitErrorEvent(cause, fallback, prefix = "", code) {
     if (this.script.errorDetail === void 0) {
       const message = cause instanceof Error ? cause.message : String(cause);
@@ -7677,7 +7872,7 @@ var LiveAgentRegistry = class {
 var liveAgentRegistry = new LiveAgentRegistry();
 
 // src/internal/local-agent/local-agent-lifecycle.ts
-async function adquirirLeaseSePossivel(store, agentId) {
+async function acquireLeaseIfPossible(store, agentId) {
   const a = store.acquire;
   if (typeof a !== "function") return;
   try {
@@ -7690,7 +7885,7 @@ async function adquirirLeaseSePossivel(store, agentId) {
     );
   }
 }
-async function soltarLeaseSePossivel(store, agentId) {
+async function releaseLeaseIfPossible(store, agentId) {
   const r = store.release;
   if (typeof r === "function") await r.call(store, agentId);
 }
@@ -7706,7 +7901,7 @@ async function disposeLocalAgentSession(agent) {
   await flushSessionWrites();
   await flushRegistrySaves(agent.workspaceCwd);
   await disposeSessionStore(agent.sessionStore);
-  descartarSessao(agent.workspaceCwd, agent.agentId);
+  discardSession(agent.workspaceCwd, agent.agentId);
 }
 async function reloadLocalAgent(agent) {
   if (agent.context !== void 0) await agent.context.refresh();
@@ -7952,184 +8147,6 @@ function cacheKey(userText, queryMode, ctx) {
   const parts = [queryMode, ctx?.namespace ?? "", ctx?.userId ?? "", ctx?.scope ?? "", userText];
   return createHash("sha256").update(parts.join("\0")).digest("hex");
 }
-var MAX_BATCH = 100;
-var MAX_RETRIES = 2;
-async function createOpenAiCompatibleRuntime(cfg, options) {
-  const model = options.model ?? cfg.defaultModel;
-  const apiKey = options.apiKey ?? process.env[cfg.apiKeyEnv];
-  if (apiKey === void 0 || apiKey.length === 0) {
-    throw new AuthenticationError(`${cfg.apiKeyEnv} missing`, {
-      code: "embedding_missing_api_key"
-    });
-  }
-  const envBaseUrl = cfg.baseUrlEnv !== void 0 ? process.env[cfg.baseUrlEnv] : void 0;
-  const baseUrl = options.baseUrl ?? envBaseUrl ?? cfg.defaultBaseUrl;
-  const fetchImpl = options.fetch ?? fetch;
-  const cache = options.cache ?? globalEmbeddingCache;
-  const dimension = cfg.dimensionByModel[model];
-  if (dimension === void 0) {
-    throw new ConfigurationError(
-      `${cfg.id} adapter: model "${model}" is not in the dimension table. Use one of: ${Object.keys(cfg.dimensionByModel).join(", ")}. To add it, update dimensionByModel in the adapter source.`,
-      { code: "embedding_unknown_model" }
-    );
-  }
-  const embeddingsPath = cfg.embeddingsPath ?? "/v1/embeddings";
-  const stats = {
-    cacheHits: 0,
-    cacheMisses: 0,
-    httpCalls: 0,
-    retries: 0
-  };
-  return {
-    id: cfg.id,
-    model,
-    dimension,
-    stats: () => ({ ...stats }),
-    embed: (texts) => embedTexts({
-      texts,
-      cache,
-      stats,
-      model,
-      dimension,
-      apiKey,
-      baseUrl,
-      embeddingsPath,
-      fetchImpl,
-      providerId: cfg.id
-    })
-  };
-}
-async function embedTexts(input) {
-  const { texts, cache, stats, model, dimension } = input;
-  const results = new Array(texts.length);
-  const pending = [];
-  for (let i = 0; i < texts.length; i++) {
-    classifyEntry({
-      index: i,
-      text: texts[i] ?? "",
-      model,
-      dimension,
-      cache,
-      stats,
-      results,
-      pending
-    });
-  }
-  await embedInBoundedBatches(input, pending, results);
-  return results.map((v) => v ?? new Array(dimension).fill(0));
-}
-function classifyEntry(args) {
-  if (args.text.trim().length === 0) {
-    args.results[args.index] = new Array(args.dimension).fill(0);
-    return;
-  }
-  const key = hashKey(args.model, args.text);
-  const cached = args.cache.get(key);
-  if (cached !== void 0) {
-    args.stats.cacheHits += 1;
-    args.results[args.index] = cached;
-    return;
-  }
-  args.stats.cacheMisses += 1;
-  args.pending.push({ index: args.index, text: args.text, key });
-}
-var MAX_CONCURRENT_BATCHES = 3;
-async function embedInBoundedBatches(input, pending, results) {
-  const batches = [];
-  for (let offset = 0; offset < pending.length; offset += MAX_BATCH) {
-    batches.push(pending.slice(offset, offset + MAX_BATCH));
-  }
-  await mapWithConcurrency(
-    batches,
-    MAX_CONCURRENT_BATCHES,
-    (batch) => processBatch(input, batch, results)
-  );
-}
-async function processBatch(input, batch, results) {
-  const vectors = await embedBatch({
-    apiKey: input.apiKey,
-    baseUrl: input.baseUrl,
-    embeddingsPath: input.embeddingsPath,
-    model: input.model,
-    inputs: batch.map((b) => b.text),
-    fetchImpl: input.fetchImpl,
-    stats: input.stats,
-    providerId: input.providerId
-  });
-  for (let j = 0; j < batch.length; j++) {
-    const slot = batch[j];
-    const vector = vectors[j];
-    if (slot === void 0 || vector === void 0) continue;
-    results[slot.index] = vector;
-    input.cache.set(slot.key, vector);
-  }
-}
-async function embedBatch(opts) {
-  const url = `${opts.baseUrl.replace(/\/$/, "")}${opts.embeddingsPath}`;
-  let attempt = 0;
-  while (true) {
-    opts.stats.httpCalls += 1;
-    const response = await postEmbedRequest(opts, url);
-    if (response.ok)
-      return await parseEmbedResponse(response, opts.providerId, opts.embeddingsPath);
-    if (isRetryable(response.status) && attempt < MAX_RETRIES) {
-      attempt += 1;
-      opts.stats.retries += 1;
-      await sleep(linearBackoffMs(attempt));
-      continue;
-    }
-    const text = await response.text().catch(() => "");
-    let body = text;
-    try {
-      body = JSON.parse(text);
-    } catch {
-    }
-    throw mapOpenAICompatibleError({
-      providerId: opts.providerId,
-      status: response.status,
-      body,
-      headers: response.headers,
-      endpoint: opts.embeddingsPath
-    });
-  }
-}
-async function postEmbedRequest(opts, url) {
-  return opts.fetchImpl(url, {
-    method: "POST",
-    headers: {
-      "content-type": "application/json",
-      authorization: `Bearer ${opts.apiKey}`
-    },
-    body: JSON.stringify({ model: opts.model, input: opts.inputs })
-  });
-}
-async function parseEmbedResponse(response, providerId, endpoint) {
-  const json = await response.json();
-  if (!Array.isArray(json.data)) {
-    throw new NetworkError(`${providerId} ${endpoint} returned no data`, {
-      code: "embedding_invalid_response",
-      metadata: {
-        provider: providerId,
-        endpoint,
-        code: "invalid_request",
-        raw: json
-      }
-    });
-  }
-  return json.data.map((d) => d.embedding);
-}
-function isRetryable(status) {
-  return status === 429 || status >= 500 && status < 600;
-}
-function hashKey(model, text) {
-  return createHash("sha256").update(`${model} ${text}`).digest("hex");
-}
-function linearBackoffMs(attempt) {
-  return 50 * attempt;
-}
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
 
 // src/internal/memory/adapters/azure-openai-embedding.ts
 var DEFAULT_AZURE_OPENAI_EMBEDDING_MODEL = "text-embedding-3-small";
@@ -8152,7 +8169,15 @@ var azureOpenAiMemoryEmbeddingProviderAdapter = {
       baseUrlEnv: "AZURE_OPENAI_ENDPOINT",
       defaultModel: DEFAULT_AZURE_OPENAI_EMBEDDING_MODEL,
       embeddingsPath: "/openai/deployments/{model}/embeddings?api-version=2024-02-01",
-      dimensionByModel: DIMENSION_BY_MODEL
+      dimensionByModel: DIMENSION_BY_MODEL,
+      // theokit#159 — Azure is NOT OpenAI on the wire, despite the name. It authenticates an API
+      // key with the `api-key` header (`Authorization: Bearer` is for Entra ID tokens, not for
+      // AZURE_OPENAI_API_KEY), and the deployment already rides in the path, so `model` has no
+      // place in the body. Sending the OpenAI shape meant every request was rejected.
+      dialect: {
+        authHeaders: (apiKey) => ({ "api-key": apiKey }),
+        body: (_model, inputs) => ({ input: inputs })
+      }
     },
     options
   )
@@ -8179,7 +8204,20 @@ var cohereMemoryEmbeddingProviderAdapter = {
       apiKeyEnv: "COHERE_API_KEY",
       defaultModel: DEFAULT_COHERE_EMBEDDING_MODEL,
       embeddingsPath: "/v2/embed",
-      dimensionByModel: DIMENSION_BY_MODEL2
+      dimensionByModel: DIMENSION_BY_MODEL2,
+      // theokit#159 — `/v2/embed` diverges in BOTH directions: it names the payload `texts`, requires
+      // `input_type`, and answers `{embeddings:{float:[[...]]}}` rather than `{data:[{embedding}]}`.
+      // `search_document` is the right default here because this runtime embeds material for
+      // storage; a query-side embedder would use `search_query`.
+      dialect: {
+        body: (model, inputs) => ({
+          model,
+          texts: [...inputs],
+          input_type: "search_document",
+          embedding_types: ["float"]
+        }),
+        vectors: (json) => json.embeddings?.float
+      }
     },
     options
   )
@@ -8237,6 +8275,9 @@ var geminiMemoryEmbeddingProviderAdapter = {
       defaultBaseUrl: "https://generativelanguage.googleapis.com",
       apiKeyEnv: "GEMINI_API_KEY",
       defaultModel: DEFAULT_GEMINI_EMBEDDING_MODEL,
+      // theokit#159 — the compat surface is under `/v1beta/openai/`, not the default
+      // `/v1/embeddings`; the previous path 404'd on every call.
+      embeddingsPath: "/v1beta/openai/embeddings",
       dimensionByModel: DIMENSION_BY_MODEL4
     },
     options
@@ -9047,9 +9088,9 @@ async function localAgentUsePersonality(args) {
 // src/internal/local-agent/local-agent-runtime-extensions.ts
 function localAgentRunUntil(agent, goal, options) {
   async function* wrap() {
-    const { runUntilImpl } = await import('./run-until-YZ2ODWOF.js');
+    const { runUntilImpl } = await import('./run-until-BK56WG4P.js');
     const buildDeps = async () => {
-      const { judgeCallImpl } = await import('./judge-call-TAEIXMYG.js');
+      const { judgeCallImpl } = await import('./judge-call-NA2G6ZMJ.js');
       const { getAgentFacade } = await import('./agent-factory-registry-ZVTABLEY.js');
       const create = getAgentFacade().create;
       return {
@@ -9082,7 +9123,7 @@ async function* localAgentStreamToCompletion(agent, message, options) {
 async function localAgentFork(parent, options) {
   const { forkAgentImpl } = await import('./fork-agent-RSV4E3EA.js');
   const { getAgentFacade } = await import('./agent-factory-registry-ZVTABLEY.js');
-  const { withPersonalityContext } = await import('./context-VAYLPT4O.js');
+  const { withPersonalityContext } = await import('./context-ATJJAFOS.js');
   const create = getAgentFacade().create;
   return withPersonalityContext(
     { slug: parent.personalitySlugSnapshot, isFork: true },
@@ -9238,6 +9279,9 @@ var SUPPORTED = /* @__PURE__ */ new Set([
   "cancel",
   "conversation"
 ]);
+function emptyTimeline() {
+  return emptyStream();
+}
 function emptyStream() {
   return {
     next: () => Promise.resolve({ done: true, value: void 0 }),
@@ -9262,6 +9306,9 @@ function createTripwireRun(args) {
     status: "cancelled",
     ...args.model !== void 0 ? { model: args.model } : {},
     stream: () => emptyStream(),
+    // theokit#140 - a tripwire run never executed, so its timeline is empty by construction, the
+    // same reason `stream()` is. Both are empty for the same fact, not by coincidence.
+    events: () => emptyTimeline(),
     wait: () => Promise.resolve(result),
     cancel: () => Promise.resolve(),
     conversation: () => Promise.resolve([]),
@@ -9457,7 +9504,7 @@ async function executeSendLocked(inputs, message, options) {
 function buildCompletionCheckDeps() {
   return {
     judge: async (ctx, opts) => {
-      const { judgeCallImpl } = await import('./judge-call-TAEIXMYG.js');
+      const { judgeCallImpl } = await import('./judge-call-NA2G6ZMJ.js');
       const { getAgentFacade } = await import('./agent-factory-registry-ZVTABLEY.js');
       return judgeCallImpl(ctx, opts, { create: getAgentFacade().create });
     }
@@ -9609,12 +9656,12 @@ var LocalAgent = class {
       this.settingSourcesIncludeProject,
       this.options.agents
     );
-    await adquirirLeaseSePossivel(this.sessionStore, this.agentId);
+    await acquireLeaseIfPossible(this.sessionStore, this.agentId);
     try {
       await hydrateSession(this.agentId, { store: this.sessionStore, cwd: this.workspaceCwd });
       await this.personalityStore.hydrate(this.agentId);
     } catch (err) {
-      await soltarLeaseSePossivel(this.sessionStore, this.agentId);
+      await releaseLeaseIfPossible(this.sessionStore, this.agentId);
       throw err;
     }
   }
@@ -9647,16 +9694,16 @@ var LocalAgent = class {
     });
   }
   /**
-   * A janela de contexto declarada na seleção de modelo, no formato de spread condicional.
+   * The context window declared on the model selection, in conditional-spread form.
    *
-   * M94 — sem isto, o `override` de `resolveEffectiveContextWindow` existia desde o M77 e nenhum
-   * call site de produção o passava: um modelo de 400k sem entrada de catálogo era orçado contra o
-   * piso de 128k. Método próprio porque o spread inline empurrava `runLockedSendCycle` para além do
-   * teto de complexidade cognitiva do projeto.
+   * M94 — without this, `resolveEffectiveContextWindow`'s `override` had existed since M77 and no
+   * production call site passed it: a 400k model with no catalog entry was budgeted against the
+   * 128k floor. Its own method because the inline spread pushed `runLockedSendCycle` past the
+   * project's cognitive-complexity ceiling.
    */
-  #janelaDeclarada() {
-    const declarada = this.model?.contextWindow;
-    return declarada !== void 0 ? { contextWindow: declarada } : {};
+  #declaredWindow() {
+    const declared = this.model?.contextWindow;
+    return declared !== void 0 ? { contextWindow: declared } : {};
   }
   async runLockedSendCycle(message, options, sendSpan, resolve, reject) {
     const userText = typeof message === "string" ? message : message.text;
@@ -9685,7 +9732,7 @@ var LocalAgent = class {
         workspaceCwd: this.workspaceCwd,
         sessionStore: this.sessionStore,
         model: this.model?.id ?? "unknown",
-        ...this.#janelaDeclarada(),
+        ...this.#declaredWindow(),
         // M50 — the auto-compaction summarizer resolves credentials like the run itself.
         ...this.options.apiKey !== void 0 ? { apiKey: this.options.apiKey } : {},
         ...options.onRunEvent !== void 0 ? { onRunEvent: options.onRunEvent } : {},
@@ -10215,7 +10262,7 @@ var Agent = class _Agent {
    * @public
    */
   static async generateObject(options) {
-    const { generateObjectImpl } = await import('./generate-object-I7UD4NWN.js');
+    const { generateObjectImpl } = await import('./generate-object-XDCBYVK3.js');
     return generateObjectImpl(options, {
       create: (opts) => _Agent.create(opts),
       delete: (agentId) => _Agent.delete(agentId)
@@ -10239,7 +10286,7 @@ var Agent = class _Agent {
       delete: (agentId) => _Agent.delete(agentId)
     };
     async function* wrapper() {
-      streamObjectImport ??= import('./stream-object-OFM66VUT.js');
+      streamObjectImport ??= import('./stream-object-HWDEEQN4.js');
       const { streamObjectImpl } = await streamObjectImport;
       yield* streamObjectImpl(options, deps);
     }
@@ -10263,7 +10310,7 @@ var Agent = class _Agent {
    * @public
    */
   static async batch(prompts, options) {
-    const { batchImpl } = await import('./batch-SY5GZLFD.js');
+    const { batchImpl } = await import('./batch-6KQM3EBA.js');
     return batchImpl(prompts, options, { create: (opts) => _Agent.create(opts) });
   }
   /**
@@ -10287,7 +10334,7 @@ var Agent = class _Agent {
    *
    *   This bullet used to say the opposite ("Disposed agents are NOT auto-deleted...
    *   call `Agent.delete(agentId)` first"). It was measured false in M91:
-   *   `tests/m91-getorcreate-apos-dispose.test.ts` builds an agent, disposes it, and
+   *   `tests/m91-getorcreate-after-dispose.test.ts` builds an agent, disposes it, and
    *   gets a different instance back. The claim was about the PERSISTENT registry and
    *   read as being about the live cache — and consumers built around the wrong half.
    *   The agent-builder's M85 interrupt rotates the session id to work around a
@@ -10401,8 +10448,8 @@ var Agent = class _Agent {
         `No local agent "${agentId}" registered \u2014 compact targets local sessions.`
       );
     }
-    const { compactSessionTranscript, buildDefaultSummarizer: buildDefaultSummarizer2 } = await import('./compact-session-WNKKIIDW.js');
-    const { cwd, model, store } = await abrirStoreLocal(reg);
+    const { compactSessionTranscript, buildDefaultSummarizer: buildDefaultSummarizer2 } = await import('./compact-session-PYEC3NZV.js');
+    const { cwd, model, store } = await openLocalStore(reg);
     return enqueueSessionWrite(
       cwd,
       agentId,
@@ -10437,8 +10484,8 @@ var Agent = class _Agent {
         `No local agent "${agentId}" registered \u2014 injectSessionTurn targets local sessions.`
       );
     }
-    const { injectSessionTurn } = await import('./inject-session-UXNJQTZ6.js');
-    const { cwd, model, store } = await abrirStoreLocal(reg);
+    const { injectSessionTurn } = await import('./inject-session-GQMTDZUN.js');
+    const { cwd, model, store } = await openLocalStore(reg);
     await injectSessionTurn({
       store,
       loc: { cwd, agentId, model },
@@ -10447,6 +10494,86 @@ var Agent = class _Agent {
       assistantText: turn.assistantText
     });
   }
+  /**
+   * theokit#146 — read a LOCAL agent's persisted transcript as STRUCTURE, for rendering.
+   *
+   * A resumed session already replays correctly to the model, but a host had no way to draw it:
+   * the only projection available folded a tool call to the string `[tool call] NAME`, dropping the
+   * call id and every argument. A card UI got prose, so cross-restart resume was worth less than
+   * starting fresh — which is what at least one consumer did.
+   *
+   * Each returned message carries both projections: `text` (unchanged, what the model replay uses)
+   * and `parts` (`text` / `tool_use` / `tool_result` with ids, names, arguments and the
+   * `toolUseId` that correlates a result back to its call).
+   *
+   * Read-only and local-only: it opens the agent's session store and walks the transcript, exactly
+   * as {@link Agent.compact} and {@link Agent.injectSessionTurn} do. It appends nothing.
+   *
+   * @throws UnknownAgentError when `agentId` names no local agent.
+   * @public
+   */
+  static async transcript(agentId) {
+    let reg = getRegisteredAgent(agentId);
+    if (reg === void 0) {
+      await hydrateRegistryFromDisk(process.cwd());
+      reg = getRegisteredAgent(agentId);
+    }
+    if (reg === void 0 || reg.runtime !== "local") {
+      throw new UnknownAgentError(
+        `No local agent "${agentId}" registered \u2014 transcript targets local sessions.`
+      );
+    }
+    const { readSessionMessages } = await import('./agent-session-store-RHMHP5DG.js');
+    const { store } = await openLocalStore(reg);
+    return readSessionMessages(store, agentId);
+  }
+  /**
+   * theokit#123 — read-only introspection of a registered agent's tools and subagents.
+   *
+   * `Agent.list()` / `Agent.get()` enumerate agents and `agent.skills.list()` covers skills, but
+   * tools and subagents lived only on `RegisteredAgent.options` — an internal contract. A
+   * reflection endpoint (theokit-studio's `theokit dev`) therefore had to report empty lists for
+   * both, and say so with an `unavailable_reason`.
+   *
+   * A PROJECTION, not the options object. Tool handlers and subagent prompts are stripped: a
+   * handler is an executable that cannot cross a process boundary, and a prompt is the agent's
+   * instructions rather than its signature — a reflection endpoint serializes what it is handed.
+   *
+   * @throws UnknownAgentError when `agentId` names no registered agent.
+   * @public
+   */
+  static async describe(agentId) {
+    const agent = await getRegisteredAgentOrThrow(agentId);
+    const { loadSubagents: loadSubagents2 } = await import('./subagents-loader-X33KH2SZ.js');
+    const settingSources = agent.options.local?.settingSources;
+    const subagents = await loadSubagents2(
+      agent.cwd ?? process.cwd(),
+      settingSources === void 0 || settingSources.includes("project"),
+      agent.options.agents
+    );
+    return {
+      agentId: agent.agentId,
+      runtime: agent.runtime,
+      ...agent.model !== void 0 ? { model: agent.model } : {},
+      // Always arrays, so a caller can tell "this agent has none" from "the SDK did not say".
+      //
+      // Honest limit, stated because the alternative is an implied claim: `tools` is still the
+      // DECLARED catalog. Plugin tools and the reasoning `think` tool are assembled per run by
+      // `buildCustomToolsInput`, so they are not knowable from the registry alone. Documented on
+      // `AgentDescription.tools`.
+      tools: (agent.options.tools ?? []).map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema
+      })),
+      subagents: Object.entries(subagents).map(([name, def]) => ({
+        name,
+        description: def.description,
+        ...def.model !== void 0 ? { model: def.model } : {},
+        ...def.tools !== void 0 ? { tools: def.tools } : {}
+      }))
+    };
+  }
   /**
    * Permanently delete a cloud agent.
    *
@@ -10480,16 +10607,16 @@ setAgentFacade({
   resume: (agentId, options) => Agent.resume(agentId, options),
   batch: (prompts, options) => Agent.batch(prompts, options)
 });
-async function abrirStoreLocal(reg) {
+async function openLocalStore(reg) {
   const cwd = reg.cwd ?? process.cwd();
   const optModel = reg.options.model;
   const model = reg.model?.id ?? (typeof optModel === "string" ? optModel : optModel?.id) ?? "unknown";
-  const { FsSessionStore: FsSessionStore2 } = await import('./fs-session-store-6MY7PNI2.js');
-  const { defaultBaseDir: defaultBaseDir2, expandTilde: expandTilde2 } = await import('./session-transcript-6WKLYIN4.js');
+  const { FsSessionStore: FsSessionStore2 } = await import('./fs-session-store-O6FNHECD.js');
+  const { defaultBaseDir: defaultBaseDir2, expandTilde: expandTilde2 } = await import('./session-transcript-3B52DKTG.js');
   const baseDir = reg.options.local?.baseDir !== void 0 ? expandTilde2(reg.options.local.baseDir) : defaultBaseDir2();
   return { cwd, model, store: new FsSessionStore2({ baseDir, cwd }) };
 }
 
 export { Agent, AgentBuilder, DEFAULT_AGENTIC_MODEL_ID, MEMORY_EMBEDDING_ADAPTERS, Tool, ToolError, UsageAccumulator, computeCost, generateCronId, getPricingEntry, openRouterMemoryEmbeddingProviderAdapter, resolveApiKey };
-//# sourceMappingURL=chunk-VYJSHGAY.js.map
-//# sourceMappingURL=chunk-VYJSHGAY.js.map
+//# sourceMappingURL=chunk-GIRD3RWH.js.map
+//# sourceMappingURL=chunk-GIRD3RWH.js.map