@theokit/sdk 5.11.1 → 5.12.0

package/dist/{run-DsA5Ip2i.d.ts → sdk-agent-CTOJlWA_.d.ts}

@@ -1,1088 +1,1503 @@
+import { M as ModelSelection, b as TextBlock, C as CustomTool, P as PermissionMode, R as RunOperation } from './agent-prims-CZyxfCmS.js';
 import * as zod from 'zod';
+import { T as TheokitAgentError } from './errors-base-B5g01neU.js';
 
 /**
- * Owner: `types/` (2 of 2 importers: conversation.ts, updates.ts). The only module in this folder
- * whose owner IS the layer — it exists to break a type-only cycle BETWEEN two of its siblings, so
- * pointing it at a subsystem would name something that does not use it.
+ * Owner: `internal/local-agent/` (2 of 4 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
  *
- * Type-leaf — base message types shared between `conversation.ts` and
- * `updates.ts`. Extracted to break LOW type-only cycle #6 (audit
- * `architecture-output/final_report.md`) per plan arch-review-fixes-2026-06-06
- * § Phase 4 / T4.1 (D438).
+ * Public `MemoryAdapter` contract (T1.1, ADRs D141 / D147).
  *
- * Public surface unchanged — `types/conversation.ts` re-exports `UserMessage`
- * from this leaf so `import type { UserMessage } from "@theokit/sdk"` keeps
- * resolving.
+ * The plugin extension point `{ kind: "memory" }` (ADR D98) declares a
+ * `createProvider` factory; this file types its return value formally.
+ * Adapters implement `write` / `recall` / `delete` plus optional methods
+ * gated by `capabilities`. `MemoryId` is a branded string prefixed with
+ * the adapter id so cross-adapter use throws on `extractRawId` (EC-B).
+ *
+ * Each provider-specific package (`@theokit-memory-supermemory`, etc)
+ * exports a factory returning a `Plugin { kind: "memory" }` whose
+ * `createProvider` resolves to a `MemoryAdapter` instance.
  *
  * @public
  */
 /**
- * User-authored message in a conversation history.
+ * Branded provider memory ID. Format: `${adapterId}:${rawProviderId}`.
+ * Use `mkMemoryId` / `extractRawId` from `../memory-adapter-helpers.js`
+ * to construct and unwrap with cross-adapter safety (EC-B).
  *
  * @public
  */
-interface UserMessage {
-    text: string;
-}
-
+type MemoryId = string & {
+    readonly __brand: "MemoryId";
+};
 /**
- * Owner: `internal/agent-loop/` (1 of 1 importers). Derived from the import graph, not declared —
- * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ * Portable identity context. `userId` is the only required field —
+ * the lowest common denominator across Supermemory / Honcho / Mem0.
+ * Adapter implementations translate the optional fields to their
+ * provider's native primitives (Honcho session, Mem0 run_id, etc).
  *
+ * @public
  */
-
+interface MemoryContext {
+    /** End-user identity. */
+    userId: string;
+    /** Agent / persona writing the memory. */
+    agentId?: string;
+    /** Logical conversation / run boundary. */
+    sessionId?: string;
+    /** Tenant / workspace partition. */
+    tenantId?: string;
+    /** Free-form tags for filtering / categorization. */
+    tags?: string[];
+    /** Provider-passthrough metadata. */
+    metadata?: Record<string, unknown>;
+}
 /**
- * Single tool call event. The internal `args` and `result` shapes are NOT stable.
+ * A single memory fact returned by `recall` or `get`.
  *
  * @public
  */
