@theokit/sdk 4.37.2 → 4.39.0

package/dist/{inject-session-UXNJQTZ6.js → inject-session-GQMTDZUN.js}

@@ -1,8 +1,9 @@
-import { enqueueSessionWrite } from './chunk-5SB4V74H.js';
-import { invalidateSessionCache } from './chunk-EEZ7CFMM.js';
-import { SessionTranscript } from './chunk-XAEAMI5H.js';
-import './chunk-56OXYUZE.js';
-import './chunk-TAPQWDW2.js';
+import { enqueueSessionWrite } from './chunk-E2FFG33C.js';
+import { invalidateSessionCache } from './chunk-5KOW3GLE.js';
+import './chunk-3I4B3OIX.js';
+import { SessionTranscript } from './chunk-JRLXEYR4.js';
+import './chunk-KX7JV5KM.js';
+import './chunk-IVSD7L22.js';
 
 // src/internal/session/inject-session.ts
 async function injectSessionTurn(opts) {
@@ -21,5 +22,5 @@ async function injectSessionTurn(opts) {
 }
 
 export { injectSessionTurn };
-//# sourceMappingURL=inject-session-UXNJQTZ6.js.map
-//# sourceMappingURL=inject-session-UXNJQTZ6.js.map
+//# sourceMappingURL=inject-session-GQMTDZUN.js.map
+//# sourceMappingURL=inject-session-GQMTDZUN.js.map

package/dist/inject-session-GQMTDZUN.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":[],"mappings":";;;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAM,oBAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAa,iBAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAA,sBAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-GQMTDZUN.js","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}

package/dist/{inject-session-DM4SKTZO.cjs → inject-session-LFCYVSLJ.cjs}

@@ -1,16 +1,17 @@
 'use strict';
 
-var chunkH5YVJB4K_cjs = require('./chunk-H5YVJB4K.cjs');
-var chunkIT3PWBW4_cjs = require('./chunk-IT3PWBW4.cjs');
-var chunkIEUDKUPM_cjs = require('./chunk-IEUDKUPM.cjs');
-require('./chunk-ICYBIC6N.cjs');
-require('./chunk-LTCOPATU.cjs');
+var chunkDCXRHCZJ_cjs = require('./chunk-DCXRHCZJ.cjs');
+var chunkBURYFNOM_cjs = require('./chunk-BURYFNOM.cjs');
+require('./chunk-XYOHKCYG.cjs');
+var chunkZ2CUEBXV_cjs = require('./chunk-Z2CUEBXV.cjs');
+require('./chunk-DGLLVCNB.cjs');
+require('./chunk-BCQ3E2ZG.cjs');
 
 // src/internal/session/inject-session.ts
 async function injectSessionTurn(opts) {
-  await chunkH5YVJB4K_cjs.enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {
+  await chunkDCXRHCZJ_cjs.enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {
     const prior = await opts.store.readRecords(opts.loc.agentId);
-    const transcript = chunkIEUDKUPM_cjs.SessionTranscript.fromRecords(prior, {
+    const transcript = chunkZ2CUEBXV_cjs.SessionTranscript.fromRecords(prior, {
       cwd: opts.loc.cwd,
       sessionId: opts.sessionId,
       model: opts.loc.model ?? "unknown"
@@ -18,10 +19,10 @@ async function injectSessionTurn(opts) {
     transcript.appendUserTurn(opts.userText);
     transcript.appendAssistantTurn({ text: opts.assistantText });
     await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));
-    chunkIT3PWBW4_cjs.invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);
+    chunkBURYFNOM_cjs.invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);
   });
 }
 
 exports.injectSessionTurn = injectSessionTurn;
-//# sourceMappingURL=inject-session-DM4SKTZO.cjs.map
-//# sourceMappingURL=inject-session-DM4SKTZO.cjs.map
+//# sourceMappingURL=inject-session-LFCYVSLJ.cjs.map
+//# sourceMappingURL=inject-session-LFCYVSLJ.cjs.map

package/dist/inject-session-LFCYVSLJ.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":["enqueueSessionWrite","SessionTranscript","invalidateSessionCache"],"mappings":";;;;;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAMA,sCAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAaC,mCAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAAC,wCAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-LFCYVSLJ.cjs","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}

package/dist/internal/agent-loop/live-events.d.ts

