@theokit/sdk 0.0.0-compat-580-20260905204608

package/dist/index.d.cts

@@ -0,0 +1,4166 @@
+import { T as TheokitAgentError, E as ErrorMetadata } from './errors-base-B5g01neU.cjs';
+export { a as ErrorCode } from './errors-base-B5g01neU.cjs';
+import { F as RunEvent, j as CostBreakdown, at as TokenUsage, R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, T as ToolResultContentBlock, b as Run, P as Processor, c as PermissionMode, d as RunEventSink$1, S as SDKMessage } from './run-CTAdRU3U.cjs';
+export { A as AgentConversationTurn, e as AssistantMessage, f as CompletionCheck, g as CompletionCheckResult, h as ConversationStep, i as ConversationTurn, j as CostBreakdown, k as CostSource, l as CostStatus, D as DoomLoopThresholds, G as GenerateOptions, m as GenerateRunResult, I as ImageBlock, n as InputProcessorContext, o as InteractionUpdate, p as McpAuthConfig, q as McpHttpServerConfig, r as McpOAuthConfig, s as McpStdioServerConfig, t as MessageOrigin, u as ModelParameterValue, O as OutputProcessorContext, v as PartialToolCallUpdate, w as ProcessorControls, x as ProcessorTripwire, y as ProcessorViolation, z as RunCompactBoundaryEvent, B as RunCompletionCheckEvent, E as RunErrorDetail, F as RunEvent, H as RunGitInfo, J as RunMemoryDegradedEvent, K as RunOperation, L as RunPermissionDeniedEvent, N as RunRateLimitEvent, Q as RunStatus, U as RunTaskCompletedEvent, V as RunTaskStartedEvent, W as RunTaskUpdatedEvent, X as RunTimelineEvent, Y as RunToCompletionOptions, Z as RunToCompletionResult, _ as RunToolProgressEvent, $ as RunTripwireEvent, a0 as SDKAssistantMessage, a1 as SDKImage, a2 as SDKImageDimension, a3 as SDKObjectDelta, a4 as SDKRequestMessage, a5 as SDKStatusMessage, a6 as SDKSystemMessage, a7 as SDKTaskMessage, a8 as SDKThinkingMessage, a9 as SDKToolUseMessage, aa as SDKUserMessage, ab as SDKUserMessageEvent, ac as SendOptions, ad as ShellCommand, ae as ShellConversationTurn, af as ShellOutput, ag as ShellOutputDeltaUpdate, ah as StepCompletedUpdate, ai as StepStartedUpdate, aj as StreamToCompletionResult, ak as SummaryCompletedUpdate, al as SummaryStartedUpdate, am as SummaryUpdate, an as TextBlock, ao as TextDeltaUpdate, ap as ThinkingCompletedUpdate, aq as ThinkingDeltaUpdate, ar as ThinkingMessage, as as TokenDeltaUpdate, at as TokenUsage, au as ToolCall, av as ToolCallCompletedUpdate, aw as ToolCallStartedUpdate, ax as ToolContextMessage, ay as ToolResult, az as ToolResultGuardOptions, aA as ToolUseBlock, aB as TurnEndedUpdate, aC as UserMessage, aD as UserMessageAppendedUpdate } from './run-CTAdRU3U.cjs';
+import { A as AgentOptions, L as LocalOptions, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as SkillsSettings, c as ListAgentsOptions, d as ListResult, e as SDKAgentInfo, G as GetAgentOptions, f as ListRunsOptions, g as GetRunOptions, h as AgentOperationOptions, i as AgentDescription, P as Plugin$1, j as ProviderProfile, I as InlineSkill, B as BudgetTracker, k as MemoryProvider, l as PreToolCallDecision } from './agent-C3KO5LKm.cjs';
+export { m as ActiveMemoryPassArgs, n as ActiveMemoryPassResult, o as AgentSubagentDescription, p as AgentToolDescription, q as BudgetCheck, r as BudgetTotal, s as BudgetUsageEvent, t as BuiltinToolName, u as CloudEnv, v as CloudRepo, w as CompatSource, x as CompatSourceAdapter, y as CompatSurface, z as CreateSkillSpec, H as HookName, D as MemoryProviderAgentRef, E as MemoryProviderFactory, F as MemoryProviderHandle, J as MemoryProviderInitOptions, K as PluginContext, N as PluginHookDisposer, O as PostAssistantReplyContext, Q as PostToolCallContext, R as PreToolCallContext, T as PreUserSendContext, U as PreUserSendResult, V as ProviderTransform, W as ProviderTransformContext, X as RecordSessionSummaryArgs, Y as SessionLifecycleContext, Z as SessionRecord, _ as SessionStore, $ as SettingSource, a0 as Skill, a1 as SkillsResolver, a2 as SkillsResolverContext, a3 as SystemPromptContext, a4 as SystemPromptMemoryFact, a5 as TelemetrySettings, a6 as ToolCallSummary, a7 as ToolResultTransformContext, a8 as TransformContext } from './agent-C3KO5LKm.cjs';
+import * as zod from 'zod';
+import { ZodType, z } from 'zod';
+import { S as StructuredOutputError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot } from './errors-DrDEgyz1.cjs';
+export { A as AgentDisposedError, c as AgentRunError, d as AgentRunErrorCode, e as AuthenticationError, f as BudgetExceedEvent, g as BudgetExceededError, h as BudgetLimit, i as BudgetMode, j as BudgetScope, k as BudgetThresholdEvent, l as BudgetWindow, C as ConfigurationError, I as IntegrationNotConnectedError, m as InvalidTaskIdError, M as MemoryAdapterError, n as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, T as TaskNotFoundError, U as UnknownAgentError, o as UnsupportedBudgetOperationError, p as UnsupportedRunOperationError, q as UnsupportedTaskOperationError, r as isTransientError } from './errors-DrDEgyz1.cjs';
+import { P as ProviderRoutingSettings, S as SDKAgent, C as ContextSettings, a as PluginsSettings, J as JudgeResult, G as GoalOptions, b as GoalEvent, c as GoalResult, M as MemoryId, d as SDKProvider } from './sdk-agent-BOiKqOgL.cjs';
+export { A as AgentMemory, e as AgentOperation, f as ContextBudget, g as ContextManagerKind, h as ContextSnapshot, i as ContextSource, j as ContextSourceStatus, I as InvalidateCacheOptions, k as MemoryAdapter, l as MemoryAdapterCapabilities, m as MemoryContext, n as MemoryFact, o as MemoryRevision, p as MemoryToolSchema, q as MemoryTurnMessage, r as PersonalityPreset, s as ProviderCapability, t as ProviderRoute, R as ResolvedProviderRoute, u as RunUntilIterator, v as SDKAgentPlugins, w as SDKAgentSkillDetail, x as SDKAgentSkills, y as SDKArtifact, z as SDKContextManager, B as SDKPluginMetadata, D as SDKProvidersManager, E as SystemPromptSkillRef, V as Verdict } from './sdk-agent-BOiKqOgL.cjs';
+export { C as Cron, a as CronCreateOptions, b as CronGetOptions, c as CronJob, d as CronJobStatus, e as CronListOptions, f as CronOperationOptions, g as CronRunOptions, h as CronRuntime, i as CronSchedulerStatus, j as CronStartOptions } from './cron-C3PhZED0.cjs';
+import { StepResult } from './workflow.cjs';
+export { Workflow, agentStep, fn } from './workflow.cjs';
+
+/**
+ * Public compaction / context-management helpers (M2-1, extended V3-3).
+ *
+ * Promotes the SDK's compaction capability to a public surface so consumers can
+ * compact a transcript, mark/filter conversation checkpoints, and detect
+ * context-overflow — without reaching into `internal/`.
+ *
+ * Two recent-window modes (V3-3):
+ *  - `keepRecent` (turn-count, default) — keeps the last N turns verbatim and
+ *    always preserves leading system PROMPTS; reuses the internal
+ *    `selectCompressionWindow` (no second algorithm).
+ *  - `keepTokens` (token-budget) — keeps the trailing turns whose accumulated
+ *    `estimateTokens` fits the budget (theocode `splitTranscript` semantics). In
+ *    this mode leading system prompts are NOT special-cased (D6).
+ *
+ * Summarization is delegated to a caller-supplied callback (which receives the
+ * older window + the summary template). With `failSafe`, a thrown summarizer
+ * returns the ORIGINAL transcript + a structured warn (compaction is an
+ * optimization, never a cause of data loss); without it, the error propagates.
+ *
+ * Public from the `@theokit/sdk/compaction` sub-path.
+ */
+
+/**
+ * Minimal message shape for compaction/compression input. THE canonical public origin (leaf type —
+ * rollup-plugin-dts cannot re-export types from internal modules into entry bundles; M42 lesson).
+ *
+ * @public
+ */
+interface CompressibleMessage {
+    role: "user" | "assistant" | "system";
+    content: string;
+}
+/**
+ * Tokenizer-free token estimate via the conventional ~4-chars-per-token
+ * heuristic: `ceil(text.length / CHARS_PER_TOKEN)`. `""` → 0; any non-empty text → ≥ 1.
+ * A cheap PRE-CALL gate for {@link shouldCompact} — NOT exact tokenization
+ * (a consumer needing exactness supplies their own tokenizer). Uses UTF-16
+ * `.length` (code units), so multibyte text is approximate.
+ *
+ * `built-in-processors.ts` re-exports this under the same name, so both entry points keep working
+ * and there is one implementation behind them.
+ */
+declare function estimateTokens(text: string): number;
+
+/**
+ * M50 (agent-builder) — session-transcript compaction.
+ *
+ * The mechanism:
+ *   - the replacement history = recent USER messages verbatim (newest→oldest under a token budget;
+ *     prior summaries filtered by marker) + ONE summary message with a textual marker prefix,
+ *     injected as `role:"user"` (`build_compacted_history`, compact.rs:589-663);
+ *   - persistence is APPEND-ONLY: a `compact_boundary` record becomes the new DAG root and the
+ *     replacement messages are chained onto it — resume replays boundary→replacement→suffix
+ *     (equivalent of `CompactedItem.replacement_history`, rollout is never truncated);
+ *   - a failing summarizer leaves the transcript UNTOUCHED (typed error; no partial state).
+ *
+ * The summarizer is dependency-injected: tests pass a deterministic fake; the public
+ * `Agent.compact` wires the ADR-D440 compression summarizer (its first real caller).
+ */
+
+interface CompactResult {
+    preTokens: number;
+    postTokens: number;
+}
+
+/**
+ * Owner: `src/` (2 of 5 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * Public types for `Agent.batch` (ADRs D134-D140).
+ *
+ * Run N prompts in parallel with bounded concurrency. Each prompt gets
+ * a fresh agent (create → send → wait → dispose). Failures isolated
+ * per-prompt; the batch never aborts on a single failure.
+ *
+ * @public
+ */
+
+/**
+ * Single prompt in a batch. Plain string is shorthand for `{ prompt }`.
+ *
+ * @public
+ */
+interface BatchItem {
+    /** Prompt text sent to the agent. */
+    prompt: string;
+    /** Per-prompt system prompt override (wins over `BatchOptions.systemPrompt`). */
+    systemPrompt?: string;
+    /**
+     * Caller-supplied metadata, round-tripped to `BatchResult.metadata`.
+     * Passed by reference — do NOT mutate while the batch is in-flight (EC-I).
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options accepted by `Agent.batch`. Extends `AgentOptions` — every
+ * prompt gets an agent created with these options (ADR D138 isolation),
+ * plus the batch-specific knobs below.
+ *
+ * @public
+ */
+interface BatchOptions extends AgentOptions {
+    /**
+     * Maximum parallel agents. Default 4 (ADR D136). Must be a positive
+     * integer. Capped to `prompts.length` to avoid spinning idle workers.
+     *
+     * Bounds the WHOLE per-item lifecycle, including `onResult`: a prompt's
+     * concurrency slot is not released until its `onResult` callback (if any)
+     * has finished (B-110). A caller doing anything stateful in `onResult` —
+     * writing a file, appending to a shared buffer, rate-limiting an API — can
+     * rely on at most `concurrency` such callbacks running at once.
+     */
+    concurrency?: number;
+    /** Optional filter applied post-collection. Return `false` to discard. */
+    filter?: (result: BatchResult) => boolean;
+    /**
+     * Streaming callback fired once per completed prompt (success OR failure).
+     * Caller exceptions are caught + logged to stderr without poisoning
+     * the batch (EC-5). Bounded by `concurrency` — see its doc.
+     */
+    onResult?: (result: BatchResult) => void | Promise<void>;
+    /** Progress callback fired after each result. */
+    onProgress?: (progress: BatchProgress) => void;
+    /**
+     * Cancel pending prompts (ADR D140). In-flight prompts continue to
+     * completion (Node `AbortSignal` semantics). When `signal.reason` is
+     * an Error, it propagates to `BatchResult.error`; otherwise a generic
+     * "aborted" error is used.
+     */
+    signal?: AbortSignal;
+    /**
+     * Opt-in Task wrapping (ADRs D363, D374). When set, the batch is
+     * registered as a `Task` (kind="batch") in the SDK's observable
+     * registry. The parent task transitions `finished` when every
+     * prompt is resolved (success OR failure).
+     *
+     * Use cases: surfacing a long-running batch in the `theokit tasks
+     * list` CLI, programmatic `Task.cancel(id)` aborting the batch, or
+     * binding a user-facing job dashboard. v1 does NOT yet emit one
+     * task PER prompt (single parent only); per-prompt tasks land in
+     * v0.2.
+     *
+     * Auto-generated id uses the `b-` reserved prefix (D368, EC-5).
+     *
+     * @public
+     */
+    task?: true | {
+        id?: string;
+        meta?: Record<string, unknown>;
+    };
+}
+/**
+ * Per-prompt outcome. Discriminated union — check `ok` before reading
+ * `result` or `error`.
+ *
+ * @public
+ */
+type BatchResult = {
+    ok: true;
+    index: number;
+    prompt: string;
+    result: RunResult;
+    metadata?: Record<string, unknown>;
+    durationMs: number;
+} | {
+    ok: false;
+    index: number;
+    prompt: string;
+    error: TheokitAgentError;
+    metadata?: Record<string, unknown>;
+    durationMs: number;
+};
+/**
+ * Live progress snapshot delivered to `onProgress`.
+ *
+ * @public
+ */
+interface BatchProgress {
+    total: number;
+    completed: number;
+    failed: number;
+    pending: number;
+    inFlight: number;
+}
+
+/**
+ * Options accepted by {@link Agent.streamObject}. Same shape as
+ * `Agent.generateObject` with the addition that the result is an
+ * `AsyncIterator<StreamObjectEvent<T>>` rather than a single Promise. See ADR D39.
+ *
+ * @public
+ */
+interface StreamObjectOptions<T extends ZodType> {
+    schema: T;
+    prompt: string;
+    systemPrompt?: string;
+    /** SE8 — accepts a bare-string id shorthand or a {@link ModelSelection}. */
+    model: string | ModelSelection;
+    apiKey?: string;
+    local: LocalOptions;
+    maxRetries?: number;
+    /**
+     * Optional provider routing forwarded to the transient agent. Required when
+     * `model.id` uses a prefix (e.g. `openai/gpt-4o-mini`) but the credential is
+     * for a unified gateway (e.g. OpenRouter). Without this, the SDK infers
+     * provider from the prefix and may fail with `provider_unresolved` even
+     * when the right env key is set under a different provider name.
+     */
+    providers?: ProviderRoutingSettings;
+}
+/**
+ * Recursive partial — `T` where every nested field becomes optional.
+ *
+ * @public
+ */
+type DeepPartial<T> = T extends (infer U)[] ? Array<DeepPartial<U>> : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+/**
+ * Event emitted by {@link Agent.streamObject}. Discriminate on `type`.
+ *
+ * - `partial` events fire zero or more times with monotonically increasing
+ *   `attempt`, carrying best-effort schema-parsed snapshots of the model's
+ *   accumulating output.
+ * - `complete` fires exactly once at the end, carrying the fully Zod-parsed
+ *   object alongside usage and finishReason — semantically identical to a
+ *   successful `Agent.generateObject()` return.
+ *
+ * @public
+ */
+type StreamObjectEvent<T> = {
+    type: "partial";
+    partial: DeepPartial<T>;
+    attempt: number;
+} | {
+    type: "complete";
+    object: T;
+    raw: unknown;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    finishReason: "tool_use" | "error";
+};
+/**
+ * Error thrown by {@link Agent.streamObject} when the model refuses to call
+ * the synthetic `output` tool or when all retries fail to produce a
+ * schema-valid object. Same code taxonomy as `GenerateObjectError`.
+ *
+ * @public
+ */
+declare class StreamObjectError extends StructuredOutputError {
+    readonly name = "StreamObjectError";
+}
+
+/**
+ * Options accepted by {@link Agent.generateObject}. Returns a typed object
+ * matching the supplied Zod schema. See ADR D33.
+ *
+ * @public
+ */
+interface GenerateObjectOptions<T extends ZodType> {
+    /** Zod schema describing the expected object shape. */
+    schema: T;
+    /** User prompt — the model is asked to fill the schema given this prompt. */
+    prompt: string;
+    /** Optional system prompt steering the model. */
+    systemPrompt?: string;
+    /** Model selection. Required (transient agents need a model). SE8 — accepts a
+     *  bare-string id shorthand (`"openai/gpt-4o-mini"`) or a {@link ModelSelection}. */
+    model: string | ModelSelection;
+    /**
+     * M21 — optional separate model for the STRUCTURING step. When set, `model` first produces a
+     * free-text reasoned answer to the prompt (phase 1), then `structuringModel` extracts the
+     * schema-matched object by calling the `output` tool over that answer (phase 2). Lets a large
+     * model reason while a cheap fast model does the extraction. Absent ⇒ today's single-model flow.
+     */
+    structuringModel?: string | ModelSelection;
+    /** API key. Falls back to env (THEOKIT_API_KEY etc). */
+    apiKey?: string;
+    /** Local runtime config (cwd, sandbox). Required to keep the transient agent local-only. */
+    local: LocalOptions;
+    /**
+     * Retry budget on parse failures. Default 1 (initial attempt + 1 retry).
+     * The transient agent is REUSED across retries so the registry sees a
+     * single entry (EC-3).
+     */
+    maxRetries?: number;
+    /**
+     * Optional provider routing forwarded to the transient agent. Required when
+     * `model.id` uses a prefix (e.g. `openai/gpt-4o-mini`) but the credential is
+     * for a unified gateway (e.g. OpenRouter). Without this, the SDK infers
+     * provider from the prefix and may fail with `provider_unresolved` even
+     * when the right env key is set under a different provider name.
+     */
+    providers?: ProviderRoutingSettings;
+    /**
+     * What to do when the model's output fails schema validation after all
+     * retries are exhausted (M14):
+     * - `'throw'` (default) — throw {@link GenerateObjectError} `parse_failed`.
+     * - `'return-raw'` — resolve with the raw, UNVALIDATED input the model sent
+     *   (`object` may not match the schema; inspect `raw` too).
+     * - `'return-partial'` — for object schemas, resolve with only the fields that
+     *   individually validate (best-effort salvage); non-object schemas fall back
+     *   to raw.
+     */
+    errorStrategy?: "throw" | "return-partial" | "return-raw";
+}
+/**
+ * Successful return from {@link Agent.generateObject}.
+ *
+ * @public
+ */
+interface GenerateObjectResult<T> {
+    /** Typed object parsed via the Zod schema. */
+    object: T;
+    /** Raw input the model passed to the synthetic tool, before Zod parse. */
+    raw: unknown;
+    /** Token usage of the LLM call(s) that produced the result. */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    /** Stop reason of the underlying agent run. */
+    finishReason: "tool_use" | "error";
+}
+/**
+ * Typed error thrown by {@link Agent.generateObject} when the model refuses
+ * to call the synthetic `output` tool or when retries are exhausted.
+ *
+ * @public
+ */
+declare class GenerateObjectError extends StructuredOutputError {
+    readonly name = "GenerateObjectError";
+}
+
+/**
+ * Terminal-method callbacks injected by `Agent.builder()` so that
+ * `agent-builder.ts` does NOT need a static import of `Agent` — keeps the
+ * dependency graph acyclic (G6).
+ *
+ * Exported, and NOT carrying the internal-visibility JSDoc tag, because
+ * `AgentBuilder` is `@public` and so is its constructor: `new AgentBuilder(deps)`
+ * is callable by anyone, which makes this parameter's type part of the published
+ * contract whether or not we intended it. Hiding it did not make it private — it
+ * made the emitted `.d.ts` say `constructor(deps?: AgentBuilderDeps)` with no such
+ * type in the file (#335). Prefer `Agent.builder()`, which injects these for you;
+ * this is the seam it uses, not an argument callers are expected to construct.
+ *
+ * @public
+ */
+interface AgentBuilderDeps {
+    create: (options: AgentOptions) => Promise<SDKAgent>;
+    getOrCreate: (agentId: string, options: AgentOptions) => Promise<SDKAgent>;
+}
+/**
+ * Fluent builder for {@link AgentOptions}. Chainable setters mutate internal
+ * state and return `this`. Three terminals:
+ *
+ * - `.build()` — synchronous snapshot (shallow clone) of accumulated options.
+ * - `.create()` — calls the injected `create` (Agent.create).
+ * - `.getOrCreate(agentId)` — calls the injected `getOrCreate` (Agent.getOrCreate).
+ *
+ * Validation runs inside the terminals via `validateAgentOptions`. See ADR D25.
+ *
+ * @public
+ */
+declare class AgentBuilder {
+    private opts;
+    private readonly deps;
+    constructor(deps?: AgentBuilderDeps);
+    /** SE8 — accepts a bare-string id shorthand (`"openai/gpt-4o-mini"`) or a {@link ModelSelection}. */
+    model(m: string | ModelSelection): this;
+    apiKey(k: string): this;
+    name(n: string): this;
+    systemPrompt(p: string | SystemPromptResolver): this;
+    local(l: LocalOptions): this;
+    cloud(c: CloudOptions): this;
+    memory(m: MemorySettings): this;
+    tools(t: CustomTool[]): this;
+    mcpServers(s: Record<string, McpServerConfig>): this;
+    agents(a: Record<string, AgentDefinition>): this;
+    context(c: ContextSettings): this;
+    providers(p: ProviderRoutingSettings): this;
+    plugins(p: PluginsSettings): this;
+    skills(s: SkillsSettings): this;
+    agentId(id: string): this;
+    /**
+     * Synchronous snapshot of the accumulated options. Returns a SHALLOW CLONE
+     * so external mutation of the result doesn't pollute the builder state (EC-2).
+     */
+    build(): AgentOptions;
+    /**
+     * Validate + create a fresh agent. Delegates to `Agent.create` via the
+     * injected `deps.create`. Throws if the builder was instantiated without
+     * deps (i.e., direct `new AgentBuilder()` instead of `Agent.builder()`).
+     */
+    create(): Promise<SDKAgent>;
+    /**
+     * Resume an existing agent or create one if the ID is unknown. Delegates to
+     * `Agent.getOrCreate` via the injected `deps.getOrCreate` (ADR D22).
+     */
+    getOrCreate(agentId: string): Promise<SDKAgent>;
+}
+
+/**
+ * Live-agent cache for production deploys (Production-Readiness #2, ADRs D307-D310).
+ *
+ * Caches `SDKAgent` instances by id with LRU eviction (when `size > maxAgents`)
+ * and an idle-timeout sweep (configurable interval, default 60s). Solves the
+ * "OOM at some point" failure mode of long-running Node servers that keep
+ * spawning fresh agents per conversation.
+ *
+ * **Distinct from `agent-registry.ts`** (the metadata registry that persists
+ * `RegisteredAgent` to `registry.json` per cwd). That module is the "address
+ * book"; this module is the "live cache". Conflating them violates SRP — see
+ * ADR D307.
+ *
+ * Defaults (ADR D308): `maxAgents: 100`, `idleTimeoutMs: 30 min`, sweep `60s`.
+ * Calibrated for indie/small-team Node deploys; high-traffic SaaS should
+ * `configure({ maxAgents: 1000 })`.
+ *
+ * @public (singleton exposed via `Agent.registry`)
+ */
+
+type EvictReason = "lru" | "idle" | "explicit";
+/**
+ * Knobs for {@link LiveAgentRegistry.configure}.
+ *
+ * The three numeric fields are a partial reconfigure — one left out keeps its current value.
+ * `onEvict` is NOT: it is assigned on every call, so `configure({ maxAgents: 200 })` clears a
+ * listener registered earlier. Re-pass the listener whenever you reconfigure.
+ *
+ * Two values are load-bearing zeroes. `maxAgents: 0` disables caching entirely, so every lookup
+ * misses and every agent is rebuilt; `idleTimeoutMs: 0` keeps the cache but leaves LRU as the only
+ * eviction, because the sweep is not started at all below that threshold. Negative numbers are
+ * clamped rather than rejected — up to 1000ms for `sweepIntervalMs`, up to 0 for the other two.
+ *
+ * @public
+ */
+interface AgentRegistryOptions {
+    /**
+     * Maximum number of agents kept alive simultaneously. LRU eviction when
+     * exceeded. Default: 100.
+     *
+     * Setting `0` disables the cache entirely — every `Agent.getOrCreate`
+     * re-initializes (high cost, but predictable memory).
+     */
+    maxAgents?: number;
+    /**
+     * Idle timeout in milliseconds. Agents not used for this duration are
+     * evicted on the next sweep tick. Default: 1_800_000 (30 minutes).
+     * Set `0` to disable idle eviction.
+     */
+    idleTimeoutMs?: number;
+    /**
+     * Sweep interval in milliseconds. Default: 60_000 (60s).
+     * Lower = more responsive eviction but more CPU. Higher = staler entries.
+     */
+    sweepIntervalMs?: number;
+    /**
+     * Called whenever an agent is evicted. Listener errors are swallowed
+     * with a one-shot stderr warn (do not crash the eviction loop).
+     */
+    onEvict?: (id: string, reason: EvictReason) => void;
+}
+/**
+ * An LRU-plus-idle cache of live `SDKAgent` instances, reached through `Agent.registry`.
+ *
+ * It exists for long-running servers that would otherwise build a fresh agent per conversation and
+ * never release one. Do not confuse it with the metadata registry in `agent-registry.ts`, which
+ * persists `RegisteredAgent` records to disk: that one is the address book, this one is the live
+ * cache, and they share nothing.
+ *
+ * The lifecycle rule that matters to callers: eviction — by LRU, by idle timeout, or by an explicit
+ * `evict` — calls `dispose()` on the agent. A reference you held onto before eviction is a disposed
+ * agent, not a detached one. `get` counts as a use and refreshes the entry's timestamp, so polling
+ * for an agent keeps it alive indefinitely.
+ *
+ * Idle eviction depends on a background sweep that only `configure` starts. A registry nobody
+ * configured caches with the documented defaults but evicts by LRU alone, so entries can sit past
+ * `idleTimeoutMs` indefinitely; call `configure` — even with no changes — to arm the sweep.
+ *
+ * Failures on the eviction path are swallowed and reported to the diagnostics channel — a throwing
+ * `dispose()` or a throwing `onEvict` listener must not stop the sweep. Configuration is
+ * process-wide and last-call-wins.
+ *
+ * @public
+ */
+declare class LiveAgentRegistry {
+    #private;
+    /**
+     * Reconfigure registry behavior. Process-wide singleton (D310) — last
+     * configure call wins for all subsequent operations.
+     */
+    configure(opts: AgentRegistryOptions): void;
+    /**
+     * Lookup a cached agent. `get` is a use — refreshes `lastUsedAt` so the
+     * entry survives LRU eviction.
+     */
+    get(id: string): SDKAgent | undefined;
+    /**
+     * Insert or overwrite an agent in the cache. Triggers fire-and-forget LRU
+     * eviction when `size > maxAgents`.
+     *
+     * EC-4: when `id` already maps to a DIFFERENT agent instance, dispose the
+     * old one before overwriting (race protection against two `getOrCreate`
+     * calls creating two agents but only the second being cached — the first
+     * would leak file handles + lifecycle controllers).
+     */
+    set(id: string, agent: SDKAgent): void;
+    /**
+     * Explicitly evict an agent by id. Returns `true` when the entry was
+     * present (false = already gone). Calls `agent.dispose()` + `onEvict`
+     * with reason `"explicit"`.
+     */
+    evict(id: string): Promise<boolean>;
+    /**
+     * Evict every cached agent. Used by graceful shutdown (`process.on('SIGTERM')`)
+     * or end-of-test cleanup.
+     */
+    evictAll(): Promise<void>;
+    /** Number of currently cached agents. */
+    size(): number;
+    /** Ids of cached agents, newest first (by lastUsedAt). */
+    ids(): readonly string[];
+}
+
+/**
+ * Owner: `src/` (1 of 2 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * The shape of a persisted session turn, as a HOST reads it.
+ *
+ * Lives in `types/` because it is public contract — `Agent.transcript()` returns it (theokit#146).
+ * `internal/session/session-types.ts` re-exports it so the runtime and the store keep importing
+ * from the leaf they always did.
+ *
+ * @public
+ */
+
+/**
+ * One turn of a session.
+ *
+ * Two projections of the same turn, and they answer different questions:
+ *
+ * - `text` is the flat rendering the model replay uses. A tool call folds to `[tool call] NAME` and
+ *   a result to `[tool result] <body>`.
+ * - `parts` is the same turn unflattened, for a host that draws tool CARDS: the call id, the tool
+ *   name, the arguments, and the `toolUseId` that ties a result back to its call — none of which
+ *   survive the flat form.
+ *
+ * `parts` was added in theokit#146 and is additive: `text` is byte-identical to what it always was,
+ * so every existing reader is untouched.
+ *
+ * @public
+ */
+interface SessionMessage {
+    role: "user" | "assistant";
+    text: string;
+    /**
+     * The structured view. Optional because a `SessionMessage` can also be built in memory during a
+     * live turn, where only the text projection exists. Absent means "this projection carries no
+     * structure", never "this turn had none".
+     */
+    parts?: readonly SessionMessagePart[];
+}
+/**
+ * One structured element of a {@link SessionMessage}.
+ *
+ * Deliberately a session-DISPLAY shape rather than a re-export of the internal LLM part union: the
+ * two answer different questions (what to send a provider vs. what to draw), and coupling them
+ * would make every provider-wire change a change to what hosts render.
+ *
+ * @public
+ */
+type SessionMessagePart = {
+    readonly type: "text";
+    readonly text: string;
+} | {
+    readonly type: "tool_use";
+    readonly id: string;
+    readonly name: string;
+    readonly input: Record<string, unknown>;
+} | {
+    readonly type: "tool_result";
+    readonly toolUseId: string;
+    readonly content: string | ReadonlyArray<ToolResultContentBlock>;
+    readonly isError?: boolean;
+};
+
+/**
+ * Result of a one-shot {@link Agent.prompt} call.
+ *
+ * @public
+ */
+type AgentPromptResult = RunResult;
+/**
+ * Static façade for creating and managing Theo agents.
+ *
+ * @public
+ */
+declare class Agent {
+    private constructor();
+    /**
+     * Live-agent cache for production deploys (Production-Readiness #2, ADRs D307-D310).
+     *
+     * Caches `SDKAgent` instances by id with LRU eviction (when `size > maxAgents`)
+     * and an idle-timeout sweep. Solves the OOM failure mode for long-running
+     * Node servers spawning fresh agents per conversation.
+     *
+     * Defaults: `maxAgents: 100`, `idleTimeoutMs: 30 min`, sweep `60s`.
+     * Configure for high-traffic SaaS:
+     *
+     * ```ts
+     * Agent.registry.configure({ maxAgents: 1000, idleTimeoutMs: 15 * 60_000 });
+     * process.on("SIGTERM", () => Agent.registry.evictAll());
+     * ```
+     *
+     * Cache hits are automatic in `Agent.getOrCreate` (T2.6). Disable the cache
+     * entirely via `configure({ maxAgents: 0 })` — every getOrCreate then
+     * re-initializes.
+     *
+     * @public
+     */
+    static readonly registry: LiveAgentRegistry;
+    /**
+     * Create a new agent. Pass either `local` or `cloud` to pick a runtime.
+     *
+     * @public
+     */
+    static create(options: AgentOptions): Promise<SDKAgent>;
+    /**
+     * One-shot prompt: create an agent, send a single message, wait, **dispose**.
+     *
+     * `Agent.prompt` is STATIC and owns the agent's whole lifecycle. To send to an
+     * agent you already hold, use the instance method — `agent.send(message)` —
+     * which keeps the conversation and does not dispose anything:
+     *
+     * ```ts
+     * const agent = await Agent.create({ ... });
+     * const run = await agent.send("first");     // NOT agent.prompt(...)
+     * const run2 = await agent.send("follow-up"); // full context retained
+     * ```
+     *
+     * There is no `agent.prompt()` (#302). The natural sentence for the second
+     * operation is "prompt the agent", so it is the method people reach for; the
+     * two differ in whether the agent survives the call, which is why they do not
+     * share a name.
+     *
+     * When `options.throwOnError === true`, rejects with `AgentRunError` if
+     * the run terminates with `status: 'error'` (instead of resolving with the
+     * error wrapped in the RunResult). Cancelled runs still resolve normally.
+     *
+     * @public
+     */
+    static prompt(message: string, options: AgentOptions): Promise<AgentPromptResult>;
+    /**
+     * Reattach to an existing agent by ID.
+     *
+     * @public
+     */
+    static resume(agentId: string, options?: Partial<AgentOptions>): Promise<SDKAgent>;
+    /**
+     * Start building an {@link AgentOptions} via fluent chain. See ADR D25.
+     * Terminals: `.build()`, `.create()`, `.getOrCreate(id)`.
+     *
+     * The builder receives `create` + `getOrCreate` as injected callbacks so
+     * that `agent-builder.ts` doesn't need a static import of `Agent` — keeps
+     * the module graph acyclic (G6).
+     *
+     * @public
+     */
+    static builder(): AgentBuilder;
+    /**
+     * Generate a typed object matching a Zod schema via a synthetic forced
+     * tool call (ADR D33). One-shot: create transient agent → send prompt →
+     * model calls `output` tool → parse args via Zod → return typed.
+     *
+     * @public
+     */
+    static generateObject<T extends zod.ZodType>(options: GenerateObjectOptions<T>): Promise<GenerateObjectResult<zod.z.infer<T>>>;
+    /**
+     * Stream a structured output object alongside intermediate `partial`
+     * deltas as the model accumulates its response (ADR D39). Returns an
+     * `AsyncIterator<StreamObjectEvent<T>>` that yields zero or more
+     * `partial` events and exactly one `complete` event at the end.
+     *
+     * The `complete` event carries the same `object: z.infer<T>` you would get
+     * from `Agent.generateObject` — same prompt + schema + model produces
+     * the same final object.
+     *
+     * @public
+     */
+    static streamObject<T extends zod.ZodType>(options: StreamObjectOptions<T>): AsyncGenerator<StreamObjectEvent<zod.z.infer<T>>, void, void>;
+    /**
+     * Run N prompts in parallel with bounded concurrency (ADRs D134-D140).
+     *
+     * Each prompt gets a fresh agent (create → send → wait → dispose). Failures
+     * are isolated per-prompt; the batch never throws on a single failure —
+     * inspect `result.ok` to discriminate success vs error. Default
+     * concurrency is 4. When `options.providers.apiKeys` has ≥2 keys per
+     * provider, all in-flight agents share a single credential pool via
+     * `AsyncLocalStorage` (EC-A) so rate-limit cooldowns are observed once
+     * instead of duplicated per agent.
+     *
+     * Streaming progress is opt-in via `onResult` / `onProgress`. `AbortSignal`
+     * cancels pending prompts; in-flight ones continue to completion (Node
+     * AbortSignal semantics). `signal.reason` propagates to `error` when set.
+     *
+     * @public
+     */
+    static batch(prompts: ReadonlyArray<string | BatchItem>, options: BatchOptions): Promise<BatchResult[]>;
+    /**
+     * Get an existing agent by ID, or create one with the supplied options if
+     * the ID is not yet registered. Eliminates the resume-vs-create boilerplate
+     * common to chat bots and other long-running agent consumers. See ADR D22.
+     *
+     * Resolution:
+     * 1. Try `Agent.resume(agentId, options)`. Return on success.
+     * 2. On `UnknownAgentError`, fall through to `Agent.create({ ...options, agentId })`.
+     * 3. On same-process race (`ConfigurationError(code: "agent_id_already_exists")`
+     *    during step 2), retry `Agent.resume` once and return the winner's handle.
+     * 4. Any other error propagates verbatim.
+     *
+     * Caveats:
+     * - The function-level `agentId` always wins over `options.agentId`.
+     * - Options differ between calls? Last-call-wins for this handle (matches `Agent.resume`).
+     * - A DISPOSED agent is replaced automatically. `dispose()` evicts the id from the
+     *   live cache (`liveAgentRegistry.forget`), so the next `getOrCreate(id)` builds a
+     *   fresh handle — no `Agent.delete(agentId)` needed.
+     *
+     *   This bullet used to say the opposite ("Disposed agents are NOT auto-deleted...
+     *   call `Agent.delete(agentId)` first"). It was measured false in M91:
+     *   `tests/agent-getorcreate-after-dispose.test.ts` builds an agent, disposes it, and
+     *   gets a different instance back. The claim was about the PERSISTENT registry and
+     *   read as being about the live cache — and consumers built around the wrong half.
+     *   The agent-builder's M85 interrupt rotates the session id to work around a
+     *   constraint that does not exist.
+     *
+     * - `close()` marks the handle disposed WITHOUT evicting the cache entry. It is
+     *   internal and unused today; if it becomes reachable, this bullet stops being true
+     *   for that path.
+     *
+     * @public
+     */
+    static getOrCreate(agentId: string, options: AgentOptions): Promise<SDKAgent>;
+    /**
+     * List agents (local or cloud). M107 — `cwd` is READ, not ignored. B-115 (2026-08-19) —
+     * `includeArchived` and `limit`/`cursor` are READ too now; see `ListAgentsOptions`'s doc for the
+     * pagination contract and why the unlimited (no `limit`) case is unaffected.
+     *
+     * @public
+     */
+    static list(options?: ListAgentsOptions): Promise<ListResult<SDKAgentInfo>>;
+    /**
+     * Get metadata for a single agent. B-115 (2026-08-19) — `cwd` is READ now (see
+     * `GetAgentOptions`'s doc); it used to be accepted and silently ignored.
+     *
+     * @public
+     */
+    static get(agentId: string, options?: GetAgentOptions): Promise<SDKAgentInfo>;
+    /**
+     * List runs for an agent. B-115 (2026-08-19) — `cwd` and `limit`/`cursor` are READ now (see
+     * `ListRunsOptions`'s doc); they used to be accepted and silently ignored.
+     *
+     * @public
+     */
+    static listRuns(agentId: string, options?: ListRunsOptions): Promise<ListResult<Run>>;
+    /**
+     * Get a single run.
+     *
+     * @public
+     */
+    static getRun(runId: string, options?: GetRunOptions): Promise<Run>;
+    /**
+     * Archive a cloud agent.
+     *
+     * @public
+     */
+    static archive(agentId: string, _options?: AgentOperationOptions): Promise<void>;
+    /**
+     * Restore an archived cloud agent.
+     *
+     * @public
+     */
+    static unarchive(agentId: string, _options?: AgentOperationOptions): Promise<void>;
+    /**
+     * Set the human-facing `name` of a registered agent (the label `Agent.list()` returns). The registry
+     * already carries a `name` field; this is the missing public mutator for it. Runtime-agnostic (mutates
+     * the local per-cwd registry for local agents; the cloud registry for cloud agents).
+     *
+     * @public
+     */
+    static rename(agentId: string, name: string, _options?: AgentOperationOptions): Promise<void>;
+    /**
+     * M50 — compact a LOCAL agent's persisted session transcript (Codex `/compact` parity): the
+     * history is summarized (recent user messages preserved verbatim + one marker'd summary) and an
+     * append-only `compact_boundary` + replacement chain is written — resume replays only the
+     * replacement + later turns. The summarizer defaults to the compression subsystem's aux-LLM
+     * (its first real caller); tests/consumers may inject their own.
+     *
+     * @public
+     */
+    static compact(agentId: string, options?: {
+        trigger?: "manual" | "auto";
+        summarize?: (messages: readonly CompressibleMessage[]) => Promise<string>;
+    }): Promise<CompactResult>;
+    /**
+     * M51 — inject a SYNTHETIC user+assistant pair into a LOCAL session's persisted transcript WITHOUT
+     * running an LLM turn (the Codex review-exit mechanism: the parent thread "learns" a result — e.g.
+     * review findings — so follow-ups work). Appends onto the DAG leaf and invalidates the in-memory
+     * cache; serialized on the per-agent write chain.
+     *
+     * @public
+     */
+    static injectSessionTurn(agentId: string, turn: {
+        userText: string;
+        assistantText: string;
+    }): Promise<void>;
+    /**
+     * theokit#146 — read a LOCAL agent's persisted transcript as STRUCTURE, for rendering.
+     *
+     * A resumed session already replays correctly to the model, but a host had no way to draw it:
+     * the only projection available folded a tool call to the string `[tool call] NAME`, dropping the
+     * call id and every argument. A card UI got prose, so cross-restart resume was worth less than
+     * starting fresh — which is what at least one consumer did.
+     *
+     * Each returned message carries both projections: `text` (unchanged, what the model replay uses)
+     * and `parts` (`text` / `tool_use` / `tool_result` with ids, names, arguments and the
+     * `toolUseId` that correlates a result back to its call).
+     *
+     * Read-only and local-only: it opens the agent's session store and walks the transcript, exactly
+     * as {@link Agent.compact} and {@link Agent.injectSessionTurn} do. It appends nothing.
+     *
+     * @throws UnknownAgentError when `agentId` names no local agent.
+     * @public
+     */
+    static transcript(agentId: string): Promise<readonly SessionMessage[]>;
+    /**
+     * theokit#123 — read-only introspection of a registered agent's tools and subagents.
+     *
+     * `Agent.list()` / `Agent.get()` enumerate agents and `agent.skills.list()` covers skills, but
+     * tools and subagents lived only on `RegisteredAgent.options` — an internal contract. A
+     * reflection endpoint (theokit-studio's `theokit dev`) therefore had to report empty lists for
+     * both, and say so with an `unavailable_reason`.
+     *
+     * A PROJECTION, not the options object. Tool handlers and subagent prompts are stripped: a
+     * handler is an executable that cannot cross a process boundary, and a prompt is the agent's
+     * instructions rather than its signature — a reflection endpoint serializes what it is handed.
+     *
+     * @throws UnknownAgentError when `agentId` names no registered agent.
+     * @public
+     */
+    static describe(agentId: string): Promise<AgentDescription>;
+    /**
+     * Permanently delete a cloud agent.
+     *
+     * @public
+     */
+    static delete(agentId: string, _options?: AgentOperationOptions): Promise<void>;
+}
+
+/**
+ * Handle returned by {@link createAgentFactory}. See ADR D23 for merge
+ * semantics.
+ *
+ * @public
+ */
+interface AgentFactory {
+    /**
+     * Create a fresh agent for this session. Equivalent to `Agent.create(merged)`
+     * where `merged` is `common` ⊕ `overrides` ⊕ `{ agentId }`.
+     */
+    forSession(agentId: string, overrides?: Partial<AgentOptions>): Promise<SDKAgent>;
+    /**
+     * Resume an existing agent for this session, or create one if the ID is
+     * unknown. Equivalent to `Agent.getOrCreate(agentId, merged)`.
+     */
+    getOrCreate(agentId: string, overrides?: Partial<AgentOptions>): Promise<SDKAgent>;
+}
+/** SE36 — `AgentFactory.create` replaces `createAgentFactory` (ADR 0015). Merges with the `AgentFactory` interface. @public */
+declare class AgentFactory {
+    private constructor();
+    static create(common: Partial<AgentOptions>): AgentFactory;
+}
+
+/**
+ * Decide whether a tool call proceeds, and say WHY — as a typed signal rather than a tool result.
+ *
+ * When a veto is delivered as an ordinary tool result, the MODEL reads it as output: it sees a
+ * string, concludes the tool failed for some reason, and retries or works around it. A denial, an
+ * error, and a tool that legitimately returned the word "denied" become indistinguishable to
+ * everything downstream — including the surface that should be telling the user what happened.
+ *
+ * ## What is generic, and what is not
+ *
+ * The RULE is a precedence: an explicit per-tool decision outranks the mode, a convenience mode does
+ * not overturn an explicit refusal, and anything undecided falls to the mode. The VOCABULARY is not
+ * — which tools exist belongs to the product and arrives as data. Nothing here names one.
+ *
+ * Deliberately separate from the blast-radius policy: that one answers "what does this action
+ * reach", this one answers "who said yes". Keeping them apart is what lets a product gate on reach
+ * without re-implementing the mode ladder, and compose both where it needs to.
+ *
+ * @public
+ */
+/** What the operator chose for everything not decided per tool. @public */
+type ApprovalMode = "ask" | "never-ask" | "refuse-all";
+/**
+ * The three answers a policy can give: proceed, put the call in front of a human, or stop it.
+ *
+ * `ask` is not a softer `deny`. A surface with no way to reach a human must treat it as a refusal,
+ * because treating it as permission is how an unattended run approves everything it was meant to
+ * pause on.
+ *
+ * @public
+ */
+type ApprovalOutcome = "allow" | "ask" | "deny";
+/**
+ * Which rule produced the outcome.
+ *
+ * The `explicitly-` pair means a per-tool list decided it; the `mode-` triple means no list named
+ * the tool and the operator's mode decided instead. Worth rendering alongside the outcome: "you
+ * denied this tool" and "your mode refuses everything" send the operator to different settings.
+ *
+ * @public
+ */
+type ApprovalReason = "explicitly-allowed" | "explicitly-denied" | "mode-ask" | "mode-never-ask" | "mode-refuse-all";
+/**
+ * One tool call to decide on, plus the operator's configuration.
+ *
+ * `tool` is matched against `denied` and `allowed` by exact string equality — there is no pattern
+ * or prefix rule. Both lists default to empty, so with neither supplied every call is decided by
+ * `mode` alone.
+ *
+ * @public
+ */
+interface ApprovalInput {
+    readonly tool: string;
+    readonly mode: ApprovalMode;
+    /** Tools the operator allowed once and for all. */
+    readonly allowed?: readonly string[];
+    /** Tools the operator refused. Outranks `allowed` and every mode. */
+    readonly denied?: readonly string[];
+}
+/**
+ * The answer, the rule that produced it, and the tool it was about.
+ *
+ * @public
+ */
+interface ApprovalDecision {
+    readonly outcome: ApprovalOutcome;
+    readonly reason: ApprovalReason;
+    /** The tool the decision was about, so a surface names it without re-deriving it. */
+    readonly tool: string;
+}
+/**
+ * Decide one tool call against the operator's lists and mode.
+ *
+ * The precedence is fixed and each step short-circuits: `denied` is consulted first, then
+ * `allowed`, then `mode`. A tool named in BOTH lists is therefore denied — a contradictory config
+ * is read restrictively, because the usual cause is an allow-entry that outlived the denial meant
+ * to replace it.
+ *
+ * This answers only who said yes. What the call REACHES is a separate question with a separate
+ * policy — `evaluateBlastRadius` — and neither consults the other, so a product that wants both
+ * gates calls both and combines the outcomes itself.
+ *
+ * @returns the outcome, why it was reached, and the tool it was about.
+ * @public
+ */
+declare function decideApproval(input: ApprovalInput): ApprovalDecision;
+
+/**
+ * Decide an action by what it REACHES and whether it can be undone — not by its name.
+ *
+ * A sandbox answers "which files may this process touch", and that is a different question from the
+ * one that decides whether an action is safe. A tool that drops a production database touches no
+ * file the sandbox cares about; a tool that lists pods reaches an entire cluster while writing
+ * nothing. Confinement covers the disk, not the reach.
+ *
+ * With nothing better available, every product gates on the tool's NAME: an allowlist of strings
+ * that says nothing about what the tool does, drifts the moment one is renamed, and cannot be
+ * reasoned about by anyone who did not write it. A guard each product re-implements is a guard some
+ * product forgets.
+ *
+ * ## What is generic here, and what is not
+ *
+ * The RULE is: an action declares the scope it reaches and whether it is reversible, and a policy
+ * decides from those two facts plus what the operator granted. The VOCABULARY is not — which scopes
+ * exist ("cluster:prod", "billing-account", "the laptop") belongs to the product and arrives as
+ * data. Nothing in this module names a scope, the same way the security floor names no sandbox mode
+ * and the trust posture names no capability.
+ *
+ * ## Why the reason is part of the answer
+ *
+ * "The sandbox stopped this" and "you never granted reach to that scope" are different facts with
+ * different fixes, and an operator told the wrong one widens the wrong thing. So a decision carries
+ * WHY — the same reason a trust posture reports its `source` and a wiring record distinguishes
+ * withheld-by-trust from never-configured.
+ *
+ * @public
+ */
+/** What an action reaches, and whether it can be taken back. @public */
+interface DeclaredAction {
+    /**
+     * The product's name for what this action reaches. An empty string is treated as UNDECLARED and
+     * refused: a tool that forgot to declare is not a tool that reaches nothing.
+     */
+    readonly scope: string;
+    /**
+     * Whether the action can be undone. Reversible actions inside a granted scope proceed;
+     * irreversible ones ask, because granting reach is not granting destruction.
+     */
+    readonly reversible: boolean;
+}
+/**
+ * The action to decide on, plus what the operator granted.
+ *
+ * `granted` is matched against `action.scope` by exact string equality: there is no prefix or
+ * wildcard rule, so granting `cluster:prod` does not grant `cluster:prod:kube-system`. A product
+ * that wants hierarchical scopes expands them itself before calling.
+ *
+ * `irreversibleAllowed` defaults to empty, so an irreversible action inside a granted scope asks
+ * for approval unless its scope was pre-approved for destruction as well.
+ *
+ * @public
+ */
+interface BlastRadiusInput {
+    readonly action: DeclaredAction;
+    /** Scopes the operator granted reach to. Empty grants nothing — never everything. */
+    readonly granted: readonly string[];
+    /** Scopes where the operator pre-approved irreversible actions, so an unattended run can work. */
+    readonly irreversibleAllowed?: readonly string[];
+}
+/**
+ * What the policy decided.
+ *
+ * `require-approval` means a human has to say yes before the action runs; a caller with no way to
+ * ask must treat it as a refusal. `refuse` is not appealable through this policy at all — the
+ * operator has to grant the scope first, which is deliberately a configuration change rather than
+ * a prompt.
+ *
+ * @public
+ */
+type BlastRadiusOutcome = "allow" | "require-approval" | "refuse";
+/** Why the decision came out that way. Rendered to the operator and read by an audit. @public */
+type BlastRadiusReason = "within-granted-scope" | "irreversible" | "scope-not-granted" | "scope-undeclared";
+/**
+ * The outcome, the rule that produced it, and the scope it was decided about.
+ *
+ * `scope` echoes what the action declared, so it is the empty string when the reason is
+ * `scope-undeclared` — the decision names what it saw rather than substituting a placeholder.
+ *
+ * @public
+ */
+interface BlastRadiusDecision {
+    readonly outcome: BlastRadiusOutcome;
+    readonly reason: BlastRadiusReason;
+    /** The scope the decision was made about, so a surface can name it without re-deriving it. */
+    readonly scope: string;
+}
+/**
+ * Decide one declared action against the scopes the operator granted.
+ *
+ * Four checks, in this order, each short-circuiting: an empty `scope` is refused as undeclared
+ * before any comparison happens; a scope absent from `granted` is refused; an irreversible action
+ * whose scope is not in `irreversibleAllowed` escalates to approval; anything left is allowed.
+ *
+ * Refusal outranking escalation is a decision, not an accident. Asking a human to approve a scope
+ * the operator never granted trains them to approve by reflex, which is how an approval prompt
+ * stops being a control.
+ *
+ * This decides reach only. Whether the operator permitted the tool at all is `decideApproval`, and
+ * the two are independent.
+ *
+ * @returns the outcome with the reason and the scope it was decided on.
+ * @public
+ */
+declare function evaluateBlastRadius(input: BlastRadiusInput): BlastRadiusDecision;
+
+/**
+ * computeCost — apply pricing entries to a TokenUsage and produce a
+ * CostBreakdown (ADRs D377, D378).
+ *
+ * Edge cases absorbed:
+ *   - EC-13: negative pricing → status="unknown" + note.
+ *   - EC-14: reasoning tokens fall back to outputCostPerMillion when
+ *     dedicated reasoning rate is undefined.
+ *   - EC-12: money precision via microcent normalization (× 1e6).
+ *   - "subscription_included" routes (Codex CLI, future Claude Pro) →
+ *     return $0 with status="included".
+ *   - Provider unknown / pricing missing → status="unknown" with
+ *     undefined amountUsd (does NOT return a false 0).
+ *
+ * @internal
+ */
+interface ComputeArgs {
+    readonly usage: TokenUsage;
+    readonly provider: string;
+    readonly model: string;
+    readonly baseUrl?: string;
+}
+/**
+ * Returns CostBreakdown with `status="estimated"`, `"unknown"`, or
+ * `"included"`. Never throws; never returns 0 when pricing is missing.
+ */
+declare function computeCost(args: ComputeArgs): CostBreakdown;
+
+/**
+ * Budget enforcement (ADRs D383, D386, EC-7/8/9).
+ *
+ * - `preflightCheck(name, estimatedUsd)` — in `block` mode, throw
+ *   `BudgetExceededError` before the LLM call if any limit would be
+ *   exceeded (EC-9 — the caller invokes it inside the mutex section).
+ * - `chargeAndCheckThresholds(name, actualUsd)` — apply the charge to the
+ *   ledger + invoke onThreshold/onExceed callbacks isolated in
+ *   try/catch (EC-8).
+ *
+ * @internal
+ */
+/**
+ * Throws BudgetExceededError if `mode === "block"` and any limit
+ * would be exceeded. No-op for audit/warn modes (post-charge checks
+ * handle those).
+ *
+ * Caller invokes this BEFORE the LLM call.
+ */
+declare function preflightCheck(name: string, estimatedUsd: number): void;
+/**
+ * Charge the budget + dispatch threshold/exceed callbacks (EC-8 isolated).
+ *
+ * - In `audit` mode: charge only, no callbacks.
+ * - In `warn` mode: charge + onThreshold (80/95) + onExceed (100). No throw.
+ * - In `block` mode: charge + onThreshold + onExceed. No throw post-call
+ *   (preflightCheck already prevented exceed for the upcoming call;
+ *   this protects against simultaneous-call races where multiple sends
+ *   each pass preflight independently — last one to charge may still
+ *   tip a limit. We document the case rather than retroactively throw).
+ */
+declare function chargeAndCheckThresholds(name: string, actualUsd: number): Promise<void>;
+
+/**
+ * normalizeUsage — convert provider-shaped raw `usage` object to
+ * canonical `TokenUsage`. Ports Hermes Agent's `normalize_usage`
+ * (reference/peer-agent/agent/usage_pricing.py:672-742).
+ *
+ * Handles 3 API shapes:
+ *   - Anthropic Messages: 4 explicit buckets (input/output/cache_read/cache_creation).
+ *   - OpenAI Chat Completions: prompt_tokens INCLUDES cache; subtract cached_tokens.
+ *   - OpenAI Responses (Codex): input_tokens INCLUDES cache; same subtraction.
+ *
+ * Edge cases:
+ *   - a peer#10266 — OpenAI-compat proxies (OpenRouter, a peer vendor AI Gateway,
+ *     a peer) routing Claude expose Anthropic-style top-level fields
+ *     (cache_read_input_tokens / cache_creation_input_tokens). Both
+ *     locations are checked with top-level fallback.
+ *   - Null/undefined fields → 0 via `int()` coerce.
+ *   - String token counts → parsed via int.
+ *   - Negative values → clamped to 0 (defensive against proxy bugs).
+ *
+ * @internal
+ */
+type ApiMode = "anthropic_messages" | "openai_chat_completions" | "openai_responses";
+/**
+ * Guess which usage shape a provider reports, from its name alone.
+ *
+ * Matching is case-insensitive and exact — `"anthropic"`, `"claude"` and `"bedrock_anthropic"`
+ * give `"anthropic_messages"`; `"openai-codex"` and `"codex"` give `"openai_responses"`. Every
+ * other name, including ones this SDK has never seen, falls through to
+ * `"openai_chat_completions"`. There is no unknown result, so a wrong guess is silent: it is
+ * read as a Chat Completions payload, whose fields are absent, and the tokens come back as 0.
+ *
+ * The default is right for the OpenAI-compatible majority (openai, openrouter, deepseek, and the
+ * compat endpoints of google, ollama and lmstudio). When it is not, pass `apiMode` to
+ * `normalizeUsage` explicitly instead of relying on the name.
+ */
+declare function inferApiMode(provider: string): ApiMode;
+/**
+ * Convert a provider's raw `usage` object into the SDK's canonical `TokenUsage`.
+ *
+ * Never throws and never reports failure. `null`, `undefined` and any non-object argument return
+ * all-zero usage, which is indistinguishable from a real response that used no tokens — so this
+ * is not the place to detect a malformed payload.
+ *
+ * `opts.apiMode` selects the reader; when omitted it is derived from `opts.provider` via
+ * `inferApiMode`, whose fallback is Chat Completions. Pass it explicitly for any provider whose
+ * name does not identify its wire shape.
+ *
+ * The shapes differ in one way that matters: Anthropic reports cache tokens in buckets separate
+ * from `input_tokens`, while both OpenAI shapes report a prompt total that already includes
+ * them. For the OpenAI readers the cache buckets are subtracted, so `inputTokens` is always the
+ * uncached portion and `inputTokens + cacheReadTokens + cacheWriteTokens` reconstructs the
+ * provider's prompt total. The subtraction is floored at 0, so a payload whose cache counts
+ * exceed its prompt total yields 0 rather than a negative.
+ *
+ * Every field is coerced: numbers are truncated toward zero, numeric strings are parsed, negative
+ * and non-finite values become 0, and anything else becomes 0.
+ *
+ * `totalTokens` is computed here as input + output + both cache buckets; a `total_tokens` the
+ * provider sent is ignored. Reasoning tokens are reported separately but are NOT added again —
+ * providers already count them inside output. `cacheReadTokens`, `cacheWriteTokens` and
+ * `reasoningTokens` are omitted from the result when they are 0, so absent means zero, not
+ * unknown.
+ *
+ * Chat Completions also accepts Anthropic-style top-level `cache_read_input_tokens` /
+ * `cache_creation_input_tokens`, which OpenAI-compatible proxies emit when they route Claude.
+ * The nested `prompt_tokens_details` values win; the top-level fields are consulted only when
+ * those are 0 or missing.
+ */
+declare function normalizeUsage(rawUsage: unknown, opts: {
+    provider: string;
+    apiMode?: ApiMode;
+}): TokenUsage;
+
+/**
+ * Pricing registry — bundled snapshot of LiteLLM JSON (ADR D379) with
+ * lazy load + alias normalization (EC-2).
+ *
+ * Snapshot lives in `pricing-data.json` (hand-curated 2026-05; refresh
+ * via `scripts/refresh-pricing.mjs`). All rates in USD per 1_000_000
+ * tokens (D378).
+ *
+ * Lookup precedence (EC-2):
+ *   1. Direct `provider/model` key
+ *   2. Strip date suffix (-YYYYMMDD or -YYYY-MM-DD)
+ *   3. Anthropic dot-to-dash normalization (claude-opus-4.7 → claude-opus-4-7)
+ *   4. Strip `openrouter/` prefix
+ *
+ * @internal
+ */
+interface PricingEntry {
+    readonly provider: string;
+    readonly model: string;
+    readonly inputCostPerMillion: number;
+    readonly outputCostPerMillion: number;
+    readonly cacheReadCostPerMillion?: number;
+    readonly cacheWriteCostPerMillion?: number;
+    readonly reasoningCostPerMillion?: number;
+    readonly pricingVersion: string;
+}
+/**
+ * Returns the pricing entry for a given `{provider, model}` route.
+ * Tries direct lookup, then 3 alias normalizations (EC-2).
+ */
+declare function getPricingEntry(opts: {
+    provider: string;
+    model: string;
+    baseUrl?: string;
+}): PricingEntry | undefined;
+
+/**
+ * UsageAccumulator — aggregate multi-step `LlmFinish` token counts
+ * into a canonical `TokenUsage` (ADR D376, mirror a peer SDK
+ * `Usage.add`).
+ *
+ * Each `add(step)` merges in a per-step finish; `toTokenUsage()`
+ * produces the aggregated public shape with `requests[]` populated
+ * when there were ≥2 steps.
+ *
+ * @internal
+ */
+interface StepUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+}
+/**
+ * Sums the per-step token counts of a multi-step run into one `TokenUsage`.
+ *
+ * Call `add` once per LLM finish, in any order, then `toTokenUsage` to read the total. The instance
+ * is a running sum, not a snapshot: `toTokenUsage` may be called repeatedly and reflects everything
+ * added so far, and there is no reset — start a new accumulator per run.
+ *
+ * Two shaping rules to expect in the output. The optional counters (cache read, cache write,
+ * reasoning) are omitted entirely when they sum to zero rather than reported as `0`. And the
+ * per-step `requests` array appears only when at least TWO steps were added, so a single-step run
+ * carries totals alone.
+ *
+ * `totalTokens` is input plus output only — cache and reasoning counts are reported separately and
+ * are not folded into it.
+ */
+declare class UsageAccumulator {
+    private input;
+    private output;
+    private cacheRead;
+    private cacheWrite;
+    private reasoning;
+    private readonly requests;
+    add(step: StepUsage): void;
+    /** Did we observe any usage at all? */
+    hasAny(): boolean;
+    toTokenUsage(): TokenUsage;
+}
+
+/**
+ * `Budget` — token cost enforcement primitive (Adoption Roadmap #1
+ * post-Tasks, ADRs D375-D388).
+ *
+ * Static facade delegating to the in-process registry + ledger.
+ * 3 modes: `audit` (log-only), `warn` (callbacks + log), `block`
+ * (preflight throw before LLM call).
+ *
+ * @public
+ *
+ * @deprecated since SDK 2.0 (iter 18+) — import this facade from
+ * `@theokit/sdk-budget` instead. The sources backing this facade have
+ * been physically extracted to `@theokit/sdk-budget/internal/` per
+ * ADR-008. The sdk-core copies are retained for the v1.x sync API
+ * contract; consumers MUST migrate before sdk-core v3.0.
+ *
+ * Migration:
+ *
+ * ```ts
+ * // Before (sdk-core, deprecated):
+ * import { Budget, computeCost } from "@theokit/sdk";
+ *
+ * // After (sdk-budget, authoritative):
+ * import {
+ *   chargeAndCheckThresholds,
+ *   createBudget,
+ *   computeUsdCost,  // replaces computeCost
+ *   createUsdBudgetTracker,
+ * } from "@theokit/sdk-budget";
+ * ```
+ */
+
+declare class Budget {
+    private constructor();
+    /**
+     * Create a budget. `name` must match `^[a-z0-9][a-z0-9_-]*$` (EC-7).
+     * Throws `ConfigurationError` if name is invalid OR already exists
+     * (EC-16: duplicate surface caller bug).
+     *
+     * `limits` is stacked (D384) — ANY exceeded triggers enforcement.
+     * Empty `limits[]` is valid: pure tracking, no thresholds/exceed
+     * callbacks fire (EC-19).
+     *
+     * Default `mode` is `"warn"` (D383). For emergency stop, use
+     * `mode: "block", limits: [{ window: "1d", limitUsd: 0 }]` (EC-18).
+     */
+    static create(options: BudgetOptions): BudgetHandle;
+    /** Returns the handle for an active budget, or `undefined`. */
+    static get(name: string): BudgetHandle | undefined;
+    /** Returns all active budgets. */
+    static list(): readonly BudgetHandle[];
+    /**
+     * Deletes a budget from the registry. Returns `true` if it existed.
+     * In-flight `agent.send` calls referencing the name treat the
+     * subsequent charge as a silent no-op + stderr warn (EC-20).
+     */
+    static delete(name: string): boolean;
+    /**
+     * Returns per-window spend snapshot for all active budgets. Each
+     * entry has `{ name, window, spentUsd, limitUsd, ratio }`.
+     */
+    static snapshot(): readonly BudgetSnapshot[];
+}
+
+/**
+ * SE25 — deterministic, no-LLM guardrail processors built on the SE24
+ * {@link Processor} seam. Cheap and churn-free (no provider/model deltas), so
+ * they are safe to own in-core — unlike the LLM-classifier processors, which are
+ * delegated (see the guardrails ADR). All are OPT-IN: add them to
+ * `AgentOptions.inputProcessors` / `outputProcessors`.
+ *
+ * @public
+ */
+/**
+ * Approximate token count from string length. This is an ESTIMATE
+ * (≈ UTF-16-code-units / 4, NOT Unicode code points, NOT an exact per-model
+ * tokenizer count) — good enough for a coarse cap, and dependency-free.
+ *
+ * Re-exported rather than reimplemented: the ratio lives in `compaction.ts`, which is where the
+ * heuristic is load-bearing. The name and the behaviour here are unchanged.
+ */
+
+/** Options for {@link createUnicodeNormalizer}. @public */
+interface UnicodeNormalizerOptions {
+    /** Remove C0 + C1 control chars + DEL (keeps tab / newline / carriage-return). Default `false`. */
+    stripControlChars?: boolean;
+    /** Collapse runs of intra-line whitespace to one space, 3+ blank lines to one, and trim. Default `false`. Uses legacy `\s`; Unicode-only whitespace (U+00A0 NBSP, U+FEFF BOM, U+2000–U+200A) is NOT collapsed. */
+    collapseWhitespace?: boolean;
+}
+/** Options for {@link createTokenLimiter}. @public */
+interface TokenLimiterOptions {
+    /** Positive integer token budget (estimate — see {@link estimateTokens}). */
+    limit: number;
+    /** Over the limit: `"truncate"` (default, cut to fit) or `"block"` (abort with a tripwire). */
+    strategy?: "truncate" | "block";
+}
+/** SE36 — `TokenLimiter.create` replaces `createTokenLimiter` (ADR 0015). @public  *
+ * `TokenLimiter.create` returns a **`Processor`**, not a `TokenLimiter`. The class is
+ * the namespace; the processor is the product.
+ */
+declare class TokenLimiter {
+    private constructor();
+    static create(opts: TokenLimiterOptions): Processor;
+}
+/** SE36 — `UnicodeNormalizer.create` replaces `createUnicodeNormalizer` (ADR 0015). @public  *
+ * `UnicodeNormalizer.create` returns a **`Processor`**, not a `UnicodeNormalizer`. The
+ * class is the namespace; the processor is the product.
+ */
+declare class UnicodeNormalizer {
+    private constructor();
+    static create(opts?: UnicodeNormalizerOptions): Processor;
+}
+
+/**
+ * Report whether a credential resolved — never what it is.
+ *
+ * Every agent product grows a "why can't I use this model?" surface: a doctor command, a status
+ * panel, a startup diagnostic. Each needs to know whether a credential resolved, and each is one
+ * careless line from printing it. The line is careless precisely because it is convenient — the
+ * value is right there, and whoever is debugging a routing problem wants to see it.
+ *
+ * So presence-only is the DEFAULT here rather than each consumer's discipline. Discipline is what
+ * every product has until the day it does not, and a leaked key is not a defect anyone can withdraw.
+ *
+ * ## Why a fingerprint and not a prefix
+ *
+ * A report has to be actionable: two people asking "is it the same key?" need something to compare.
+ * The convenient answer — the first eight characters — is still the secret, and it is enough to
+ * identify a key in a breach corpus. A hash is not.
+ *
+ * @public
+ */
+/**
+ * One provider's credential lookup, as the product resolved it.
+ *
+ * `value` is the secret itself. It is hashed and dropped inside `describeCredential` — it never
+ * reaches the report, and nothing here stores it.
+ *
+ * @public
+ */
+interface CredentialInput {
+    /** The product's name for the provider. This module never knows one of its own. */
+    readonly provider: string;
+    /** The resolved secret, or `undefined`/empty when nothing resolved. */
+    readonly value: string | undefined;
+    /** Where it came from, in the product's vocabulary — `env`, `file`, `keychain`, `oauth`. */
+    readonly source: string;
+}
+/**
+ * A presence-only view of one credential, safe to print, log, or attach to a support bundle.
+ *
+ * `fingerprint` is the first eight hex characters of the SHA-256 of the trimmed secret: enough for
+ * two people to agree they are holding the same key, and not a substring of it. It is absent
+ * whenever `present` is false.
+ *
+ * @public
+ */
+interface CredentialReport {
+    readonly provider: string;
+    readonly present: boolean;
+    readonly source: string;
+    /** Eight hex characters of a hash. Absent when no credential resolved. Never a prefix. */
+    readonly fingerprint?: string;
+}
+/**
+ * Turn a resolved credential into something you can show a user.
+ *
+ * The value is trimmed before the emptiness test, so `undefined`, `""` and whitespace all report
+ * `present: false` with no fingerprint. That matters because an environment variable that expanded
+ * to nothing arrives as an empty string, and calling that "present" sends whoever is debugging to
+ * hunt for a routing bug instead of a missing secret.
+ *
+ * @returns a report safe to log, render and attach to a support bundle.
+ * @public
+ */
+declare function describeCredential(input: CredentialInput): CredentialReport;
+
+/**
+ * Plugin contract — RUNTIME value + type re-exports (T1.1, ADRs D97-D101).
+ *
+ * SE45/SE46 — the pure `Plugin` *type* and its type companions now live in
+ * `types/plugin.ts` (above the DIP boundary, because `Plugin` is public
+ * contract). This module keeps the RUNTIME value (`definePlugin` /
+ * `Plugin.create`) and re-exports the types so every existing
+ * `../plugins/types.js` importer (and the `index.ts` barrel) resolves the same
+ * names unchanged.
+ *
+ * @public
+ */
+
+/**
+ * Identity helper for plugin authors. TS-only convenience — preserves
+ * inferred type without forcing manual `Plugin` annotation.
+ *
+ * @public
+ */
+declare function definePlugin<P extends Plugin>(p: P): P;
+type Plugin = Plugin$1;
+/** SE36 — `Plugin.create` replaces `definePlugin` (ADR 0015). Const-companion (the `Plugin` type alias blocks a class of the same name); `create` is the generic `definePlugin`. @public */
+declare const Plugin: {
+    create: typeof definePlugin;
+};
+
+/**
+ * Options for {@link defineProvider}.
+ *
+ * @public
+ */
+interface DefineProviderOptions {
+    /** Plugin version surfaced in diagnostics. Default `"1.0.0"`. */
+    version?: string;
+}
+/** SE36 — uniform namespace API. `Provider.create` replaces `defineProvider` (ADR 0015). @public */
+declare class Provider {
+    private constructor();
+    static create(profile: ProviderProfile, opts?: DefineProviderOptions): Plugin;
+    /**
+     * Every first-party builtin provider (anthropic, openai, openrouter, gemini, ollama, the ChatGPT/Codex
+     * `openai-chatgpt`, …) as model-provider plugins, ready to hand to `Agent.create({ plugins })` or any
+     * runtime that consumes model-provider plugins (e.g. the `theokit` agent server / `@theokit/agents`, whose
+     * own model resolution does NOT share this registry). Enables a consumer to route to ANY SDK builtin —
+     * including one added later in a single SDK file — with ZERO provider-specific code: just
+     * `.plugins(Provider.builtins())` once, then pick a `provider/model` id. @public
+     */
+    static builtins(): Plugin[];
+    /**
+     * The builtin serving `modelId`, or `undefined` when none does.
+     *
+     * The grammar of a model id — `provider/model` — now has **one** owner. M94: the consumer
+     * redid it by hand with `modelId.slice(0, modelId.indexOf('/'))`, which on an id **without a slash** returns the
+     * id minus its last character (`claude-opus-5` -> `claude-opus-`): it matches no provider and the
+     * caller fell through to the default, without distinguishing that from a hit. A non-routable model was
+     * indistinguishable from the happy path.
+     *
+     * Returns `undefined` instead of throwing: the caller decides whether absence is an error, and only they
+     * know whether the model came from an explicit `--model` (an error) or from the default (normal).
+     *
+     * @public
+     */
+    static forModel(modelId: string): Plugin | undefined;
+}
+
+/**
+ * SE23 — `defineSkillReadTool`: an OPT-IN factory that gives the MODEL on-demand
+ * access to a skill's full body + references via a `skill_read` tool.
+ *
+ * TheoKit discloses skills eagerly through the `<skills>` system-prompt block
+ * (name + description only). This factory is the LAZY read path: the consumer
+ * explicitly adds the returned {@link CustomTool} to `tools`, and when the model
+ * calls it with a skill name, it gets that skill's `instructions` (+ SE21
+ * `references`). The SDK NEVER auto-injects it — bring-your-own-tools stays
+ * intact (sibling of `defineSubAgent` / `workflowAsTool`). See ADR 0007.
+ *
+ *   import { Agent, createSkill, defineSkillReadTool } from "@theokit/sdk";
+ *
+ *   const skills = [createSkill({ name: "release", description: "…", instructions: "…" })];
+ *   const agent = await Agent.create({
+ *     model: { id: "openai/gpt-4o-mini" },
+ *     skills: { inline: skills },
+ *     tools: [defineSkillReadTool(skills)],
+ *   });
+ *
+ * @public
+ */
+
+/** SE36 — `SkillReadTool.create` replaces `defineSkillReadTool` (ADR 0015). @public  *
+ * `SkillReadTool.create` returns a **`CustomTool`** — a skill-reading tool, not a
+ * `SkillReadTool` instance.
+ */
+declare class SkillReadTool {
+    private constructor();
+    static create(skills: ReadonlyArray<InlineSkill>): CustomTool;
+}
+
+/**
+ * Options for {@link sanitizeToolInput}. Trim is the only default-on rung — coercion and JSON
+ * repair change a value's representation, so they are opt-in (the SDK's "values are strings; Zod
+ * coerces" boundary; see `define-tool.ts` doc-comment).
+ *
+ * @public
+ */
+interface SanitizeOptions {
+    /** Trim leading/trailing whitespace from string values. Default `true`. */
+    trim?: boolean;
+    /** Coerce string values to typed values (`"5"`→`5`, `"true"`→`true`, `"null"`→`null`, JSON). Default `false`. */
+    coerce?: boolean;
+    /** Repair-then-parse malformed JSON-looking string values (via `jsonrepair`). Default `false`. */
+    repairJson?: boolean;
+    /**
+     * Optional Zod schema. When it is a `z.object(...)`, coercion is schema-aware: each TOP-LEVEL
+     * field is coerced only toward a candidate its field-schema accepts (so a `z.string()` field
+     * keeps `"5"` as a string). Non-object schemas (union/record) fall back to heuristic coercion.
+     * Note: with `deep: true`, nested fields always use heuristic coercion (the schema is not
+     * descended into).
+     */
+    schema?: ZodType;
+    /**
+     * Recurse into nested plain objects. Default `false` (shallow).
+     *
+     * ARRAYS ARE NOT GATED BY THIS. Their string elements are sanitized by whichever rungs are on —
+     * `trim` is on by default — because a value does not stop being a string by sitting in a list, and
+     * a caller who saw `{ tag: "  a  " }` trimmed has no reason to expect `{ tags: ["  a  "] }` left
+     * alone. What `deep` gates is descending into OBJECTS, wherever they are: at the top level, nested,
+     * or inside an array.
+     */
+    deep?: boolean;
+    /**
+     * Max recursion depth. Default `8`.
+     *
+     * Counts every hop, array or object, so a deeply nested structure cannot recurse without bound even
+     * when `deep` is off — array descent is not gated by `deep`, and this is what bounds it.
+     */
+    maxDepth?: number;
+}
+
+/**
+ * SE16 — the handler's return type. With no `outputSchema` the tool returns a
+ * plain `string` (pre-SE16 shape). With an `outputSchema` the handler returns the
+ * STRUCTURED output inferred from it (validated + serialized to the tool result).
+ * The `[O]` tuple wrap prevents distribution so `never` maps cleanly to `string`.
+ */
+type ToolHandlerReturn<O extends ZodType> = [O] extends [never] ? string : z.infer<O>;
+/**
+ * Spec accepted by {@link Tool.create}. `inputSchema` is a Zod schema; the `handler` argument type
+ * is inferred via `z.infer<T>` — no `as` casts.
+ *
+ * The two optional output fields do different jobs and compose. `outputSchema` changes what the
+ * handler must RETURN (a structured value instead of a string) and validates it; `toModelOutput`
+ * changes only what the MODEL sees in the tool result, while observability still receives the full
+ * handler output. Set neither and the handler returns a plain string that goes to both.
+ *
+ * `zod` is referenced as a type only, so a consumer that never calls `Tool.create` does not need it
+ * installed.
+ *
+ * @public
+ */
+interface DefineToolSpec<T extends ZodType, O extends ZodType = never> {
+    /** Tool name surfaced to the LLM. Same constraints as {@link CustomTool.name}. */
+    name: string;
+    /** Description surfaced to the LLM. */
+    description: string;
+    /** Zod schema describing the input. Must be `z.object(...)` at the root for the LLM tool contract. */
+    inputSchema: T;
+    /**
+     * SE16 — optional Zod schema describing the OUTPUT. When set, the handler
+     * returns the structured value inferred from it; the value is validated against
+     * this schema and serialized to the tool result (a string stays as-is, an object
+     * is JSON-stringified). A validation failure raises `ZodError`, converted to a
+     * `tool_result(isError)`. Absent ⇒ the handler returns a plain string (unchanged).
+     */
+    outputSchema?: O;
+    /**
+     * Handler invoked with the parsed input. Type is inferred via `z.infer<T>`; the
+     * return type is `z.infer<O>` when `outputSchema` is set, else `string`.
+     * #65 — an optional 2nd `ToolContext` argument carries the run's `AbortSignal`,
+     * so a cooperative handler can stop early when the run is cancelled. Existing
+     * single-argument handlers are unaffected.
+     */
+    handler: (input: z.infer<T>, ctx?: {
+        signal?: AbortSignal;
+        context?: unknown;
+        threadId?: string;
+    }) => ToolHandlerReturn<O> | Promise<ToolHandlerReturn<O>>;
+    /**
+     * SE17 — map the handler's (validated) output to the compact / multimodal
+     * representation the MODEL sees in the tool_result. The handler keeps returning
+     * the FULL result (validated by `outputSchema`); `toModelOutput` shapes only what
+     * reaches the model, so app-facing detail is not forced into model context.
+     * Returns a string OR SE7 `ToolResultContentBlock[]` (text + image). Absent ⇒
+     * the tool_result is the serialized handler output (SE16 / pre-SE17 behavior).
+     * The split is REAL: the model's `tool_result` carries this compact value, while
+     * observability (`onToolEnd.result`) receives the FULL raw handler output
+     * (serialized) — so the app keeps the complete result. ONE handler execution
+     * feeds both channels.
+     */
+    toModelOutput?: (output: ToolHandlerReturn<O>) => string | ToolResultContentBlock[];
+    /**
+     * Sanitize the raw model-emitted args BEFORE schema validation (`@theokit/sdk/sanitize`).
+     * `true` trims whitespace; an object opts into coercion / JSON-repair. Coercion is schema-aware
+     * against this tool's `inputSchema`. Absent ⇒ args reach validation untouched. Sanitize is
+     * hygiene, not a validity bypass — a genuinely invalid arg still raises `ZodError`.
+     */
+    sanitize?: boolean | SanitizeOptions;
+}
+/**
+ * SE36 — the uniform `X.create()` namespace API. `Tool.create(spec)` is the sole public
+ * constructor for a {@link CustomTool}; it wraps the internal builder so behavior is identical
+ * (ADR 0015). A `private constructor` makes `Tool` a namespace, not an instantiable value —
+ * `new Tool()` is a compile error. Mirrors `Agent.create` / `Cron.create`.
+ *
+ * @public
+ */
+declare class Tool {
+    private constructor();
+    static create<T extends ZodType, O extends ZodType = never>(spec: DefineToolSpec<T, O>): CustomTool;
+}
+
+/**
+ * Audit whether every configuration key can be set from the environment, or says why not.
+ *
+ * A key settable only by editing a file cannot be set in CI, in a container, or for a single
+ * invocation. That is usually an oversight rather than a decision, and it is invisible — nothing
+ * fails, the key simply has no environment path, and nobody notices until someone needs one.
+ *
+ * The opposite failure rots more quietly. An opt-out written for a key that has since gained an
+ * environment path, or for a key that no longer exists, still reads as a considered decision while
+ * exempting nothing. Both questions are answered by one call so a consumer cannot check the gap and
+ * forget the rot: they fail for opposite reasons, and a suite that asks only one looks complete.
+ *
+ * ## Why the framework owns the rule and not the keys
+ *
+ * A framework cannot enumerate a consumer's configuration keys, and should not try. Which keys exist
+ * is that product's vocabulary — the same reason the security floor takes its permissiveness order
+ * as data and the trust posture takes its capability list. So the consumer ranges over its own keys
+ * with this, rather than registering them here.
+ *
+ * That is a narrower claim than "reachability is checked in the framework", and it is the honest
+ * one: the failure still surfaces in the consumer's own suite. What the consumer no longer writes is
+ * the detector, which is where the subtlety lives — the stale-opt-out half is the part everyone
+ * forgets.
+ *
+ * @public
+ */
+/** A key deliberately left off the environment, with the reason and what would reverse it. @public */
+interface EnvOptOut {
+    readonly key: string;
+    /** Why an environment variable is the wrong shape for this key. */
+    readonly reason: string;
+    /** What would make this opt-out obsolete. An opt-out with no exit is a permanent excuse. */
+    readonly exitCriterion: string;
+}
+/**
+ * The three lists the audit compares: every key the product declares, the subset an environment
+ * variable can set, and the documented exemptions.
+ *
+ * All three are matched by exact string equality, and `reachable` and `optOuts` are read as subsets
+ * of `keys` — an entry in either that is not in `keys` is what makes an opt-out stale, and an entry
+ * in `reachable` that is not in `keys` is simply ignored.
+ *
+ * @public
+ */
+interface EnvReachabilityInput {
+    /** Every configuration key the product declares. */
+    readonly keys: readonly string[];
+    /** The subset that an environment variable can set. */
+    readonly reachable: readonly string[];
+    /** Documented exemptions for keys that deliberately have no environment path. */
+    readonly optOuts: readonly EnvOptOut[];
+}
+/**
+ * The two failures, reported separately because they have opposite fixes.
+ *
+ * A key in `unreachable` needs either an environment path or a documented opt-out. A key in
+ * `staleOptOuts` needs its opt-out DELETED — it exempts nothing, either because the key gained an
+ * environment path or because the key no longer exists. Both lists empty is the passing state.
+ *
+ * @public
+ */
+interface EnvReachabilityAudit {
+    /** Keys with neither an environment path nor a documented opt-out. */
+    readonly unreachable: readonly string[];
+    /** Opt-outs that exempt nothing: the key gained an environment path, or no longer exists. */
+    readonly staleOptOuts: readonly string[];
+}
+/**
+ * Answer both halves of the reachability question in one call.
+ *
+ * A key counts as covered when it is in `reachable` OR carries an opt-out, so an opt-out silences
+ * the gap it was written for and nothing else. Assert on both returned lists: a suite that checks
+ * only `unreachable` still passes while the opt-outs rot, which is the half everyone forgets.
+ *
+ * This performs no I/O and reads no environment. The caller supplies its own key vocabulary,
+ * because a framework cannot enumerate a consumer's configuration keys.
+ *
+ * @returns both axes, in the order the caller declared them — a stable order so a failure message
+ *   does not change between runs for reasons unrelated to the code.
+ * @public
+ */
+declare function auditEnvReachability(input: EnvReachabilityInput): EnvReachabilityAudit;
+
+/**
+ * `EventBus` — typed EventEmitter wrapper.
+ *
+ * Provides type-safe publish/subscribe with automatic unsubscribe cleanup.
+ * Each handler is try-caught (EC-2) so one failing handler cannot break others.
+ */
+type EventHandler<T> = (payload: T) => void;
+/**
+ * A typed publish/subscribe bus, parameterised by a map of event name to payload type.
+ *
+ * `publish` is SYNCHRONOUS: handlers run in subscription order before it returns, so a slow handler
+ * blocks the publisher. Each handler is invoked inside its own try/catch, so one that throws cannot
+ * stop the others — the error is written to the diagnostics channel and counted on
+ * `handlerErrorCount`. Assert on that counter in tests; a subscriber failing on every event is
+ * otherwise invisible.
+ *
+ * `subscribe` returns the unsubscribe function, which is the only way to detach a handler — there
+ * is no `off` taking the handler back. Handlers are held in a `Set` per event, so subscribing the
+ * same function reference twice registers it once.
+ *
+ * Payload objects are passed by reference to every handler; nothing here copies them, so a handler
+ * that mutates a payload mutates it for the handlers after it.
+ */
+declare class EventBus<Events extends Record<string, unknown>> {
+    #private;
+    private handlers;
+    /** M3 #64 — number of handler invocations that threw (and were logged). */
+    get handlerErrorCount(): number;
+    /**
+     * Subscribe to an event. Returns an unsubscribe function.
+     */
+    subscribe<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>): () => void;
+    /**
+     * Publish an event to all subscribers. EC-2: try-catch per handler.
+     */
+    publish<K extends keyof Events>(event: K, payload: Events[K]): void;
+    /**
+     * Subscribe to an event for a single firing. Returns an unsubscribe function.
+     */
+    once<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>): () => void;
+}
+
+/** Inputs to the judge — pure data. */
+interface JudgeContext {
+    goal: string;
+    lastResponse: string;
+    subgoals?: string[];
+}
+/** Caller-supplied tuning knobs for the judge call. */
+interface JudgeOptions {
+    /**
+     * Judge model identifier. When absent, it DERIVES from {@link agentModel} — and only falls back to the literal
+     * `"openai/gpt-4o-mini"` when neither is provided.
+     *
+     * M80 — the fixed default was provider-blind: it only resolves on OpenRouter. With an Anthropic key it gives
+     * 404, with an OAuth bearer it gives 401, and in both the goal burned 3 whole turns before failing with
+     * a misleading reason. The agent-builder already worked around this by deriving on its own; the knowledge
+     * belongs here.
+     */
+    judgeModel?: string;
+    /**
+     * M80 — the DRIVEN agent's model. It is the basis of the derivation: a judge running on the same model as the
+     * chat works wherever chat works.
+     */
+    agentModel?: string;
+    /** Override env. Default `process.env.OPENROUTER_API_KEY` (EC-A). */
+    apiKey?: string;
+}
+/**
+ * M80 — the judge's credential or model does not work: 401/404.
+ *
+ * Fails FAST by design. `rules/error-handling.md` § 2 separates recoverable from unrecoverable, and a
+ * nonexistent model does not start existing on retry — folding that into `{parseFailed: true}` made the loop
+ * try three times and report "failed" on a consecutive-failure limit, hiding that the cause was the
+ * credential. A slow, opaque failure traded for a fast, clear one.
+ *
+ * PARSE failures and network errors stay folded: they are recoverable, and the loop already decides on
+ * in a row.
+ */
+declare class JudgeCredentialError extends TheokitAgentError {
+    readonly httpStatus: number;
+    readonly judgeModel: string;
+    readonly name = "JudgeCredentialError";
+    constructor(httpStatus: number, judgeModel: string, cause: unknown);
+}
+
+/**
+ * Goal-driven Ralph loop (T3.2, ADRs D115-D121).
+ *
+ * `runUntilImpl` is an `AsyncGenerator<GoalEvent, GoalResult, void>`:
+ * yields events as the loop progresses, returns the final result when
+ * the goal completes, fails, or is paused. The auxiliary judge model is
+ * injected via `deps.judge` so the generator stays free of the `Agent`
+ * façade import.
+ *
+ * EC-C fix: pre-aborted signals emit only `[paused]`, not `[active, paused]`.
+ * EC-D: `maxTurns: 0` is supported (vacuous yield active → failed).
+ *
+ * @internal
+ */
+
+/** DI contract: the judge is the only external touchpoint. */
+interface RunUntilDeps {
+    judge: (ctx: JudgeContext, opts?: JudgeOptions) => Promise<JudgeResult>;
+}
+
+/**
+ * The goal-loop's continuation marker — in a LEAF module, on purpose.
+ *
+ * It lived in `goal-loop.ts` and was imported by `run-until.ts`, which `goal-loop` in turn
+ * imports back. The cycle was broken at runtime (the return edge is `import type` + a dynamic
+ * `await import()`), but the cycle detector counts the dynamic edge — and counting a dynamic import as a cycle
+ * makes the gate impossible to satisfy without abandoning the canonical cycle-breaking technique.
+ *
+ * A constant shared by two modules that know each other is the textbook case for extraction into a
+ * leaf: neither needs to import the other to know it. The cycle disappears under ANY detector, with no
+ * tool policy and without changing a line of behavior.
+ */
+declare const GOAL_CONTINUATION_MARKER = "[[theokit:goal-continuation]]";
+
+/**
+ * M56 (agent-builder goal transparency) — PUBLIC goal-loop driver for CUSTOM agent surfaces.
+ *
+ * `LocalAgent.runUntil` binds the goal loop to a registered local agent. Surfaces that route turns
+ * through their OWN transport (e.g. a TUI store facade, so every goal turn renders in the same
+ * timeline as a manual turn) need the SAME loop over a minimal `send → wait` shape. This export
+ * gives them exactly that: the canonical `runUntilImpl` (judge + continuation + token budget +
+ * Codex states) with the default judge wired from the DI registry.
+ *
+ * @public
+ */
+
+/** The minimal surface the goal loop drives — anything that can send a prompt and wait for it. */
+interface GoalLoopAgent {
+    send(prompt: string): Promise<{
+        wait(): Promise<{
+            result?: string;
+            usage?: {
+                totalTokens?: number;
+            };
+        }>;
+    }>;
+}
+/**
+ * Run the goal-driven loop (`send → judge → continuation`) over ANY `send → wait` surface.
+ * Identical semantics to `Agent.runUntil` (ADRs D115-D121 + M55 token budget / states).
+ * `depsOverride` is a test seam for injecting a fake judge.
+ */
+declare function runGoalLoop(agent: GoalLoopAgent, goal: string, options?: GoalOptions, depsOverride?: RunUntilDeps): AsyncGenerator<GoalEvent, GoalResult, void>;
+
+/**
+ * Reference `BudgetTracker` impl — pure token + iteration counter
+ * (SDK 2.0 Phase 2 / T2.1 — ADR D1 reference implementation).
+ *
+ * Counts tokens per type (input/output) + iteration count. Enforces
+ * optional `maxTokens` / `maxIterations` ceilings via `check()`.
+ *
+ * Does NOT compute USD cost — leaves that to richer impls in
+ * `@theokit/sdk-budget` (post-Phase-2). This file is intentionally
+ * minimal so consumers can:
+ *   - use it as-is for simple guard-rails;
+ *   - read it as a worked example before authoring a custom tracker;
+ *   - rely on it as a fallback before sdk-budget ships.
+ *
+ * @public — surface-level reference impl.
+ */
+
+/** Options for `createCounterBudgetTracker`. */
+interface CounterBudgetTrackerOptions {
+    /** Hard ceiling on total tokens (input + output). When reached, `check()` returns `allowed: false`. */
+    readonly maxTokens?: number;
+    /** Hard ceiling on iterations counted by `nextIteration()`. */
+    readonly maxIterations?: number;
+}
+/**
+ * Build a fresh tracker. The returned object is independent — call
+ * `createCounterBudgetTracker()` per Agent instance.
+ *
+ * The tracker exposes the `BudgetTracker` contract PLUS a `nextIteration()`
+ * helper for impls that want explicit iteration counting (the agent loop
+ * calls it once per turn). Without `nextIteration()` calls, the iteration
+ * cap is never reached.
+ */
+declare function createCounterBudgetTracker(options?: CounterBudgetTrackerOptions): BudgetTracker & {
+    nextIteration(): void;
+};
+
+/**
+ * The library's single diagnostics channel — silent by default (#147).
+ *
+ * ## The problem
+ *
+ * The SDK wrote diagnostics straight to `process.stderr` from hot paths — 92 sites across 51
+ * files under `internal/`. In a TUI host (Ink, alternate screen), those writes interleave with the
+ * render and **corrupt the frame**. And the host had no way to intercept them: there was no
+ * injectable logger. One consumer went as far as installing `proper-lockfile` just to silence ONE
+ * of them.
+ *
+ * A library cannot assume `stdout`/`stderr` are free sinks. The application owns the terminal, not
+ * the dependency.
+ *
+ * ## The contract
+ *
+ * - **`setDiagnosticsSink(fn)`** hands the messages to the application, which decides where to put
+ *   them (a status line, a file, a panel). It is what was missing for a TUI to coexist with the SDK.
+ * - **With no sink, nothing is emitted.** A library does not own the host's terminal.
+ *
+ * ## Silent by default, and how 36 suites survived the flip
+ *
+ * The default WAS `stderr`, and 36 test files spy on `process.stderr.write` to assert a given
+ * warning is emitted. That contract is real and had to survive; migrating all 36 by hand, across
+ * four different spy styles, is how you weaken 36 suites in one commit.
+ *
+ * So the flip happened at the default, and `vitest.setup.ts` installs a sink that FORWARDS to
+ * `stderr` for the duration of every test. Those assertions still test what they always tested —
+ * "this condition emits a diagnostic" — through the channel a host would use, while production
+ * emits nothing unless asked.
+ *
+ * The cost is stated rather than hidden: no test observes the production default by accident, so
+ * `tests/diagnostics-public-entry.test.ts` pins it explicitly by clearing the sink first.
+ *
+ * ## Coverage is the whole guarantee
+ *
+ * The first sweep migrated the 92 sites under `internal/` and left `src/`'s own modules —
+ * `event-bus.ts`, `batch.ts`, `compaction.ts`, `internal/workflow/step-branch.ts`. A host could
+ * therefore install a sink and still have its frame corrupted by a batch run, which is the reported
+ * defect with a smaller blast radius. Those are routed here too, and
+ * `tests/lint/no-direct-terminal-write.test.ts` is what keeps the next hot path from
+ * reintroducing one. "Mostly interceptable" is not interceptable.
+ *
+ * The remaining direct writers are allowlisted there with a reason, and every one of them is a seam
+ * whose destination the CALLER already chooses (`opts.warn`, `opts.logger`, the Workflow logger).
+ *
+ * ## What this is NOT
+ *
+ * It is not a logger with levels, formatting or multiple destinations. It is the minimum that
+ * resolves the reported blocker; a full logger here would be inventing a requirement nobody asked
+ * for.
+ */
+/** Receives each diagnostic message already formatted, with the trailing `\n`. */
+type DiagnosticsSink = (message: string) => void;
+/**
+ * Installs (or removes, by passing `undefined`) the diagnostics destination.
+ *
+ * When a sink is present it is the ONLY destination — `stderr` gets no copy. Duplicating
+ * destinations would hand the problem back to the TUI that installed the sink precisely to get the
+ * messages out of the terminal.
+ */
+declare function setDiagnosticsSink(next: DiagnosticsSink | undefined): void;
+
+/**
+ * The fail-safe emitter for the `RunEvent` stream — runtime, deliberately NOT in `types/`.
+ *
+ * Eleven modules across `agent-loop/`, `runtime/`, `task/` and `local-agent/` call it; the type it
+ * carries stays in `types/run-events.ts`, which is what `types/` is for. Sibling of
+ * `internal/diagnostics.ts`, which swallows sink failures on the same principle and for the same
+ * reason: observability degrades what you can SEE, never what the agent DOES.
+ *
+ * @internal
+ */
+/**
+ * SE2 — emit a {@link RunEvent} to an optional sink, swallowing any sink error so
+ * observability can never break the run (fail-safe, mirrors the EventBus EC-2
+ * contract). No-op when the sink is absent.
+ */
+declare function emitRunEvent(sink: RunEventSink$1 | undefined, event: RunEvent): void;
+
+/**
+ * Run `fn` after every earlier `withCwdMutex` call for the same `key` has settled, and return
+ * what `fn` returns.
+ *
+ * Calls with the same key run strictly in the order they were made — FIFO, never concurrent.
+ * Calls with different keys never wait on each other. The key is an opaque string: two callers
+ * serialize against each other exactly when they pass equal keys, so a shared key IS the
+ * contract, and a mismatched one silently buys no protection at all.
+ *
+ * A rejection does not poison the queue. The next waiter runs whether the previous `fn` fulfilled
+ * or rejected, and the rejection is delivered only to the caller whose `fn` threw. This function
+ * neither retries nor swallows: the returned promise rejects with whatever `fn` rejected with.
+ *
+ * There is no timeout and no cancellation. An `fn` that never settles blocks that key for the
+ * lifetime of the process.
+ *
+ * **Scope — this is an in-process lock only.** State is a module-scoped Map, so it serializes
+ * callers that share one module instance and nothing else. Two processes, two worker threads, or
+ * two copies of the SDK resolved into the same tree do not see each other's queue. When the
+ * resource is a file that other processes can also write, use `withFileLock` from
+ * `./file-lock.ts` instead — it takes an OS-level lock and layers this mutex underneath, so it
+ * gives both guarantees. Reach for `withCwdMutex` directly when the shared state is in memory, or
+ * when the file is one only this process touches.
+ *
+ * Extracted packages (`@theokit/sdk-budget`, `@theokit/sdk-memory`) import this from
+ * `@theokit/sdk` rather than reimplementing it, precisely so the Map is the same one: a per-package
+ * copy would give each package its own queue and let their writes race.
+ *
+ * The Map is module-scoped, so nothing survives a process restart or a fresh module instance, and
+ * its entries are never removed — pass keys from a bounded set rather than from arbitrary input.
+ * Signature and semantics will not change before sdk-core v3.0.
+ *
+ * @public
+ */
+declare function withCwdMutex<T>(key: string, fn: () => Promise<T>): Promise<T>;
+
+/**
+ * Reference `MemoryProvider` impl — no-op fallback (SDK 2.0 Phase 1 /
+ * T1.2 reference implementation, mirrors `createCounterBudgetTracker`).
+ *
+ * Every method is a degenerate identity:
+ *   - `init()` returns a handle wrapping a no-op `MemoryAdapter`.
+ *   - `buildTools()` returns `[]` (no memory tools surfaced to the LLM).
+ *   - `runActivePass()` returns `{ facts: [] }` (no recall fires).
+ *   - `dispose()` is a no-op.
+ *
+ * Why ship this:
+ *   - Default safety net before `@theokit/sdk-memory` is installed.
+ *   - Worked reference for authors of custom providers.
+ *   - Enables `Agent.create({ memoryProvider: createNoopMemoryProvider() })`
+ *     unit tests without pulling memory infrastructure.
+ *
+ * NOT a substitute for the existing `Memory` class — the legacy class
+ * stays authoritative until the subsystem fully ports to providers
+ * (Phase 1 / T1.6).
+ *
+ * @public — surface-level reference impl.
+ */
+
+/** SE36 — `NoopMemoryProvider.create` replaces `createNoopMemoryProvider` (ADR 0015). @public */
+declare class NoopMemoryProvider {
+    private constructor();
+    static create(): MemoryProvider;
+}
+
+/**
+ * Task-id grammar (D368) — runtime, deliberately NOT in `types/`.
+ *
+ * It lived in `types/task.ts`, which `types/index.ts` re-exports with `export type *`. That star
+ * cannot carry a value, so the only reason `isValidTaskId` ever reached a consumer is that the DTS
+ * rollup hoists the declaration while the runtime bundle emits nothing — exactly the shape of #279,
+ * where the import typechecked and was `undefined` at the call site. `src/index.ts` re-exports both
+ * names from here, so the public API is unchanged.
+ *
+ * @internal
+ */
+/**
+ * Validates a task ID against the public grammar + reserved prefixes.
+ * Throws `InvalidTaskIdError` from `../errors.js` on rejection.
+ *
+ * Adapter callers (workflow/batch/cron) MUST set `allowReserved: true`
+ * to register their own IDs; user-facing surfaces (`Task.submit`,
+ * `agent.send({ task: { id } })`) leave it false.
+ */
+declare function isValidTaskId(id: string, allowReserved: boolean): boolean;
+/** Re-exported for adapter implementations + tests. */
+declare const TASK_RESERVED_PREFIXES: readonly string[];
+
+/**
+ * The subset of the OpenTelemetry `Span` API this SDK calls.
+ *
+ * Structural, not nominal: a real `@opentelemetry/api` span satisfies it, and so does a test double
+ * or a no-op. That is why it is exported — `@theokit/sdk-memory` previously kept a hand-written
+ * mirror of this shape, and the two had already drifted (the mirror rejected `undefined` attribute
+ * values this one accepts, and declared `end()` without its `endTime` parameter). Import this
+ * instead of re-declaring it.
+ *
+ * Erased at build time, so importing it adds nothing to a bundle and does not require
+ * `@opentelemetry/api` to be installed.
+ *
+ * @public
+ */
+interface OTelSpan {
+    setAttribute(key: string, value: string | number | boolean): void;
+    setAttributes(attrs: Record<string, string | number | boolean | undefined>): void;
+    addEvent(name: string, attrs?: Record<string, string | number | boolean>): void;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): void;
+    recordException(err: unknown): void;
+    end(endTime?: number): void;
+    spanContext(): {
+        traceId: string;
+        spanId: string;
+    };
+    isRecording(): boolean;
+}
+/**
+ * Telemetry handle returned by {@link createTelemetry}. Callers use this to
+ * start spans, add events, etc. When telemetry is disabled OR OTel is not
+ * installed, every method is a safe no-op.
+ *
+ */
+interface TelemetryHandle {
+    readonly enabled: boolean;
+    readonly includeContent: boolean;
+    /** Start a span. Returns a no-op span if telemetry is disabled. */
+    startSpan(name: string, attrs?: Record<string, string | number | boolean>): OTelSpan;
+    /** Start a child span nested under `parent` (M3 #64). `undefined` parent →
+     *  a root span (parentless callers, or telemetry with no run span). */
+    startChildSpan(parent: OTelSpan | undefined, name: string, attrs?: Record<string, string | number | boolean>): OTelSpan;
+    /**
+     * Record a histogram observation. T0.1 ships
+     * `theokit_memory_recall_duration_ms`; downstream tasks add more.
+     * No-op when telemetry is disabled or when `@opentelemetry/api`'s metrics
+     * namespace is unavailable. ADR D34 — exporter errors are swallowed by `safe()`.
+     */
+    recordHistogram(name: string, valueMs: number, attrs?: Record<string, string | number | boolean>): void;
+    /** End all open spans on this handle (best-effort, used by Agent.dispose). */
+    endAll(): void;
+}
+
+/**
+ * `JobQueue` — background job queue with status tracking, cancellation, and an
+ * optional concurrency bound.
+ *
+ * EC-1: all enqueued functions are wrapped in Promise.resolve().then() so
+ * synchronous throws become rejections.
+ *
+ * #58: each job runs under an `AbortController` whose signal is passed to the
+ * job fn, so `cancel()` actually interrupts a running job (not just a status
+ * flip); an optional `maxConcurrency` bounds how many jobs run at once.
+ */
+type JobStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
+interface Job<T> {
+    id: string;
+    status: JobStatus;
+    result?: T;
+    error?: string;
+}
+/** #58 — construction options. */
+interface JobQueueOptions {
+    /**
+     * Max jobs running concurrently. Omit for unbounded (previous behavior).
+     * Values < 1 are clamped to 1 (an invalid bound must not deadlock).
+     */
+    maxConcurrency?: number;
+}
+/**
+ * An in-process queue of background jobs with status tracking, cancellation, and an optional
+ * concurrency bound.
+ *
+ * `enqueue` returns a job id immediately and never throws for the job's own failure: a synchronous
+ * throw inside the function becomes a rejection, and a rejection becomes `status: "failed"` with
+ * the message on `job.error`. Poll `getJob(id)` or `list()` for outcomes — there is no completion
+ * event and no promise to await.
+ *
+ * Cancellation is COOPERATIVE. `cancel` aborts the `AbortSignal` handed to the job function and
+ * flips the status, but a function that ignores the signal keeps running to completion; its result
+ * is then discarded, because a cancelled job never leaves the cancelled state. The concurrency slot
+ * of a running job is freed at cancel time rather than when it eventually settles, so a job that
+ * never settles cannot deadlock a bounded queue.
+ *
+ * State lives entirely in memory and grows without bound — nothing evicts finished jobs. This is a
+ * queue for one process, not a durable one.
+ */
+declare class JobQueue {
+    #private;
+    private jobs;
+    private controllers;
+    private readonly maxConcurrency;
+    private running;
+    private readonly waiting;
+    constructor(options?: JobQueueOptions);
+    /**
+     * Enqueue a background function. Returns the job ID immediately. The function
+     * receives an `AbortSignal` that fires when the job is cancelled (#58) — a
+     * cooperative job should observe it to stop early. Existing `() => Promise<T>`
+     * callers are unaffected (the signal argument is simply ignored).
+     */
+    enqueue<T>(fn: (signal: AbortSignal) => Promise<T>): string;
+    getJob(id: string): Job<unknown> | undefined;
+    list(): Job<unknown>[];
+    /**
+     * Cancel a pending or running job. Returns true if cancelled. #58 — aborts the
+     * job's `AbortSignal` so a cooperative running job is actually interrupted.
+     */
+    cancel(id: string): boolean;
+}
+
+/**
+ * Fold configuration layers in a declared order — later layers win, named keys accumulate.
+ *
+ * Every product that reads configuration from more than one place rebuilds these two rules, and the
+ * second one is not a nicety. With plain last-wins, a project file DISPLACES the user's entries for
+ * a list-valued key rather than adding to them — and for a key like `hooks`, which carries arbitrary
+ * command execution, that is the difference between a repository adding a hook and a repository
+ * removing yours.
+ *
+ * The layer NAMES are the caller's, supplied as data. One product's chain is
+ * defaults/user/project/profile/env/cli; `profile` is that product's idea and does not belong here.
+ * That is the same test the security floor passed: a vocabulary expressible as data generalises, an
+ * open-ended interface shaped by one product does not.
+ *
+ * @public
+ */
+
+/** Raised when a declared layer chain is not strictly ascending. @public */
+declare class LayerOrderError extends TheokitAgentError {
+    readonly name = "LayerOrderError";
+}
+/**
+ * One named layer in a precedence chain.
+ *
+ * `precedence` is optional and the two usages do not mix well: omit it everywhere to say "this
+ * array is already in order", or supply it everywhere you want `verifyLayerOrdering` to check.
+ * Entries without it are SKIPPED by that check rather than treated as zero, so a chain where only
+ * some entries declare a number is verified only between those.
+ *
+ * @public
+ */
+interface DeclaredLayer {
+    readonly layer: string;
+    /** Higher wins. Optional — omit it to mean "this array is already the order". */
+    readonly precedence?: number;
+}
+/**
+ * A declared layer together with the values it supplies.
+ *
+ * `foldLayers` consumes these in array order, so a later entry wins for the keys it mentions. A key
+ * a layer does not mention — or mentions with `undefined` — leaves the earlier value standing;
+ * there is no way for a layer to erase a key another layer set.
+ *
+ * @public
+ */
+interface LayerValues extends DeclaredLayer {
+    readonly values: Readonly<Record<string, unknown>>;
+}
+/**
+ * Assert that each layer strictly outranks the one before it.
+ *
+ * Entries without a `precedence` are skipped rather than treated as zero: omitting it means the
+ * caller is expressing order by position, and inventing a number for them would manufacture a
+ * conflict out of a legitimate usage.
+ *
+ * @throws LayerOrderError naming both layers and both precedences — a refusal that only says "out
+ *   of order" sends the reader to compare the whole list by hand.
+ * @public
+ */
+declare function verifyLayerOrdering(layers: readonly DeclaredLayer[]): void;
+/**
+ * Combine `entries` into one record.
+ *
+ * Later entries win. A value of `undefined` never overwrites — a layer that does not mention a key
+ * must not erase it, because "said nothing" is overwhelmingly more common than "said nothing on
+ * purpose".
+ *
+ * Keys in `accumulatingKeys` whose value is an array are CONCATENATED across layers instead of
+ * replaced. A non-array value for such a key replaces, deliberately: a malformed config must not
+ * corrupt the accumulator into a mixed list, and leaving the raw value visible lets the consumer's
+ * own validation reject it with its own message.
+ *
+ * The accumulator is per-call and the inputs are never mutated, so folding twice yields the same
+ * answer — which a consumer that folds once to display and once to apply depends on.
+ *
+ * @public
+ */
+declare function foldLayers(entries: readonly LayerValues[], accumulatingKeys?: readonly string[]): Record<string, unknown>;
+
+/**
+ * Public handle to an open memory index. Mirrors the internal `MemoryIndex`
+ * contract structurally; defined here (NOT re-exported from internal/) so
+ * the public DTS surface does not pull the internal/runtime cycle that
+ * trips rollup-plugin-dts.
+ *
+ * @public
+ */
+interface MemoryIndexHandle {
+    sync(): Promise<{
+        filesScanned: number;
+        filesUpdated: number;
+        chunksWritten: number;
+        chunksEmbedded: number;
+        /**
+         * Whether this backend actually walked a corpus. `false` on the Lance backend, which is a
+         * vector store fed by explicit writes and has no corpus — its zero counts mean "not applicable",
+         * not "nothing to reindex". Read this before treating the counts as a measurement.
+         */
+        supported: boolean;
+    }>;
+    search(query: string, options?: {
+        maxResults?: number;
+        minScore?: number;
+        sources?: ReadonlyArray<"memory" | "sessions" | "wiki">;
+    }): Promise<ReadonlyArray<{
+        path: string;
+        startLine: number;
+        endLine: number;
+        score: number;
+        textScore: number;
+        vectorScore?: number;
+        snippet: string;
+        source: "memory" | "sessions" | "wiki";
+        citation: string;
+    }>>;
+    status(): {
+        backend: "fts-only" | "hybrid";
+        filesIndexed: number;
+        chunksIndexed: number;
+        lastSyncMs?: number;
+        /**
+         * Whether `filesIndexed` / `chunksIndexed` were measured. `false` on the Lance backend, whose
+         * store is async while `status()` is not — the zeros there are placeholders, so
+         * `chunksIndexed > 0` is not a valid test for "is the index populated".
+         */
+        countsExact: boolean;
+    };
+    close(): Promise<void> | void;
+}
+/**
+ * Inputs for {@link Memory.runDreamingSweep}.
+ *
+ * `embedding` is required and has no default: the sweep scores cosine similarity between facts, so
+ * without real embeddings there is nothing to dedup or cluster on. Both thresholds are cosine
+ * similarity in [0, 1] and default to `0.95` for dedup and `0.75` for clustering — dedup is the
+ * stricter of the two because merging two facts that were merely related is a data loss, while
+ * failing to cluster them only costs a note.
+ *
+ * @public
+ */
+interface DreamingSweepOptions {
+    /** Workspace cwd holding `.theokit/memory/`. */
+    cwd: string;
+    /**
+     * Absolute path (or `~/`-prefixed) of the memory root to sweep, when the agent that wrote it set
+     * `memory.directory`. Defaults to `<cwd>/.theokit/memory`.
+     */
+    directory?: string;
+    /**
+     * Embedding provider for semantic dedup + clustering. Required — dreaming
+     * relies on real embeddings to score cosine similarity. Supported providers:
+     * `"openai"`, `"mistral"`, `"openrouter"`, `"voyage"`, `"deepinfra"`,
+     * `"ollama"` (local, ADR D183).
+     */
+    embedding: {
+        provider: "openai" | "mistral" | "openrouter" | "voyage" | "deepinfra" | "ollama";
+        model?: string;
+    };
+    /** Cosine-similarity threshold for the dedup phase. Default `0.95`. */
+    dedupThreshold?: number;
+    /** Cosine-similarity threshold for the clustering phase. Default `0.75`. */
+    clusterThreshold?: number;
+}
+/**
+ * What one dreaming sweep did.
+ *
+ * `status` is `"skipped"` when the workspace held no facts to work on and `"error"` when the sweep
+ * failed; both come back with every counter at zero, so check `status` before reading a zero as
+ * "there was nothing to consolidate". A failure is reported through this field rather than as a
+ * rejection, which means a caller that only awaits the promise never learns the sweep did nothing.
+ * `factsBefore` and `factsAfter` bracket the run, which is the pair to compare when you want to
+ * know whether the sweep was worth running rather than how many operations it performed.
+ *
+ * @public
+ */
+interface DreamingSweepResult {
+    status: "ok" | "skipped" | "error";
+    factsBefore: number;
+    factsAfter: number;
+    duplicatesRemoved: number;
+    clustersCreated: number;
+    notesWritten: number;
+}
+/**
+ * Options for `Memory.openIndex`. Mirrors the internal `OpenIndexOptions`
+ * but using only public types from the SDK surface.
+ *
+ * @public
+ */
+interface OpenMemoryIndexOptions {
+    /** Workspace cwd holding `.theokit/memory/`. */
+    cwd: string;
+    /** Override storage file path (SQLite) OR storage directory (Lance). */
+    filePath?: string;
+    /**
+     * Embedding runtime — REQUIRED for `backend: "lance"`, optional for
+     * `"sqlite-vec"` (when omitted, SQLite runs FTS-only without vector
+     * recall).
+     */
+    embedding?: {
+        provider: "openai" | "mistral" | "openrouter" | "voyage" | "deepinfra" | "ollama";
+        model?: string;
+    };
+    /** Default `"sqlite-vec"`. Set to `"lance"` to opt into LanceDB (peer dep). */
+    backend?: "sqlite-vec" | "lance";
+}
+/**
+ * Memory operations that run OUTSIDE an agent turn.
+ *
+ * Everything here is reachable without `Agent.create({ memory: ... })`, which is the point: opening
+ * an index directly is how a CLI or a maintenance job inspects or rebuilds what the agent will
+ * later read, and the dreaming sweep is maintenance that no `send()` triggers.
+ *
+ * Both operations route through the `@theokit/sdk-memory` peer package when it is installed and
+ * fall back to the in-tree implementation when it is not. The fallback is not a degraded mode —
+ * behaviour and thrown errors match — so consumers do not branch on which path ran.
+ *
+ * @public
+ */
+declare const Memory: {
+    /**
+     * Open a memory index. Dispatches to SQLite-vec (default, zero deps) or
+     * LanceDB (opt-in via `backend: "lance"`, requires `@lancedb/lancedb`
+     * peer dep + an embedding runtime).
+     *
+     * Returns a `MemoryIndex` with `sync()`, `search(query, opts?)`,
+     * `status()`, and `close()`. Use this when you want a direct index
+     * handle outside of `Agent.create({ memory: ... })`.
+     *
+     * @throws ConfigurationError({code:"invalid_memory_backend"}) for typos
+     *   like `"lancedb"`.
+     * @throws ConfigurationError({code:"lance_requires_embedding"}) when
+     *   `backend: "lance"` is requested without `embedding`.
+     * @throws ConfigurationError({code:"lance_backend_unavailable"}) when
+     *   `backend: "lance"` is requested but the peer dep is absent.
+     *
+     * @public
+     */
+    openIndex(opts: OpenMemoryIndexOptions): Promise<MemoryIndexHandle>;
+    /**
+     * Run a dreaming sweep: dedup near-duplicate facts, cluster thematically
+     * related ones, and write a consolidated note + diary entry.
+     *
+     * @public
+     */
+    runDreamingSweep(opts: DreamingSweepOptions): Promise<DreamingSweepResult>;
+};
+
+/**
+ * Runtime helpers for `MemoryAdapter` (T1.1, ADR D141).
+ *
+ * Kept separate from `types/memory-adapter.ts` so the types module
+ * stays import-free of runtime code (dep-cruise rule
+ * `types-dont-import-runtime`). Adapter authors call `mkMemoryId` to
+ * construct a branded id and `extractRawId` to unwrap with cross-adapter
+ * safety (EC-B).
+ *
+ * @public
+ */
+
+/**
+ * Construct a branded `MemoryId` for an adapter. Embeds the adapter
+ * identifier so `extractRawId` can reject ids minted by other adapters.
+ *
+ * @public
+ */
+declare function mkMemoryId(adapterId: string, rawId: string): MemoryId;
+/**
+ * Extract the raw provider id from a `MemoryId`, enforcing that the
+ * prefix matches `expectedAdapterId`. Throws `MemoryAdapterError(code:
+ * "invalid_input")` on mismatch — prevents `mem0.delete(supermemoryId)`
+ * from accidentally deleting unrelated data (EC-B).
+ *
+ * @public
+ */
+declare function extractRawId(id: MemoryId, expectedAdapterId: string): string;
+
+/**
+ * Options for {@link migrateSqliteToLance}.
+ *
+ * @public
+ */
+interface MigrateOptions {
+    cwd: string;
+    dryRun?: boolean;
+    batchSize?: number;
+    logger?: (msg: string) => void;
+}
+/**
+ * Outcome of {@link migrateSqliteToLance}.
+ *
+ * @public
+ */
+interface MigrateResult {
+    countSqlite: number;
+    countLance: number;
+    validated: boolean;
+    sampleComparisons: ReadonlyArray<{
+        id: string;
+        match: boolean;
+    }>;
+    lancePath: string;
+    committed: boolean;
+}
+/**
+ * Migrate the Memory index from SQLite to LanceDB. ADR D44.
+ *
+ * @public
+ */
+declare function migrateSqliteToLance(options: MigrateOptions): Promise<MigrateResult>;
+
+/**
+ * `PermissionEngine` — first-match permission rules for tool invocations.
+ *
+ * Evaluates a tool name (and optional arguments, #55) against an ordered list
+ * of rules. First matching rule wins; when no rule matches the `defaultAction`
+ * is returned. #55 — the default is now `"ask"` (FAIL-CLOSED): a permission
+ * engine that cannot positively allow must not silently allow. Opt back into
+ * the previous fail-open behavior with `{ defaultAction: "allow" }`.
+ */
+type PermissionAction = "allow" | "deny" | "ask";
+
+/**
+ * SE1 — apply a {@link PermissionMode} to a rule-engine verdict. Pure.
+ *
+ * `explicit` is `true` when the verdict came from a rule that matched by name (and
+ * args), `false` when it is the fail-closed default for an unmatched call. The flag
+ * is load-bearing for `acceptEdits`, which auto-approves the unmatched default but
+ * keeps honoring an explicit `ask` rule (unlike `bypass`, which allows even that).
+ *
+ * INVARIANT (both a peer project + Codex): an explicit `deny` is immune to EVERY
+ * auto-approve mode — `bypass`/`acceptEdits` never un-deny.
+ */
+declare function applyMode(verdict: PermissionAction, mode: PermissionMode, explicit: boolean): PermissionAction;
+/**
+ * #55 — an argument matcher. A rule with `args` gates on the tool's argument
+ * VALUES, not just its name: an exact string, a RegExp (tested against the
+ * stringified value), or a predicate. Every declared arg must match for the
+ * rule to apply — so `{ tool: "shell", args: { command: /rm\s+-rf/ } }` denies
+ * a destructive shell call while leaving `ls` to fall through.
+ */
+type ArgMatcher = string | RegExp | ((value: unknown) => boolean);
+/**
+ * One entry in a {@link PermissionEngine}'s ordered rule list.
+ *
+ * Order is the semantics. The engine walks the list and the first rule whose `tool` matches — and
+ * whose `args` matchers all pass, when it declares any — decides; nothing after it is consulted. Put
+ * the narrow rules first: a catch-all `tool` RegExp placed above a specific deny makes that deny
+ * unreachable, and nothing warns you.
+ *
+ * `args` is what lets one tool name resolve differently depending on what it is asked to do —
+ * `{ tool: "shell", args: { command: /rm\s+-rf/ }, action: "deny" }` blocks the destructive call and
+ * leaves `ls` to fall through to a later rule. Every declared matcher must pass.
+ *
+ * **A rule that declares an argument the call did not supply does not match**, whatever form the
+ * matcher takes — string, RegExp or predicate. The predicate is not invoked with `undefined`; the
+ * guard runs first, for every matcher form. Evaluation continues to the next rule.
+ *
+ * That was not always true, and the fix is the reason this paragraph is explicit (#367). A predicate
+ * used to be called anyway, so `(v) => v !== "prod"` returned true for a missing argument and an
+ * ALLOW rule authorized a call that supplied nothing, while `(v) => v.includes("rm")` threw a
+ * TypeError out of the permission gate. This docblock told consumers to guard every predicate by
+ * hand for months after `argMatches` stopped needing it — you do not have to.
+ *
+ * A rule that matches yields an EXPLICIT verdict, and that is what makes it survive a permissive
+ * `PermissionMode`: `acceptEdits` auto-approves the unmatched default but still honours an explicit
+ * `ask` rule, and an explicit `deny` is immune to every mode, `bypass` included.
+ */
+interface PermissionRule {
+    /** Tool name (exact string) or pattern (RegExp). */
+    tool: string | RegExp;
+    /**
+     * #55 — optional per-argument matchers. When present, the rule matches only
+     * if the tool name matches AND every declared arg predicate matches the
+     * corresponding call argument. A missing/undefined arg fails its predicate
+     * (the rule does not match) — never throws.
+     */
+    args?: Record<string, ArgMatcher>;
+    /** Action to take when rule matches. */
+    action: PermissionAction;
+}
+/** Options for {@link PermissionEngine}. */
+interface PermissionEngineOptions {
+    /**
+     * Action when no rule matches. #55 — default is now `"ask"` (fail-closed): a
+     * permission engine that cannot positively allow must not silently allow.
+     * Pass `"allow"` to restore the previous fail-open behavior.
+     */
+    readonly defaultAction?: PermissionAction;
+}
+/**
+ * Ordered first-match permission rules for tool invocations — the policy object you hand to
+ * `PermissionPlugin.create()` to have it enforced.
+ *
+ * On its own it enforces nothing. `evaluate(toolName, args, mode)` is a pure function returning
+ * `"allow" | "deny" | "ask"`, and no part of the SDK calls it until the engine is wrapped in a plugin
+ * and that plugin is registered on an agent. The plugin is where a verdict becomes behaviour: `deny`
+ * blocks the tool call, `allow` passes it through, and `ask` is routed to the host's `canUseTool`
+ * gate — with no gate configured, `ask` blocks. So constructing an engine and never registering it
+ * is a policy that does nothing, which is the mistake worth knowing about first.
+ *
+ * It is fail-closed by default: a call no rule matches resolves to `"ask"`, not `"allow"`, so a tool
+ * the rules never mention needs a human — or an explicit `{ defaultAction: "allow" }` — before it
+ * runs. Keep that default if you intend to use `PermissionMode: "plan"` for read-only behaviour,
+ * because `plan` gates on the RESOLVED verdict: an engine built with `defaultAction: "allow"` still
+ * allows every unmatched call under `plan`.
+ *
+ * The rules array is stored by reference and walked afresh on every `evaluate` call. Mutating the
+ * array you passed in therefore changes the policy of a live engine; build a new engine when you
+ * want a policy change to be a deliberate, visible event.
+ */
+declare class PermissionEngine {
+    #private;
+    private readonly rules;
+    private readonly defaultAction;
+    constructor(rules: PermissionRule[], options?: PermissionEngineOptions);
+    /**
+     * Evaluate a tool name (and optional arguments) against the rules. First
+     * match wins; falls back to the configured `defaultAction` (default `"ask"`,
+     * fail-closed) when no rule matches. #55 — a rule with `args` gates on the
+     * argument values, so the same tool name can resolve to different actions
+     * depending on what it is asked to do.
+     */
+    evaluate(toolName: string, args?: Record<string, unknown>, mode?: PermissionMode): PermissionAction;
+}
+
+/**
+ * M7-5 — `createPermissionPlugin`: wire a {@link PermissionEngine} into the
+ * `definePlugin` `pre_tool_call` veto seam. This is the canonical exemplar that
+ * gives `PermissionEngine` a real caller (it was previously exported-but-unwired):
+ * on each tool call the engine's verdict maps to the veto contract —
+ * `"deny"` -> block, `"ask"` -> the caller's `onAsk` resolver (or block, fail-closed),
+ * `"allow"` -> pass.
+ *
+ * @public
+ */
+
+/**
+ * SE1 — context passed to the {@link PermissionGate}. Intentionally minimal for
+ * SE1; `agentId`/`runId` (for audit logging) are a documented follow-up — they are
+ * available on the raw `pre_tool_call` context and can be threaded in a later slice.
+ */
+interface PermissionGateContext {
+    /** The tool being gated. */
+    readonly toolName: string;
+    /** The active permission mode for this run. */
+    readonly mode: PermissionMode;
+}
+/**
+ * SE1 — the resolution of an `"ask"` verdict by the host gate. Fail-closed: an
+ * absent gate, a throwing gate, and a `"deny"` decision all block. Arg rewrite
+ * (`updatedInput`) is intentionally NOT supported yet — the `pre_tool_call` seam
+ * is veto-only (`{ block, message }`); a future enhancement can extend it.
+ */
+type PermissionGateDecision = {
+    readonly behavior: "allow";
+} | {
+    readonly behavior: "deny";
+    readonly message?: string;
+};
+/**
+ * SE1 — the enriched `canUseTool` gate (the Anthropic-parity shape). Invoked ONLY
+ * on an `"ask"` verdict, it receives the tool name, its input args, and the run
+ * {@link PermissionGateContext}, and resolves to allow/deny. May be async (a real
+ * gate can prompt a human — the `pre_tool_call` seam awaits it).
+ */
+type PermissionGate = (toolName: string, input: Record<string, unknown>, ctx: PermissionGateContext) => PermissionGateDecision | Promise<PermissionGateDecision>;
+/** Options for {@link createPermissionPlugin}. */
+interface PermissionPluginOptions {
+    /** Plugin name (default `"permission-engine"`). */
+    readonly name?: string;
+    /**
+     * SE1 — the per-run {@link PermissionMode}. Threaded into `engine.evaluate`, so
+     * `bypass` auto-allows the ask verdict (gate never consulted), `plan` blocks
+     * mutations, etc. An explicit `deny` rule is immune to every mode. Default
+     * `"default"` (rules decide; unmatched ⇒ fail-closed ask).
+     */
+    readonly mode?: PermissionMode;
+    /**
+     * SE1 — the enriched gate for the `"ask"` verdict. Preferred over {@link onAsk}.
+     * Absent gate on an `ask` verdict ⇒ fail-closed block.
+     */
+    readonly canUseTool?: PermissionGate;
+    /**
+     * @deprecated since SE1 — use {@link canUseTool}, which receives `(toolName,
+     * input, ctx)` and returns a typed decision. Honored only when `canUseTool` is
+     * absent. Returns a veto (`{block,message}`) to deny or `undefined` to allow.
+     */
+    readonly onAsk?: (toolName: string) => PreToolCallDecision | undefined;
+}
+/** SE36 — `PermissionPlugin.create` replaces `createPermissionPlugin` (ADR 0015). @public */
+declare class PermissionPlugin {
+    private constructor();
+    static create(engine: PermissionEngine, opts?: PermissionPluginOptions): Plugin;
+}
+
+/**
+ * Load a project's `.env` without letting it move the credential store or switch off a trust
+ * decision.
+ *
+ * `process.loadEnvFile()` reads the PROJECT's `.env` into `process.env`. For a provider key that is
+ * exactly right and is the documented way to configure a scaffolded product. For the handful of
+ * variables that decide WHERE credentials live and WHAT is trusted it is a hole: a cloned
+ * repository is untrusted input, and a `.env` inside it is untrusted input the runtime is about to
+ * treat as configuration.
+ *
+ * Concretely, without this guard a repository shipping
+ *
+ * ```
+ * THEOKIT_AUTH_HOME=/tmp/attacker-store
+ * ```
+ *
+ * redirects the credential store the moment the product starts in that directory — before any
+ * trust prompt, because locating the store is what happens first.
+ *
+ * ## Why it lives here
+ *
+ * The scaffolding template (`create-theokit`, TUI surface) calls `process.loadEnvFile()` with no
+ * guard, so every product generated from it starts exposed. One consumer found this and fixed it in
+ * ~30 lines of its own. A defence each consumer has to rediscover is a defence most will not have,
+ * and this one is invisible when missing: nothing fails, the store simply moves.
+ *
+ * ## Why the set is named
+ *
+ * A convention — "anything ending in `_HOME`", "anything with TRUST in it" — silently changes
+ * meaning as variables are added, in the direction of accidentally sovereign or accidentally not.
+ * The list is explicit so that making a variable sovereign is a deliberate act, and so a reader can
+ * see the security boundary without grepping for it.
+ *
+ * @public
+ */
+/**
+ * Variables a project-scoped source may never set. Each either locates the credential store, names
+ * the config directory that is read as configuration, or carries a trust decision.
+ *
+ * `THEOKIT_API_KEY` is deliberately ABSENT. A project supplying its own provider key through `.env`
+ * is the documented, intended path — treating it as sovereign would break every scaffolded product
+ * to defend nothing, since a key the project supplies is a key the project already has.
+ *
+ * @public
+ */
+declare const SOVEREIGN_ENV_KEYS: readonly ["THEOKIT_HOME", "THEOKIT_AUTH_HOME", "THEOKIT_TRUSTED_PROVIDERS", "THEOKIT_REDACT_SECRETS", "THEOKIT_OAUTH_TX_SALT"];
+/**
+ * The union of {@link SOVEREIGN_ENV_KEYS} entries — the variables a project-scoped `.env` may never
+ * set.
+ *
+ * Derived from the array rather than written out, so adding a key in one place cannot leave the
+ * type behind. Use it where a caller must name one of the protected variables and a plain `string`
+ * would let a typo through silently.
+ *
+ * @public
+ */
+type SovereignEnvKey = (typeof SOVEREIGN_ENV_KEYS)[number];
+/** The mutable shape of `process.env`, narrowed so a caller can pass a plain object in tests. */
+type MutableEnv = Record<string, string | undefined>;
+/**
+ * Read the project's `.env` into `env`, then restore every {@link SOVEREIGN_ENV_KEYS} entry to the
+ * value it had BEFORE the load — including restoring it to absent.
+ *
+ * Capture-then-restore rather than filtering the file: `process.loadEnvFile` offers no hook between
+ * parsing and assignment, and reimplementing dotenv parsing to filter it would be a second parser
+ * to keep in step with Node's. Restoring afterwards needs no parser and cannot disagree with one.
+ *
+ * @param env the environment to mutate. Defaults to `process.env`.
+ * @param load performs the load. Defaults to `process.loadEnvFile` when the runtime has it, and to
+ *   `undefined` when it does not — in which case this is a no-op rather than a startup crash.
+ * @public
+ */
+declare function loadProjectEnv(env?: MutableEnv, load?: (() => void) | undefined): void;
+
+/**
+ * Decide which session artifacts may be deleted — and never delete them.
+ *
+ * This package creates session artifacts (transcripts, locks, temp files) and cleans up only what is
+ * in flight in the operation doing the cleaning: a lock it just released, a `.tmp` from a failed
+ * atomic write. Nothing collects the rest, so every consumer either writes its own collector or lets
+ * the directory grow without bound — and a hand-rolled collector on the path that deletes a user's
+ * transcript is the worst place for each product to learn the same lessons separately.
+ *
+ * ## Planning is not deleting, deliberately
+ *
+ * A function that decided AND deleted could not be tested without a filesystem, and the case that
+ * matters most — "we could not establish whether this session is live" — would have to be simulated
+ * rather than asserted. Here the decision is pure: the plan IS the dry run, and executing it is a
+ * separate act on a value someone can read first. That separation is the dry-run guarantee, rather
+ * than a flag that has to be remembered.
+ *
+ * ## The tri-state
+ *
+ * `keep`, `reap`, `undetermined`. An artifact whose liveness could not be established is never
+ * reaped and never quietly counted as dead. Collapsing "could not determine" into "not there" is how
+ * a collector deletes a session running on another machine, or behind a mount that answered slowly.
+ * The third bucket costs a branch and buys the only guarantee worth having on this path.
+ *
+ * @public
+ */
+
+/** Raised when a retention policy cannot be honoured as written. @public */
+declare class RetentionPolicyError extends TheokitAgentError {
+    readonly name = "RetentionPolicyError";
+}
+/**
+ * One artifact the caller is considering deleting, described well enough to decide about.
+ *
+ * `id` is only ever compared for equality, so any stable identity works — a path, a session id, an
+ * inode. `live` is the tri-state that carries the whole safety property: `"unknown"` means the
+ * caller could not establish liveness, and it is honoured as a third answer rather than folded into
+ * `false`.
+ *
+ * @public
+ */
+interface ReapableArtifact {
+    readonly id: string;
+    /** Epoch milliseconds. Compared against an injected `nowMs`, never against a read clock. */
+    readonly lastModifiedMs: number;
+    /**
+     * Whether a writer still holds this artifact. `"unknown"` when the caller could not establish it —
+     * a stale lock behind a slow mount, a PID on another host — and it is honoured as a third answer
+     * rather than folded into `false`.
+     */
+    readonly live: boolean | "unknown";
+}
+/**
+ * How long artifacts are kept and how many always survive.
+ *
+ * The two interact as a window plus a FLOOR, not as two independent allowances: `keepLast` rescues
+ * artifacts only when the window and liveness together spared fewer than that many, and rescues
+ * exactly enough to reach the count. Both are refused by `planReaping` rather than clamped when
+ * they are not expressible — see its `@throws`.
+ *
+ * @public
+ */
+interface RetentionPolicy {
+    /** Artifacts strictly older than this are candidates. The boundary itself is kept. */
+    readonly maxAgeMs: number;
+    /**
+     * A FLOOR on how many artifacts survive: "you will always have your last N sessions". When
+     * liveness and the retention window already spare N or more, this changes nothing; when they
+     * spare fewer, the newest of the remainder are spared until the count reaches N.
+     *
+     * Undetermined artifacts do NOT count toward the floor. Their liveness was never established, so
+     * counting them would let a transient mount failure satisfy the floor with artifacts nobody
+     * confirmed exist as sessions — and quietly delete the ones that do.
+     */
+    readonly keepLast: number;
+}
+/** Why an artifact survived. @public */
+type KeepReason = "live" | "within-retention" | "keep-last";
+/**
+ * An artifact that survived, carrying the reason it did.
+ *
+ * The reason is the one that spared it FIRST, in the order liveness, then the retention window,
+ * then the floor — so a live artifact inside the window reports `"live"`, and `"keep-last"` only
+ * appears on artifacts that had no reason of their own.
+ *
+ * @public
+ */
+interface KeptArtifact extends ReapableArtifact {
+    readonly reason: KeepReason;
+}
+/**
+ * The decision, as three disjoint buckets whose union is exactly the input.
+ *
+ * Nothing is deleted by producing one of these — the plan IS the dry run, and executing it is a
+ * separate act on a value you can read first. Delete only what is in `reap`; `undetermined` is not
+ * a smaller `reap`, it is the set nobody could decide about.
+ *
+ * @public
+ */
+interface ReapPlan {
+    /** Safe to delete. Everything here was decided, not defaulted. */
+    readonly reap: readonly ReapableArtifact[];
+    readonly keep: readonly KeptArtifact[];
+    /** Liveness could not be established. Never deleted, never counted as kept. */
+    readonly undetermined: readonly ReapableArtifact[];
+}
+/**
+ * Everything `planReaping` needs: the candidates, the policy, and the current time.
+ *
+ * `nowMs` is a parameter rather than a clock read so the same input always produces the same plan —
+ * which is what lets a caller compute a plan, show it, and execute it later against the same
+ * decision instead of a freshly re-derived one.
+ *
+ * @public
+ */
+interface ReapPlanInput {
+    readonly artifacts: readonly ReapableArtifact[];
+    readonly retention: RetentionPolicy;
+    /** Injected so the plan is reproducible and testable; this module never reads a clock. */
+    readonly nowMs: number;
+}
+/**
+ * Sort artifacts into keep, reap, and undetermined — and delete nothing.
+ *
+ * The order of decision is liveness, then the retention window, then the floor. An artifact whose
+ * `live` is `"unknown"` leaves at the first step and is never considered again: it is not counted
+ * toward `keepLast`, so a transient mount failure cannot satisfy "keep my last two" with artifacts
+ * nobody confirmed while the confirmed ones are deleted.
+ *
+ * The window boundary belongs to the safe side. An artifact exactly `maxAgeMs` old is kept, so a
+ * 30-day retention never means 29 depending on clock granularity.
+ *
+ * @returns the three buckets. Their union is exactly the input, each artifact counted once — the
+ *   invariant an operator reads the totals against.
+ * @throws RetentionPolicyError when `maxAgeMs` is negative or not finite, or `keepLast` is negative
+ *   or not an integer. Nonsense is refused rather than clamped, because a clamped window on this
+ *   path deletes data the operator meant to keep.
+ * @public
+ */
+declare function planReaping(input: ReapPlanInput): ReapPlan;
+
+/** The internal JSON-Schema shape the synthetic `output` tool consumes. */
+type NormalizedJsonSchema = Record<string, unknown>;
+/**
+ * Normalize any supported schema to the internal JSON Schema. Async because the Valibot path
+ * dynamically imports its optional converter. Throws a clear, typed-message error for an unsupported
+ * schema or a missing Valibot peer (error-handling.md).
+ */
+declare function normalizeSchema(schema: unknown): Promise<NormalizedJsonSchema>;
+
+/**
+ * Public security namespace (T2.1, ADR D68).
+ *
+ * Two entry points:
+ *
+ * - `Security.redact(text, opts?)` — apply the canonical redactor to
+ *   arbitrary text. Useful when a consumer app (or example) writes its
+ *   own logs / metrics / paste-share artifacts that the SDK's wired
+ *   sinks (error metadata, telemetry, transcript, migration) don't
+ *   cover.
+ * - `Security.addPattern(re)` — register a custom credential pattern
+ *   on top of the 12 builtins (OpenAI, Anthropic, GitHub PAT classic +
+ *   fine, GitLab, AWS, Google, Slack, Sentry, Stripe live + restricted)
+ *   plus the parametric `key=value` + `Bearer <token>` matchers.
+ *
+ * Redaction is ON by default. Disable with `THEOKIT_REDACT_SECRETS=false`
+ * (a warning is emitted on stderr so the operator knows the SDK process
+ * is vulnerable). The env var is snapshotted at module init — runtime
+ * mutation cannot disable it, defending against prompt injection that
+ * tries to flip the flag mid-run.
+ */
+declare class Security {
+    private constructor();
+    /**
+     * Redact known credential patterns from `text` and return the masked
+     * string. Use this at any consumer output boundary the SDK does not
+     * directly own (custom stdout loggers, app-level metrics, debug-share
+     * artifacts, etc.).
+     *
+     * Coerces non-strings (objects via JSON.stringify, null/undefined → "").
+     * Two-bucket masking: tokens shorter than 18 chars → `***`; longer
+     * tokens preserve `prefix...suffix` for debuggability without revealing
+     * the secret middle.
+     *
+     * @param text - The value to redact. Strings, objects, primitives all OK.
+     * @param opts.codeFile - When `true`, skips the parametric `key=value`
+     *   matcher so file content like `.env.example` placeholders is left
+     *   intact. Built-in pattern matches still apply.
+     *
+     * @example
+     * console.log(`[bot] received: ${Security.redact(userText)}`);
+     * // → "[bot] received: please remember sk-abc...xyz1"
+     */
+    static redact(text: unknown, opts?: {
+        codeFile?: boolean;
+    }): string;
+    /**
+     * Register a custom redaction pattern. Additive — built-in patterns
+     * (OpenAI, Anthropic, GitHub PAT, AWS, etc.) cannot be removed.
+     *
+     * @param re - RegExp with `/g` flag. Throws if `/g` is missing
+     *             (without /g, only first match is replaced and the rest
+     *             leaks).
+     *
+     * Process-global mutable state. The SDK is designed for single-tenant
+     * processes (Theo PaaS user runtime, local CLI). Multi-tenant
+     * deployments running multiple SDK consumers in the same Node process
+     * share this list — patterns added by tenant A apply to tenant B's
+     * redactions. Acceptable for v1; future isolate-aware refactor would
+     * thread patterns through a context if needed.
+     *
+     * @example
+     * Security.addPattern(/MYORG-[A-Z0-9]{32}/g);
+     * // → text containing "MYORG-AAAA...AAAA" now masks like a builtin.
+     */
+    static addPattern(re: RegExp): void;
+}
+
+/**
+ * Resolve a security-relevant setting across configuration layers, where a lower-trust layer may
+ * TIGHTEN it and never loosen it.
+ *
+ * Layered configuration usually resolves last-wins, and for the keys that decide confinement — a
+ * sandbox mode, an approval policy — last-wins is a hole. With plain precedence a project layer
+ * outranks the user's own file, so a cloned repository can hand itself the most permissive setting
+ * and the operator's global choice loses silently, at the moment the directory is opened. Nothing
+ * fails; the confinement is simply gone.
+ *
+ * ## What is generic here, and what is not
+ *
+ * The RULE is generic: named layers may only move the value in the confining direction, while one
+ * designated layer — the operator's explicit flag — wins in both. The VOCABULARY is not: which
+ * values count as more permissive, what the layers are called, and which one is the operator's are
+ * all the consumer's, and are parameters.
+ *
+ * That distinction is what makes this extractable when a keypress router was not. Here the
+ * vocabulary is DATA — two lists and a name — so a second product supplies its own without
+ * inheriting the first's words. An interface shaped by one product's states would have given the
+ * second consumer something to route around.
+ *
+ * ## Why the override is not validated
+ *
+ * `override` is returned verbatim, even when it is outside `permissiveness`. Validating the
+ * operator's flag is the consumer's job: it owns the vocabulary, the error message and the exit
+ * code. Silently dropping an unrecognised flag would be worse than passing it through — the
+ * operator would see their explicit instruction ignored with no explanation.
+ *
+ * A value outside the vocabulary in a RESTRICTED layer is different and IS ignored: a typo in a
+ * repository's config must neither become the effective setting nor be treated as maximally
+ * permissive.
+ *
+ * @public
+ */
+/**
+ * The vocabulary, the layer names, and the values to resolve.
+ *
+ * Two orders matter and they are not the same one. The UNRESTRICTED layers — every key of `layers`
+ * that is neither `override` nor listed in `restricted` — are resolved last-wins in the enumeration
+ * order of the `layers` object. The RESTRICTED layers are applied in the order of the `restricted`
+ * array, regardless of where they sit in `layers`. Put a layer in `restricted` and its position in
+ * that array is what decides when it gets to tighten.
+ *
+ * A layer named in `restricted` but absent from `layers`, or present with `undefined`, is skipped.
+ *
+ * @public
+ */
+interface SecurityFloorInput {
+    /**
+     * The vocabulary, ordered from most confined to least. Index is permissiveness, so
+     * `["read-only", "workspace-write", "danger-full-access"]` says read-only confines the most.
+     */
+    readonly permissiveness: readonly string[];
+    /** Layers that may only tighten — typically anything a repository or environment can supply. */
+    readonly restricted: readonly string[];
+    /** The layer that wins outright in both directions — the operator's explicit flag. */
+    readonly override: string;
+    /**
+     * Values per layer. Layers absent from `restricted` are unconstrained, which is how a `user`
+     * layer loosens its own `defaults`.
+     */
+    readonly layers: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * Resolve a security-relevant setting so that a lower-trust layer can only tighten it.
+ *
+ * Two paths. When `layers[override]` holds a value, that value is returned VERBATIM and nothing
+ * else is consulted — it is not checked against `permissiveness`, because validating the operator's
+ * own flag belongs to the consumer that owns the vocabulary and the error message. Otherwise a
+ * baseline is taken from the unrestricted layers, and each restricted layer in turn may lower it
+ * and never raise it.
+ *
+ * Two consequences worth knowing before wiring this up. A value in a restricted layer that is not
+ * in `permissiveness` is IGNORED rather than trusted, so a typo in a repository's config leaves the
+ * baseline standing instead of becoming the effective setting. And the ceiling only ever descends:
+ * once one restricted layer tightens, a later one cannot return to the baseline, even though it
+ * could have chosen that value had it come first.
+ *
+ * When no layer supplied a value at all, the answer is `undefined` — the absence is reported rather
+ * than filled in with the most confined member of the vocabulary.
+ *
+ * @returns the resolved value, or `undefined` when no layer supplied one.
+ * @public
+ */
+declare function applySecurityFloor(input: SecurityFloorInput): string | undefined;
+
+/**
+ * Refuse to destroy a session another process is still writing.
+ *
+ * Every agent product that lets a user delete or overwrite a session needs this, and the failure is
+ * unrecoverable in the worst way: a transcript removed underneath a running session takes with it
+ * everything that session had not flushed, and nothing errors. The user sees a successful delete.
+ *
+ * ## The ordering is the point
+ *
+ * The check runs BEFORE anything is mutated. Removing a registry entry and then refusing leaves a
+ * session that can be neither opened nor deleted — worse than either outcome on its own. So this is
+ * a function the caller passes through rather than a flag it may consult afterwards: the throw is
+ * what stops the mutation, and there is no way to read the answer and forget to act on it.
+ *
+ * ## What is generic, and what is not
+ *
+ * The RULE is: a session declared live is not destroyable, and refusing says which one and why. The
+ * VOCABULARY is not — how a product decides liveness (a pointer file, the newest transcript, a
+ * lease, an active registry entry) is its own. Nothing here touches a filesystem.
+ *
+ * @public
+ */
+
+/** Why the destruction was refused. @public */
+type LiveSessionReason = "session-is-live" | "liveness-undetermined";
+/**
+ * Raised by `guardSessionDestruction` instead of letting a session be destroyed.
+ *
+ * Read `reason` rather than the message when deciding what to do: `"session-is-live"` is fixed by
+ * closing the other session, `"liveness-undetermined"` is fixed by making the liveness check work
+ * again, and telling a user to close a session when nothing could be read sends them to close
+ * nothing. `sessionId` carries the session the refusal was about.
+ *
+ * @public
+ */
+declare class LiveSessionError extends TheokitAgentError {
+    readonly name = "LiveSessionError";
+    readonly sessionId: string;
+    readonly reason: LiveSessionReason;
+    constructor(sessionId: string, reason: LiveSessionReason);
+}
+/**
+ * Throw unless `sessionId` is safe to destroy.
+ *
+ * @param live - the sessions the product declares live, or `undefined` when it could not tell.
+ *   The distinction is load-bearing: an EMPTY set is a legitimate answer (nothing is open), while
+ *   `undefined` refuses. A product that swallowed a read error and returned `[]` would hand this
+ *   guard the one input that disables it entirely, on exactly the path that destroys data.
+ * @throws LiveSessionError naming the session and the reason — "close that session" and "the guard
+ *   could not read" have different fixes, and conflating them sends the user to close nothing.
+ * @public
+ */
+declare function guardSessionDestruction(sessionId: string, live: readonly string[] | undefined): void;
+
+/** Which session to read, in the terms a host already has. */
+interface ReadSessionMessagesOptions {
+    /** The session's agent id — the same id `Agent` was created or resumed with. */
+    sessionId: string;
+    /**
+     * The working directory the session belongs to. Sessions are per-cwd, so the same
+     * id under a different cwd is a different session. Defaults to `process.cwd()`.
+     */
+    cwd?: string;
+    /**
+     * Where transcripts live. Only needed when the agent was created with
+     * `local.sessionDir`; otherwise the SDK's default location is used.
+     */
+    sessionDir?: string;
+}
+/**
+ * Read the messages a session already contains, for a surface that needs to re-render it.
+ *
+ * #546 — the SDK read these records to give the model its context on resume, and a host had
+ * no way to read the same thing: a resumed session showed an empty screen while the model
+ * demonstrably remembered. The alternative was for the host to parse
+ * `<sessionDir>/projects/<encoded-cwd>/<id>.jsonl` itself, which is a private contract —
+ * both the record shape and the directory encoding are the SDK's to change.
+ *
+ * This is deliberately narrower than the internal reader it wraps. That one takes a
+ * {@link SessionStore}, and exporting it would put that interface, its record shape and its
+ * lease semantics into the public surface to serve a caller that only wants to render what
+ * is already there. A host that HAS a custom store can already read from it directly.
+ *
+ * Parsing stays tolerant, as it is on the resume path: a malformed line costs one message,
+ * not the screen. A session that was never written resolves to `[]` rather than throwing —
+ * a fresh session has no history, which is not an error.
+ *
+ * @example
+ * ```ts
+ * const history = await readSessionMessages({ sessionId, cwd: projectDir });
+ * for (const m of history) render(m.role, m.text);
+ * ```
+ */
+declare function readSessionMessages(options: ReadSessionMessagesOptions): Promise<SessionMessage[]>;
+
+/**
+ * M3 #62 — scoped session state.
+ *
+ * A conversation id can be namespaced by SCOPE so a consumer keeps app-durable,
+ * user-durable, and ephemeral (temp) session data separated in the same store:
+ *
+ * - `app:`  — durable state shared across users (app-level memory).
+ * - `user:` — durable state for one user.
+ * - `temp:` — ephemeral state a consumer prunes on logout / session end.
+ *
+ * The scope is a prefix on the conversation id (`"<scope>__<id>"`). The `__`
+ * separator is path-safe (unlike `:`, which the identifier guard rejects), so a
+ * host can partition sessions by scope over the native transcript store.
+ *
+ * @public
+ */
+/** M3 #62 — session state scope. */
+type SessionScope = "app" | "user" | "temp";
+/** M3 #62 — build a scope-namespaced conversation id (`"<scope>__<id>"`). */
+declare function scopedConversationId(scope: SessionScope, id: string): string;
+/** M3 #62 — the id prefix (`"<scope>__"`) used to match a scope's conversations. */
+declare function sessionScopePrefix(scope: SessionScope): string;
+
+/**
+ * `createSquad` — a sequential team of agents.
+ *
+ * A Squad is a thin convenience that COMPOSES `Workflow` + `agentStep` — it
+ * adds NO new orchestration logic. Agents run in array order; each agent's
+ * output is threaded into the next agent's prompt. For branching/parallel/
+ * foreach teams use `Workflow` directly; for manager→worker delegation use
+ * subagents or `@theokit/sdk-handoff`.
+ *
+ * Mirrors the `createAgentFactory` composition-LEGO precedent (a factory over
+ * existing primitives, not a new subsystem).
+ *
+ * @public
+ */
+
+/**
+ * Options for {@link createSquad}.
+ *
+ * @public
+ */
+interface SquadOptions {
+    /**
+     * Agents run in array order (sequential pipeline). Must be non-empty.
+     *
+     * M81 — accepts an `AgentDefinition` (plain data) as well as a constructed `SDKAgent`. Building a
+     * team used to force the caller to materialize every member by hand first: resolve the credential,
+     * assemble the options, call `Agent.create`, await. That is precisely the work this milestone moves
+     * into the framework elsewhere, so leaving it here would be inconsistent — and with
+     * `discoverSubagents` now public (`@theokit/sdk/subagents-loader`), the data that describes an
+     * agent is reachable, which closes the loop: discover → build a team, with no manual step between.
+     *
+     * Mixing both forms in one list is supported on purpose: a real team usually has members from
+     * different origins.
+     */
+    agents: ReadonlyArray<SDKAgent | AgentDefinition>;
+    /**
+     * Orchestration process. Only `"sequential"` is supported (the default).
+     * `"hierarchical"` is accepted by the type but rejected at runtime with
+     * guidance — use subagents or `@theokit/sdk-handoff` for manager→worker
+     * delegation (those already cover it).
+     */
+    process?: "sequential" | "hierarchical";
+    /** Optional squad name (surfaced on the underlying workflow). Default `"squad"`. */
+    name?: string;
+}
+/**
+ * Result of a {@link Squad.run}. `result` is the final (last agent's) output;
+ * `steps` is the per-agent trace from the underlying workflow run.
+ *
+ * @public
+ */
+interface SquadRun {
+    readonly result: unknown;
+    readonly status: "running" | "completed" | "failed" | "suspended" | "cancelled";
+    readonly steps: ReadonlyArray<StepResult>;
+}
+/**
+ * A sequential agent team produced by {@link createSquad}.
+ *
+ * @public
+ */
+interface Squad {
+    /** Run the team over `input`, threading each agent's output to the next. */
+    run(input: unknown): Promise<SquadRun>;
+}
+/** SE36 — `Squad.create` replaces `createSquad` (ADR 0015). Merges with the `Squad` interface. @public */
+declare class Squad {
+    private constructor();
+    static create(options: SquadOptions): Squad;
+}
+
+/**
+ * Owner: `internal/task/` (4 of 5 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * Public type contract for the Task observability registry (ADRs D361-D374).
+ *
+ * Tasks are an opt-in observability layer over async work in the SDK
+ * (`Agent.send`, `Agent.batch`, `Workflow.run`, `Cron` fires). They have
+ * a closed 5-state lifecycle (D362), discriminated events (D366), and a
+ * pluggable store (D364). The `Task` facade in `task.ts` is the public
+ * surface; consumers import these types from `@theokit/sdk`.
+ *
+ * @public
+ */
+/**
+ * Closed enum of the 5 lifecycle states (D362).
+ *
+ * Transitions are acyclic:
+ *   queued → running → (finished | error | cancelled)
+ *   queued → cancelled (direct, no run started)
+ */
+type TaskState = "queued" | "running" | "finished" | "error" | "cancelled";
+/** Discriminator of the runtime that produced a task (D374). */
+type TaskKind = "run" | "batch" | "workflow" | "cron" | "custom";
+/** Discriminated union of task lifecycle events (D366). */
+type TaskEvent = {
+    readonly type: "submitted";
+    readonly taskId: string;
+    readonly kind: TaskKind;
+    readonly submittedAt: number;
+    readonly meta?: Record<string, unknown>;
+    /** D372 — flag set on the first yielded event when the ring buffer was at cap. */
+    readonly truncated?: boolean;
+} | {
+    readonly type: "started";
+    readonly taskId: string;
+    readonly startedAt: number;
+} | {
+    readonly type: "progress";
+    readonly taskId: string;
+    readonly at: number;
+    readonly payload: unknown;
+} | {
+    readonly type: "finished";
+    readonly taskId: string;
+    readonly finishedAt: number;
+    readonly result: unknown;
+} | {
+    readonly type: "errored";
+    readonly taskId: string;
+    readonly erroredAt: number;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+} | {
+    readonly type: "cancelled";
+    readonly taskId: string;
+    readonly cancelledAt: number;
+    readonly reason?: string;
+};
+/** Public read-only view of a task entry in the registry. */
+interface TaskHandle {
+    readonly id: string;
+    readonly kind: TaskKind;
+    readonly state: TaskState;
+    readonly submittedAt: number;
+    readonly startedAt?: number;
+    readonly finishedAt?: number;
+    readonly cancelledAt?: number;
+    readonly erroredAt?: number;
+    readonly result?: unknown;
+    readonly error?: {
+        readonly code: string;
+        readonly message: string;
+    };
+    readonly meta?: Record<string, unknown>;
+    /**
+     * EC-7 — cross-process best-effort cancel flag. Set by CLI
+     * `theokit tasks cancel` via JsonFileTaskStore. The owning process
+     * polls at checkpoints and honors via AbortController. Always
+     * `undefined` for in-process cancel paths (which go directly through
+     * AbortController).
+     */
+    readonly cancelRequested?: boolean;
+    /**
+     * Why the task was cancelled, when whoever cancelled it said. Free text, written alongside
+     * `cancelledAt` for a `queued` task and alongside `cancelRequested` for a `running` one.
+     *
+     * Absent when no reason was given — an empty string is not a reason, and a default like
+     * "cancelled" would put words in the operator's mouth. `theokit tasks cancel --reason` is what
+     * writes it (#351); nothing in the runtime reads it, because it exists for the human reading the
+     * registry later.
+     */
+    readonly cancelReason?: string;
+}
+/** Query filter for `Task.list`. */
+interface TaskFilter {
+    readonly state?: TaskState | readonly TaskState[];
+    readonly kind?: TaskKind | readonly TaskKind[];
+    readonly submittedAfter?: number;
+    readonly submittedBefore?: number;
+    /**
+     * Defaults to 100. `JsonFileTaskStore` returns the newest matching tasks first and reads its
+     * whole directory to find them (256 files at a time); page past this limit with
+     * `submittedBefore` (#362).
+     */
+    readonly limit?: number;
+}
+/** Options for `Task.submit`. */
+interface TaskSubmitOptions {
+    /**
+     * Optional user-supplied ID. Must match grammar `^[a-z0-9][a-z0-9_-]*$`
+     * and MUST NOT start with the reserved prefixes `wf-` / `b-` / `cron-`
+     * (D368, EC-5). When omitted, `crypto.randomUUID()` is used.
+     */
+    readonly id?: string;
+    readonly meta?: Record<string, unknown>;
+    /**
+     * Optional caller-provided AbortSignal. If already aborted at submit
+     * time, the registry short-circuits to `cancelled` without acquiring
+     * a semaphore slot (EC-4).
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * SE2 — an opt-in {@link import("./run-events.js").RunEventSink}. The task's
+     * lifecycle is forwarded to it as typed `task_started` / `task_updated` /
+     * `task_completed` RunEvents, so a caller that spawned the task can observe it
+     * through the same `onRunEvent` channel as the rest of the run. Best-effort (a
+     * throwing sink never breaks the task). The dedicated `Task.subscribe(id)`
+     * channel is unaffected.
+     */
+    readonly onRunEvent?: RunEventSink$1;
+}
+/** Options shape for `TaskStore` factory (D364). */
+type TaskStoreOptions = {
+    readonly backend: "memory";
+} | {
+    readonly backend: "json";
+    readonly dir: string;
+};
+/** Result of `Task.cancel` (D365 — idempotent). */
+interface TaskCancelResult {
+    readonly cancelled: boolean;
+    readonly alreadyTerminal: boolean;
+}
+
+/**
+ * `Task` — observable async work registry (Adoption Roadmap gap #2,
+ * ADRs D361-D374).
+ *
+ * Static facade delegating to the in-process `TaskRegistry` singleton.
+ * The lifecycle of any task is the 5-state machine `queued | running |
+ * finished | error | cancelled` (D362). Wrapping `Agent.send` /
+ * `Agent.batch` / `Workflow.run` / `Cron` fires is opt-in via the
+ * `{ task: true }` option on each (D363).
+ *
+ * @public
+ */
+
+interface TaskWorkContext {
+    readonly signal: AbortSignal;
+    emit(payload: unknown): void;
+}
+/**
+ * The unit of work handed to {@link Task.submit}.
+ *
+ * It receives the context rather than raw arguments: `ctx.signal` aborts on cancel and should be
+ * observed by anything long-running, and `ctx.emit(payload)` produces a `progress` event for
+ * subscribers. May be synchronous — the return type allows a plain value as well as a promise.
+ *
+ * @public
+ */
+type TaskWorkFn<T> = (ctx: TaskWorkContext) => Promise<T> | T;
+/**
+ * Registry-level configuration. May only be applied BEFORE the first
+ * `Task.submit` of the process — see EC-13. Subsequent calls emit a
+ * single stderr line and become no-ops.
+ */
+interface TaskConfigureOptions {
+    readonly store?: TaskStoreOptions;
+    readonly maxConcurrent?: number;
+    readonly retentionMs?: number;
+}
+/**
+ * Static facade over the process-wide task registry — the observability layer for asynchronous
+ * work.
+ *
+ * Not instantiable: the constructor throws, and every operation is a static that delegates to one
+ * in-process singleton. Tasks are an OPT-IN wrapper. `Agent.send`, `Agent.batch`, `Workflow.run`
+ * and `Cron` fires only appear here when submitted with `{ task: true }`; work you submit yourself
+ * goes through `Task.submit`.
+ *
+ * Two ordering constraints bite in practice. `Task.configure` must run before the first `submit` of
+ * the process — a later call logs one line and is otherwise a no-op. And `Task.get` returning
+ * `undefined` does not mean the id never existed: retention evicts terminal tasks, so an id can go
+ * from known to unknown over time.
+ *
+ * @public
+ */
+declare class Task {
+    private constructor();
+    /**
+     * Configure the registry. **Must be called before the first `submit`**
+     * (EC-13). Available knobs: pluggable store (D364), concurrency cap
+     * (D369), and retention (D373).
+     */
+    static configure(opts: TaskConfigureOptions): void;
+    /**
+     * Submit a unit of asynchronous work to the registry.
+     *
+     * The `work` function receives `{ signal, emit }` — `signal` is the
+     * AbortSignal honored on cancel; `emit(payload)` produces a
+     * `progress` event observable via `Task.subscribe`.
+     *
+     * Returns a `TaskHandle` in `state: "queued"`. Subsequent state
+     * transitions are observable via `Task.subscribe(handle.id)` OR
+     * polled via `Task.get(handle.id)`.
+     *
+     * **Idempotency (D367):** submitting twice with the same `id` returns
+     * the existing handle without re-invoking work.
+     *
+     * **Grammar (D368):** user-supplied ids must match
+     * `^[a-z0-9][a-z0-9_-]*$` and must not start with reserved prefixes
+     * `wf-` / `b-` / `cron-`. Otherwise `InvalidTaskIdError` is thrown.
+     *
+     * **Pre-aborted signal (EC-4):** if `options.signal` is already
+     * aborted, the task short-circuits to `cancelled` without acquiring
+     * a semaphore slot and without invoking `work`.
+     */
+    static submit<T>(kind: TaskKind, work: TaskWorkFn<T>, options?: TaskSubmitOptions): Promise<TaskHandle>;
+    /** Returns matching handles, capped at `filter.limit ?? 100`. */
+    static list(filter?: TaskFilter): Promise<TaskHandle[]>;
+    /** Returns a single handle by id, or `undefined` if unknown / evicted. */
+    static get(id: string): Promise<TaskHandle | undefined>;
+    /**
+     * Idempotent cancel (D365). Returns:
+     *   - `{ cancelled: true, alreadyTerminal: false }` — transitioned
+     *     queued/running task to `cancelled`.
+     *   - `{ cancelled: false, alreadyTerminal: true }` — task already
+     *     terminal.
+     *   - `{ cancelled: false, alreadyTerminal: false }` — task unknown.
+     *
+     * Never throws.
+     */
+    static cancel(id: string, reason?: string): Promise<TaskCancelResult>;
+    /**
+     * Subscribe to a task's event stream. The returned `AsyncIterable<TaskEvent>`
+     * starts by replaying buffered events (ring buffer cap 64, D372) and
+     * then yields live events until a terminal event (finished / errored
+     * / cancelled) is emitted, at which point it closes automatically.
+     *
+     * Calling `.return()` on the iterator (or `break` in a `for await`)
+     * cleans up the subscriber callback (EC-10).
+     *
+     * Throws `TaskNotFoundError` if the id is unknown or has been evicted.
+     */
+    static subscribe(id: string): AsyncIterable<TaskEvent>;
+}
+
+/**
+ * Dynamic provider catalog loader (T10.1, ADR D447).
+ *
+ * Loads provider metadata from `provider-catalog.json` at runtime.
+ * Malformed entries are skipped with WARN (EC-1) — never crash.
+ *
+ * @internal
+ */
+
+interface ProviderCapabilities {
+    supportsToolUse: boolean;
+    supportsVision: boolean;
+    supportsStructuredOutput: boolean;
+    supportsStreaming: boolean;
+    supportsCacheControl: boolean;
+    maxContextTokens?: number;
+    maxOutputTokens?: number;
+}
+
+/**
+ * Owner: `internal/catalog/` (2 of 3 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * Account-level user info returned by `Theokit.me()`.
+ *
+ * @public
+ */
+interface SDKUser {
+    apiKeyName: string;
+    userEmail?: string;
+    createdAt: string;
+}
+/**
+ * Per-model parameter definition discovered from `Theokit.models.list()`.
+ *
+ * @public
+ */
+interface ModelParameterDefinition {
+    id: string;
+    displayName?: string;
+    values: Array<{
+        value: string;
+        displayName?: string;
+    }>;
+}
+/**
+ * Preset variant for a model — pre-filled parameter combinations.
+ *
+ * @public
+ */
+interface ModelVariant {
+    params: Array<{
+        id: string;
+        value: string;
+    }>;
+    displayName: string;
+    description?: string;
+    isDefault?: boolean;
+}
+/**
+ * Single model entry in the catalog.
+ *
+ * @public
+ */
+interface ModelListItem {
+    id: string;
+    /** Short, plain-text model name. Mirrors `displayName` for typical SDKs. */
+    name?: string;
+    displayName: string;
+    description?: string;
+    parameters?: ModelParameterDefinition[];
+    variants?: ModelVariant[];
+}
+/**
+ * Alias of {@link ModelListItem}, used where a model comes back from the Theokit platform rather
+ * than from a catalog listing.
+ *
+ * It is the SAME type, not a narrowed one — the alias exists so platform-facing signatures read in
+ * platform vocabulary alongside `SDKRepository` and `SDKUser`, and a value of either name is
+ * assignable to the other.
+ *
+ * @public
+ */
+type SDKModel = ModelListItem;
+/**
+ * GitHub repository connected to the team. Cloud-only.
+ *
+ * @public
+ */
+interface SDKRepository {
+    url: string;
+}
+
+/**
+ * Options shared by every `Theokit.*` request.
+ *
+ * @public
+ */
+interface TheokitRequestOptions {
+    /** Override the `THEOKIT_API_KEY` env var for this call. */
+    apiKey?: string;
+    /**
+     * Target a specific provider for catalog reads. When set to a provider
+     * with `authType: "none"` (e.g. `"ollama"`, `"lmstudio"`, `"llamacpp"`),
+     * `Theokit.models.list({ provider })` reads from the provider's local
+     * `/v1/models` endpoint instead of the TheoCloud catalog. ADR D184.
+     *
+     * @public
+     */
+    provider?: string;
+}
+/**
+ * Account-level and catalog reads. All methods accept an optional `apiKey`
+ * and otherwise fall back to the `THEOKIT_API_KEY` environment variable.
+ *
+ * @public
+ */
+declare class Theokit {
+    private constructor();
+    /**
+     * Return the user behind the current API key.
+     *
+     * @public
+     */
+    static me(options?: TheokitRequestOptions): Promise<SDKUser>;
+    /**
+     * Model catalog reads.
+     *
+     * @public
+     */
+    static readonly models: {
+        list: (options?: TheokitRequestOptions) => Promise<SDKModel[]>;
+        capabilities: (providerOrModelId: string) => ProviderCapabilities | undefined;
+    };
+    /**
+     * Connected GitHub repositories for the calling user's team. Cloud only.
+     *
+     * @public
+     */
+    static readonly repositories: {
+        list: (options?: TheokitRequestOptions) => Promise<SDKRepository[]>;
+    };
+    /**
+     * Provider catalog. Lists every provider known to the platform, including
+     * plugin-registered ones, with capability and availability metadata.
+     *
+     * @public
+     */
+    static readonly providers: {
+        list: (options?: TheokitRequestOptions) => Promise<SDKProvider[]>;
+    };
+    /**
+     * Local introspection of bundled SDK assets (ADR D201). Unlike the
+     * cloud-catalog `providers.list()` (which hits the TheoCloud HTTP API),
+     * `inspect.*` reads the SDK's own bundled registries — useful for
+     * tooling (e.g. `@theokit/cli`'s `theokit inspect`) that needs to know
+     * what's available WITHOUT a network round-trip.
+     *
+     * @public
+     */
+    static readonly inspect: {
+        builtinProviders: () => Array<{
+            readonly name: string;
+            readonly apiMode: string;
+            readonly authType: string;
+            readonly baseUrl: string;
+            readonly aliases?: ReadonlyArray<string>;
+            readonly envVars: ReadonlyArray<string>;
+        }>;
+        embeddingAdapters: () => Array<{
+            readonly id: string;
+            readonly transport: string;
+            readonly defaultModel: string;
+        }>;
+    };
+}
+
+/**
+ * Attach a blast-radius declaration to a tool, so the approval layer gates on what the tool DOES.
+ *
+ * Without this the only key available to a policy is the tool's NAME, which says nothing about the
+ * action, drifts the moment a tool is renamed, and cannot be reviewed by anyone who did not write
+ * it. `delete_namespace` and `list_pods` differ by a word.
+ *
+ * ## Why a wrapper rather than a field on the input schema
+ *
+ * `inputSchema` is what the MODEL sees. Blast radius is not for the model — it is for the approval
+ * layer — and putting it there would leak policy into the prompt and let a model-authored argument
+ * influence its own gate. The declaration rides alongside the tool instead, under a symbol so it
+ * cannot collide with a tool's own properties or be serialised into a prompt by accident.
+ *
+ * @public
+ */
+
+/**
+ * Symbol-keyed on purpose. THAT is what keeps the declaration out of a prompt: `Object.keys` and
+ * `JSON.stringify` both ignore symbol keys, so a tool serialised on its way to the model carries
+ * none of it. A string key would also risk colliding with a property the tool already has.
+ *
+ * Exported because the `@public` `WithBlastRadius<T>` below uses it as a COMPUTED
+ * KEY. A computed key is part of the type it keys, so the emitted declaration
+ * names this const — and a name the declaration file does not carry is a broken
+ * reference (#335). `Symbol.for` keeps it a registry symbol, so an exported
+ * binding does not weaken the property-hiding this comment describes: the value
+ * was always retrievable by any code that knows the string.
+ *
+ * @public
+ */
+declare const DECLARED: unique symbol;
+/**
+ * A tool that may carry a blast-radius declaration under {@link DECLARED}.
+ *
+ * The property is OPTIONAL in the type, so a plain tool is assignable to it and the type alone
+ * never proves a declaration was made. `describeAction` is what tells the two apart at runtime.
+ *
+ * @public
+ */
+type WithBlastRadius<T> = T & {
+    readonly [DECLARED]?: DeclaredAction;
+};
+/**
+ * Declare what a tool reaches, for the approval layer rather than for the model.
+ *
+ * This MUTATES `tool` — it defines a symbol-keyed property on the object it was given and hands
+ * the same reference back, so every existing reference to that tool sees the declaration too.
+ * Calling it again on the same tool replaces the previous declaration; the property is
+ * `configurable`, so re-declaring never throws.
+ *
+ * The declaration is invisible to `Object.keys` and `JSON.stringify` because the key is a symbol,
+ * which is what keeps it out of anything serialised into a prompt.
+ *
+ * @returns the same tool, with its action declared. The tool is not otherwise altered — the model
+ *   must see exactly what it saw before.
+ * @public
+ */
+declare function withBlastRadius<T extends object>(tool: T, action: DeclaredAction): WithBlastRadius<T>;
+/**
+ * Read back the action a tool declared, if any.
+ *
+ * This is how an approval layer obtains the `action` for `evaluateBlastRadius`. An `undefined`
+ * result means nobody has reviewed this tool's reach, which is a different fact from a tool that
+ * declared a narrow scope — decide what to do with the unreviewed case explicitly rather than
+ * treating it as harmless.
+ *
+ * @returns the declared action, or `undefined` when the tool never declared one — NOT an empty
+ *   action. "Never declared" and "declared as reaching nothing" are different facts, and collapsing
+ *   them is how an unreviewed tool passes as harmless.
+ * @public
+ */
+declare function describeAction(tool: object): DeclaredAction | undefined;
+
+/**
+ * SE7 — `ToolError`: thrown FROM a tool `handler` to report a failure back to
+ * the model with structured content (text and/or an image), not just a string.
+ * Kept in its own module (not `errors.ts`) so the error taxonomy file stays
+ * under the G8 LoC budget and this tool-shaped error lives next to the tool
+ * surface it serves.
+ *
+ * @public
+ */
+
+/**
+ * Thrown from a tool `handler` to surface a failure to the model. The SDK turns
+ * it into a `tool_result` with `isError: true` carrying the content. A plain
+ * `Error` thrown from a handler still works (its message becomes text);
+ * `ToolError` is the opt-in for a clean message or a multimodal error (e.g. an
+ * error screenshot).
+ *
+ * @public
+ */
+declare class ToolError extends TheokitAgentError {
+    readonly name: string;
+    /** The error content surfaced to the model: a string, or text/image blocks. */
+    readonly content: string | ToolResultContentBlock[];
+    constructor(content: string | ToolResultContentBlock[], options?: {
+        code?: string;
+        cause?: unknown;
+        metadata?: ErrorMetadata;
+    });
+}
+
+/**
+ * Owner: `src/` (1 of 1 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * Public types for ShareGPT trajectory export (ADR D139).
+ *
+ * Output format for fine-tuning datasets — consumed by HuggingFace, Axolotl,
+ * LLaMA-Factory, and most modern fine-tuning toolchains. Pure data shape;
+ * no runtime dependency.
+ *
+ * @public
+ */
+/**
+ * One ShareGPT message in a conversation. `from` identifies the role and
+ * `value` carries the textual content. Tool calls live in `tool_calls`
+ * (assistant-only) and tool results re-enter as `from: "tool"` entries.
+ *
+ * @public
+ */
+interface ShareGptMessage {
+    /** "human" for user, "gpt" for assistant, "tool" for tool result, "system" for system. */
+    from: "human" | "gpt" | "tool" | "system";
+    /** The message text. Empty string is valid (preserves turn boundary). */
+    value: string;
+    /** Optional tool calls — only emitted when `from === "gpt"`. */
+    tool_calls?: Array<{
+        name: string;
+        arguments: Record<string, unknown>;
+    }>;
+}
+/**
+ * One full ShareGPT-format trajectory — a single conversation plus
+ * metadata. JSONL-friendly (one trajectory per line when serialized).
+ *
+ * @public
+ */
+interface ShareGptTrajectory {
+    conversations: ShareGptMessage[];
+    metadata?: {
+        model?: string;
+        timestamp: string;
+        durationMs: number;
+        promptIndex: number;
+    };
+    /** `true` when the source `BatchResult.ok === true`. Always `true` in current shape. */
+    completed: boolean;
+    /** Token usage when surfaced by the underlying RunResult (provider-specific). */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+
+/**
+ * `toShareGptTrajectory` — opt-in BatchResult → ShareGPT converter (ADR D139).
+ *
+ * Pure transformation. Returns `null` for failed results so callers can
+ * filter via `.map(toShareGptTrajectory).filter(Boolean)`. Tool calls and
+ * tool results are preserved when an SDKMessage trace is provided; otherwise
+ * a minimal `human → gpt` trajectory is emitted from the final text.
+ *
+ * @public
+ */
+
+/**
+ * Convert a successful `BatchResult` to ShareGPT-format trajectory.
+ *
+ * Behavior:
+ * - `result.ok === false` → returns `null` (EC-11).
+ * - First entry is always `{from: "human", value: result.prompt}`.
+ * - When `options.messages` is supplied, each SDKMessage maps to one or
+ *   more ShareGPT entries (assistant text → gpt, tool_use → gpt + tool).
+ * - Without `options.messages`, fall back to a single `{from: "gpt"}`
+ *   entry carrying `result.result.result` (the final text) when present.
+ * - Malformed message entries are silently skipped (EC-F / EC-14).
+ *
+ * @public
+ */
+declare function toShareGptTrajectory(result: BatchResult, options?: {
+    messages?: SDKMessage[];
+    model?: string;
+}): ShareGptTrajectory | null;
+
+/**
+ * Decide what a project directory is allowed to switch on.
+ *
+ * A product that reads a repository has to answer this before it builds anything: are that
+ * repository's hooks honoured, are its MCP servers started, do its instructions enter the persona?
+ * The stakes are not configuration-shaped. A hook is arbitrary command execution on every tool
+ * call, and an MCP server is an external process SPAWNED while the agent is built — before any
+ * per-tool approval exists to refuse it. A product that gets this wrong grants local execution on
+ * first build, in a directory the user only meant to open.
+ *
+ * ## What this is, and what it deliberately is not
+ *
+ * The arithmetic is small: pick a level, derive one boolean per capability. The value is the
+ * INVARIANT — untrusted means EVERY declared capability is off, and `allows` is built FROM the
+ * declared list, so a product that adds a ninth capability cannot forget to gate it. That failure
+ * is invisible when it happens: the new capability simply works in a directory where it should not,
+ * and nothing reports anything.
+ *
+ * It does NOT decide what "trusted" means. Where the record lives, what the environment variable is
+ * called, whether a legacy alias is still honoured — all of that is the consumer's, because all of
+ * it is that product's vocabulary. The framework owns the shape of the answer and the guarantee
+ * that the answer covers everything declared.
+ *
+ * ## Why `source` is reported
+ *
+ * "Trusted because the operator recorded this directory" and "trusted because a blanket environment
+ * switch is on" are different facts. A surface that only shows `trusted` cannot warn about the
+ * second, which is the one that stays on across every directory the process ever opens.
+ *
+ * @public
+ */
+/**
+ * Whether a project directory may switch anything on.
+ *
+ * There is no middle level on purpose: `untrusted` means every declared capability is off, not
+ * "some are off". A product that wants a partial grant expresses it by declaring fewer capabilities
+ * for that call, not by inventing a third level here.
+ *
+ * @public
+ */
+type TrustLevel = "trusted" | "untrusted";
+/** Where the decision came from. @public */
+type TrustSource = "env" | "store" | "default";
+/**
+ * What the decision is made from: the capability vocabulary, a way to read the operator's record,
+ * and an optional blanket override.
+ *
+ * `capabilities` is load-bearing rather than descriptive — the returned `allows` is built from
+ * exactly this list, so a capability missing from it is a capability nothing gates.
+ *
+ * @public
+ */
+interface TrustPostureInput<K extends string> {
+    /**
+     * Every capability a repository could switch on. `allows` is built from exactly this list — the
+     * guarantee that nothing is left ungated.
+     */
+    readonly capabilities: readonly K[];
+    /**
+     * Whether the operator has recorded this directory as trusted. Called at most once, and not at
+     * all when `envOverride` already granted trust — it may touch the filesystem.
+     */
+    readonly isTrusted: () => boolean;
+    /**
+     * A blanket override from the consumer's own environment vocabulary. `true` grants trust;
+     * `false` and `undefined` both mean "the operator did not switch it on" — NOT "switched it off",
+     * because an unset variable must not override a trusted store.
+     */
+    readonly envOverride?: boolean;
+}
+/**
+ * The decision: the level, where it came from, and one boolean per declared capability.
+ *
+ * `allows` has exactly the keys of the `capabilities` list it was built from, so reading a
+ * capability the caller never declared is a type error rather than a silent `undefined` that a
+ * consumer would read as "not allowed".
+ *
+ * @public
+ */
+interface TrustPosture<K extends string> {
+    readonly level: TrustLevel;
+    readonly source: TrustSource;
+    /** One entry per declared capability. Every value is `false` when the level is untrusted. */
+    readonly allows: Readonly<Record<K, boolean>>;
+}
+/**
+ * Decide what a project directory is allowed to switch on.
+ *
+ * Precedence: `envOverride === true` grants trust and SHORT-CIRCUITS — `isTrusted` is not called at
+ * all, which matters because it may touch the filesystem. Otherwise `isTrusted()` is called exactly
+ * once and its answer decides. `envOverride === false` is not a denial: it falls through to the
+ * store like `undefined` does, so an unset or explicitly-off environment switch can never revoke a
+ * directory the operator recorded as trusted.
+ *
+ * Every entry of `allows` is `false` whenever the level is untrusted, and the entries are generated
+ * from `capabilities` rather than supplied per capability — that is what makes "nothing was left
+ * ungated" a property of the call instead of a habit of the caller.
+ *
+ * @public
+ */
+declare function resolveTrustPosture<K extends string>(input: TrustPostureInput<K>): TrustPosture<K>;
+
+/**
+ * Record what a build actually wired, as opposed to what configuration asked for.
+ *
+ * A product that reads a project directory decides, while building, which of that directory's
+ * entities it will honour: MCP servers, skills, hook events, commands. When a trust posture withholds
+ * them, the build simply proceeds with fewer — and every surface that later asks "what is loaded?"
+ * sees an empty list. Empty because nothing was configured and empty because everything was withheld
+ * are the same emptiness to the reader, and only one of them is something they can act on.
+ *
+ * ## Why this is not a re-read
+ *
+ * The obvious implementation of any "what is loaded?" listing is to read the configuration again.
+ * That is the defect this exists to prevent: a re-read cannot detect a disagreement between what
+ * config asked for and what the build did, because it IS the config. The two disagree exactly when
+ * something suppressed an entity, which is the case worth reporting.
+ *
+ * So this function is pure and parameterized. It performs no I/O, which is what makes "no second
+ * read" checkable rather than promised — the caller passes the values it handed to the builder, at
+ * the moment it handed them over, and what comes back is an observation of that moment.
+ *
+ * ## What is generic here, and what is not
+ *
+ * The RULE is generic: for each capability, active is the request when allowed and empty when not,
+ * and suppression is only claimed when something was actually removed. The VOCABULARY is not —
+ * which capabilities exist and what the entities are called belong to the product, and arrive as
+ * data.
+ *
+ * @public
+ */
+
+/** Raised when a recorded capability has no entry in the gate. @public */
+declare class UngatedCapabilityError extends TheokitAgentError {
+    readonly name = "UngatedCapabilityError";
+}
+/** What one capability asked for, and what it got. @public */
+interface WiredEntity {
+    /** The names actually handed to the builder. Empty when the capability was withheld. */
+    readonly active: readonly string[];
+    /**
+     * The names configuration ASKED for. Equal to `active` when nothing was withheld; the difference
+     * is exactly what the reader cannot otherwise see.
+     */
+    readonly requested: readonly string[];
+    /**
+     * True only when the gate is what emptied `active`.
+     *
+     * Deliberately false for a withheld capability that requested nothing: an untrusted directory with
+     * no skills and a trusted one with no skills are the same emptiness, and a flag that fires when
+     * nothing happened teaches the reader to ignore it.
+     */
+    readonly suppressedByTrust: boolean;
+}
+/**
+ * The two halves of the observation: the gate that was applied, and what was handed to the builder.
+ *
+ * `requested` drives the shape of the record — the result has exactly its keys — while `posture`
+ * only has to contain a gate for each of them. A posture that gates MORE than `requested` covers is
+ * fine and normal; a posture that gates FEWER is refused, see `recordWiring`.
+ *
+ * Pass the values at the moment they go to the builder. Re-deriving them from configuration
+ * afterwards would defeat the point: config is what was asked for, and the disagreement with what
+ * was wired is the only thing this records.
+ *
+ * @public
+ */
+interface WiringRecordInput<K extends string> {
+    /**
+     * The gate. Typically the output of `resolveTrustPosture`, which is what makes the name
+     * `suppressedByTrust` accurate rather than decorative — a posture is the only thing in this
+     * package that withholds a capability.
+     *
+     * It may gate MORE than `requested` covers: a posture also gates things that are not lists of
+     * names, like durable memory. Those are not entities and do not appear in the record.
+     */
+    readonly posture: {
+        readonly allows: Readonly<Record<string, boolean>>;
+    };
+    /** Per capability, the entity names the build was given. Drives which keys the record has. */
+    readonly requested: Readonly<Record<K, readonly string[]>>;
+}
+/**
+ * Record what a build actually wired, per capability.
+ *
+ * For each key of `requested`: `active` is a copy of the requested names when the posture allows
+ * that capability and an empty array when it does not, `requested` is always a copy of what was
+ * asked for, and `suppressedByTrust` is true only when the gate emptied a NON-EMPTY request. A
+ * withheld capability that requested nothing reports `false`, because a flag that fires when
+ * nothing happened is a flag readers learn to ignore.
+ *
+ * Pure and synchronous — it performs no I/O, which is what makes "this is not a second read of the
+ * configuration" checkable rather than promised.
+ *
+ * @returns one entry per key of `requested`, each a snapshot rather than a view of the caller's
+ *   arrays — the record is read long after the build, and aliasing would make it answer with what
+ *   the process holds now instead of with what was wired.
+ * @throws UngatedCapabilityError when a key of `requested` has no entry in `posture.allows`. Absent
+ *   is not read as denied: reporting a capability nobody gates as suppressed would send the reader
+ *   looking for a trust setting that does not exist.
+ * @public
+ */
+declare function recordWiring<K extends string>(input: WiringRecordInput<K>): Readonly<Record<K, WiredEntity>>;
+
+export { Agent, AgentBuilder, AgentDefinition, type AgentDescription, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type ApprovalDecision, type ApprovalInput, type ApprovalMode, type ApprovalOutcome, type ApprovalReason, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, type BlastRadiusDecision, type BlastRadiusInput, type BlastRadiusOutcome, type BlastRadiusReason, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, type BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, type CredentialInput, type CredentialReport, type CustomTool, type DeclaredAction, type DeclaredLayer, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DiagnosticsSink, type DreamingSweepOptions, type DreamingSweepResult, type EnvOptOut, type EnvReachabilityAudit, type EnvReachabilityInput, ErrorMetadata, EventBus, type EvictReason, GOAL_CONTINUATION_MARKER, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, GoalEvent, type GoalLoopAgent, GoalOptions, GoalResult, InlineSkill, JobQueue, type JobQueueOptions, JudgeCredentialError, type JudgeResult, type KeepReason, type KeptArtifact, LayerOrderError, type LayerValues, ListAgentsOptions, ListResult, ListRunsOptions, type LiveAgentRegistry, LiveSessionError, type LiveSessionReason, LocalOptions, McpServerConfig, Memory, MemoryId, type MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, type OTelSpan, type PermissionAction, PermissionEngine, type PermissionEngineOptions, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, type PermissionRule, Plugin, PluginsSettings, PreToolCallDecision, type Processor, Provider, type ProviderProfile, ProviderRoutingSettings, type ReadSessionMessagesOptions, type ReapPlan, type ReapPlanInput, type ReapableArtifact, type RetentionPolicy, RetentionPolicyError, Run, RunEventSink$1 as RunEventSink, RunResult, type SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, SOVEREIGN_ENV_KEYS, Security, type SecurityFloorInput, type SessionMessage, type SessionMessagePart, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, type SovereignEnvKey, Squad, type SquadOptions, type SquadRun, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, type TelemetryHandle, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, type ToolResultContentBlock, type TrustLevel, type TrustPosture, type TrustPostureInput, type TrustSource, UngatedCapabilityError, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, type WiredEntity, type WiringRecordInput, type WithBlastRadius, applyMode, applySecurityFloor, auditEnvReachability, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, decideApproval, describeAction, describeCredential, emitRunEvent, estimateTokens, evaluateBlastRadius, extractRawId, foldLayers, getPricingEntry, guardSessionDestruction, inferApiMode, isValidTaskId, loadProjectEnv, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, planReaping, preflightCheck, readSessionMessages, recordWiring, resolveTrustPosture, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, verifyLayerOrdering, withBlastRadius, withCwdMutex };