@theokit/sdk 4.19.1 → 4.19.2

package/dist/cron-M2Xz7lq2.d.cts

@@ -0,0 +1,2582 @@
+import * as zod from 'zod';
+import { ZodType } from 'zod';
+import { M as ModelSelection, ac as SDKUserMessage, ae as SendOptions, b as Run, G as GenerateOptions, n as GenerateRunResult, _ as RunToCompletionOptions, $ as RunToCompletionResult, S as SDKMessage, al as StreamToCompletionResult, C as CustomTool, c as PermissionMode, a as McpServerConfig, P as Processor, u as MessageOrigin } from './run-DFM1H2jW.cjs';
+
+/**
+ * `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
+ */
+/** One transcript record (one JSONL line). `message` absent on `system` (compact_boundary) records. */
+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;
+    };
+    message?: Record<string, unknown>;
+}
+
+/**
+ * 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.
+ *
+ * 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>;
+}
+
+/**
+ * Public `MemoryAdapter` contract (T1.1, ADRs D141 / D147).
+ *
+ * The plugin extension point `{ kind: "memory" }` (ADR D98) declares a
+ * `createProvider` factory; this file types its return value formally.
+ * Adapters implement `write` / `recall` / `delete` plus optional methods
+ * gated by `capabilities`. `MemoryId` is a branded string prefixed with
+ * the adapter id so cross-adapter use throws on `extractRawId` (EC-B).
+ *
+ * Each provider-specific package (`@theokit-memory-supermemory`, etc)
+ * exports a factory returning a `Plugin { kind: "memory" }` whose
+ * `createProvider` resolves to a `MemoryAdapter` instance.
+ *
+ * @public
+ */
+/**
+ * Branded provider memory ID. Format: `${adapterId}:${rawProviderId}`.
+ * Use `mkMemoryId` / `extractRawId` from `../memory-adapter-helpers.js`
+ * to construct and unwrap with cross-adapter safety (EC-B).
+ *
+ * @public
+ */
+type MemoryId = string & {
+    readonly __brand: "MemoryId";
+};
+/**
+ * Portable identity context. `userId` is the only required field —
+ * the lowest common denominator across Supermemory / Honcho / Mem0.
+ * Adapter implementations translate the optional fields to their
+ * provider's native primitives (Honcho session, Mem0 run_id, etc).
+ *
+ * @public
+ */
+interface MemoryContext {
+    /** End-user identity. */
+    userId: string;
+    /** Agent / persona writing the memory. */
+    agentId?: string;
+    /** Logical conversation / run boundary. */
+    sessionId?: string;
+    /** Tenant / workspace partition. */
+    tenantId?: string;
+    /** Free-form tags for filtering / categorization. */
+    tags?: string[];
+    /** Provider-passthrough metadata. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A single memory fact returned by `recall` or `get`.
+ *
+ * @public
+ */
+interface MemoryFact {
+    id: MemoryId;
+    content: string;
+    /** Semantic relevance score (provider-defined scale) when result of `recall`. */
+    score?: number;
+    /** ISO 8601 timestamp of creation. */
+    createdAt?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Versioned snapshot of a memory's history. Only emitted by providers
+ * with `capabilities.history === true` (Mem0 today).
+ *
+ * @public
+ */
+interface MemoryRevision {
+    id: MemoryId;
+    content: string;
+    version: number;
+    changedAt: string;
+}
+/**
+ * Statically declared adapter feature flags. Consumers feature-detect
+ * at compile time via `if (adapter.capabilities.history)`.
+ *
+ * @public
+ */
+interface MemoryAdapterCapabilities {
+    /** Returns prior versions of a memory via `history(id)`. */
+    history: boolean;
+    /** First-class `sessionId` scoping. */
+    sessions: boolean;
+    /** First-class `tenantId` scoping. */
+    tenancy: boolean;
+    /** Provider performs reasoning over memory (e.g., Honcho dialectic). */
+    reasoning: boolean;
+    /** Exposes LLM-callable function-calling schemas. */
+    toolSchemas: boolean;
+    /** Supports background prefetch (currently informational). */
+    prefetch: boolean;
+}
+/**
+ * One assistant-turn message in the canonical `{role, content}` shape
+ * an adapter may receive instead of a flat string when writing a turn.
+ *
+ * @public
+ */
+interface MemoryTurnMessage {
+    role: "user" | "assistant" | "system";
+    content: string;
+}
+/**
+ * OpenAI-format function-calling schema exposed to the LLM.
+ *
+ * @public
+ */
+interface MemoryToolSchema {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+/**
+ * Portable third-party memory adapter contract. Implementations live
+ * in `@theokit-memory-*` packages; the SDK never imports them.
+ *
+ * @public
+ */
+interface MemoryAdapter {
+    /** Short identifier — matches the `${adapterId}` prefix in `MemoryId`. */
+    readonly id: string;
+    readonly capabilities: MemoryAdapterCapabilities;
+    /** Synchronous availability probe — no network, no I/O. */
+    isAvailable(): boolean;
+    /** One-shot initialization. Idempotent: safe to call multiple times. */
+    initialize?(): Promise<void>;
+    /**
+     * Persist a fact or full turn to memory. Returns the stored
+     * `MemoryId`. Throws `MemoryAdapterError(code: "invalid_input")` on
+     * empty content or invalid identifiers in `ctx`.
+     */
+    write(content: string | MemoryTurnMessage[], ctx: MemoryContext): Promise<MemoryId>;
+    /**
+     * Semantic recall — top-`k` facts ordered by relevance. Returns
+     * empty array when `k === 0` or no matches.
+     */
+    recall(query: string, ctx: MemoryContext, k?: number): Promise<MemoryFact[]>;
+    /**
+     * Delete a memory by id. Throws `MemoryAdapterError(code:
+     * "invalid_input")` when the id was minted by a different adapter
+     * (EC-B). Throws `code: "not_found"` when the id does not exist.
+     */
+    delete(id: MemoryId): Promise<void>;
+    list?(ctx: MemoryContext, opts?: {
+        cursor?: string;
+        limit?: number;
+    }): AsyncIterable<MemoryFact>;
+    get?(id: MemoryId): Promise<MemoryFact | null>;
+    history?(id: MemoryId): Promise<MemoryRevision[]>;
+    /** Empty array when `capabilities.toolSchemas === false`. */
+    getToolSchemas?(): MemoryToolSchema[];
+    handleToolCall?(name: string, args: Record<string, unknown>, ctx: MemoryContext): Promise<string>;
+    /** Graceful shutdown — flush queues, close connections. */
+    shutdown?(): Promise<void>;
+}
+/**
+ * Direct memory API exposed on `SDKAgent.memory`. Resolves to whichever
+ * memory adapter(s) are registered via `Agent.create({ plugins: [...] })`.
+ *
+ * @public
+ */
+interface AgentMemory {
+    /**
+     * Persist a fact. Returns the first adapter's id; in multi-adapter
+     * setups all adapters receive the write (fan-out).
+     */
+    write(content: string | MemoryTurnMessage[], ctx?: Partial<MemoryContext>): Promise<MemoryId>;
+    /** Semantic recall — merged + deduped across registered adapters. */
+    recall(query: string, ctx?: Partial<MemoryContext>, k?: number): Promise<MemoryFact[]>;
+    /** Delete a memory by id — routes to the owning adapter via prefix. */
+    delete(id: MemoryId): Promise<void>;
+    /** Returns the first registered adapter or `null` when none exists. */
+    adapter(): MemoryAdapter | null;
+}
+
+/**
+ * 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 */
+declare class Skill {
+    private constructor();
+    static create(spec: CreateSkillSpec): InlineSkill;
+}
+
+/**
+ * `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;
+}
+
+/**
+ * Context manager backend.
+ *
+ * - `"file"` — Read `.theokit/context.json` from the workspace (local) or the
+ *   cloned repo (cloud).
+ *
+ * @public
+ */
+type ContextManagerKind = "file";
+/**
+ * Context configuration accepted by `Agent.create()` via {@link AgentOptions.context}.
+ *
+ * @public
+ */
+interface ContextSettings {
+    /** Which backend reads context. Defaults to `"file"`. */
+    manager?: ContextManagerKind;
+    /** Hard cap on tokens emitted into the agent's system prompt. */
+    maxTokens?: number;
+    /**
+     * Per-file truncation cap in characters. Default 40_000 (~10k tokens).
+     * Larger files are truncated with 70%/20% head/tail + marker (ADR D155).
+     *
+     * @public
+     */
+    maxBytesPerFile?: number;
+    /**
+     * Aggregate cap across all context files in characters. Default 120_000.
+     * When total exceeds this, lower-priority sources are dropped (ADR D155).
+     *
+     * Note: context snapshot is **refresh-time** (EC-T); modifying context
+     * files mid-flight does not auto-update. Call `agent.reload()` to pick
+     * up changes.
+     *
+     * @public
+     */
+    maxBytesTotal?: number;
+}
+/**
+ * Inclusion state of a single context source in a {@link ContextSnapshot}.
+ *
+ * @public
+ */
+type ContextSourceStatus = "included" | "excluded" | "summarized";
+/**
+ * A single context source resolved by the context manager.
+ *
+ * @public
+ */
+interface ContextSource {
+    /** Stable identifier — usually the filename without extension. */
+    name: string;
+    /** Path relative to the workspace root, when applicable. */
+    path?: string;
+    /** Whether the source was included, dropped, or summarized to fit the budget. */
+    status: ContextSourceStatus;
+    /** Free-text reason when `status !== "included"`. */
+    reason?: string;
+}
+/**
+ * Token budget used by the context manager for a single agent.
+ *
+ * @public
+ */
+interface ContextBudget {
+    maxTokens?: number;
+    /**
+     * Either a token count or a list of token strings extracted from source
+     * content. Normalized to `<tokens>` in golden comparisons.
+     */
+    usedTokens?: number | string[];
+}
+/**
+ * Result of `agent.context.snapshot()`. Public and secret-free by design — safe
+ * to log and persist. Raw secrets, local absolute paths, and exact token values
+ * are never present.
+ *
+ * @public
+ */
+interface ContextSnapshot {
+    runtime: "local" | "cloud";
+    sources: ContextSource[];
+    budget?: ContextBudget;
+}
+/**
+ * Public context manager handle exposed as `agent.context`.
+ *
+ * @public
+ */
+interface SDKContextManager {
+    /** Inspect what the context manager actually loaded for the agent. */
+    snapshot(): Promise<ContextSnapshot>;
+}
+
+/**
+ * Fork primitive public type contracts (T1.2, ADRs D110-D114).
+ *
+ * Extracted into a leaf type module (arch-review ADR 0001) so the public
+ * `types/agent.ts` barrel can reference `ForkOptions`/`ForkResult` without
+ * importing the `internal/runtime/lifecycle/fork-agent.ts` implementation — which in
+ * turn imports back from `types/agent.ts`. That mutual reference created a
+ * type-only `madge` cycle. These interfaces are self-contained (no SDKAgent
+ * / AgentOptions references), so co-locating them here breaks the cycle with
+ * no runtime change. `fork-agent.ts` re-exports them for back-compat.
+ */
+/**
+ * Caller-supplied fork configuration. See `forkAgentImpl`.
+ *
+ * @public
+ */
+interface ForkOptions {
+    /**
+     * Tool subset visible to the fork. Names must match the canonical (post-repair)
+     * tool name — typically lowercase. Tools not in this set return a `tool_result`
+     * with `"Tool blocked by fork whitelist"` content (EC-H).
+     */
+    allowedTools: Set<string>;
+    /** Task prompt sent to the fork. */
+    prompt: string;
+    /** Override system prompt. Default: byte-identical inheritance from parent (D112). */
+    systemPrompt?: string;
+    /** Memory write provenance tag (D114). Default `"fork"`. */
+    forkOrigin?: string;
+}
+/**
+ * Outcome of a fork run.
+ *
+ * @public
+ */
+interface ForkResult {
+    /** Final agent response text (`undefined` when the fork produced no result). */
+    result: string | undefined;
+    /** Tool calls executed inside the fork. */
+    toolCalls: ReadonlyArray<{
+        name: string;
+        input: Record<string, unknown>;
+    }>;
+    /** Aggregate token usage reported by the run. */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+
+/**
+ * Public event types emitted by {@link SDKAgent.runUntil} (ADRs D115-D117).
+ *
+ * Discriminated union by `type` field so consumers can `switch (event.type)`
+ * with full TypeScript exhaustiveness. Mirrors the
+ * {@link import("../stream-object.js").StreamObjectEvent} pattern (ADR D39).
+ *
+ * @public
+ */
+/**
+ * Single event emitted while iterating a goal-driven loop. Five variants:
+ *
+ * - `turn_start` — the agent is about to invoke `send()`. Emitted once
+ *   per turn.
+ * - `agent_response` — the agent's `send()` resolved; carries the text
+ *   reply.
+ * - `judge_verdict` — the auxiliary judge model evaluated the response.
+ *   `parseFailed: true` indicates the judge returned a malformed reply
+ *   (fail-safe verdict = `continue`, see ADR D121).
+ * - `continuation` — the judge ruled `continue`; carries the prompt that
+ *   was sent on THIS turn (i.e., the input that produced the agent
+ *   response just yielded). Useful for consumers who want to audit the
+ *   exact continuation message that drove each iteration. The prompt
+ *   for the NEXT turn is composed lazily at the start of that turn
+ *   from the latest `agent_response.content`.
+ * - `status_change` — transition of the overall goal state. Always
+ *   emitted once at start (`active`) and once at end
+ *   (`completed | failed | paused`).
+ *
+ * @public
+ */
+type GoalEvent = {
+    type: "turn_start";
+    turn: number;
+    goal: string;
+} | {
+    type: "agent_response";
+    turn: number;
+    content: string;
+} | {
+    type: "judge_verdict";
+    turn: number;
+    verdict: "done" | "continue" | "skipped";
+    reason: string;
+    parseFailed: boolean;
+} | {
+    type: "continuation";
+    turn: number;
+    prompt: string;
+} | {
+    type: "status_change";
+    status: "active" | "paused" | "completed" | "failed" | "budget_limited" | "blocked";
+    reason: string;
+};
+/**
+ * Return value of the `runUntil` async generator. Consumer reads via
+ * `const { value } = await gen.next()` (when `done: true`).
+ *
+ * @public
+ */
+interface GoalResult {
+    status: "completed" | "failed" | "paused" | "budget_limited" | "blocked";
+    turnsUsed: number;
+    /** M55 — tokens somados ao longo do loop (0 quando `usage` esteve ausente — fail-open). */
+    tokensUsed: number;
+    finalResponse: string | undefined;
+}
+/**
+ * Return type of {@link import("../internal/local-agent/local-agent.js").LocalAgent.runUntil}.
+ * Extracted so the LocalAgent method signature stays a single line (G8 LoC budget).
+ *
+ * @public
+ */
+type RunUntilIterator = AsyncGenerator<GoalEvent, GoalResult, void>;
+/**
+ * Per-call configuration for `Agent.runUntil`.
+ *
+ * @public
+ */
+interface GoalOptions {
+    /** Hard cap on iterations (safety net against runaway). Default `20`. */
+    maxTurns?: number;
+    /**
+     * M55 — token budget (Codex ext/goal parity, tool.rs:454-465). Soma `run.wait().usage.totalTokens`
+     * por turno; ao cruzar, o loop para com status `budget_limited`. Omitido ⇒ ilimitado (só maxTurns).
+     * `usage` ausente nunca estoura o budget (fail-open).
+     */
+    tokenBudget?: number;
+    /** Bail after N consecutive judge parse failures. Default `3` (ADR D121). */
+    maxConsecutiveJudgeFailures?: number;
+    /** Judge model identifier. Default `"openai/gpt-4o-mini"` (ADR D119). */
+    judgeModel?: string;
+    /** Override env for the judge auxiliary agent. Default `OPENROUTER_API_KEY` (EC-A). */
+    judgeApiKey?: string;
+    /** Optional subgoals fed to the judge prompt. */
+    subgoals?: string[];
+    /**
+     * Cancel mid-loop via `AbortController.signal`. The generator yields
+     * a `status_change: paused` event and returns at the next turn
+     * boundary (ADR D117).
+     */
+    signal?: AbortSignal;
+}
+
+/**
+ * Capability slot a provider can fulfill.
+ *
+ * @public
+ */
+type ProviderCapability = "chat" | "web_search" | "image" | "embedding";
+/**
+ * A single user-declared routing rule. Maps a capability to a provider, and
+ * optionally pins a specific model.
+ *
+ * @public
+ */
+interface ProviderRoute {
+    capability: ProviderCapability;
+    provider: string;
+    model?: string;
+    /**
+     * Opt-in leaked-dialect safe-parse for this route's provider (theokit#58
+     * follow-up). When `true`, a `chat_completions` finish that carries ZERO
+     * native `tool_calls` has its assistant text scanned for the Hermes
+     * `<function=…></tool_call>` dialect, and any recovered calls are surfaced as
+     * real `tool_calls` so the loop executes them — for models (qwen3-coder via
+     * OpenRouter) that intermittently leak tool calls as text. Default `false`;
+     * fail-open (a partial/unclosed block never fabricates a call). Scoped to the
+     * resolved chat chain, so a non-leaking route is unaffected.
+     */
+    extractToolCallsFromContent?: boolean;
+}
+/**
+ * Provider routing configuration accepted by `Agent.create()` via
+ * {@link AgentOptions.providers}.
+ *
+ * @public
+ */
+interface ProviderRoutingSettings {
+    /** Explicit `{ capability → provider }` map. First match wins per capability. */
+    routes: ProviderRoute[];
+    /** Provider names to try in order when a route has no provider available. */
+    fallback?: string[];
+    /**
+     * Multiple API keys per provider for same-provider key rotation
+     * (credential pool — ADRs D123-D133). When a key hits HTTP 429, 402,
+     * or 401, the SDK rotates to the next entry transparently before
+     * falling back to a different provider.
+     *
+     * Example:
+     * ```ts
+     * apiKeys: { openrouter: ["sk-or-...", "sk-or-..."], anthropic: ["..."] }
+     * ```
+     *
+     * Empty arrays and empty strings are filtered out. If a provider has
+     * exactly 1 effective key, the pool is transparent (no rotation behavior).
+     *
+     * Conflicts with the single-key shape `AgentOptions.apiKey: "..."` —
+     * use one OR the other, not both.
+     *
+     * @public
+     */
+    apiKeys?: Record<string, string[]>;
+    /**
+     * Rotation strategy per provider for the credential pool. Default is
+     * `"fill_first"` (use entries[0] until exhausted). Only consulted when
+     * `apiKeys[provider]` has ≥2 entries.
+     *
+     * @public
+     */
+    credentialPoolStrategy?: Record<string, "fill_first" | "round_robin" | "least_used" | "random">;
+}
+/**
+ * Plugins configuration accepted by `Agent.create()` via
+ * {@link AgentOptions.plugins}.
+ *
+ * @public
+ */
+interface PluginsSettings {
+    /** Plugin names to enable. Plugin discovery is plugin-provider specific. */
+    enabled?: string[];
+}
+/**
+ * Resolved routing decision returned by `agent.providers.routes()`. Public and
+ * secret-free by design — safe to log.
+ *
+ * @public
+ */
+interface ResolvedProviderRoute {
+    capability: string;
+    provider: string;
+    model?: string;
+    /** Why the runtime picked this provider (e.g. `"explicit-model-provider"`). */
+    reason: string;
+}
+/**
+ * Public providers manager handle exposed as `agent.providers`.
+ *
+ * @public
+ */
+interface SDKProvidersManager {
+    /** Inspect which provider serves each capability for this agent. */
+    routes(): Promise<ResolvedProviderRoute[]>;
+}
+/**
+ * Provider catalog entry returned by `Theokit.providers.list()`.
+ *
+ * @public
+ */
+interface SDKProvider {
+    name: string;
+    displayName: string;
+    capabilities: string[];
+    isAvailable: boolean;
+    /** JSON Schema describing the env vars / fields needed to enable this provider. */
+    setupSchema: object;
+}
+
+/**
+ * Public skill metadata exposed to the system-prompt resolver. Mirrors the
+ * shape returned by `agent.skills.list()` — name + description only, never
+ * full skill bodies.
+ *
+ * @public
+ */
+interface SystemPromptSkillRef {
+    name: string;
+    description: string;
+}
+/**
+ * A skill resolved WITH its body, returned by {@link SDKAgentSkills.get}. Unlike
+ * {@link SystemPromptSkillRef} (name + description only), this carries the full
+ * `instructions` — read from the SKILL.md for filesystem skills or the inline
+ * `createSkill` body. @public
+ */
+interface SDKAgentSkillDetail {
+    name: string;
+    description: string;
+    instructions: string;
+    /** SE21 — supporting documents bundled with the skill (filename → content), when present. */
+    references?: Record<string, string>;
+}
+interface SDKAgentSkills {
+    list(): Promise<ReadonlyArray<SystemPromptSkillRef>>;
+    /**
+     * SE20 — resolve a skill by name INCLUDING its body (`instructions`). Returns
+     * `undefined` when no enabled skill matches. `list()` stays lean (name +
+     * description); full bodies come only through `get`.
+     */
+    get(name: string): Promise<SDKAgentSkillDetail | undefined>;
+}
+/**
+ * Public plugin metadata returned by `agent.plugins.list()`. Mirrors the
+ * `.theokit/plugins/<name>/MANIFEST.json` allow-listed shape; never exposes
+ * raw plugin bodies, credentials, or internal hooks.
+ *
+ * @public
+ */
+interface SDKPluginMetadata {
+    name: string;
+    description?: string;
+}
+/**
+ * Public plugin listing handle exposed as `agent.plugins`. Populated when
+ * `settingSources` includes `"plugins"` OR when `plugins.enabled` is set
+ * on the agent options.
+ *
+ * @public
+ */
+interface SDKAgentPlugins {
+    list(): Promise<ReadonlyArray<SDKPluginMetadata>>;
+}
+/**
+ * Artifact produced inside an agent's workspace. Cloud-only.
+ *
+ * @public
+ */
+interface SDKArtifact {
+    path: string;
+    sizeBytes: number;
+    updatedAt: string;
+}
+/**
+ * Handle returned by `Agent.create()` and `Agent.resume()`.
+ *
+ * @public
+ */
+interface SDKAgent {
+    readonly agentId: string;
+    readonly model: ModelSelection | undefined;
+    /**
+     * Context manager for this agent. Populated when context is enabled via
+     * {@link AgentOptions.context}. See {@link SDKContextManager}.
+     */
+    readonly context?: SDKContextManager;
+    /**
+     * Provider routing inspector for this agent. Populated when at least one
+     * provider route is configured (via {@link AgentOptions.providers}, plugins,
+     * or model-implied providers). See {@link SDKProvidersManager}.
+     */
+    readonly providers?: SDKProvidersManager;
+    /**
+     * Skill listing for this agent. Populated when project-scoped skills are
+     * enabled (`settingSources: ["project"]`) or when `skills.enabled` is set.
+     * See {@link SDKAgentSkills}.
+     */
+    readonly skills?: SDKAgentSkills;
+    /**
+     * Plugin listing for this agent. Populated when project-scoped plugins are
+     * enabled (`settingSources: ["plugins"]`) or when `plugins.enabled` is set.
+     * See {@link SDKAgentPlugins}.
+     */
+    readonly plugins?: SDKAgentPlugins;
+    send(message: string | SDKUserMessage, options?: SendOptions): Promise<Run>;
+    /**
+     * SE9 — integrated structured output. Runs the normal tool loop (the tools run
+     * first) then coerces the final answer into the `output` Zod schema, returning a
+     * validated, inferred-typed object. Sugar over `Agent.generateObject` (ADR D33).
+     */
+    generate<T extends zod.ZodType>(message: string | SDKUserMessage, options: GenerateOptions<T>): Promise<GenerateRunResult<zod.z.infer<T>>>;
+    /** Fire-and-forget disposal. */
+    close(): void;
+    /** Re-read filesystem config (context, hooks, project MCP, subagents) without disposing. */
+    reload(): Promise<void>;
+    /**
+     * Async disposal. Idempotent — calling more than once is a no-op (per ADR D5).
+     * Prefer `await using agent = await Agent.create(...)` over explicit
+     * `dispose()` for resource safety.
+     */
+    dispose(): Promise<void>;
+    /**
+     * `await using` support per ADR D5. Identical semantics to `dispose()` —
+     * idempotent across both surfaces.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /** Cloud-only. Local returns an empty array. */
+    listArtifacts(): Promise<SDKArtifact[]>;
+    /** Cloud-only. Local throws `UnsupportedRunOperationError`. */
+    downloadArtifact(path: string): Promise<Buffer>;
+    /**
+     * Signal that prompt cache should be invalidated. By default deferred —
+     * applied at the start of the next `send()`. Pass `{ applyNow: true }` to
+     * force immediate disposal (caller must `Agent.create()` again to use).
+     *
+     * Cache invalidation is a cost regression (provider charges full price
+     * for the rebuilt cache; see ADRs D94-D95). Use sparingly and deliberately.
+     *
+     * Cloud agents: no-op (cloud runtime reconstructs state per request).
+     *
+     * @public
+     */
+    invalidateCache?(reason: string, options?: InvalidateCacheOptions): Promise<void>;
+    /**
+     * Goal-driven Ralph loop (ADRs D115-D121). Iterates `agent.send` →
+     * judge → continuation until the auxiliary judge model returns `done`,
+     * the judge fails too many times in a row, max turns are exhausted,
+     * or the caller aborts via `AbortSignal`.
+     *
+     * Yields {@link import("./goal-events.js").GoalEvent} per state
+     * transition; returns a {@link import("./goal-events.js").GoalResult}
+     * summary as the generator's final value.
+     *
+     * Cloud agents throw {@link import("../errors.js").UnsupportedRunOperationError}
+     * **synchronously** (no AsyncGenerator returned) — wrap in try/catch
+     * if you support both runtimes.
+     *
+     * Caveat: do not call `agent.dispose()` mid-iteration; the next `send`
+     * propagates the disposal error through the generator to the consumer.
+     *
+     * @public
+     */
+    runUntil?(goal?: string, options?: GoalOptions): RunUntilIterator;
+    /**
+     * Fork a short-lived sub-agent with parent's credentials + system
+     * prompt byte-identical (ADR D112 — cache hit) and a restricted tool
+     * whitelist (ADR D111 — AsyncLocalStorage isolation).
+     *
+     * Cloud agents throw {@link import("../errors.js").UnsupportedRunOperationError}.
+     *
+     * @public
+     */
+    fork?(options: ForkOptions): Promise<ForkResult>;
+    /**
+     * Drive `send` to completion across iteration-ceiling truncations (M1 Phase 3).
+     * When a `send` stops at the loop's iteration cap (`RunResult.stoppedAtIterationLimit`),
+     * this re-sends a short continuation prompt — the agent's stateful session
+     * preserves the conversation — until a genuine terminal: `done` (finished),
+     * `step_limit` (`maxRounds` exhausted), or `no_progress` (two empty rounds).
+     *
+     * Local agents only. Cloud agents throw
+     * {@link import("../errors.js").UnsupportedRunOperationError} (the cloud
+     * runtime manages its own continuation policy server-side).
+     *
+     * @public
+     */
+    runToCompletion?(message: string, options?: RunToCompletionOptions): Promise<RunToCompletionResult>;
+    /**
+     * STREAMING continuation driver (V3-4) — the streaming twin of
+     * {@link SDKAgent.runToCompletion}. Returns an `AsyncGenerator` that yields each
+     * round's {@link import("./messages.js").SDKMessage}s LIVE (for a UI), reusing the
+     * same terminal policy (`done`/`step_limit`/`no_progress` + bounded re-prompt).
+     *
+     * The {@link import("./run.js").StreamToCompletionResult} is the generator's RETURN
+     * value — read it via a manual `gen.next()` loop (`while (!res.done) res = await
+     * gen.next()` → `res.value`); a plain `for await...of` consumes the yielded
+     * messages but discards the return value.
+     *
+     * Local agents only. Cloud agents throw
+     * {@link import("../errors.js").UnsupportedRunOperationError}.
+     *
+     * @public
+     */
+    streamToCompletion?(message: string, options?: RunToCompletionOptions): AsyncGenerator<SDKMessage, StreamToCompletionResult>;
+    /**
+     * Direct API to third-party memory adapter(s) registered via
+     * `plugins: [...]` (ADR D141 / D142). Returns `null` when no adapter
+     * is registered. In multi-adapter setups `write` fans out to all;
+     * `recall` merges + dedupes; `delete` routes by `MemoryId` prefix.
+     *
+     * @public
+     */
+    memory?: AgentMemory;
+    /**
+     * Activate a personality preset for the next `send` (Hermes #26).
+     * Reserved names `"none"`, `"default"`, and `"neutral"` clear the
+     * active preset. Returns the resolved preset (or `null` when cleared).
+     *
+     * Persistence: pass `{ save: true }` to persist across process
+     * restarts (stored under `$THEOKIT_HOME/personality.json`).
+     *
+     * History: by default the conversation history is preserved across
+     * the switch. Pass `{ reset: true }` to also clear the session.
+     *
+     * Cloud agents throw {@link import("../errors.js").UnsupportedRunOperationError}.
+     *
+     * @public
+     */
+    usePersonality?(name: string, opts?: {
+        save?: boolean;
+        reset?: boolean;
+    }): Promise<PersonalityPreset | null>;
+}
+/**
+ * Resolved personality preset surfaced via {@link SDKAgent.usePersonality}
+ * (Hermes #26, ADRs D160-D169). Re-declared here so the public DTS bundle
+ * never crosses the `internal/` path boundary. The implementation type in
+ * `internal/personality/types.ts` is structurally identical.
+ *
+ * @public
+ */
+interface PersonalityPreset {
+    readonly name: string;
+    readonly description: string | undefined;
+    readonly tools: ReadonlyArray<string> | undefined;
+    readonly model: string | undefined;
+    readonly tags: ReadonlyArray<string> | undefined;
+    readonly systemPrompt: string;
+    readonly source: "project" | "user";
+    readonly sourcePath: string;
+}
+/**
+ * Options for {@link SDKAgent.invalidateCache}.
+ *
+ * @public
+ */
+interface InvalidateCacheOptions {
+    /**
+     * When `true`, dispose the agent immediately so caller must recreate it
+     * to continue. Default `false` (deferred — applied on next `send()`).
+     */
+    applyNow?: boolean;
+}
+
+/**
+ * `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/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.
+ */
+
+/** 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;
+    /** 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: SDKAgent): 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;
+}
+
+/**
+ * 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). This is the CONTRACT-shape adaptation of OpenCode's provider `auth.loader`
+ * (MIT © 2025 opencode — `packages/core/src/plugin/provider/*.ts`), retargeted to 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;
+}
+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;
+}
+
+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";
+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;
+}
+interface PreToolCallDecision {
+    block: true;
+    message: string;
+}
+/**
+ * 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;
+    memoryContext?: MemoryContext;
+}
+type HookHandler = (ctx: unknown) => unknown | Promise<unknown>;
+type CommandHandler = (args: Record<string, unknown>) => Promise<string> | string;
+interface CommandOptions {
+    description?: string;
+}
+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`. */
+    on(hook: HookName, handler: HookHandler): void;
+    /** 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;
+}
+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";
+/**
+ * Local agent configuration.
+ *
+ * @public
+ */
+interface LocalOptions {
+    cwd?: string | string[];
+    settingSources?: SettingSource[];
+    sandboxOptions?: {
+        enabled: boolean;
+    };
+    /**
+     * SE40 — base directory for the native Claude-shaped session transcript
+     * (`<baseDir>/projects/<encoded-cwd>/<agentId>.jsonl`). Default `~/.theokit`.
+     * Set to `~/.claude` to write sessions the Claude Code CLI can `--continue`.
+     */
+    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;
+    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;
+    /**
+     * 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. Without it
+ * installed, telemetry is a no-op even when `enabled: true`.
+ *
+ * @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>;
+    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[];
+    /**
+     * 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.
+     *
+     * **Status (Phase 2 incremental):** the option is wired to the type
+     * surface only. Agent-loop runtime wiring is additive and lands in a
+     * subsequent iteration — for now, the kernel still uses the legacy
+     * `UsageAccumulator` + `IterationBudget` from `internal/budget/`.
+     * Consumers passing a custom tracker today get the type guarantee but
+     * NOT runtime enforcement.
+     *
+     * 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.
+     *
+     * **Status (Phase 1 incremental):** the option is wired to the type
+     * surface only. Agent-loop runtime wiring is additive and lands in
+     * subsequent iterations (T1.4 plumbing, T1.5 runtime hooks). For now,
+     * the kernel still uses the legacy `Memory` class + `internal/memory/*`
+     * runtime files. Consumers passing a custom provider today get the type
+     * guarantee but NOT runtime enforcement.
+     *
+     * 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[];
+});
+/**
+ * Options for `Agent.list()`.
+ *
+ * @public
+ */
+type ListAgentsOptions = {
+    limit?: number;
+    cursor?: string;
+} & ({
+    runtime?: undefined;
+} | {
+    runtime: "local";
+    cwd?: string;
+} | {
+    runtime: "cloud";
+    prUrl?: string;
+    includeArchived?: boolean;
+    apiKey?: string;
+});
+/**
+ * Options for `Agent.get()`.
+ *
+ * @public
+ */
+interface GetAgentOptions {
+    cwd?: string;
+    apiKey?: string;
+}
+/**
+ * Options for `Agent.listRuns()`.
+ *
+ * @public
+ */
+type ListRunsOptions = {
+    limit?: number;
+    cursor?: string;
+} & ({
+    runtime?: "local";
+    cwd?: string;
+} | {
+    runtime: "cloud";
+    apiKey?: 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;
+}
+
+/**
+ * Public type contract for `Workflow.create / .run / .resume` (Adoption
+ * Roadmap #5; ADRs D230-D248).
+ *
+ * Step types form a discriminated union by `kind`. Helper factory functions
+ * (`fn()`, `agentStep()`) live in `workflow.ts` and hide the discriminator
+ * from end users.
+ *
+ * @public
+ */
+
+type Step = FnStep | AgentStep | ParallelStep | BranchStep | ForeachStep | DowhileStep | SleepStep | SuspendStep;
+/** A pure function step. */
+interface FnStep {
+    readonly kind: "fn";
+    readonly id: string;
+    readonly fn: (input: unknown, ctx: StepContext) => Promise<unknown> | unknown;
+    readonly inputSchema?: ZodType;
+    readonly outputSchema?: ZodType;
+    readonly retry?: RetryPolicy;
+    /** D238 — slot reserved; runtime throws if engine not yet implemented. */
+    readonly compensate?: (input: unknown, output: unknown, error: Error) => Promise<void> | void;
+}
+/** An agent.send-driven step. */
+interface AgentStep {
+    readonly kind: "agent";
+    readonly id: string;
+    readonly agent: SDKAgent;
+    readonly promptTemplate: string | ((input: unknown) => string);
+    readonly retry?: RetryPolicy;
+    /**
+     * SE3 — provenance stamped onto this step's `agent.send()` (forwarded to
+     * `RunResult.origin`). Squad sets `{ kind: "peer", from: "agent-<i-1>" }` on
+     * every step after the first so a peer-driven turn is attributable.
+     */
+    readonly origin?: MessageOrigin;
+}
+/** N concurrent branches, each its own mini-step-list. */
+interface ParallelStep {
+    readonly kind: "parallel";
+    readonly id: string;
+    readonly branches: ReadonlyArray<ReadonlyArray<Step>>;
+    readonly concurrency?: number;
+    readonly errorPolicy?: "fail-fast" | "collect";
+}
+/** First-match-wins predicates + optional fallback. */
+interface BranchStep {
+    readonly kind: "branch";
+    readonly id: string;
+    readonly predicates: ReadonlyArray<readonly [(input: unknown) => boolean | Promise<boolean>, ReadonlyArray<Step>]>;
+    readonly fallback?: ReadonlyArray<Step>;
+}
+/** Map a step over an upstream array output. */
+interface ForeachStep {
+    readonly kind: "foreach";
+    readonly id: string;
+    /** ID of an upstream top-level step whose output is iterable. */
+    readonly iterableFrom: string;
+    readonly step: Step;
+    readonly concurrency?: number;
+}
+/** Loop a step until condFn returns false. */
+interface DowhileStep {
+    readonly kind: "dowhile";
+    readonly id: string;
+    readonly step: Step;
+    readonly condFn: (output: unknown, iteration: number) => boolean | Promise<boolean>;
+    readonly maxIterations?: number;
+}
+/** Pause for a fixed duration. */
+interface SleepStep {
+    readonly kind: "sleep";
+    readonly id: string;
+    readonly durationMs: number;
+}
+/** Standalone explicit suspend point. */
+interface SuspendStep {
+    readonly kind: "suspend";
+    readonly id: string;
+    readonly payloadSchema?: ZodType;
+}
+/** D237 — retry policy applied per fn/agent step. */
+interface RetryPolicy {
+    /** Total attempts (MIN 1, MAX 20). `1` = no retry. */
+    readonly maxAttempts: number;
+    readonly initialBackoffMs?: number;
+    readonly backoffCoefficient?: number;
+    readonly maximumBackoffMs?: number;
+    readonly nonRetryableErrors?: ReadonlyArray<string>;
+}
+/** D247 — context handed to every step.fn. */
+interface StepContext {
+    readonly runId: string;
+    readonly signal: AbortSignal;
+    readonly log: {
+        debug: (msg: string, attrs?: Record<string, unknown>) => void;
+        info: (msg: string, attrs?: Record<string, unknown>) => void;
+        warn: (msg: string, attrs?: Record<string, unknown>) => void;
+    };
+    /** Pause the workflow; resume via `Workflow.resume({...})`. */
+    readonly suspend: (payload?: unknown) => Promise<never>;
+    /**
+     * SE29 — the workflow's shared state (from `WorkflowOptions.initialState`,
+     * mutated by {@link setState}), visible to every subsequent step in the run.
+     * `undefined` when no `initialState`/`setState` has run. Persisted across
+     * suspend/resume.
+     */
+    readonly state: unknown;
+    /**
+     * SE29 — update the shared state for subsequent steps. Validated against
+     * `WorkflowOptions.stateSchema` when set (a mismatch throws
+     * {@link WorkflowStateError}, which fails the step/run — Rule 8).
+     */
+    readonly setState: (next: unknown) => void;
+}
+interface StepResult {
+    readonly stepId: string;
+    readonly kind: Step["kind"];
+    readonly status: "completed" | "failed" | "skipped" | "suspended";
+    readonly attempts: number;
+    readonly durationMs: number;
+    readonly output?: unknown;
+    readonly error?: {
+        name: string;
+        message: string;
+    };
+}
+interface WorkflowRun<TOutput = unknown> {
+    readonly id: string;
+    readonly name: string;
+    readonly status: "running" | "completed" | "failed" | "suspended" | "cancelled";
+    readonly output?: TOutput;
+    readonly error?: {
+        name: string;
+        message: string;
+    };
+    readonly startedAt: number;
+    readonly endedAt?: number;
+    readonly stepResults: ReadonlyArray<StepResult>;
+}
+/**
+ * SE28 — a step-level workflow event emitted by `Workflow.stream()` as top-level
+ * steps run. Coarse-grained (one event per top-level step; nested
+ * parallel/branch/foreach emit as their single wrapping step), distinct from the
+ * token-delta agent stream. Discriminate on `type`.
+ *
+ * @public
+ */
+type WorkflowEvent = {
+    readonly type: "step_started";
+    readonly stepId: string;
+} | {
+    readonly type: "step_completed";
+    readonly stepId: string;
+    readonly output: unknown;
+} | {
+    readonly type: "step_failed";
+    readonly stepId: string;
+    readonly error: {
+        readonly name: string;
+        readonly message: string;
+    };
+} | {
+    readonly type: "workflow_suspended";
+    readonly stepId: string;
+} | {
+    readonly type: "workflow_completed";
+};
+/**
+ * SE28 — the async iterator returned by `Workflow.stream()`. Yields
+ * {@link WorkflowEvent}s in execution order; `result` resolves to the same
+ * terminal {@link WorkflowRun} the `run()` path returns (the authoritative
+ * outcome — the stream ends when the run terminates).
+ *
+ * @public
+ */
+type WorkflowStream<TOutput = unknown> = AsyncIterableIterator<WorkflowEvent> & {
+    readonly result: Promise<WorkflowRun<TOutput>>;
+};
+interface WorkflowPersistenceOptions {
+    readonly backend: "memory" | "json";
+    /** Required for `backend: "json"`. */
+    readonly dir?: string;
+}
+interface WorkflowOptions {
+    readonly name: string;
+    readonly persistence?: WorkflowPersistenceOptions;
+    /**
+     * SE27 — Zod schema for the WHOLE workflow's input. When set, `run(input)`
+     * validates `input` BEFORE step 1; a mismatch yields `status: "failed"` with a
+     * typed {@link WorkflowInputError} in `error` (fail-fast, no step runs, no
+     * silent coerce). Absent ⇒ no whole-workflow input validation (unchanged).
+     */
+    readonly inputSchema?: ZodType;
+    /**
+     * SE27 — Zod schema for the workflow's final output. When set, the terminal
+     * `completed` output is validated before `WorkflowRun.output` is populated; a
+     * mismatch yields `status: "failed"` with a typed {@link WorkflowOutputError}.
+     * Only validated on the `completed` path (suspended/failed runs skip it).
+     */
+    readonly outputSchema?: ZodType;
+    /**
+     * SE29 — Zod schema for the workflow's shared state (see `StepContext.state` /
+     * `setState`). When set, `initialState` and every `setState(next)` are
+     * validated against it (a mismatch throws {@link WorkflowStateError}). When
+     * `initialState` is absent, `state` starts as `undefined` and validation fires
+     * on the first `setState` call.
+     */
+    readonly stateSchema?: ZodType;
+    /**
+     * SE29 — the initial shared state, seeded onto `StepContext.state` before
+     * step 1. Validated against `stateSchema` when both are set. Persisted across
+     * suspend/resume.
+     */
+    readonly initialState?: unknown;
+    /** Internal — minted at `.commit()`. Not user-facing. */
+    readonly workflowId?: string;
+}
+interface WorkflowRunOptions {
+    readonly signal?: AbortSignal;
+    /** Override run ID for deterministic resume (advanced; default = mintRunId). */
+    readonly runId?: string;
+    /**
+     * Opt-in Task wrapping (ADRs D363, D374). Registers the workflow run
+     * as a `Task` (kind="workflow") with a `wf-` namespaced id (D368,
+     * EC-5). The task transitions terminal when `Workflow.run` resolves.
+     *
+     * Auto-id: `wf-{runId}`.
+     *
+     * @public
+     */
+    readonly task?: true | {
+        id?: string;
+        meta?: Record<string, unknown>;
+    };
+}
+interface WorkflowResumeOptions<TI = unknown> {
+    readonly runId: string;
+    readonly workflow: {
+        run: (input: TI, opts?: WorkflowRunOptions) => Promise<WorkflowRun>;
+    };
+    readonly payload?: unknown;
+    readonly signal?: AbortSignal;
+}
+
+/**
+ * Public `Workflow` class — declarative multi-step orchestration over
+ * `Agent.send`, `Handoff`, `Agent.batch` and friends (Adoption Roadmap #5;
+ * ADRs D230-D248).
+ *
+ * Usage:
+ *
+ *   import { Agent } from "@theokit/sdk";
+ *   import { Workflow, fn, agentStep } from "@theokit/sdk/workflow";
+ *
+ *   const classifier = await Agent.create({ ... });
+ *   const wf = Workflow.create({ name: "demo" })
+ *     .then(fn("validate", (input: { id: string }) => {
+ *       if (!input.id) throw new Error("missing id");
+ *       return input;
+ *     }))
+ *     .then(agentStep("classify", classifier, (i) => `Classify: ${JSON.stringify(i)}`))
+ *     .commit();
+ *
+ *   const run = await wf.run({ id: "x" });
+ *   console.log(run.status, run.output);
+ *
+ * @public
+ */
+
+declare class WorkflowBuilder<TInput = unknown, TOutput = unknown> {
+    private readonly options;
+    private readonly _steps;
+    private _committed;
+    then<TO = unknown>(step: Step): WorkflowBuilder<TInput, TO>;
+    parallel(branches: ReadonlyArray<ReadonlyArray<Step>>, opts?: {
+        id?: string;
+        concurrency?: number;
+        errorPolicy?: "fail-fast" | "collect";
+    }): WorkflowBuilder<TInput, unknown[]>;
+    branch(predicates: BranchStep["predicates"], opts?: {
+        id?: string;
+        fallback?: ReadonlyArray<Step>;
+    }): WorkflowBuilder<TInput, unknown>;
+    foreach(iterableFrom: string, step: Step, opts?: {
+        id?: string;
+        concurrency?: number;
+    }): WorkflowBuilder<TInput, unknown[]>;
+    dowhile(step: Step, condFn: DowhileStep["condFn"], opts?: {
+        id?: string;
+        maxIterations?: number;
+    }): WorkflowBuilder<TInput, unknown>;
+    sleep(durationMs: number, id?: string): WorkflowBuilder<TInput, TOutput>;
+    suspend(opts?: {
+        id?: string;
+        payloadSchema?: ZodType;
+    }): WorkflowBuilder<TInput, unknown>;
+    commit(): Workflow<TInput, TOutput>;
+    private validateUniqueIds;
+    private assertNotCommitted;
+}
+declare class Workflow<TInput = unknown, TOutput = unknown> {
+    private readonly _options;
+    private readonly _steps;
+    /**
+     * Construct a workflow builder. Validate options via Zod and return a
+     * `WorkflowBuilder` for fluent chaining. Call `.commit()` to obtain the
+     * immutable `Workflow`.
+     */
+    static create<TI = unknown, TO = unknown>(options: WorkflowOptions): WorkflowBuilder<TI, TO>;
+    /**
+     * Run this workflow with the given input. Returns a populated
+     * `WorkflowRun`. Errors inside a step DO NOT throw — they propagate via
+     * `run.status === "failed"`.
+     */
+    run(input: TInput, opts?: WorkflowRunOptions): Promise<WorkflowRun<TOutput>>;
+    /**
+     * SE28 — run the workflow and STREAM step-level events as they happen. Returns
+     * an async iterator of {@link WorkflowEvent}s (`step_started` / `step_completed`
+     * / `step_failed` / `workflow_suspended` / `workflow_completed`, top-level
+     * steps) plus a `result` promise resolving to the same terminal
+     * {@link WorkflowRun} `run()` returns. Iterate for progress; await `result` for
+     * the outcome. The stream ends when the run terminates.
+     *
+     * `result` is the AUTHORITATIVE terminal status. Not every terminal state has a
+     * closing event: a step failure emits `step_failed`, but an `outputSchema`
+     * rejection (SE27) or an abort ends the stream WITHOUT `workflow_completed` —
+     * always `await result` to read the final `status`. Consuming order is free:
+     * awaiting `result` without draining, or draining without awaiting `result`,
+     * both work (breaking out of `for await` stops the buffering early).
+     */
+    stream(input: TInput, opts?: WorkflowRunOptions): WorkflowStream<TOutput>;
+    /**
+     * Resume a suspended workflow from its snapshot. Throws
+     * `WorkflowSnapshotNotFoundError` if `runId` is unknown.
+     */
+    static resume<TO = unknown>(opts: WorkflowResumeOptions): Promise<WorkflowRun<TO>>;
+}
+
+/**
+ * Runtime hosting a cron job. Mirrors the agent runtime split.
+ *
+ * - `local` — the in-process scheduler activated via `Cron.start()` fires the
+ *   job while the host process is alive.
+ * - `cloud` — Theo PaaS schedules the job server-side; fires independent of
+ *   any SDK process.
+ *
+ * @public
+ */
+type CronRuntime = "local" | "cloud";
+/**
+ * Lifecycle state reported by `Cron.list()` / `Cron.get()`.
+ *
+ * @public
+ */
+type CronJobStatus = "scheduled" | "running" | "paused" | "errored";
+/**
+ * Persistent cron-scheduled invocation of the Theo agent or a workflow.
+ *
+ * Exactly one target is set: {@link CronJob.agent} (ephemeral agent created on
+ * each fire), {@link CronJob.agentId} (bound to an existing agent for context
+ * continuity), or {@link CronJob.workflow} (a committed workflow run per fire;
+ * SE35). Agent targets carry a `message`; a workflow target carries `inputData`.
+ *
+ * @public
+ */
+interface CronJob {
+    id: string;
+    name?: string;
+    /** Standard 5-field POSIX cron expression or shorthand (`@hourly`, `@daily`, ...). */
+    cron: string;
+    /** IANA timezone identifier. Defaults to `"UTC"`. */
+    timezone?: string;
+    /** Message sent to the agent on each fire. Present for agent targets; absent for a workflow target. */
+    message?: string | SDKUserMessage;
+    /** Ephemeral agent options. Mutually exclusive with `agentId`/`workflow`. */
+    agent?: AgentOptions;
+    /** ID of an existing agent to reuse for context continuity. Mutually exclusive with `agent`/`workflow`. */
+    agentId?: string;
+    /**
+     * SE35 — a committed {@link Workflow} run on each fire (`workflow.run(inputData)`).
+     * Mutually exclusive with `agent`/`agentId`. Held in-memory (local runtime only —
+     * a workflow instance cannot cross the cloud process boundary). ADR 0014.
+     */
+    workflow?: Workflow;
+    /** SE35 — input passed to `workflow.run(inputData)` on each fire. Workflow targets only. */
+    inputData?: unknown;
+    /** Whether the scheduler will fire this job on schedule. */
+    enabled: boolean;
+    /** Current status. */
+    status: CronJobStatus;
+    /** Runtime that hosts this job. Inferred from `agent`/`agentId`/`workflow` at create time (a `workflow` target is always `local`). */
+    runtime: CronRuntime;
+    /** Unix ms of the last successful fire, if any. */
+    lastRunAt?: number;
+    /** Unix ms of the next scheduled fire, computed by the scheduler. */
+    nextRunAt?: number;
+    /** Unix ms when the job was created. */
+    createdAt: number;
+}
+/**
+ * Options for `Cron.create()`.
+ *
+ * Pass exactly ONE target: `agent` (ephemeral agent fresh per fire), `agentId`
+ * (reuse an existing agent — preserves conversation context), or `workflow`
+ * (SE35 — run a committed workflow per fire). Agent targets REQUIRE `message`;
+ * a workflow target takes `inputData` and MUST NOT set `message`. Violations are
+ * a `ConfigurationError`.
+ *
+ * @public
+ */
+interface CronCreateOptions {
+    cron: string;
+    /** Message for an agent target. Required with `agent`/`agentId`; forbidden with `workflow`. */
+    message?: string | SDKUserMessage;
+    agent?: AgentOptions;
+    agentId?: string;
+    /** SE35 — a committed {@link Workflow} to run per fire. Mutually exclusive with `agent`/`agentId`. */
+    workflow?: Workflow;
+    /** SE35 — input for `workflow.run(inputData)`. Workflow targets only. */
+    inputData?: unknown;
+    name?: string;
+    timezone?: string;
+    /** Defaults to `true`. */
+    enabled?: boolean;
+    /** Falls back to `THEOKIT_API_KEY`. */
+    apiKey?: string;
+}
+/**
+ * Options for `Cron.list()`.
+ *
+ * @public
+ */
+type CronListOptions = {
+    limit?: number;
+    cursor?: string;
+} & ({
+    runtime?: undefined;
+} | {
+    runtime: "local";
+    cwd?: string;
+} | {
+    runtime: "cloud";
+    apiKey?: string;
+});
+/**
+ * Options for `Cron.get()`.
+ *
+ * @public
+ */
+interface CronGetOptions {
+    cwd?: string;
+    apiKey?: string;
+}
+/**
+ * Options for `Cron.delete()` / `Cron.enable()` / `Cron.disable()`.
+ *
+ * @public
+ */
+interface CronOperationOptions {
+    cwd?: string;
+    apiKey?: string;
+}
+/**
+ * Options for `Cron.run()` — manually trigger a job off-schedule.
+ *
+ * @public
+ */
+interface CronRunOptions {
+    cwd?: string;
+    apiKey?: string;
+}
+/**
+ * Options for `Cron.start()` — activates the in-process scheduler for local
+ * jobs.
+ *
+ * @public
+ */
+interface CronStartOptions {
+    /** Local workspace whose `.theokit/cron/jobs.json` to load. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Override the env API key. */
+    apiKey?: string;
+}
+/**
+ * Snapshot of the local scheduler returned by `Cron.status()`.
+ *
+ * @public
+ */
+interface CronSchedulerStatus {
+    /** Whether the in-process scheduler is currently running. */
+    running: boolean;
+    /** Number of jobs loaded into the scheduler. */
+    jobCount: number;
+    /** Unix ms of the next scheduled fire across all jobs, if any. */
+    nextFireAt?: number;
+    /** Last error observed in the scheduler, if any. */
+    lastError?: {
+        jobId: string;
+        message: string;
+        at: number;
+    };
+}
+
+/**
+ * Static façade for scheduling Theo agent runs on a cron expression.
+ *
+ * @public
+ */
+declare class Cron {
+    private constructor();
+    /**
+     * Create and persist a cron job.
+     *
+     * @public
+     */
+    static create(options: CronCreateOptions): Promise<CronJob>;
+    /**
+     * List cron jobs (local, cloud, or both).
+     *
+     * @public
+     */
+    static list(options?: CronListOptions): Promise<ListResult<CronJob>>;
+    /**
+     * Get a single cron job by ID.
+     *
+     * @public
+     */
+    static get(jobId: string, _options?: CronGetOptions): Promise<CronJob>;
+    /**
+     * Delete a cron job permanently.
+     *
+     * @public
+     */
+    static delete(jobId: string, _options?: CronOperationOptions): Promise<void>;
+    /**
+     * Re-enable a paused cron job.
+     *
+     * @public
+     */
+    static enable(jobId: string, _options?: CronOperationOptions): Promise<CronJob>;
+    /**
+     * Pause a cron job without deleting it.
+     *
+     * @public
+     */
+    static disable(jobId: string, _options?: CronOperationOptions): Promise<CronJob>;
+    /**
+     * Manually trigger a cron job off-schedule. Returns the resulting `Run`
+     * (agent target) or `WorkflowRun` (workflow target — SE35).
+     *
+     * @public
+     */
+    static run(jobId: string, _options?: CronRunOptions): Promise<Run | WorkflowRun>;
+    /**
+     * Activate the in-process scheduler for local cron jobs.
+     *
+     * @public
+     */
+    static start(options?: CronStartOptions): Promise<void>;
+    /**
+     * Stop the in-process scheduler. Jobs are preserved.
+     *
+     * @public
+     */
+    static stop(): Promise<void>;
+    /**
+     * Snapshot of the local scheduler.
+     *
+     * @public
+     */
+    static status(_options?: CronStartOptions): Promise<CronSchedulerStatus>;
+}
+
+export { type CronSchedulerStatus as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type BudgetUsageEvent as D, type CloudEnv as E, type CloudRepo as F, type GetAgentOptions as G, type ContextBudget as H, type InlineSkill as I, type ContextManagerKind as J, type ContextSnapshot as K, type LocalOptions as L, type MemorySettings as M, type ContextSource as N, type ContextSourceStatus as O, type ProviderRoutingSettings as P, type CreateSkillSpec as Q, Cron as R, type SystemPromptResolver as S, type CronCreateOptions as T, type CronGetOptions as U, type CronJob as V, type CronJobStatus as W, type CronListOptions as X, type CronOperationOptions as Y, type CronRunOptions as Z, type CronRuntime as _, type AgentDefinition as a, type CronStartOptions as a0, type HookName as a1, type InvalidateCacheOptions as a2, type MemoryAdapter as a3, type MemoryAdapterCapabilities as a4, type MemoryContext as a5, type MemoryFact as a6, type MemoryProviderHandle as a7, type MemoryProviderInitOptions as a8, type MemoryRevision as a9, type SkillsResolver as aA, type SkillsResolverContext as aB, type SystemPromptContext as aC, type SystemPromptMemoryFact as aD, type SystemPromptSkillRef as aE, type TelemetrySettings as aF, type MemoryToolSchema as aa, type MemoryTurnMessage as ab, type PersonalityPreset as ac, type PluginContext as ad, type PostAssistantReplyContext as ae, type PreToolCallContext as af, type PreUserSendContext as ag, type PreUserSendResult as ah, type ProviderCapability as ai, type ProviderRoute as aj, type ProviderTransform as ak, type ProviderTransformContext as al, type RecordSessionSummaryArgs as am, type ResolvedProviderRoute as an, type RunUntilIterator as ao, type SDKAgentPlugins as ap, type SDKAgentSkillDetail as aq, type SDKAgentSkills as ar, type SDKArtifact as as, type SDKContextManager as at, type SDKPluginMetadata as au, type SDKProvidersManager as av, type SessionRecord as aw, type SessionStore as ax, type SettingSource as ay, Skill as az, type ContextSettings as b, type PluginsSettings as c, type SkillsSettings as d, type SDKAgent as e, type ListAgentsOptions as f, type ListResult as g, type SDKAgentInfo as h, type ListRunsOptions as i, type GetRunOptions as j, type AgentOperationOptions as k, type Plugin as l, type ProviderProfile as m, type GoalOptions as n, type GoalEvent as o, type GoalResult as p, type MemoryProvider as q, type MemoryId as r, type PreToolCallDecision as s, type StepResult as t, type SDKProvider as u, type ActiveMemoryPassArgs as v, type ActiveMemoryPassResult as w, type AgentMemory as x, type BudgetCheck as y, type BudgetTotal as z };