@@ -0,0 +1,46 @@
+import type { SDKMessage } from "../../types/messages.js";
+/**
+ * theokit#140 — the loop's event log, reporting each event AS IT HAPPENS.
+ *
+ * ## The defect this closes
+ *
+ * `runAgentLoop` collected events into a plain array and returned it, so nothing reached the run
+ * until the loop had finished. `RealLocalRun.applyAgentLoopOutput` then copied the whole batch in
+ * one pass. Meanwhile `SendOptions.onDelta` fired live from inside that same loop.
+ *
+ * Two clocks, one of which does not start until the other has stopped. A consumer that wanted tool
+ * calls interleaved with tokens in true order had to fuse both surfaces itself — which is exactly
+ * what `@theokit/agents` was doing, and the documented root of its ordering bug (theokit#47), its
+ * namespace-dedup bug (theokit#138) and its missing terminal frame (theokit#142).
+ *
+ * ## Why a subclass, and not a callback threaded through nine call sites
+ *
+ * The events are appended from nine places across `loop.ts`, `loop-llm-stream.ts` and
+ * `tool-dispatch.ts`. Threading an `onEvent` parameter to each would touch every one of them and,
+ * worse, would leave the NEXT `events.push(...)` silently un-notified — a defect that reintroduces
+ * itself by omission, which is the failure mode this whole issue is about.
+ *
+ * Extending `Array` moves the decision to the single place the log is CREATED. Every existing push
+ * becomes live with no call-site change, and any push added later is live for free.
+ *
+ * It stays a real `Array`: `AgentLoopOutput.events` is still `SDKMessage[]`, `instanceof Array`
+ * still holds, and every downstream consumer — including the batch copy in `applyAgentLoopOutput` —
+ * is unchanged. This is additive; nothing that worked before observes a difference.
+ *
+ * `push` is the only override, deliberately. The loop only ever appends; overriding the rest of the
+ * mutation surface would be guarding against callers that do not exist (YAGNI), and a subscriber
+ * that must reason about splices is a worse contract than one that receives appends.
+ */
+export declare class LiveEventLog extends Array<SDKMessage> {
+    #private;
+    /** Attach the live subscriber. One sink: the run that owns this loop. */
+    subscribe(sink: (event: SDKMessage) => void): void;
+    push(...events: SDKMessage[]): number;
+}
+/**
+ * Build the loop's event log, seeded with the events that exist before the loop starts.
+ *
+ * `LiveEventLog.from` rather than `new LiveEventLog(...seed)`: the `Array` constructor treats a
+ * single numeric argument as a length, and a seed is a list of events, never a count.
+ */
+export declare function createEventLog(seed: readonly SDKMessage[]): LiveEventLog;

package/dist/internal/agent-loop/loop-thinking-steps.d.ts

@@ -0,0 +1,28 @@
+/**
+ * theokit#122 — where a round's thinking block becomes a conversation step.
+ *
+ * Extracted from `loop.ts` when it crossed the G8 400-LoC cap. These two belong together: both
+ * answer "the round produced a thinking block — where does it land in the persisted conversation",
+ * and the answer differs by which path closes the round.
+ *
+ * @internal
+ */
+import type { LlmThinkingPart } from "../llm/types.js";
+import type { LoopContext } from "./loop-context-init.js";
+/**
+ * theokit#122 — the round's thinking block as a conversation step.
+ *
+ * Shared by the two paths that can close a round: the assistant-text path and the tool_use path.
+ * The tool_use path is the one that matters — a round of thinking + a tool call with NO preamble
+ * text is the common Anthropic shape, and it is exactly the case the first version of this fix
+ * dropped (the block stayed on the context and was persisted against the NEXT round's text).
+ */
+export declare function thinkingStep(thinking: LlmThinkingPart): ConversationStep;
+/**
+ * theokit#122 — persist the block for a round that called a tool and said nothing.
+ *
+ * Such a round emits no assistant-text step, so without this the block is never recorded for it —
+ * which is exactly how the first version of this fix let round N's signature reach round N+1.
+ * No-op when the round had text (the text path already recorded it) or produced no thinking.
+ */
+export declare function recordThinkingOnSilentToolRound(ctx: LoopContext, text: string, thinking: LlmThinkingPart | undefined): void;

package/dist/internal/agent-loop/message-builders.d.ts

@@ -1,5 +1,5 @@
 import type { SDKAssistantMessage, SDKThinkingMessage, SDKUserMessageEvent } from "../../types/messages.js";
