@theokit/sdk 4.19.1 → 4.19.2

package/dist/index.d.cts

@@ -0,0 +1,2309 @@
+import { T as TheokitAgentError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot, E as ErrorMetadata } from './errors-gE8612p9.cjs';
+export { A as AgentDisposedError, c as AgentRunError, d as AgentRunErrorCode, e as AuthenticationError, f as BudgetExceedEvent, g as BudgetExceededError, h as BudgetLimit, i as BudgetMode, j as BudgetScope, k as BudgetThresholdEvent, l as BudgetWindow, C as ConfigurationError, m as ErrorCode, I as IntegrationNotConnectedError, n as InvalidTaskIdError, M as MemoryAdapterError, o as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, p as TaskNotFoundError, U as UnknownAgentError, q as UnsupportedBudgetOperationError, r as UnsupportedRunOperationError, s as UnsupportedTaskOperationError, t as isTransientError } from './errors-gE8612p9.cjs';
+import { A as AgentOptions, L as LocalOptions, P as ProviderRoutingSettings, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as ContextSettings, c as PluginsSettings, d as SkillsSettings, e as SDKAgent, f as ListAgentsOptions, g as ListResult, h as SDKAgentInfo, G as GetAgentOptions, i as ListRunsOptions, j as GetRunOptions, k as AgentOperationOptions, l as Plugin$1, m as ProviderProfile, I as InlineSkill, n as GoalOptions, o as GoalEvent, p as GoalResult, B as BudgetTracker, q as MemoryProvider, r as MemoryId, s as PreToolCallDecision, t as StepResult, u as SDKProvider } from './cron-M2Xz7lq2.cjs';
+export { v as ActiveMemoryPassArgs, w as ActiveMemoryPassResult, x as AgentMemory, y as BudgetCheck, z as BudgetTotal, D as BudgetUsageEvent, E as CloudEnv, F as CloudRepo, H as ContextBudget, J as ContextManagerKind, K as ContextSnapshot, N as ContextSource, O as ContextSourceStatus, Q as CreateSkillSpec, R as Cron, T as CronCreateOptions, U as CronGetOptions, V as CronJob, W as CronJobStatus, X as CronListOptions, Y as CronOperationOptions, Z as CronRunOptions, _ as CronRuntime, $ as CronSchedulerStatus, a0 as CronStartOptions, a1 as HookName, a2 as InvalidateCacheOptions, a3 as MemoryAdapter, a4 as MemoryAdapterCapabilities, a5 as MemoryContext, a6 as MemoryFact, a7 as MemoryProviderHandle, a8 as MemoryProviderInitOptions, a9 as MemoryRevision, aa as MemoryToolSchema, ab as MemoryTurnMessage, ac as PersonalityPreset, ad as PluginContext, ae as PostAssistantReplyContext, af as PreToolCallContext, ag as PreUserSendContext, ah as PreUserSendResult, ai as ProviderCapability, aj as ProviderRoute, ak as ProviderTransform, al as ProviderTransformContext, am as RecordSessionSummaryArgs, an as ResolvedProviderRoute, ao as RunUntilIterator, ap as SDKAgentPlugins, aq as SDKAgentSkillDetail, ar as SDKAgentSkills, as as SDKArtifact, at as SDKContextManager, au as SDKPluginMetadata, av as SDKProvidersManager, aw as SessionRecord, ax as SessionStore, ay as SettingSource, az as Skill, aA as SkillsResolver, aB as SkillsResolverContext, aC as SystemPromptContext, aD as SystemPromptMemoryFact, aE as SystemPromptSkillRef, aF as TelemetrySettings } from './cron-M2Xz7lq2.cjs';
+import { R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, b as Run, P as Processor, T as ToolResultContentBlock, c as PermissionMode, d as PermissionEngine, e as RunEventSink, S as SDKMessage } from './run-DFM1H2jW.cjs';
+export { A as AgentConversationTurn, f as AssistantMessage, g as CompletionCheck, h as CompletionCheckResult, i as ConversationStep, j as ConversationTurn, k as CostBreakdown, l as CostSource, m as CostStatus, D as DoomLoopThresholds, G as GenerateOptions, n as GenerateRunResult, I as ImageBlock, o as InputProcessorContext, p as InteractionUpdate, q as McpAuthConfig, r as McpHttpServerConfig, s as McpOAuthConfig, t as McpStdioServerConfig, u as MessageOrigin, v as ModelParameterValue, O as OutputProcessorContext, w as PartialToolCallUpdate, x as PermissionAction, y as PermissionEngineOptions, z as PermissionRule, B as ProcessorControls, E as ProcessorTripwire, F as ProcessorViolation, H as RunCompactBoundaryEvent, J as RunCompletionCheckEvent, K as RunErrorDetail, L as RunEvent, N as RunGitInfo, Q as RunOperation, U as RunPermissionDeniedEvent, V as RunRateLimitEvent, W as RunStatus, X as RunTaskCompletedEvent, Y as RunTaskStartedEvent, Z as RunTaskUpdatedEvent, _ as RunToCompletionOptions, $ as RunToCompletionResult, a0 as RunToolProgressEvent, a1 as RunTripwireEvent, a2 as SDKAssistantMessage, a3 as SDKImage, a4 as SDKImageDimension, a5 as SDKObjectDelta, a6 as SDKRequestMessage, a7 as SDKStatusMessage, a8 as SDKSystemMessage, a9 as SDKTaskMessage, aa as SDKThinkingMessage, ab as SDKToolUseMessage, ac as SDKUserMessage, ad as SDKUserMessageEvent, ae as SendOptions, af as ShellCommand, ag as ShellConversationTurn, ah as ShellOutput, ai as ShellOutputDeltaUpdate, aj as StepCompletedUpdate, ak as StepStartedUpdate, al as StreamToCompletionResult, am as SummaryCompletedUpdate, an as SummaryStartedUpdate, ao as SummaryUpdate, ap as TextBlock, aq as TextDeltaUpdate, ar as ThinkingCompletedUpdate, as as ThinkingDeltaUpdate, at as ThinkingMessage, au as TokenDeltaUpdate, av as TokenUsage, aw as ToolCall, ax as ToolCallCompletedUpdate, ay as ToolCallStartedUpdate, az as ToolContextMessage, aA as ToolResult, aB as ToolResultGuardOptions, aC as ToolUseBlock, aD as TurnEndedUpdate, aE as UserMessage, aF as UserMessageAppendedUpdate, aG as applyMode, aH as emitRunEvent } from './run-DFM1H2jW.cjs';
+import * as zod from 'zod';
+import { ZodType, z } from 'zod';
+
+/**
+ * Public compaction / context-management helpers (M2-1, extended V3-3).
+ *
+ * Promotes the SDK's compaction capability to a public surface so consumers can
+ * compact a transcript, mark/filter conversation checkpoints, and detect
+ * context-overflow — without reaching into `internal/`.
+ *
+ * Two recent-window modes (V3-3):
+ *  - `keepRecent` (turn-count, default) — keeps the last N turns verbatim and
+ *    always preserves leading system PROMPTS; reuses the internal
+ *    `selectCompressionWindow` (no second algorithm).
+ *  - `keepTokens` (token-budget) — keeps the trailing turns whose accumulated
+ *    `estimateTokens` fits the budget (theocode `splitTranscript` semantics). In
+ *    this mode leading system prompts are NOT special-cased (D6).
+ *
+ * Summarization is delegated to a caller-supplied callback (which receives the
+ * older window + the summary template). With `failSafe`, a thrown summarizer
+ * returns the ORIGINAL transcript + a structured warn (compaction is an
+ * optimization, never a cause of data loss); without it, the error propagates.
+ *
+ * Public from the `@theokit/sdk/compaction` sub-path.
+ */
+/**
+ * Minimal message shape for compaction/compression input. THE canonical public origin (leaf type —
+ * rollup-plugin-dts cannot re-export types from internal modules into entry bundles; M42 lesson).
+ *
+ * @public
+ */
+interface CompressibleMessage {
+    role: "user" | "assistant" | "system";
+    content: string;
+}
+
+/**
+ * M50 (agent-builder) — session-transcript compaction, Codex-faithful.
+ *
+ * Mirrors the vendored Codex mechanism (`codex-rs/core/src/compact.rs`):
+ *   - the replacement history = recent USER messages verbatim (newest→oldest under a token budget;
+ *     prior summaries filtered by marker) + ONE summary message with a textual marker prefix,
+ *     injected as `role:"user"` (`build_compacted_history`, compact.rs:589-663);
+ *   - persistence is APPEND-ONLY: a `compact_boundary` record becomes the new DAG root and the
+ *     replacement messages are chained onto it — resume replays boundary→replacement→suffix
+ *     (equivalent of `CompactedItem.replacement_history`, rollout is never truncated);
+ *   - a failing summarizer leaves the transcript UNTOUCHED (typed error; no partial state).
+ *
+ * The summarizer is dependency-injected: tests pass a deterministic fake; the public
+ * `Agent.compact` wires the ADR-D440 compression summarizer (its first real caller).
+ */
+
+interface CompactResult {
+    preTokens: number;
+    postTokens: number;
+}
+
+/**
+ * Public types for `Agent.batch` (ADRs D134-D140).
+ *
+ * Run N prompts in parallel with bounded concurrency. Each prompt gets
+ * a fresh agent (create → send → wait → dispose). Failures isolated
+ * per-prompt; the batch never aborts on a single failure.
+ *
+ * @public
+ */
+
+/**
+ * Single prompt in a batch. Plain string is shorthand for `{ prompt }`.
+ *
+ * @public
+ */
+interface BatchItem {
+    /** Prompt text sent to the agent. */
+    prompt: string;
+    /** Per-prompt system prompt override (wins over `BatchOptions.systemPrompt`). */
+    systemPrompt?: string;
+    /**
+     * Caller-supplied metadata, round-tripped to `BatchResult.metadata`.
+     * Passed by reference — do NOT mutate while the batch is in-flight (EC-I).
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options accepted by `Agent.batch`. Extends `AgentOptions` — every
+ * prompt gets an agent created with these options (ADR D138 isolation),
+ * plus the batch-specific knobs below.
+ *
+ * @public
+ */
+interface BatchOptions extends AgentOptions {
+    /**
+     * Maximum parallel agents. Default 4 (ADR D136). Must be a positive
+     * integer. Capped to `prompts.length` to avoid spinning idle workers.
+     */
+    concurrency?: number;
+    /** Optional filter applied post-collection. Return `false` to discard. */
+    filter?: (result: BatchResult) => boolean;
+    /**
+     * Streaming callback fired once per completed prompt (success OR failure).
+     * Caller exceptions are caught + logged to stderr without poisoning
+     * the batch (EC-5).
+     */
+    onResult?: (result: BatchResult) => void | Promise<void>;
+    /** Progress callback fired after each result. */
+    onProgress?: (progress: BatchProgress) => void;
+    /**
+     * Cancel pending prompts (ADR D140). In-flight prompts continue to
+     * completion (Node `AbortSignal` semantics). When `signal.reason` is
+     * an Error, it propagates to `BatchResult.error`; otherwise a generic
+     * "aborted" error is used.
+     */
+    signal?: AbortSignal;
+    /**
+     * Opt-in Task wrapping (ADRs D363, D374). When set, the batch is
+     * registered as a `Task` (kind="batch") in the SDK's observable
+     * registry. The parent task transitions `finished` when every
+     * prompt is resolved (success OR failure).
+     *
+     * Use cases: surfacing a long-running batch in the `theokit tasks
+     * list` CLI, programmatic `Task.cancel(id)` aborting the batch, or
+     * binding a user-facing job dashboard. v1 does NOT yet emit one
+     * task PER prompt (single parent only); per-prompt tasks land in
+     * v0.2.
+     *
+     * Auto-generated id uses the `b-` reserved prefix (D368, EC-5).
+     *
+     * @public
+     */
+    task?: true | {
+        id?: string;
+        meta?: Record<string, unknown>;
+    };
+}
+/**
+ * Per-prompt outcome. Discriminated union — check `ok` before reading
+ * `result` or `error`.
+ *
+ * @public
+ */
+type BatchResult = {
+    ok: true;
+    index: number;
+    prompt: string;
+    result: RunResult;
+    metadata?: Record<string, unknown>;
+    durationMs: number;
+} | {
+    ok: false;
+    index: number;
+    prompt: string;
+    error: TheokitAgentError;
+    metadata?: Record<string, unknown>;
+    durationMs: number;
+};
+/**
+ * Live progress snapshot delivered to `onProgress`.
+ *
+ * @public
+ */
+interface BatchProgress {
+    total: number;
+    completed: number;
+    failed: number;
+    pending: number;
+    inFlight: number;
+}
+
+/**
+ * Options accepted by {@link Agent.streamObject}. Same shape as
+ * `Agent.generateObject` with the addition that the result is an
+ * `AsyncIterator<StreamObjectEvent<T>>` rather than a single Promise. See ADR D39.
+ *
+ * @public
+ */
+interface StreamObjectOptions<T extends ZodType> {
+    schema: T;
+    prompt: string;
+    systemPrompt?: string;
+    /** SE8 — accepts a bare-string id shorthand or a {@link ModelSelection}. */
+    model: string | ModelSelection;
+    apiKey?: string;
+    local: LocalOptions;
+    maxRetries?: number;
+    /**
+     * Optional provider routing forwarded to the transient agent. Required when
+     * `model.id` uses a prefix (e.g. `openai/gpt-4o-mini`) but the credential is
+     * for a unified gateway (e.g. OpenRouter). Without this, the SDK infers
+     * provider from the prefix and may fail with `provider_unresolved` even
+     * when the right env key is set under a different provider name.
+     */
+    providers?: ProviderRoutingSettings;
+}
+/**
+ * Recursive partial — `T` where every nested field becomes optional.
+ *
+ * @public
+ */
+type DeepPartial<T> = T extends (infer U)[] ? Array<DeepPartial<U>> : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+/**
+ * Event emitted by {@link Agent.streamObject}. Discriminate on `type`.
+ *
+ * - `partial` events fire zero or more times with monotonically increasing
+ *   `attempt`, carrying best-effort schema-parsed snapshots of the model's
+ *   accumulating output.
+ * - `complete` fires exactly once at the end, carrying the fully Zod-parsed
+ *   object alongside usage and finishReason — semantically identical to a
+ *   successful `Agent.generateObject()` return.
+ *
+ * @public
+ */
+type StreamObjectEvent<T> = {
+    type: "partial";
+    partial: DeepPartial<T>;
+    attempt: number;
+} | {
+    type: "complete";
+    object: T;
+    raw: unknown;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    finishReason: "tool_use" | "error";
+};
+/**
+ * Error thrown by {@link Agent.streamObject} when the model refuses to call
+ * the synthetic `output` tool or when all retries fail to produce a
+ * schema-valid object. Same code taxonomy as `GenerateObjectError`.
+ *
+ * @public
+ */
+declare class StreamObjectError extends Error {
+    readonly name = "StreamObjectError";
+    readonly code: "no_tool_call" | "parse_failed";
+    readonly cause?: unknown;
+    constructor(code: "no_tool_call" | "parse_failed", message: string, cause?: unknown);
+}
+
+/**
+ * Options accepted by {@link Agent.generateObject}. Returns a typed object
+ * matching the supplied Zod schema. See ADR D33.
+ *
+ * @public
+ */
+interface GenerateObjectOptions<T extends ZodType> {
+    /** Zod schema describing the expected object shape. */
+    schema: T;
+    /** User prompt — the model is asked to fill the schema given this prompt. */
+    prompt: string;
+    /** Optional system prompt steering the model. */
+    systemPrompt?: string;
+    /** Model selection. Required (transient agents need a model). SE8 — accepts a
+     *  bare-string id shorthand (`"openai/gpt-4o-mini"`) or a {@link ModelSelection}. */
+    model: string | ModelSelection;
+    /**
+     * M21 — optional separate model for the STRUCTURING step. When set, `model` first produces a
+     * free-text reasoned answer to the prompt (phase 1), then `structuringModel` extracts the
+     * schema-matched object by calling the `output` tool over that answer (phase 2). Lets a large
+     * model reason while a cheap fast model does the extraction. Absent ⇒ today's single-model flow.
+     */
+    structuringModel?: string | ModelSelection;
+    /** API key. Falls back to env (THEOKIT_API_KEY etc). */
+    apiKey?: string;
+    /** Local runtime config (cwd, sandbox). Required to keep the transient agent local-only. */
+    local: LocalOptions;
+    /**
+     * Retry budget on parse failures. Default 1 (initial attempt + 1 retry).
+     * The transient agent is REUSED across retries so the registry sees a
+     * single entry (EC-3).
+     */
+    maxRetries?: number;
+    /**
+     * Optional provider routing forwarded to the transient agent. Required when
+     * `model.id` uses a prefix (e.g. `openai/gpt-4o-mini`) but the credential is
+     * for a unified gateway (e.g. OpenRouter). Without this, the SDK infers
+     * provider from the prefix and may fail with `provider_unresolved` even
+     * when the right env key is set under a different provider name.
+     */
+    providers?: ProviderRoutingSettings;
+    /**
+     * What to do when the model's output fails schema validation after all
+     * retries are exhausted (M14):
+     * - `'throw'` (default) — throw {@link GenerateObjectError} `parse_failed`.
+     * - `'return-raw'` — resolve with the raw, UNVALIDATED input the model sent
+     *   (`object` may not match the schema; inspect `raw` too).
+     * - `'return-partial'` — for object schemas, resolve with only the fields that
+     *   individually validate (best-effort salvage); non-object schemas fall back
+     *   to raw.
+     */
+    errorStrategy?: "throw" | "return-partial" | "return-raw";
+}
+/**
+ * Successful return from {@link Agent.generateObject}.
+ *
+ * @public
+ */
+interface GenerateObjectResult<T> {
+    /** Typed object parsed via the Zod schema. */
+    object: T;
+    /** Raw input the model passed to the synthetic tool, before Zod parse. */
+    raw: unknown;
+    /** Token usage of the LLM call(s) that produced the result. */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    /** Stop reason of the underlying agent run. */
+    finishReason: "tool_use" | "error";
+}
+/**
+ * Typed error thrown by {@link Agent.generateObject} when the model refuses
+ * to call the synthetic `output` tool or when retries are exhausted.
+ *
+ * @public
+ */
+declare class GenerateObjectError extends Error {
+    readonly name = "GenerateObjectError";
+    readonly code: "no_tool_call" | "parse_failed";
+    readonly cause?: unknown;
+    constructor(code: "no_tool_call" | "parse_failed", message: string, cause?: unknown);
+}
+
+/**
+ * Fluent builder for {@link AgentOptions}. Chainable setters mutate internal
+ * state and return `this`. Three terminals:
+ *
+ * - `.build()` — synchronous snapshot (shallow clone) of accumulated options.
+ * - `.create()` — calls the injected `create` (Agent.create).
+ * - `.getOrCreate(agentId)` — calls the injected `getOrCreate` (Agent.getOrCreate).
+ *
+ * Validation runs inside the terminals via `validateAgentOptions`. See ADR D25.
+ *
+ * @public
+ */
+declare class AgentBuilder {
+    private opts;
+    private readonly deps;
+    constructor(deps?: AgentBuilderDeps);
+    /** SE8 — accepts a bare-string id shorthand (`"openai/gpt-4o-mini"`) or a {@link ModelSelection}. */
+    model(m: string | ModelSelection): this;
+    apiKey(k: string): this;
+    name(n: string): this;
+    systemPrompt(p: string | SystemPromptResolver): this;
+    local(l: LocalOptions): this;
+    cloud(c: CloudOptions): this;
+    memory(m: MemorySettings): this;
+    tools(t: CustomTool[]): this;
+    mcpServers(s: Record<string, McpServerConfig>): this;
+    agents(a: Record<string, AgentDefinition>): this;
+    context(c: ContextSettings): this;
+    providers(p: ProviderRoutingSettings): this;
+    plugins(p: PluginsSettings): this;
+    skills(s: SkillsSettings): this;
+    agentId(id: string): this;
+    /**
+     * Synchronous snapshot of the accumulated options. Returns a SHALLOW CLONE
+     * so external mutation of the result doesn't pollute the builder state (EC-2).
+     */
+    build(): AgentOptions;
+    /**
+     * Validate + create a fresh agent. Delegates to `Agent.create` via the
+     * injected `deps.create`. Throws if the builder was instantiated without
+     * deps (i.e., direct `new AgentBuilder()` instead of `Agent.builder()`).
+     */
+    create(): Promise<SDKAgent>;
+    /**
+     * Resume an existing agent or create one if the ID is unknown. Delegates to
+     * `Agent.getOrCreate` via the injected `deps.getOrCreate` (ADR D22).
+     */
+    getOrCreate(agentId: string): Promise<SDKAgent>;
+}
+
+/**
+ * Live-agent cache for production deploys (Production-Readiness #2, ADRs D307-D310).
+ *
+ * Caches `SDKAgent` instances by id with LRU eviction (when `size > maxAgents`)
+ * and an idle-timeout sweep (configurable interval, default 60s). Solves the
+ * "OOM at some point" failure mode of long-running Node servers that keep
+ * spawning fresh agents per conversation.
+ *
+ * **Distinct from `agent-registry.ts`** (the metadata registry that persists
+ * `RegisteredAgent` to `registry.json` per cwd). That module is the "address
+ * book"; this module is the "live cache". Conflating them violates SRP — see
+ * ADR D307.
+ *
+ * Defaults (ADR D308): `maxAgents: 100`, `idleTimeoutMs: 30 min`, sweep `60s`.
+ * Calibrated for indie/small-team Node deploys; high-traffic SaaS should
+ * `configure({ maxAgents: 1000 })`.
+ *
+ * @public (singleton exposed via `Agent.registry`)
+ */
+
+type EvictReason = "lru" | "idle" | "explicit";
+interface AgentRegistryOptions {
+    /**
+     * Maximum number of agents kept alive simultaneously. LRU eviction when
+     * exceeded. Default: 100.
+     *
+     * Setting `0` disables the cache entirely — every `Agent.getOrCreate`
+     * re-initializes (high cost, but predictable memory).
+     */
+    maxAgents?: number;
+    /**
+     * Idle timeout in milliseconds. Agents not used for this duration are
+     * evicted on the next sweep tick. Default: 1_800_000 (30 minutes).
+     * Set `0` to disable idle eviction.
+     */
+    idleTimeoutMs?: number;
+    /**
+     * Sweep interval in milliseconds. Default: 60_000 (60s).
+     * Lower = more responsive eviction but more CPU. Higher = staler entries.
+     */
+    sweepIntervalMs?: number;
+    /**
+     * Called whenever an agent is evicted. Listener errors are swallowed
+     * with a one-shot stderr warn (do not crash the eviction loop).
+     */
+    onEvict?: (id: string, reason: EvictReason) => void;
+}
+declare class LiveAgentRegistry {
+    #private;
+    /**
+     * Reconfigure registry behavior. Process-wide singleton (D310) — last
+     * configure call wins for all subsequent operations.
+     */
+    configure(opts: AgentRegistryOptions): void;
+    /**
+     * Lookup a cached agent. `get` is a use — refreshes `lastUsedAt` so the
+     * entry survives LRU eviction.
+     */
+    get(id: string): SDKAgent | undefined;
+    /**
+     * Insert or overwrite an agent in the cache. Triggers fire-and-forget LRU
+     * eviction when `size > maxAgents`.
+     *
+     * EC-4: when `id` already maps to a DIFFERENT agent instance, dispose the
+     * old one before overwriting (race protection against two `getOrCreate`
+     * calls creating two agents but only the second being cached — the first
+     * would leak file handles + lifecycle controllers).
+     */
+    set(id: string, agent: SDKAgent): void;
+    /**
+     * Explicitly evict an agent by id. Returns `true` when the entry was
+     * present (false = already gone). Calls `agent.dispose()` + `onEvict`
+     * with reason `"explicit"`.
+     */
+    evict(id: string): Promise<boolean>;
+    /**
+     * Evict every cached agent. Used by graceful shutdown (`process.on('SIGTERM')`)
+     * or end-of-test cleanup.
+     */
+    evictAll(): Promise<void>;
+    /** Number of currently cached agents. */
+    size(): number;
+    /** Ids of cached agents, newest first (by lastUsedAt). */
+    ids(): readonly string[];
+}
+
+/**
+ * Result of a one-shot {@link Agent.prompt} call.
+ *
+ * @public
+ */
+type AgentPromptResult = RunResult;
+/**
+ * Static façade for creating and managing Theo agents.
+ *
+ * @public
+ */
+declare class Agent {
+    private constructor();
+    /**
+     * Live-agent cache for production deploys (Production-Readiness #2, ADRs D307-D310).
+     *
+     * Caches `SDKAgent` instances by id with LRU eviction (when `size > maxAgents`)
+     * and an idle-timeout sweep. Solves the OOM failure mode for long-running
+     * Node servers spawning fresh agents per conversation.
+     *
+     * Defaults: `maxAgents: 100`, `idleTimeoutMs: 30 min`, sweep `60s`.
+     * Configure for high-traffic SaaS:
+     *
+     * ```ts
+     * Agent.registry.configure({ maxAgents: 1000, idleTimeoutMs: 15 * 60_000 });
+     * process.on("SIGTERM", () => Agent.registry.evictAll());
+     * ```
+     *
+     * Cache hits are automatic in `Agent.getOrCreate` (T2.6). Disable the cache
+     * entirely via `configure({ maxAgents: 0 })` — every getOrCreate then
+     * re-initializes.
+     *
+     * @public
+     */
+    static readonly registry: LiveAgentRegistry;
+    /**
+     * Create a new agent. Pass either `local` or `cloud` to pick a runtime.
+     *
+     * @public
+     */
+    static create(options: AgentOptions): Promise<SDKAgent>;
+    /**
+     * One-shot prompt: create an agent, send a single message, wait, dispose.
+     *
+     * When `options.throwOnError === true`, rejects with `AgentRunError` if
+     * the run terminates with `status: 'error'` (instead of resolving with the
+     * error wrapped in the RunResult). Cancelled runs still resolve normally.
+     *
+     * @public
+     */
+    static prompt(message: string, options: AgentOptions): Promise<AgentPromptResult>;
+    /**
+     * Reattach to an existing agent by ID.
+     *
+     * @public
+     */
+    static resume(agentId: string, options?: Partial<AgentOptions>): Promise<SDKAgent>;
+    /**
+     * Start building an {@link AgentOptions} via fluent chain. See ADR D25.
+     * Terminals: `.build()`, `.create()`, `.getOrCreate(id)`.
+     *
+     * The builder receives `create` + `getOrCreate` as injected callbacks so
+     * that `agent-builder.ts` doesn't need a static import of `Agent` — keeps
+     * the module graph acyclic (G6).
+     *
+     * @public
+     */
+    static builder(): AgentBuilder;
+    /**
+     * Generate a typed object matching a Zod schema via a synthetic forced
+     * tool call (ADR D33). One-shot: create transient agent → send prompt →
+     * model calls `output` tool → parse args via Zod → return typed.
+     *
+     * @public
+     */
+    static generateObject<T extends zod.ZodType>(options: GenerateObjectOptions<T>): Promise<GenerateObjectResult<zod.z.infer<T>>>;
+    /**
+     * Stream a structured output object alongside intermediate `partial`
+     * deltas as the model accumulates its response (ADR D39). Returns an
+     * `AsyncIterator<StreamObjectEvent<T>>` that yields zero or more
+     * `partial` events and exactly one `complete` event at the end.
+     *
+     * The `complete` event carries the same `object: z.infer<T>` you would get
+     * from `Agent.generateObject` — same prompt + schema + model produces
+     * the same final object.
+     *
+     * @public
+     */
+    static streamObject<T extends zod.ZodType>(options: StreamObjectOptions<T>): AsyncGenerator<StreamObjectEvent<zod.z.infer<T>>, void, void>;
+    /**
+     * Run N prompts in parallel with bounded concurrency (ADRs D134-D140).
+     *
+     * Each prompt gets a fresh agent (create → send → wait → dispose). Failures
+     * are isolated per-prompt; the batch never throws on a single failure —
+     * inspect `result.ok` to discriminate success vs error. Default
+     * concurrency is 4. When `options.providers.apiKeys` has ≥2 keys per
+     * provider, all in-flight agents share a single credential pool via
+     * `AsyncLocalStorage` (EC-A) so rate-limit cooldowns are observed once
+     * instead of duplicated per agent.
+     *
+     * Streaming progress is opt-in via `onResult` / `onProgress`. `AbortSignal`
+     * cancels pending prompts; in-flight ones continue to completion (Node
+     * AbortSignal semantics). `signal.reason` propagates to `error` when set.
+     *
+     * @public
+     */
+    static batch(prompts: ReadonlyArray<string | BatchItem>, options: BatchOptions): Promise<BatchResult[]>;
+    /**
+     * Get an existing agent by ID, or create one with the supplied options if
+     * the ID is not yet registered. Eliminates the resume-vs-create boilerplate
+     * common to chat bots and other long-running agent consumers. See ADR D22.
+     *
+     * Resolution:
+     * 1. Try `Agent.resume(agentId, options)`. Return on success.
+     * 2. On `UnknownAgentError`, fall through to `Agent.create({ ...options, agentId })`.
+     * 3. On same-process race (`ConfigurationError(code: "agent_id_already_exists")`
+     *    during step 2), retry `Agent.resume` once and return the winner's handle.
+     * 4. Any other error propagates verbatim.
+     *
+     * Caveats:
+     * - The function-level `agentId` always wins over `options.agentId`.
+     * - Options differ between calls? Last-call-wins for this handle (matches `Agent.resume`).
+     * - Disposed agents are NOT auto-deleted from the registry. To force a fresh
+     *   agent, call `Agent.delete(agentId)` first.
+     *
+     * @public
+     */
+    static getOrCreate(agentId: string, options: AgentOptions): Promise<SDKAgent>;
+    /**
+     * List agents (local or cloud).
+     *
+     * @public
+     */
+    static list(options?: ListAgentsOptions): Promise<ListResult<SDKAgentInfo>>;
+    /**
+     * Get metadata for a single agent.
+     *
+     * @public
+     */
+    static get(agentId: string, _options?: GetAgentOptions): Promise<SDKAgentInfo>;
+    /**
+     * List runs for an agent.
+     *
+     * @public
+     */
+    static listRuns(agentId: string, _options?: ListRunsOptions): Promise<ListResult<Run>>;
+    /**
+     * Get a single run.
+     *
+     * @public
+     */
+    static getRun(runId: string, options?: GetRunOptions): Promise<Run>;
+    /**
+     * Archive a cloud agent.
+     *
+     * @public
+     */
+    static archive(agentId: string, _options?: AgentOperationOptions): Promise<void>;
+    /**
+     * Restore an archived cloud agent.
+     *
+     * @public
+     */
+    static unarchive(agentId: string, _options?: AgentOperationOptions): Promise<void>;
+    /**
+     * Set the human-facing `name` of a registered agent (the label `Agent.list()` returns). The registry
+     * already carries a `name` field; this is the missing public mutator for it. Runtime-agnostic (mutates
+     * the local per-cwd registry for local agents; the cloud registry for cloud agents).
+     *
+     * @public
+     */
+    static rename(agentId: string, name: string, _options?: AgentOperationOptions): Promise<void>;
+    /**
+     * M50 — compact a LOCAL agent's persisted session transcript (Codex `/compact` parity): the
+     * history is summarized (recent user messages preserved verbatim + one marker'd summary) and an
+     * append-only `compact_boundary` + replacement chain is written — resume replays only the
+     * replacement + later turns. The summarizer defaults to the compression subsystem's aux-LLM
+     * (its first real caller); tests/consumers may inject their own.
+     *
+     * @public
+     */
+    static compact(agentId: string, options?: {
+        trigger?: "manual" | "auto";
+        summarize?: (messages: readonly CompressibleMessage[]) => Promise<string>;
+    }): Promise<CompactResult>;
+    /**
+     * M51 — inject a SYNTHETIC user+assistant pair into a LOCAL session's persisted transcript WITHOUT
+     * running an LLM turn (the Codex review-exit mechanism: the parent thread "learns" a result — e.g.
+     * review findings — so follow-ups work). Appends onto the DAG leaf and invalidates the in-memory
+     * cache; serialized on the per-agent write chain.
+     *
+     * @public
+     */
+    static injectSessionTurn(agentId: string, turn: {
+        userText: string;
+        assistantText: string;
+    }): Promise<void>;
+    /**
+     * Permanently delete a cloud agent.
+     *
+     * @public
+     */
+    static delete(agentId: string, _options?: AgentOperationOptions): Promise<void>;
+}
+
+/**
+ * Handle returned by {@link createAgentFactory}. See ADR D23 for merge
+ * semantics.
+ *
+ * @public
+ */
+interface AgentFactory {
+    /**
+     * Create a fresh agent for this session. Equivalent to `Agent.create(merged)`
+     * where `merged` is `common` ⊕ `overrides` ⊕ `{ agentId }`.
+     */
+    forSession(agentId: string, overrides?: Partial<AgentOptions>): Promise<SDKAgent>;
+    /**
+     * Resume an existing agent for this session, or create one if the ID is
+     * unknown. Equivalent to `Agent.getOrCreate(agentId, merged)`.
+     */
+    getOrCreate(agentId: string, overrides?: Partial<AgentOptions>): Promise<SDKAgent>;
+}
+/** SE36 — `AgentFactory.create` replaces `createAgentFactory` (ADR 0015). Merges with the `AgentFactory` interface. @public */
+declare class AgentFactory {
+    private constructor();
+    static create(common: Partial<AgentOptions>): AgentFactory;
+}
+
+/**
+ * computeCost — apply pricing entries to a TokenUsage and produce a
+ * CostBreakdown (ADRs D377, D378).
+ *
+ * Edge cases absorbed:
+ *   - EC-13: negative pricing → status="unknown" + note.
+ *   - EC-14: reasoning tokens fall back to outputCostPerMillion when
+ *     dedicated reasoning rate is undefined.
+ *   - EC-12: money precision via microcent normalization (× 1e6).
+ *   - "subscription_included" routes (Codex CLI, future Claude Pro) →
+ *     return $0 with status="included".
+ *   - Provider unknown / pricing missing → status="unknown" with
+ *     undefined amountUsd (NÃO retorna 0 falso).
+ *
+ * @internal
+ */
+interface ComputeArgs {
+    readonly usage: TokenUsage;
+    readonly provider: string;
+    readonly model: string;
+    readonly baseUrl?: string;
+}
+/**
+ * Returns CostBreakdown with `status="estimated"`, `"unknown"`, or
+ * `"included"`. Never throws; never returns 0 when pricing is missing.
+ */
+declare function computeCost(args: ComputeArgs): CostBreakdown;
+
+/**
+ * Budget enforcement (ADRs D383, D386, EC-7/8/9).
+ *
+ * - `preflightCheck(name, estimatedUsd)` — em `block` mode, throw
+ *   `BudgetExceededError` antes da LLM call se qualquer limit seria
+ *   excedido (EC-9 — caller chama dentro do mutex section).
+ * - `chargeAndCheckThresholds(name, actualUsd)` — apply charge ao
+ *   ledger + invoca onThreshold/onExceed callbacks isolated em
+ *   try/catch (EC-8).
+ *
+ * @internal
+ */
+/**
+ * Throws BudgetExceededError if `mode === "block"` and any limit
+ * would be exceeded. No-op for audit/warn modes (post-charge checks
+ * handle those).
+ *
+ * Caller invokes this BEFORE the LLM call.
+ */
+declare function preflightCheck(name: string, estimatedUsd: number): void;
+/**
+ * Charge the budget + dispatch threshold/exceed callbacks (EC-8 isolated).
+ *
+ * - In `audit` mode: charge only, no callbacks.
+ * - In `warn` mode: charge + onThreshold (80/95) + onExceed (100). No throw.
+ * - In `block` mode: charge + onThreshold + onExceed. No throw post-call
+ *   (preflightCheck already prevented exceed for the upcoming call;
+ *   this protects against simultaneous-call races where multiple sends
+ *   each pass preflight independently — last one to charge may still
+ *   tip a limit. We document the case rather than retroactively throw).
+ */
+declare function chargeAndCheckThresholds(name: string, actualUsd: number): Promise<void>;
+
+/**
+ * normalizeUsage — convert provider-shaped raw `usage` object to
+ * canonical `TokenUsage`. Ports Hermes Agent's `normalize_usage`
+ * (referencia/peer-agent/agent/usage_pricing.py:672-742).
+ *
+ * Handles 3 API shapes:
+ *   - Anthropic Messages: 4 explicit buckets (input/output/cache_read/cache_creation).
+ *   - OpenAI Chat Completions: prompt_tokens INCLUDES cache; subtract cached_tokens.
+ *   - OpenAI Responses (Codex): input_tokens INCLUDES cache; same subtraction.
+ *
+ * Edge cases:
+ *   - a peer#10266 — OpenAI-compat proxies (OpenRouter, a peer vendor AI Gateway,
+ *     a peer) routing Claude expose Anthropic-style top-level fields
+ *     (cache_read_input_tokens / cache_creation_input_tokens). Both
+ *     locations are checked with top-level fallback.
+ *   - Null/undefined fields → 0 via `int()` coerce.
+ *   - String token counts → parsed via int.
+ *   - Negative values → clamped to 0 (defensive against proxy bugs).
+ *
+ * @internal
+ */
+type ApiMode = "anthropic_messages" | "openai_chat_completions" | "openai_responses";
+declare function inferApiMode(provider: string): ApiMode;
+declare function normalizeUsage(rawUsage: unknown, opts: {
+    provider: string;
+    apiMode?: ApiMode;
+}): TokenUsage;
+
+/**
+ * Pricing registry — bundled snapshot of LiteLLM JSON (ADR D379) with
+ * lazy load + alias normalization (EC-2).
+ *
+ * Snapshot lives in `pricing-data.json` (hand-curated 2026-05; refresh
+ * via `scripts/refresh-pricing.mjs`). All rates in USD per 1_000_000
+ * tokens (D378).
+ *
+ * Lookup precedence (EC-2):
+ *   1. Direct `provider/model` key
+ *   2. Strip date suffix (-YYYYMMDD or -YYYY-MM-DD)
+ *   3. Anthropic dot-to-dash normalization (claude-opus-4.7 → claude-opus-4-7)
+ *   4. Strip `openrouter/` prefix
+ *
+ * @internal
+ */
+interface PricingEntry {
+    readonly provider: string;
+    readonly model: string;
+    readonly inputCostPerMillion: number;
+    readonly outputCostPerMillion: number;
+    readonly cacheReadCostPerMillion?: number;
+    readonly cacheWriteCostPerMillion?: number;
+    readonly reasoningCostPerMillion?: number;
+    readonly pricingVersion: string;
+}
+/**
+ * Returns the pricing entry for a given `{provider, model}` route.
+ * Tries direct lookup, then 3 alias normalizations (EC-2).
+ */
+declare function getPricingEntry(opts: {
+    provider: string;
+    model: string;
+    baseUrl?: string;
+}): PricingEntry | undefined;
+
+/**
+ * UsageAccumulator — aggregate multi-step `LlmFinish` token counts
+ * into a canonical `TokenUsage` (ADR D376, mirror a peer SDK
+ * `Usage.add`).
+ *
+ * Each `add(step)` merges in a per-step finish; `toTokenUsage()`
+ * produces the aggregated public shape with `requests[]` populated
+ * when there were ≥2 steps.
+ *
+ * @internal
+ */
+interface StepUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+}
+declare class UsageAccumulator {
+    private input;
+    private output;
+    private cacheRead;
+    private cacheWrite;
+    private reasoning;
+    private readonly requests;
+    add(step: StepUsage): void;
+    /** Did we observe any usage at all? */
+    hasAny(): boolean;
+    toTokenUsage(): TokenUsage;
+}
+
+/**
+ * `Budget` — token cost enforcement primitive (Adoption Roadmap #1
+ * post-Tasks, ADRs D375-D388).
+ *
+ * Static facade delegating to the in-process registry + ledger.
+ * 3 modes: `audit` (log-only), `warn` (callbacks + log), `block`
+ * (preflight throw before LLM call).
+ *
+ * @public
+ *
+ * @deprecated since SDK 2.0 (iter 18+) — import this facade from
+ * `@theokit/sdk-budget` instead. The sources backing this facade have
+ * been physically extracted to `@theokit/sdk-budget/internal/` per
+ * ADR-008. The sdk-core copies are retained for the v1.x sync API
+ * contract; consumers MUST migrate before sdk-core v3.0.
+ *
+ * Migration:
+ *
+ * ```ts
+ * // Before (sdk-core, deprecated):
+ * import { Budget, computeCost } from "@theokit/sdk";
+ *
+ * // After (sdk-budget, authoritative):
+ * import {
+ *   chargeAndCheckThresholds,
+ *   createBudget,
+ *   computeUsdCost,  // replaces computeCost
+ *   createUsdBudgetTracker,
+ * } from "@theokit/sdk-budget";
+ * ```
+ */
+
+declare class Budget {
+    private constructor();
+    /**
+     * Create a budget. `name` must match `^[a-z0-9][a-z0-9_-]*$` (EC-7).
+     * Throws `ConfigurationError` if name is invalid OR already exists
+     * (EC-16: duplicate surface caller bug).
+     *
+     * `limits` is stacked (D384) — ANY exceeded triggers enforcement.
+     * Empty `limits[]` is valid: pure tracking, no thresholds/exceed
+     * callbacks fire (EC-19).
+     *
+     * Default `mode` is `"warn"` (D383). For emergency stop, use
+     * `mode: "block", limits: [{ window: "1d", limitUsd: 0 }]` (EC-18).
+     */
+    static create(options: BudgetOptions): BudgetHandle;
+    /** Returns the handle for an active budget, or `undefined`. */
+    static get(name: string): BudgetHandle | undefined;
+    /** Returns all active budgets. */
+    static list(): readonly BudgetHandle[];
+    /**
+     * Deletes a budget from the registry. Returns `true` if it existed.
+     * In-flight `agent.send` calls referencing the name treat the
+     * subsequent charge as a silent no-op + stderr warn (EC-20).
+     */
+    static delete(name: string): boolean;
+    /**
+     * Returns per-window spend snapshot for all active budgets. Each
+     * entry has `{ name, window, spentUsd, limitUsd, ratio }`.
+     */
+    static snapshot(): readonly BudgetSnapshot[];
+}
+
+/**
+ * SE25 — deterministic, no-LLM guardrail processors built on the SE24
+ * {@link Processor} seam. Cheap and churn-free (no provider/model deltas), so
+ * they are safe to own in-core — unlike the LLM-classifier processors, which are
+ * delegated (see the guardrails ADR). All are OPT-IN: add them to
+ * `AgentOptions.inputProcessors` / `outputProcessors`.
+ *
+ * @public
+ */
+
+/**
+ * Approximate token count from string length. This is an ESTIMATE
+ * (≈ UTF-16-code-units / 4, NOT Unicode code points, NOT an exact per-model
+ * tokenizer count) — good enough for a coarse cap, and dependency-free.
+ */
+declare function estimateTokens(text: string): number;
+/** Options for {@link createUnicodeNormalizer}. @public */
+interface UnicodeNormalizerOptions {
+    /** Remove C0 + C1 control chars + DEL (keeps tab / newline / carriage-return). Default `false`. */
+    stripControlChars?: boolean;
+    /** Collapse runs of intra-line whitespace to one space, 3+ blank lines to one, and trim. Default `false`. Uses legacy `\s`; Unicode-only whitespace (U+00A0 NBSP, U+FEFF BOM, U+2000–U+200A) is NOT collapsed. */
+    collapseWhitespace?: boolean;
+}
+/** Options for {@link createTokenLimiter}. @public */
+interface TokenLimiterOptions {
+    /** Positive integer token budget (estimate — see {@link estimateTokens}). */
+    limit: number;
+    /** Over the limit: `"truncate"` (default, cut to fit) or `"block"` (abort with a tripwire). */
+    strategy?: "truncate" | "block";
+}
+/** SE36 — `TokenLimiter.create` replaces `createTokenLimiter` (ADR 0015). @public */
+declare class TokenLimiter {
+    private constructor();
+    static create(opts: TokenLimiterOptions): Processor;
+}
+/** SE36 — `UnicodeNormalizer.create` replaces `createUnicodeNormalizer` (ADR 0015). @public */
+declare class UnicodeNormalizer {
+    private constructor();
+    static create(opts?: UnicodeNormalizerOptions): Processor;
+}
+
+/**
+ * Plugin contract — RUNTIME value + type re-exports (T1.1, ADRs D97-D101).
+ *
+ * SE45/SE46 — the pure `Plugin` *type* and its type companions now live in
+ * `types/plugin.ts` (above the DIP boundary, because `Plugin` is public
+ * contract). This module keeps the RUNTIME value (`definePlugin` /
+ * `Plugin.create`) and re-exports the types so every existing
+ * `../plugins/types.js` importer (and the `index.ts` barrel) resolves the same
+ * names unchanged.
+ *
+ * @public
+ */
+
+/**
+ * Identity helper for plugin authors. TS-only convenience — preserves
+ * inferred type without forcing manual `Plugin` annotation.
+ *
+ * @public
+ */
+declare function definePlugin<P extends Plugin>(p: P): P;
+type Plugin = Plugin$1;
+/** SE36 — `Plugin.create` replaces `definePlugin` (ADR 0015). Const-companion (the `Plugin` type alias blocks a class of the same name); `create` is the generic `definePlugin`. @public */
+declare const Plugin: {
+    create: typeof definePlugin;
+};
+
+/**
+ * Options for {@link defineProvider}.
+ *
+ * @public
+ */
+interface DefineProviderOptions {
+    /** Plugin version surfaced in diagnostics. Default `"1.0.0"`. */
+    version?: string;
+}
+/** SE36 — uniform namespace API. `Provider.create` replaces `defineProvider` (ADR 0015). @public */
+declare class Provider {
+    private constructor();
+    static create(profile: ProviderProfile, opts?: DefineProviderOptions): Plugin;
+    /**
+     * Every first-party builtin provider (anthropic, openai, openrouter, gemini, ollama, the ChatGPT/Codex
+     * `openai-chatgpt`, …) as model-provider plugins, ready to hand to `Agent.create({ plugins })` or any
+     * runtime that consumes model-provider plugins (e.g. the `theokit` agent server / `@theokit/agents`, whose
+     * own model resolution does NOT share this registry). Enables a consumer to route to ANY SDK builtin —
+     * including one added later in a single SDK file — with ZERO provider-specific code: just
+     * `.plugins(Provider.builtins())` once, then pick a `provider/model` id. @public
+     */
+    static builtins(): Plugin[];
+}
+
+/**
+ * SE23 — `defineSkillReadTool`: an OPT-IN factory that gives the MODEL on-demand
+ * access to a skill's full body + references via a `skill_read` tool.
+ *
+ * TheoKit discloses skills eagerly through the `<skills>` system-prompt block
+ * (name + description only). This factory is the LAZY read path: the consumer
+ * explicitly adds the returned {@link CustomTool} to `tools`, and when the model
+ * calls it with a skill name, it gets that skill's `instructions` (+ SE21
+ * `references`). The SDK NEVER auto-injects it — bring-your-own-tools stays
+ * intact (sibling of `defineSubAgent` / `workflowAsTool`). See ADR 0007.
+ *
+ *   import { Agent, createSkill, defineSkillReadTool } from "@theokit/sdk";
+ *
+ *   const skills = [createSkill({ name: "release", description: "…", instructions: "…" })];
+ *   const agent = await Agent.create({
+ *     model: { id: "openai/gpt-4o-mini" },
+ *     skills: { inline: skills },
+ *     tools: [defineSkillReadTool(skills)],
+ *   });
+ *
+ * @public
+ */
+
+/** SE36 — `SkillReadTool.create` replaces `defineSkillReadTool` (ADR 0015). @public */
+declare class SkillReadTool {
+    private constructor();
+    static create(skills: ReadonlyArray<InlineSkill>): CustomTool;
+}
+
+/**
+ * Options for {@link sanitizeToolInput}. Trim is the only default-on rung — coercion and JSON
+ * repair change a value's representation, so they are opt-in (the SDK's "values are strings; Zod
+ * coerces" boundary; see `define-tool.ts` doc-comment).
+ *
+ * @public
+ */
+interface SanitizeOptions {
+    /** Trim leading/trailing whitespace from string values. Default `true`. */
+    trim?: boolean;
+    /** Coerce string values to typed values (`"5"`→`5`, `"true"`→`true`, `"null"`→`null`, JSON). Default `false`. */
+    coerce?: boolean;
+    /** Repair-then-parse malformed JSON-looking string values (via `jsonrepair`). Default `false`. */
+    repairJson?: boolean;
+    /**
+     * Optional Zod schema. When it is a `z.object(...)`, coercion is schema-aware: each TOP-LEVEL
+     * field is coerced only toward a candidate its field-schema accepts (so a `z.string()` field
+     * keeps `"5"` as a string). Non-object schemas (union/record) fall back to heuristic coercion.
+     * Note: with `deep: true`, nested fields always use heuristic coercion (the schema is not
+     * descended into).
+     */
+    schema?: ZodType;
+    /** Recurse into nested objects/arrays. Default `false` (shallow). */
+    deep?: boolean;
+    /** Max recursion depth when `deep` is set. Default `8`. */
+    maxDepth?: number;
+}
+
+/**
+ * Spec accepted by {@link defineTool}. `inputSchema` is a Zod schema; the
+ * `handler` argument type is inferred via `z.infer<T>` — no `as` casts.
+ *
+ * @public
+ */
+/**
+ * SE16 — the handler's return type. With no `outputSchema` the tool returns a
+ * plain `string` (pre-SE16 shape). With an `outputSchema` the handler returns the
+ * STRUCTURED output inferred from it (validated + serialized to the tool result).
+ * The `[O]` tuple wrap prevents distribution so `never` maps cleanly to `string`.
+ */
+type ToolHandlerReturn<O extends ZodType> = [O] extends [never] ? string : z.infer<O>;
+interface DefineToolSpec<T extends ZodType, O extends ZodType = never> {
+    /** Tool name surfaced to the LLM. Same constraints as {@link CustomTool.name}. */
+    name: string;
+    /** Description surfaced to the LLM. */
+    description: string;
+    /** Zod schema describing the input. Must be `z.object(...)` at the root for the LLM tool contract. */
+    inputSchema: T;
+    /**
+     * SE16 — optional Zod schema describing the OUTPUT. When set, the handler
+     * returns the structured value inferred from it; the value is validated against
+     * this schema and serialized to the tool result (a string stays as-is, an object
+     * is JSON-stringified). A validation failure raises `ZodError`, converted to a
+     * `tool_result(isError)`. Absent ⇒ the handler returns a plain string (unchanged).
+     */
+    outputSchema?: O;
+    /**
+     * Handler invoked with the parsed input. Type is inferred via `z.infer<T>`; the
+     * return type is `z.infer<O>` when `outputSchema` is set, else `string`.
+     * #65 — an optional 2nd `ToolContext` argument carries the run's `AbortSignal`,
+     * so a cooperative handler can stop early when the run is cancelled. Existing
+     * single-argument handlers are unaffected.
+     */
+    handler: (input: z.infer<T>, ctx?: {
+        signal?: AbortSignal;
+        context?: unknown;
+        threadId?: string;
+    }) => ToolHandlerReturn<O> | Promise<ToolHandlerReturn<O>>;
+    /**
+     * SE17 — map the handler's (validated) output to the compact / multimodal
+     * representation the MODEL sees in the tool_result. The handler keeps returning
+     * the FULL result (validated by `outputSchema`); `toModelOutput` shapes only what
+     * reaches the model, so app-facing detail is not forced into model context.
+     * Returns a string OR SE7 `ToolResultContentBlock[]` (text + image). Absent ⇒
+     * the tool_result is the serialized handler output (SE16 / pre-SE17 behavior).
+     * The split is REAL: the model's `tool_result` carries this compact value, while
+     * observability (`onToolEnd.result`) receives the FULL raw handler output
+     * (serialized) — so the app keeps the complete result. ONE handler execution
+     * feeds both channels.
+     */
+    toModelOutput?: (output: ToolHandlerReturn<O>) => string | ToolResultContentBlock[];
+    /**
+     * Sanitize the raw model-emitted args BEFORE schema validation (`@theokit/sdk/sanitize`).
+     * `true` trims whitespace; an object opts into coercion / JSON-repair. Coercion is schema-aware
+     * against this tool's `inputSchema`. Absent ⇒ args reach validation untouched. Sanitize is
+     * hygiene, not a validity bypass — a genuinely invalid arg still raises `ZodError`.
+     */
+    sanitize?: boolean | SanitizeOptions;
+}
+/**
+ * SE36 — the uniform `X.create()` namespace API. `Tool.create(spec)` is the sole public
+ * constructor for a {@link CustomTool}; it wraps the internal builder so behavior is identical
+ * (ADR 0015). A `private constructor` makes `Tool` a namespace, not an instantiable value —
+ * `new Tool()` is a compile error. Mirrors `Agent.create` / `Cron.create`.
+ *
+ * @public
+ */
+declare class Tool {
+    private constructor();
+    static create<T extends ZodType, O extends ZodType = never>(spec: DefineToolSpec<T, O>): CustomTool;
+}
+
+/**
+ * `EventBus` — typed EventEmitter wrapper.
+ *
+ * Provides type-safe publish/subscribe with automatic unsubscribe cleanup.
+ * Each handler is try-caught (EC-2) so one failing handler cannot break others.
+ */
+type EventHandler<T> = (payload: T) => void;
+declare class EventBus<Events extends Record<string, unknown>> {
+    #private;
+    private handlers;
+    /** M3 #64 — number of handler invocations that threw (and were logged). */
+    get handlerErrorCount(): number;
+    /**
+     * Subscribe to an event. Returns an unsubscribe function.
+     */
+    subscribe<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>): () => void;
+    /**
+     * Publish an event to all subscribers. EC-2: try-catch per handler.
+     */
+    publish<K extends keyof Events>(event: K, payload: Events[K]): void;
+    /**
+     * Subscribe to an event for a single firing. Returns an unsubscribe function.
+     */
+    once<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>): () => void;
+}
+
+/**
+ * Judge call primitive (T2.2, ADRs D119-D121).
+ *
+ * Instantiates a short-lived auxiliary agent that evaluates whether a
+ * goal is satisfied. The auxiliary judge runs with `tools: []` and a
+ * cheap model (default `openai/gpt-4o-mini`) — see ADR D119. The judge
+ * model needs only API access; we read `OPENROUTER_API_KEY` directly
+ * from the environment (EC-A — single source of truth) and let the
+ * caller override via {@link JudgeOptions.apiKey} for Anthropic or
+ * direct-OpenAI environments.
+ *
+ * NOTE: judge aux agents created from inside a `forkAgent` context will
+ * inherit the parent fork's whitelist via AsyncLocalStorage (EC-J).
+ * `tools: []` keeps this benign today; future callers that add tools to
+ * a judge should be aware.
+ *
+ * @internal
+ */
+/** Inputs to the judge — pure data. */
+interface JudgeContext {
+    goal: string;
+    lastResponse: string;
+    subgoals?: string[];
+}
+/** Caller-supplied tuning knobs for the judge call. */
+interface JudgeOptions {
+    /** Judge model identifier. Default `"openai/gpt-4o-mini"` (ADR D119). */
+    judgeModel?: string;
+    /** Override env. Default `process.env.OPENROUTER_API_KEY` (EC-A). */
+    apiKey?: string;
+}
+
+/**
+ * Public types for the judge subsystem (T2.1, ADR D120).
+ *
+ * @internal
+ */
+/** Outcome of {@link parseVerdict} / {@link judgeCallImpl}. */
+interface JudgeResult {
+    verdict: Verdict;
+    reason: string;
+    /**
+     * `true` when the underlying text did not start with one of the three
+     * canonical prefixes. The verdict is set to `"continue"` (fail-safe,
+     * ADR D121) to avoid stopping prematurely; callers track consecutive
+     * failures and bail via `maxConsecutiveJudgeFailures`.
+     */
+    parseFailed: boolean;
+}
+
+/**
+ * Goal-driven Ralph loop (T3.2, ADRs D115-D121).
+ *
+ * `runUntilImpl` is an `AsyncGenerator<GoalEvent, GoalResult, void>`:
+ * yields events as the loop progresses, returns the final result when
+ * the goal completes, fails, or is paused. The auxiliary judge model is
+ * injected via `deps.judge` so the generator stays free of the `Agent`
+ * façade import.
+ *
+ * EC-C fix: pre-aborted signals emit only `[paused]`, not `[active, paused]`.
+ * EC-D: `maxTurns: 0` is supported (vacuous yield active → failed).
+ *
+ * @internal
+ */
+
+/** DI contract: the judge is the only external touchpoint. */
+interface RunUntilDeps {
+    judge: (ctx: JudgeContext, opts?: JudgeOptions) => Promise<JudgeResult>;
+}
+
+/**
+ * M56 (agent-builder goal transparency) — PUBLIC goal-loop driver for CUSTOM agent surfaces.
+ *
+ * `LocalAgent.runUntil` binds the goal loop to a registered local agent. Surfaces that route turns
+ * through their OWN transport (e.g. a TUI store facade, so every goal turn renders in the same
+ * timeline as a manual turn) need the SAME loop over a minimal `send → wait` shape. This export
+ * gives them exactly that: the canonical `runUntilImpl` (judge + continuation + token budget +
+ * Codex states) with the default judge wired from the DI registry.
+ *
+ * @public
+ */
+
+/**
+ * Stable marker on the FIRST LINE of every goal-continuation prompt. Surfaces detect it to render the
+ * turn collapsed, exclude it from backtrack windows, and skip it in compaction preservation.
+ */
+declare const GOAL_CONTINUATION_MARKER = "[[theokit:goal-continuation]]";
+
+/** The minimal surface the goal loop drives — anything that can send a prompt and wait for it. */
+interface GoalLoopAgent {
+    send(prompt: string): Promise<{
+        wait(): Promise<{
+            result?: string;
+            usage?: {
+                totalTokens?: number;
+            };
+        }>;
+    }>;
+}
+/**
+ * Run the goal-driven loop (`send → judge → continuation`) over ANY `send → wait` surface.
+ * Identical semantics to `Agent.runUntil` (ADRs D115-D121 + M55 token budget / states).
+ * `depsOverride` is a test seam for injecting a fake judge.
+ */
+declare function runGoalLoop(agent: GoalLoopAgent, goal: string, options?: GoalOptions, depsOverride?: RunUntilDeps): AsyncGenerator<GoalEvent, GoalResult, void>;
+
+/**
+ * Reference `BudgetTracker` impl — pure token + iteration counter
+ * (SDK 2.0 Phase 2 / T2.1 — ADR D1 reference implementation).
+ *
+ * Counts tokens per type (input/output) + iteration count. Enforces
+ * optional `maxTokens` / `maxIterations` ceilings via `check()`.
+ *
+ * Does NOT compute USD cost — leaves that to richer impls in
+ * `@theokit/sdk-budget` (post-Phase-2). This file is intentionally
+ * minimal so consumers can:
+ *   - use it as-is for simple guard-rails;
+ *   - read it as a worked example before authoring a custom tracker;
+ *   - rely on it as a fallback before sdk-budget ships.
+ *
+ * @public — surface-level reference impl.
+ */
+
+/** Options for `createCounterBudgetTracker`. */
+interface CounterBudgetTrackerOptions {
+    /** Hard ceiling on total tokens (input + output). When reached, `check()` returns `allowed: false`. */
+    readonly maxTokens?: number;
+    /** Hard ceiling on iterations counted by `nextIteration()`. */
+    readonly maxIterations?: number;
+}
+/**
+ * Build a fresh tracker. The returned object is independent — call
+ * `createCounterBudgetTracker()` per Agent instance.
+ *
+ * The tracker exposes the `BudgetTracker` contract PLUS a `nextIteration()`
+ * helper for impls that want explicit iteration counting (the agent loop
+ * calls it once per turn). Without `nextIteration()` calls, the iteration
+ * cap is never reached.
+ */
+declare function createCounterBudgetTracker(options?: CounterBudgetTrackerOptions): BudgetTracker & {
+    nextIteration(): void;
+};
+
+declare function withCwdMutex<T>(key: string, fn: () => Promise<T>): Promise<T>;
+
+/**
+ * Reference `MemoryProvider` impl — no-op fallback (SDK 2.0 Phase 1 /
+ * T1.2 reference implementation, mirrors `createCounterBudgetTracker`).
+ *
+ * Every method is a degenerate identity:
+ *   - `init()` returns a handle wrapping a no-op `MemoryAdapter`.
+ *   - `buildTools()` returns `[]` (no memory tools surfaced to the LLM).
+ *   - `runActivePass()` returns `{ facts: [] }` (no recall fires).
+ *   - `dispose()` is a no-op.
+ *
+ * Why ship this:
+ *   - Default safety net before `@theokit/sdk-memory` is installed.
+ *   - Worked reference for authors of custom providers.
+ *   - Enables `Agent.create({ memoryProvider: createNoopMemoryProvider() })`
+ *     unit tests without pulling memory infrastructure.
+ *
+ * NOT a substitute for the existing `Memory` class — the legacy class
+ * stays authoritative until the subsystem fully ports to providers
+ * (Phase 1 / T1.6).
+ *
+ * @public — surface-level reference impl.
+ */
+
+/** SE36 — `NoopMemoryProvider.create` replaces `createNoopMemoryProvider` (ADR 0015). @public */
+declare class NoopMemoryProvider {
+    private constructor();
+    static create(): MemoryProvider;
+}
+
+/**
+ * `JobQueue` — background job queue with status tracking, cancellation, and an
+ * optional concurrency bound.
+ *
+ * EC-1: all enqueued functions are wrapped in Promise.resolve().then() so
+ * synchronous throws become rejections.
+ *
+ * #58: each job runs under an `AbortController` whose signal is passed to the
+ * job fn, so `cancel()` actually interrupts a running job (not just a status
+ * flip); an optional `maxConcurrency` bounds how many jobs run at once.
+ */
+type JobStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
+interface Job<T> {
+    id: string;
+    status: JobStatus;
+    result?: T;
+    error?: string;
+}
+/** #58 — construction options. */
+interface JobQueueOptions {
+    /**
+     * Max jobs running concurrently. Omit for unbounded (previous behavior).
+     * Values < 1 are clamped to 1 (an invalid bound must not deadlock).
+     */
+    maxConcurrency?: number;
+}
+declare class JobQueue {
+    #private;
+    private jobs;
+    private controllers;
+    private readonly maxConcurrency;
+    private running;
+    private readonly waiting;
+    constructor(options?: JobQueueOptions);
+    /**
+     * Enqueue a background function. Returns the job ID immediately. The function
+     * receives an `AbortSignal` that fires when the job is cancelled (#58) — a
+     * cooperative job should observe it to stop early. Existing `() => Promise<T>`
+     * callers are unaffected (the signal argument is simply ignored).
+     */
+    enqueue<T>(fn: (signal: AbortSignal) => Promise<T>): string;
+    getJob(id: string): Job<unknown> | undefined;
+    list(): Job<unknown>[];
+    /**
+     * Cancel a pending or running job. Returns true if cancelled. #58 — aborts the
+     * job's `AbortSignal` so a cooperative running job is actually interrupted.
+     */
+    cancel(id: string): boolean;
+}
+
+/**
+ * Public handle to an open memory index. Mirrors the internal `MemoryIndex`
+ * contract structurally; defined here (NOT re-exported from internal/) so
+ * the public DTS surface does not pull the internal/runtime cycle that
+ * trips rollup-plugin-dts.
+ *
+ * @public
+ */
+interface MemoryIndexHandle {
+    sync(): Promise<{
+        filesScanned: number;
+        filesUpdated: number;
+        chunksWritten: number;
+        chunksEmbedded: number;
+    }>;
+    search(query: string, options?: {
+        maxResults?: number;
+        minScore?: number;
+        sources?: ReadonlyArray<"memory" | "sessions" | "wiki">;
+    }): Promise<ReadonlyArray<{
+        path: string;
+        startLine: number;
+        endLine: number;
+        score: number;
+        textScore: number;
+        vectorScore?: number;
+        snippet: string;
+        source: "memory" | "sessions" | "wiki";
+        citation: string;
+    }>>;
+    status(): {
+        backend: "fts-only" | "hybrid";
+        filesIndexed: number;
+        chunksIndexed: number;
+        lastSyncMs?: number;
+    };
+    close(): Promise<void> | void;
+}
+/**
+ * Public `Memory` namespace.
+ *
+ * Exposes operations users can run outside of `agent.send()` — most notably
+ * the dreaming sweep (consolidation of facts via dedup + clustering).
+ *
+ * @public
+ */
+interface DreamingSweepOptions {
+    /** Workspace cwd holding `.theokit/memory/`. */
+    cwd: string;
+    /**
+     * Embedding provider for semantic dedup + clustering. Required — dreaming
+     * relies on real embeddings to score cosine similarity. Supported providers:
+     * `"openai"`, `"mistral"`, `"openrouter"`, `"voyage"`, `"deepinfra"`,
+     * `"ollama"` (local, ADR D183).
+     */
+    embedding: {
+        provider: "openai" | "mistral" | "openrouter" | "voyage" | "deepinfra" | "ollama";
+        model?: string;
+    };
+    /** Cosine-similarity threshold for the dedup phase. Default `0.95`. */
+    dedupThreshold?: number;
+    /** Cosine-similarity threshold for the clustering phase. Default `0.75`. */
+    clusterThreshold?: number;
+}
+interface DreamingSweepResult {
+    status: "ok" | "skipped" | "error";
+    factsBefore: number;
+    factsAfter: number;
+    duplicatesRemoved: number;
+    clustersCreated: number;
+    notesWritten: number;
+}
+/**
+ * Options for `Memory.openIndex`. Mirrors the internal `OpenIndexOptions`
+ * but using only public types from the SDK surface.
+ *
+ * @public
+ */
+interface OpenMemoryIndexOptions {
+    /** Workspace cwd holding `.theokit/memory/`. */
+    cwd: string;
+    /** Override storage file path (SQLite) OR storage directory (Lance). */
+    filePath?: string;
+    /**
+     * Embedding runtime — REQUIRED for `backend: "lance"`, optional for
+     * `"sqlite-vec"` (when omitted, SQLite runs FTS-only without vector
+     * recall).
+     */
+    embedding?: {
+        provider: "openai" | "mistral" | "openrouter" | "voyage" | "deepinfra" | "ollama";
+        model?: string;
+    };
+    /** Default `"sqlite-vec"`. Set to `"lance"` to opt into LanceDB (peer dep). */
+    backend?: "sqlite-vec" | "lance";
+}
+declare const Memory: {
+    /**
+     * Open a memory index. Dispatches to SQLite-vec (default, zero deps) or
+     * LanceDB (opt-in via `backend: "lance"`, requires `@lancedb/lancedb`
+     * peer dep + an embedding runtime).
+     *
+     * Returns a `MemoryIndex` with `sync()`, `search(query, opts?)`,
+     * `status()`, and `close()`. Use this when you want a direct index
+     * handle outside of `Agent.create({ memory: ... })`.
+     *
+     * @throws ConfigurationError({code:"invalid_memory_backend"}) for typos
+     *   like `"lancedb"`.
+     * @throws ConfigurationError({code:"lance_requires_embedding"}) when
+     *   `backend: "lance"` is requested without `embedding`.
+     * @throws ConfigurationError({code:"lance_backend_unavailable"}) when
+     *   `backend: "lance"` is requested but the peer dep is absent.
+     *
+     * @public
+     */
+    openIndex(opts: OpenMemoryIndexOptions): Promise<MemoryIndexHandle>;
+    /**
+     * Run a dreaming sweep: dedup near-duplicate facts, cluster thematically
+     * related ones, and write a consolidated note + diary entry.
+     *
+     * @public
+     */
+    runDreamingSweep(opts: DreamingSweepOptions): Promise<DreamingSweepResult>;
+};
+
+/**
+ * Runtime helpers for `MemoryAdapter` (T1.1, ADR D141).
+ *
+ * Kept separate from `types/memory-adapter.ts` so the types module
+ * stays import-free of runtime code (dep-cruise rule
+ * `types-dont-import-runtime`). Adapter authors call `mkMemoryId` to
+ * construct a branded id and `extractRawId` to unwrap with cross-adapter
+ * safety (EC-B).
+ *
+ * @public
+ */
+
+/**
+ * Construct a branded `MemoryId` for an adapter. Embeds the adapter
+ * identifier so `extractRawId` can reject ids minted by other adapters.
+ *
+ * @public
+ */
+declare function mkMemoryId(adapterId: string, rawId: string): MemoryId;
+/**
+ * Extract the raw provider id from a `MemoryId`, enforcing that the
+ * prefix matches `expectedAdapterId`. Throws `MemoryAdapterError(code:
+ * "invalid_input")` on mismatch — prevents `mem0.delete(supermemoryId)`
+ * from accidentally deleting unrelated data (EC-B).
+ *
+ * @public
+ */
+declare function extractRawId(id: MemoryId, expectedAdapterId: string): string;
+
+/**
+ * Options for {@link migrateSqliteToLance}.
+ *
+ * @public
+ */
+interface MigrateOptions {
+    cwd: string;
+    dryRun?: boolean;
+    batchSize?: number;
+    logger?: (msg: string) => void;
+}
+/**
+ * Outcome of {@link migrateSqliteToLance}.
+ *
+ * @public
+ */
+interface MigrateResult {
+    countSqlite: number;
+    countLance: number;
+    validated: boolean;
+    sampleComparisons: ReadonlyArray<{
+        id: string;
+        match: boolean;
+    }>;
+    lancePath: string;
+    committed: boolean;
+}
+/**
+ * Migrate the Memory index from SQLite to LanceDB. ADR D44.
+ *
+ * @public
+ */
+declare function migrateSqliteToLance(options: MigrateOptions): Promise<MigrateResult>;
+
+/**
+ * M7-5 — `createPermissionPlugin`: wire a {@link PermissionEngine} into the
+ * `definePlugin` `pre_tool_call` veto seam. This is the canonical exemplar that
+ * gives `PermissionEngine` a real caller (it was previously exported-but-unwired):
+ * on each tool call the engine's verdict maps to the veto contract —
+ * `"deny"` -> block, `"ask"` -> the caller's `onAsk` resolver (or block, fail-closed),
+ * `"allow"` -> pass.
+ *
+ * @public
+ */
+
+/**
+ * SE1 — context passed to the {@link PermissionGate}. Intentionally minimal for
+ * SE1; `agentId`/`runId` (for audit logging) are a documented follow-up — they are
+ * available on the raw `pre_tool_call` context and can be threaded in a later slice.
+ */
+interface PermissionGateContext {
+    /** The tool being gated. */
+    readonly toolName: string;
+    /** The active permission mode for this run. */
+    readonly mode: PermissionMode;
+}
+/**
+ * SE1 — the resolution of an `"ask"` verdict by the host gate. Fail-closed: an
+ * absent gate, a throwing gate, and a `"deny"` decision all block. Arg rewrite
+ * (`updatedInput`) is intentionally NOT supported yet — the `pre_tool_call` seam
+ * is veto-only (`{ block, message }`); a future enhancement can extend it.
+ */
+type PermissionGateDecision = {
+    readonly behavior: "allow";
+} | {
+    readonly behavior: "deny";
+    readonly message?: string;
+};
+/**
+ * SE1 — the enriched `canUseTool` gate (the Anthropic-parity shape). Invoked ONLY
+ * on an `"ask"` verdict, it receives the tool name, its input args, and the run
+ * {@link PermissionGateContext}, and resolves to allow/deny. May be async (a real
+ * gate can prompt a human — the `pre_tool_call` seam awaits it).
+ */
+type PermissionGate = (toolName: string, input: Record<string, unknown>, ctx: PermissionGateContext) => PermissionGateDecision | Promise<PermissionGateDecision>;
+/** Options for {@link createPermissionPlugin}. */
+interface PermissionPluginOptions {
+    /** Plugin name (default `"permission-engine"`). */
+    readonly name?: string;
+    /**
+     * SE1 — the per-run {@link PermissionMode}. Threaded into `engine.evaluate`, so
+     * `bypass` auto-allows the ask verdict (gate never consulted), `plan` blocks
+     * mutations, etc. An explicit `deny` rule is immune to every mode. Default
+     * `"default"` (rules decide; unmatched ⇒ fail-closed ask).
+     */
+    readonly mode?: PermissionMode;
+    /**
+     * SE1 — the enriched gate for the `"ask"` verdict. Preferred over {@link onAsk}.
+     * Absent gate on an `ask` verdict ⇒ fail-closed block.
+     */
+    readonly canUseTool?: PermissionGate;
+    /**
+     * @deprecated since SE1 — use {@link canUseTool}, which receives `(toolName,
+     * input, ctx)` and returns a typed decision. Honored only when `canUseTool` is
+     * absent. Returns a veto (`{block,message}`) to deny or `undefined` to allow.
+     */
+    readonly onAsk?: (toolName: string) => PreToolCallDecision | undefined;
+}
+/** SE36 — `PermissionPlugin.create` replaces `createPermissionPlugin` (ADR 0015). @public */
+declare class PermissionPlugin {
+    private constructor();
+    static create(engine: PermissionEngine, opts?: PermissionPluginOptions): Plugin;
+}
+
+/** The internal JSON-Schema shape the synthetic `output` tool consumes. */
+type NormalizedJsonSchema = Record<string, unknown>;
+/**
+ * Normalize any supported schema to the internal JSON Schema. Async because the Valibot path
+ * dynamically imports its optional converter. Throws a clear, typed-message error for an unsupported
+ * schema or a missing Valibot peer (error-handling.md).
+ */
+declare function normalizeSchema(schema: unknown): Promise<NormalizedJsonSchema>;
+
+/**
+ * Public security namespace (T2.1, ADR D68).
+ *
+ * Two entry points:
+ *
+ * - `Security.redact(text, opts?)` — apply the canonical redactor to
+ *   arbitrary text. Useful when a consumer app (or example) writes its
+ *   own logs / metrics / paste-share artifacts that the SDK's wired
+ *   sinks (error metadata, telemetry, transcript, migration) don't
+ *   cover.
+ * - `Security.addPattern(re)` — register a custom credential pattern
+ *   on top of the 12 builtins (OpenAI, Anthropic, GitHub PAT classic +
+ *   fine, GitLab, AWS, Google, Slack, Sentry, Stripe live + restricted)
+ *   plus the parametric `key=value` + `Bearer <token>` matchers.
+ *
+ * Redaction is ON by default. Disable with `THEOKIT_REDACT_SECRETS=false`
+ * (a warning is emitted on stderr so the operator knows the SDK process
+ * is vulnerable). The env var is snapshotted at module init — runtime
+ * mutation cannot disable it, defending against prompt injection that
+ * tries to flip the flag mid-run.
+ */
+declare class Security {
+    private constructor();
+    /**
+     * Redact known credential patterns from `text` and return the masked
+     * string. Use this at any consumer output boundary the SDK does not
+     * directly own (custom stdout loggers, app-level metrics, debug-share
+     * artifacts, etc.).
+     *
+     * Coerces non-strings (objects via JSON.stringify, null/undefined → "").
+     * Two-bucket masking: tokens shorter than 18 chars → `***`; longer
+     * tokens preserve `prefix...suffix` for debuggability without revealing
+     * the secret middle.
+     *
+     * @param text - The value to redact. Strings, objects, primitives all OK.
+     * @param opts.codeFile - When `true`, skips the parametric `key=value`
+     *   matcher so file content like `.env.example` placeholders is left
+     *   intact. Built-in pattern matches still apply.
+     *
+     * @example
+     * console.log(`[bot] received: ${Security.redact(userText)}`);
+     * // → "[bot] received: please remember sk-abc...xyz1"
+     */
+    static redact(text: unknown, opts?: {
+        codeFile?: boolean;
+    }): string;
+    /**
+     * Register a custom redaction pattern. Additive — built-in patterns
+     * (OpenAI, Anthropic, GitHub PAT, AWS, etc.) cannot be removed.
+     *
+     * @param re - RegExp with `/g` flag. Throws if `/g` is missing
+     *             (without /g, only first match is replaced and the rest
+     *             leaks).
+     *
+     * Process-global mutable state. The SDK is designed for single-tenant
+     * processes (Theo PaaS user runtime, local CLI). Multi-tenant
+     * deployments running multiple SDK consumers in the same Node process
+     * share this list — patterns added by tenant A apply to tenant B's
+     * redactions. Acceptable for v1; future isolate-aware refactor would
+     * thread patterns through a context if needed.
+     *
+     * @example
+     * Security.addPattern(/MYORG-[A-Z0-9]{32}/g);
+     * // → text containing "MYORG-AAAA...AAAA" now masks like a builtin.
+     */
+    static addPattern(re: RegExp): void;
+}
+
+/**
+ * M3 #62 — scoped session state.
+ *
+ * A conversation id can be namespaced by SCOPE so a consumer keeps app-durable,
+ * user-durable, and ephemeral (temp) session data separated in the same store:
+ *
+ * - `app:`  — durable state shared across users (app-level memory).
+ * - `user:` — durable state for one user.
+ * - `temp:` — ephemeral state a consumer prunes on logout / session end.
+ *
+ * The scope is a prefix on the conversation id (`"<scope>__<id>"`). The `__`
+ * separator is path-safe (unlike `:`, which the identifier guard rejects), so a
+ * host can partition sessions by scope over the native transcript store.
+ *
+ * @public
+ */
+/** M3 #62 — session state scope. */
+type SessionScope = "app" | "user" | "temp";
+/** M3 #62 — build a scope-namespaced conversation id (`"<scope>__<id>"`). */
+declare function scopedConversationId(scope: SessionScope, id: string): string;
+/** M3 #62 — the id prefix (`"<scope>__"`) used to match a scope's conversations. */
+declare function sessionScopePrefix(scope: SessionScope): string;
+
+/**
+ * `createSquad` — a sequential team of agents.
+ *
+ * A Squad is a thin convenience that COMPOSES `Workflow` + `agentStep` — it
+ * adds NO new orchestration logic. Agents run in array order; each agent's
+ * output is threaded into the next agent's prompt. For branching/parallel/
+ * foreach teams use `Workflow` directly; for manager→worker delegation use
+ * subagents or `@theokit/sdk-handoff`.
+ *
+ * Mirrors the `createAgentFactory` composition-LEGO precedent (a factory over
+ * existing primitives, not a new subsystem).
+ *
+ * @public
+ */
+
+/**
+ * Options for {@link createSquad}.
+ *
+ * @public
+ */
+interface SquadOptions {
+    /** Agents run in array order (sequential pipeline). Must be non-empty. */
+    agents: ReadonlyArray<SDKAgent>;
+    /**
+     * Orchestration process. Only `"sequential"` is supported (the default).
+     * `"hierarchical"` is accepted by the type but rejected at runtime with
+     * guidance — use subagents or `@theokit/sdk-handoff` for manager→worker
+     * delegation (those already cover it).
+     */
+    process?: "sequential" | "hierarchical";
+    /** Optional squad name (surfaced on the underlying workflow). Default `"squad"`. */
+    name?: string;
+}
+/**
+ * Result of a {@link Squad.run}. `result` is the final (last agent's) output;
+ * `steps` is the per-agent trace from the underlying workflow run.
+ *
+ * @public
+ */
+interface SquadRun {
+    readonly result: unknown;
+    readonly status: "running" | "completed" | "failed" | "suspended" | "cancelled";
+    readonly steps: ReadonlyArray<StepResult>;
+}
+/**
+ * A sequential agent team produced by {@link createSquad}.
+ *
+ * @public
+ */
+interface Squad {
+    /** Run the team over `input`, threading each agent's output to the next. */
+    run(input: unknown): Promise<SquadRun>;
+}
+/** SE36 — `Squad.create` replaces `createSquad` (ADR 0015). Merges with the `Squad` interface. @public */
+declare class Squad {
+    private constructor();
+    static create(options: SquadOptions): Squad;
+}
+
+/**
+ * Public type contract for the Task observability registry (ADRs D361-D374).
+ *
+ * Tasks are an opt-in observability layer over async work in the SDK
+ * (`Agent.send`, `Agent.batch`, `Workflow.run`, `Cron` fires). They have
+ * a closed 5-state lifecycle (D362), discriminated events (D366), and a
+ * pluggable store (D364). The `Task` facade in `task.ts` is the public
+ * surface; consumers import these types from `@theokit/sdk`.
+ *
+ * @public
+ */
+/**
+ * Closed enum of the 5 lifecycle states (D362).
+ *
+ * Transitions are acyclic:
+ *   queued → running → (finished | error | cancelled)
+ *   queued → cancelled (direct, no run started)
+ */
+type TaskState = "queued" | "running" | "finished" | "error" | "cancelled";
+/** Discriminator of the runtime that produced a task (D374). */
+type TaskKind = "run" | "batch" | "workflow" | "cron" | "custom";
+/** Discriminated union of task lifecycle events (D366). */
+type TaskEvent = {
+    readonly type: "submitted";
+    readonly taskId: string;
+    readonly kind: TaskKind;
+    readonly submittedAt: number;
+    readonly meta?: Record<string, unknown>;
+    /** D372 — flag set on the first yielded event when the ring buffer was at cap. */
+    readonly truncated?: boolean;
+} | {
+    readonly type: "started";
+    readonly taskId: string;
+    readonly startedAt: number;
+} | {
+    readonly type: "progress";
+    readonly taskId: string;
+    readonly at: number;
+    readonly payload: unknown;
+} | {
+    readonly type: "finished";
+    readonly taskId: string;
+    readonly finishedAt: number;
+    readonly result: unknown;
+} | {
+    readonly type: "errored";
+    readonly taskId: string;
+    readonly erroredAt: number;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+} | {
+    readonly type: "cancelled";
+    readonly taskId: string;
+    readonly cancelledAt: number;
+    readonly reason?: string;
+};
+/** Public read-only view of a task entry in the registry. */
+interface TaskHandle {
+    readonly id: string;
+    readonly kind: TaskKind;
+    readonly state: TaskState;
+    readonly submittedAt: number;
+    readonly startedAt?: number;
+    readonly finishedAt?: number;
+    readonly cancelledAt?: number;
+    readonly erroredAt?: number;
+    readonly result?: unknown;
+    readonly error?: {
+        readonly code: string;
+        readonly message: string;
+    };
+    readonly meta?: Record<string, unknown>;
+    /**
+     * EC-7 — cross-process best-effort cancel flag. Set by CLI
+     * `theokit tasks cancel` via JsonFileTaskStore. The owning process
+     * polls at checkpoints and honors via AbortController. Always
+     * `undefined` for in-process cancel paths (which go directly through
+     * AbortController).
+     */
+    readonly cancelRequested?: boolean;
+}
+/** Query filter for `Task.list`. */
+interface TaskFilter {
+    readonly state?: TaskState | readonly TaskState[];
+    readonly kind?: TaskKind | readonly TaskKind[];
+    readonly submittedAfter?: number;
+    readonly submittedBefore?: number;
+    /** Defaults to 100. JsonFileTaskStore hard-caps loaded entries at 256 (D364). */
+    readonly limit?: number;
+}
+/** Options for `Task.submit`. */
+interface TaskSubmitOptions {
+    /**
+     * Optional user-supplied ID. Must match grammar `^[a-z0-9][a-z0-9_-]*$`
+     * and MUST NOT start with the reserved prefixes `wf-` / `b-` / `cron-`
+     * (D368, EC-5). When omitted, `crypto.randomUUID()` is used.
+     */
+    readonly id?: string;
+    readonly meta?: Record<string, unknown>;
+    /**
+     * Optional caller-provided AbortSignal. If already aborted at submit
+     * time, the registry short-circuits to `cancelled` without acquiring
+     * a semaphore slot (EC-4).
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * SE2 — an opt-in {@link import("./run-events.js").RunEventSink}. The task's
+     * lifecycle is forwarded to it as typed `task_started` / `task_updated` /
+     * `task_completed` RunEvents, so a caller that spawned the task can observe it
+     * through the same `onRunEvent` channel as the rest of the run. Best-effort (a
+     * throwing sink never breaks the task). The dedicated `Task.subscribe(id)`
+     * channel is unaffected.
+     */
+    readonly onRunEvent?: RunEventSink;
+}
+/** Options shape for `TaskStore` factory (D364). */
+type TaskStoreOptions = {
+    readonly backend: "memory";
+} | {
+    readonly backend: "json";
+    readonly dir: string;
+};
+/** Result of `Task.cancel` (D365 — idempotent). */
+interface TaskCancelResult {
+    readonly cancelled: boolean;
+    readonly alreadyTerminal: boolean;
+}
+/**
+ * Validates a task ID against the public grammar + reserved prefixes.
+ * Throws `InvalidTaskIdError` from `../errors.js` on rejection.
+ *
+ * Adapter callers (workflow/batch/cron) MUST set `allowReserved: true`
+ * to register their own IDs; user-facing surfaces (`Task.submit`,
+ * `agent.send({ task: { id } })`) leave it false.
+ */
+declare function isValidTaskId(id: string, allowReserved: boolean): boolean;
+/** Re-exported for adapter implementations + tests. */
+declare const TASK_RESERVED_PREFIXES: readonly string[];
+
+/**
+ * `Task` — observable async work registry (Adoption Roadmap gap #2,
+ * ADRs D361-D374).
+ *
+ * Static facade delegating to the in-process `TaskRegistry` singleton.
+ * The lifecycle of any task is the 5-state machine `queued | running |
+ * finished | error | cancelled` (D362). Wrapping `Agent.send` /
+ * `Agent.batch` / `Workflow.run` / `Cron` fires is opt-in via the
+ * `{ task: true }` option on each (D363).
+ *
+ * @public
+ */
+
+interface TaskWorkContext {
+    readonly signal: AbortSignal;
+    emit(payload: unknown): void;
+}
+type TaskWorkFn<T> = (ctx: TaskWorkContext) => Promise<T> | T;
+/**
+ * Registry-level configuration. May only be applied BEFORE the first
+ * `Task.submit` of the process — see EC-13. Subsequent calls emit a
+ * single stderr line and become no-ops.
+ */
+interface TaskConfigureOptions {
+    readonly store?: TaskStoreOptions;
+    readonly maxConcurrent?: number;
+    readonly retentionMs?: number;
+}
+declare class Task {
+    private constructor();
+    /**
+     * Configure the registry. **Must be called before the first `submit`**
+     * (EC-13). Available knobs: pluggable store (D364), concurrency cap
+     * (D369), and retention (D373).
+     */
+    static configure(opts: TaskConfigureOptions): void;
+    /**
+     * Submit a unit of asynchronous work to the registry.
+     *
+     * The `work` function receives `{ signal, emit }` — `signal` is the
+     * AbortSignal honored on cancel; `emit(payload)` produces a
+     * `progress` event observable via `Task.subscribe`.
+     *
+     * Returns a `TaskHandle` in `state: "queued"`. Subsequent state
+     * transitions are observable via `Task.subscribe(handle.id)` OR
+     * polled via `Task.get(handle.id)`.
+     *
+     * **Idempotency (D367):** submitting twice with the same `id` returns
+     * the existing handle without re-invoking work.
+     *
+     * **Grammar (D368):** user-supplied ids must match
+     * `^[a-z0-9][a-z0-9_-]*$` and must not start with reserved prefixes
+     * `wf-` / `b-` / `cron-`. Otherwise `InvalidTaskIdError` is thrown.
+     *
+     * **Pre-aborted signal (EC-4):** if `options.signal` is already
+     * aborted, the task short-circuits to `cancelled` without acquiring
+     * a semaphore slot and without invoking `work`.
+     */
+    static submit<T>(kind: TaskKind, work: TaskWorkFn<T>, options?: TaskSubmitOptions): Promise<TaskHandle>;
+    /** Returns matching handles, capped at `filter.limit ?? 100`. */
+    static list(filter?: TaskFilter): Promise<TaskHandle[]>;
+    /** Returns a single handle by id, or `undefined` if unknown / evicted. */
+    static get(id: string): Promise<TaskHandle | undefined>;
+    /**
+     * Idempotent cancel (D365). Returns:
+     *   - `{ cancelled: true, alreadyTerminal: false }` — transitioned
+     *     queued/running task to `cancelled`.
+     *   - `{ cancelled: false, alreadyTerminal: true }` — task already
+     *     terminal.
+     *   - `{ cancelled: false, alreadyTerminal: false }` — task unknown.
+     *
+     * Never throws.
+     */
+    static cancel(id: string, reason?: string): Promise<TaskCancelResult>;
+    /**
+     * Subscribe to a task's event stream. The returned `AsyncIterable<TaskEvent>`
+     * starts by replaying buffered events (ring buffer cap 64, D372) and
+     * then yields live events until a terminal event (finished / errored
+     * / cancelled) is emitted, at which point it closes automatically.
+     *
+     * Calling `.return()` on the iterator (or `break` in a `for await`)
+     * cleans up the subscriber callback (EC-10).
+     *
+     * Throws `TaskNotFoundError` if the id is unknown or has been evicted.
+     */
+    static subscribe(id: string): AsyncIterable<TaskEvent>;
+}
+
+/**
+ * Dynamic provider catalog loader (T10.1, ADR D447).
+ *
+ * Loads provider metadata from `provider-catalog.json` at runtime.
+ * Malformed entries are skipped with WARN (EC-1) — never crash.
+ *
+ * @internal
+ */
+
+interface ProviderCapabilities {
+    supportsToolUse: boolean;
+    supportsVision: boolean;
+    supportsStructuredOutput: boolean;
+    supportsStreaming: boolean;
+    supportsCacheControl: boolean;
+    maxContextTokens?: number;
+    maxOutputTokens?: number;
+}
+
+/**
+ * Account-level user info returned by `Theokit.me()`.
+ *
+ * @public
+ */
+interface SDKUser {
+    apiKeyName: string;
+    userEmail?: string;
+    createdAt: string;
+}
+/**
+ * Per-model parameter definition discovered from `Theokit.models.list()`.
+ *
+ * @public
+ */
+interface ModelParameterDefinition {
+    id: string;
+    displayName?: string;
+    values: Array<{
+        value: string;
+        displayName?: string;
+    }>;
+}
+/**
+ * Preset variant for a model — pre-filled parameter combinations.
+ *
+ * @public
+ */
+interface ModelVariant {
+    params: Array<{
+        id: string;
+        value: string;
+    }>;
+    displayName: string;
+    description?: string;
+    isDefault?: boolean;
+}
+/**
+ * Single model entry in the catalog.
+ *
+ * @public
+ */
+interface ModelListItem {
+    id: string;
+    /** Short, plain-text model name. Mirrors `displayName` for typical SDKs. */
+    name?: string;
+    displayName: string;
+    description?: string;
+    parameters?: ModelParameterDefinition[];
+    variants?: ModelVariant[];
+}
+/** @public */
+type SDKModel = ModelListItem;
+/**
+ * GitHub repository connected to the team. Cloud-only.
+ *
+ * @public
+ */
+interface SDKRepository {
+    url: string;
+}
+
+/**
+ * Options shared by every `Theokit.*` request.
+ *
+ * @public
+ */
+interface TheokitRequestOptions {
+    /** Override the `THEOKIT_API_KEY` env var for this call. */
+    apiKey?: string;
+    /**
+     * Target a specific provider for catalog reads. When set to a provider
+     * with `authType: "none"` (e.g. `"ollama"`, `"lmstudio"`, `"llamacpp"`),
+     * `Theokit.models.list({ provider })` reads from the provider's local
+     * `/v1/models` endpoint instead of the TheoCloud catalog. ADR D184.
+     *
+     * @public
+     */
+    provider?: string;
+}
+/**
+ * Account-level and catalog reads. All methods accept an optional `apiKey`
+ * and otherwise fall back to the `THEOKIT_API_KEY` environment variable.
+ *
+ * @public
+ */
+declare class Theokit {
+    private constructor();
+    /**
+     * Return the user behind the current API key.
+     *
+     * @public
+     */
+    static me(options?: TheokitRequestOptions): Promise<SDKUser>;
+    /**
+     * Model catalog reads.
+     *
+     * @public
+     */
+    static readonly models: {
+        list: (options?: TheokitRequestOptions) => Promise<SDKModel[]>;
+        capabilities: (providerOrModelId: string) => ProviderCapabilities | undefined;
+    };
+    /**
+     * Connected GitHub repositories for the calling user's team. Cloud only.
+     *
+     * @public
+     */
+    static readonly repositories: {
+        list: (options?: TheokitRequestOptions) => Promise<SDKRepository[]>;
+    };
+    /**
+     * Provider catalog. Lists every provider known to the platform, including
+     * plugin-registered ones, with capability and availability metadata.
+     *
+     * @public
+     */
+    static readonly providers: {
+        list: (options?: TheokitRequestOptions) => Promise<SDKProvider[]>;
+    };
+    /**
+     * Local introspection of bundled SDK assets (ADR D201). Unlike the
+     * cloud-catalog `providers.list()` (which hits the TheoCloud HTTP API),
+     * `inspect.*` reads the SDK's own bundled registries — useful for
+     * tooling (e.g. `@theokit/cli`'s `theokit inspect`) that needs to know
+     * what's available WITHOUT a network round-trip.
+     *
+     * @public
+     */
+    static readonly inspect: {
+        builtinProviders: () => Array<{
+            readonly name: string;
+            readonly apiMode: string;
+            readonly authType: string;
+            readonly baseUrl: string;
+            readonly aliases?: ReadonlyArray<string>;
+            readonly envVars: ReadonlyArray<string>;
+        }>;
+        embeddingAdapters: () => Array<{
+            readonly id: string;
+            readonly transport: string;
+            readonly defaultModel: string;
+        }>;
+    };
+}
+
+/**
+ * SE7 — `ToolError`: thrown FROM a tool `handler` to report a failure back to
+ * the model with structured content (text and/or an image), not just a string.
+ * Kept in its own module (not `errors.ts`) so the error taxonomy file stays
+ * under the G8 LoC budget and this tool-shaped error lives next to the tool
+ * surface it serves.
+ *
+ * @public
+ */
+
+/**
+ * Thrown from a tool `handler` to surface a failure to the model. The SDK turns
+ * it into a `tool_result` with `isError: true` carrying the content. A plain
+ * `Error` thrown from a handler still works (its message becomes text);
+ * `ToolError` is the opt-in for a clean message or a multimodal error (e.g. an
+ * error screenshot).
+ *
+ * @public
+ */
+declare class ToolError extends TheokitAgentError {
+    readonly name: string;
+    /** The error content surfaced to the model: a string, or text/image blocks. */
+    readonly content: string | ToolResultContentBlock[];
+    constructor(content: string | ToolResultContentBlock[], options?: {
+        code?: string;
+        cause?: unknown;
+        metadata?: ErrorMetadata;
+    });
+}
+
+/**
+ * Public types for ShareGPT trajectory export (ADR D139).
+ *
+ * Output format for fine-tuning datasets — consumed by HuggingFace, Axolotl,
+ * LLaMA-Factory, and most modern fine-tuning toolchains. Pure data shape;
+ * no runtime dependency.
+ *
+ * @public
+ */
+/**
+ * One ShareGPT message in a conversation. `from` identifies the role and
+ * `value` carries the textual content. Tool calls live in `tool_calls`
+ * (assistant-only) and tool results re-enter as `from: "tool"` entries.
+ *
+ * @public
+ */
+interface ShareGptMessage {
+    /** "human" for user, "gpt" for assistant, "tool" for tool result, "system" for system. */
+    from: "human" | "gpt" | "tool" | "system";
+    /** The message text. Empty string is valid (preserves turn boundary). */
+    value: string;
+    /** Optional tool calls — only emitted when `from === "gpt"`. */
+    tool_calls?: Array<{
+        name: string;
+        arguments: Record<string, unknown>;
+    }>;
+}
+/**
+ * One full ShareGPT-format trajectory — a single conversation plus
+ * metadata. JSONL-friendly (one trajectory per line when serialized).
+ *
+ * @public
+ */
+interface ShareGptTrajectory {
+    conversations: ShareGptMessage[];
+    metadata?: {
+        model?: string;
+        timestamp: string;
+        durationMs: number;
+        promptIndex: number;
+    };
+    /** `true` when the source `BatchResult.ok === true`. Always `true` in current shape. */
+    completed: boolean;
+    /** Token usage when surfaced by the underlying RunResult (provider-specific). */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+
+/**
+ * `toShareGptTrajectory` — opt-in BatchResult → ShareGPT converter (ADR D139).
+ *
+ * Pure transformation. Returns `null` for failed results so callers can
+ * filter via `.map(toShareGptTrajectory).filter(Boolean)`. Tool calls and
+ * tool results are preserved when an SDKMessage trace is provided; otherwise
+ * a minimal `human → gpt` trajectory is emitted from the final text.
+ *
+ * @public
+ */
+
+/**
+ * Convert a successful `BatchResult` to ShareGPT-format trajectory.
+ *
+ * Behavior:
+ * - `result.ok === false` → returns `null` (EC-11).
+ * - First entry is always `{from: "human", value: result.prompt}`.
+ * - When `options.messages` is supplied, each SDKMessage maps to one or
+ *   more ShareGPT entries (assistant text → gpt, tool_use → gpt + tool).
+ * - Without `options.messages`, fall back to a single `{from: "gpt"}`
+ *   entry carrying `result.result.result` (the final text) when present.
+ * - Malformed message entries are silently skipped (EC-F / EC-14).
+ *
+ * @public
+ */
+declare function toShareGptTrajectory(result: BatchResult, options?: {
+    messages?: SDKMessage[];
+    model?: string;
+}): ShareGptTrajectory | null;
+
+export { Agent, AgentBuilder, AgentDefinition, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, CustomTool, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DreamingSweepOptions, type DreamingSweepResult, ErrorMetadata, EventBus, type EvictReason, GOAL_CONTINUATION_MARKER, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, GoalEvent, type GoalLoopAgent, GoalOptions, GoalResult, InlineSkill, JobQueue, type JobQueueOptions, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, PermissionEngine, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, Plugin, PluginsSettings, PreToolCallDecision, Processor, Provider, ProviderProfile, ProviderRoutingSettings, Run, RunEventSink, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, Security, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, Squad, type SquadOptions, type SquadRun, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, ToolResultContentBlock, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, estimateTokens, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, runGoalLoop, scopedConversationId, sessionScopePrefix, toShareGptTrajectory, withCwdMutex };