@theokit/sdk 0.0.0-compat-580-20260905204608

package/dist/agent-C3KO5LKm.d.cts

@@ -0,0 +1,1871 @@
+import { n as MemoryFact, k as MemoryAdapter, m as MemoryContext, E as SystemPromptSkillRef, C as ContextSettings, P as ProviderRoutingSettings, a as PluginsSettings, S as SDKAgent } from './sdk-agent-BOiKqOgL.cjs';
+import { M as ModelSelection, C as CustomTool, c as PermissionMode, a as McpServerConfig, P as Processor } from './run-CTAdRU3U.cjs';
+
+/**
+ * Owner: `src/` (1 of 2 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * `SessionRecord` — the native on-disk transcript record shape (SE40).
+ *
+ * The theokit session format IS the Claude Code record shape: a
+ * `uuid`/`parentUuid` DAG of records with structured
+ * `text`/`tool_use`/`tool_result`/`thinking` blocks. This is the contract the
+ * pluggable {@link SessionStore} seam operates over.
+ *
+ * DIP-correct home (SE46): the contract lives in the domain `types/` layer;
+ * the application-layer DAG core (`internal/persistence/session-transcript.ts`)
+ * re-exports it for back-compat while owning the record builders + reader.
+ *
+ * @public
+ */
+/** A content block inside {@link TranscriptMessage}. */
+type TranscriptBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "thinking";
+    thinking?: string;
+    signature?: string;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    type: "tool_result";
+    tool_use_id: string;
+    content: unknown;
+    is_error?: boolean;
+};
+/**
+ * The message body of a {@link SessionRecord}.
+ *
+ * **It is NOT called `SessionMessage`** — that name already exists in
+ * `internal/session/session-types.ts` with the shape `{role, text}`, incompatible with this one.
+ * Reusing an exported name for a new shape is
+ * precisely the silent break M91 cost two patches to undo.
+ *
+ * Parsing from disk stays **tolerant** (`readTranscript` skips a malformed line): what changes here
+ * is the **type**, not leniency — records written by earlier versions stay readable.
+ *
+ * @public
+ */
+interface TranscriptMessage {
+    role: "user" | "assistant";
+    content: TranscriptBlock[];
+    /**
+     * The three fields below appear **only** on the assistant record, and come from the writer
+     * (`SessionTranscript.appendAssistant`). Declared optional because the user record does not carry
+     * them — measured in the writer itself, not assumed.
+     */
+    id?: string;
+    type?: "message";
+    model?: string;
+}
+/**
+ * One transcript record — a single line of the session JSONL file, and the unit the pluggable
+ * `SessionStore` seam reads and writes.
+ *
+ * Records form a `uuid`/`parentUuid` DAG, not a flat list: `parentUuid` names the preceding record
+ * and is `null` at the root. Thread a session by following those links; a reader that assumes file
+ * order is linear will mis-thread one that branched.
+ *
+ * `message` is absent on `system` records — a compaction boundary carries `compactMetadata` instead —
+ * so it is optional even on records you would expect to be conversational, and `type` is what tells
+ * you which you are holding.
+ *
+ * Reading is deliberately tolerant: a malformed line is skipped rather than failing the whole read.
+ * Every record you receive is well-formed, but the file may have contained more than you got back,
+ * so this is not the type to use for an exact-count audit of what was written.
+ *
+ * @public
+ */
+interface SessionRecord {
+    type: "user" | "assistant" | "system";
+    uuid: string;
+    parentUuid: string | null;
+    sessionId: string;
+    timestamp: string;
+    isSidechain?: boolean;
+    userType?: string;
+    cwd?: string;
+    version?: string;
+    subtype?: string;
+    compactMetadata?: {
+        preTokens: number;
+        trigger: string;
+    };
+    /**
+     * The message body, in the shape the transcript writer actually writes.
+     *
+     * M94 — it was `Record<string, unknown>`, and the consumer recovered the type with a cast on every read.
+     * The shape **has always been fixed** (`SessionTranscript.appendToolResults` / `#push` produce
+     * it); it simply was not declared. It stays optional because system records carry no message.
+     */
+    message?: TranscriptMessage;
+}
+
+/**
+ * Owner: `internal/session/` (4 of 8 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * SE41 — the pluggable `SessionStore` seam over the NATIVE session transcript.
+ *
+ * A minimal, two-method port so an external store (Postgres / Redis / KV /
+ * durable object) can be the **primary store AND resume source** — the
+ * serverless (ephemeral FS) and multi-host / multi-pod use case that SE40
+ * dropped when it removed the `ConversationStorageAdapter`. This is deliberately
+ * NOT that removed ~10-method adapter: the seam is JUST record read/append over
+ * the native {@link SessionRecord} shape (no getMessages / getSessionMeta /
+ * delete / objective methods).
+ *
+ * The SDK ships a real default implementation, `FsSessionStore`, that reads and
+ * append-writes the native Claude-shaped `.jsonl` transcript — omitting
+ * `local.sessionStore` yields byte-identical current behavior (back-compat, zero
+ * consumer change). Injected via `local.sessionStore` for external stores.
+ *
+ * THIS SEAM DOES NOT HIDE THE STORAGE, AND IS NOT MEANT TO. A Repository
+ * abstracts a persistence model away; this one is defined in terms of the
+ * native one — the port speaks {@link SessionRecord}, "the exact SessionRecord
+ * the SDK writes", and the on-disk layout's path helpers (`encodeProjectDir`,
+ * `transcriptPath`, `transcriptRoot`) are published on purpose at
+ * `@theokit/sdk/persistence` so a consumer can locate a transcript file.
+ *
+ * That is the whole design and the reason the seam is two methods rather than
+ * ten: the format is the contract, and a store implements read/append over it.
+ * A consumer supplying `local.sessionStore` is NOT bound by those paths — they
+ * describe where the DEFAULT `FsSessionStore` puts files, not where an external
+ * store must.
+ *
+ * Consistency contract: `appendRecords` is append-only and ordering-preserving.
+ * The FS default serializes appends per agent with a cross-process file lock;
+ * external implementations own (and MUST document) their own concurrency
+ * guarantees for two hosts appending to the same `agentId`.
+ *
+ * @public
+ */
+
+/**
+ * The pluggable session-store seam. Exactly two methods over the native
+ * {@link SessionRecord} shape.
+ *
+ * @public
+ */
+interface SessionStore {
+    /**
+     * Return every persisted record for `agentId`, in append order. A session
+     * that was never written MUST resolve to `[]` (not throw) — a fresh agent has
+     * no history. The SDK reconstructs the resumable `LlmMessage[]` from these
+     * records via the native DAG reader, so the shape MUST be the exact
+     * {@link SessionRecord} the SDK writes.
+     *
+     * A store that cannot READ (e.g. the backing DB is unreachable on resume)
+     * MUST throw a typed error rather than silently returning `[]` — a silent
+     * empty read would masquerade as "no history" and drop the conversation.
+     */
+    readRecords(agentId: string): Promise<SessionRecord[]>;
+    /**
+     * Append `records` (the new-turn delta) to `agentId`'s session, append-only.
+     * MUST preserve order and MUST NOT drop or rewrite prior records — the native
+     * format is an append-only `parentUuid` DAG (compaction is a new-root
+     * `compact_boundary` record, still an append).
+     *
+     * Note on the write path: per-turn persistence is fire-and-forget so `send()`
+     * is never blocked by store I/O — an `appendRecords` rejection is logged to
+     * stderr, NOT thrown to the caller (best-effort write). An external store that
+     * must guarantee durability should make `appendRecords` resilient (retry /
+     * durable write) internally. This differs from {@link SessionStore.readRecords},
+     * which MUST throw on failure (a resume cannot proceed on a silent partial history).
+     */
+    appendRecords(agentId: string, records: readonly SessionRecord[]): Promise<void>;
+    /**
+     * Claim the single-writer lease for `agentId`, if this store has one. OPTIONAL.
+     *
+     * The SDK calls it when an agent starts and skips it when absent, so a two-method store keeps
+     * working unchanged — declaring it here does not require it, which is the whole reason it is
+     * optional. What declaring it DOES is make the capability discoverable: the SDK probed for this
+     * method through an `as unknown` cast against an interface that never mentioned it, so a
+     * third-party store author — the serverless / multi-pod case this port exists to serve — read a
+     * two-method interface, implemented two methods, and never learned the hook was there.
+     *
+     * CONTRACT, and the half that matters: a rejection whose `name` is `"SessionBusyError"` PROPAGATES
+     * to the caller, because another process holding the session is a decision the caller has to make
+     * (`exec` forks to a new id). Any other rejection is treated as "no lease available here" —
+     * logged, and the turn proceeds without single-writer protection, since the write is best-effort
+     * by contract anyway.
+     */
+    acquire?(agentId: string): Promise<void>;
+    /**
+     * Release the lease `acquire` claimed, if this store has one. OPTIONAL.
+     *
+     * Called on agent disposal. A rejection is not handled specially.
+     */
+    release?(agentId: string): Promise<void>;
+    /**
+     * Release store-level resources — a connection pool, a file handle. OPTIONAL.
+     *
+     * Called once, on agent disposal, after {@link SessionStore.release}.
+     */
+    dispose?(): Promise<void>;
+}
+
+/**
+ * A discovered skill's metadata. The skill BODY is never included — only the
+ * strict frontmatter fields plus the resolved `source` path.
+ *
+ * Public via `@theokit/sdk/skills`.
+ *
+ * @public
+ */
+interface Skill$1 {
+    name: string;
+    description: string;
+    /** Absolute path to the discovered `SKILL.md`. */
+    source: string;
+    category?: string;
+    dependencies?: string[];
+}
+
+/**
+ * M22 — `createSkill`: define a skill in TypeScript, without a `SKILL.md` file on disk.
+ *
+ * An inline skill is usable ALONGSIDE filesystem skills (`AgentOptions.skills.inline`), and points
+ * an agent at code-defined capabilities without a `.theokit/skills/<name>/SKILL.md`. Like file
+ * skills, its `name` + `description` surface in the `<skills>` system-prompt block; its
+ * `instructions` (the body) travel on the object for the consumer (the SDK injects name+description,
+ * not bodies — inline and file skills are symmetric there). Inline skills override file skills on a
+ * name conflict (mirrors the subagents-loader precedent).
+ */
+
+/** A code-defined skill (from {@link createSkill}) — a {@link Skill} plus its inline body. */
+interface InlineSkill extends Skill$1 {
+    /** The skill body/instructions (inline skills carry it here instead of a SKILL.md file). */
+    instructions: string;
+    /**
+     * SE21 — supporting documents bundled with the skill (filename → content),
+     * mirroring a filesystem skill's `references/` directory. Surfaced to the app
+     * via `agent.skills.get(name)`; not injected into the model prompt.
+     */
+    references?: Record<string, string>;
+}
+/** Spec accepted by {@link createSkill}. */
+interface CreateSkillSpec {
+    name: string;
+    description: string;
+    instructions: string;
+    category?: string;
+    dependencies?: string[];
+    /** SE21 — supporting documents (filename → content), like a filesystem skill's `references/`. */
+    references?: Record<string, string>;
+}
+/** SE36 — `Skill.create` replaces `createSkill` (ADR 0015). @public  *
+ * `Skill.create` returns an **`InlineSkill`**, not a `Skill`. The class is the namespace;
+ * the inline skill descriptor is the product.
+ */
+declare class Skill {
+    private constructor();
+    static create(spec: CreateSkillSpec): InlineSkill;
+}
+
+/**
+ * Owner: `internal/budget/tracker/` (1 of 1 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * `BudgetTracker` — runtime contract for budget/usage tracking in the
+ * agent loop (SDK 2.0 Phase 2 / T2.1 — ADR D1 interface inversion).
+ *
+ * This interface is the FOUNDATION for the eventual extraction of the
+ * Budget subsystem to `@theokit/sdk-budget`. The kernel depends on this
+ * contract (not on `UsageAccumulator` / `IterationBudget` concrete classes)
+ * so the implementation can move to a separate package without circular
+ * imports.
+ *
+ * DIP-correct home (SE46): the contract types live in the domain `types/`
+ * layer; the application-layer implementation
+ * (`internal/budget/tracker/budget-tracker.ts`) re-exports them for
+ * back-compat while owning the concrete trackers.
+ *
+ * @public — surface-level interface; impl is internal-but-replaceable.
+ */
+/** Single usage event recorded during one LLM call. */
+interface BudgetUsageEvent {
+    /** Token count for this event. */
+    readonly tokens: number;
+    /** Provider/model identifier (e.g., `"openai/gpt-4o-mini"`). */
+    readonly model: string;
+    /** Whether this is an input (prompt) or output (completion) measurement. */
+    readonly type: "input" | "output";
+    /** Optional ISO 8601 timestamp; defaults to now() if omitted. */
+    readonly at?: string;
+}
+/** Decision the tracker returns on each iteration / pre-flight check. */
+interface BudgetCheck {
+    /** Whether the agent loop is allowed to proceed. */
+    readonly allowed: boolean;
+    /**
+     * When `allowed` is false, names the reason in a stable, codemod-friendly
+     * form. Consumers map this to retry / surface to user / abort behavior.
+     */
+    readonly reason?: "budget_exceeded" | "iteration_limit" | "cost_limit" | "token_limit" | "custom";
+    /** Free-form details for logs / diagnostics. */
+    readonly detail?: string;
+}
+/** Aggregate snapshot of usage so far. */
+interface BudgetTotal {
+    /** Sum of all input + output tokens. */
+    readonly tokens: number;
+    /** USD cost when pricing data is available; `undefined` otherwise. */
+    readonly costUsd?: number;
+    /** Iteration count if the impl tracks it. */
+    readonly iterations?: number;
+}
+/**
+ * The kernel-facing contract. Implementations live OUTSIDE the agent loop
+ * (in `@theokit/sdk-budget` after Phase 2 / in `internal/budget/` until then).
+ *
+ * Implementations MUST be:
+ *   - **Synchronous** — every method returns a value, never a Promise.
+ *     `track()` is on the hot path (called on every iteration); async would
+ *     bloat the loop with floating promises and force every call site to
+ *     await.
+ *   - **Non-throwing in track()** — record-only semantics. Validation
+ *     failures bubble up via `check()` instead.
+ */
+interface BudgetTracker {
+    /** Record a single usage event. MUST be synchronous and non-throwing. */
+    track(event: BudgetUsageEvent): void;
+    /** Pre-flight check before the next iteration. */
+    check(): BudgetCheck;
+    /** Snapshot of accumulated totals (for telemetry / final reporting). */
+    getTotal(): BudgetTotal;
+    /**
+     * Advance the iteration counter by one. Called by the agent loop ONCE per
+     * completed turn (M1-1) so that trackers which gate on `maxIterations`
+     * (e.g. `createCounterBudgetTracker`) actually halt. OPTIONAL: trackers that
+     * only gate on tokens/USD omit it and the loop no-ops via optional chaining.
+     * MUST be synchronous and non-throwing.
+     */
+    nextIteration?(): void;
+}
+
+/**
+ * Owner: `internal/memory/storage/` (1 of 2 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * `MemoryProvider` — kernel-facing port for the memory subsystem
+ * (SDK 2.0 Phase 1 / T1.1 — Hexagonal Architecture / Ports & Adapters,
+ * SOLID Dependency Inversion).
+ *
+ * The agent loop kernel depends on THIS CONTRACT — not on the concrete
+ * `internal/memory/*` modules. Default adapter ships with `@theokit/sdk`
+ * (no-op for back-compat); rich impl ships in `@theokit/sdk-memory`.
+ * Consumers opt-in via `Agent.create({ memoryProvider: ... })`.
+ *
+ * DIP-correct home (SE46): the port + companion contract types live in the
+ * domain `types/` layer; the application-layer module
+ * (`internal/runtime/memory-glue/memory-provider.ts`) re-exports them for
+ * back-compat while the concrete providers live under `internal/`.
+ *
+ * Layered model (mirrors Budget):
+ *   - `MemoryAdapter` (in `types/memory-adapter.ts`) — LOW-LEVEL data port:
+ *     write / recall / delete primitives.
+ *   - `MemoryProvider` (THIS FILE) — HIGH-LEVEL lifecycle port: init,
+ *     tool factories, active memory pass, embedding runtime selection.
+ *
+ * @public — surface-level interface; impls are internal-but-replaceable.
+ */
+
+/**
+ * The agent identity a `MemoryProvider` is given — the whole of it.
+ *
+ * `buildTools` used to declare `agent: SDKAgent`, a 33-member interface, and the agent loop satisfied
+ * it with `{ agentId, model } as SDKAgent`. The cast is what made it compile, and it suppressed
+ * exactly the check that mattered: an implementation reaching for any of the other 31 members —
+ * `send()`, `fork()`, `dispose()` — gets `undefined is not a function` at runtime with no
+ * compile-time signal.
+ *
+ * Two fields is what the port actually offers, so two fields is what it declares. `SDKAgent`
+ * structurally satisfies this, so a caller holding a real agent still passes it, and TypeScript's
+ * bivariant method parameters mean an existing implementation typed `agent: SDKAgent` still compiles.
+ * What changes is that the fabricated ref no longer needs a cast to exist.
+ */
+interface MemoryProviderAgentRef {
+    readonly agentId: string;
+    readonly model: ModelSelection | undefined;
+}
+/** Result of `MemoryProvider.runActivePass(...)` — what the kernel injects into the LLM call. */
+interface ActiveMemoryPassResult {
+    /** Compressed memory facts to seed the LLM's context window for this turn. */
+    readonly facts: ReadonlyArray<MemoryFact>;
+    /** Optional system-prompt enrichment derived from the recalled facts. */
+    readonly systemPromptAdditions?: string;
+    /** Whether the active-memory circuit breaker tripped (degraded mode). */
+    readonly breakerTripped?: boolean;
+}
+/** Arguments for `MemoryProvider.runActivePass(...)`. */
+interface ActiveMemoryPassArgs {
+    /** The current user message — used as the recall query. */
+    readonly userMessage: string;
+    /** Conversation history (most recent first). */
+    readonly history: ReadonlyArray<{
+        role: "user" | "assistant";
+        content: string;
+    }>;
+    /** Agent identity for scope. */
+    readonly agentId: string;
+}
+/**
+ * Arguments for `MemoryProvider.recordSessionSummary(...)`
+ * (SDK 2.0 Phase 1 physical Stage 3 prep — iter 27).
+ *
+ * The "session summary" is the markdown that gets written to disk
+ * after a finished run + indexed under `corpus="sessions"`. This
+ * port method lets sdk-core's `post-run-lifecycle.ts` delegate the
+ * write to the provider instead of importing
+ * `internal/memory/storage/session-summary-writer.ts` directly.
+ *
+ * @public
+ */
+interface RecordSessionSummaryArgs {
+    /**
+     * Workspace cwd where on-disk artefacts live. Included on the args
+     * (not on a handle) because `recordSessionSummary` is STATELESS — it
+     * runs AFTER `runAgentLoop`'s `dispose()` releases the per-run handle.
+     * The kernel passes its own `workspaceCwd`; the impl uses it to
+     * compute the markdown file path.
+     */
+    readonly cwd: string;
+    /**
+     * The memory root the kernel resolved for this agent, from `memory.directory` or the default.
+     *
+     * Supplied by the kernel, never constructed by an implementor — which is why it is required
+     * rather than optional. An implementation that recomputed it from `cwd` would write the summary
+     * into a different directory than the one the rest of the subsystem uses (#463).
+     */
+    readonly memoryRoot: MemoryRoot;
+    /** Run id used as the filename key. */
+    readonly runId: string;
+    /** Agent identity for scope (foldering). */
+    readonly agentId: string;
+    /** Verbatim user message that started the run. */
+    readonly userText: string;
+    /** Final assistant text the run produced. */
+    readonly assistantText: string;
+    /** Final run status (only "finished" is recorded today). */
+    readonly status: "finished" | "error" | "cancelled";
+    /** Wall-clock ms at write time. */
+    readonly at: number;
+}
+/** Options for `MemoryProvider.init(...)`. */
+interface MemoryProviderInitOptions {
+    /** Workspace cwd where on-disk artefacts live (`.theokit/memory/...`). */
+    readonly cwd: string;
+    /** Embedding-provider id (`"openai" | "ollama" | ...`); when omitted the impl picks a default. */
+    readonly embeddingProviderId?: string;
+}
+/**
+ * Opaque handle returned by `init()`. Carried back into other methods so
+ * the impl can stash per-agent state (index, breaker, cache, …) without
+ * exposing it to the kernel.
+ */
+interface MemoryProviderHandle {
+    /** Adapter interface for direct read/write — matches existing `MemoryAdapter` shape. */
+    readonly adapter: MemoryAdapter;
+    /** Implementation-defined opaque field (private state pointer / index handle). */
+    readonly [implState: symbol]: unknown;
+}
+/**
+ * The kernel-facing contract. Implementations live OUTSIDE the agent loop
+ * (in `@theokit/sdk-memory` after Phase 1; in `internal/memory/` until then).
+ *
+ * Implementations MUST be:
+ *   - **Lazy** — `init()` may be called once per agent; subsequent calls
+ *     return the same handle (impl decides via cache). Heavy work
+ *     (loading the index, opening SQLite) deferred until first use.
+ *   - **Non-throwing on the hot path** — `runActivePass()` returns an
+ *     empty `facts: []` on degradation rather than throwing. Errors
+ *     surface via the breakerTripped flag + telemetry.
+ */
+interface MemoryProvider {
+    /** Construct or fetch the per-agent handle. Lazy + idempotent. */
+    init(opts: MemoryProviderInitOptions): Promise<MemoryProviderHandle>;
+    /** Build the LLM-facing tool catalog (memory_search, memory_get, …). */
+    buildTools(handle: MemoryProviderHandle, agent: MemoryProviderAgentRef): ReadonlyArray<CustomTool>;
+    /** Run the active-memory pre-LLM pass — recall + compress + format. */
+    runActivePass(handle: MemoryProviderHandle, args: ActiveMemoryPassArgs): Promise<ActiveMemoryPassResult>;
+    /**
+     * Optional post-run hook (SDK 2.0 Phase 1 physical Stage 1 — iter 19).
+     * Called by the agent loop AFTER a successful send so the impl can
+     * incorporate the session summary into its index (e.g., re-index the
+     * `sessions` corpus so the next recall sees it).
+     *
+     * Fire-and-forget at the call site; impl MUST be idempotent +
+     * non-throwing. Optional so existing impls (createNoopMemoryProvider,
+     * sdk-memory@0.1.0) keep working without modification.
+     *
+     * Mirrors the role of `LocalAgentMemory.syncIfReady()` in sdk-core's
+     * legacy memory path — exposing it via the port is the seam that
+     * unblocks moving LocalAgentMemory's logic out to sdk-memory.
+     */
+    sync?(handle: MemoryProviderHandle): Promise<void> | void;
+    /**
+     * Optional session-summary write hook (SDK 2.0 Phase 1 physical
+     * Stage 3 prep — iter 27, refined iter 28).
+     *
+     * Called by `post-run-lifecycle.ts` AFTER a finished run to persist
+     * the run's session-summary markdown under `corpus="sessions"`. When
+     * defined, the kernel delegates the write to the provider; when
+     * undefined, post-run-lifecycle falls back to the direct
+     * `writeSessionSummary` import (legacy path, until Stage 3 source
+     * move drops that import entirely).
+     *
+     * STATELESS — does NOT take a `MemoryProviderHandle` because post-run-
+     * lifecycle runs AFTER `runAgentLoop` disposed the per-run handle.
+     * `cwd` lives on `args` instead. Impls that need per-agent state can
+     * cache it via closure inside the provider factory.
+     *
+     * Impl MUST be non-throwing on the hot path. The kernel swallows
+     * any throw + emits a stderr warning.
+     *
+     * Optional so existing impls (createNoopMemoryProvider,
+     * createInMemoryMarkdownProvider) keep working without modification.
+     */
+    recordSessionSummary?(args: RecordSessionSummaryArgs): Promise<void> | void;
+    /** Release the handle (close index, flush caches). Idempotent + non-throwing. */
+    dispose(handle: MemoryProviderHandle): Promise<void> | void;
+}
+/**
+ * A directory that has been RESOLVED as a memory root, distinguished from a bare `cwd`.
+ *
+ * Structural rather than a `unique symbol` brand: a `unique symbol` is identity-based and the d.ts
+ * bundler inlines the declaration into each package that re-exports it, so `@theokit/sdk-memory`
+ * ended up with a `MemoryRoot` its own compiler considered incompatible with the SDK's, on values
+ * that were the same string. A structural tag refuses a bare `string` exactly as well and survives
+ * the package boundary, which is where this type has to work.
+ *
+ * G7 / DIP — defined HERE, in the domain types layer, rather than in
+ * `internal/memory/storage/memory-root.ts`. It was defined in the adapter and reached for from this
+ * file, which made the port depend on the adapter for a field of its own argument type; the runtime
+ * helpers (`resolveMemoryRoot`, `asMemoryRoot`) stay in the adapter and import it from here.
+ *
+ * @public
+ */
+type MemoryRoot = string & {
+    readonly __memoryRoot: "resolved";
+};
+
+/**
+ * Owner: `internal/providers/` (1 of 1 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * ProviderProfile + ApiMode + AuthType contract types (T3.1, ADR D105).
+ *
+ * Profile is **data-only** — no methods. Adding a provider is declaring an
+ * object literal; the Transport layer (D106) consumes `apiMode` to pick
+ * the HTTP dialect.
+ *
+ * SE45/SE46 — relocated from `internal/providers/types.ts` into `types/` so the
+ * public contract (embedded in the `Plugin` type) lives above the DIP boundary;
+ * `internal/providers/types.ts` re-exports these names for back-compat.
+ *
+ * @public
+ */
+type ApiMode = "chat_completions" | "anthropic_messages" | "responses_api" | "bedrock" | "bedrock_anthropic";
+type AuthType = "api_key" | "oauth_device_code" | "oauth_external" | "aws_sdk" | "aws_bearer" | "gcp_oauth" | "none";
+/**
+ * M41 (agent-builder provider framework) — the context a provider's `transform` receives per request. An
+ * object from day one so it can grow without breaking (M42 adds the resolved `credential`).
+ *
+ * @public
+ */
+interface ProviderTransformContext {
+    /** The bearer the router resolved for this request (env var, injected key, or an oauth access token). */
+    apiKey: string;
+}
+/**
+ * M41 — the one OPTIONAL behavior seam on a provider profile. It lets a provider own its per-request auth:
+ * `fetch` is the universal seam (a provider that returns its own fetch fully controls headers + refresh, for
+ * every transport that accepts a fetch); `headers` is a convenience merged over `extraHeaders` on transports
+ * that carry them (responses_api). A provider owns its per-request auth material plus transparent token
+ * refresh, expressed against theokit's transport model.
+ * Closes the gap where a `ProviderProfile` could only declare STATIC headers.
+ *
+ * @public
+ */
+interface ProviderTransform {
+    /**
+     * Dynamic per-request headers, merged OVER the profile's static `extraHeaders`, and spread AFTER the
+     * transport's base `authorization`/`content-type`. A provider that owns its auth MAY intentionally set
+     * `authorization` here to override the resolved bearer — but a stray `authorization`/`content-type` key
+     * will silently replace the base header, so return only the headers you mean to add.
+     */
+    headers?(ctx: ProviderTransformContext): Record<string, string>;
+    /** A fetch to use for this provider's requests (refresh-aware / fully provider-controlled). */
+    fetch?(ctx: ProviderTransformContext): typeof fetch;
+}
+/**
+ * A data-only declaration of an LLM provider: its name, HTTP dialect, auth style, base URL and
+ * fallback models. There is nothing to implement — the router selects the transport from `apiMode` —
+ * so any OpenAI- or Anthropic-compatible endpoint (Groq, Together, Fireworks, a private gateway)
+ * becomes a provider without new code.
+ *
+ * A profile does nothing by itself. Wrap it with `Provider.create(profile)` and pass the resulting
+ * plugin to `Agent.create({ plugins: [...] })`; from there you route to it with the `provider/model`
+ * id prefix or through `providers.routes`.
+ *
+ * `name` is the routing prefix and `aliases` adds alternatives to it. `envVars` lists the environment
+ * variables that may supply the credential, and `authType` says what kind of credential that is.
+ *
+ * Reach for `transform` only when static data genuinely is not enough — a provider that computes
+ * headers per request or refreshes its own token. Leaving it absent keeps the profile on the pure
+ * data path. If you do supply `headers`, note that they are spread AFTER the transport's own
+ * `authorization` and `content-type`, so returning either key replaces the base header rather than
+ * adding to it.
+ */
+interface ProviderProfile {
+    name: string;
+    apiMode: ApiMode;
+    aliases?: ReadonlyArray<string>;
+    displayName?: string;
+    description?: string;
+    signupUrl?: string;
+    envVars: ReadonlyArray<string>;
+    authType: AuthType;
+    baseUrl: string;
+    modelsUrl?: string;
+    hostname?: string;
+    fallbackModels: ReadonlyArray<string>;
+    extraHeaders?: Record<string, string>;
+    /**
+     * M45 — explicit chat-completions path override (data-only). Absent, the transport derives it: a baseUrl
+     * whose path already carries a version segment (`/v1`, `/v2beta`, …) gets `/chat/completions` appended;
+     * a host-only baseUrl keeps the legacy `/v1/chat/completions`. Set this for shapes neither rule expresses
+     * (e.g. Perplexity's unversioned `/chat/completions`).
+     */
+    chatCompletionsPath?: string;
+    bodyOverrides?: Record<string, unknown>;
+    /**
+     * M41 — the optional per-request behavior seam (dynamic headers + refresh-aware fetch). Absent ⇒ the profile
+     * is pure data and takes the static path byte-for-byte. See {@link ProviderTransform}.
+     */
+    transform?: ProviderTransform;
+    /**
+     * Opt-in leaked-dialect safe-parse (theokit#58 follow-up). When `true`, a chat_completions finish
+     * with ZERO native `tool_calls` has its assistant content scanned for the Hermes
+     * `<function=…></tool_call>` dialect and any recovered calls are surfaced as real `tool_calls`.
+     * Default off — only enable for routes/models known to leak (e.g. a qwen3-coder profile variant).
+     */
+    extractToolCallsFromContent?: boolean;
+    /**
+     * Opt-in encrypted-reasoning carry for `apiMode: "responses_api"` (usetheokit/theokit-sdk#383).
+     * When `true`, the request adds `include: ["reasoning.encrypted_content"]` and
+     * `reasoning.context: "all_turns"`, and the transport replays the ciphertext the provider returned
+     * so the model does not re-derive its chain of thought on every round of a turn.
+     *
+     * Default off, and deliberately per-profile rather than per-`apiMode`: `include` is a documented
+     * Responses-API field but `reasoning.context` is not, so a provider that validates strictly
+     * answers it with `400`. Enable it only for a backend measured to accept both — the builtin
+     * `openai-chatgpt` profile is one, because issue #383 captured OpenAI Codex sending exactly these
+     * fields to that endpoint. Ignored by every other `apiMode`.
+     */
+    encryptedReasoning?: boolean;
+}
+
+/**
+ * The fixed set of points a `"general"` plugin may attach to through `PluginContext.on`. A closed
+ * enum rather than an open string, so a plugin cannot register for a hook the loop never fires.
+ *
+ * What separates them is what the SDK does with the handler's return value, and that is the thing to
+ * settle before writing one:
+ *
+ * - `pre_tool_call` is the only VETO point. Return `{ block: true, message }` to stop the call; the
+ *   first handler that blocks wins and the remaining handlers are not consulted.
+ * - `transform_tool_result` and `transform_llm_output` are CHAINED. Each handler receives what the
+ *   previous one returned; `undefined` keeps the current value and anything else — `null` included —
+ *   replaces it.
+ * - `pre_user_send` returns `{ recalledContext }`, which the loop concatenates across handlers and
+ *   injects ahead of the user prompt.
+ * - Everything else (`post_tool_call`, `pre_llm_call`, `post_llm_call`, `on_session_start`,
+ *   `on_session_end`, `post_assistant_reply`) is fire-and-forget: the return value is DISCARDED. A
+ *   policy that needs to change a tool result belongs on `transform_tool_result` — put it on
+ *   `post_tool_call` and it quietly degrades to observation.
+ *
+ * Failure is asymmetric too. A fire-and-forget or transform handler that throws is caught, logged to
+ * stderr, and the run continues. A `pre_tool_call` handler that throws is NOT caught by the hook
+ * dispatcher, so its exception escapes into the tool-dispatch path — a permission-style handler
+ * should resolve its own errors to an explicit block rather than relying on that.
+ */
+type HookName = "pre_tool_call" | "post_tool_call" | "pre_llm_call" | "post_llm_call" | "on_session_start" | "on_session_end" | "transform_tool_result" | "transform_llm_output" | "pre_user_send" | "post_assistant_reply";
+/**
+ * What a `pre_tool_call` handler is given: the tool about to run, the arguments the model produced
+ * for it, and the identity of the run asking.
+ *
+ * `args` came from the model, not from a validated caller. A handler that gates on argument values
+ * must treat every field as untrusted and survive one that is missing or of the wrong type.
+ *
+ * `permissionMode` is the run's resolved mode — `SendOptions.permissionMode` falling back to
+ * `AgentOptions.permissionMode` — threaded here so a permission-style plugin can gate per run rather
+ * than at construction time. Absent means neither was set, and the plugin's own default applies;
+ * plugins that are not about permissions ignore it.
+ */
+interface PreToolCallContext {
+    name: string;
+    args: Record<string, unknown>;
+    agentId: string;
+    runId: string;
+    /**
+     * SE1 — the run's resolved `PermissionMode` (from `SendOptions.permissionMode`
+     * ?? `AgentOptions.permissionMode`), threaded so a permission-style plugin can
+     * gate per-run rather than at construction time. Absent ⇒ the plugin's own
+     * default applies. Ignored by non-permission plugins.
+     */
+    permissionMode?: PermissionMode;
+}
+/**
+ * The veto a `pre_tool_call` handler returns to stop a tool call. Returning `undefined` allows it —
+ * there is no approval value, and `block` is the literal `true`, so `{ block: false }` is not
+ * expressible and cannot be used to force a call through.
+ *
+ * The first blocking handler decides; later `pre_tool_call` handlers never run.
+ *
+ * `message` is not a log line. The loop turns the veto into a `tool_result` reading "Plugin blocked
+ * this tool call: <message>", deliberately NOT flagged as an error, so the model reads it and can
+ * choose another route instead of the run failing. Write it for the model: say what was refused and
+ * what it might do instead. It also reaches observability — as the `stderr` of a tool-completed event
+ * with exit code 126, and as the message on a `permission_denied` run event.
+ */
+interface PreToolCallDecision {
+    block: true;
+    message: string;
+}
+/** #65 — context for the `post_tool_call` hook (fired after a tool runs). @public */
+interface PostToolCallContext {
+    name: string;
+    args: Record<string, unknown>;
+    result: {
+        stdout: string;
+        stderr: string;
+        exitCode?: number | null;
+    };
+    agentId: string;
+    runId: string;
+}
+/** #65 — context for the `on_session_start` / `on_session_end` hooks. @public */
+interface SessionLifecycleContext {
+    agentId: string;
+    runId: string;
+}
+/** #65 — context for the `transform_tool_result` / `transform_llm_output` hooks. @public */
+interface TransformContext {
+    agentId: string;
+    runId: string;
+}
+/**
+ * M82 — one tool call of the turn, as seen by `transform_tool_result`. `id` is the correlation key
+ * back into the batch: it equals the `toolUseId` of the matching `tool_result` part.
+ *
+ * @public
+ */
+interface ToolCallSummary {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+/**
+ * M82 — context for `transform_tool_result`, the only tool-stage hook whose return value the SDK
+ * actually applies (`#runTransform` folds it; `#runFireAndForget` discards `post_tool_call`'s).
+ *
+ * Before M82 this seam knew only `{agentId, runId}`, so a hook could transform results but could not
+ * tell WHICH tool produced which one. A policy scoped to a tool name — the common case — therefore
+ * had to live on `post_tool_call`, whose return is discarded, and silently degraded to observation.
+ *
+ * `toolCalls` is PLURAL because the seam is batch-shaped: `dispatchTools` runs every tool call of the
+ * turn and the hook receives all results together. A singular `name` would have to lie in any
+ * multi-tool turn. Correlate with `LlmToolResultPart.toolUseId === ToolCallSummary.id`.
+ *
+ * Kept separate from {@link TransformContext} on purpose: that type is shared with
+ * `transform_llm_output`, which has no tool call at all, and an optional field there would be
+ * permanently `undefined` for half its consumers.
+ *
+ * @public
+ */
+interface ToolResultTransformContext extends TransformContext {
+    toolCalls: readonly ToolCallSummary[];
+}
+/**
+ * Context passed to `pre_user_send` hook handlers (ADR D145).
+ *
+ * @public
+ */
+interface PreUserSendContext {
+    prompt: string;
+    agentId: string;
+    runId: string;
+    /** Caller-supplied memory context, flowing through from `AgentOptions.memoryContext`. */
+    memoryContext?: MemoryContext;
+    /** Forwarded `AbortSignal` so adapter recall HTTP can be cancelled mid-flight (EC-H). */
+    signal?: AbortSignal;
+}
+/**
+ * Optional result returned by `pre_user_send` handlers. The agent loop
+ * concatenates `recalledContext` from all handlers and injects it as a
+ * `<memory-context>...</memory-context>` block before the user prompt.
+ *
+ * @public
+ */
+interface PreUserSendResult {
+    recalledContext?: string;
+}
+/**
+ * Context passed to `post_assistant_reply` hook handlers (ADR D145).
+ * Fire-and-forget — exceptions are caught and surfaced to stderr; the
+ * caller's `wait()` never blocks on this dispatch.
+ *
+ * @public
+ */
+interface PostAssistantReplyContext {
+    prompt: string;
+    reply: string;
+    agentId: string;
+    runId: string;
+    /**
+     * `true` when the run that produced `reply` called at least one tool (#358).
+     *
+     * A reply produced by a tool call is not safely replayable: re-serving the text hands a later
+     * caller the RESULT of a `write_file` / HTTP POST / payment without the side effect having
+     * happened. A semantic cache must skip storing such a reply, and before this field existed it
+     * had nothing to key on and assumed `false`.
+     *
+     * Derived from the run's replayed event stream, so it counts tool calls the run actually made,
+     * not tools the agent merely has.
+     */
+    usedTools: boolean;
+    memoryContext?: MemoryContext;
+}
+type HookHandler = (ctx: unknown) => unknown | Promise<unknown>;
+type CommandHandler = (args: Record<string, unknown>) => Promise<string> | string;
+interface CommandOptions {
+    description?: string;
+}
+/**
+ * Detaches a hook handler attached with {@link PluginContext.on}. Idempotent.
+ *
+ * @public
+ */
+type PluginHookDisposer = () => void;
+/**
+ * The registration surface passed to a `"general"` plugin's `register(ctx)`, and the plugin's only
+ * route into the agent. Outside production it is a sealed Proxy that throws when a plugin assigns a
+ * property of its own, so smuggling state onto the context fails loudly in development.
+ *
+ * `register` runs ONCE, when the plugin is registered — never per run. Anything the plugin wants to
+ * do during a turn has to be attached here as a hook; there is no later entry point. Each plugin gets
+ * its own context, so registrations stay attributable to the plugin that made them.
+ *
+ * Two things worth knowing before writing one. Commands registered here are consumed by CLI and bot
+ * wrappers only — the agent loop never dispatches them, so a plugin that ships nothing but commands
+ * has no effect on a programmatic run. And `on` drops a handler that is not a function, with a
+ * warning on stderr rather than an error at registration: the gentler failure, and the easier one to
+ * miss.
+ *
+ * `on` returns a {@link PluginHookDisposer}: calling it detaches that one handler, and calling it
+ * again is a no-op. A plugin that registers a hook per run and never detaches is the leak this
+ * exists to make fixable.
+ *
+ * @public
+ */
+interface PluginContext {
+    /** Register a custom tool. Equivalent to passing in `AgentOptions.tools`. */
+    registerTool(tool: CustomTool): void;
+    /** Register a slash-command-style handler. Consumed by CLI/bot wrappers; NOT used by the agent loop. */
+    registerCommand(name: string, handler: CommandHandler, opts?: CommandOptions): void;
+    /**
+     * Attach a hook handler. `pre_tool_call` supports veto via `PreToolCallDecision`.
+     *
+     * Returns a disposer that detaches THIS handler. Calling it twice is a no-op, and a handler the
+     * SDK refused (a non-function, which is warned and ignored) returns a disposer that does nothing —
+     * so the caller never has to branch on whether the registration took.
+     *
+     * It used to return `void`, which made this a one-way door: a plugin registered through
+     * `initialize()` had no removal path and its handlers ran for the life of the process. The one
+     * documented dynamic case — the ACP permission plugin, re-installed on every prompt — worked only
+     * because `#byName` keys the replacement, so re-registering the WHOLE plugin was the only way to
+     * detach one hook. Two observers in this package already return their own disposer
+     * (`FixtureRunBase.onDidChangeStatus`) or offer an explicit removal (`MessageBus.unregister`).
+     */
+    on(hook: HookName, handler: HookHandler): PluginHookDisposer;
+    /** Inject a user/system message into the next agent turn. v1 supports only `on_session_start` context. */
+    injectMessage(content: string, role?: "user" | "system"): void;
+}
+interface BasePlugin {
+    name: string;
+    version: string;
+}
+/**
+ * Memory provider factory shape (ADR D141). Returns a `MemoryAdapter`
+ * (sync) or a Promise resolving to one (lazy HTTP probe / config load).
+ *
+ * Adapters live in `@theokit-memory-*` packages; the SDK never imports
+ * them. Factory rejection is caught by the plugin manager and surfaced
+ * as `ConfigurationError(code: "plugin_factory_failed")` (EC-F) — never
+ * an unhandled rejection.
+ *
+ * PUBLIC, deliberately (#335). This type is the shape a consumer must satisfy
+ * to write a memory plugin: it is named by the PUBLIC `Plugin` union below, in
+ * the `createProvider` position. It used to carry the internal-visibility JSDoc
+ * tag, which made `stripInternal` delete the declaration while the union went
+ * on referencing it — so the published `.d.ts` named a type it did not declare.
+ * Invisible under `skipLibCheck`, and an `error`-typed graph for any consumer
+ * running type-aware lint. A type reachable from a public signature is public
+ * whatever the tag says; the tag was the thing that was wrong.
+ *
+ * Do NOT write that tag's literal spelling anywhere in this comment. It is
+ * matched as text, so a JSDoc block that merely MENTIONS it is stripped exactly
+ * as if it had declared it — which is how the first attempt at this fix failed,
+ * with a build error naming a symbol whose own explanation had re-hidden it.
+ */
+type MemoryProviderFactory = (cwd: string) => MemoryAdapter | Promise<MemoryAdapter>;
+type Plugin = (BasePlugin & {
+    kind: "general";
+    register: (ctx: PluginContext) => void | Promise<void>;
+}) | (BasePlugin & {
+    kind: "model-provider";
+    profile: ProviderProfile;
+}) | (BasePlugin & {
+    kind: "memory";
+    createProvider: MemoryProviderFactory;
+});
+
+/**
+ * Which on-disk settings layers a local agent loads.
+ *
+ * @public
+ */
+type SettingSource = "project" | "user" | "team" | "mdm" | "plugins" | "all";
+/**
+ * A foreign configuration dialect this SDK can read.
+ *
+ * A DIFFERENT axis from {@link SettingSource}, and collapsing the two would be wrong: that one is
+ * about SCOPE (user vs project, and the trust posture behind it), this one about which product's
+ * format a project wants imported. A project can legitimately want project scope with `.theokit/`
+ * only — which is now the default.
+ *
+ * @public
+ */
+type CompatSource = "claude-code" | CompatSourceAdapter;
+/**
+ * A surface a foreign configuration source may be admitted to.
+ *
+ * They are named separately because they carry very different risk. A skill is TEXT that enters the
+ * system prompt; a subagent is a definition; a plugin is CODE LOADING; a hook is COMMAND EXECUTION.
+ * Reusing the skills you already wrote for another product is a reasonable thing to want, and it is
+ * not a reason to hand that product's directory the right to run commands.
+ *
+ * @public
+ */
+type CompatSurface = "hooks" | "plugins" | "skills" | "subagents";
+/**
+ * A foreign source admitted to named surfaces only.
+ *
+ * ```ts
+ * local: { compatSources: [{ kind: "claude-code", import: ["skills", "subagents"] }] }
+ * ```
+ *
+ * `import` is not optional in spirit even though it is in the type: an adapter that omits it
+ * imports NOTHING. That is deliberate and it is the fail-closed rule this whole option exists to
+ * serve — a typo in a surface name must narrow access, never widen it.
+ *
+ * The bare `"claude-code"` string keeps meaning every surface. It is what `5.0.0-next.1` published,
+ * and silently narrowing it would turn a working opt-in into a no-op that says nothing — which is
+ * the defect usetheokit/theokit-sdk#524 reports, one level up.
+ *
+ * @public
+ */
+interface CompatSourceAdapter {
+    readonly kind: "claude-code";
+    readonly import?: readonly CompatSurface[];
+}
+/**
+ * A tool the SDK declares to the model on its own initiative — not one the consumer passed in
+ * {@link AgentOptions.tools}, and not one an MCP server exposed.
+ *
+ * These three names are also the ones the SDK reserves: a custom tool may not claim them. Listing
+ * one in {@link AgentOptions.withheldBuiltinTools} both stops it being declared and releases the
+ * name, because nothing of the SDK's is occupying it any more.
+ *
+ * Named for usetheokit/theokit-sdk#381, which is the report that the catalog had no opt-out.
+ *
+ * @public
+ */
+type BuiltinToolName = "shell" | "memory_search" | "memory_get";
+/**
+ * Local agent configuration.
+ *
+ * TWO THINGS A LOCAL AGENT DOES BY DEFAULT, both reported as surprises (#338):
+ *
+ * 1. **A `shell` tool is always registered**, including when you pass `tools: []`. Every local
+ *    agent can therefore read any file reachable from {@link LocalOptions.cwd}. One report describes
+ *    an evaluation invalidated this way: the working directory held the benchmark's answer key, and
+ *    two transcripts show the model citing it. Deny it explicitly if that matters —
+ *    `{ tool: "shell", action: "deny" }` on a {@link PermissionEngine} rule is terminal under every
+ *    permission mode, including `bypass`. A deny rule still leaves the tool in the advertised
+ *    catalog, so the model may attempt it and be refused; to keep it out of the catalog entirely,
+ *    pass `withheldBuiltinTools: ["shell"]` on {@link AgentOptions} (usetheokit/theokit-sdk#381).
+ *
+ * 2. **Finished runs write a transcript to disk**, at `.theokit/memory/sessions/<runId>.md` under
+ *    the workspace `cwd`, with the full prompt and reply. This happens with no `memory` config and
+ *    with `settingSources: []` — it is what `memory_search({ corpus: "sessions" })` reads. Opt out
+ *    with `memory: { enabled: false }`, which suppresses the write entirely
+ *    (usetheokit/theokit-sdk#382). Leaving `memory`
+ *    unset still writes, so if the workspace is a git repository, add `.theokit/` to `.gitignore`:
+ *    one report describes a transcript reaching a public repo before it was noticed.
+ *
+ * @public
+ */
+interface LocalOptions {
+    /**
+     * Workspace root(s). Also the reach of the always-present `shell` tool — see the note on
+     * {@link LocalOptions}, and the transcript written under `.theokit/memory/sessions/` here.
+     */
+    cwd?: string | string[];
+    settingSources?: SettingSource[];
+    /**
+     * Foreign configuration dialects to import. Default: none — `.theokit/` only.
+     *
+     * `.claude/` used to be read unconditionally across hooks, plugins, skills and subagents, so a
+     * repository that merely had Claude Code set up had its hooks executed, its skills folded into
+     * the system prompt and its subagents registered, having configured nothing for this SDK
+     * (usetheokit/theokit-sdk#524). One consequence was every turn being denied, because those hook
+     * commands are written against a runtime that defines `$CLAUDE_PROJECT_DIR` and this one did not
+     * (#522).
+     *
+     * A trust gate answers "do I trust the code in this directory?". That is a different question
+     * from "do I want another product's configuration imported into this one?", and they come apart
+     * in the ordinary case: a repository you trust completely is exactly where `.claude/` is
+     * populated — for a different tool, by a different contract, often by a teammate who never heard
+     * of this SDK.
+     *
+     * Listing a dialect is all-or-nothing for that dialect, and restores exactly the previous
+     * behaviour. On a name collision `.theokit/` wins: the native definition is the one the project
+     * wrote for this runtime.
+     */
+    compatSources?: CompatSource[];
+    sandboxOptions?: {
+        enabled: boolean;
+    };
+    /**
+     * Directory for the native Claude-shaped session transcript
+     * (`<sessionDir>/projects/<encoded-cwd>/<agentId>.jsonl`). Default `~/.theokit`.
+     * Set to `~/.claude` to write sessions the Claude Code CLI can `--continue`.
+     *
+     * **This is not the working directory** — that is {@link LocalOptions.cwd},
+     * four lines above. Only transcripts are written here.
+     *
+     * Introduced in #301 as the unambiguous name for what `baseDir` always meant.
+     */
+    sessionDir?: string;
+    /**
+     * @deprecated Renamed to {@link LocalOptions.sessionDir} (#301). Still honoured,
+     * and `sessionDir` wins when both are set.
+     *
+     * "Base directory" reads as the directory the agent works in, sitting in an
+     * interface whose `cwd` is the one that actually means that. Setting it to
+     * `"./"` — which is what the name invites — runs without error and writes
+     * `./projects/<encoded-cwd>/<agentId>.jsonl` into the caller's repository root.
+     * Nothing warns, because nothing is wrong from the code's point of view.
+     */
+    baseDir?: string;
+    /**
+     * SE41 — inject an external {@link import("./session-store.js").SessionStore}
+     * (Postgres / Redis / KV / durable object) as the PRIMARY session store and
+     * resume source. Omit for the default FS transcript store (`baseDir` above) —
+     * byte-identical to SE40. Use this for serverless (ephemeral FS) or multi-host /
+     * multi-pod deployments where a resumed agent must read its history from a shared
+     * store instead of local disk. The records stay the native Claude-shaped shape,
+     * so `--continue` interop is preserved (a store may also mirror to `~/.claude`).
+     */
+    sessionStore?: SessionStore;
+}
+/**
+ * Repo to clone into a cloud agent's VM.
+ *
+ * @public
+ */
+interface CloudRepo {
+    url: string;
+    startingRef?: string;
+    prUrl?: string;
+}
+/**
+ * Cloud execution environment.
+ *
+ * @public
+ */
+interface CloudEnv {
+    type: "cloud" | "pool" | "machine";
+    name?: string;
+}
+/**
+ * Cloud agent configuration.
+ *
+ * @public
+ */
+interface CloudOptions {
+    env?: CloudEnv;
+    repos?: CloudRepo[];
+    workOnCurrentBranch?: boolean;
+    autoCreatePR?: boolean;
+    skipReviewerRequest?: boolean;
+    /**
+     * Short-lived credentials scoped to the agent. Encrypted at rest, deleted
+     * with the agent. Names must not start with `THEOKIT_`.
+     */
+    envVars?: Record<string, string>;
+}
+/**
+ * Subagent definition. The parent agent spawns these via its Agent tool.
+ *
+ * @public
+ */
+interface AgentDefinition {
+    description: string;
+    prompt: string;
+    /**
+     * Absolute path to the `.md` this subagent was read from, when it came from disk.
+     *
+     * ABSENT for a subagent declared in code through {@link AgentOptions.subagents} — "you passed
+     * this one in" is a different fact from "read from disk", and one value for both would trade one
+     * silence for another.
+     *
+     * It exists so a listing can answer which root a subagent came from, which
+     * usetheokit/theokit-sdk#524 asks for by name: a consumer could not tell that an agent arrived
+     * from `.claude/agents/` rather than its own directory, and silent inheritance is what made that
+     * take a debugging session to notice. `HookCommand.sourcePath` and `Skill.source` already
+     * answered it for the other two surfaces.
+     */
+    source?: string;
+    model?: ModelSelection | "inherit";
+    mcpServers?: Array<string | Record<string, McpServerConfig>>;
+    /**
+     * Tool whitelist (M4-6). When set, the sub-agent may ONLY call tools whose
+     * canonical (post-repair, lowercase) name is in this list — any other tool
+     * call is vetoed at dispatch via the same `withToolWhitelist` enforcement
+     * forks use (NOT `PermissionEngine`). Absent/empty → unscoped (inherits the
+     * parent's full toolset). Apply with `withSubagentToolScope`.
+     */
+    tools?: string[];
+    /**
+     * Per-subagent shell sandbox toggle. When `true`, the spawned child runs with
+     * `local.sandboxOptions.enabled = true` (the SDK's boolean shell sandbox). Absent
+     * ⇒ inherit the parent's sandbox posture. The SDK has no granular sandbox *mode*
+     * (read-only / workspace-write / danger); a mode string in the disk frontmatter is
+     * a typed load error, not a silent boolean coercion. Reasoning effort is NOT a
+     * field here — it rides inside `model.params` (e.g. `[{ id: "thinking", value: "low" }]`).
+     */
+    sandbox?: boolean;
+}
+/**
+ * Public view of a recalled memory fact exposed to the system-prompt resolver.
+ *
+ * @public
+ */
+interface SystemPromptMemoryFact {
+    text: string;
+}
+/**
+ * Context passed to a {@link SystemPromptResolver}. Field order is a
+ * compatibility contract: new fields are appended, never reordered.
+ *
+ * @public
+ */
+interface SystemPromptContext {
+    agentId: string;
+    cwd: string | undefined;
+    model: ModelSelection | undefined;
+    skills: ReadonlyArray<SystemPromptSkillRef>;
+    userMessage: string;
+    /** Recalled durable facts when memory is enabled. Appended in v1.1. */
+    memory: ReadonlyArray<SystemPromptMemoryFact>;
+}
+/**
+ * Resolver function that produces the system prompt dynamically. Receives
+ * the {@link SystemPromptContext} and returns a string (or a Promise of one).
+ *
+ * The SDK does NOT impose a timeout on the resolver — wrap your own
+ * `Promise.race` if you call into slow resources. Errors propagate to the
+ * caller of `agent.send()`.
+ *
+ * @public
+ */
+type SystemPromptResolver = (ctx: SystemPromptContext) => string | Promise<string>;
+/**
+ * Skills configuration accepted by `Agent.create()` via
+ * {@link AgentOptions.skills}.
+ *
+ * Skills are discovered from `.theokit/skills/<name>/SKILL.md` when
+ * `local.settingSources` includes `"project"`.
+ *
+ * @public
+ */
+interface SkillsSettings {
+    /**
+     * Names of skills the parent agent may invoke. When omitted, every
+     * discovered skill is enabled.
+     */
+    enabled?: string[];
+    /**
+     * Whether the SDK auto-injects the loaded skill list (name + description) as a
+     * `<skills>` block in the LLM system prompt. Default `true`.
+     *
+     * Set to `false` when supplying a custom `systemPrompt` resolver that formats
+     * skills itself.
+     */
+    autoInject?: boolean;
+    /**
+     * M22 — discover skills from a CUSTOM directory (containing `<name>/SKILL.md`) instead of the
+     * default `<cwd>/.theokit/skills`. Absent ⇒ the default root.
+     */
+    skillsDir?: string;
+    /**
+     * M22 — code-defined skills (from `createSkill`) merged with the discovered ones. An inline skill
+     * overrides a discovered file skill of the same name.
+     */
+    inline?: InlineSkill[];
+}
+/**
+ * SE22 — context passed to a {@link SkillsResolver}. Mirrors
+ * {@link SystemPromptContext} MINUS `skills`: the resolver runs BEFORE skills
+ * are assembled, so the resolved list does not exist yet.
+ *
+ * @public
+ */
+interface SkillsResolverContext {
+    agentId: string;
+    /** Workspace cwd. `string | undefined` mirrors {@link SystemPromptContext}; a local agent always passes a concrete path. */
+    cwd: string | undefined;
+    model: ModelSelection | undefined;
+    userMessage: string;
+    /** Recalled durable facts when memory is enabled. */
+    memory: ReadonlyArray<SystemPromptMemoryFact>;
+}
+/**
+ * SE22 — a resolver that produces {@link SkillsSettings} per run from runtime
+ * context (e.g. the user's role). Mirrors the {@link SystemPromptResolver}
+ * pattern: evaluated per `send()` BEFORE skill assembly, so a cached
+ * `getOrCreate` agent re-resolves on every run.
+ *
+ * The SDK imposes NO timeout — wrap your own `Promise.race` for slow sources. A
+ * throwing resolver fails the run (no silent fallback — Rule 8). Cloud agents
+ * reject a function resolver (it can't run on PaaS); resolve to a static
+ * {@link SkillsSettings} object before `Agent.create()`.
+ *
+ * @public
+ */
+type SkillsResolver = (ctx: SkillsResolverContext) => SkillsSettings | Promise<SkillsSettings>;
+/**
+ * Memory configuration accepted by `Agent.create()` via {@link AgentOptions.memory}.
+ *
+ * Persists durable facts under `.theokit/memory/<namespace>/<scope>-<userId>.json`.
+ *
+ * @public
+ */
+interface MemorySettings {
+    enabled: boolean;
+    namespace?: string;
+    userId?: string;
+    scope?: "agent" | "user" | "team";
+    storePath?: string;
+    /**
+     * Where this agent's memory lives. Default `<cwd>/.theokit/memory`.
+     *
+     * Must be an absolute path or start with `~/` — a relative value is refused rather than
+     * resolved, because the two plausible bases put the store in two different places.
+     *
+     * Point it at `~/.claude/projects/<encoded-cwd>/memory` to WRITE where the Claude Code CLI
+     * reads. That store is READ unconditionally either way, so setting this is only needed to
+     * share the writes.
+     */
+    directory?: string;
+    /**
+     * Whether the SDK auto-injects recalled facts as a `<memory>` block in the
+     * LLM system prompt. Default `true`.
+     */
+    autoInject?: boolean;
+    /**
+     * Index + tools configuration (memory-system-peer-project-parity).
+     *
+     * When `tools !== false`, the SDK registers `memory_search` and
+     * `memory_get` with the LLM. Backed by SQLite + FTS5 (and sqlite-vec
+     * when an embedding provider is configured).
+     */
+    index?: {
+        /** Whether to register `memory_search` + `memory_get` tools. Default `true`. */
+        tools?: boolean;
+        /**
+         * Vector index backend (ADR D43). Default `"sqlite-vec"`. Set to
+         * `"lance"` to use `@lancedb/lancedb` (optional peer dep) for scale.
+         */
+        backend?: "sqlite-vec" | "lance";
+        /** Embedding provider config. When omitted, the index runs in FTS-only mode. */
+        embedding?: {
+            provider: "openai" | "mistral" | "openrouter" | "voyage" | "deepinfra";
+            model?: string;
+        };
+    };
+    /**
+     * Active Memory blocking recall (Phase 7). When `enabled: true`, runs
+     * before each `send()` and prepends an `<active-memory>` block.
+     */
+    activeRecall?: {
+        enabled?: boolean;
+        queryMode?: "message" | "recent" | "full";
+        timeoutMs?: number;
+        maxSummaryChars?: number;
+        persistTranscripts?: boolean;
+    };
+}
+/**
+ * Telemetry configuration for an agent. When `enabled: true`, the SDK emits
+ * OpenTelemetry spans for `agent.send`, `llm.call`, `tool.call`, and
+ * `memory.search`. See ADR D34.
+ *
+ * Privacy: content (prompts, responses, tool args) is OMITTED by default —
+ * only timing/counts/IDs are recorded. Opt in via `includeContent: true`
+ * to add prompt/response/args events to the spans (consumer's
+ * responsibility to sanitize PII).
+ *
+ * `@opentelemetry/api` is an OPTIONAL peer dependency — declared, so your package manager can
+ * tell you the version range, and not installed for you. Without it, telemetry is a NO-OP even
+ * when `enabled: true`: the tracer is loaded lazily inside a try/catch, so nothing throws and
+ * nothing is recorded. A run that reports no spans with `enabled: true` is almost always this,
+ * not a misconfigured collector.
+ *
+ * @public
+ */
+interface TelemetrySettings {
+    /** Master switch. Default `false`. */
+    enabled: boolean;
+    /** Whether to include prompts/responses/tool args as span events. Default `false`. */
+    includeContent?: boolean;
+    /** Exporter selection. Default `"console"`. Custom exporters are passed-through. */
+    exporter?: "console" | "otlp" | unknown;
+    /** Service name on emitted spans. Default `"theokit-sdk"`. */
+    serviceName?: string;
+    /**
+     * Auto-detect and register OTel exporters for installed observability
+     * libs (Langfuse, Sentry, PostHog) via `createRequire` feature-detect.
+     * Default `true`. See ADR D42.
+     */
+    autoDetect?: boolean;
+    /**
+     * Per-adapter opt-out. Lowercase names: `"langfuse" | "sentry" | "posthog"`.
+     * Default `[]`.
+     */
+    disable?: string[];
+}
+/**
+ * Top-level options accepted by `Agent.create()`.
+ *
+ * Pass either `local` or `cloud` to pick a runtime.
+ *
+ * @public
+ */
+interface AgentOptions {
+    /**
+     * The model to run. SE8 — accepts a bare-string id shorthand
+     * (`"openai/gpt-4o-mini"`, normalized to `{ id }`) OR a {@link ModelSelection}
+     * object (use the object form to pass `params`).
+     */
+    model?: string | ModelSelection;
+    /** Falls back to `THEOKIT_API_KEY`. */
+    apiKey?: string;
+    name?: string;
+    /**
+     * When `true`, `Agent.prompt` (and any helper that goes through `run.wait()`)
+     * rejects with `AgentRunError` instead of resolving with `{ status: 'error' }`.
+     * Cancelled runs (`status: 'cancelled'`) still resolve — cancel ≠ error.
+     * If `result.error` is undefined despite `status: 'error'` (malformed RunResult),
+     * the defensive guard resolves normally (no throw).
+     *
+     * Default `false` (backwards-compatible).
+     *
+     * @public
+     */
+    throwOnError?: boolean;
+    /**
+     * System prompt for the agent. Either a plain string or a resolver
+     * function that receives the {@link SystemPromptContext} and returns the
+     * prompt dynamically. Override per-call via {@link SendOptions.systemPrompt}.
+     *
+     * Subagents do NOT inherit this — they use {@link AgentDefinition.prompt}.
+     */
+    systemPrompt?: string | SystemPromptResolver;
+    local?: LocalOptions;
+    cloud?: CloudOptions;
+    mcpServers?: Record<string, McpServerConfig>;
+    /**
+     * M77 — how long an MCP client lives.
+     *
+     * `'run'` (DEFAULT, and the historical behaviour) spawns a client per `send` and drops it when the
+     * run ends. `'session'` pools clients per `(agentId, server, config)` and keeps them across turns,
+     * which keeps the MCP runtime alive across turns. Measured cost of the per-run path: 193 / 138 / 134 ms of spawn + handshake on
+     * every turn.
+     *
+     * Opt-in rather than default because it changes the FAILURE model: a server that dies mid-session
+     * becomes a reachable state. One-shot and cron runs gain nothing from pooling and would pay that
+     * risk, so they keep `'run'` unless they ask otherwise.
+     */
+    mcpLifecycle?: "run" | "session";
+    agents?: Record<string, AgentDefinition>;
+    agentId?: string;
+    /** Context manager configuration. See `agent.context`. */
+    context?: ContextSettings;
+    /** Provider routing configuration. See `agent.providers`. */
+    providers?: ProviderRoutingSettings;
+    /**
+     * Plugins for this agent, in one of two forms:
+     *
+     * - **Named-enable settings** — `{ enabled: ["name", ...] }`. Selects which
+     *   file-discovered plugin providers (under `.theokit/plugins/`) are active.
+     *   Plugin sources must also be active via `local.settingSources`.
+     * - **Code `Plugin` objects** — an array of `Plugin` instances, e.g.
+     *   `plugins: [Handoff.asPlugin({ ... })]`. These are registered directly by
+     *   the runtime (`extractCodePlugins`); no `settingSources` entry is needed.
+     *
+     * The two forms are mutually exclusive — pass one or the other.
+     */
+    plugins?: PluginsSettings | readonly Plugin[];
+    /**
+     * SE1 — the default permission mode for this agent's runs, threaded to a
+     * registered `PermissionPlugin`'s pre-tool gate. A per-send
+     * `SendOptions.permissionMode` overrides it. Absent ⇒ the plugin's own
+     * construction-time mode applies. Local runtime.
+     */
+    permissionMode?: PermissionMode;
+    /**
+     * Skills configuration. Either a static {@link SkillsSettings} object or —
+     * SE22 — a {@link SkillsResolver} evaluated per `send()` to pick skills from
+     * runtime context (e.g. user role). A cached agent re-resolves each run. The
+     * agent-scoped `agent.skills` handle reflects the STATIC/base config; the
+     * resolver drives the per-send `<skills>` block.
+     */
+    skills?: SkillsSettings | SkillsResolver;
+    /**
+     * SE24 — guardrail processors. `inputProcessors` run in order before the LLM
+     * (normalize / validate / block / rewrite the user message); `outputProcessors`
+     * run on the model's final text before it reaches the caller (redact / block).
+     * A processor that `abort()`s stops the run with a {@link RunResult.tripwire}
+     * (+ a `tripwire` run-event). Empty/absent ⇒ unchanged behavior. See
+     * {@link Processor}.
+     */
+    inputProcessors?: readonly Processor[];
+    outputProcessors?: readonly Processor[];
+    /** Memory configuration. Persists durable facts; auto-recalled on send. */
+    memory?: MemorySettings;
+    /**
+     * Inline custom tools. Local runtime only — cloud agents reject any non-empty
+     * `tools` array. Handlers are not persisted; pass them again on resume.
+     * See {@link CustomTool}.
+     */
+    tools?: CustomTool[];
+    /**
+     * Builtin tools this agent must NOT declare to the model. Absent or empty ⇒ every builtin the
+     * rest of the configuration would register is declared, exactly as before this option existed.
+     *
+     * WHY WITHHOLDING IS NOT THE SAME AS DENYING. A consumer that cannot allow `shell` — because it
+     * reaches outside their own sandbox scope — can already refuse the call in a `pre_tool_call` hook
+     * or with a {@link PermissionEngine} deny rule. That stops the execution and pays for the offer
+     * twice over: the schema rides in EVERY request of EVERY round (measured at 267 characters for
+     * `shell`, 1,462 for `memory_search` + `memory_get` together — usetheokit/theokit-sdk#381), and
+     * the model can spend a whole round discovering a refusal it had no way to anticipate. Declaring
+     * a tool that is guaranteed to be refused is the wrong shape; withholding removes it from the
+     * catalog, so the model is never offered what it cannot have.
+     *
+     * WITHHOLDING RELEASES THE NAME. `withheldBuiltinTools: ["shell"]` lets {@link AgentOptions.tools}
+     * declare a tool called `shell` without the `tool_reserved_name` error — the reservation exists to
+     * stop a collision with the SDK's own tool, and there is no longer one to collide with. Every
+     * builtin still declared stays reserved.
+     *
+     * This governs DECLARATION, not authorization. A withheld builtin is simply absent from the
+     * catalog: a model that invents the name anyway gets `Unknown tool <name>` (exit 127) rather than
+     * an execution, but nothing here evaluates a policy. Keep the deny rule if you need one that a
+     * per-send `tools` override cannot reopen.
+     *
+     * @public
+     */
+    withheldBuiltinTools?: readonly BuiltinToolName[];
+    /**
+     * SE37 — opt-in reasoning. When `true`, the agent gets a chain-of-thought
+     * preamble prepended to its system prompt AND the `think` reasoning tool
+     * auto-attached, turning a non-reasoning model into a reason -> act ->
+     * observe loop (same model; reuses the existing tool loop). Default `false` —
+     * byte-identical behaviour when unset. Inert (with a one-time warn) when a
+     * native reasoning model is configured (`model.params: [{ id: "thinking" }]`),
+     * so native and prompt-based reasoning never stack. See `ReasoningTools` in `@theokit/sdk-tools`.
+     */
+    reasoning?: boolean;
+    /**
+     * Telemetry (OpenTelemetry) configuration. Default disabled. See
+     * {@link TelemetrySettings} and ADR D34.
+     */
+    telemetry?: TelemetrySettings;
+    /**
+     * Arbitrary metadata bag for caller-supplied provenance. Currently used by
+     * the fork primitive (ADR D114) to tag `metadata.forkOrigin` and
+     * `metadata.parentAgentId` so memory writes downstream can be attributed.
+     *
+     * Not persisted to the agent registry — informational only at runtime.
+     *
+     * @public
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Default `MemoryContext` for third-party memory adapter plugins
+     * (ADR D141). When set, `pre_user_send` / `post_assistant_reply`
+     * hooks receive this context unless the caller overrides it. The
+     * `agent.memory` direct API also defaults to it.
+     *
+     * @public
+     */
+    memoryContext?: MemoryContext;
+    /**
+     * Maximum byte length of the `<memory-context>` block injected by
+     * `pre_user_send` adapter hooks (EC-A). Larger recalls are sliced
+     * with `…[truncated]`. Default 16_000 (~4k tokens). Set lower for
+     * cheaper turns; higher for longer-context models.
+     *
+     * @public
+     */
+    maxRecallContextBytes?: number;
+    /**
+     * Declarative handoff destinations (Adoption Roadmap #4; ADRs D214-D229).
+     * Each entry is either a raw `SDKAgent` (auto-wrapped with defaults) OR a
+     * `HandoffDescriptor` from `Handoff.create(target, opts?)`.
+     *
+     * Runtime injects synthetic `transfer_to_<receiver.name>` tools per
+     * destination (D214/D215). When the LLM invokes one, the receiver takes
+     * over the next turn (peer-to-peer, D217).
+     *
+     * @public
+     */
+    handoffs?: ReadonlyArray<SDKAgent | unknown>;
+    /**
+     * Maximum chain depth across handoffs per `agent.send()` call (D218).
+     * Default 5. Exceeding throws `HandoffLoopError`. Set to 0 to disable
+     * the handoff tools entirely (EC-8 / handoffs never fire).
+     *
+     * @public
+     */
+    maxHandoffDepth?: number;
+    /**
+     * Production-Readiness #6 — quota / abuse gates (ADRs D322-D323).
+     *
+     * `onBeforeCreate` fires BEFORE the agent is registered or persisted —
+     * throw to block creation. `onBeforeSend` fires BEFORE each `agent.send`
+     * (after `pre_user_send` adapter hooks, before any LLM call or storage
+     * write) — throw to block the send.
+     *
+     * Unlike `onTool*` (observation), these hooks are BLOCKERS — errors
+     * propagate as rejection on `Agent.create` / `agent.send`. Use them for
+     * per-user conversation caps, per-conversation message caps, abuse
+     * detection.
+     *
+     * @public
+     */
+    onBeforeCreate?: (event: {
+        conversationId: string;
+        userId?: string;
+    }) => Promise<void> | void;
+    /**
+     * Fires before each `agent.send`. `previousMessageCount` is the count of
+     * messages already persisted BEFORE the current send adds the user
+     * message. Throw to block.
+     *
+     * @public
+     */
+    onBeforeSend?: (event: {
+        conversationId: string;
+        previousMessageCount: number;
+    }) => Promise<void> | void;
+    /**
+     * Production-Readiness #4 — tool lifecycle hooks (ADRs D315-D317).
+     *
+     * `onToolStart` fires BEFORE the handler runs. `onToolEnd` fires after a
+     * successful handler return. `onToolError` fires when validation fails OR
+     * the handler throws — `event.error` is always an `Error` instance.
+     *
+     * Hook errors are SWALLOWED with a stderr warn (do not abort the run).
+     * The `callId` is unique per tool invocation and identical across the
+     * start/end (or start/error) pair, so consumers can correlate.
+     *
+     * Use cases: cost tracking, audit logs, per-tool retry/alerting,
+     * latency telemetry.
+     *
+     * @public
+     */
+    onToolStart?: (event: {
+        toolName: string;
+        args: unknown;
+        conversationId: string;
+        callId: string;
+    }) => void | Promise<void>;
+    /** Fires when a tool handler returns successfully. */
+    onToolEnd?: (event: {
+        toolName: string;
+        args: unknown;
+        result: unknown;
+        conversationId: string;
+        callId: string;
+        durationMs: number;
+    }) => void | Promise<void>;
+    /**
+     * Fires when a tool handler throws OR schema validation rejects the args.
+     * `event.error` is always an `Error` instance (D315/EC-6 — validation
+     * reasons are wrapped in `new Error(reason)`).
+     *
+     * `attempt` is always `1` in v1 (D317 — reserved for future retry policy).
+     */
+    onToolError?: (event: {
+        toolName: string;
+        args: unknown;
+        error: Error;
+        conversationId: string;
+        callId: string;
+        durationMs: number;
+        attempt: number;
+    }) => void | Promise<void>;
+    /**
+     * Pluggable budget/usage tracker (SDK 2.0 Phase 2 / T2.1 — ADR D1 interface
+     * inversion). When provided, the agent loop calls `tracker.track(...)`
+     * after each LLM completion and `tracker.check()` before each iteration.
+     *
+     * **Runtime enforcement is live.** Verified against the call graph on
+     * 2026-09-01: `internal/agent-loop/loop.ts:78-81` reads the tracker and
+     * gates the iteration through `evaluateBudgetGate`, `:110` calls
+     * `nextIteration()`, and `:390`/`:397` call `track(...)` per completion;
+     * the option reaches the loop from `AgentOptions` at
+     * `internal/local-agent/real-local-run.ts:342`.
+     *
+     * This paragraph previously said the opposite — "wired to the type surface
+     * only ... NOT runtime enforcement" — and it was wrong in the expensive stale-claim-ok: verbatim quote of the corrected text
+     * direction: a consumer reading the published `.d.ts` was told the SDK would
+     * not enforce their cost ceiling, so the rational response was to build a
+     * second control outside it, or to stop trusting the option.
+     *
+     * Default impls available today via `@theokit/sdk`:
+     *   - `createCounterBudgetTracker({ maxTokens, maxIterations })`
+     *
+     * Future: post-Phase-2, `@theokit/sdk-budget` ships a richer impl with
+     * USD pricing.
+     *
+     * @public
+     */
+    budgetTracker?: BudgetTracker;
+    /**
+     * Pluggable memory subsystem (SDK 2.0 Phase 1 / T1.3 — Hexagonal
+     * Architecture interface inversion). When provided, the agent loop
+     * calls `provider.init(...)` once per agent, surfaces tools from
+     * `provider.buildTools(...)` to the LLM, runs `provider.runActivePass(...)`
+     * pre-LLM to inject recalled facts, and `provider.dispose(...)` on
+     * Agent shutdown.
+     *
+     * **Runtime enforcement is live.** Verified against the call graph on
+     * 2026-09-01: `internal/agent-loop/loop-context-init.ts:95` calls
+     * `provider.init(...)`, `:129` surfaces `provider.buildTools(...)` to the
+     * model, `:166` runs `provider.runActivePass(...)`, and
+     * `internal/agent-loop/loop.ts:176`/`:204` call `sync` and `dispose`.
+     *
+     * This paragraph previously said the opposite — "wired to the type surface
+     * only ... NOT runtime enforcement". A stale "not implemented yet" note on a stale-claim-ok: verbatim quote of the corrected text
+     * `@public` symbol is worse than no note: it is believed, it survives the
+     * work it describes, and nothing in this repo compares such a claim against
+     * the call graph.
+     *
+     * Default impls available today via `@theokit/sdk`:
+     *   - `createNoopMemoryProvider()` — degenerate fallback / worked example
+     *
+     * Future: post-Phase-1, `@theokit/sdk-memory` ships a rich impl with
+     * LanceDB / embeddings / circuit breaker / active-memory cache.
+     *
+     * @public
+     */
+    memoryProvider?: MemoryProvider;
+}
+/**
+ * Metadata returned by `Agent.list()` and `Agent.get()`.
+ *
+ * @public
+ */
+type SDKAgentInfo = {
+    agentId: string;
+    name: string;
+    summary: string;
+    lastModified: number;
+    status?: "running" | "finished" | "error";
+    createdAt?: number;
+    archived?: boolean;
+} & ({
+    runtime?: undefined;
+} | {
+    runtime: "local";
+    cwd?: string;
+} | {
+    runtime: "cloud";
+    env?: CloudEnv;
+    repos?: string[];
+});
+/**
+ * theokit#123 — one tool of a registered agent, as a reflection surface sees it.
+ *
+ * A projection, not the `CustomTool` itself: the handler is an executable that cannot cross a
+ * process boundary and has no meaning to a caller enumerating a registry.
+ *
+ * @public
+ */
+interface AgentToolDescription {
+    name: string;
+    description: string;
+    /** The JSON Schema sent to the model verbatim — the tool's callable signature. */
+    inputSchema: Record<string, unknown>;
+}
+/**
+ * theokit#123 — one subagent of a registered agent (what theokit-studio calls a workflow).
+ *
+ * `prompt` is deliberately absent. Enumeration asks what a subagent IS and what it may call; its
+ * system prompt is instructions, not signature, and a reflection endpoint that serializes it
+ * publishes the agent's behaviour to anyone who can reach the endpoint.
+ *
+ * @public
+ */
+interface AgentSubagentDescription {
+    /** The key under `AgentOptions.agents` — how the parent addresses it. */
+    name: string;
+    description: string;
+    /** `"inherit"` (or absent) means it runs on the parent's model. */
+    model?: ModelSelection | "inherit";
+    /** Tool whitelist, when the subagent is scoped to a subset of the parent's tools. */
+    tools?: string[];
+}
+/**
+ * theokit#123 — the read-only introspection of a registered agent, returned by `Agent.describe()`.
+ *
+ * `Agent.list()` / `Agent.get()` enumerate agents and `agent.skills.list()` covers skills; this
+ * fills the remaining gap, so a reflection endpoint can report the live registry instead of
+ * degrading to empty lists.
+ *
+ * `tools` and `subagents` are always arrays — never `undefined` — so a caller can distinguish
+ * "this agent has none" from "the SDK did not say".
+ *
+ * @public
+ */
+interface AgentDescription {
+    agentId: string;
+    /** Inlined rather than imported from the registry contract: `types/` stays a leaf (theokit#146). */
+    runtime: "local" | "cloud";
+    model?: ModelSelection;
+    /**
+     * The agent's DECLARED tool catalog.
+     *
+     * Plugin-contributed tools and the internal `think` tool (added when `reasoning` is on) are
+     * assembled per run and are not knowable from the registry, so they are absent here. Stated
+     * rather than implied: a reflection endpoint should not present this as the complete runtime set.
+     */
+    tools: readonly AgentToolDescription[];
+    /**
+     * Every subagent the runtime would resolve — file-based roles from `.theokit/agents/*.md` merged
+     * with the inline `agentOptions.agents`, the same set `loadSubagents` builds for a run.
+     */
+    subagents: readonly AgentSubagentDescription[];
+}
+/**
+ * Options for `Agent.list()`.
+ *
+ * `limit`/`cursor` paginate (B-115): a `limit` bounds the page and, when more agents remain,
+ * `ListResult.nextCursor` is set — pass it back as `cursor` for the next page. Omitting `limit`
+ * returns every matching agent in one page, unpaginated, exactly as before (M107 declared imposing
+ * pagination order unconditionally a breaking change to every caller's observed order; pagination
+ * here is opt-in and only reorders the page it returns, never the unlimited default).
+ *
+ * @public
+ */
+type ListAgentsOptions = {
+    limit?: number;
+    cursor?: string;
+} & ({
+    runtime?: undefined;
+} | {
+    runtime: "local";
+    cwd?: string;
+} | {
+    runtime: "cloud";
+    /**
+     * Hide archived agents unless `true`. Default `false` (hidden) — B-115, this used to be
+     * accepted and silently ignored; every archived agent was always included.
+     */
+    includeArchived?: boolean;
+    apiKey?: string;
+});
+/**
+ * Options for `Agent.get()`.
+ *
+ * `cwd` (default `process.cwd()`) selects which workspace's on-disk registry to hydrate before the
+ * lookup — same rule `Agent.list` uses (B-115; this used to be accepted and silently ignored).
+ *
+ * @public
+ */
+interface GetAgentOptions {
+    cwd?: string;
+    apiKey?: string;
+}
+/**
+ * Options for `Agent.listRuns()`.
+ *
+ * `cwd` (default `process.cwd()`) hydrates that workspace's registry before validating the agent
+ * exists — same rule as `Agent.get` (B-115). `limit`/`cursor` paginate the SAME way as
+ * `Agent.list` — see its doc — except no reordering is ever needed: a single agent's runs are
+ * already returned in the stable order they were created.
+ *
+ * B-115 — `runtime` removed 2026-08-19. A single `agentId` already pins exactly one runtime;
+ * filtering an already-single-agent's runs by runtime filtered nothing and was never checked.
+ *
+ * @public
+ */
+interface ListRunsOptions {
+    cwd?: string;
+    apiKey?: string;
+    limit?: number;
+    cursor?: string;
+}
+/**
+ * Options for `Agent.getRun()`. Cloud requires the parent `agentId`.
+ *
+ * @public
+ */
+type GetRunOptions = {
+    runtime?: "local";
+    cwd?: string;
+} | {
+    runtime: "cloud";
+    agentId: string;
+    apiKey?: string;
+};
+/**
+ * Options for archive/unarchive/delete.
+ *
+ * @public
+ */
+interface AgentOperationOptions {
+    cwd?: string;
+    apiKey?: string;
+}
+/**
+ * Paginated list shape.
+ *
+ * @public
+ */
+interface ListResult<T> {
+    items: T[];
+    nextCursor?: string;
+}
+
+export { type SettingSource as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type MemoryProviderAgentRef as D, type MemoryProviderFactory as E, type MemoryProviderHandle as F, type GetAgentOptions as G, type HookName as H, type InlineSkill as I, type MemoryProviderInitOptions as J, type PluginContext as K, type LocalOptions as L, type MemorySettings as M, type PluginHookDisposer as N, type PostAssistantReplyContext as O, type Plugin as P, type PostToolCallContext as Q, type PreToolCallContext as R, type SystemPromptResolver as S, type PreUserSendContext as T, type PreUserSendResult as U, type ProviderTransform as V, type ProviderTransformContext as W, type RecordSessionSummaryArgs as X, type SessionLifecycleContext as Y, type SessionRecord as Z, type SessionStore as _, type AgentDefinition as a, Skill as a0, type SkillsResolver as a1, type SkillsResolverContext as a2, type SystemPromptContext as a3, type SystemPromptMemoryFact as a4, type TelemetrySettings as a5, type ToolCallSummary as a6, type ToolResultTransformContext as a7, type TransformContext as a8, type SkillsSettings as b, type ListAgentsOptions as c, type ListResult as d, type SDKAgentInfo as e, type ListRunsOptions as f, type GetRunOptions as g, type AgentOperationOptions as h, type AgentDescription as i, type ProviderProfile as j, type MemoryProvider as k, type PreToolCallDecision as l, type ActiveMemoryPassArgs as m, type ActiveMemoryPassResult as n, type AgentSubagentDescription as o, type AgentToolDescription as p, type BudgetCheck as q, type BudgetTotal as r, type BudgetUsageEvent as s, type BuiltinToolName as t, type CloudEnv as u, type CloudRepo as v, type CompatSource as w, type CompatSourceAdapter as x, type CompatSurface as y, type CreateSkillSpec as z };