@theokit/sdk 4.37.2 → 4.39.0

package/dist/index.d.ts

@@ -1,13 +1,13 @@
-import { T as TheokitAgentError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot, E as ErrorMetadata } from './errors-Cua4WC9H.js';
-export { A as AgentDisposedError, c as AgentRunError, d as AgentRunErrorCode, e as AuthenticationError, f as BudgetExceedEvent, g as BudgetExceededError, h as BudgetLimit, i as BudgetMode, j as BudgetScope, k as BudgetThresholdEvent, l as BudgetWindow, C as ConfigurationError, m as ErrorCode, I as IntegrationNotConnectedError, n as InvalidTaskIdError, M as MemoryAdapterError, o as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, p as TaskNotFoundError, U as UnknownAgentError, q as UnsupportedBudgetOperationError, r as UnsupportedRunOperationError, s as UnsupportedTaskOperationError, t as isTransientError } from './errors-Cua4WC9H.js';
-import { A as AgentOptions, L as LocalOptions, P as ProviderRoutingSettings, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as ContextSettings, c as PluginsSettings, d as SkillsSettings, e as SDKAgent, f as ListAgentsOptions, g as ListResult, h as SDKAgentInfo, G as GetAgentOptions, i as ListRunsOptions, j as GetRunOptions, k as AgentOperationOptions, l as Plugin$1, m as ProviderProfile, I as InlineSkill, J as JudgeResult, n as GoalOptions, o as GoalEvent, p as GoalResult, B as BudgetTracker, q as MemoryProvider, r as MemoryId, s as PreToolCallDecision, t as SDKProvider } from './agent-SmxntivO.js';
-export { u as ActiveMemoryPassArgs, v as ActiveMemoryPassResult, w as AgentMemory, x as BudgetCheck, y as BudgetTotal, z as BudgetUsageEvent, D as CloudEnv, E as CloudRepo, F as ContextBudget, H as ContextManagerKind, K as ContextSnapshot, N as ContextSource, O as ContextSourceStatus, Q as CreateSkillSpec, R as HookName, T as InvalidateCacheOptions, U as MemoryAdapter, V as MemoryAdapterCapabilities, W as MemoryContext, X as MemoryFact, Y as MemoryProviderHandle, Z as MemoryProviderInitOptions, _ as MemoryRevision, $ as MemoryToolSchema, a0 as MemoryTurnMessage, a1 as PersonalityPreset, a2 as PluginContext, a3 as PostAssistantReplyContext, a4 as PostToolCallContext, a5 as PreToolCallContext, a6 as PreUserSendContext, a7 as PreUserSendResult, a8 as ProviderCapability, a9 as ProviderRoute, aa as ProviderTransform, ab as ProviderTransformContext, ac as RecordSessionSummaryArgs, ad as ResolvedProviderRoute, ae as RunUntilIterator, af as SDKAgentPlugins, ag as SDKAgentSkillDetail, ah as SDKAgentSkills, ai as SDKArtifact, aj as SDKContextManager, ak as SDKPluginMetadata, al as SDKProvidersManager, am as SessionLifecycleContext, an as SessionRecord, ao as SessionStore, ap as SettingSource, aq as Skill, ar as SkillsResolver, as as SkillsResolverContext, at as SystemPromptContext, au as SystemPromptMemoryFact, av as SystemPromptSkillRef, aw as TelemetrySettings, ax as ToolCallSummary, ay as ToolResultTransformContext, az as TransformContext, aA as Verdict } from './agent-SmxntivO.js';
-import { R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, b as Run, P as Processor, T as ToolResultContentBlock, c as PermissionMode, d as PermissionEngine, e as RunEventSink, S as SDKMessage } from './run-CwEJtLPE.js';
-export { A as AgentConversationTurn, f as AssistantMessage, g as CompletionCheck, h as CompletionCheckResult, i as ConversationStep, j as ConversationTurn, k as CostBreakdown, l as CostSource, m as CostStatus, D as DoomLoopThresholds, G as GenerateOptions, n as GenerateRunResult, I as ImageBlock, o as InputProcessorContext, p as InteractionUpdate, q as McpAuthConfig, r as McpHttpServerConfig, s as McpOAuthConfig, t as McpStdioServerConfig, u as MessageOrigin, v as ModelParameterValue, O as OutputProcessorContext, w as PartialToolCallUpdate, x as PermissionAction, y as PermissionEngineOptions, z as PermissionRule, B as ProcessorControls, E as ProcessorTripwire, F as ProcessorViolation, H as RunCompactBoundaryEvent, J as RunCompletionCheckEvent, K as RunErrorDetail, L as RunEvent, N as RunGitInfo, Q as RunOperation, U as RunPermissionDeniedEvent, V as RunRateLimitEvent, W as RunStatus, X as RunTaskCompletedEvent, Y as RunTaskStartedEvent, Z as RunTaskUpdatedEvent, _ as RunToCompletionOptions, $ as RunToCompletionResult, a0 as RunToolProgressEvent, a1 as RunTripwireEvent, a2 as SDKAssistantMessage, a3 as SDKImage, a4 as SDKImageDimension, a5 as SDKObjectDelta, a6 as SDKRequestMessage, a7 as SDKStatusMessage, a8 as SDKSystemMessage, a9 as SDKTaskMessage, aa as SDKThinkingMessage, ab as SDKToolUseMessage, ac as SDKUserMessage, ad as SDKUserMessageEvent, ae as SendOptions, af as ShellCommand, ag as ShellConversationTurn, ah as ShellOutput, ai as ShellOutputDeltaUpdate, aj as StepCompletedUpdate, ak as StepStartedUpdate, al as StreamToCompletionResult, am as SummaryCompletedUpdate, an as SummaryStartedUpdate, ao as SummaryUpdate, ap as TextBlock, aq as TextDeltaUpdate, ar as ThinkingCompletedUpdate, as as ThinkingDeltaUpdate, at as ThinkingMessage, au as TokenDeltaUpdate, av as TokenUsage, aw as ToolCall, ax as ToolCallCompletedUpdate, ay as ToolCallStartedUpdate, az as ToolContextMessage, aA as ToolResult, aB as ToolResultGuardOptions, aC as ToolUseBlock, aD as TurnEndedUpdate, aE as UserMessage, aF as UserMessageAppendedUpdate, aG as applyMode, aH as emitRunEvent } from './run-CwEJtLPE.js';
+import { T as TheokitAgentError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot, E as ErrorMetadata } from './errors-DjBQ4Tn8.js';
+export { A as AgentDisposedError, c as AgentRunError, d as AgentRunErrorCode, e as AuthenticationError, f as BudgetExceedEvent, g as BudgetExceededError, h as BudgetLimit, i as BudgetMode, j as BudgetScope, k as BudgetThresholdEvent, l as BudgetWindow, C as ConfigurationError, m as ErrorCode, I as IntegrationNotConnectedError, n as InvalidTaskIdError, M as MemoryAdapterError, o as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, p as TaskNotFoundError, U as UnknownAgentError, q as UnsupportedBudgetOperationError, r as UnsupportedRunOperationError, s as UnsupportedTaskOperationError, t as isTransientError } from './errors-DjBQ4Tn8.js';
+import { A as AgentOptions, L as LocalOptions, P as ProviderRoutingSettings, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as ContextSettings, c as PluginsSettings, d as SkillsSettings, e as SDKAgent, f as ListAgentsOptions, g as ListResult, h as SDKAgentInfo, G as GetAgentOptions, i as ListRunsOptions, j as GetRunOptions, k as AgentOperationOptions, l as AgentDescription, m as Plugin$1, n as ProviderProfile, I as InlineSkill, J as JudgeResult, o as GoalOptions, p as GoalEvent, q as GoalResult, B as BudgetTracker, r as MemoryProvider, s as MemoryId, t as PreToolCallDecision, u as SDKProvider } from './agent-ZCZa7YQv.js';
+export { v as ActiveMemoryPassArgs, w as ActiveMemoryPassResult, x as AgentMemory, y as AgentSubagentDescription, z as AgentToolDescription, D as BudgetCheck, E as BudgetTotal, F as BudgetUsageEvent, H as CloudEnv, K as CloudRepo, N as ContextBudget, O as ContextManagerKind, Q as ContextSnapshot, R as ContextSource, T as ContextSourceStatus, U as CreateSkillSpec, V as HookName, W as InvalidateCacheOptions, X as MemoryAdapter, Y as MemoryAdapterCapabilities, Z as MemoryContext, _ as MemoryFact, $ as MemoryProviderHandle, a0 as MemoryProviderInitOptions, a1 as MemoryRevision, a2 as MemoryToolSchema, a3 as MemoryTurnMessage, a4 as PersonalityPreset, a5 as PluginContext, a6 as PostAssistantReplyContext, a7 as PostToolCallContext, a8 as PreToolCallContext, a9 as PreUserSendContext, aa as PreUserSendResult, ab as ProviderCapability, ac as ProviderRoute, ad as ProviderTransform, ae as ProviderTransformContext, af as RecordSessionSummaryArgs, ag as ResolvedProviderRoute, ah as RunUntilIterator, ai as SDKAgentPlugins, aj as SDKAgentSkillDetail, ak as SDKAgentSkills, al as SDKArtifact, am as SDKContextManager, an as SDKPluginMetadata, ao as SDKProvidersManager, ap as SessionLifecycleContext, aq as SessionRecord, ar as SessionStore, as as SettingSource, at as Skill, au as SkillsResolver, av as SkillsResolverContext, aw as SystemPromptContext, ax as SystemPromptMemoryFact, ay as SystemPromptSkillRef, az as TelemetrySettings, aA as ToolCallSummary, aB as ToolResultTransformContext, aC as TransformContext, aD as Verdict } from './agent-ZCZa7YQv.js';
+import { R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, T as ToolResultContentBlock, b as Run, P as Processor, c as PermissionMode, d as PermissionEngine, e as RunEventSink, S as SDKMessage } from './run-i2-fUohR.js';
+export { A as AgentConversationTurn, f as AssistantMessage, g as CompletionCheck, h as CompletionCheckResult, i as ConversationStep, j as ConversationTurn, k as CostBreakdown, l as CostSource, m as CostStatus, D as DoomLoopThresholds, G as GenerateOptions, n as GenerateRunResult, I as ImageBlock, o as InputProcessorContext, p as InteractionUpdate, q as McpAuthConfig, r as McpHttpServerConfig, s as McpOAuthConfig, t as McpStdioServerConfig, u as MessageOrigin, v as ModelParameterValue, O as OutputProcessorContext, w as PartialToolCallUpdate, x as PermissionAction, y as PermissionEngineOptions, z as PermissionRule, B as ProcessorControls, E as ProcessorTripwire, F as ProcessorViolation, H as RunCompactBoundaryEvent, J as RunCompletionCheckEvent, K as RunErrorDetail, L as RunEvent, N as RunGitInfo, Q as RunOperation, U as RunPermissionDeniedEvent, V as RunRateLimitEvent, W as RunStatus, X as RunTaskCompletedEvent, Y as RunTaskStartedEvent, Z as RunTaskUpdatedEvent, _ as RunTimelineEvent, $ as RunToCompletionOptions, a0 as RunToCompletionResult, a1 as RunToolProgressEvent, a2 as RunTripwireEvent, a3 as SDKAssistantMessage, a4 as SDKImage, a5 as SDKImageDimension, a6 as SDKObjectDelta, a7 as SDKRequestMessage, a8 as SDKStatusMessage, a9 as SDKSystemMessage, aa as SDKTaskMessage, ab as SDKThinkingMessage, ac as SDKToolUseMessage, ad as SDKUserMessage, ae as SDKUserMessageEvent, af as SendOptions, ag as ShellCommand, ah as ShellConversationTurn, ai as ShellOutput, aj as ShellOutputDeltaUpdate, ak as StepCompletedUpdate, al as StepStartedUpdate, am as StreamToCompletionResult, an as SummaryCompletedUpdate, ao as SummaryStartedUpdate, ap as SummaryUpdate, aq as TextBlock, ar as TextDeltaUpdate, as as ThinkingCompletedUpdate, at as ThinkingDeltaUpdate, au as ThinkingMessage, av as TokenDeltaUpdate, aw as TokenUsage, ax as ToolCall, ay as ToolCallCompletedUpdate, az as ToolCallStartedUpdate, aA as ToolContextMessage, aB as ToolResult, aC as ToolResultGuardOptions, aD as ToolUseBlock, aE as TurnEndedUpdate, aF as UserMessage, aG as UserMessageAppendedUpdate, aH as applyMode, aI as emitRunEvent } from './run-i2-fUohR.js';
 import * as zod from 'zod';
 import { ZodType, z } from 'zod';