-interface ToolCall {
-    callId: string;
-    name: string;
-    args?: unknown;
-    result?: unknown;
+interface MemoryFact {
+    id: MemoryId;
+    content: string;
+    /** Semantic relevance score (provider-defined scale) when result of `recall`. */
+    score?: number;
+    /** ISO 8601 timestamp of creation. */
+    createdAt?: string;
+    metadata?: Record<string, unknown>;
 }
 /**
- * Incremental text token from the assistant.
+ * Versioned snapshot of a memory's history. Only emitted by providers
+ * with `capabilities.history === true` (Mem0 today).
  *
  * @public
  */
-interface TextDeltaUpdate {
-    type: "text-delta";
-    text: string;
+interface MemoryRevision {
+    id: MemoryId;
+    content: string;
+    version: number;
+    changedAt: string;
 }
 /**
- * Incremental reasoning token.
+ * Statically declared adapter feature flags. Consumers feature-detect
+ * at compile time via `if (adapter.capabilities.history)`.
  *
  * @public
  */
-interface ThinkingDeltaUpdate {
-    type: "thinking-delta";
-    text: string;
+interface MemoryAdapterCapabilities {
+    /** Returns prior versions of a memory via `history(id)`. */
+    history: boolean;
+    /** First-class `sessionId` scoping. */
+    sessions: boolean;
+    /** First-class `tenantId` scoping. */
+    tenancy: boolean;
+    /** Provider performs reasoning over memory (e.g., Honcho dialectic). */
+    reasoning: boolean;
+    /** Exposes LLM-callable function-calling schemas. */
+    toolSchemas: boolean;
+    /** Supports background prefetch (currently informational). */
+    prefetch: boolean;
 }
 /**
- * Emitted when a reasoning block completes.
+ * One assistant-turn message in the canonical `{role, content}` shape
+ * an adapter may receive instead of a flat string when writing a turn.
  *
  * @public
  */
-interface ThinkingCompletedUpdate {
-    type: "thinking-completed";
-    thinkingDurationMs: number;
+interface MemoryTurnMessage {
+    role: "user" | "assistant" | "system";
+    content: string;
 }
 /**
- * Tool call started — args committed.
+ * OpenAI-format function-calling schema exposed to the LLM.
  *
  * @public
  */
-interface ToolCallStartedUpdate {
-    type: "tool-call-started";
-    callId: string;
-    toolCall: ToolCall;
-    modelCallId: string;
+interface MemoryToolSchema {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
 }
 /**
- * Tool call arguments streaming in incrementally.
+ * Portable third-party memory adapter contract. Implementations live
+ * in `@theokit-memory-*` packages; the SDK never imports them.
  *
  * @public
  */
-interface PartialToolCallUpdate {
-    type: "partial-tool-call";
-    callId: string;
-    toolCall: ToolCall;
-    modelCallId: string;
+interface MemoryAdapter {
+    /** Short identifier — matches the `${adapterId}` prefix in `MemoryId`. */
+    readonly id: string;
+    readonly capabilities: MemoryAdapterCapabilities;
+    /**
+     * Synchronous availability probe — no network, no I/O. Typically "do I have the credentials I
+     * need".
+     *
+     * `false` DISABLES the adapter: the runtime skips it when building the agent's memory, warns
+     * naming this `id`, and carries on with whatever other adapters said yes. When every registered
+     * adapter declines, a `write` or `recall` fails with `no_memory_adapter` and a message saying so,
+     * rather than resolving without storing anything.
+     *
+     * It was mandatory and consulted by nothing until #360, which made it a contract that read as a
+     * guarantee and provided none — a missing key surfaced mid-conversation as `auth_failed` instead.
+     */
+    isAvailable(): boolean;
+    /** One-shot initialization. Idempotent: safe to call multiple times. */
+    initialize?(): Promise<void>;
+    /**
+     * Persist a fact or full turn to memory. Returns the stored
+     * `MemoryId`. Throws `MemoryAdapterError(code: "invalid_input")` on
+     * empty content or invalid identifiers in `ctx`.
+     */
+    write(content: string | MemoryTurnMessage[], ctx: MemoryContext): Promise<MemoryId>;
+    /**
+     * Semantic recall — top-`k` facts ordered by relevance. Returns
+     * empty array when `k === 0` or no matches.
+     */
+    recall(query: string, ctx: MemoryContext, k?: number): Promise<MemoryFact[]>;
+    /**
+     * Delete a memory by id. Throws `MemoryAdapterError(code:
+     * "invalid_input")` when the id was minted by a different adapter
+     * (EC-B). Throws `code: "not_found"` when the id does not exist.
+     */
+    delete(id: MemoryId): Promise<void>;
+    list?(ctx: MemoryContext, opts?: {
+        cursor?: string;
+        limit?: number;
+    }): AsyncIterable<MemoryFact>;
+    get?(id: MemoryId): Promise<MemoryFact | null>;
+    history?(id: MemoryId): Promise<MemoryRevision[]>;
+    /** Empty array when `capabilities.toolSchemas === false`. */
+    getToolSchemas?(): MemoryToolSchema[];
+    handleToolCall?(name: string, args: Record<string, unknown>, ctx: MemoryContext): Promise<string>;
+    /** Graceful shutdown — flush queues, close connections. */
+    shutdown?(): Promise<void>;
 }
 /**
- * Tool call completed.
+ * Direct memory API exposed on `SDKAgent.memory`. Resolves to whichever
+ * memory adapter(s) are registered via `Agent.create({ plugins: [...] })`.
  *
  * @public
  */
-interface ToolCallCompletedUpdate {
-    type: "tool-call-completed";
-    callId: string;
-    toolCall: ToolCall;
-    modelCallId: string;
+interface AgentMemory {
+    /**
+     * Persist a fact. Returns the first adapter's id; in multi-adapter
+     * setups all adapters receive the write (fan-out).
+     */
+    write(content: string | MemoryTurnMessage[], ctx?: Partial<MemoryContext>): Promise<MemoryId>;
+    /** Semantic recall — merged + deduped across registered adapters. */
+    recall(query: string, ctx?: Partial<MemoryContext>, k?: number): Promise<MemoryFact[]>;
+    /** Delete a memory by id — routes to the owning adapter via prefix. */
+    delete(id: MemoryId): Promise<void>;
+    /** Returns the first registered adapter or `null` when none exists. */
+    adapter(): MemoryAdapter | null;
 }
+
 /**
- * Token count delta for usage tracking.
+ * Owner: `internal/runtime/processors/` (3 of 4 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * SE24 — guardrail processor pipeline. A `Processor` inspects/transforms/blocks
+ * the user message (input) or the model's final text (output). Processors run in
+ * order; each may rewrite its payload, `abort(reason)` to stop the run (surfaced
+ * as {@link RunResult.tripwire} + a `tripwire` run-event), or `warn()` to report
+ * a non-blocking violation. The pipeline is provider-agnostic and carries NO LLM
+ * — an LLM-classifier processor is the consumer's (delegated, see the guardrails
+ * ADR). Mirrors a peer framework's `inputProcessors` / `outputProcessors`.
  *
  * @public
  */
-interface TokenDeltaUpdate {
-    type: "token-delta";
-    tokens: number;
-}
 /**
- * Conversation step started.
+ * A policy violation surfaced to a processor's {@link Processor.onViolation}
+ * callback — on `abort()` (blocking) AND on `warn()` (non-blocking).
  *
  * @public
  */
-interface StepStartedUpdate {
-    type: "step-started";
-    stepId: number;
+interface ProcessorViolation {
+    processorId: string;
+    message: string;
+    detail?: unknown;
 }
 /**
- * Conversation step completed.
+ * Controls available to a processor while it runs: `abort()` stops the run with
+ * a tripwire; `warn()` reports a non-blocking violation and continues.
  *
  * @public
  */
-interface StepCompletedUpdate {
-    type: "step-completed";
-    stepId: number;
-    stepDurationMs: number;
+interface ProcessorControls {
+    /** Stop the run immediately with a tripwire. Throws — code after it never runs. */
+    abort(reason: string): never;
+    /** Report a non-blocking violation (fires `onViolation`); the run continues. */
+    warn(message: string, detail?: unknown): void;
+}
+/** Context passed to {@link Processor.processInput}. @public */
+interface InputProcessorContext extends ProcessorControls {
+    /** The user message text for this send. */
+    message: string;
+    agentId: string;
+}
+/** Context passed to {@link Processor.processOutput}. @public */
+interface OutputProcessorContext extends ProcessorControls {
+    /** The model's final assistant text for this run. */
+    text: string;
+    agentId: string;
 }
 /**
- * Turn ended with usage summary.
+ * A guardrail processor. Provide `processInput` (runs before the LLM) and/or
+ * `processOutput` (runs on the final text). A processor's `strategy` (block /
+ * rewrite / redact / warn) is expressed via the {@link ProcessorControls}:
+ * return the transformed payload to rewrite/redact, `abort()` to block, `warn()`
+ * to report without blocking. The core ships no strategy enum — strategies are a
+ * processor-level convention over these primitives.
  *
  * @public
  */
-interface TurnEndedUpdate {
-    type: "turn-ended";
-    usage?: {
-        inputTokens: number;
-        outputTokens: number;
-        cacheReadTokens: number;
-        cacheWriteTokens: number;
-    };
+interface Processor {
+    /** Stable id — surfaced on {@link ProcessorViolation} and {@link RunResult.tripwire}. */
+    id: string;
+    /**
+     * Transform or block the user message before it reaches the model. Return the
+     * (possibly rewritten) text; returning nothing (void) preserves the message
+     * unchanged. May be `async`.
+     */
+    processInput?(ctx: InputProcessorContext): string | Promise<string> | void;
+    /**
+     * Transform or block the model's final text before it reaches the caller.
+     * Return the (possibly redacted) text; returning nothing (void) preserves the
+     * text unchanged. May be `async`.
+     */
+    processOutput?(ctx: OutputProcessorContext): string | Promise<string> | void;
+    /** Fires on `abort()` and `warn()`. Errors thrown here are swallowed (never break the pipeline). */
+    onViolation?(violation: ProcessorViolation): void;
 }
 /**
- * User message appended to the conversation.
+ * The tripwire detail attached to {@link RunResult.tripwire} when a processor
+ * aborts, and carried by the `tripwire` run-event.
  *
  * @public
  */
-interface UserMessageAppendedUpdate {
-    type: "user-message-appended";
-    userMessage: UserMessage;
+interface ProcessorTripwire {
+    reason: string;
+    processorId: string;
 }
+
 /**
- * A conversation summary produced during a run, delivered through `SendOptions.onDelta`.
+ * Owner: `src/` (1 of 2 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
  *
- * Nothing in this package emits it. It is declared so an exhaustive `switch` over
- * {@link InteractionUpdate} compiles, and so a runtime that does produce summaries has a typed
- * channel — do not build a feature that waits on it against the local runtime.
+ * Context manager backend.
+ *
+ * - `"file"` — Read `.theokit/context.json` from the workspace (local) or the
+ *   cloned repo (cloud).
  *
  * @public
  */
-interface SummaryUpdate {
-    type: "summary";
-    summary: string;
-}
+type ContextManagerKind = "file";
 /**
- * Opens the bracket around a {@link SummaryUpdate}, for a UI that wants to show a pending state
- * before the summary text exists. Paired with {@link SummaryCompletedUpdate}.
- *
- * Like the summary variants around it, nothing in this package emits it.
+ * Context configuration accepted by `Agent.create()` via {@link AgentOptions.context}.
  *
  * @public
  */
-interface SummaryStartedUpdate {
-    type: "summary-started";
+interface ContextSettings {
+    /** Which backend reads context. Defaults to `"file"`. */
+    manager?: ContextManagerKind;
+    /** Hard cap on tokens emitted into the agent's system prompt. */
+    maxTokens?: number;
+    /**
+     * Per-file truncation cap in characters. Default 40_000 (~10k tokens).
+     * Larger files are truncated with 70%/20% head/tail + marker (ADR D155).
+     *
+     * @public
+     */
+    maxBytesPerFile?: number;
+    /**
+     * Aggregate cap across all context files in characters. Default 120_000.
+     * When total exceeds this, lower-priority sources are dropped (ADR D155).
+     *
+     * Note: context snapshot is **refresh-time** (EC-T); modifying context
+     * files mid-flight does not auto-update. Call `agent.reload()` to pick
+     * up changes.
+     *
+     * @public
+     */
+    maxBytesTotal?: number;
 }
 /**
- * Closes the bracket opened by {@link SummaryStartedUpdate}. Carries no payload — the summary text
- * itself arrives as {@link SummaryUpdate}.
+ * Inclusion state of a single context source in a {@link ContextSnapshot}.
  *
- * Like the summary variants around it, nothing in this package emits it.
+ * @public
+ */
+type ContextSourceStatus = "included" | "excluded" | "summarized";
+/**
+ * A single context source resolved by the context manager.
  *
  * @public
  */
-interface SummaryCompletedUpdate {
-    type: "summary-completed";
+interface ContextSource {
+    /** Stable identifier — usually the filename without extension. */
+    name: string;
+    /** Path relative to the workspace root, when applicable. */
+    path?: string;
+    /** Whether the source was included, dropped, or summarized to fit the budget. */
+    status: ContextSourceStatus;
+    /** Free-text reason when `status !== "included"`. */
+    reason?: string;
 }
 /**
- * Incremental output from a shell command running inside a run.
+ * Token budget used by the context manager for a single agent.
  *
- * `event` is an untyped bag on purpose: this package neither produces nor narrows it, so a consumer
- * that receives one should treat it as unvalidated input and check for the fields it needs rather
- * than casting. As with the summary variants, nothing here emits this — it exists so the
- * {@link InteractionUpdate} union covers a runtime that does.
+ * @public
+ */
+interface ContextBudget {
+    maxTokens?: number;
+    /**
+     * Either a token count or a list of token strings extracted from source
+     * content. Normalized to `<tokens>` in golden comparisons.
+     */
+    usedTokens?: number | string[];
+}
+/**
+ * Result of `agent.context.snapshot()`. Public and secret-free by design — safe
+ * to log and persist. Raw secrets, local absolute paths, and exact token values
+ * are never present.
  *
  * @public
  */
-interface ShellOutputDeltaUpdate {
-    type: "shell-output-delta";
-    event: Record<string, unknown>;
+interface ContextSnapshot {
+    runtime: "local" | "cloud";
+    sources: ContextSource[];
+    budget?: ContextBudget;
 }
 /**
- * Lowest-level raw update from a run. Pass `onDelta` to `agent.send()` to
- * consume these. Finer-grained than `SDKMessage` events.
+ * Public context manager handle exposed as `agent.context`.
  *
  * @public
  */
-type InteractionUpdate = TextDeltaUpdate | ThinkingDeltaUpdate | ThinkingCompletedUpdate | ToolCallStartedUpdate | ToolCallCompletedUpdate | PartialToolCallUpdate | TokenDeltaUpdate | StepStartedUpdate | StepCompletedUpdate | TurnEndedUpdate | UserMessageAppendedUpdate | SummaryUpdate | SummaryStartedUpdate | SummaryCompletedUpdate | ShellOutputDeltaUpdate;
+interface SDKContextManager {
+    /** Inspect what the context manager actually loaded for the agent. */
+    snapshot(): Promise<ContextSnapshot>;
+}
 
 /**
- * Owner: `internal/agent-loop/` (3 of 11 importers). Derived from the import graph, not declared —
- * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ * Owner: `sandbox/` (1 of 2 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
  *
- * SE2 — typed runtime EVENT stream, ADDITIVE to the `SDKMessage` content stream.
+ * Child-process environment policy contract (#54).
  *
- * `Run.stream()` yields `SDKMessage`s (the conversation content). `RunEvent`s are
- * out-of-band runtime-OBSERVABILITY signals — the model's content is unaffected —
- * delivered opt-in via `SendOptions.onRunEvent`. Discriminate on `type`. Mirrors
- * the Anthropic `SDKMessage`-union approach (rate-limit, permission-denied, task
- * lifecycle, compaction boundary).
+ * The DIP-correct home for the `EnvPolicy` contract type: the domain `types/`
+ * layer owns the contract, and the application-layer implementation
+ * (`internal/runtime/lifecycle/env-policy.ts`) re-exports it for back-compat
+ * while owning the runtime logic (`resolveChildEnv`, secret patterns, …).
  *
- * The union is the forward-compatible CONTRACT (discriminate exhaustively). The
- * runtime EMITS every variant end-to-end: `tool_progress` + `permission_denied`
- * (agent-loop tool-dispatch seam), `rate_limit` (pool-aware LLM client 429 retry),
- * `compact_boundary` (session auto-compaction), and `task_*` (opt-in bridge from a
- * `Task.submit({ onRunEvent })` task's lifecycle). A consumer switching on `type`
- * sees the real signal.
+ * Modes:
+ *  - `inherit-scrubbed` (DEFAULT) — inherit all parent vars EXCEPT secret-like
+ *    names (`*KEY*`, `*SECRET*`, `*TOKEN*`, `*PASSWORD*`, `*_AUTH*`). Non-breaking:
+ *    existing spawns keep every non-secret var; only secrets stop leaking.
+ *  - `core` — inherit ONLY a safe base allowlist (PATH/HOME/…); strongest scrub.
+ *  - `all` — explicit opt-out: inherit everything, secrets included.
  *
  * @public
  */
-type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunCompactionFallbackEvent | RunTripwireEvent | RunCompletionCheckEvent | RunMcpServerFailedEvent | RunMcpServerReadyEvent | RunMemoryDegradedEvent;
+type EnvPolicy = "inherit-scrubbed" | "core" | "all";
+
 /**
- * theokit#188 — an MCP server was configured but its tools could not be listed, so NONE of its
- * tools exist for this run.
+ * Owner: `internal/mcp/` (2 of 5 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
  *
- * The failure was always caught (`safeListTools` returns `[]` so one broken server cannot take the
- * turn down) and always DIAGNOSED — to `diag()`, i.e. the SDK's stderr. Nothing reached the
- * consumer, so a UI listing configured servers could show one as present while every tool it
- * provides had silently vanished. Degrading gracefully is right; degrading INVISIBLY is not.
- *
- * Emitted once per failing server per run, on the same catch path that already had both the name
- * and the reason.
  */
-interface RunMcpServerFailedEvent {
-    readonly type: "mcp_server_failed";
-    /** The server as named in the MCP configuration, so the consumer can match it to what it lists. */
-    readonly serverName: string;
-    /** Why listing failed — a spawn error, a handshake timeout, a protocol error. */
-    readonly message: string;
-}
+
 /**
- * usetheokit/theokit#426 — an MCP server came up, and these are the tools it delivered.
- *
- * The sibling of {@link RunMcpServerFailedEvent}, emitted from the same function, on the other
- * branch. Without it a consumer could see what was CONFIGURED and what BROKE, and could not tell a
- * server that came up with twelve tools from one that came up with none — which is exactly the case
- * an operator opens a server-status panel to find. `tools: []` on a healthy server is a real and
- * previously unreportable state.
- *
- * An EVENT rather than a getter, because the state is scoped to the run: with
- * `mcpLifecycle: "run"` a server may not exist by the time anyone asks, so a getter would have to
- * answer about something already gone. This says what was true when the run started.
+ * MCP server configuration accepted by `Agent.create()` and `agent.send()`.
  *
- * Emitted once per successfully-listed server per run.
+ * @public
  */
-interface RunMcpServerReadyEvent {
-    readonly type: "mcp_server_ready";
-    /** The server as named in the MCP configuration — the key a consumer already lists it under. */
-    readonly serverName: string;
+type McpStdioServerConfig = {
+    type?: "stdio";
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    /** Local agents only. Cloud rejects this field. */
+    cwd?: string;
     /**
-     * The tool names the server reported, as IT names them.
-     *
-     * Not the `mcp_<server>_<tool>` form the model sees: that spelling is sanitized for the provider,
-     * and a consumer matching it back to a server's own documentation would have to undo the mangling.
+     * #59 — per-request timeout in ms. A request that gets no reply within this
+     * window rejects with a typed `NetworkError` (`code: "mcp_timeout"`) instead
+     * of hanging the agent loop forever. Default 30_000.
      */
-    readonly tools: readonly string[];
-}
+    requestTimeoutMs?: number;
+    /**
+     * #54 — env inherit/scrub policy for the spawned MCP server process. Defaults
+     * to `"inherit-scrubbed"` (drop secret-like host vars: `*KEY*`/`*SECRET*`/
+     * `*TOKEN*`/`*PASSWORD*`/`*_AUTH*`/…) so a third-party MCP server binary cannot
+     * exfiltrate host secrets via the environment. `env` above is merged AFTER the
+     * policy and always wins. Pass `"all"` to restore full inheritance.
+     */
+    envPolicy?: EnvPolicy;
+};
 /**
- * SE24 — a guardrail processor called `abort()`; the run stops with a tripwire.
- * Delivered via {@link SendOptions.onRunEvent} (mirrors the `RunResult.tripwire`
- * surfaced on `wait()`).
+ * OAuth-style auth bundle for HTTP/SSE MCP servers.
+ *
+ * @public
  */
-interface RunTripwireEvent {
-    readonly type: "tripwire";
-    readonly reason: string;
-    readonly processorId: string;
-}
-/** A tool call is being dispatched (before its result). */
-interface RunToolProgressEvent {
-    readonly type: "tool_progress";
-    readonly toolName: string;
-    readonly toolCallId: string;
-}
-/** The provider returned a rate-limit (HTTP 429); the loop will back off + retry. */
-interface RunRateLimitEvent {
-    readonly type: "rate_limit";
-    /** Retry attempt number (1-based) about to be delayed. */
-    readonly attempt: number;
-    /** Delay in ms before the retry, when the provider/policy supplied one. */
-    readonly retryAfterMs?: number;
+interface McpAuthConfig {
+    CLIENT_ID: string;
+    CLIENT_SECRET?: string;
+    scopes?: string[];
+    /**
+     * OAuth 2.1 PKCE flow configuration (ADR D41, v1.2+). When present, the
+     * SDK runs the PKCE flow on first use and stores tokens via keychain or
+     * file. Without this, the SDK relies on `CLIENT_SECRET` + manual headers.
+     */
+    oauth?: McpOAuthConfig;
 }
 /**
- * A tool call was DENIED before dispatch — by the permission gate/plugin (SE1),
- * an operator file-hook `preToolUse`, or the fork tool-whitelist. `source`
- * discriminates which. `toolCallId` joins the event to the tool-call log.
+ * OAuth 2.1 PKCE flow descriptor. See ADR D41.
+ *
+ * @public
  */
-interface RunPermissionDeniedEvent {
-    readonly type: "permission_denied";
-    readonly toolName: string;
-    readonly toolCallId: string;
-    /** Which layer blocked the call. */
-    readonly source: "plugin" | "file_hook" | "fork_whitelist";
-    /** The rejection message surfaced to the model. */
-    readonly message: string;
-}
-/** A background task/subagent started. */
-interface RunTaskStartedEvent {
-    readonly type: "task_started";
-    readonly taskId: string;
-    readonly description?: string;
-}
-/** A background task/subagent changed state. */
-interface RunTaskUpdatedEvent {
-    readonly type: "task_updated";
-    readonly taskId: string;
-    readonly status: string;
-}
-/** A background task/subagent finished. */
-interface RunTaskCompletedEvent {
-    readonly type: "task_completed";
-    readonly taskId: string;
-    readonly status: "completed" | "failed" | "stopped";
+interface McpOAuthConfig {
+    /** Authorization endpoint (e.g. https://api.notion.com/v1/oauth/authorize). */
+    authorizationEndpoint: string;
+    /** Token endpoint (e.g. https://api.notion.com/v1/oauth/token). */
+    tokenEndpoint: string;
+    /** Where the OAuth `code` is received. */
+    redirectMode: "manual" | "localhost";
+    /** Localhost callback port (0 = random free port, default). */
+    localhostPort?: number;
+    /** Flow timeout in ms (default 300_000 = 5min). */
+    timeoutMs?: number;
 }
 /**
- * SE34 — the per-send completion check (`isTaskComplete`) produced a verdict.
- * Emitted once, after a finished run's reply is judged against
- * {@link SendOptions.completionCheck}. Distinct from `task_completed` (which is
- * background-task/subagent lifecycle). Mirrors {@link RunResult.completionCheck}.
+ * HTTP or SSE MCP server.
+ *
+ * @public
  */
-interface RunCompletionCheckEvent {
-    readonly type: "completion_check";
-    readonly complete: boolean;
-    readonly reason: string;
-}
-/** The conversation crossed a compaction boundary (history was summarized). */
-interface RunCompactBoundaryEvent {
-    readonly type: "compact_boundary";
-    readonly trigger: "manual" | "auto";
-    /** Token count before compaction, when known. */
-    readonly preTokens?: number;
-}
+type McpHttpServerConfig = {
+    type?: "http" | "sse";
+    url: string;
+    /** Passed through. `Authorization` works here. */
+    headers?: Record<string, string>;
+    auth?: McpAuthConfig;
+    /**
+     * #59 — per-request timeout in ms, enforced via `AbortSignal.timeout`. A
+     * fetch that does not respond within this window rejects with a typed
+     * `NetworkError` (`code: "mcp_timeout"`). Default 30_000.
+     */
+    requestTimeoutMs?: number;
+};
 /**
- * M77 — auto-compaction is budgeting against a FLOOR, because neither the catalog nor the caller
- * supplied a context window for this model.
- *
- * The prior behaviour was to disable auto-compaction entirely and write one line to stderr per
- * process. That is fail-OPEN: the conversation grows until the provider rejects it. This event exists
- * so a surface can say "I am running without a real budget" instead of the user discovering it at the
- * moment of failure.
+ * Union of MCP server configs.
  *
- * Not emitted when the window came from the catalog (the normal path) or from an explicit caller
- * override (the caller already knows).
+ * @public
  */
-interface RunCompactionFallbackEvent {
-    readonly type: "compaction_fallback";
-    /** The model whose window is unknown — what the user needs to fix in configuration. */
-    readonly model: string;
-    /** The floor being budgeted against, after the safety margin. */
-    readonly window: number;
-}
+type McpServerConfig = McpStdioServerConfig | McpHttpServerConfig;
+
 /**
- * A memory stage failed and the run continued without it.
- *
- * The same shape of gap {@link RunMcpServerFailedEvent} closed for MCP, in the module next door.
- * `initLoopContext` had three bare `catch { <field> = <empty> }` blocks: an init failure meant no
- * memory tool was registered, a `buildTools` failure meant no provider tools, and a `runActivePass`
- * failure meant no recalled context in the system prompt. The agent then answered without the memory
- * it was configured with, and nothing recorded it — not stderr, not this sink, not the span in scope.
+ * Owner: `src/` (4 of 9 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
  *
- * Degrading to a working agent is the right BEHAVIOUR. This event exists because the degradation was
- * unobservable, so a host UI showed a healthy run.
+ * Capability slot a provider can fulfill.
  *
- * Emitted once per failing stage per run.
+ * @public
+ */
+type ProviderCapability = "chat" | "web_search" | "image" | "embedding";
+/**
+ * A single user-declared routing rule. Maps a capability to a provider, and
+ * optionally pins a specific model.
  *
  * @public
  */
-interface RunMemoryDegradedEvent {
-    readonly type: "memory_degraded";
-    /** Which stage failed: `init`, `buildTools`, or `activePass`. */
-    readonly stage: string;
-    /** Why it failed, as the provider reported it. */
-    readonly message: string;
+interface ProviderRoute {
+    capability: ProviderCapability;
+    provider: string;
+    model?: string;
+    /**
+     * Opt-in leaked-dialect safe-parse for this route's provider (theokit#58
+     * follow-up). When `true`, a `chat_completions` finish that carries ZERO
+     * native `tool_calls` has its assistant text scanned for the Hermes
+     * `<function=…></tool_call>` dialect, and any recovered calls are surfaced as
+     * real `tool_calls` so the loop executes them — for models (qwen3-coder via
+     * OpenRouter) that intermittently leak tool calls as text. Default `false`;
+     * fail-open (a partial/unclosed block never fabricates a call). Scoped to the
+     * resolved chat chain, so a non-leaking route is unaffected.
+     */
+    extractToolCallsFromContent?: boolean;
 }
 /**
- * Receives every {@link RunEvent} a run emits, in emission order.
- *
- * Wired through `onRunEvent` on the run options. The sink is observability, never control flow: it
- * cannot cancel, alter, or delay the run, and {@link emitRunEvent} swallows anything it throws — a
- * broken sink degrades what you can see, never what the agent does.
- *
- * Synchronous by signature, so a slow sink slows the run. Hand work off rather than awaiting inside
- * it; returning a promise here would be ignored, not awaited.
+ * Provider routing configuration accepted by `Agent.create()` via
+ * {@link AgentOptions.providers}.
  *
  * @public
  */
-type RunEventSink = (event: RunEvent) => void;
-
+interface ProviderRoutingSettings {
+    /** Explicit `{ capability → provider }` map. First match wins per capability. */
+    routes: ProviderRoute[];
+    /** Provider names to try in order when a route has no provider available. */
+    fallback?: string[];
+    /**
+     * Multiple API keys per provider for same-provider key rotation
+     * (credential pool — ADRs D123-D133). When a key hits HTTP 429, 402,
+     * or 401, the SDK rotates to the next entry transparently before
+     * falling back to a different provider.
+     *
+     * Example:
+     * ```ts
+     * apiKeys: { openrouter: ["sk-or-...", "sk-or-..."], anthropic: ["..."] }
+     * ```
+     *
+     * Empty arrays and empty strings are filtered out. If a provider has
+     * exactly 1 effective key, the pool is transparent (no rotation behavior).
+     *
+     * Conflicts with the single-key shape `AgentOptions.apiKey: "..."` —
+     * use one OR the other, not both.
+     *
+     * @public
+     */
+    apiKeys?: Record<string, string[]>;
+    /**
+     * Rotation strategy per provider for the credential pool. Default is
+     * `"fill_first"` (use entries[0] until exhausted). Only consulted when
+     * `apiKeys[provider]` has ≥2 entries.
+     *
+     * @public
+     */
+    credentialPoolStrategy?: Record<string, "fill_first" | "round_robin" | "least_used" | "random">;
+}
 /**
- * Owner: `internal/runtime/processors/` (3 of 4 importers). Derived from the import graph, not declared —
- * `tests/lint/types-name-their-owner.test.ts` re-derives it.
- *
- * SE24 — guardrail processor pipeline. A `Processor` inspects/transforms/blocks
- * the user message (input) or the model's final text (output). Processors run in
- * order; each may rewrite its payload, `abort(reason)` to stop the run (surfaced
- * as {@link RunResult.tripwire} + a `tripwire` run-event), or `warn()` to report
- * a non-blocking violation. The pipeline is provider-agnostic and carries NO LLM
- * — an LLM-classifier processor is the consumer's (delegated, see the guardrails
- * ADR). Mirrors a peer framework's `inputProcessors` / `outputProcessors`.
+ * Plugins configuration accepted by `Agent.create()` via
+ * {@link AgentOptions.plugins}.
  *
  * @public
  */
+interface PluginsSettings {
+    /** Plugin names to enable. Plugin discovery is plugin-provider specific. */
+    enabled?: string[];
+}
 /**
- * A policy violation surfaced to a processor's {@link Processor.onViolation}
- * callback — on `abort()` (blocking) AND on `warn()` (non-blocking).
+ * Resolved routing decision returned by `agent.providers.routes()`. Public and
+ * secret-free by design — safe to log.
  *
  * @public
  */
-interface ProcessorViolation {
-    processorId: string;
-    message: string;
-    detail?: unknown;
+interface ResolvedProviderRoute {
+    capability: string;
+    provider: string;
+    model?: string;
+    /** Why the runtime picked this provider (e.g. `"explicit-model-provider"`). */
+    reason: string;
 }
 /**
- * Controls available to a processor while it runs: `abort()` stops the run with
- * a tripwire; `warn()` reports a non-blocking violation and continues.
+ * Public providers manager handle exposed as `agent.providers`.
  *
  * @public
  */
-interface ProcessorControls {
-    /** Stop the run immediately with a tripwire. Throws — code after it never runs. */
-    abort(reason: string): never;
-    /** Report a non-blocking violation (fires `onViolation`); the run continues. */
-    warn(message: string, detail?: unknown): void;
+interface SDKProvidersManager {
+    /** Inspect which provider serves each capability for this agent. */
+    routes(): Promise<ResolvedProviderRoute[]>;
 }
-/** Context passed to {@link Processor.processInput}. @public */
-interface InputProcessorContext extends ProcessorControls {
-    /** The user message text for this send. */
-    message: string;
-    agentId: string;
-}
-/** Context passed to {@link Processor.processOutput}. @public */
-interface OutputProcessorContext extends ProcessorControls {
-    /** The model's final assistant text for this run. */
-    text: string;
-    agentId: string;
+/**
+ * Provider catalog entry returned by `Theokit.providers.list()`.
+ *
+ * @public
+ */
+interface SDKProvider {
+    name: string;
+    displayName: string;
+    capabilities: string[];
+    isAvailable: boolean;
+    /** JSON Schema describing the env vars / fields needed to enable this provider. */
+    setupSchema: object;
 }
+
 /**
- * A guardrail processor. Provide `processInput` (runs before the LLM) and/or
- * `processOutput` (runs on the final text). A processor's `strategy` (block /
- * rewrite / redact / warn) is expressed via the {@link ProcessorControls}:
- * return the transformed payload to rewrite/redact, `abort()` to block, `warn()`
- * to report without blocking. The core ships no strategy enum — strategies are a
- * processor-level convention over these primitives.
+ * Owner: `internal/agent-loop/` (4 of 16 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ */
+
+/**
+ * Tool invocation block emitted by the assistant.
  *
  * @public
  */
-interface Processor {
-    /** Stable id — surfaced on {@link ProcessorViolation} and {@link RunResult.tripwire}. */
+interface ToolUseBlock {
+    type: "tool_use";
     id: string;
-    /**
-     * Transform or block the user message before it reaches the model. Return the
-     * (possibly rewritten) text; returning nothing (void) preserves the message
-     * unchanged. May be `async`.
-     */
-    processInput?(ctx: InputProcessorContext): string | Promise<string> | void;
-    /**
-     * Transform or block the model's final text before it reaches the caller.
-     * Return the (possibly redacted) text; returning nothing (void) preserves the
-     * text unchanged. May be `async`.
-     */
-    processOutput?(ctx: OutputProcessorContext): string | Promise<string> | void;
-    /** Fires on `abort()` and `warn()`. Errors thrown here are swallowed (never break the pipeline). */
-    onViolation?(violation: ProcessorViolation): void;
+    name: string;
+    /** Tool args are not part of the stable schema. Treat as unknown and parse defensively. */
+    input: unknown;
 }
 /**
- * The tripwire detail attached to {@link RunResult.tripwire} when a processor
- * aborts, and carried by the `tripwire` run-event.
+ * Init metadata. Emitted once at the start of a run.
  *
  * @public
  */
-interface ProcessorTripwire {
-    reason: string;
-    processorId: string;
+interface SDKSystemMessage {
+    type: "system";
+    subtype?: "init";
+    agent_id: string;
+    run_id: string;
+    model?: ModelSelection;
+    tools?: string[];
 }
-
 /**
- * Owner: `src/` (2 of 7 importers). Derived from the import graph, not declared —
- * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ * Echo of the user prompt for this run.
  *
- * Leaf module for content-block types shared by `messages.ts` (assistant/user
- * content) and `agent-prims.ts` (`CustomTool` handler results). Kept
- * import-free so both can depend on it WITHOUT the `agent-prims ↔ messages`
- * cycle (#7).
+ * @public
+ */
+interface SDKUserMessageEvent {
+    type: "user";
+    agent_id: string;
+    run_id: string;
+    message: {
+        role: "user";
+        content: TextBlock[];
+    };
+}
+/**
+ * Model text output for this run.
  *
  * @public
  */
+interface SDKAssistantMessage {
+    type: "assistant";
+    agent_id: string;
+    run_id: string;
+    message: {
+        role: "assistant";
+        content: Array<TextBlock | ToolUseBlock>;
+    };
+}
 /**
- * Plain text content block emitted by the assistant or user, or returned by a
- * tool.
+ * Reasoning content.
  *
  * @public
  */
-interface TextBlock {
-    type: "text";
+interface SDKThinkingMessage {
+    type: "thinking";
+    agent_id: string;
+    run_id: string;
     text: string;
+    thinking_duration_ms?: number;
+    /**
+     * theokit#122 — the provider's cryptographic signature for this thinking block, when it issued
+     * one. Anthropic requires a resumed conversation to replay each thinking block WITH its
+     * signature; without it the next request fails with `400 "thinking blocks cannot be modified"`,
+     * which made an extended-thinking session unresumable.
+     *
+     * Absent for providers that stream reasoning text unsigned (the OpenAI-compatible wire).
+     */
+    signature?: string;
 }
 /**
- * SE7 — a base64-encoded image block a tool can hand back as (part of) its
- * result or its `ToolError`. `media_type` is a MIME type (e.g. `"image/png"`);
- * `data` is the base64 payload without a data-URL prefix.
+ * Tool invocation lifecycle event. Emitted at start with `args`, then again on
+ * completion with `result`.
  *
- * Note: when a tool builds this from model- or user-influenced input, treat
- * `media_type` as UNTRUSTED — validate/allow-list it before rendering it in a
- * log or UI (it could carry newlines / control chars). The SDK only forwards it
- * (JSON-serialized onto the wire) and never executes or path-joins it.
+ * Tool `args` and `result` are NOT part of the stable schema — treat as unknown.
  *
  * @public
  */
-interface ImageBlock {
-    type: "image";
-    source: {
-        type: "base64";
-        media_type: string;
-        data: string;
+interface SDKToolUseMessage {
+    type: "tool_call";
+    agent_id: string;
+    run_id: string;
+    call_id: string;
+    name: string;
+    status: "running" | "completed" | "error";
+    args?: unknown;
+    result?: unknown;
+    truncated?: {
+        args?: boolean;
+        result?: boolean;
     };
 }
 /**
- * SE7 — structured content a tool result may carry: text and/or images. A tool
- * `handler` may return this (success) and a `ToolError` may carry it (failure).
- * Block-capable provider wires forward it natively; string-only provider wires
- * flatten text and fail fast on an image.
+ * Cloud run lifecycle transitions.
  *
  * @public
  */
-type ToolResultContentBlock = TextBlock | ImageBlock;
-
+interface SDKStatusMessage {
+    type: "status";
+    agent_id: string;
+    run_id: string;
+    status: "CREATING" | "RUNNING" | "FINISHED" | "ERROR" | "CANCELLED" | "EXPIRED";
+    message?: string;
+}
 /**
- * Owner: `internal/agent-loop/` (3 of 11 importers). Derived from the import graph, not
- * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
- *
- * Type-leaf — primitives shared between `agent.ts`, `run.ts`, and
- * `messages.ts`. Extracted to break LOW type-only cycles #5 and #7
- * (audit `architecture-output/final_report.md`) per plan
- * arch-review-fixes-2026-06-06 § Phase 4 / T4.1 (D438).
- *
- * Public surface unchanged — `types/agent.ts` re-exports these from this
- * leaf so `import type { ModelSelection, CustomTool } from "@theokit/sdk"`
- * keeps resolving.
+ * Task-level milestones and summaries.
  *
  * @public
  */
+interface SDKTaskMessage {
+    type: "task";
+    agent_id: string;
+    run_id: string;
+    status?: string;
+    text?: string;
+}
 /**
- * One slot in a {@link ModelSelection.params} array.
+ * Awaiting user input or approval.
  *
  * @public
  */
-interface ModelParameterValue {
-    id: string;
-    value: string;
+interface SDKRequestMessage {
+    type: "request";
+    agent_id: string;
+    run_id: string;
+    request_id: string;
 }
 /**
- * Identifies a model plus optional per-model parameters (e.g. reasoning effort).
- *
- * Use `Theokit.models.list()` to discover valid ids and parameter definitions.
+ * Partial object emitted during `Agent.streamObject<T>` streaming (ADR D45).
+ * `partial` is `DeepPartial<z.infer<T>>` at the typed iterator level but
+ * erased to `unknown` here because SDKMessage union is non-generic.
  *
  * @public
  */
-interface ModelSelection {
-    id: string;
-    params?: ModelParameterValue[];
-    /**
-     * M94 — the model's context window, in tokens. Becomes the window resolver's `override`.
-     *
-     * It exists for models with NO catalog entry: without it, a 400k model was budgeted against the
-     * 128k floor and compacted ~3x more than it needed to. A value above what the catalog knows is
-     * clamped — declaring 10M does not blow past the provider.
-     */
-    contextWindow?: number;
-    /**
-     * #332 — the endpoint THIS model should reach, for OpenAI-compatible and local servers.
-     *
-     * Without it the base URL came only from a process-wide env var (`OLLAMA_HOST`) or the provider
-     * profile's shipped default, so every `ollama/*` model in a process shared one host — an app
-     * could not run a small model on localhost and a large one on a GPU box.
-     *
-     * It outranks the env var deliberately: with the env var winning, whoever set it for one model
-     * would keep hijacking every other one, which is the same bug wearing a hat.
-     *
-     * Leaving it unset keeps the zero-config path exactly as it was — `ollama/qwen2.5:3b` still
-     * resolves to `http://localhost:11434` from the profile, with no key and no setup.
-     */
-    url?: string;
+interface SDKObjectDelta {
+    type: "object_delta";
+    agent_id: string;
+    run_id: string;
+    partial: unknown;
+    attempt: number;
 }
 /**
- * SE12 — a read-only, text-only projection of one turn of the run's conversation,
- * exposed to a tool handler via `ctx.messages`. Content is flattened to text; tool
- * calls / results and non-text parts are dropped, and turns that project to empty
- * text are omitted. Consumed by `defineSubAgent`'s `messageFilter` to forward
- * (a subset of) the supervisor transcript to a subagent.
+ * Discriminated union of all stream events. Discriminate on `type`.
  *
- * `role` includes `"system"` for type-completeness with the wire message shape,
- * but the system prompt travels on a separate request field — a `"system"` entry
- * does NOT appear in the current projection.
+ * All events include `agent_id` and `run_id`.
  *
  * @public
  */
-interface ToolContextMessage {
-    role: "system" | "user" | "assistant";
-    content: string;
-}
+type SDKMessage = SDKSystemMessage | SDKUserMessageEvent | SDKAssistantMessage | SDKThinkingMessage | SDKToolUseMessage | SDKStatusMessage | SDKTaskMessage | SDKRequestMessage | SDKObjectDelta;
+
 /**
- * Local function tool declared per-agent via {@link AgentOptions.tools}. The
- * handler runs in-process; no MCP server is involved. The SDK serializes
- * `name`, `description`, and `inputSchema` into the model's tool catalog.
+ * Owner: `internal/runtime/lifecycle/` (1 of 1 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
  *
- * Handlers MUST be re-passed on `Agent.resume()` because closures cannot be
- * persisted. The tool catalog (name + description + schema) is NOT serialized.
+ * Fork primitive public type contracts (T1.2, ADRs D110-D114).
+ *
+ * Extracted into a leaf type module (arch-review ADR 0001) so the public
+ * `types/agent.ts` barrel can reference `ForkOptions`/`ForkResult` without
+ * importing the `internal/runtime/lifecycle/fork-agent.ts` implementation — which in
+ * turn imports back from `types/agent.ts`. That mutual reference created a
+ * type-only `madge` cycle. These interfaces are self-contained (no SDKAgent
+ * / AgentOptions references), so co-locating them here breaks the cycle with
+ * no runtime change. `fork-agent.ts` re-exports them for back-compat.
+ */
+/**
+ * Caller-supplied fork configuration. See `forkAgentImpl`.
  *
  * @public
  */
-interface CustomTool {
+interface ForkOptions {
     /**
-     * Tool name surfaced to the LLM. Must match `^[a-zA-Z][a-zA-Z0-9_-]{0,63}$`
-     * and must not collide with `shell`, `memory_search`, `memory_get`, or any
-     * `mcp_*` prefix (reserved for the SDK's built-in tools).
+     * Tool subset visible to the fork. Names must match the canonical (post-repair)
+     * tool name — typically lowercase. Tools not in this set return a `tool_result`
+     * with `"Tool blocked by fork whitelist"` content (EC-H).
      */
-    name: string;
-    /** Description surfaced to the LLM. Required — drives tool-selection accuracy. */
-    description: string;
-    /** JSON Schema (Draft-7 subset) describing the `input` argument. Must be `type: "object"`. */
-    inputSchema: Record<string, unknown>;
-    /**
-     * Local handler invoked when the model emits `tool_use` for this tool.
-     * Returns a string OR structured content blocks (SE7 — text + image, e.g. a
-     * screenshot) that become the `tool_result.content` surfaced back to the
-     * model. Throws → SDK converts to `tool_result` with `isError: true` and the
-     * error `message` as content; throw a `ToolError` to carry a clean message or
-     * multimodal error content. #65 — an optional 2nd `ToolContext` argument
-     * carries the run's `AbortSignal`; single-argument handlers are unaffected. M7
-     * — the same `ctx` also carries an optional user `context` (provided once via
-     * `SendOptions.context`), so shared config like a `projectRoot` is read by
-     * every tool instead of baked into each factory. SE12 — `ctx.messages` is a
-     * read-only, text-only projection of the current turn's transcript (see
-     * {@link ToolContextMessage}); `defineSubAgent`'s `messageFilter` consumes it.
-     * #119 — `ctx.threadId` is the run's session identity (the key passed to
-     * `Agent.getOrCreate(sessionId, …)`, or the agent's own id), so a stateful tool
-     * shared across sessions can scope its state per session instead of leaking it.
-     */
-    handler: (input: Record<string, unknown>, ctx?: {
-        signal?: AbortSignal;
-        context?: unknown;
-        messages?: readonly ToolContextMessage[];
-        threadId?: string;
-    }) => string | ToolResultContentBlock[] | Promise<string | ToolResultContentBlock[]>;
-}
-/**
- * How the permission engine treats the UNMATCHED verdict.
- *
- * - `default` — ask.
- * - `plan` — read-only.
- * - `acceptEdits` — auto-approve the unmatched verdict, but still honour an explicit `ask` rule.
- * - `bypass` (alias `bypassPermissions`, the Anthropic-exact name) — everything allowed EXCEPT an
- *   explicit `deny`. Never asks.
- *
- * G7 / DIP — defined in this type leaf rather than in `permission-engine.ts`, which is a RUNTIME
- * module. `types/agent.ts`, `types/run.ts` and `types/plugin.ts` all need the union, and each one
- * used to reach into the engine for it: three of the nine violations the `types-dont-import-runtime`
- * rule reported the moment it was able to see type-only edges at all. The engine re-exports it, so
- * `import type { PermissionMode } from "@theokit/sdk"` is unchanged.
- *
- * @public
- */
-type PermissionMode = "default" | "plan" | "acceptEdits" | "bypass" | "bypassPermissions";
-
+    allowedTools: Set<string>;
+    /** Task prompt sent to the fork. */
+    prompt: string;
+    /** Override system prompt. Default: byte-identical inheritance from parent (D112). */
+    systemPrompt?: string;
+    /** Memory write provenance tag (D114). Default `"fork"`. */
+    forkOrigin?: string;
+}
 /**
- * Owner: `internal/agent-loop/` (4 of 8 importers). Derived from the import graph, not
- * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ * Outcome of a fork run.
  *
+ * @public
  */
+interface ForkResult {
+    /** Final agent response text (`undefined` when the fork produced no result). */
+    result: string | undefined;
+    /** Tool calls executed inside the fork. */
+    toolCalls: ReadonlyArray<{
+        name: string;
+        input: Record<string, unknown>;
+    }>;
+    /** Aggregate token usage reported by the run. */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
 
 /**
- * Plain assistant message in a conversation history.
+ * Owner: `internal/judge/` (3 of 8 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * M80 — the terminal verdicts a judge can return.
+ *
+ * `"blocked"` was added here in this milestone. `GoalResult.status` already carried it, but the
+ * judge had no way to EMIT it: its vocabulary was `done | continue | skipped`, so facing a real
+ * blocker it could only say `continue` — and the loop repeated the same turn until it blew the
+ * budget, reporting `failed` on a limit rather than `blocked` on impossibility. Two different causes
+ * with the same visible outcome.
  *
  * @public
  */
-interface AssistantMessage {
-    text: string;
-}
+type Verdict = "done" | "continue" | "skipped" | "blocked";
 /**
- * Reasoning step in a conversation history.
+ * M80 — the result of a judge call, now public.
+ *
+ * It was `internal/`, so a consumer wanting to type the return — to react to `blocked` without a
+ * magic string — had to redeclare the shape. It is the same duplication M78 closed for the error
+ * hierarchy: without a public surface, reimplementing is the only legal way out for anyone behind
+ * the layer boundary.
  *
  * @public
  */
-interface ThinkingMessage {
-    text: string;
-    thinkingDurationMs?: number;
+interface JudgeResult {
+    verdict: Verdict;
+    reason: string;
     /**
-     * theokit#122 — the provider's cryptographic signature for this thinking block, when it issued
-     * one. Persisted with the block so a resumed conversation can replay it byte-identically;
-     * Anthropic rejects a modified or unsigned thinking block with
-     * `400 "thinking blocks cannot be modified"`.
+     * `true` when the text did not start with one of the canonical prefixes. The verdict becomes
+     * `"continue"` (fail-safe) so the loop does not stop too early; the caller counts consecutive
+     * failures and gives up via `maxConsecutiveJudgeFailures`.
      */
-    signature?: string;
+    parseFailed: boolean;
 }
 /**
- * Shell command executed during a run.
+ * Single event emitted while iterating a goal-driven loop — the public event type of
+ * {@link SDKAgent.runUntil} (ADRs D115-D117). Discriminated union by the `type` field so
+ * consumers can `switch (event.type)` with full TypeScript exhaustiveness; mirrors the
+ * {@link import("../stream-object.js").StreamObjectEvent} pattern (ADR D39).
+ *
+ * Five variants:
+ *
+ * - `turn_start` — the agent is about to invoke `send()`. Emitted once
+ *   per turn.
+ * - `agent_response` — the agent's `send()` resolved; carries the text
+ *   reply.
+ * - `judge_verdict` — the auxiliary judge model evaluated the response.
+ *   `parseFailed: true` indicates the judge returned a malformed reply
+ *   (fail-safe verdict = `continue`, see ADR D121).
+ * - `continuation` — the judge ruled `continue`; carries the prompt that
+ *   was sent on THIS turn (i.e., the input that produced the agent
+ *   response just yielded). Useful for consumers who want to audit the
+ *   exact continuation message that drove each iteration. The prompt
+ *   for the NEXT turn is composed lazily at the start of that turn
+ *   from the latest `agent_response.content`.
+ * - `status_change` — transition of the overall goal state. Always
+ *   emitted once at start (`active`) and once at end
+ *   (`completed | failed | paused`).
+ *
+ * @public
+ */
+type GoalEvent = {
+    type: "turn_start";
+    turn: number;
+    goal: string;
+} | {
+    type: "agent_response";
+    turn: number;
+    content: string;
+} | {
+    type: "judge_verdict";
+    turn: number;
+    /** M80 — `"blocked"` was added: the judge can declare impossibility, not just "continue". */
+    verdict: "done" | "continue" | "skipped" | "blocked";
+    reason: string;
+    parseFailed: boolean;
+} | {
+    type: "continuation";
+    turn: number;
+    prompt: string;
+} | {
+    type: "status_change";
+    status: "active" | "paused" | "completed" | "failed" | "budget_limited" | "blocked";
+    reason: string;
+};
+/**
+ * Return value of the `runUntil` async generator. Consumer reads via
+ * `const { value } = await gen.next()` (when `done: true`).
  *
  * @public
  */
-interface ShellCommand {
-    command: string;
-    workingDirectory?: string;
+interface GoalResult {
+    status: "completed" | "failed" | "paused" | "budget_limited" | "blocked";
+    turnsUsed: number;
+    /** M55 — tokens summed across the loop (0 when `usage` was absent — fail-open). */
+    tokensUsed: number;
+    finalResponse: string | undefined;
 }
 /**
- * Output of a shell command.
+ * Return type of {@link import("../internal/local-agent/local-agent.js").LocalAgent.runUntil}.
+ * Extracted so the LocalAgent method signature stays a single line (G8 LoC budget).
  *
  * @public
  */
-interface ShellOutput {
-    stdout: string;
-    stderr: string;
-    exitCode: number;
-}
+type RunUntilIterator = AsyncGenerator<GoalEvent, GoalResult, void>;
 /**
- * Result of a tool invocation. Pairs with the preceding `toolCall` step
- * by `callId`. `isError: true` when the tool returned a failure result.
- *
- * T2.3 — added so `Run.conversation()` surfaces the full interaction
- * including tool results (parity with OpenAI Agents `RunResult.new_items`).
+ * Per-call configuration for `Agent.runUntil`.
  *
  * @public
  */
-interface ToolResult {
-    callId: string;
-    name: string;
-    result: string;
-    isError: boolean;
+interface GoalOptions {
+    /** Hard cap on iterations (safety net against runaway). Default `20`. */
+    maxTurns?: number;
+    /**
+     * M55 — token budget (Codex ext/goal parity, tool.rs:454-465). Sums `run.wait().usage.totalTokens`
+     * per turn; on crossing it, the loop stops with status `budget_limited`. Omitted => unlimited (only
+     * maxTurns). A missing `usage` never blows the budget (fail-open).
+     */
+    tokenBudget?: number;
+    /** Bail after N consecutive judge parse failures. Default `3` (ADR D121). */
+    maxConsecutiveJudgeFailures?: number;
+    /** Judge model identifier. Default `"openai/gpt-4o-mini"` (ADR D119). */
+    judgeModel?: string;
+    /** Override env for the judge auxiliary agent. Default `OPENROUTER_API_KEY` (EC-A). */
+    judgeApiKey?: string;
+    /**
+     * M80 — the model of the DRIVEN agent, the basis for deriving the judge when `judgeModel` is
+     * omitted.
+     *
+     * It exists because the fixed default (`openai/gpt-4o-mini`) only resolves on OpenRouter: an
+     * Anthropic key gives 404, an OAuth bearer gives 401, and the goal burned 3 turns before failing
+     * with a misleading reason. A judge running on the chat's own model works wherever chat works.
+     */
+    agentModel?: string;
+    /** Optional subgoals fed to the judge prompt. */
+    subgoals?: string[];
+    /**
+     * Cancel mid-loop via `AbortController.signal`. The generator yields
+     * a `status_change: paused` event and returns at the next turn
+     * boundary (ADR D117).
+     */
+    signal?: AbortSignal;
 }
+
 /**
- * A single step inside an agent turn, discriminated by `type`: an assistant message, a tool call, the
- * tool result that pairs with it, or a thinking block.
+ * Owner: `types/` (2 of 2 importers: conversation.ts, updates.ts). The only module in this folder
+ * whose owner IS the layer — it exists to break a type-only cycle BETWEEN two of its siblings, so
+ * pointing it at a subsystem would name something that does not use it.
  *
- * It reaches a caller by two routes that are NOT the same set. `Run.conversation()` returns the
- * accumulated steps of a finished turn and includes `thinkingMessage`. `SendOptions.onStep` fires
- * live while the turn runs and emits `assistantMessage`, `toolCall` and `toolResult` — but never
- * `thinkingMessage`, which the loop builds only into the accumulated conversation. A UI that wants
- * reasoning as it happens should read the `thinking-delta` / `thinking-completed` variants of
- * `InteractionUpdate` through `onDelta` instead.
- *
- * `toolCall` and its `toolResult` arrive as an ordered pair matched by `callId`; a call whose result
- * never came back has no `toolResult` step, so do not assume they alternate. Where a
- * `thinkingMessage` exists it precedes the `assistantMessage` of the same turn — that is the order
- * the provider requires of the message the block belongs to, not a presentation choice.
+ * Type-leaf — base message types shared between `conversation.ts` and
+ * `updates.ts`. Extracted to break LOW type-only cycle #6 (audit
+ * `architecture-output/final_report.md`) per plan arch-review-fixes-2026-06-06
+ * § Phase 4 / T4.1 (D438).
  *
- * @public
- */
-type ConversationStep = {
-    type: "assistantMessage";
-    message: AssistantMessage;
-} | {
-    type: "toolCall";
-    message: ToolCall;
-} | {
-    type: "toolResult";
-    message: ToolResult;
-} | {
-    type: "thinkingMessage";
-    message: ThinkingMessage;
-};
-/**
- * Agent turn: user message + assistant/tool/thinking steps.
+ * Public surface unchanged — `types/conversation.ts` re-exports `UserMessage`
+ * from this leaf so `import type { UserMessage } from "@theokit/sdk"` keeps
+ * resolving.
  *
  * @public
  */
-interface AgentConversationTurn {
-    userMessage?: UserMessage;
-    steps: ConversationStep[];
-}
 /**
- * Shell turn: a command and its output.
+ * User-authored message in a conversation history.
  *
  * @public
  */
-interface ShellConversationTurn {
-    shellCommand?: ShellCommand;
-    shellOutput?: ShellOutput;
+interface UserMessage {
+    text: string;
 }
+
 /**
- * Structured per-turn view of a run.
+ * Owner: `internal/agent-loop/` (1 of 1 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
  *
- * @public
  */
-type ConversationTurn = {
-    type: "agentConversationTurn";
-    turn: AgentConversationTurn;
-} | {
-    type: "shellConversationTurn";
-    turn: ShellConversationTurn;
-};
 
 /**
- * Owner: `sandbox/` (1 of 2 importers). Derived from the import graph, not
- * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
- *
- * Child-process environment policy contract (#54).
- *
- * The DIP-correct home for the `EnvPolicy` contract type: the domain `types/`
- * layer owns the contract, and the application-layer implementation
- * (`internal/runtime/lifecycle/env-policy.ts`) re-exports it for back-compat
- * while owning the runtime logic (`resolveChildEnv`, secret patterns, …).
- *
- * Modes:
- *  - `inherit-scrubbed` (DEFAULT) — inherit all parent vars EXCEPT secret-like
- *    names (`*KEY*`, `*SECRET*`, `*TOKEN*`, `*PASSWORD*`, `*_AUTH*`). Non-breaking:
- *    existing spawns keep every non-secret var; only secrets stop leaking.
- *  - `core` — inherit ONLY a safe base allowlist (PATH/HOME/…); strongest scrub.
- *  - `all` — explicit opt-out: inherit everything, secrets included.
+ * Single tool call event. The internal `args` and `result` shapes are NOT stable.
  *
  * @public
  */
-type EnvPolicy = "inherit-scrubbed" | "core" | "all";
-
+interface ToolCall {
+    callId: string;
+    name: string;
+    args?: unknown;
+    result?: unknown;
+}
 /**
- * Owner: `internal/mcp/` (2 of 5 importers). Derived from the import graph, not declared —
- * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ * Incremental text token from the assistant.
  *
+ * @public
  */
-
+interface TextDeltaUpdate {
+    type: "text-delta";
+    text: string;
+}
 /**
- * MCP server configuration accepted by `Agent.create()` and `agent.send()`.
+ * Incremental reasoning token.
  *
  * @public
  */
-type McpStdioServerConfig = {
-    type?: "stdio";
-    command: string;
-    args?: string[];
-    env?: Record<string, string>;
-    /** Local agents only. Cloud rejects this field. */
-    cwd?: string;
-    /**
-     * #59 — per-request timeout in ms. A request that gets no reply within this
-     * window rejects with a typed `NetworkError` (`code: "mcp_timeout"`) instead
-     * of hanging the agent loop forever. Default 30_000.
-     */
-    requestTimeoutMs?: number;
-    /**
-     * #54 — env inherit/scrub policy for the spawned MCP server process. Defaults
-     * to `"inherit-scrubbed"` (drop secret-like host vars: `*KEY*`/`*SECRET*`/
-     * `*TOKEN*`/`*PASSWORD*`/`*_AUTH*`/…) so a third-party MCP server binary cannot
-     * exfiltrate host secrets via the environment. `env` above is merged AFTER the
-     * policy and always wins. Pass `"all"` to restore full inheritance.
-     */
-    envPolicy?: EnvPolicy;
-};
+interface ThinkingDeltaUpdate {
+    type: "thinking-delta";
+    text: string;
+}
 /**
- * OAuth-style auth bundle for HTTP/SSE MCP servers.
+ * Emitted when a reasoning block completes.
  *
  * @public
  */
-interface McpAuthConfig {
-    CLIENT_ID: string;
-    CLIENT_SECRET?: string;
-    scopes?: string[];
-    /**
-     * OAuth 2.1 PKCE flow configuration (ADR D41, v1.2+). When present, the
-     * SDK runs the PKCE flow on first use and stores tokens via keychain or
-     * file. Without this, the SDK relies on `CLIENT_SECRET` + manual headers.
-     */
-    oauth?: McpOAuthConfig;
+interface ThinkingCompletedUpdate {
+    type: "thinking-completed";
+    thinkingDurationMs: number;
 }
 /**
- * OAuth 2.1 PKCE flow descriptor. See ADR D41.
+ * Tool call started — args committed.
  *
  * @public
  */
-interface McpOAuthConfig {
-    /** Authorization endpoint (e.g. https://api.notion.com/v1/oauth/authorize). */
-    authorizationEndpoint: string;
-    /** Token endpoint (e.g. https://api.notion.com/v1/oauth/token). */
-    tokenEndpoint: string;
-    /** Where the OAuth `code` is received. */
-    redirectMode: "manual" | "localhost";
-    /** Localhost callback port (0 = random free port, default). */
-    localhostPort?: number;
-    /** Flow timeout in ms (default 300_000 = 5min). */
-    timeoutMs?: number;
+interface ToolCallStartedUpdate {
+    type: "tool-call-started";
+    callId: string;
+    toolCall: ToolCall;
+    modelCallId: string;
 }
 /**
- * HTTP or SSE MCP server.
+ * Tool call arguments streaming in incrementally.
  *
  * @public
  */
-type McpHttpServerConfig = {
-    type?: "http" | "sse";
-    url: string;
-    /** Passed through. `Authorization` works here. */
-    headers?: Record<string, string>;
-    auth?: McpAuthConfig;
-    /**
-     * #59 — per-request timeout in ms, enforced via `AbortSignal.timeout`. A
-     * fetch that does not respond within this window rejects with a typed
-     * `NetworkError` (`code: "mcp_timeout"`). Default 30_000.
-     */
-    requestTimeoutMs?: number;
-};
+interface PartialToolCallUpdate {
+    type: "partial-tool-call";
+    callId: string;
+    toolCall: ToolCall;
+    modelCallId: string;
+}
 /**
- * Union of MCP server configs.
+ * Tool call completed.
  *
  * @public
  */
-type McpServerConfig = McpStdioServerConfig | McpHttpServerConfig;
-
+interface ToolCallCompletedUpdate {
+    type: "tool-call-completed";
+    callId: string;
+    toolCall: ToolCall;
+    modelCallId: string;
+}
 /**
- * Owner: `internal/agent-loop/` (4 of 16 importers). Derived from the import graph, not declared —
- * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ * Token count delta for usage tracking.
  *
+ * @public
  */
-
+interface TokenDeltaUpdate {
+    type: "token-delta";
+    tokens: number;
+}
 /**
- * Tool invocation block emitted by the assistant.
+ * Conversation step started.
  *
  * @public
  */
-interface ToolUseBlock {
-    type: "tool_use";
-    id: string;
-    name: string;
-    /** Tool args are not part of the stable schema. Treat as unknown and parse defensively. */
-    input: unknown;
+interface StepStartedUpdate {
+    type: "step-started";
+    stepId: number;
 }
 /**
- * Init metadata. Emitted once at the start of a run.
+ * Conversation step completed.
  *
  * @public
  */
-interface SDKSystemMessage {
-    type: "system";
-    subtype?: "init";
-    agent_id: string;
-    run_id: string;
-    model?: ModelSelection;
-    tools?: string[];
+interface StepCompletedUpdate {
+    type: "step-completed";
+    stepId: number;
+    stepDurationMs: number;
 }
 /**
- * Echo of the user prompt for this run.
+ * Turn ended with usage summary.
  *
  * @public
  */
-interface SDKUserMessageEvent {
-    type: "user";
-    agent_id: string;
-    run_id: string;
-    message: {
-        role: "user";
-        content: TextBlock[];
+interface TurnEndedUpdate {
+    type: "turn-ended";
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
     };
 }
 /**
- * Model text output for this run.
+ * User message appended to the conversation.
  *
  * @public
  */
-interface SDKAssistantMessage {
-    type: "assistant";
-    agent_id: string;
-    run_id: string;
-    message: {
-        role: "assistant";
-        content: Array<TextBlock | ToolUseBlock>;
-    };
+interface UserMessageAppendedUpdate {
+    type: "user-message-appended";
+    userMessage: UserMessage;
 }
 /**
- * Reasoning content.
+ * A conversation summary produced during a run, delivered through `SendOptions.onDelta`.
+ *
+ * Nothing in this package emits it. It is declared so an exhaustive `switch` over
+ * {@link InteractionUpdate} compiles, and so a runtime that does produce summaries has a typed
+ * channel — do not build a feature that waits on it against the local runtime.
  *
  * @public
  */
-interface SDKThinkingMessage {
-    type: "thinking";
-    agent_id: string;
-    run_id: string;
-    text: string;
-    thinking_duration_ms?: number;
-    /**
-     * theokit#122 — the provider's cryptographic signature for this thinking block, when it issued
-     * one. Anthropic requires a resumed conversation to replay each thinking block WITH its
-     * signature; without it the next request fails with `400 "thinking blocks cannot be modified"`,
-     * which made an extended-thinking session unresumable.
+interface SummaryUpdate {
+    type: "summary";
+    summary: string;
+}
+/**
+ * Opens the bracket around a {@link SummaryUpdate}, for a UI that wants to show a pending state
+ * before the summary text exists. Paired with {@link SummaryCompletedUpdate}.
+ *
+ * Like the summary variants around it, nothing in this package emits it.
+ *
+ * @public
+ */
+interface SummaryStartedUpdate {
+    type: "summary-started";
+}
+/**
+ * Closes the bracket opened by {@link SummaryStartedUpdate}. Carries no payload — the summary text
+ * itself arrives as {@link SummaryUpdate}.
+ *
+ * Like the summary variants around it, nothing in this package emits it.
+ *
+ * @public
+ */
+interface SummaryCompletedUpdate {
+    type: "summary-completed";
+}
+/**
+ * Incremental output from a shell command running inside a run.
+ *
+ * `event` is an untyped bag on purpose: this package neither produces nor narrows it, so a consumer
+ * that receives one should treat it as unvalidated input and check for the fields it needs rather
+ * than casting. As with the summary variants, nothing here emits this — it exists so the
+ * {@link InteractionUpdate} union covers a runtime that does.
+ *
+ * @public
+ */
+interface ShellOutputDeltaUpdate {
+    type: "shell-output-delta";
+    event: Record<string, unknown>;
+}
+/**
+ * Lowest-level raw update from a run. Pass `onDelta` to `agent.send()` to
+ * consume these. Finer-grained than `SDKMessage` events.
+ *
+ * @public
+ */
+type InteractionUpdate = TextDeltaUpdate | ThinkingDeltaUpdate | ThinkingCompletedUpdate | ToolCallStartedUpdate | ToolCallCompletedUpdate | PartialToolCallUpdate | TokenDeltaUpdate | StepStartedUpdate | StepCompletedUpdate | TurnEndedUpdate | UserMessageAppendedUpdate | SummaryUpdate | SummaryStartedUpdate | SummaryCompletedUpdate | ShellOutputDeltaUpdate;
+
+/**
+ * Owner: `internal/agent-loop/` (3 of 11 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * SE2 — typed runtime EVENT stream, ADDITIVE to the `SDKMessage` content stream.
+ *
+ * `Run.stream()` yields `SDKMessage`s (the conversation content). `RunEvent`s are
+ * out-of-band runtime-OBSERVABILITY signals — the model's content is unaffected —
+ * delivered opt-in via `SendOptions.onRunEvent`. Discriminate on `type`. Mirrors
+ * the Anthropic `SDKMessage`-union approach (rate-limit, permission-denied, task
+ * lifecycle, compaction boundary).
+ *
+ * The union is the forward-compatible CONTRACT (discriminate exhaustively). The
+ * runtime EMITS every variant end-to-end: `tool_progress` + `permission_denied`
+ * (agent-loop tool-dispatch seam), `rate_limit` (pool-aware LLM client 429 retry),
+ * `compact_boundary` (session auto-compaction), and `task_*` (opt-in bridge from a
+ * `Task.submit({ onRunEvent })` task's lifecycle). A consumer switching on `type`
+ * sees the real signal.
+ *
+ * @public
+ */
+type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunCompactionFallbackEvent | RunTripwireEvent | RunCompletionCheckEvent | RunMcpServerFailedEvent | RunMcpServerReadyEvent | RunMemoryDegradedEvent;
+/**
+ * theokit#188 — an MCP server was configured but its tools could not be listed, so NONE of its
+ * tools exist for this run.
+ *
+ * The failure was always caught (`safeListTools` returns `[]` so one broken server cannot take the
+ * turn down) and always DIAGNOSED — to `diag()`, i.e. the SDK's stderr. Nothing reached the
+ * consumer, so a UI listing configured servers could show one as present while every tool it
+ * provides had silently vanished. Degrading gracefully is right; degrading INVISIBLY is not.
+ *
+ * Emitted once per failing server per run, on the same catch path that already had both the name
+ * and the reason.
+ */
+interface RunMcpServerFailedEvent {
+    readonly type: "mcp_server_failed";
+    /** The server as named in the MCP configuration, so the consumer can match it to what it lists. */
+    readonly serverName: string;
+    /** Why listing failed — a spawn error, a handshake timeout, a protocol error. */
+    readonly message: string;
+}
+/**
+ * usetheokit/theokit#426 — an MCP server came up, and these are the tools it delivered.
+ *
+ * The sibling of {@link RunMcpServerFailedEvent}, emitted from the same function, on the other
+ * branch. Without it a consumer could see what was CONFIGURED and what BROKE, and could not tell a
+ * server that came up with twelve tools from one that came up with none — which is exactly the case
+ * an operator opens a server-status panel to find. `tools: []` on a healthy server is a real and
+ * previously unreportable state.
+ *
+ * An EVENT rather than a getter, because the state is scoped to the run: with
+ * `mcpLifecycle: "run"` a server may not exist by the time anyone asks, so a getter would have to
+ * answer about something already gone. This says what was true when the run started.
+ *
+ * Emitted once per successfully-listed server per run.
+ */
+interface RunMcpServerReadyEvent {
+    readonly type: "mcp_server_ready";
+    /** The server as named in the MCP configuration — the key a consumer already lists it under. */
+    readonly serverName: string;
+    /**
+     * The tool names the server reported, as IT names them.
      *
-     * Absent for providers that stream reasoning text unsigned (the OpenAI-compatible wire).
+     * Not the `mcp_<server>_<tool>` form the model sees: that spelling is sanitized for the provider,
+     * and a consumer matching it back to a server's own documentation would have to undo the mangling.
+     */
+    readonly tools: readonly string[];
+}
+/**
+ * SE24 — a guardrail processor called `abort()`; the run stops with a tripwire.
+ * Delivered via {@link SendOptions.onRunEvent} (mirrors the `RunResult.tripwire`
+ * surfaced on `wait()`).
+ */
+interface RunTripwireEvent {
+    readonly type: "tripwire";
+    readonly reason: string;
+    readonly processorId: string;
+}
+/** A tool call is being dispatched (before its result). */
+interface RunToolProgressEvent {
+    readonly type: "tool_progress";
+    readonly toolName: string;
+    readonly toolCallId: string;
+}
+/** The provider returned a rate-limit (HTTP 429); the loop will back off + retry. */
+interface RunRateLimitEvent {
+    readonly type: "rate_limit";
+    /** Retry attempt number (1-based) about to be delayed. */
+    readonly attempt: number;
+    /** Delay in ms before the retry, when the provider/policy supplied one. */
+    readonly retryAfterMs?: number;
+}
+/**
+ * A tool call was DENIED before dispatch — by the permission gate/plugin (SE1),
+ * an operator file-hook `preToolUse`, or the fork tool-whitelist. `source`
+ * discriminates which. `toolCallId` joins the event to the tool-call log.
+ */
+interface RunPermissionDeniedEvent {
+    readonly type: "permission_denied";
+    readonly toolName: string;
+    readonly toolCallId: string;
+    /** Which layer blocked the call. */
+    readonly source: "plugin" | "file_hook" | "fork_whitelist";
+    /** The rejection message surfaced to the model. */
+    readonly message: string;
+}
+/** A background task/subagent started. */
+interface RunTaskStartedEvent {
+    readonly type: "task_started";
+    readonly taskId: string;
+    readonly description?: string;
+}
+/** A background task/subagent changed state. */
+interface RunTaskUpdatedEvent {
+    readonly type: "task_updated";
+    readonly taskId: string;
+    readonly status: string;
+}
+/** A background task/subagent finished. */
+interface RunTaskCompletedEvent {
+    readonly type: "task_completed";
+    readonly taskId: string;
+    readonly status: "completed" | "failed" | "stopped";
+}
+/**
+ * SE34 — the per-send completion check (`isTaskComplete`) produced a verdict.
+ * Emitted once, after a finished run's reply is judged against
+ * {@link SendOptions.completionCheck}. Distinct from `task_completed` (which is
+ * background-task/subagent lifecycle). Mirrors {@link RunResult.completionCheck}.
+ */
+interface RunCompletionCheckEvent {
+    readonly type: "completion_check";
+    readonly complete: boolean;
+    readonly reason: string;
+}
+/** The conversation crossed a compaction boundary (history was summarized). */
+interface RunCompactBoundaryEvent {
+    readonly type: "compact_boundary";
+    readonly trigger: "manual" | "auto";
+    /** Token count before compaction, when known. */
+    readonly preTokens?: number;
+}
+/**
+ * M77 — auto-compaction is budgeting against a FLOOR, because neither the catalog nor the caller
+ * supplied a context window for this model.
+ *
+ * The prior behaviour was to disable auto-compaction entirely and write one line to stderr per
+ * process. That is fail-OPEN: the conversation grows until the provider rejects it. This event exists
+ * so a surface can say "I am running without a real budget" instead of the user discovering it at the
+ * moment of failure.
+ *
+ * Not emitted when the window came from the catalog (the normal path) or from an explicit caller
+ * override (the caller already knows).
+ */
+interface RunCompactionFallbackEvent {
+    readonly type: "compaction_fallback";
+    /** The model whose window is unknown — what the user needs to fix in configuration. */
+    readonly model: string;
+    /** The floor being budgeted against, after the safety margin. */
+    readonly window: number;
+}
+/**
+ * A memory stage failed and the run continued without it.
+ *
+ * The same shape of gap {@link RunMcpServerFailedEvent} closed for MCP, in the module next door.
+ * `initLoopContext` had three bare `catch { <field> = <empty> }` blocks: an init failure meant no
+ * memory tool was registered, a `buildTools` failure meant no provider tools, and a `runActivePass`
+ * failure meant no recalled context in the system prompt. The agent then answered without the memory
+ * it was configured with, and nothing recorded it — not stderr, not this sink, not the span in scope.
+ *
+ * Degrading to a working agent is the right BEHAVIOUR. This event exists because the degradation was
+ * unobservable, so a host UI showed a healthy run.
+ *
+ * Emitted once per failing stage per run.
+ *
+ * @public
+ */
+interface RunMemoryDegradedEvent {
+    readonly type: "memory_degraded";
+    /** Which stage failed: `init`, `buildTools`, or `activePass`. */
+    readonly stage: string;
+    /** Why it failed, as the provider reported it. */
+    readonly message: string;
+}
+/**
+ * Receives every {@link RunEvent} a run emits, in emission order.
+ *
+ * Wired through `onRunEvent` on the run options. The sink is observability, never control flow: it
+ * cannot cancel, alter, or delay the run, and {@link emitRunEvent} swallows anything it throws — a
+ * broken sink degrades what you can see, never what the agent does.
+ *
+ * Synchronous by signature, so a slow sink slows the run. Hand work off rather than awaiting inside
+ * it; returning a promise here would be ignored, not awaited.
+ *
+ * @public
+ */
+type RunEventSink = (event: RunEvent) => void;
+
+/**
+ * Owner: `internal/agent-loop/` (4 of 8 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ */
+
+/**
+ * Plain assistant message in a conversation history.
+ *
+ * @public
+ */
+interface AssistantMessage {
+    text: string;
+}
+/**
+ * Reasoning step in a conversation history.
+ *
+ * @public
+ */
+interface ThinkingMessage {
+    text: string;
+    thinkingDurationMs?: number;
+    /**
+     * theokit#122 — the provider's cryptographic signature for this thinking block, when it issued
+     * one. Persisted with the block so a resumed conversation can replay it byte-identically;
+     * Anthropic rejects a modified or unsigned thinking block with
+     * `400 "thinking blocks cannot be modified"`.
      */
     signature?: string;
 }
 /**
- * Tool invocation lifecycle event. Emitted at start with `args`, then again on
- * completion with `result`.
- *
- * Tool `args` and `result` are NOT part of the stable schema — treat as unknown.
+ * Shell command executed during a run.
  *
  * @public
  */
-interface SDKToolUseMessage {
-    type: "tool_call";
-    agent_id: string;
-    run_id: string;
-    call_id: string;
-    name: string;
-    status: "running" | "completed" | "error";
-    args?: unknown;
-    result?: unknown;
-    truncated?: {
-        args?: boolean;
-        result?: boolean;
-    };
+interface ShellCommand {
+    command: string;
+    workingDirectory?: string;
 }
 /**
- * Cloud run lifecycle transitions.
+ * Output of a shell command.
  *
  * @public
  */
-interface SDKStatusMessage {
-    type: "status";
-    agent_id: string;
-    run_id: string;
-    status: "CREATING" | "RUNNING" | "FINISHED" | "ERROR" | "CANCELLED" | "EXPIRED";
-    message?: string;
+interface ShellOutput {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
 }
 /**
- * Task-level milestones and summaries.
+ * Result of a tool invocation. Pairs with the preceding `toolCall` step
+ * by `callId`. `isError: true` when the tool returned a failure result.
+ *
+ * T2.3 — added so `Run.conversation()` surfaces the full interaction
+ * including tool results (parity with OpenAI Agents `RunResult.new_items`).
  *
  * @public
  */
-interface SDKTaskMessage {
-    type: "task";
-    agent_id: string;
-    run_id: string;
-    status?: string;
-    text?: string;
+interface ToolResult {
+    callId: string;
+    name: string;
+    result: string;
+    isError: boolean;
 }
 /**
- * Awaiting user input or approval.
+ * A single step inside an agent turn, discriminated by `type`: an assistant message, a tool call, the
+ * tool result that pairs with it, or a thinking block.
+ *
+ * It reaches a caller by two routes that are NOT the same set. `Run.conversation()` returns the
+ * accumulated steps of a finished turn and includes `thinkingMessage`. `SendOptions.onStep` fires
+ * live while the turn runs and emits `assistantMessage`, `toolCall` and `toolResult` — but never
+ * `thinkingMessage`, which the loop builds only into the accumulated conversation. A UI that wants
+ * reasoning as it happens should read the `thinking-delta` / `thinking-completed` variants of
+ * `InteractionUpdate` through `onDelta` instead.
+ *
+ * `toolCall` and its `toolResult` arrive as an ordered pair matched by `callId`; a call whose result
+ * never came back has no `toolResult` step, so do not assume they alternate. Where a
+ * `thinkingMessage` exists it precedes the `assistantMessage` of the same turn — that is the order
+ * the provider requires of the message the block belongs to, not a presentation choice.
  *
  * @public
  */
-interface SDKRequestMessage {
-    type: "request";
-    agent_id: string;
-    run_id: string;
-    request_id: string;
-}
+type ConversationStep = {
+    type: "assistantMessage";
+    message: AssistantMessage;
+} | {
+    type: "toolCall";
+    message: ToolCall;
+} | {
+    type: "toolResult";
+    message: ToolResult;
+} | {
+    type: "thinkingMessage";
+    message: ThinkingMessage;
+};
 /**
- * Partial object emitted during `Agent.streamObject<T>` streaming (ADR D45).
- * `partial` is `DeepPartial<z.infer<T>>` at the typed iterator level but
- * erased to `unknown` here because SDKMessage union is non-generic.
+ * Agent turn: user message + assistant/tool/thinking steps.
  *
  * @public
  */
-interface SDKObjectDelta {
-    type: "object_delta";
-    agent_id: string;
-    run_id: string;
-    partial: unknown;
-    attempt: number;
+interface AgentConversationTurn {
+    userMessage?: UserMessage;
+    steps: ConversationStep[];
 }
 /**
- * Discriminated union of all stream events. Discriminate on `type`.
+ * Shell turn: a command and its output.
  *
- * All events include `agent_id` and `run_id`.
+ * @public
+ */
+interface ShellConversationTurn {
+    shellCommand?: ShellCommand;
+    shellOutput?: ShellOutput;
+}
+/**
+ * Structured per-turn view of a run.
  *
  * @public
  */
-type SDKMessage = SDKSystemMessage | SDKUserMessageEvent | SDKAssistantMessage | SDKThinkingMessage | SDKToolUseMessage | SDKStatusMessage | SDKTaskMessage | SDKRequestMessage | SDKObjectDelta;
+type ConversationTurn = {
+    type: "agentConversationTurn";
+    turn: AgentConversationTurn;
+} | {
+    type: "shellConversationTurn";
+    turn: ShellConversationTurn;
+};
 
 /**
  * Owner: `internal/budget/` (3 of 8 importers). Derived from the import graph, not declared —
@@ -1168,16 +1583,6 @@ interface ToolResultGuardOptions {
  * @public
  */
 type RunStatus = "running" | "finished" | "error" | "cancelled";
-/**
- * Operations that may or may not be supported on a given {@link Run}, or on
- * its parent agent.
- *
- * Runtime-specific availability — query at runtime with `run.supports(op)` and
- * read the human reason via `run.unsupportedReason(op)`.
- *
- * @public
- */
-type RunOperation = "stream" | "wait" | "cancel" | "conversation" | "listArtifacts" | "downloadArtifact" | "runUntil" | "runToCompletion" | "streamToCompletion" | "fork" | "usePersonality" | "workflow";
 /**
  * Git metadata attached to cloud runs.
  *
@@ -1408,15 +1813,23 @@ type StreamToCompletionResult = RunToCompletionResult;
  * Structured error attached to a {@link RunResult} when the underlying run
  * transitioned to `"error"` status. `message` is always present; `code` is
  * a stable identifier suitable for branching (e.g. `"llm_4xx"`,
- * `"tool_dispatch_failed"`, `"mcp_init_failed"`); `cause` is the raw error
- * for further inspection when available.
+ * `"tool_dispatch_failed"`, `"mcp_init_failed"`); `cause` is the typed
+ * {@link TheokitAgentError} behind the failure, so `instanceof` works on it
+ * directly (e.g. `result.error?.cause instanceof AuthenticationError`).
+ *
+ * A failure whose original cause was missing or not an SDK error carries an
+ * `UnknownAgentError` with the same message and code, holding the original
+ * value at its own `cause`.
+ *
+ * With `AgentOptions.throwOnError`, `run.wait()` rejects with this same `cause`
+ * instead of resolving.
  *
  * @public
  */
 interface RunErrorDetail {
     message: string;
     code?: string;
-    cause?: unknown;
+    cause?: TheokitAgentError;
 }
 /**
  * Dimensions of an inline image attachment.
@@ -1810,4 +2223,338 @@ interface GenerateRunResult<O> {
     };
 }
 
-export type { RunToolProgressEvent as $, AgentConversationTurn as A, RunCompletionCheckEvent as B, CustomTool as C, DoomLoopThresholds as D, EnvPolicy as E, RunErrorDetail as F, GenerateOptions as G, RunEvent as H, ImageBlock as I, RunGitInfo as J, RunMemoryDegradedEvent as K, RunOperation as L, ModelSelection as M, RunPermissionDeniedEvent as N, OutputProcessorContext as O, Processor as P, RunRateLimitEvent as Q, RunResult as R, SDKMessage as S, ToolResultContentBlock as T, RunStatus as U, RunTaskCompletedEvent as V, RunTaskStartedEvent as W, RunTaskUpdatedEvent as X, RunTimelineEvent as Y, RunToCompletionOptions as Z, RunToCompletionResult as _, McpServerConfig as a, RunTripwireEvent as a0, SDKAssistantMessage as a1, SDKImage as a2, SDKImageDimension as a3, SDKObjectDelta as a4, SDKRequestMessage as a5, SDKStatusMessage as a6, SDKSystemMessage as a7, SDKTaskMessage as a8, SDKThinkingMessage as a9, ToolResultGuardOptions as aA, ToolUseBlock as aB, TurnEndedUpdate as aC, UserMessage as aD, UserMessageAppendedUpdate as aE, SDKToolUseMessage as aa, SDKUserMessage as ab, SDKUserMessageEvent as ac, SendOptions as ad, ShellCommand as ae, ShellConversationTurn as af, ShellOutput as ag, ShellOutputDeltaUpdate as ah, StepCompletedUpdate as ai, StepStartedUpdate as aj, StreamToCompletionResult as ak, SummaryCompletedUpdate as al, SummaryStartedUpdate as am, SummaryUpdate as an, TextBlock as ao, TextDeltaUpdate as ap, ThinkingCompletedUpdate as aq, ThinkingDeltaUpdate as ar, ThinkingMessage as as, TokenDeltaUpdate as at, TokenUsage as au, ToolCall as av, ToolCallCompletedUpdate as aw, ToolCallStartedUpdate as ax, ToolContextMessage as ay, ToolResult as az, Run as b, PermissionMode as c, RunEventSink as d, AssistantMessage as e, CompletionCheck as f, CompletionCheckResult as g, ConversationStep as h, ConversationTurn as i, CostBreakdown as j, CostSource as k, CostStatus as l, GenerateRunResult as m, InputProcessorContext as n, InteractionUpdate as o, McpAuthConfig as p, McpHttpServerConfig as q, McpOAuthConfig as r, McpStdioServerConfig as s, MessageOrigin as t, ModelParameterValue as u, PartialToolCallUpdate as v, ProcessorControls as w, ProcessorTripwire as x, ProcessorViolation as y, RunCompactBoundaryEvent as z };
+/**
+ * Public skill metadata exposed to the system-prompt resolver. Mirrors the
+ * shape returned by `agent.skills.list()` — name + description only, never
+ * full skill bodies.
+ *
+ * @public
+ */
+interface SystemPromptSkillRef {
+    name: string;
+    description: string;
+    /**
+     * Where this skill came from: the absolute path to its `SKILL.md` for a skill read from disk,
+     * or the synthetic `inline://<name>` marker `createSkill` stamps on a code-defined one (see
+     * `create-skill.ts`) — there is no third case, so this is populated for every skill `list()`
+     * returns.
+     *
+     * It is the ORIGIN and NOT the body: `list()` stays lean by contract, and a skill's instructions
+     * are reachable only through {@link SDKAgentSkills.get}. What this adds is the answer to
+     * usetheokit/theokit-sdk#524's visibility question — which root a skill came from, so a listing
+     * can show that one arrived from `.claude/skills/` rather than the project's own directory, or
+     * that it was never on disk at all.
+     *
+     * Typed optional rather than required because {@link SystemPromptSkillRef} is the shape any
+     * future skill producer returns, and this SDK should not assert every one of them can name an
+     * origin.
+     */
+    source?: string;
+}
+/**
+ * A skill resolved WITH its body, returned by {@link SDKAgentSkills.get}. Unlike
+ * {@link SystemPromptSkillRef}, which carries metadata only, this carries the full
+ * `instructions` — read from the SKILL.md for filesystem skills or the inline
+ * `createSkill` body. @public
+ */
+interface SDKAgentSkillDetail {
+    name: string;
+    description: string;
+    instructions: string;
+    /** SE21 — supporting documents bundled with the skill (filename → content), when present. */
+    references?: Record<string, string>;
+}
+/**
+ * The skill handle exposed as `agent.skills`, present only when project-scoped skills are enabled
+ * (`settingSources: ["project"]`) or `skills.enabled` is set. The property is optional on the agent,
+ * and `undefined` there means skills were never turned on — not that none were found.
+ *
+ * The split between its two methods is the choice it asks of a caller. `list()` returns name and
+ * description only, which is what belongs in a system prompt: it stays cheap and it keeps skill
+ * bodies out of the context window. `get(name)` resolves one skill WITH its `instructions` — the
+ * SKILL.md body for a filesystem skill, the inline body for one built with `createSkill` — and
+ * returns `undefined` when no enabled skill matches that name. Ask for a body only when you are
+ * about to use it.
+ *
+ * @public
+ */
+interface SDKAgentSkills {
+    list(): Promise<ReadonlyArray<SystemPromptSkillRef>>;
+    /**
+     * SE20 — resolve a skill by name INCLUDING its body (`instructions`). Returns
+     * `undefined` when no enabled skill matches. `list()` stays lean (name +
+     * description); full bodies come only through `get`.
+     */
+    get(name: string): Promise<SDKAgentSkillDetail | undefined>;
+}
+/**
+ * Public plugin metadata returned by `agent.plugins.list()`. Mirrors the
+ * `.theokit/plugins/<name>/MANIFEST.json` allow-listed shape; never exposes
+ * raw plugin bodies, credentials, or internal hooks.
+ *
+ * @public
+ */
+interface SDKPluginMetadata {
+    name: string;
+    description?: string;
+    /**
+     * Absolute path the plugin manifest was read from.
+     *
+     * The runtime has ALWAYS returned this — `agent.plugins.list()` hands back the internal
+     * `PluginMetadata`, whose own docblock says it carries provenance "so callers can audit where the
+     * plugin came from". This type simply did not declare it, so the caller received the field and
+     * the compiler denied it existed. Declaring it is what makes the audit usetheokit/theokit-sdk#524
+     * asks for reachable in typed code.
+     */
+    source?: string;
+}
+/**
+ * Public plugin listing handle exposed as `agent.plugins`. Populated when
+ * `settingSources` includes `"plugins"` OR when `plugins.enabled` is set
+ * on the agent options.
+ *
+ * @public
+ */
+interface SDKAgentPlugins {
+    list(): Promise<ReadonlyArray<SDKPluginMetadata>>;
+}
+/**
+ * Artifact produced inside an agent's workspace. Cloud-only.
+ *
+ * @public
+ */
+interface SDKArtifact {
+    path: string;
+    sizeBytes: number;
+    updatedAt: string;
+}
+/**
+ * An operation a consumer may ask an {@link SDKAgent} about via `supports()`.
+ *
+ * Deliberately the members whose availability DIFFERS between runtimes, plus the core ones a caller
+ * may want to assert positively. A union rather than `string` so a typo is a compile error instead
+ * of a silent `false`.
+ *
+ * @public
+ */
+type AgentOperation = "send" | "generate" | "listArtifacts" | "downloadArtifact" | "runUntil" | "fork" | "runToCompletion" | "streamToCompletion" | "usePersonality" | "invalidateCache";
+/**
+ * Handle returned by `Agent.create()` and `Agent.resume()`.
+ *
+ * @public
+ */
+interface SDKAgent {
+    readonly agentId: string;
+    readonly model: ModelSelection | undefined;
+    /**
+     * Context manager for this agent. Populated when context is enabled via
+     * {@link AgentOptions.context}. See {@link SDKContextManager}.
+     */
+    readonly context?: SDKContextManager;
+    /**
+     * Provider routing inspector for this agent. Populated when at least one
+     * provider route is configured (via {@link AgentOptions.providers}, plugins,
+     * or model-implied providers). See {@link SDKProvidersManager}.
+     */
+    readonly providers?: SDKProvidersManager;
+    /**
+     * Skill listing for this agent. Populated when project-scoped skills are
+     * enabled (`settingSources: ["project"]`) or when `skills.enabled` is set.
+     * See {@link SDKAgentSkills}.
+     */
+    readonly skills?: SDKAgentSkills;
+    /**
+     * Plugin listing for this agent. Populated when project-scoped plugins are
+     * enabled (`settingSources: ["plugins"]`) or when `plugins.enabled` is set.
+     * See {@link SDKAgentPlugins}.
+     */
+    readonly plugins?: SDKAgentPlugins;
+    send(message: string | SDKUserMessage, options?: SendOptions): Promise<Run>;
+    /**
+     * SE9 — integrated structured output. Runs the normal tool loop (the tools run
+     * first) then coerces the final answer into the `output` Zod schema, returning a
+     * validated, inferred-typed object. Sugar over `Agent.generateObject` (ADR D33).
+     */
+    generate<T extends zod.ZodType>(message: string | SDKUserMessage, options: GenerateOptions<T>): Promise<GenerateRunResult<zod.z.infer<T>>>;
+    /** Fire-and-forget disposal. */
+    close(): void;
+    /** Re-read filesystem config (context, hooks, project MCP, subagents) without disposing. */
+    reload(): Promise<void>;
+    /**
+     * Async disposal. Idempotent — calling more than once is a no-op (per ADR D5).
+     * Prefer `await using agent = await Agent.create(...)` over explicit
+     * `dispose()` for resource safety.
+     */
+    dispose(): Promise<void>;
+    /**
+     * `await using` support per ADR D5. Identical semantics to `dispose()` —
+     * idempotent across both surfaces.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Which operations this agent's runtime actually performs.
+     *
+     * `SDKAgent` is one handle over two runtimes that do not offer the same operations, and the type
+     * does not model the difference: `downloadArtifact` is a REQUIRED member that rejects for every
+     * input on a local agent, and five optional members are present-but-throwing on a cloud one, so
+     * `typeof agent.fork === "function"` is true and calling it throws. Neither requiredness nor
+     * optionality expresses "exists here, not there".
+     *
+     * Ask before calling. Mirrors `Run.supports(op)` / `Run.unsupportedReason(op)`, which solved the
+     * same problem one layer down over the `RunOperation` union.
+     *
+     * This is a MITIGATION. The structural fix is to split this interface into a common core plus
+     * `LocalCapableAgent` / `CloudCapableAgent`, so the compiler refuses the call instead of the
+     * runtime and a consumer narrows once instead of asking per call. That is breaking on a published
+     * surface and is deliberately not done here.
+     *
+     * @public
+     */
+    supports(operation: AgentOperation): boolean;
+    /**
+     * Human-readable reason `supports(operation)` returned `false`, or `undefined` when it returned
+     * `true`. The message names the runtime, so an operator reading a log knows which half of the
+     * union they are holding.
+     *
+     * @public
+     */
+    unsupportedReason(operation: AgentOperation): string | undefined;
+    /** Cloud-only. Local returns an empty array. */
+    listArtifacts(): Promise<SDKArtifact[]>;
+    /** Cloud-only. Local throws `UnsupportedRunOperationError`. */
+    downloadArtifact(path: string): Promise<Buffer>;
+    /**
+     * Signal that prompt cache should be invalidated. By default deferred —
+     * applied at the start of the next `send()`. Pass `{ applyNow: true }` to
+     * force immediate disposal (caller must `Agent.create()` again to use).
+     *
+     * Cache invalidation is a cost regression (provider charges full price
+     * for the rebuilt cache; see ADRs D94-D95). Use sparingly and deliberately.
+     *
+     * Cloud agents: no-op (cloud runtime reconstructs state per request).
+     *
+     * @public
+     */
+    invalidateCache?(reason: string, options?: InvalidateCacheOptions): Promise<void>;
+    /**
+     * Goal-driven Ralph loop (ADRs D115-D121). Iterates `agent.send` →
+     * judge → continuation until the auxiliary judge model returns `done`,
+     * the judge fails too many times in a row, max turns are exhausted,
+     * or the caller aborts via `AbortSignal`.
+     *
+     * Yields {@link import("./goal-events.js").GoalEvent} per state
+     * transition; returns a {@link import("./goal-events.js").GoalResult}
+     * summary as the generator's final value.
+     *
+     * Cloud agents throw {@link import("../errors.js").UnsupportedRunOperationError}
+     * **synchronously** (no AsyncGenerator returned) — wrap in try/catch
+     * if you support both runtimes.
+     *
+     * Caveat: do not call `agent.dispose()` mid-iteration; the next `send`
+     * propagates the disposal error through the generator to the consumer.
+     *
+     * @public
+     */
+    runUntil?(goal?: string, options?: GoalOptions): RunUntilIterator;
+    /**
+     * Fork a short-lived sub-agent with parent's credentials + system
+     * prompt byte-identical (ADR D112 — cache hit) and a restricted tool
+     * whitelist (ADR D111 — AsyncLocalStorage isolation).
+     *
+     * Cloud agents throw {@link import("../errors.js").UnsupportedRunOperationError}.
+     *
+     * @public
+     */
+    fork?(options: ForkOptions): Promise<ForkResult>;
+    /**
+     * Drive `send` to completion across iteration-ceiling truncations (M1 Phase 3).
+     * When a `send` stops at the loop's iteration cap (`RunResult.stoppedAtIterationLimit`),
+     * this re-sends a short continuation prompt — the agent's stateful session
+     * preserves the conversation — until a genuine terminal: `done` (finished),
+     * `step_limit` (`maxRounds` exhausted), or `no_progress` (two empty rounds).
+     *
+     * Local agents only. Cloud agents throw
+     * {@link import("../errors.js").UnsupportedRunOperationError} (the cloud
+     * runtime manages its own continuation policy server-side).
+     *
+     * @public
+     */
+    runToCompletion?(message: string, options?: RunToCompletionOptions): Promise<RunToCompletionResult>;
+    /**
+     * STREAMING continuation driver (V3-4) — the streaming twin of
+     * {@link SDKAgent.runToCompletion}. Returns an `AsyncGenerator` that yields each
+     * round's {@link import("./messages.js").SDKMessage}s LIVE (for a UI), reusing the
+     * same terminal policy (`done`/`step_limit`/`no_progress` + bounded re-prompt).
+     *
+     * The {@link import("./run.js").StreamToCompletionResult} is the generator's RETURN
+     * value — read it via a manual `gen.next()` loop (`while (!res.done) res = await
+     * gen.next()` → `res.value`); a plain `for await...of` consumes the yielded
+     * messages but discards the return value.
+     *
+     * Local agents only. Cloud agents throw
+     * {@link import("../errors.js").UnsupportedRunOperationError}.
+     *
+     * @public
+     */
+    streamToCompletion?(message: string, options?: RunToCompletionOptions): AsyncGenerator<SDKMessage, StreamToCompletionResult>;
+    /**
+     * Direct API to third-party memory adapter(s) registered via
+     * `plugins: [...]` (ADR D141 / D142). Returns `null` when no adapter
+     * is registered. In multi-adapter setups `write` fans out to all;
+     * `recall` merges + dedupes; `delete` routes by `MemoryId` prefix.
+     *
+     * @public
+     */
+    memory?: AgentMemory;
+    /**
+     * Activate a personality preset for the next `send` (Hermes #26).
+     * Reserved names `"none"`, `"default"`, and `"neutral"` clear the
+     * active preset. Returns the resolved preset (or `null` when cleared).
+     *
+     * Persistence: pass `{ save: true }` to persist across process
+     * restarts (stored under `$THEOKIT_HOME/personality.json`).
+     *
+     * History: by default the conversation history is preserved across
+     * the switch. Pass `{ reset: true }` to also clear the session.
+     *
+     * Cloud agents throw {@link import("../errors.js").UnsupportedRunOperationError}.
+     *
+     * @public
+     */
+    usePersonality?(name: string, opts?: {
+        save?: boolean;
+        reset?: boolean;
+    }): Promise<PersonalityPreset | null>;
+}
+/**
+ * Resolved personality preset surfaced via {@link SDKAgent.usePersonality}
+ * (Hermes #26, ADRs D160-D169). Re-declared here so the public DTS bundle
+ * never crosses the `internal/` path boundary. The implementation type in
+ * `internal/personality/types.ts` is structurally identical.
+ *
+ * @public
+ */
+interface PersonalityPreset {
+    readonly name: string;
+    readonly description: string | undefined;
+    readonly tools: ReadonlyArray<string> | undefined;
+    readonly model: string | undefined;
+    readonly tags: ReadonlyArray<string> | undefined;
+    readonly systemPrompt: string;
+    readonly source: "project" | "user";
+    readonly sourcePath: string;
+}
+/**
+ * Options for {@link SDKAgent.invalidateCache}.
+ *
+ * @public
+ */
+interface InvalidateCacheOptions {
+    /**
+     * When `true`, dispose the agent immediately so caller must recreate it
+     * to continue. Default `false` (deferred — applied on next `send()`).
+     */
+    applyNow?: boolean;
+}
+
+export type { OutputProcessorContext as $, AgentConversationTurn as A, GenerateRunResult as B, ContextSettings as C, DoomLoopThresholds as D, EnvPolicy as E, ForkOptions as F, GoalOptions as G, InteractionUpdate as H, InputProcessorContext as I, JudgeResult as J, InvalidateCacheOptions as K, McpAuthConfig as L, McpServerConfig as M, McpHttpServerConfig as N, McpOAuthConfig as O, ProviderRoutingSettings as P, McpStdioServerConfig as Q, RunResult as R, SDKAgent as S, MemoryAdapter as T, MemoryAdapterCapabilities as U, MemoryContext as V, MemoryFact as W, MemoryRevision as X, MemoryToolSchema as Y, MemoryTurnMessage as Z, MessageOrigin as _, PluginsSettings as a, ToolCall as a$, PartialToolCallUpdate as a0, PersonalityPreset as a1, ProcessorControls as a2, ProcessorTripwire as a3, ProcessorViolation as a4, ProviderCapability as a5, ProviderRoute as a6, ResolvedProviderRoute as a7, RunCompactBoundaryEvent as a8, RunCompletionCheckEvent as a9, SDKProvidersManager as aA, SDKRequestMessage as aB, SDKStatusMessage as aC, SDKSystemMessage as aD, SDKTaskMessage as aE, SDKThinkingMessage as aF, SDKToolUseMessage as aG, SDKUserMessage as aH, SDKUserMessageEvent as aI, SendOptions as aJ, ShellCommand as aK, ShellConversationTurn as aL, ShellOutput as aM, ShellOutputDeltaUpdate as aN, StepCompletedUpdate as aO, StepStartedUpdate as aP, StreamToCompletionResult as aQ, SummaryCompletedUpdate as aR, SummaryStartedUpdate as aS, SummaryUpdate as aT, SystemPromptSkillRef as aU, TextDeltaUpdate as aV, ThinkingCompletedUpdate as aW, ThinkingDeltaUpdate as aX, ThinkingMessage as aY, TokenDeltaUpdate as aZ, TokenUsage as a_, RunErrorDetail as aa, RunEvent as ab, RunGitInfo as ac, RunMemoryDegradedEvent as ad, RunPermissionDeniedEvent as ae, RunRateLimitEvent as af, RunStatus as ag, RunTaskCompletedEvent as ah, RunTaskStartedEvent as ai, RunTaskUpdatedEvent as aj, RunTimelineEvent as ak, RunToCompletionOptions as al, RunToCompletionResult as am, RunToolProgressEvent as an, RunTripwireEvent as ao, RunUntilIterator as ap, SDKAgentPlugins as aq, SDKAgentSkillDetail as ar, SDKAgentSkills as as, SDKArtifact as at, SDKAssistantMessage as au, SDKContextManager as av, SDKImage as aw, SDKImageDimension as ax, SDKObjectDelta as ay, SDKPluginMetadata as az, Run as b, ToolCallCompletedUpdate as b0, ToolCallStartedUpdate as b1, ToolResult as b2, ToolResultGuardOptions as b3, ToolUseBlock as b4, TurnEndedUpdate as b5, UserMessage as b6, UserMessageAppendedUpdate as b7, Verdict as b8, Processor as c, GoalEvent as d, GoalResult as e, MemoryId as f, RunEventSink as g, SDKProvider as h, SDKMessage as i, AgentMemory as j, AgentOperation as k, AssistantMessage as l, CompletionCheck as m, CompletionCheckResult as n, ContextBudget as o, ContextManagerKind as p, ContextSnapshot as q, ContextSource as r, ContextSourceStatus as s, ConversationStep as t, ConversationTurn as u, CostBreakdown as v, CostSource as w, CostStatus as x, ForkResult as y, GenerateOptions as z };