-import type { LlmMessage, LlmToolCallPart } from "../llm/types.js";
+import type { LlmMessage, LlmThinkingPart, LlmToolCallPart } from "../llm/types.js";
 import type { AgentLoopInputs } from "./loop-types.js";
 export declare function buildUserEvent(inputs: AgentLoopInputs): SDKUserMessageEvent;
 export declare function buildAssistantEvent(inputs: AgentLoopInputs, text: string): SDKAssistantMessage;
@@ -8,5 +8,14 @@ export declare function buildAssistantEvent(inputs: AgentLoopInputs, text: strin
  * issue #48: when the reasoning duration was measured, carry it as `thinking_duration_ms`
  * so a `Run.stream()` replay can render how long the model reasoned.
  */
-export declare function buildThinkingEvent(inputs: AgentLoopInputs, text: string, thinkingDurationMs?: number): SDKThinkingMessage;
-export declare function buildAssistantTurn(text: string, toolCalls: LlmToolCallPart[]): LlmMessage;
+export declare function buildThinkingEvent(inputs: AgentLoopInputs, text: string, thinkingDurationMs?: number, signature?: string): SDKThinkingMessage;
+/**
+ * theokit#122 — `thinking` is FIRST, and that ordering is a provider requirement, not a preference.
+ *
+ * Anthropic verifies the signed block on the next request and requires it to lead the assistant
+ * message it belongs to. Omitting it (which this builder did until theokit#122's follow-up) makes
+ * round 2 of any thinking + tools run fail with `400 "thinking blocks cannot be modified"` — the
+ * exact failure the issue exists to remove. An unsigned block is passed through here and dropped at
+ * the wire by `thinkingToWireBlock`, which is where that policy belongs.
+ */
+export declare function buildAssistantTurn(text: string, toolCalls: LlmToolCallPart[], thinking?: LlmThinkingPart): LlmMessage;

package/dist/internal/budget/compute-cost.d.ts

@@ -10,7 +10,7 @@
  *   - "subscription_included" routes (Codex CLI, future Claude Pro) →
  *     return $0 with status="included".
  *   - Provider unknown / pricing missing → status="unknown" with
- *     undefined amountUsd (NÃO retorna 0 falso).
+ *     undefined amountUsd (does NOT return a false 0).
  *
  * @internal
  */

package/dist/internal/diagnostics.d.ts

@@ -1,54 +1,69 @@
 /**
- * Canal único de diagnóstico da biblioteca — silencioso por padrão (#147).
+ * The library's single diagnostics channel — silent by default (#147).
  *
  * ## O problema
  *
- * O SDK escrevia diagnósticos direto em `process.stderr` a partir de caminhos quentes —
- * 92 sítios em 51 arquivos sob `internal/`. Numa host de TUI (Ink, alternate screen), essas
- * escritas se intercalam com o render e **corrompem o frame**. E o host não tinha como
- * interceptá-las: não havia logger injetável. Um consumidor chegou a instalar
- * `proper-lockfile` só para calar UMA delas.
+ * The SDK wrote diagnostics straight to `process.stderr` from hot paths — 92 sites across 51
+ * files under `internal/`. In a TUI host (Ink, alternate screen), those writes interleave with the
+ * render and **corrupt the frame**. And the host had no way to intercept them: there was no
+ * injectable logger. One consumer went as far as installing `proper-lockfile` just to silence ONE
+ * of them.
  *
- * Uma biblioteca não pode assumir que `stdout`/`stderr` são sinks livres. Quem é dono do
- * terminal é a aplicação, não a dependência.
+ * A library cannot assume `stdout`/`stderr` are free sinks. The application owns the terminal, not
+ * the dependency.
  *
  * ## O contrato
  *
- * - **`setDiagnosticsSink(fn)`** entrega as mensagens à aplicação, que decide onde colocá-las
- *   (uma linha de status, um arquivo, um painel). É o que faltava para uma TUI conviver com o SDK.
- * - **Sem sink, vai para o `stderr`** — exatamente como antes desta mudança.
+ * - **`setDiagnosticsSink(fn)`** hands the messages to the application, which decides where to put
+ *   them (a status line, a file, a panel). It is what was missing for a TUI to coexist with the SDK.
+ * - **With no sink, nothing is emitted.** A library does not own the host's terminal.
  *
- * ## Por que o padrão NÃO mudou (ainda), e isso é deliberado
+ * ## Silent by default, and how 36 suites survived the flip
  *
- * A #147 pede silêncio por padrão, e é o alvo certo. Mas **58 arquivos de teste** asseram hoje
- * que estes diagnósticos chegam ao `stderr` — eles codificam o contrato "o aviso É emitido", que
- * continua valendo e não deve ser perdido. Virar o padrão sem migrá-los reprovaria ~53 testes, e
- * migrá-los às pressas, em quatro formas diferentes de espionar o `stderr`, é a receita para
- * enfraquecer 58 suítes de uma vez.
+ * The default WAS `stderr`, and 36 test files spy on `process.stderr.write` to assert a given
+ * warning is emitted. That contract is real and had to survive; migrating all 36 by hand, across
+ * four different spy styles, is how you weaken 36 suites in one commit.
  *
- * Então esta mudança entrega a metade que DESTRAVA o consumidor — o host de TUI agora consegue
- * interceptar, que era o bloqueio relatado ("no way to intercept these; no injectable logger") — e
- * deixa a virada do padrão como migração própria, com custo medido. Um host que quer silêncio
- * hoje instala `setDiagnosticsSink(() => {})`.
+ * So the flip happened at the default, and `vitest.setup.ts` installs a sink that FORWARDS to
+ * `stderr` for the duration of every test. Those assertions still test what they always tested —
+ * "this condition emits a diagnostic" — through the channel a host would use, while production
+ * emits nothing unless asked.
  *
- * ## O que isto NÃO é
+ * The cost is stated rather than hidden: no test observes the production default by accident, so
+ * `tests/diagnostics-public-entry.test.ts` pins it explicitly by clearing the sink first.
  *
- * Não é um logger com níveis, formatação ou destinos múltiplos. É o mínimo que resolve o
- * bloqueio relatado; um logger completo aqui seria inventar requisito que ninguém pediu.
+ * ## Coverage is the whole guarantee
+ *
+ * The first sweep migrated the 92 sites under `internal/` and left `src/`'s own modules —
+ * `event-bus.ts`, `batch.ts`, `compaction.ts`, `internal/workflow/step-branch.ts`. A host could
+ * therefore install a sink and still have its frame corrupted by a batch run, which is the reported
+ * defect with a smaller blast radius. Those are routed here too, and
+ * `tests/lint/no-direct-terminal-write.test.ts` is what keeps the next hot path from
+ * reintroducing one. "Mostly interceptable" is not interceptable.
+ *
+ * The remaining direct writers are allowlisted there with a reason, and every one of them is a seam
+ * whose destination the CALLER already chooses (`opts.warn`, `opts.logger`, the Workflow logger).
+ *
+ * ## What this is NOT
+ *
+ * It is not a logger with levels, formatting or multiple destinations. It is the minimum that
+ * resolves the reported blocker; a full logger here would be inventing a requirement nobody asked
+ * for.
  */
-/** Recebe cada mensagem de diagnóstico já formatada, com o `\n` final. */
+/** Receives each diagnostic message already formatted, with the trailing `\n`. */
 export type DiagnosticsSink = (message: string) => void;
 /**
- * Instala (ou remove, passando `undefined`) o destino dos diagnósticos.
+ * Installs (or removes, by passing `undefined`) the diagnostics destination.
  *
- * Quando há sink, ele é o ÚNICO destino — o `stderr` não recebe cópia. Duplicar destinos
- * devolveria o problema à TUI que instalou o sink justamente para tirar as mensagens do terminal.
+ * When a sink is present it is the ONLY destination — `stderr` gets no copy. Duplicating
+ * destinations would hand the problem back to the TUI that installed the sink precisely to get the
+ * messages out of the terminal.
  */
 export declare function setDiagnosticsSink(next: DiagnosticsSink | undefined): void;
 /**
- * Emite uma mensagem de diagnóstico da biblioteca.
+ * Emits a library diagnostic message.
  *
- * Substitui `process.stderr.write` nos caminhos internos. Nunca lança: um sink defeituoso não
- * pode derrubar o run que ele apenas observa.
+ * Replaces `process.stderr.write` on internal paths. Never throws: a faulty sink must not
+ * must not take down the run it merely observes.
  */
 export declare function diag(message: string): void;

package/dist/internal/error-mappers/anthropic.d.ts

@@ -12,7 +12,7 @@
  *                                       `"content_filtered"` for policy.)
  *   408     → `NetworkError`          (`code: "timeout"`)
  *   5xx     → `NetworkError`          (`code: "server_error"` — covers 529
- *                                       overloaded_error common em horário
+ *                                       overloaded_error common at peak
  *                                       de pico)
  *   other   → `UnknownAgentError`     (`code: "unknown"`)
  *