-import { S as StepResult } from './cron-Dx7B-3WB.js';
-export { C as Cron, a as CronCreateOptions, b as CronGetOptions, c as CronJob, d as CronJobStatus, e as CronListOptions, f as CronOperationOptions, g as CronRunOptions, h as CronRuntime, i as CronSchedulerStatus, j as CronStartOptions } from './cron-Dx7B-3WB.js';
+import { S as StepResult } from './cron-Bx7tzm5R.js';
+export { C as Cron, a as CronCreateOptions, b as CronGetOptions, c as CronJob, d as CronJobStatus, e as CronListOptions, f as CronOperationOptions, g as CronRunOptions, h as CronRuntime, i as CronSchedulerStatus, j as CronStartOptions } from './cron-Bx7tzm5R.js';
 
 /**
  * Public compaction / context-management helpers (M2-1, extended V3-3).
@@ -468,6 +468,66 @@ declare class LiveAgentRegistry {
     ids(): readonly string[];
 }
 
+/**
+ * The shape of a persisted session turn, as a HOST reads it.
+ *
+ * Lives in `types/` because it is public contract — `Agent.transcript()` returns it (theokit#146).
+ * `internal/session/session-types.ts` re-exports it so the runtime and the store keep importing
+ * from the leaf they always did.
+ *
+ * @public
+ */
+
+/**
+ * One turn of a session.
+ *
+ * Two projections of the same turn, and they answer different questions:
+ *
+ * - `text` is the flat rendering the model replay uses. A tool call folds to `[tool call] NAME` and
+ *   a result to `[tool result] <body>`.
+ * - `parts` is the same turn unflattened, for a host that draws tool CARDS: the call id, the tool
+ *   name, the arguments, and the `toolUseId` that ties a result back to its call — none of which
+ *   survive the flat form.
+ *
+ * `parts` was added in theokit#146 and is additive: `text` is byte-identical to what it always was,
+ * so every existing reader is untouched.
+ *
+ * @public
+ */
+interface SessionMessage {
+    role: "user" | "assistant";
+    text: string;
+    /**
+     * The structured view. Optional because a `SessionMessage` can also be built in memory during a
+     * live turn, where only the text projection exists. Absent means "this projection carries no
+     * structure", never "this turn had none".
+     */
+    parts?: readonly SessionMessagePart[];
+}
+/**
+ * One structured element of a {@link SessionMessage}.
+ *
+ * Deliberately a session-DISPLAY shape rather than a re-export of the internal LLM part union: the
+ * two answer different questions (what to send a provider vs. what to draw), and coupling them
+ * would make every provider-wire change a change to what hosts render.
+ *
+ * @public
+ */
+type SessionMessagePart = {
+    readonly type: "text";
+    readonly text: string;
+} | {
+    readonly type: "tool_use";
+    readonly id: string;
+    readonly name: string;
+    readonly input: Record<string, unknown>;
+} | {
+    readonly type: "tool_result";
+    readonly toolUseId: string;
+    readonly content: string | ReadonlyArray<ToolResultContentBlock>;
+    readonly isError?: boolean;
+};
+
 /**
  * Result of a one-shot {@link Agent.prompt} call.
  *
@@ -596,7 +656,7 @@ declare 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
@@ -679,6 +739,41 @@ declare class Agent {
         userText: string;
         assistantText: string;
     }): Promise<void>;
+    /**
+     * 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 transcript(agentId: string): Promise<readonly SessionMessage[]>;
+    /**
+     * 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 describe(agentId: string): Promise<AgentDescription>;
     /**
      * Permanently delete a cloud agent.
      *
@@ -723,7 +818,7 @@ declare class AgentFactory {
  *   - "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
  */
