@theokit/sdk 1.5.0

package/dist/index.d.cts

@@ -0,0 +1,1878 @@
+import { T as TheokitAgentError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot } from './errors-CK8brCJ1.cjs';
+export { A as AgentRunError, c as AgentRunErrorCode, d as AuthenticationError, e as BudgetExceedEvent, f as BudgetExceededError, g as BudgetLimit, h as BudgetMode, i as BudgetScope, j as BudgetThresholdEvent, k as BudgetWindow, C as ConfigurationError, E as ErrorCode, l as ErrorMetadata, I as IntegrationNotConnectedError, m as InvalidTaskIdError, M as MemoryAdapterError, n as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, o as TaskNotFoundError, U as UnknownAgentError, p as UnsupportedBudgetOperationError, q as UnsupportedRunOperationError, r as UnsupportedTaskOperationError } from './errors-CK8brCJ1.cjs';
+import { A as AgentOptions, R as RunResult, M as ModelSelection, L as LocalOptions, P as ProviderRoutingSettings, S as SystemPromptResolver, C as CloudOptions, a as MemorySettings, b as CustomTool, c as McpServerConfig, d as AgentDefinition, e as ContextSettings, f as PluginsSettings, g as SkillsSettings, h as SDKAgent, i as ListAgentsOptions, j as ListResult, k as SDKAgentInfo, G as GetAgentOptions, l as ListRunsOptions, m as Run, n as GetRunOptions, o as AgentOperationOptions, H as HandoffOptions, p as HandoffDescriptor, q as ConversationStorageAdapter, r as StoredMessage, s as MemoryId, t as SDKProvider, u as SDKMessage } from './run-DkCD5DeO.cjs';
+export { v as AgentConversationTurn, w as AgentMemory, x as AssistantMessage, y as CloudEnv, z as CloudRepo, B as ContextBudget, D as ContextManagerKind, E as ContextSnapshot, F as ContextSource, I as ContextSourceStatus, J as ConversationStep, K as ConversationTurn, N as CostBreakdown, O as CostSource, Q as CostStatus, T as GoalEvent, U as GoalOptions, V as GoalResult, W as HandoffContext, X as HandoffHistory, Y as HandoffLoopError, Z as HandoffNameCollisionError, _ as HandoffPairLoopError, $ as HandoffReceiverDisposedError, a0 as HandoffResult, a1 as HandoffSelfReferenceError, a2 as InteractionUpdate, a3 as InvalidateCacheOptions, a4 as McpAuthConfig, a5 as McpHttpServerConfig, a6 as McpOAuthConfig, a7 as McpStdioServerConfig, a8 as MemoryAdapter, a9 as MemoryAdapterCapabilities, aa as MemoryContext, ab as MemoryFact, ac as MemoryRevision, ad as MemoryToolSchema, ae as MemoryTurnMessage, af as ModelParameterValue, ag as PartialToolCallUpdate, ah as PersonalityPreset, ai as ProviderCapability, aj as ProviderRoute, ak as ResolvedProviderRoute, al as RunErrorDetail, am as RunGitInfo, an as RunOperation, ao as RunStatus, ap as RunUntilIterator, aq as SDKAgentPlugins, ar as SDKAgentSkills, as as SDKArtifact, at as SDKAssistantMessage, au as SDKContextManager, av as SDKImage, aw as SDKImageDimension, ax as SDKObjectDelta, ay as SDKPluginMetadata, az as SDKProvidersManager, aA as SDKRequestMessage, aB as SDKStatusMessage, aC as SDKSystemMessage, aD as SDKTaskMessage, aE as SDKThinkingMessage, aF as SDKToolUseMessage, aG as SDKUserMessage, aH as SDKUserMessageEvent, aI as SendOptions, aJ as SettingSource, aK as ShellCommand, aL as ShellConversationTurn, aM as ShellOutput, aN as ShellOutputDeltaUpdate, aO as StepCompletedUpdate, aP as StepStartedUpdate, aQ as SummaryCompletedUpdate, aR as SummaryStartedUpdate, aS as SummaryUpdate, aT as SystemPromptContext, aU as SystemPromptMemoryFact, aV as SystemPromptSkillRef, aW as TelemetrySettings, aX as TextBlock, aY as TextDeltaUpdate, aZ as ThinkingCompletedUpdate, a_ as ThinkingDeltaUpdate, a$ as ThinkingMessage, b0 as TokenDeltaUpdate, b1 as TokenUsage, b2 as ToolCall, b3 as ToolCallCompletedUpdate, b4 as ToolCallStartedUpdate, b5 as ToolUseBlock, b6 as TurnEndedUpdate, b7 as UserMessage, b8 as UserMessageAppendedUpdate } from './run-DkCD5DeO.cjs';
+import * as zod from 'zod';
+import { ZodType, z } from 'zod';
+export { C as Cron, a as CronCreateOptions, b as CronGetOptions, c as CronJob, d as CronJobStatus, e as CronListOptions, f as CronOperationOptions, g as CronRunOptions, h as CronRuntime, i as CronSchedulerStatus, j as CronStartOptions } from './cron-1yxL3K2S.cjs';
+
+/**
+ * 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;
+    model: 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). */
+    model: 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;
+}
+/**
+ * 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);
+    model(m: 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>;
+    /**
+     * 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>;
+}
+/**
+ * Capture a common {@link AgentOptions} prefix and produce per-session agents
+ * with focused overrides. Useful for chat-bot patterns where most config is
+ * shared across users/sessions.
+ *
+ * Merge rules (ADR D23):
+ * - Top-level shallow merge with `overrides` winning.
+ * - Deep merge for `local`, `memory`, `cloud` (configuration objects with
+ *   non-conflicting flat keys).
+ * - Total replace for `mcpServers`, `agents`, `tools`, `providers`,
+ *   `plugins`, `skills`, `context` (collection-shaped).
+ * - The function-level `agentId` always wins over both `common.agentId` and
+ *   `overrides.agentId`.
+ *
+ * The factory holds `common` by reference — mutating it after construction
+ * leaks to subsequent `forSession` calls (documented caveat).
+ *
+ * @public
+ */
+declare function createAgentFactory(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/hermes-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:
+ *   - cline#10266 — OpenAI-compat proxies (OpenRouter, Vercel AI Gateway,
+ *     Cline) 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$1 = "anthropic_messages" | "openai_chat_completions" | "openai_responses";
+declare function inferApiMode(provider: string): ApiMode$1;
+declare function normalizeUsage(rawUsage: unknown, opts: {
+    provider: string;
+    apiMode?: ApiMode$1;
+}): 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 openai-agents-python
+ * `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
+ */
+
+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[];
+}
+
+/**
+ * ProviderProfile + ApiMode types (T3.1, ADR D105).
+ *
+ * Profile is **data-only** — no methods. Adding a provider is declaring an
+ * object literal; the Transport layer (D106) consumes `apiMode` to pick
+ * the HTTP dialect.
+ *
+ * @public
+ */
+type ApiMode = "chat_completions" | "anthropic_messages" | "responses_api" | "bedrock" | "bedrock_anthropic";
+type AuthType = "api_key" | "oauth_device_code" | "oauth_external" | "aws_sdk" | "aws_bearer" | "gcp_oauth" | "none";
+interface ProviderProfile {
+    name: string;
+    apiMode: ApiMode;
+    aliases?: ReadonlyArray<string>;
+    displayName?: string;
+    description?: string;
+    signupUrl?: string;
+    envVars: ReadonlyArray<string>;
+    authType: AuthType;
+    baseUrl: string;
+    modelsUrl?: string;
+    hostname?: string;
+    fallbackModels: ReadonlyArray<string>;
+    extraHeaders?: Record<string, string>;
+    bodyOverrides?: Record<string, unknown>;
+}
+
+type HookName = "pre_tool_call" | "post_tool_call" | "pre_llm_call" | "post_llm_call" | "on_session_start" | "on_session_end" | "transform_tool_result" | "transform_llm_output" | "pre_user_send" | "post_assistant_reply";
+interface PreToolCallContext {
+    name: string;
+    args: Record<string, unknown>;
+    agentId: string;
+    runId: string;
+}
+interface PreToolCallDecision {
+    block: true;
+    message: string;
+}
+type HookHandler = (ctx: unknown) => unknown | Promise<unknown>;
+type CommandHandler = (args: Record<string, unknown>) => Promise<string> | string;
+interface CommandOptions {
+    description?: string;
+}
+interface PluginContext {
+    /** Register a custom tool. Equivalent to passing in `AgentOptions.tools`. */
+    registerTool(tool: CustomTool): void;
+    /** Register a slash-command-style handler. Consumed by CLI/bot wrappers; NOT used by the agent loop. */
+    registerCommand(name: string, handler: CommandHandler, opts?: CommandOptions): void;
+    /** Attach a hook handler. `pre_tool_call` supports veto via `PreToolCallDecision`. */
+    on(hook: HookName, handler: HookHandler): void;
+    /** Inject a user/system message into the next agent turn. v1 supports only `on_session_start` context. */
+    injectMessage(content: string, role?: "user" | "system"): void;
+}
+interface BasePlugin {
+    name: string;
+    version: string;
+}
+type Plugin = (BasePlugin & {
+    kind: "general";
+    register: (ctx: PluginContext) => void | Promise<void>;
+}) | (BasePlugin & {
+    kind: "model-provider";
+    profile: ProviderProfile;
+}) | (BasePlugin & {
+    kind: "memory";
+    createProvider: MemoryProviderFactory;
+});
+/**
+ * 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;
+
+/**
+ * Public type contract for `Cache.semantic / .asPlugin / .stats / .clear`
+ * (Adoption Roadmap #6; ADRs D249-D266).
+ *
+ * @public
+ */
+interface CacheTTLConfig {
+    /** Default TTL applied to all entries. Format: `"1h" | "30m" | 86400 (seconds)`. */
+    readonly default: string | number;
+    /** Regex marking queries that must NEVER be cached (e.g. /weather|today|now/i). */
+    readonly exclude?: RegExp;
+}
+interface CachePersistenceOptions {
+    readonly backend: "memory" | "json";
+    /** Required when backend = "json". */
+    readonly dir?: string;
+}
+/**
+ * Embedder runtime shape — minimal subset of `EmbeddingRuntime` (D11) the
+ * Cache actually uses. Lets tests inject fake embedders without pulling
+ * the full memory subsystem.
+ */
+interface CacheEmbedderRuntime {
+    readonly id: string;
+    readonly model: string;
+    readonly dimension: number;
+    embed(texts: ReadonlyArray<string>): Promise<number[][]>;
+}
+interface CacheSemanticOptions {
+    /** Embedder instance. REQUIRED in v1 — no autoselect (avoids surprise API calls). */
+    readonly embedder: CacheEmbedderRuntime;
+    /** Cosine distance threshold (0..2). Default 0.85; lower = stricter. */
+    readonly threshold?: number;
+    /** TTL config. Default `{ default: "1h" }`. */
+    readonly ttl?: CacheTTLConfig;
+    /** Multi-tenant namespace. Default `"global"`. */
+    readonly namespace?: string;
+    /** Default modelId attached to entries when caller doesn't override. */
+    readonly modelId?: string;
+    /** Max entries (LRU eviction). Default 1000. */
+    readonly maxEntries?: number;
+    /** Persistence backend. Default in-memory. */
+    readonly persistence?: CachePersistenceOptions;
+}
+interface CacheEntry {
+    readonly key: string;
+    readonly namespace: string;
+    readonly embedderId: string;
+    readonly modelId: string;
+    readonly prompt: string;
+    readonly response: string;
+    readonly vector: ReadonlyArray<number>;
+    readonly createdAt: number;
+    readonly expiresAt: number;
+    readonly accessedAt: number;
+    readonly accessCount: number;
+}
+interface CacheStats {
+    readonly entries: number;
+    readonly kvHits: number;
+    readonly semanticHits: number;
+    readonly misses: number;
+    readonly excluded: number;
+    readonly evicted: number;
+    readonly embedderFailures: number;
+}
+declare class CacheEmbedderError extends Error {
+    readonly name = "CacheEmbedderError";
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+declare class CacheInvalidTtlError extends Error {
+    readonly input: string | number;
+    readonly name = "CacheInvalidTtlError";
+    constructor(input: string | number);
+}
+
+/**
+ * Public `Cache` class — semantic LLM response cache (Adoption Roadmap #6;
+ * ADRs D249-D266).
+ *
+ * Usage:
+ *
+ *   import { Agent, Cache, definePlugin } from "@theokit/sdk";
+ *
+ *   const cache = Cache.semantic({
+ *     embedder: myEmbedderRuntime,    // EmbeddingRuntime (D11)
+ *     threshold: 0.85,
+ *     ttl: { default: "1h", exclude: /weather|today|now/i },
+ *     namespace: "my-app",
+ *     modelId: "openai/gpt-4o-mini",
+ *   });
+ *
+ *   const agent = await Agent.create({
+ *     model: { id: "openai/gpt-4o-mini" },
+ *     plugins: [cache.asPlugin()],
+ *     // ...
+ *   });
+ *
+ *   await agent.send("What is the capital of France?");   // miss → LLM
+ *   await agent.send("Tell me the capital of France");    // semantic hit
+ *
+ * @public
+ */
+
+declare class Cache {
+    private readonly embedder;
+    private readonly threshold;
+    private readonly ttl;
+    private readonly namespace;
+    private readonly modelId;
+    private readonly store;
+    private _plugin?;
+    private constructor();
+    static semantic(options: CacheSemanticOptions): Cache;
+    /**
+     * EC-4 absorbed: memoized so repeated `asPlugin()` calls return the SAME
+     * plugin descriptor — no duplicate hook registration.
+     */
+    asPlugin(): Plugin;
+    /**
+     * Explicit cache lookup — callers that want true LLM short-circuit
+     * call this BEFORE `agent.send()`, then dispatch to the LLM only on miss.
+     *
+     * v1 plugin mode provides recall + context-inject (LLM still called).
+     * v1.x will add transparent short-circuit via an agent-loop refactor.
+     */
+    consult(prompt: string): Promise<{
+        hit: false;
+    } | {
+        hit: true;
+        response: string;
+        source: "kv" | "semantic";
+        distance?: number;
+    }>;
+    /**
+     * Explicit cache store — pair with `consult()` to manually feed the
+     * cache after dispatching the LLM call yourself.
+     */
+    remember(prompt: string, response: string, opts?: {
+        usedTools?: boolean;
+    }): Promise<void>;
+    /** Stats snapshot — primary observable for dogfood verification. */
+    stats(): CacheStats;
+    /** Clear all entries (and flush to disk if JSON backend). */
+    clear(): Promise<void>;
+    /** Force-evict expired entries. Returns count removed. */
+    evictExpired(now?: number): 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
+ */
+interface DefineToolSpec<T extends ZodType> {
+    /** 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;
+    /** Handler invoked with the parsed input. Type is inferred via `z.infer<T>`. */
+    handler: (input: z.infer<T>) => string | Promise<string>;
+}
+/**
+ * Type-safe builder for {@link CustomTool}. Converts a Zod schema to JSON
+ * Schema (for the LLM-facing `inputSchema` field), wraps the handler with a
+ * runtime `schema.parse` step, and preserves type inference.
+ *
+ * Behaviour (ADR D24):
+ * - JSON Schema conversion uses Zod 4's native `z.toJSONSchema` with
+ *   `unrepresentable: "any"` so transforms/refinements round-trip.
+ * - Runtime parse failures throw `ZodError`; the SDK's tool-dispatch converts
+ *   them to `tool_result(isError)` with the Zod message.
+ * - Handler signature is `(input: z.infer<T>)`, not `Record<string, unknown>`.
+ * - `zod` loads lazily via `createRequire` — consumers who don't call
+ *   `defineTool` don't need `zod` installed.
+ *
+ * @public
+ */
+declare function defineTool<T extends ZodType>(spec: DefineToolSpec<T>): CustomTool;
+
+/**
+ * Public `Handoff` class — factory for handoff descriptors (Adoption
+ * Roadmap #4; ADRs D214-D229).
+ *
+ * Usage:
+ *
+ *   import { Agent, Handoff } from "@theokit/sdk";
+ *
+ *   const billing = await Agent.create({
+ *     name: "billing",
+ *     systemPrompt: "You handle billing questions.",
+ *     model: { id: "openai/gpt-4o-mini" },
+ *     apiKey: process.env.OPENROUTER_API_KEY,
+ *   });
+ *
+ *   const triage = await Agent.create({
+ *     name: "triage",
+ *     systemPrompt: "Classify the user's intent and transfer to the right specialist.",
+ *     model: { id: "openai/gpt-4o-mini" },
+ *     apiKey: process.env.OPENROUTER_API_KEY,
+ *     handoffs: [
+ *       billing,  // auto-wrapped as Handoff.create(billing)
+ *       Handoff.create(supportAgent, { inputFilter: redactCreditCards }),
+ *     ],
+ *   });
+ *
+ * @public
+ */
+
+/** Recommended system-prompt prefix for senders (D215 / EC-13). */
+declare const RECOMMENDED_HANDOFF_PROMPT_PREFIX: string;
+declare class Handoff {
+    private constructor();
+    /**
+     * Build a `HandoffDescriptor` for a target agent. Wrap with custom options
+     * (filter / inputType / callback / whitelist / etc); pass to
+     * `Agent.create({ handoffs: [...] })`.
+     *
+     * Raw `SDKAgent` instances in `handoffs[]` are auto-wrapped by the runtime
+     * — call `Handoff.create()` explicitly only when you need to customize.
+     */
+    static create<TInput extends ZodType = ZodType>(target: SDKAgent, options?: HandoffOptions<TInput>): HandoffDescriptor<TInput>;
+}
+/**
+ * Imperative escape hatch (D225). Useful for tests / programmatic flows
+ * that need deterministic handoff without LLM routing.
+ *
+ * NOTE: this is a STANDALONE helper rather than a method on `SDKAgent`
+ * to avoid invasive refactor of the agent class. Behavior is identical
+ * to invoking the corresponding synthetic tool would be.
+ */
+declare function handoffTo(sender: SDKAgent, target: SDKAgent, message: string, options?: HandoffOptions): Promise<string>;
+
+/**
+ * Filesystem-backed implementation of {@link ConversationStorageAdapter}
+ * (Production-Readiness #1, ADR D304).
+ *
+ * Default adapter when `AgentOptions.conversationStorage` is not provided.
+ * Writes append-only JSONL to `<root>/.theokit/agents/<safeId>/messages.jsonl`,
+ * preserving the pre-D303 byte-identical behavior (redaction D68 + JSONL
+ * line granularity).
+ *
+ * Path safety: every conversationId flows through `sanitizeIdentifier` +
+ * `safePathJoin` before touching disk. `deleteConversation` re-applies the
+ * guard (EC-1) — without this the new `rm -rf` would escape via traversal.
+ *
+ * Listing: `listConversationIds` catches ENOENT (EC-2) so first-run deploys
+ * without any `.theokit/agents/` directory return `[]` instead of crashing.
+ *
+ * @public
+ */
+
+interface FileSystemConversationStorageOptions {
+    /** Root directory under which `.theokit/agents/<id>/` lives. Defaults to `process.cwd()`. */
+    root?: string;
+}
+declare class FileSystemConversationStorage implements ConversationStorageAdapter {
+    #private;
+    constructor(opts?: FileSystemConversationStorageOptions);
+    /** Exposed for tests + diagnostics. The path is sanitized at use sites. */
+    get root(): string;
+    getMessages(conversationId: string): Promise<readonly StoredMessage[]>;
+    appendMessage(conversationId: string, message: StoredMessage): Promise<void>;
+    deleteConversation(conversationId: string): Promise<void>;
+    listConversationIds(opts?: {
+        limit?: number;
+    }): Promise<readonly string[]>;
+    compact(conversationId: string, maxTurns: number): Promise<void>;
+    dispose(): Promise<void>;
+}
+
+/**
+ * In-memory implementation of {@link ConversationStorageAdapter} (Production-Readiness #1, ADR D304).
+ *
+ * Intended for tests + ephemeral single-process dev/CLI usage. Holds messages
+ * in a `Map<conversationId, StoredMessage[]>`. JavaScript's single-threaded
+ * runtime makes per-conversation appends naturally atomic; no external mutex
+ * needed.
+ *
+ * The adapter returns defensive copies from `getMessages` so callers cannot
+ * mutate internal state by holding a reference to the returned array.
+ *
+ * @public
+ */
+
+declare class InMemoryConversationStorage implements ConversationStorageAdapter {
+    #private;
+    getMessages(conversationId: string): Promise<readonly StoredMessage[]>;
+    appendMessage(conversationId: string, message: StoredMessage): Promise<void>;
+    deleteConversation(conversationId: string): Promise<void>;
+    listConversationIds(opts?: {
+        limit?: number;
+    }): Promise<readonly string[]>;
+    dispose(): Promise<void>;
+}
+
+/**
+ * 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>;
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+/** 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>;
+}
+
+/**
+ * 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[]>;
+    };
+    /**
+     * 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;
+        }>;
+    };
+}
+
+/**
+ * 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, type AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, Cache, CacheEmbedderError, type CacheEmbedderRuntime, type CacheEntry, CacheInvalidTtlError, type CachePersistenceOptions, type CacheSemanticOptions, type CacheStats, type CacheTTLConfig, CloudOptions, ContextSettings, ConversationStorageAdapter, CustomTool, type DeepPartial, type DefineToolSpec, type DreamingSweepOptions, type DreamingSweepResult, type EvictReason, FileSystemConversationStorage, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, Handoff, HandoffDescriptor, HandoffOptions, type HookName, InMemoryConversationStorage, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryId, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, type Plugin, type PluginContext, PluginsSettings, type PreToolCallContext, type PreToolCallDecision, type ProviderProfile, ProviderRoutingSettings, RECOMMENDED_HANDOFF_PROMPT_PREFIX, Run, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, Security, type ShareGptMessage, type ShareGptTrajectory, SkillsSettings, StoredMessage, 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, UsageAccumulator, chargeAndCheckThresholds, computeCost, createAgentFactory, definePlugin, defineTool, extractRawId, getPricingEntry, handoffTo, inferApiMode, isValidTaskId, migrateSqliteToLance, mkMemoryId, normalizeUsage, preflightCheck, toShareGptTrajectory };