package/dist/internal/global-singleton.d.ts

@@ -1,13 +1,13 @@
 /**
  * Singleton por realm, chaveado por `Symbol.for`.
  *
- * Existe porque um pacote pode ser carregado mais de uma vez no mesmo processo (duas cópias em
- * `node_modules`, ESM e CJS lado a lado, monorepo com versões distintas) — e aí `const x = new Map()`
- * a nível de módulo produz DUAS caches que não se enxergam. `Symbol.for` usa o registro global de
- * símbolos, que é do realm e não do módulo, então todas as cópias convergem para a mesma instância.
+ * It exists because a package can be loaded more than once in the same process (two copies in
+ * `node_modules`, ESM and CJS side by side, a monorepo with distinct versions) — and then a module-level
+ * `const x = new Map()` produces TWO caches that cannot see each other. `Symbol.for` uses the global
+ * symbol registry, which belongs to the realm and not the module, so every copy converges on one instance.
  *
- * Estava copiado verbatim em `providers/discovery.ts` e `providers/catalog-loader.ts`. Isso é
- * duplicação de CONHECIMENTO, não coincidência de forma: as duas cópias precisam concordar sobre o
- * mecanismo, e uma corrigida sem a outra produz exatamente o bug que a função existe para evitar.
+ * It was copied verbatim into `providers/discovery.ts` and `providers/catalog-loader.ts`. That is
+ * duplicated KNOWLEDGE, not a coincidence of shape: the two copies have to agree on the
+ * mechanism, and one fixed without the other produces exactly the bug the function exists to avoid.
  */
 export declare function globalSingleton<T>(key: string, create: () => T): T;