@@ -743,8 +838,8 @@ declare function computeCost(args: ComputeArgs): CostBreakdown;
  * Budget enforcement (ADRs D383, D386, EC-7/8/9).
  *
  * - `preflightCheck(name, estimatedUsd)` — em `block` mode, throw
- *   `BudgetExceededError` antes da LLM call se qualquer limit seria
- *   excedido (EC-9 — caller chama dentro do mutex section).
+ *   `BudgetExceededError` before the LLM call if any limit would be
+ *   exceeded (EC-9 — the caller invokes it inside the mutex section).
  * - `chargeAndCheckThresholds(name, actualUsd)` — apply charge ao
  *   ledger + invoca onThreshold/onExceed callbacks isolated em
  *   try/catch (EC-8).
@@ -1021,16 +1116,16 @@ declare class Provider {
      */
     static builtins(): Plugin[];
     /**
-     * O builtin que atende `modelId`, ou `undefined` quando nenhum atende.
+     * The builtin serving `modelId`, or `undefined` when none does.
      *
-     * A gramática de um id de modelo — `provider/modelo` — passa a ter **um** dono. M94: o consumidor
-     * a refazia à mão com `modelId.slice(0, modelId.indexOf('/'))`, que num id **sem barra** devolve o
-     * id menos o último caractere (`claude-opus-5` → `claude-opus-`): casa provider nenhum e o
-     * chamador seguia para o default, sem distinguir isso de um acerto. Um modelo não-roteável era
-     * indistinguível do caminho feliz.
+     * The grammar of a model id — `provider/model` — now has **one** owner. M94: the consumer
+     * redid it by hand with `modelId.slice(0, modelId.indexOf('/'))`, which on an id **without a slash** returns the
+     * id minus its last character (`claude-opus-5` -> `claude-opus-`): it matches no provider and the
+     * caller fell through to the default, without distinguishing that from a hit. A non-routable model was
+     * indistinguishable from the happy path.
      *
-     * Devolve `undefined` em vez de lançar: quem decide se a ausência é erro é o chamador, e só ele
-     * sabe se o modelo veio de um `--model` explícito (erro) ou do default (normal).
+     * Returns `undefined` instead of throwing: the caller decides whether absence is an error, and only they
+     * know whether the model came from an explicit `--model` (an error) or from the default (normal).
      *
      * @public
      */
@@ -1203,32 +1298,32 @@ interface JudgeContext {
 /** Caller-supplied tuning knobs for the judge call. */
 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.
  */
 declare class JudgeCredentialError extends TheokitAgentError {
@@ -1259,16 +1354,16 @@ interface RunUntilDeps {
 }
 
 /**
- * O marcador de continuação do goal-loop — num módulo FOLHA, de propósito.
+ * The goal-loop's continuation marker — in a LEAF module, on purpose.
  *
- * Ele vivia em `goal-loop.ts` e era importado por `run-until.ts`, que o `goal-loop` por sua vez
- * importa de volta. O ciclo estava quebrado em runtime (a volta é `import type` + `await import()`
- * dinâmico), mas o detector de ciclos conta a aresta dinâmica — e contar import dinâmico como ciclo
- * torna o gate impossível de satisfazer sem abandonar a técnica canônica de quebrar ciclos.
+ * It lived in `goal-loop.ts` and was imported by `run-until.ts`, which `goal-loop` in turn
+ * imports back. The cycle was broken at runtime (the return edge is `import type` + a dynamic
+ * `await import()`), but the cycle detector counts the dynamic edge — and counting a dynamic import as a cycle
+ * makes the gate impossible to satisfy without abandoning the canonical cycle-breaking technique.
  *
- * Uma constante compartilhada por dois módulos que se conhecem é o caso-escola de extração para
- * folha: ninguém precisa importar o outro para conhecê-la. Some o ciclo em QUALQUER detector, sem
- * política de ferramenta e sem mudar uma linha de comportamento.
+ * A constant shared by two modules that know each other is the textbook case for extraction into a
+ * leaf: neither needs to import the other to know it. The cycle disappears under ANY detector, with no
+ * tool policy and without changing a line of behavior.
  */
 declare const GOAL_CONTINUATION_MARKER = "[[theokit:goal-continuation]]";
 
@@ -1339,6 +1434,69 @@ declare function createCounterBudgetTracker(options?: CounterBudgetTrackerOption
     nextIteration(): void;
 };
 
+/**
+ * The library's single diagnostics channel — silent by default (#147).
+ *
+ * ## O problema
+ *
+ * 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.
+ *
+ * A library cannot assume `stdout`/`stderr` are free sinks. The application owns the terminal, not
+ * the dependency.
+ *
+ * ## O contrato
+ *
+ * - **`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.
+ *
+ * ## Silent by default, and how 36 suites survived the flip
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * ## 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.
+ */
+/** Receives each diagnostic message already formatted, with the trailing `\n`. */
+type DiagnosticsSink = (message: string) => void;
+/**
+ * Installs (or removes, by passing `undefined`) the diagnostics destination.
+ *
+ * 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.
+ */
+declare function setDiagnosticsSink(next: DiagnosticsSink | undefined): void;
+
 declare function withCwdMutex<T>(key: string, fn: () => Promise<T>): Promise<T>;
 
 /**
@@ -2352,4 +2510,4 @@ declare function toShareGptTrajectory(result: BatchResult, options?: {
     model?: string;
 }): ShareGptTrajectory | null;
 
-export { Agent, AgentBuilder, AgentDefinition, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, CustomTool, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DreamingSweepOptions, type DreamingSweepResult, ErrorMetadata, EventBus, type EvictReason, GOAL_CONTINUATION_MARKER, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, GoalEvent, type GoalLoopAgent, GoalOptions, GoalResult, InlineSkill, JobQueue, type JobQueueOptions, JudgeCredentialError, JudgeResult, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, PermissionEngine, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, Plugin, PluginsSettings, PreToolCallDecision, Processor, Provider, ProviderProfile, ProviderRoutingSettings, Run, RunEventSink, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, Security, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, Squad, type SquadOptions, type SquadRun, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, ToolResultContentBlock, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, estimateTokens, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, runGoalLoop, scopedConversationId, sessionScopePrefix, toShareGptTrajectory, withCwdMutex };
+export { Agent, AgentBuilder, AgentDefinition, AgentDescription, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, CustomTool, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DiagnosticsSink, type DreamingSweepOptions, type DreamingSweepResult, ErrorMetadata, EventBus, type EvictReason, GOAL_CONTINUATION_MARKER, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, GoalEvent, type GoalLoopAgent, GoalOptions, GoalResult, InlineSkill, JobQueue, type JobQueueOptions, JudgeCredentialError, JudgeResult, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, PermissionEngine, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, Plugin, PluginsSettings, PreToolCallDecision, Processor, Provider, ProviderProfile, ProviderRoutingSettings, Run, RunEventSink, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, Security, type SessionMessage, type SessionMessagePart, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, Squad, type SquadOptions, type SquadRun, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, ToolResultContentBlock, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, estimateTokens, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, withCwdMutex };

package/dist/index.js

@@ -1,56 +1,61 @@
-export { StreamObjectError } from './chunk-QFMXXUUT.js';
-export { GOAL_CONTINUATION_MARKER } from './chunk-2ONFGMBV.js';
-export { JudgeCredentialError } from './chunk-VNNK6AKU.js';
-export { GenerateObjectError } from './chunk-M5ZQBOIZ.js';
-import './chunk-ZJN6NTHE.js';
-import { Workflow, agentStep } from './chunk-SDIBMLL5.js';
-import './chunk-YDLNI7J6.js';
+export { JudgeCredentialError } from './chunk-D7IULBF2.js';
+export { StreamObjectError } from './chunk-DU7DE543.js';
+export { GOAL_CONTINUATION_MARKER } from './chunk-PY2RQOA7.js';
+export { GenerateObjectError } from './chunk-KE6XKRLQ.js';
+import './chunk-JZUPMTJY.js';
+import { Workflow, agentStep } from './chunk-MC5EINBV.js';
+import './chunk-V2RBCCN5.js';
 import './chunk-CAH3G4IS.js';
-export { Cron } from './chunk-T4QWDOG6.js';
-import { MEMORY_EMBEDDING_ADAPTERS, resolveApiKey, DEFAULT_AGENTIC_MODEL_ID, Agent } from './chunk-VYJSHGAY.js';
-export { Agent, AgentBuilder, Tool, ToolError, UsageAccumulator, computeCost, getPricingEntry } from './chunk-VYJSHGAY.js';
+export { Cron } from './chunk-KWUNN5J2.js';
+import { MEMORY_EMBEDDING_ADAPTERS, resolveApiKey, DEFAULT_AGENTIC_MODEL_ID, Agent } from './chunk-GIRD3RWH.js';
+export { Agent, AgentBuilder, Tool, ToolError, UsageAccumulator, computeCost, getPricingEntry } from './chunk-GIRD3RWH.js';
 import './chunk-2SFBB54R.js';
-import { configure, submit, list, get, cancel, subscribe } from './chunk-HEN5WXXI.js';
-export { emitRunEvent } from './chunk-HEN5WXXI.js';
-import './chunk-5SB4V74H.js';
+import { configure, submit, list, get, cancel, subscribe } from './chunk-LJX2SQV2.js';
+export { emitRunEvent } from './chunk-LJX2SQV2.js';
 import './chunk-K2BQQ445.js';
-import './chunk-YVTNFKZO.js';
-import { discoverProviderPlugins, shouldUseFixtureMode, isFixtureApiKey, httpRequest, mapOllamaTransportError, readErrorResponseBody, mapOllamaHttpError } from './chunk-GL7CFBVC.js';
-import './chunk-EXQV452X.js';
-import './chunk-EEZ7CFMM.js';
-import { lanceStoragePath, LanceIndex, readFactsFromMarkdown, defaultIndexPath, openMemoryDb, memoryDir } from './chunk-DCJ5MCJ3.js';
-import './chunk-F6Y4IEQM.js';
+import './chunk-E2FFG33C.js';
+import './chunk-KGRIHEDT.js';
+import { discoverProviderPlugins, shouldUseFixtureMode, isFixtureApiKey, httpRequest, mapOllamaTransportError, readErrorResponseBody, mapOllamaHttpError } from './chunk-ZYB6B7QJ.js';
+import './chunk-HWNVAUK4.js';
+import './chunk-5KOW3GLE.js';
+import './chunk-3I4B3OIX.js';
+import { lanceStoragePath, LanceIndex, readFactsFromMarkdown, defaultIndexPath, openMemoryDb, memoryDir } from './chunk-4F7JQZOX.js';
+import './chunk-ML5A5DOJ.js';
 import './chunk-7GFX45DD.js';
-import './chunk-ZW345YOI.js';
+import './chunk-YP67XZES.js';
+import './chunk-QKE556YD.js';
+import './chunk-SCFW5MJZ.js';
+import './chunk-OXNYIMZZ.js';
 import './chunk-FD2UT76F.js';
 import './chunk-U54XCYG3.js';
-import './chunk-FV3YEMQ7.js';
+import './chunk-RP5HQVLD.js';
 import './chunk-6X6ID4MO.js';
 import './chunk-UJ7IQJAG.js';
 import './chunk-7AD3ZTZL.js';
-import './chunk-QGDKZDPN.js';
-import './chunk-NFCKEBHI.js';
-import './chunk-MXSMAGDU.js';
-import './chunk-YHZXBDAW.js';
-import './chunk-GLUWH6JO.js';
+import './chunk-LGILIGV3.js';
+import './chunk-PI4RO4GR.js';
+import './chunk-ET6PHZRX.js';
+import './chunk-JRLXEYR4.js';
+import './chunk-BQDUEG4C.js';
+import './chunk-AECV3G5Z.js';
 import { withCwdMutex } from './chunk-2XLKLVVR.js';
 export { withCwdMutex } from './chunk-2XLKLVVR.js';
-import './chunk-XAEAMI5H.js';
-import './chunk-CSZRJ4RE.js';
+import './chunk-6EEYRFJC.js';
 import { toJsonSchema } from './chunk-4VPXM6UU.js';
-import { replaceFileAtomic } from './chunk-56OXYUZE.js';
-import './chunk-YCXMSDSP.js';
-import './chunk-6VP3XGEK.js';
+import { replaceFileAtomic } from './chunk-KX7JV5KM.js';
+import './chunk-YRXY2A5L.js';
+import './chunk-65ONFZWM.js';
 import { parseModelId } from './chunk-X2FR4OIT.js';
-import { registerBuiltins, listProviders, getCatalogCapabilities, getProviderProfile } from './chunk-77WHPVXE.js';
-import './chunk-I35DI7ES.js';
+import { registerBuiltins, listProviders, getCatalogCapabilities, getProviderProfile } from './chunk-TOTP24P6.js';
+import './chunk-DKFGUOWL.js';
 import './chunk-5NBUH3NO.js';
-import './chunk-2WFB5ZOX.js';
-import './chunk-WDGCZDRG.js';
-import './chunk-UQPDFW4E.js';
-import { BudgetExceededError, MemoryAdapterError, AuthenticationError, ConfigurationError } from './chunk-CD73YHEH.js';
-export { AgentDisposedError, AgentRunError, AuthenticationError, BudgetExceededError, ConfigurationError, IntegrationNotConnectedError, InvalidTaskIdError, MemoryAdapterError, NetworkError, RateLimitError, TaskNotFoundError, TheokitAgentError, UnknownAgentError, UnsupportedBudgetOperationError, UnsupportedRunOperationError, UnsupportedTaskOperationError, isTransientError } from './chunk-CD73YHEH.js';
-import { diag, redactSecrets, addPattern } from './chunk-TAPQWDW2.js';
+import './chunk-42IFCKQZ.js';
+import './chunk-J3UK2GMN.js';
+import './chunk-AR5MQZ3J.js';
+import { BudgetExceededError, MemoryAdapterError, AuthenticationError, ConfigurationError } from './chunk-SG5ZWT6C.js';
+export { AgentDisposedError, AgentRunError, AuthenticationError, BudgetExceededError, ConfigurationError, IntegrationNotConnectedError, InvalidTaskIdError, MemoryAdapterError, NetworkError, RateLimitError, TaskNotFoundError, TheokitAgentError, UnknownAgentError, UnsupportedBudgetOperationError, UnsupportedRunOperationError, UnsupportedTaskOperationError, isTransientError } from './chunk-SG5ZWT6C.js';
+import { diag, redactSecrets, addPattern } from './chunk-IVSD7L22.js';
+export { setDiagnosticsSink } from './chunk-IVSD7L22.js';
 import { z } from 'zod';
 import { randomUUID, createHash } from 'crypto';
 import { mkdir, readFile } from 'fs/promises';
@@ -594,16 +599,16 @@ var Provider = class _Provider {
     return listProviders().map((profile) => defineProvider(profile));
   }
   /**
-   * O builtin que atende `modelId`, ou `undefined` quando nenhum atende.
+   * The builtin serving `modelId`, or `undefined` when none does.
    *
-   * A gramática de um id de modelo — `provider/modelo` — passa a ter **um** dono. M94: o consumidor
-   * a refazia à mão com `modelId.slice(0, modelId.indexOf('/'))`, que num id **sem barra** devolve o
-   * id menos o último caractere (`claude-opus-5` → `claude-opus-`): casa provider nenhum e o
-   * chamador seguia para o default, sem distinguir isso de um acerto. Um modelo não-roteável era
-   * indistinguível do caminho feliz.
+   * The grammar of a model id — `provider/model` — now has **one** owner. M94: the consumer
+   * redid it by hand with `modelId.slice(0, modelId.indexOf('/'))`, which on an id **without a slash** returns the
+   * id minus its last character (`claude-opus-5` -> `claude-opus-`): it matches no provider and the
+   * caller fell through to the default, without distinguishing that from a hit. A non-routable model was
+   * indistinguishable from the happy path.
    *
-   * Devolve `undefined` em vez de lançar: quem decide se a ausência é erro é o chamador, e só ele
-   * sabe se o modelo veio de um `--model` explícito (erro) ou do default (normal).
+   * Returns `undefined` instead of throwing: the caller decides whether absence is an error, and only they
+   * know whether the model came from an explicit `--model` (an error) or from the default (normal).
    *
    * @public
    */
@@ -694,10 +699,8 @@ var EventBus = class {
       } catch (cause) {
         this.#handlerErrorCount += 1;
         const message = cause instanceof Error ? cause.message : String(cause);
-        process.stderr.write(
-          `[theokit-sdk] event-bus: handler for "${String(event)}" threw: ${message}
-`
-        );
+        diag(`[theokit-sdk] event-bus: handler for "${String(event)}" threw: ${message}
+`);
       }
     }
   }
@@ -717,9 +720,9 @@ var EventBus = class {
 // src/goal-loop.ts
 function runGoalLoop(agent, goal, options, depsOverride) {
   async function* wrap() {
-    const { runUntilImpl } = await import('./run-until-YZ2ODWOF.js');
+    const { runUntilImpl } = await import('./run-until-BK56WG4P.js');
     const deps = depsOverride ?? await (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 {
@@ -1166,7 +1169,7 @@ var Memory = {
       openArgs.embedding = await resolveEmbedding(opts.embedding, peer.MEMORY_EMBEDDING_ADAPTERS);
       return await peer.IndexManager.open(openArgs);
     }
-    const { IndexManager } = await import('./index-manager-KKAK7NT3.js');
+    const { IndexManager } = await import('./index-manager-ZVZUHPP7.js');
     openArgs.embedding = await resolveEmbedding(opts.embedding, MEMORY_EMBEDDING_ADAPTERS);
     return await IndexManager.open(openArgs);
   },
@@ -1600,10 +1603,10 @@ function ehAgenteConstruido(m) {
   return typeof m.send === "function";
 }
 async function materializar(def, indice) {
-  const { Agent: Agent2 } = await import('./agent-DW2J37IH.js');
+  const { Agent: Agent2 } = await import('./agent-KKZYLY5D.js');
   return Agent2.create({
-    // `AgentDefinition.model` admite o sentinel `'inherit'`, que não é um id de modelo. Herdar
-    // aqui significa "não declare nada e deixe o default valer" — passar o literal adiante criaria
+    // `AgentDefinition.model` admits the sentinel `'inherit'`, which is not a model id. Inheriting
+    // here means "declare nothing and let the default apply" — forwarding the literal would create
     // um agente pedindo um modelo chamado `inherit`.
     ...def.model !== void 0 && def.model !== "inherit" ? { model: def.model } : {},
     ...def.prompt !== void 0 ? { systemPrompt: def.prompt } : {},
@@ -1626,12 +1629,12 @@ function createSquad(options) {
   }
   return {
     run: async (input) => {
-      const run = await (await montarPipeline(agents, options.name)).run(input);
+      const run = await (await buildPipeline(agents, options.name)).run(input);
       return { result: run.output, status: run.status, steps: run.stepResults };
     }
   };
 }
-async function montarPipeline(agents, nome) {
+async function buildPipeline(agents, nome) {
   let builder = Workflow.create({ name: nome ?? "squad" });
   for (let i = 0; i < agents.length; i++) {
     const membro = agents[i];