package/dist/internal/judge/judge-call.d.ts

@@ -8,32 +8,32 @@ export interface JudgeContext {
 /** Caller-supplied tuning knobs for the judge call. */
 export interface JudgeOptions {
     /**
-     * Judge model identifier. Quando ausente, DERIVA de {@link agentModel} — e só cai no literal
-     * `"openai/gpt-4o-mini"` se nem esse for informado.
+     * Judge model identifier. When absent, it DERIVES from {@link agentModel} — and only falls back to the literal
+     * `"openai/gpt-4o-mini"` when neither is provided.
      *
-     * M80 — o default fixo era provider-cego: ele só resolve em OpenRouter. Com chave Anthropic dá
-     * 404, com bearer OAuth dá 401, e em ambos o goal queimava 3 turnos inteiros antes de falhar com
-     * razão enganosa. O agent-builder já contornava isso derivando por conta própria; o conhecimento
-     * pertence aqui.
+     * M80 — the fixed default was provider-blind: it only resolves on OpenRouter. With an Anthropic key it gives
+     * 404, with an OAuth bearer it gives 401, and in both the goal burned 3 whole turns before failing with
+     * a misleading reason. The agent-builder already worked around this by deriving on its own; the knowledge
+     * belongs here.
      */
     judgeModel?: string;
     /**
-     * M80 — o modelo do agente CONDUZIDO. É a base da derivação: um judge que roda no mesmo modelo do
-     * chat funciona onde o chat funciona.
+     * M80 — the DRIVEN agent's model. It is the basis of the derivation: a judge running on the same model as the
+     * chat works wherever chat works.
      */
     agentModel?: string;
     /** Override env. Default `process.env.OPENROUTER_API_KEY` (EC-A). */
     apiKey?: string;
 }
 /**
- * M80 — a credencial ou o modelo do judge não servem: 401/404.
+ * M80 — the judge's credential or model does not work: 401/404.
  *
- * Falha RÁPIDA por design. `rules/error-handling.md § 2` separa recuperável de irrecuperável, e um
- * modelo inexistente não passa a existir no retry — dobrar isso em `{parseFailed: true}` fazia o loop
- * tentar três vezes e reportar "failed" por limite de falhas consecutivas, escondendo que a causa era
- * credencial. Falha lenta e opaca trocada por rápida e clara.
+ * Fails FAST by design. `rules/error-handling.md` § 2 separates recoverable from unrecoverable, and a
+ * nonexistent model does not start existing on retry — folding that into `{parseFailed: true}` made the loop
+ * try three times and report "failed" on a consecutive-failure limit, hiding that the cause was the
+ * credential. A slow, opaque failure traded for a fast, clear one.
  *
- * Falha de PARSE e erro de rede continuam dobrados: são recuperáveis, e o loop já decide por falhas
+ * PARSE failures and network errors stay folded: they are recoverable, and the loop already decides on
  * consecutivas.
  */
 export declare class JudgeCredentialError extends TheokitAgentError {

package/dist/internal/llm/anthropic-shared.d.ts

@@ -25,10 +25,6 @@ export interface AnthropicResponseLike {
 export declare function extractAnthropicText(response: AnthropicResponseLike): string;
 export declare function extractAnthropicToolCalls(response: AnthropicResponseLike): LlmToolCallPart[];
 export declare function mapAnthropicStopReason(reason: string | null): LlmStopReason;
-/**
- * Convert an SDK `LlmMessage` to the Anthropic Messages wire shape.
- * Identical across the three Anthropic-compatible clients (D289/D292).
- */
 export declare function toAnthropicWireMessage(message: LlmMessage): Record<string, unknown>;
 /**
  * Build the common body shape for Anthropic Messages requests. Caller
@@ -93,4 +89,8 @@ export declare function buildAnthropicCommonBody(request: LlmRequest): {
         description: string;
         input_schema: unknown;
     }>;
+    thinking?: {
+        type: "enabled";
+        budget_tokens: number;
+    };
 };

package/dist/internal/llm/retrying-client.d.ts

@@ -1,40 +1,40 @@
 import type { LlmClient, LlmEvent, LlmFinish, LlmRequest } from "./types.js";
-/** Teto de tentativas. Fixo em 3 — o DoD do M93 nomeia o número. */
-export declare const MAX_TENTATIVAS = 3;
+/** Attempt ceiling. Fixed at 3 — M93's DoD names the number. */
+export declare const MAX_ATTEMPTS = 3;
 /**
- * O erro é transitório, isto é: reexecutar pode mudar o resultado?
+ * Is the error transient — that is, can retrying change the outcome?
  *
- * ## Delega para `isTransientError`, e diz o que subtrai
+ * ## Delegates to `isTransientError`, and states what it subtracts
  *
- * O SDK **já** publica `isTransientError` — documentado como "a single source of truth rather than
- * a re-derivation", e com o aviso explícito de que "It never inspects `err.message`". A primeira
- * versão desta função ignorou as duas coisas: derivou de novo, por regex sobre a mensagem
- * (`/\b4\d\d\b/`). A revisão adversarial mediu o custo — `connect ECONNREFUSED 127.0.0.1:443`
- * era classificado como NÃO transitório, porque a **porta** casa a regex. Os erros de rede para os
- * quais o retry existe eram exatamente os excluídos.
+ * The SDK **already** publishes `isTransientError` — documented as "a single source of truth rather
+ * than a re-derivation", with the explicit warning that "It never inspects `err.message`". The first
+ * version of this function ignored both: it re-derived, by regex over the message (`/\b4\d\d\b/`).
+ * Adversarial review measured the cost — `connect ECONNREFUSED 127.0.0.1:443` was classified as NOT
+ * transient, because the **port** matches the regex. The network errors retry exists for were
+ * exactly the ones excluded.
  *
- * Reinventar aqui foi violação da rung 4 da parcimônia com a peça pronta à mão. O que sobra desta
- * função são **três subtrações** do veredito do dono, cada uma com razão:
+ * Reinventing here violated parsimony rung 4 with the part already at hand. What remains of this
+ * function are **three subtractions** from the owner's verdict, each with a reason:
  *
- * | Subtração | Por quê |
+ * | Subtraction | Why |
  * |---|---|
- * | `CredentialPoolExhaustedError` | o pool já gastou o próprio orçamento de tentativas e rotação; o `nextRetryAt` está em dezenas de segundos. Reexecutar multiplicaria a espera por `MAX_TENTATIVAS` sem chance de sucesso. |
- * | `code === "circuit_open"` | o breaker existe **para** falhar rápido; envolvê-lo num retry desfaz de fora a decisão que ele acabou de tomar. |
- * | `RateLimitError` com 402 | cota de faturamento não se resolve em milissegundos — é por isso que o `classifyAndDecide` do pool rotaciona em vez de esperar. |
+ * | `CredentialPoolExhaustedError` | the pool already spent its own attempt and rotation budget; `nextRetryAt` is tens of seconds out. Retrying would multiply the wait by `MAX_ATTEMPTS` with no chance of success. |
+ * | `code === "circuit_open"` | the breaker exists **in order to** fail fast; wrapping it in a retry undoes from outside the decision it just made. |
+ * | `RateLimitError` with 402 | a billing quota does not resolve in milliseconds — which is why the pool's `classifyAndDecide` rotates instead of waiting. |
  *
- * As duas primeiras vieram da medição da revisão: com elas transitórias, o pool inteiro era
- * reexecutado 3×, e uma espera de 30 s virava ~90 s.
+ * The first two came out of the review's measurements: with them treated as transient, the entire
+ * pool was retried 3x, and a 30 s wait became ~90 s.
  */
-export declare function ehTransitorio(err: unknown): boolean;
+export declare function isRetriableError(err: unknown): boolean;
 /**
- * ## Por que NÃO há circuit breaker aqui
+ * ## Why there is NO circuit breaker here
  *
- * O `CircuitBreaker` do pacote é **chaveado por credencial** (`recordSuccess(key)` /
- * `recordTimeout(key)`): existe para o pool marcar uma chave como insalubre e **pular** para outra. Com
- * uma chave só não há para onde pular, então um breaker aqui registraria estado que ninguém consulta.
+ * The package's `CircuitBreaker` is **keyed by credential** (`recordSuccess(key)` /
+ * `recordTimeout(key)`): it exists so the pool can mark a key unhealthy and **skip** to another.
+ * With a single key there is nowhere to skip to, so a breaker here would record state nobody reads.
  *
- * Rung 1 da parcimônia — "isto precisa existir?". Não: seria cerimônia com nome de resiliência. O que
- * protege o caminho de chave única é o teto de tentativas e o backoff, e os dois estão abaixo.
+ * Parsimony rung 1 — "does this need to exist?". No: it would be ceremony with resilience's name on
+ * it. What protects the single-key path is the attempt ceiling and the backoff, and both are below.
  */
 export declare class RetryingLlmClient implements LlmClient {
     #private;
@@ -42,10 +42,10 @@ export declare class RetryingLlmClient implements LlmClient {
         rng?: () => number;
     });
     /**
-     * O cliente decorado. Público pela mesma convenção de `FaultInjectingLlmClient.inner`: os testes
-     * de fiação do router afirmam `instanceof PoolAwareLlmClient` e precisam enxergar através dos
-     * decorators. Sem isto, adicionar um decorator quebra testes cuja intenção continua válida — que
-     * foi exatamente o que o M93 fez com 4 testes pré-existentes.
+     * The decorated client. Public by the same convention as `FaultInjectingLlmClient.inner`: the
+     * router's wiring tests assert `instanceof PoolAwareLlmClient` and need to see through the
+     * decorators. Without this, adding a decorator breaks tests whose intent is still valid — which is
+     * exactly what M93 did to 4 pre-existing tests.
      */
     get inner(): LlmClient;
     get name(): string;

package/dist/internal/llm/transport-error.d.ts

@@ -1,7 +1,7 @@
 /**
- * Envolve uma falha de socket num {@link NetworkError}, preservando a causa.
+ * Wraps a socket failure in a {@link NetworkError}, preserving the cause.
  *
- * Devolve o erro original — sem envolver — quando ele é um abort ou já é um erro do SDK.
+ * Returns the original error — unwrapped — when it is an abort or already an SDK error.
  */
 export declare function wrapTransportError(err: unknown, ctx: {
     providerId: string;

package/dist/internal/llm/types.d.ts

@@ -43,7 +43,24 @@ export interface LlmImagePart {
         url: string;
     };
 }
-export type LlmContentPart = LlmTextPart | LlmToolCallPart | LlmToolResultPart | LlmImagePart;
+/**
+ * theokit#122 — an extended-thinking block, carried WITH its provider-issued signature.
+ *
+ * The signature is the whole reason this part exists. Anthropic requires a resumed conversation to
+ * replay each `thinking` block byte-identically, signature included; replaying the text alone is
+ * rejected with `400 "thinking blocks cannot be modified"` (anthropics/claude-code#63147). So a
+ * session that used extended thinking could be persisted but never resumed.
+ *
+ * `signature` is optional because not every provider issues one — the OpenAI-compatible reasoning
+ * channel streams `reasoning`/`reasoning_content` text with no signature at all. A part without a
+ * signature is display-only history; it must not be replayed to Anthropic as a thinking block.
+ */
+export interface LlmThinkingPart {
+    type: "thinking";
+    text: string;
+    signature?: string;
+}
+export type LlmContentPart = LlmTextPart | LlmToolCallPart | LlmToolResultPart | LlmImagePart | LlmThinkingPart;
 export interface LlmMessage {
     role: "system" | "user" | "assistant";
     content: LlmContentPart[];
@@ -122,20 +139,36 @@ export interface LlmRequest {
      */
     toolChoice?: "auto" | "none" | "required";
 }
+/**
+ * What a provider stream reports WHILE it is running. Tool calls are deliberately absent.
+ *
+ * theokit#144: this union used to declare `tool_use` and `stop` variants. Only two providers ever
+ * yielded them (`responses.ts`, `fault-injection.ts`), the loop's collector
+ * (`loop-llm-stream.ts`) never read them, and the tool calls they carried were duplicates of what
+ * `LlmFinish.toolCalls` already returned. So they were not a live tool channel — they were a
+ * declaration of one, which is worse: it told implementers a provider-level channel existed and
+ * cost `@theokit/agents` a workaround (holding every `text_delta` until the stream drained, which
+ * broke live token streaming on text-only turns — issue #47).
+ *
+ * Wiring them instead of deleting them was rejected: `openai.ts` and `anthropic.ts` cannot produce
+ * them at all (their tool calls only resolve at completion), so a live provider-level channel would
+ * exist on some providers and not others — a worse contract than a uniform one.
+ *
+ * **The canonical live tool channel is `onDelta`**: `tool-call-started` / `tool-call-completed`
+ * `InteractionUpdate`s, emitted by `runToolWithLifecycle` (`agent-loop/tool-dispatch.ts`) between
+ * LLM rounds. It is uniform across providers, carries a `callId` correlating the two ends, and
+ * fires before the post-tool answer text. `Run.events()` (theokit#140) merges it with the
+ * structural `SDKMessage`s into one ordered timeline.
+ *
+ * The stop reason is not an event either — it is returned once, on `LlmFinish.stopReason`.
+ */
 export type LlmEvent = {
     type: "text_delta";
     text: string;
 } | {
     type: "reasoning_delta";
     text: string;
-} | {
-    type: "tool_use";
-    id: string;
-    name: string;
-    input: Record<string, unknown>;
-} | {
-    type: "stop";
-    reason: LlmStopReason;
+    signature?: string;
 } | {
     type: "error";
     message: string;
@@ -153,6 +186,13 @@ export interface LlmFinish {
     cacheWriteTokens?: number;
     /** Reasoning tokens (OpenAI o-series). ADR D376. */
     reasoningTokens?: number;
+    /**
+     * theokit#122 — the turn's extended-thinking block, with the provider's signature when it issued
+     * one. Returned on the finish value rather than reconstructed from the `reasoning_delta` text,
+     * because the signature arrives once for the whole block and only the provider adapter knows
+     * which block it belongs to.
+     */
+    thinking?: LlmThinkingPart;
 }
 export interface LlmClient {
     readonly name: string;

package/dist/internal/local-agent/mcp-pool.d.ts

@@ -3,9 +3,13 @@
  *
  * `buildMcpMap` (`real-local-run.ts`) builds a fresh `McpClient` on every run, so each `send` pays
  * spawn + handshake again: 193 / 138 / 134 ms per turn, measured. The reference anchors this at the
- * session — Codex keeps its `McpConnectionManager` in `SessionServices`
- * (`core/src/state/service.rs:116`), next to a field commented *"Session-scoped model client shared
- * across turns"*, and REPLACES the runtime rather than rebuilding it.
+ * session — Codex keeps its `mcp_runtime: Arc<McpRuntime>` in `SessionServices`
+ * (`codex-rs/core/src/state/service.rs:51-58`), next to a field commented *"Session-scoped model
+ * client shared across turns"*, and REPLACES the runtime rather than rebuilding it.
+ *
+ * theokit#155: pooling the client OBJECT was never enough — the turn also has to stop closing what
+ * it does not own. See `runOwnsMcpClients` (`real-local-run.ts`) and the idempotent
+ * `StdioMcpClient.initialize()`.
  *
  * Generic over the client type on purpose: this file knows about keys, reuse and idleness, and
  * nothing about MCP. That keeps it unit-testable without spawning a server, and keeps `McpClient`'s