@theokit/sdk 1.5.0

package/dist/run-DkCD5DeO.d.cts

@@ -0,0 +1,2181 @@
+import { ZodType } from 'zod';
+
+/**
+ * Public event types emitted by {@link SDKAgent.runUntil} (ADRs D115-D117).
+ *
+ * Discriminated union by `type` field so consumers can `switch (event.type)`
+ * with full TypeScript exhaustiveness. Mirrors the
+ * {@link import("../stream-object.js").StreamObjectEvent} pattern (ADR D39).
+ *
+ * @public
+ */
+/**
+ * Single event emitted while iterating a goal-driven loop. Five variants:
+ *
+ * - `turn_start` — the agent is about to invoke `send()`. Emitted once
+ *   per turn.
+ * - `agent_response` — the agent's `send()` resolved; carries the text
+ *   reply.
+ * - `judge_verdict` — the auxiliary judge model evaluated the response.
+ *   `parseFailed: true` indicates the judge returned a malformed reply
+ *   (fail-safe verdict = `continue`, see ADR D121).
+ * - `continuation` — the judge ruled `continue`; carries the prompt that
+ *   was sent on THIS turn (i.e., the input that produced the agent
+ *   response just yielded). Useful for consumers who want to audit the
+ *   exact continuation message that drove each iteration. The prompt
+ *   for the NEXT turn is composed lazily at the start of that turn
+ *   from the latest `agent_response.content`.
+ * - `status_change` — transition of the overall goal state. Always
+ *   emitted once at start (`active`) and once at end
+ *   (`completed | failed | paused`).
+ *
+ * @public
+ */
+type GoalEvent = {
+    type: "turn_start";
+    turn: number;
+    goal: string;
+} | {
+    type: "agent_response";
+    turn: number;
+    content: string;
+} | {
+    type: "judge_verdict";
+    turn: number;
+    verdict: "done" | "continue" | "skipped";
+    reason: string;
+    parseFailed: boolean;
+} | {
+    type: "continuation";
+    turn: number;
+    prompt: string;
+} | {
+    type: "status_change";
+    status: "active" | "paused" | "completed" | "failed";
+    reason: string;
+};
+/**
+ * Return value of the `runUntil` async generator. Consumer reads via
+ * `const { value } = await gen.next()` (when `done: true`).
+ *
+ * @public
+ */
+interface GoalResult {
+    status: "completed" | "failed" | "paused";
+    turnsUsed: number;
+    finalResponse: string | undefined;
+}
+/**
+ * Return type of {@link import("../internal/runtime/local-agent.js").LocalAgent.runUntil}.
+ * Extracted so the LocalAgent method signature stays a single line (G8 LoC budget).
+ *
+ * @public
+ */
+type RunUntilIterator = AsyncGenerator<GoalEvent, GoalResult, void>;
+/**
+ * Per-call configuration for `Agent.runUntil`.
+ *
+ * @public
+ */
+interface GoalOptions {
+    /** Hard cap on iterations. Default `20`. */
+    maxTurns?: number;
+    /** Bail after N consecutive judge parse failures. Default `3` (ADR D121). */
+    maxConsecutiveJudgeFailures?: number;
+    /** Judge model identifier. Default `"openai/gpt-4o-mini"` (ADR D119). */
+    judgeModel?: string;
+    /** Override env for the judge auxiliary agent. Default `OPENROUTER_API_KEY` (EC-A). */
+    judgeApiKey?: string;
+    /** Optional subgoals fed to the judge prompt. */
+    subgoals?: string[];
+    /**
+     * Cancel mid-loop via `AbortController.signal`. The generator yields
+     * a `status_change: paused` event and returns at the next turn
+     * boundary (ADR D117).
+     */
+    signal?: AbortSignal;
+}
+
+/**
+ * Pluggable persistence for conversation history (Production-Readiness #1, ADRs D303-D306).
+ *
+ * The default {@link FileSystemConversationStorage} writes append-only JSONL
+ * to `<cwd>/.theokit/agents/<id>/messages.jsonl`. Custom adapters back the
+ * SDK against Postgres, Redis, Durable Objects, or any other store — required
+ * for serverless deploys (Vercel, Cloudflare Workers) and multi-host setups
+ * (K8s replicas, TheoCloud) where the filesystem is ephemeral or not shared.
+ *
+ * @public
+ */
+/**
+ * Persisted message envelope used by {@link ConversationStorageAdapter}.
+ *
+ * The shape is deliberately narrower than the full {@link SDKMessage} variant
+ * tree — only durable content survives. `role` covers all message origins the
+ * SDK persists today (user/assistant) plus the forward-compat slots for
+ * tool-shaped messages (ADR D310 / EC-10).
+ *
+ * @public
+ */
+interface StoredMessage {
+    /** Origin of the message. `tool_call` / `tool_result` reserved for forward compat. */
+    role: "user" | "assistant" | "system" | "tool_call" | "tool_result";
+    /** UTF-8 payload. May be empty string (e.g., a tool with no return value). */
+    content: string;
+    /** Optional epoch-ms timestamp. Implementations MAY default to `Date.now()` on append. */
+    at?: number;
+}
+/**
+ * Pluggable conversation persistence contract.
+ *
+ * Implementations MUST be safe under concurrent append from a single process
+ * — the SDK runtime serializes per-(agent,cwd) but adapters serving multiple
+ * processes are responsible for their own atomicity.
+ *
+ * All methods return `Promise<>` even for synchronous backends (in-memory).
+ * Polymorphism uniformity beats the ~1μs microtask cost (ADR D306).
+ *
+ * @public
+ */
+interface ConversationStorageAdapter {
+    /**
+     * Return the full message history for a conversation, in insertion order.
+     * MUST return `[]` (not throw) when the conversation does not exist.
+     */
+    getMessages(conversationId: string): Promise<readonly StoredMessage[]>;
+    /**
+     * Append a single message to the conversation.
+     * MUST be atomic — concurrent appends MUST NOT corrupt the log.
+     * MUST create the conversation lazily if it does not exist.
+     */
+    appendMessage(conversationId: string, message: StoredMessage): Promise<void>;
+    /**
+     * Delete the entire conversation. MUST be idempotent (delete-of-missing = ok).
+     */
+    deleteConversation(conversationId: string): Promise<void>;
+    /**
+     * Optional: list conversation ids. Used by housekeeping flows.
+     * Implementations that cannot enumerate (e.g., wildcards too expensive on
+     * production Redis) MAY return `undefined` to signal "not supported".
+     */
+    listConversationIds?(opts?: {
+        limit?: number;
+    }): Promise<readonly string[] | undefined>;
+    /**
+     * Optional FS-specific compaction trigger (ADR D304). The default FS adapter
+     * trims old turns past a soft cap; other backends typically no-op.
+     */
+    compact?(conversationId: string, maxTurns: number): Promise<void>;
+    /**
+     * Optional: dispose underlying handles (close DB pool, etc.).
+     * MUST be safe to call multiple times.
+     */
+    dispose?(): Promise<void>;
+}
+
+/**
+ * Public types for `Agent.create({ handoffs })` + `Handoff.create()` +
+ * `Agent.handoffTo()` (Adoption Roadmap #4; ADRs D214-D229).
+ *
+ * Pattern: handoff-as-tool. Each handoff destination becomes a synthetic
+ * `transfer_to_<receiver>` function tool exposed to the LLM. Runtime
+ * intercepts the tool call and routes the next turn to the receiver.
+ *
+ * @public
+ */
+
+/**
+ * Context handed to `onHandoff` callbacks and `isEnabled` predicates.
+ * Read-only snapshot of the handoff dispatch state.
+ */
+interface HandoffContext {
+    readonly senderAgentId: string;
+    readonly receiverAgentId: string;
+    /** Depth counter AT dispatch time (post-increment; first handoff = 1). */
+    readonly currentDepth: number;
+    /** Chain of agentIds traversed so far in this send(). Always ends with sender. */
+    readonly chain: ReadonlyArray<string>;
+}
+/**
+ * The transcript wrapper passed to `inputFilter`. `messages` is widened to
+ * `unknown[]` so this type doesn't import from `messages.ts` (avoids cycle
+ * — implementations cast to `SDKMessage[]` internally).
+ */
+interface HandoffHistory {
+    readonly messages: ReadonlyArray<unknown>;
+}
+/**
+ * Options accepted by `Handoff.create(target, opts?)`.
+ *
+ * @public
+ */
+interface HandoffOptions<TInput extends ZodType = ZodType> {
+    /** Override the default tool name `transfer_to_<receiver.name>` (D215). */
+    readonly toolName?: string;
+    /** Override the default tool description. */
+    readonly toolDescription?: string;
+    /**
+     * Side-effect callback fired BEFORE the receiver takes over.
+     *
+     * **Semantics (D227):** throwing aborts the handoff — the synthetic tool
+     * returns `tool_error: onHandoff_failed: <message>` so the LLM sees the
+     * conflict. Logger-style consumers MUST wrap their own try/catch to
+     * swallow exceptions.
+     */
+    readonly onHandoff?: (ctx: HandoffContext, parsed: TInput extends ZodType ? unknown : undefined) => void | Promise<void>;
+    /**
+     * Zod schema for the handoff tool-call arguments (structured payload).
+     * When set, LLM-provided args are validated before `onHandoff` fires.
+     *
+     * **Edge case (D229):** empty/null `inputJson` parses as `{}` before
+     * Zod refinements fire — required-field schemas still throw normally.
+     */
+    readonly inputType?: TInput;
+    /**
+     * Filter the history passed to the receiver (D216 default = full; D219).
+     *
+     * **Resilience (D228):** if this callback throws, the runtime logs once
+     * to stderr and falls back to the un-filtered history. Use this for
+     * privacy redaction; if you need fatal-on-failure semantics, throw in
+     * `onHandoff` instead.
+     */
+    readonly inputFilter?: (history: HandoffHistory) => HandoffHistory | Promise<HandoffHistory>;
+    /**
+     * Restrict the receiver's tools for the post-handoff turn ONLY (D224).
+     * Subsequent receiver-internal turns use the receiver's full tool set.
+     */
+    readonly tools?: ReadonlyArray<string>;
+    /**
+     * Dynamically enable/disable this handoff. Bool = static; predicate =
+     * called per-`Agent.send()` to evaluate.
+     */
+    readonly isEnabled?: boolean | ((ctx: HandoffContext) => boolean | Promise<boolean>);
+}
+/**
+ * Result of a single handoff dispatch (for telemetry / observability).
+ *
+ * @public
+ */
+interface HandoffResult {
+    readonly from: string;
+    readonly to: string;
+    readonly depth: number;
+    readonly toolName: string;
+    readonly reasonFromLlm?: string;
+}
+/** Throw when handoff depth exceeds `maxHandoffDepth` (default 5; D218). */
+declare class HandoffLoopError extends Error {
+    readonly name = "HandoffLoopError";
+    readonly depth: number;
+    readonly chain: ReadonlyArray<string>;
+    constructor(depth: number, chain: ReadonlyArray<string>);
+}
+/** Throw when the same (sender, receiver) pair invoked twice in one send() (D221). */
+declare class HandoffPairLoopError extends Error {
+    readonly name = "HandoffPairLoopError";
+    readonly senderAgentId: string;
+    readonly receiverAgentId: string;
+    constructor(senderAgentId: string, receiverAgentId: string);
+}
+/** Throw when an agent's `handoffs[]` includes a self-reference (EC-6). */
+declare class HandoffSelfReferenceError extends Error {
+    readonly name = "HandoffSelfReferenceError";
+    readonly agentId: string;
+    constructor(agentId: string);
+}
+/** Throw when receiver is disposed at dispatch time (EC-5). */
+declare class HandoffReceiverDisposedError extends Error {
+    readonly name = "HandoffReceiverDisposedError";
+    readonly receiverAgentId: string;
+    constructor(receiverAgentId: string);
+}
+/** Throw when two handoffs in the same parent collide on tool name (D215). */
+declare class HandoffNameCollisionError extends Error {
+    readonly name = "HandoffNameCollisionError";
+    readonly conflictingName: string;
+    constructor(conflictingName: string);
+}
+/**
+ * Public `Handoff` shape — what `Handoff.create()` returns. Read-only
+ * accessors only; behavior lives in the engine.
+ *
+ * @public
+ */
+interface HandoffDescriptor<TInput extends ZodType = ZodType> {
+    readonly target: SDKAgent;
+    readonly options: HandoffOptions<TInput>;
+    /** Resolved tool name (after applying toolName override or default `transfer_to_<receiver>`). */
+    readonly resolvedToolName: string;
+}
+
+/**
+ * Public `MemoryAdapter` contract (T1.1, ADRs D141 / D147).
+ *
+ * The plugin extension point `{ kind: "memory" }` (ADR D98) declares a
+ * `createProvider` factory; this file types its return value formally.
+ * Adapters implement `write` / `recall` / `delete` plus optional methods
+ * gated by `capabilities`. `MemoryId` is a branded string prefixed with
+ * the adapter id so cross-adapter use throws on `extractRawId` (EC-B).
+ *
+ * Each provider-specific package (`@theokit-memory-supermemory`, etc)
+ * exports a factory returning a `Plugin { kind: "memory" }` whose
+ * `createProvider` resolves to a `MemoryAdapter` instance.
+ *
+ * @public
+ */
+/**
+ * Branded provider memory ID. Format: `${adapterId}:${rawProviderId}`.
+ * Use `mkMemoryId` / `extractRawId` from `../memory-adapter-helpers.js`
+ * to construct and unwrap with cross-adapter safety (EC-B).
+ *
+ * @public
+ */
+type MemoryId = string & {
+    readonly __brand: "MemoryId";
+};
+/**
+ * Portable identity context. `userId` is the only required field —
+ * the lowest common denominator across Supermemory / Honcho / Mem0.
+ * Adapter implementations translate the optional fields to their
+ * provider's native primitives (Honcho session, Mem0 run_id, etc).
+ *
+ * @public
+ */
+interface MemoryContext {
+    /** End-user identity. */
+    userId: string;
+    /** Agent / persona writing the memory. */
+    agentId?: string;
+    /** Logical conversation / run boundary. */
+    sessionId?: string;
+    /** Tenant / workspace partition. */
+    tenantId?: string;
+    /** Free-form tags for filtering / categorization. */
+    tags?: string[];
+    /** Provider-passthrough metadata. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A single memory fact returned by `recall` or `get`.
+ *
+ * @public
+ */
+interface MemoryFact {
+    id: MemoryId;
+    content: string;
+    /** Semantic relevance score (provider-defined scale) when result of `recall`. */
+    score?: number;
+    /** ISO 8601 timestamp of creation. */
+    createdAt?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Versioned snapshot of a memory's history. Only emitted by providers
+ * with `capabilities.history === true` (Mem0 today).
+ *
+ * @public
+ */
+interface MemoryRevision {
+    id: MemoryId;
+    content: string;
+    version: number;
+    changedAt: string;
+}
+/**
+ * Statically declared adapter feature flags. Consumers feature-detect
+ * at compile time via `if (adapter.capabilities.history)`.
+ *
+ * @public
+ */
+interface MemoryAdapterCapabilities {
+    /** Returns prior versions of a memory via `history(id)`. */
+    history: boolean;
+    /** First-class `sessionId` scoping. */
+    sessions: boolean;
+    /** First-class `tenantId` scoping. */
+    tenancy: boolean;
+    /** Provider performs reasoning over memory (e.g., Honcho dialectic). */
+    reasoning: boolean;
+    /** Exposes LLM-callable function-calling schemas. */
+    toolSchemas: boolean;
+    /** Supports background prefetch (currently informational). */
+    prefetch: boolean;
+}
+/**
+ * One assistant-turn message in the canonical `{role, content}` shape
+ * an adapter may receive instead of a flat string when writing a turn.
+ *
+ * @public
+ */
+interface MemoryTurnMessage {
+    role: "user" | "assistant" | "system";
+    content: string;
+}
+/**
+ * OpenAI-format function-calling schema exposed to the LLM.
+ *
+ * @public
+ */
+interface MemoryToolSchema {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+/**
+ * Portable third-party memory adapter contract. Implementations live
+ * in `@theokit-memory-*` packages; the SDK never imports them.
+ *
+ * @public
+ */
+interface MemoryAdapter {
+    /** Short identifier — matches the `${adapterId}` prefix in `MemoryId`. */
+    readonly id: string;
+    readonly capabilities: MemoryAdapterCapabilities;
+    /** Synchronous availability probe — no network, no I/O. */
+    isAvailable(): boolean;
+    /** One-shot initialization. Idempotent: safe to call multiple times. */
+    initialize?(): Promise<void>;
+    /**
+     * Persist a fact or full turn to memory. Returns the stored
+     * `MemoryId`. Throws `MemoryAdapterError(code: "invalid_input")` on
+     * empty content or invalid identifiers in `ctx`.
+     */
+    write(content: string | MemoryTurnMessage[], ctx: MemoryContext): Promise<MemoryId>;
+    /**
+     * Semantic recall — top-`k` facts ordered by relevance. Returns
+     * empty array when `k === 0` or no matches.
+     */
+    recall(query: string, ctx: MemoryContext, k?: number): Promise<MemoryFact[]>;
+    /**
+     * Delete a memory by id. Throws `MemoryAdapterError(code:
+     * "invalid_input")` when the id was minted by a different adapter
+     * (EC-B). Throws `code: "not_found"` when the id does not exist.
+     */
+    delete(id: MemoryId): Promise<void>;
+    list?(ctx: MemoryContext, opts?: {
+        cursor?: string;
+        limit?: number;
+    }): AsyncIterable<MemoryFact>;
+    get?(id: MemoryId): Promise<MemoryFact | null>;
+    history?(id: MemoryId): Promise<MemoryRevision[]>;
+    /** Empty array when `capabilities.toolSchemas === false`. */
+    getToolSchemas?(): MemoryToolSchema[];
+    handleToolCall?(name: string, args: Record<string, unknown>, ctx: MemoryContext): Promise<string>;
+    /** Graceful shutdown — flush queues, close connections. */
+    shutdown?(): Promise<void>;
+}
+/**
+ * Direct memory API exposed on `SDKAgent.memory`. Resolves to whichever
+ * memory adapter(s) are registered via `Agent.create({ plugins: [...] })`.
+ *
+ * @public
+ */
+interface AgentMemory {
+    /**
+     * Persist a fact. Returns the first adapter's id; in multi-adapter
+     * setups all adapters receive the write (fan-out).
+     */
+    write(content: string | MemoryTurnMessage[], ctx?: Partial<MemoryContext>): Promise<MemoryId>;
+    /** Semantic recall — merged + deduped across registered adapters. */
+    recall(query: string, ctx?: Partial<MemoryContext>, k?: number): Promise<MemoryFact[]>;
+    /** Delete a memory by id — routes to the owning adapter via prefix. */
+    delete(id: MemoryId): Promise<void>;
+    /** Returns the first registered adapter or `null` when none exists. */
+    adapter(): MemoryAdapter | null;
+}
+
+/**
+ * Context manager backend.
+ *
+ * - `"file"` — Read `.theokit/context.json` from the workspace (local) or the
+ *   cloned repo (cloud).
+ *
+ * @public
+ */
+type ContextManagerKind = "file";
+/**
+ * Context configuration accepted by `Agent.create()` via {@link AgentOptions.context}.
+ *
+ * @public
+ */
+interface ContextSettings {
+    /** Which backend reads context. Defaults to `"file"`. */
+    manager?: ContextManagerKind;
+    /** Hard cap on tokens emitted into the agent's system prompt. */
+    maxTokens?: number;
+    /**
+     * Per-file truncation cap in characters. Default 40_000 (~10k tokens).
+     * Larger files are truncated with 70%/20% head/tail + marker (ADR D155).
+     *
+     * @public
+     */
+    maxBytesPerFile?: number;
+    /**
+     * Aggregate cap across all context files in characters. Default 120_000.
+     * When total exceeds this, lower-priority sources are dropped (ADR D155).
+     *
+     * Note: context snapshot is **refresh-time** (EC-T); modifying context
+     * files mid-flight does not auto-update. Call `agent.reload()` to pick
+     * up changes.
+     *
+     * @public
+     */
+    maxBytesTotal?: number;
+}
+/**
+ * Inclusion state of a single context source in a {@link ContextSnapshot}.
+ *
+ * @public
+ */
+type ContextSourceStatus = "included" | "excluded" | "summarized";
+/**
+ * A single context source resolved by the context manager.
+ *
+ * @public
+ */
+interface ContextSource {
+    /** Stable identifier — usually the filename without extension. */
+    name: string;
+    /** Path relative to the workspace root, when applicable. */
+    path?: string;
+    /** Whether the source was included, dropped, or summarized to fit the budget. */
+    status: ContextSourceStatus;
+    /** Free-text reason when `status !== "included"`. */
+    reason?: string;
+}
+/**
+ * Token budget used by the context manager for a single agent.
+ *
+ * @public
+ */
+interface ContextBudget {
+    maxTokens?: number;
+    /**
+     * Either a token count or a list of token strings extracted from source
+     * content. Normalized to `<tokens>` in golden comparisons.
+     */
+    usedTokens?: number | string[];
+}
+/**
+ * Result of `agent.context.snapshot()`. Public and secret-free by design — safe
+ * to log and persist. Raw secrets, local absolute paths, and exact token values
+ * are never present.
+ *
+ * @public
+ */
+interface ContextSnapshot {
+    runtime: "local" | "cloud";
+    sources: ContextSource[];
+    budget?: ContextBudget;
+}
+/**
+ * Public context manager handle exposed as `agent.context`.
+ *
+ * @public
+ */
+interface SDKContextManager {
+    /** Inspect what the context manager actually loaded for the agent. */
+    snapshot(): Promise<ContextSnapshot>;
+}
+
+/**
+ * MCP server configuration accepted by `Agent.create()` and `agent.send()`.
+ *
+ * @public
+ */
+type McpStdioServerConfig = {
+    type?: "stdio";
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    /** Local agents only. Cloud rejects this field. */
+    cwd?: string;
+};
+/**
+ * OAuth-style auth bundle for HTTP/SSE MCP servers.
+ *
+ * @public
+ */
+interface McpAuthConfig {
+    CLIENT_ID: string;
+    CLIENT_SECRET?: string;
+    scopes?: string[];
+    /**
+     * OAuth 2.1 PKCE flow configuration (ADR D41, v1.2+). When present, the
+     * SDK runs the PKCE flow on first use and stores tokens via keychain or
+     * file. Without this, the SDK relies on `CLIENT_SECRET` + manual headers.
+     */
+    oauth?: McpOAuthConfig;
+}
+/**
+ * OAuth 2.1 PKCE flow descriptor. See ADR D41.
+ *
+ * @public
+ */
+interface McpOAuthConfig {
+    /** Authorization endpoint (e.g. https://api.notion.com/v1/oauth/authorize). */
+    authorizationEndpoint: string;
+    /** Token endpoint (e.g. https://api.notion.com/v1/oauth/token). */
+    tokenEndpoint: string;
+    /** Where the OAuth `code` is received. */
+    redirectMode: "manual" | "localhost";
+    /** Localhost callback port (0 = random free port, default). */
+    localhostPort?: number;
+    /** Flow timeout in ms (default 300_000 = 5min). */
+    timeoutMs?: number;
+}
+/**
+ * HTTP or SSE MCP server.
+ *
+ * @public
+ */
+type McpHttpServerConfig = {
+    type?: "http" | "sse";
+    url: string;
+    /** Passed through. `Authorization` works here. */
+    headers?: Record<string, string>;
+    auth?: McpAuthConfig;
+};
+/**
+ * Union of MCP server configs. See `docs.md` for the full reference.
+ *
+ * @public
+ */
+type McpServerConfig = McpStdioServerConfig | McpHttpServerConfig;
+
+/**
+ * Capability slot a provider can fulfill.
+ *
+ * @public
+ */
+type ProviderCapability = "chat" | "web_search" | "image" | "embedding";
+/**
+ * A single user-declared routing rule. Maps a capability to a provider, and
+ * optionally pins a specific model.
+ *
+ * @public
+ */
+interface ProviderRoute {
+    capability: ProviderCapability;
+    provider: string;
+    model?: string;
+}
+/**
+ * Provider routing configuration accepted by `Agent.create()` via
+ * {@link AgentOptions.providers}.
+ *
+ * @public
+ */
+interface ProviderRoutingSettings {
+    /** Explicit `{ capability → provider }` map. First match wins per capability. */
+    routes: ProviderRoute[];
+    /** Provider names to try in order when a route has no provider available. */
+    fallback?: string[];
+    /**
+     * Multiple API keys per provider for same-provider key rotation
+     * (credential pool — ADRs D123-D133). When a key hits HTTP 429, 402,
+     * or 401, the SDK rotates to the next entry transparently before
+     * falling back to a different provider.
+     *
+     * Example:
+     * ```ts
+     * apiKeys: { openrouter: ["sk-or-...", "sk-or-..."], anthropic: ["..."] }
+     * ```
+     *
+     * Empty arrays and empty strings are filtered out. If a provider has
+     * exactly 1 effective key, the pool is transparent (no rotation behavior).
+     *
+     * Conflicts with the single-key shape `AgentOptions.apiKey: "..."` —
+     * use one OR the other, not both.
+     *
+     * @public
+     */
+    apiKeys?: Record<string, string[]>;
+    /**
+     * Rotation strategy per provider for the credential pool. Default is
+     * `"fill_first"` (use entries[0] until exhausted). Only consulted when
+     * `apiKeys[provider]` has ≥2 entries.
+     *
+     * @public
+     */
+    credentialPoolStrategy?: Record<string, "fill_first" | "round_robin" | "least_used" | "random">;
+}
+/**
+ * Plugins configuration accepted by `Agent.create()` via
+ * {@link AgentOptions.plugins}.
+ *
+ * @public
+ */
+interface PluginsSettings {
+    /** Plugin names to enable. Plugin discovery is plugin-provider specific. */
+    enabled?: string[];
+}
+/**
+ * Resolved routing decision returned by `agent.providers.routes()`. Public and
+ * secret-free by design — safe to log.
+ *
+ * @public
+ */
+interface ResolvedProviderRoute {
+    capability: string;
+    provider: string;
+    model?: string;
+    /** Why the runtime picked this provider (e.g. `"explicit-model-provider"`). */
+    reason: string;
+}
+/**
+ * Public providers manager handle exposed as `agent.providers`.
+ *
+ * @public
+ */
+interface SDKProvidersManager {
+    /** Inspect which provider serves each capability for this agent. */
+    routes(): Promise<ResolvedProviderRoute[]>;
+}
+/**
+ * Provider catalog entry returned by `Theokit.providers.list()`.
+ *
+ * @public
+ */
+interface SDKProvider {
+    name: string;
+    displayName: string;
+    capabilities: string[];
+    isAvailable: boolean;
+    /** JSON Schema describing the env vars / fields needed to enable this provider. */
+    setupSchema: object;
+}
+
+/**
+ * One slot in a {@link ModelSelection.params} array.
+ *
+ * @public
+ */
+interface ModelParameterValue {
+    id: string;
+    value: string;
+}
+/**
+ * Identifies a model plus optional per-model parameters (e.g. reasoning effort).
+ *
+ * Use `Theokit.models.list()` to discover valid ids and parameter definitions.
+ *
+ * @public
+ */
+interface ModelSelection {
+    id: string;
+    params?: ModelParameterValue[];
+}
+/**
+ * Which on-disk settings layers a local agent loads.
+ *
+ * @public
+ */
+type SettingSource = "project" | "user" | "team" | "mdm" | "plugins" | "all";
+/**
+ * Local agent configuration.
+ *
+ * @public
+ */
+interface LocalOptions {
+    cwd?: string | string[];
+    settingSources?: SettingSource[];
+    sandboxOptions?: {
+        enabled: boolean;
+    };
+}
+/**
+ * Repo to clone into a cloud agent's VM.
+ *
+ * @public
+ */
+interface CloudRepo {
+    url: string;
+    startingRef?: string;
+    prUrl?: string;
+}
+/**
+ * Cloud execution environment.
+ *
+ * @public
+ */
+interface CloudEnv {
+    type: "cloud" | "pool" | "machine";
+    name?: string;
+}
+/**
+ * Cloud agent configuration.
+ *
+ * @public
+ */
+interface CloudOptions {
+    env?: CloudEnv;
+    repos?: CloudRepo[];
+    workOnCurrentBranch?: boolean;
+    autoCreatePR?: boolean;
+    skipReviewerRequest?: boolean;
+    /**
+     * Short-lived credentials scoped to the agent. Encrypted at rest, deleted
+     * with the agent. Names must not start with `THEOKIT_`.
+     */
+    envVars?: Record<string, string>;
+}
+/**
+ * Subagent definition. The parent agent spawns these via its Agent tool.
+ *
+ * @public
+ */
+interface AgentDefinition {
+    description: string;
+    prompt: string;
+    model?: ModelSelection | "inherit";
+    mcpServers?: Array<string | Record<string, McpServerConfig>>;
+}
+/**
+ * Public skill metadata exposed to the system-prompt resolver. Mirrors the
+ * shape returned by `agent.skills.list()` — name + description only, never
+ * full skill bodies.
+ *
+ * @public
+ */
+interface SystemPromptSkillRef {
+    name: string;
+    description: string;
+}
+/**
+ * Public skill listing handle exposed as `agent.skills`. Populated when
+ * `settingSources` includes `"project"` so the SDK discovers
+ * `.theokit/skills/<name>/SKILL.md` files OR when `skills.enabled` is set
+ * explicitly on the agent options.
+ *
+ * @public
+ */
+interface SDKAgentSkills {
+    list(): Promise<ReadonlyArray<SystemPromptSkillRef>>;
+}
+/**
+ * Public plugin metadata returned by `agent.plugins.list()`. Mirrors the
+ * `.theokit/plugins/<name>/MANIFEST.json` allow-listed shape; never exposes
+ * raw plugin bodies, credentials, or internal hooks.
+ *
+ * @public
+ */
+interface SDKPluginMetadata {
+    name: string;
+    description?: string;
+}
+/**
+ * Public plugin listing handle exposed as `agent.plugins`. Populated when
+ * `settingSources` includes `"plugins"` OR when `plugins.enabled` is set
+ * on the agent options.
+ *
+ * @public
+ */
+interface SDKAgentPlugins {
+    list(): Promise<ReadonlyArray<SDKPluginMetadata>>;
+}
+/**
+ * Public view of a recalled memory fact exposed to the system-prompt resolver.
+ *
+ * @public
+ */
+interface SystemPromptMemoryFact {
+    text: string;
+}
+/**
+ * Context passed to a {@link SystemPromptResolver}. Field order is a
+ * compatibility contract: new fields are appended, never reordered.
+ *
+ * @public
+ */
+interface SystemPromptContext {
+    agentId: string;
+    cwd: string | undefined;
+    model: ModelSelection | undefined;
+    skills: ReadonlyArray<SystemPromptSkillRef>;
+    userMessage: string;
+    /** Recalled durable facts when memory is enabled. Appended in v1.1. */
+    memory: ReadonlyArray<SystemPromptMemoryFact>;
+}
+/**
+ * Resolver function that produces the system prompt dynamically. Receives
+ * the {@link SystemPromptContext} and returns a string (or a Promise of one).
+ *
+ * The SDK does NOT impose a timeout on the resolver — wrap your own
+ * `Promise.race` if you call into slow resources. Errors propagate to the
+ * caller of `agent.send()`.
+ *
+ * @public
+ */
+type SystemPromptResolver = (ctx: SystemPromptContext) => string | Promise<string>;
+/**
+ * Skills configuration accepted by `Agent.create()` via
+ * {@link AgentOptions.skills}.
+ *
+ * Skills are discovered from `.theokit/skills/<name>/SKILL.md` when
+ * `local.settingSources` includes `"project"`.
+ *
+ * @public
+ */
+interface SkillsSettings {
+    /**
+     * Names of skills the parent agent may invoke. When omitted, every
+     * discovered skill is enabled.
+     */
+    enabled?: string[];
+    /**
+     * Whether the SDK auto-injects the loaded skill list (name + description) as a
+     * `<skills>` block in the LLM system prompt. Default `true`.
+     *
+     * Set to `false` when supplying a custom `systemPrompt` resolver that formats
+     * skills itself.
+     */
+    autoInject?: boolean;
+}
+/**
+ * Memory configuration accepted by `Agent.create()` via {@link AgentOptions.memory}.
+ *
+ * Persists durable facts under `.theokit/memory/<namespace>/<scope>-<userId>.json`.
+ *
+ * @public
+ */
+interface MemorySettings {
+    enabled: boolean;
+    namespace?: string;
+    userId?: string;
+    scope?: "agent" | "user" | "team";
+    storePath?: string;
+    /**
+     * Whether the SDK auto-injects recalled facts as a `<memory>` block in the
+     * LLM system prompt. Default `true`.
+     */
+    autoInject?: boolean;
+    /**
+     * Index + tools configuration (memory-system-openclaw-parity).
+     *
+     * When `tools !== false`, the SDK registers `memory_search` and
+     * `memory_get` with the LLM. Backed by SQLite + FTS5 (and sqlite-vec
+     * when an embedding provider is configured).
+     */
+    index?: {
+        /** Whether to register `memory_search` + `memory_get` tools. Default `true`. */
+        tools?: boolean;
+        /**
+         * Vector index backend (ADR D43). Default `"sqlite-vec"`. Set to
+         * `"lance"` to use `@lancedb/lancedb` (optional peer dep) for scale.
+         */
+        backend?: "sqlite-vec" | "lance";
+        /** Embedding provider config. When omitted, the index runs in FTS-only mode. */
+        embedding?: {
+            provider: "openai" | "mistral" | "openrouter" | "voyage" | "deepinfra";
+            model?: string;
+        };
+    };
+    /**
+     * Active Memory blocking recall (Phase 7). When `enabled: true`, runs
+     * before each `send()` and prepends an `<active-memory>` block.
+     */
+    activeRecall?: {
+        enabled?: boolean;
+        queryMode?: "message" | "recent" | "full";
+        timeoutMs?: number;
+        maxSummaryChars?: number;
+        persistTranscripts?: boolean;
+    };
+}
+/**
+ * Inline custom tool — registered with the LLM under the given name + schema
+ * and dispatched locally to {@link CustomTool.handler} when the model emits a
+ * `tool_use` for it.
+ *
+ * Local runtime only (SDK v1.0). Cloud agents reject `tools` (handlers cannot
+ * cross the wire — use MCP servers or subagents for cloud tool surfaces).
+ *
+ * Handlers MUST be re-passed on `Agent.resume()` because closures cannot be
+ * persisted. The tool catalog (name + description + schema) is NOT serialized.
+ *
+ * @public
+ */
+interface CustomTool {
+    /**
+     * Tool name surfaced to the LLM. Must match `^[a-zA-Z][a-zA-Z0-9_-]{0,63}$`
+     * and must not collide with `shell`, `memory_search`, `memory_get`, or any
+     * `mcp_*` prefix (reserved for the SDK's built-in tools).
+     */
+    name: string;
+    /** Description surfaced to the LLM. Required — drives tool-selection accuracy. */
+    description: string;
+    /** JSON Schema (Draft-7 subset) describing the `input` argument. Must be `type: "object"`. */
+    inputSchema: Record<string, unknown>;
+    /**
+     * Local handler invoked when the model emits `tool_use` for this tool.
+     * Returns a string (becomes the `tool_result.content` surfaced back to the
+     * model). Throws → SDK converts to `tool_result` with `isError: true` and
+     * the error `message` as content.
+     */
+    handler: (input: Record<string, unknown>) => string | Promise<string>;
+}
+/**
+ * Telemetry configuration for an agent. When `enabled: true`, the SDK emits
+ * OpenTelemetry spans for `agent.send`, `llm.call`, `tool.call`, and
+ * `memory.search`. See ADR D34.
+ *
+ * Privacy: content (prompts, responses, tool args) is OMITTED by default —
+ * only timing/counts/IDs are recorded. Opt in via `includeContent: true`
+ * to add prompt/response/args events to the spans (consumer's
+ * responsibility to sanitize PII).
+ *
+ * `@opentelemetry/api` is an OPTIONAL peer dependency. Without it
+ * installed, telemetry is a no-op even when `enabled: true`.
+ *
+ * @public
+ */
+interface TelemetrySettings {
+    /** Master switch. Default `false`. */
+    enabled: boolean;
+    /** Whether to include prompts/responses/tool args as span events. Default `false`. */
+    includeContent?: boolean;
+    /** Exporter selection. Default `"console"`. Custom exporters are passed-through. */
+    exporter?: "console" | "otlp" | unknown;
+    /** Service name on emitted spans. Default `"theokit-sdk"`. */
+    serviceName?: string;
+    /**
+     * Auto-detect and register OTel exporters for installed observability
+     * libs (Langfuse, Sentry, PostHog) via `createRequire` feature-detect.
+     * Default `true`. See ADR D42.
+     */
+    autoDetect?: boolean;
+    /**
+     * Per-adapter opt-out. Lowercase names: `"langfuse" | "sentry" | "posthog"`.
+     * Default `[]`.
+     */
+    disable?: string[];
+}
+/**
+ * Top-level options accepted by `Agent.create()`.
+ *
+ * Pass either `local` or `cloud` to pick a runtime.
+ *
+ * @public
+ */
+interface AgentOptions {
+    model?: ModelSelection;
+    /** Falls back to `THEOKIT_API_KEY`. */
+    apiKey?: string;
+    name?: string;
+    /**
+     * When `true`, `Agent.prompt` (and any helper that goes through `run.wait()`)
+     * rejects with `AgentRunError` instead of resolving with `{ status: 'error' }`.
+     * Cancelled runs (`status: 'cancelled'`) still resolve — cancel ≠ error.
+     * If `result.error` is undefined despite `status: 'error'` (malformed RunResult),
+     * the defensive guard resolves normally (no throw).
+     *
+     * Default `false` (backwards-compatible).
+     *
+     * @public
+     */
+    throwOnError?: boolean;
+    /**
+     * System prompt for the agent. Either a plain string or a resolver
+     * function that receives the {@link SystemPromptContext} and returns the
+     * prompt dynamically. Override per-call via {@link SendOptions.systemPrompt}.
+     *
+     * Subagents do NOT inherit this — they use {@link AgentDefinition.prompt}.
+     */
+    systemPrompt?: string | SystemPromptResolver;
+    local?: LocalOptions;
+    cloud?: CloudOptions;
+    mcpServers?: Record<string, McpServerConfig>;
+    agents?: Record<string, AgentDefinition>;
+    agentId?: string;
+    /** Context manager configuration. See `agent.context`. */
+    context?: ContextSettings;
+    /** Provider routing configuration. See `agent.providers`. */
+    providers?: ProviderRoutingSettings;
+    /** Plugins to enable. Plugin sources must also be active via `local.settingSources`. */
+    plugins?: PluginsSettings;
+    /** Skills configuration. See `agent.skills`. */
+    skills?: SkillsSettings;
+    /** Memory configuration. Persists durable facts; auto-recalled on send. */
+    memory?: MemorySettings;
+    /**
+     * Inline custom tools. Local runtime only — cloud agents reject any non-empty
+     * `tools` array. Handlers are not persisted; pass them again on resume.
+     * See {@link CustomTool}.
+     */
+    tools?: CustomTool[];
+    /**
+     * Telemetry (OpenTelemetry) configuration. Default disabled. See
+     * {@link TelemetrySettings} and ADR D34.
+     */
+    telemetry?: TelemetrySettings;
+    /**
+     * Arbitrary metadata bag for caller-supplied provenance. Currently used by
+     * the fork primitive (ADR D114) to tag `metadata.forkOrigin` and
+     * `metadata.parentAgentId` so memory writes downstream can be attributed.
+     *
+     * Not persisted to the agent registry — informational only at runtime.
+     *
+     * @public
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Default `MemoryContext` for third-party memory adapter plugins
+     * (ADR D141). When set, `pre_user_send` / `post_assistant_reply`
+     * hooks receive this context unless the caller overrides it. The
+     * `agent.memory` direct API also defaults to it.
+     *
+     * @public
+     */
+    memoryContext?: MemoryContext;
+    /**
+     * Maximum byte length of the `<memory-context>` block injected by
+     * `pre_user_send` adapter hooks (EC-A). Larger recalls are sliced
+     * with `…[truncated]`. Default 16_000 (~4k tokens). Set lower for
+     * cheaper turns; higher for longer-context models.
+     *
+     * @public
+     */
+    maxRecallContextBytes?: number;
+    /**
+     * Declarative handoff destinations (Adoption Roadmap #4; ADRs D214-D229).
+     * Each entry is either a raw `SDKAgent` (auto-wrapped with defaults) OR a
+     * `HandoffDescriptor` from `Handoff.create(target, opts?)`.
+     *
+     * Runtime injects synthetic `transfer_to_<receiver.name>` tools per
+     * destination (D214/D215). When the LLM invokes one, the receiver takes
+     * over the next turn (peer-to-peer, D217).
+     *
+     * @public
+     */
+    handoffs?: ReadonlyArray<SDKAgent | HandoffDescriptor>;
+    /**
+     * Maximum chain depth across handoffs per `agent.send()` call (D218).
+     * Default 5. Exceeding throws `HandoffLoopError`. Set to 0 to disable
+     * the handoff tools entirely (EC-8 / handoffs never fire).
+     *
+     * @public
+     */
+    maxHandoffDepth?: number;
+    /**
+     * Production-Readiness #6 — quota / abuse gates (ADRs D322-D323).
+     *
+     * `onBeforeCreate` fires BEFORE the agent is registered or persisted —
+     * throw to block creation. `onBeforeSend` fires BEFORE each `agent.send`
+     * (after `pre_user_send` adapter hooks, before any LLM call or storage
+     * write) — throw to block the send.
+     *
+     * Unlike `onTool*` (observation), these hooks are BLOCKERS — errors
+     * propagate as rejection on `Agent.create` / `agent.send`. Use them for
+     * per-user conversation caps, per-conversation message caps, abuse
+     * detection.
+     *
+     * @public
+     */
+    onBeforeCreate?: (event: {
+        conversationId: string;
+        userId?: string;
+    }) => Promise<void> | void;
+    /**
+     * Fires before each `agent.send`. `previousMessageCount` is the count of
+     * messages already persisted BEFORE the current send adds the user
+     * message. Throw to block.
+     *
+     * @public
+     */
+    onBeforeSend?: (event: {
+        conversationId: string;
+        previousMessageCount: number;
+    }) => Promise<void> | void;
+    /**
+     * Production-Readiness #4 — tool lifecycle hooks (ADRs D315-D317).
+     *
+     * `onToolStart` fires BEFORE the handler runs. `onToolEnd` fires after a
+     * successful handler return. `onToolError` fires when validation fails OR
+     * the handler throws — `event.error` is always an `Error` instance.
+     *
+     * Hook errors are SWALLOWED with a stderr warn (do not abort the run).
+     * The `callId` is unique per tool invocation and identical across the
+     * start/end (or start/error) pair, so consumers can correlate.
+     *
+     * Use cases: cost tracking, audit logs, per-tool retry/alerting,
+     * latency telemetry.
+     *
+     * @public
+     */
+    onToolStart?: (event: {
+        toolName: string;
+        args: unknown;
+        conversationId: string;
+        callId: string;
+    }) => void | Promise<void>;
+    /** Fires when a tool handler returns successfully. */
+    onToolEnd?: (event: {
+        toolName: string;
+        args: unknown;
+        result: unknown;
+        conversationId: string;
+        callId: string;
+        durationMs: number;
+    }) => void | Promise<void>;
+    /**
+     * Fires when a tool handler throws OR schema validation rejects the args.
+     * `event.error` is always an `Error` instance (D315/EC-6 — validation
+     * reasons are wrapped in `new Error(reason)`).
+     *
+     * `attempt` is always `1` in v1 (D317 — reserved for future retry policy).
+     */
+    onToolError?: (event: {
+        toolName: string;
+        args: unknown;
+        error: Error;
+        conversationId: string;
+        callId: string;
+        durationMs: number;
+        attempt: number;
+    }) => void | Promise<void>;
+    /**
+     * Pluggable conversation persistence (Production-Readiness #1; ADRs D303-D306).
+     *
+     * Default: undefined → `FileSystemConversationStorage` writing to
+     * `<cwd>/.theokit/agents/<id>/messages.jsonl` (byte-identical to pre-D303
+     * behavior). Pass `InMemoryConversationStorage` for tests, or a custom
+     * adapter (Postgres/Redis/Durable Objects) for serverless and multi-host
+     * deploys.
+     *
+     * NOTE: not persisted in the registry snapshot — closures don't serialize.
+     * On `Agent.resume`, pass the adapter again. If the agent was originally
+     * created with a custom `conversationStorage`, resume without it throws
+     * `ConfigurationError(code: "conversation_storage_required")` (D325) to
+     * avoid silent FS fallback that would lose history.
+     *
+     * @public
+     */
+    conversationStorage?: ConversationStorageAdapter;
+}
+/**
+ * Artifact produced inside an agent's workspace. Cloud-only.
+ *
+ * @public
+ */
+interface SDKArtifact {
+    path: string;
+    sizeBytes: number;
+    updatedAt: string;
+}
+/**
+ * Handle returned by `Agent.create()` and `Agent.resume()`.
+ *
+ * @public
+ */
+interface SDKAgent {
+    readonly agentId: string;
+    readonly model: ModelSelection | undefined;
+    /**
+     * Context manager for this agent. Populated when context is enabled via
+     * {@link AgentOptions.context}. See {@link SDKContextManager}.
+     */
+    readonly context?: SDKContextManager;
+    /**
+     * Provider routing inspector for this agent. Populated when at least one
+     * provider route is configured (via {@link AgentOptions.providers}, plugins,
+     * or model-implied providers). See {@link SDKProvidersManager}.
+     */
+    readonly providers?: SDKProvidersManager;
+    /**
+     * Skill listing for this agent. Populated when project-scoped skills are
+     * enabled (`settingSources: ["project"]`) or when `skills.enabled` is set.
+     * See {@link SDKAgentSkills}.
+     */
+    readonly skills?: SDKAgentSkills;
+    /**
+     * Plugin listing for this agent. Populated when project-scoped plugins are
+     * enabled (`settingSources: ["plugins"]`) or when `plugins.enabled` is set.
+     * See {@link SDKAgentPlugins}.
+     */
+    readonly plugins?: SDKAgentPlugins;
+    send(message: string | SDKUserMessage, options?: SendOptions): Promise<Run>;
+    /** Fire-and-forget disposal. */
+    close(): void;
+    /** Re-read filesystem config (context, hooks, project MCP, subagents) without disposing. */
+    reload(): Promise<void>;
+    /**
+     * Async disposal. Idempotent — calling more than once is a no-op (per ADR D5).
+     * Prefer `await using agent = await Agent.create(...)` over explicit
+     * `dispose()` for resource safety.
+     */
+    dispose(): Promise<void>;
+    /**
+     * `await using` support per ADR D5. Identical semantics to `dispose()` —
+     * idempotent across both surfaces.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /** Cloud-only. Local returns an empty array. */
+    listArtifacts(): Promise<SDKArtifact[]>;
+    /** Cloud-only. Local throws `UnsupportedRunOperationError`. */
+    downloadArtifact(path: string): Promise<Buffer>;
+    /**
+     * Signal that prompt cache should be invalidated. By default deferred —
+     * applied at the start of the next `send()`. Pass `{ applyNow: true }` to
+     * force immediate disposal (caller must `Agent.create()` again to use).
+     *
+     * Cache invalidation is a cost regression (provider charges full price
+     * for the rebuilt cache; see ADRs D94-D95). Use sparingly and deliberately.
+     *
+     * Cloud agents: no-op (cloud runtime reconstructs state per request).
+     *
+     * @public
+     */
+    invalidateCache?(reason: string, options?: InvalidateCacheOptions): Promise<void>;
+    /**
+     * Goal-driven Ralph loop (ADRs D115-D121). Iterates `agent.send` →
+     * judge → continuation until the auxiliary judge model returns `done`,
+     * the judge fails too many times in a row, max turns are exhausted,
+     * or the caller aborts via `AbortSignal`.
+     *
+     * Yields {@link import("./goal-events.js").GoalEvent} per state
+     * transition; returns a {@link import("./goal-events.js").GoalResult}
+     * summary as the generator's final value.
+     *
+     * Cloud agents throw {@link import("../errors.js").UnsupportedRunOperationError}
+     * **synchronously** (no AsyncGenerator returned) — wrap in try/catch
+     * if you support both runtimes.
+     *
+     * Caveat: do not call `agent.dispose()` mid-iteration; the next `send`
+     * propagates the disposal error through the generator to the consumer.
+     *
+     * @public
+     */
+    runUntil?(goal: string, options?: GoalOptions): RunUntilIterator;
+    /**
+     * Fork a short-lived sub-agent with parent's credentials + system
+     * prompt byte-identical (ADR D112 — cache hit) and a restricted tool
+     * whitelist (ADR D111 — AsyncLocalStorage isolation).
+     *
+     * Cloud agents throw {@link import("../errors.js").UnsupportedRunOperationError}.
+     *
+     * @public
+     */
+    fork?(options: undefined): Promise<undefined>;
+    /**
+     * Direct API to third-party memory adapter(s) registered via
+     * `plugins: [...]` (ADR D141 / D142). Returns `null` when no adapter
+     * is registered. In multi-adapter setups `write` fans out to all;
+     * `recall` merges + dedupes; `delete` routes by `MemoryId` prefix.
+     *
+     * @public
+     */
+    memory?: AgentMemory;
+    /**
+     * Activate a personality preset for the next `send` (Hermes #26).
+     * Reserved names `"none"`, `"default"`, and `"neutral"` clear the
+     * active preset. Returns the resolved preset (or `null` when cleared).
+     *
+     * Persistence: pass `{ save: true }` to persist across process
+     * restarts (stored under `$THEOKIT_HOME/personality.json`).
+     *
+     * History: by default the conversation history is preserved across
+     * the switch. Pass `{ reset: true }` to also clear the session.
+     *
+     * Cloud agents throw {@link import("../errors.js").UnsupportedRunOperationError}.
+     *
+     * @public
+     */
+    usePersonality?(name: string, opts?: {
+        save?: boolean;
+        reset?: boolean;
+    }): Promise<PersonalityPreset | null>;
+}
+/**
+ * Resolved personality preset surfaced via {@link SDKAgent.usePersonality}
+ * (Hermes #26, ADRs D160-D169). Re-declared here so the public DTS bundle
+ * never crosses the `internal/` path boundary. The implementation type in
+ * `internal/personality/types.ts` is structurally identical.
+ *
+ * @public
+ */
+interface PersonalityPreset {
+    readonly name: string;
+    readonly description: string | undefined;
+    readonly tools: ReadonlyArray<string> | undefined;
+    readonly model: string | undefined;
+    readonly tags: ReadonlyArray<string> | undefined;
+    readonly systemPrompt: string;
+    readonly source: "project" | "user";
+    readonly sourcePath: string;
+}
+/**
+ * Options for {@link SDKAgent.invalidateCache}.
+ *
+ * @public
+ */
+interface InvalidateCacheOptions {
+    /**
+     * When `true`, dispose the agent immediately so caller must recreate it
+     * to continue. Default `false` (deferred — applied on next `send()`).
+     */
+    applyNow?: boolean;
+}
+/**
+ * Metadata returned by `Agent.list()` and `Agent.get()`.
+ *
+ * @public
+ */
+type SDKAgentInfo = {
+    agentId: string;
+    name: string;
+    summary: string;
+    lastModified: number;
+    status?: "running" | "finished" | "error";
+    createdAt?: number;
+    archived?: boolean;
+} & ({
+    runtime?: undefined;
+} | {
+    runtime: "local";
+    cwd?: string;
+} | {
+    runtime: "cloud";
+    env?: CloudEnv;
+    repos?: string[];
+});
+/**
+ * Options for `Agent.list()`.
+ *
+ * @public
+ */
+type ListAgentsOptions = {
+    limit?: number;
+    cursor?: string;
+} & ({
+    runtime?: undefined;
+} | {
+    runtime: "local";
+    cwd?: string;
+} | {
+    runtime: "cloud";
+    prUrl?: string;
+    includeArchived?: boolean;
+    apiKey?: string;
+});
+/**
+ * Options for `Agent.get()`.
+ *
+ * @public
+ */
+interface GetAgentOptions {
+    cwd?: string;
+    apiKey?: string;
+}
+/**
+ * Options for `Agent.listRuns()`.
+ *
+ * @public
+ */
+type ListRunsOptions = {
+    limit?: number;
+    cursor?: string;
+} & ({
+    runtime?: "local";
+    cwd?: string;
+} | {
+    runtime: "cloud";
+    apiKey?: string;
+});
+/**
+ * Options for `Agent.getRun()`. Cloud requires the parent `agentId`.
+ *
+ * @public
+ */
+type GetRunOptions = {
+    runtime?: "local";
+    cwd?: string;
+} | {
+    runtime: "cloud";
+    agentId: string;
+    apiKey?: string;
+};
+/**
+ * Options for archive/unarchive/delete.
+ *
+ * @public
+ */
+interface AgentOperationOptions {
+    cwd?: string;
+    apiKey?: string;
+}
+/**
+ * Paginated list shape.
+ *
+ * @public
+ */
+interface ListResult<T> {
+    items: T[];
+    nextCursor?: string;
+}
+
+/**
+ * Single tool call event. The internal `args` and `result` shapes are NOT stable.
+ *
+ * @public
+ */
+interface ToolCall {
+    callId: string;
+    name: string;
+    args?: unknown;
+    result?: unknown;
+}
+/**
+ * Incremental text token from the assistant.
+ *
+ * @public
+ */
+interface TextDeltaUpdate {
+    type: "text-delta";
+    text: string;
+}
+/**
+ * Incremental reasoning token.
+ *
+ * @public
+ */
+interface ThinkingDeltaUpdate {
+    type: "thinking-delta";
+    text: string;
+}
+/**
+ * Emitted when a reasoning block completes.
+ *
+ * @public
+ */
+interface ThinkingCompletedUpdate {
+    type: "thinking-completed";
+    thinkingDurationMs: number;
+}
+/**
+ * Tool call started — args committed.
+ *
+ * @public
+ */
+interface ToolCallStartedUpdate {
+    type: "tool-call-started";
+    callId: string;
+    toolCall: ToolCall;
+    modelCallId: string;
+}
+/**
+ * Tool call arguments streaming in incrementally.
+ *
+ * @public
+ */
+interface PartialToolCallUpdate {
+    type: "partial-tool-call";
+    callId: string;
+    toolCall: ToolCall;
+    modelCallId: string;
+}
+/**
+ * Tool call completed.
+ *
+ * @public
+ */
+interface ToolCallCompletedUpdate {
+    type: "tool-call-completed";
+    callId: string;
+    toolCall: ToolCall;
+    modelCallId: string;
+}
+/**
+ * Token count delta for usage tracking.
+ *
+ * @public
+ */
+interface TokenDeltaUpdate {
+    type: "token-delta";
+    tokens: number;
+}
+/**
+ * Conversation step started.
+ *
+ * @public
+ */
+interface StepStartedUpdate {
+    type: "step-started";
+    stepId: number;
+}
+/**
+ * Conversation step completed.
+ *
+ * @public
+ */
+interface StepCompletedUpdate {
+    type: "step-completed";
+    stepId: number;
+    stepDurationMs: number;
+}
+/**
+ * Turn ended with usage summary.
+ *
+ * @public
+ */
+interface TurnEndedUpdate {
+    type: "turn-ended";
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+    };
+}
+/**
+ * User message appended to the conversation.
+ *
+ * @public
+ */
+interface UserMessageAppendedUpdate {
+    type: "user-message-appended";
+    userMessage: UserMessage;
+}
+/** @public */
+interface SummaryUpdate {
+    type: "summary";
+    summary: string;
+}
+/** @public */
+interface SummaryStartedUpdate {
+    type: "summary-started";
+}
+/** @public */
+interface SummaryCompletedUpdate {
+    type: "summary-completed";
+}
+/** @public */
+interface ShellOutputDeltaUpdate {
+    type: "shell-output-delta";
+    event: Record<string, unknown>;
+}
+/**
+ * Lowest-level raw update from a run. Pass `onDelta` to `agent.send()` to
+ * consume these. Finer-grained than `SDKMessage` events.
+ *
+ * @public
+ */
+type InteractionUpdate = TextDeltaUpdate | ThinkingDeltaUpdate | ThinkingCompletedUpdate | ToolCallStartedUpdate | ToolCallCompletedUpdate | PartialToolCallUpdate | TokenDeltaUpdate | StepStartedUpdate | StepCompletedUpdate | TurnEndedUpdate | UserMessageAppendedUpdate | SummaryUpdate | SummaryStartedUpdate | SummaryCompletedUpdate | ShellOutputDeltaUpdate;
+
+/**
+ * Plain assistant message in a conversation history.
+ *
+ * @public
+ */
+interface AssistantMessage {
+    text: string;
+}
+/**
+ * Reasoning step in a conversation history.
+ *
+ * @public
+ */
+interface ThinkingMessage {
+    text: string;
+    thinkingDurationMs?: number;
+}
+/**
+ * User-authored message in a conversation history.
+ *
+ * @public
+ */
+interface UserMessage {
+    text: string;
+}
+/**
+ * Shell command executed during a run.
+ *
+ * @public
+ */
+interface ShellCommand {
+    command: string;
+    workingDirectory?: string;
+}
+/**
+ * Output of a shell command.
+ *
+ * @public
+ */
+interface ShellOutput {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/**
+ * Single step inside an agent turn.
+ *
+ * @public
+ */
+type ConversationStep = {
+    type: "assistantMessage";
+    message: AssistantMessage;
+} | {
+    type: "toolCall";
+    message: ToolCall;
+} | {
+    type: "thinkingMessage";
+    message: ThinkingMessage;
+};
+/**
+ * Agent turn: user message + assistant/tool/thinking steps.
+ *
+ * @public
+ */
+interface AgentConversationTurn {
+    userMessage?: UserMessage;
+    steps: ConversationStep[];
+}
+/**
+ * Shell turn: a command and its output.
+ *
+ * @public
+ */
+interface ShellConversationTurn {
+    shellCommand?: ShellCommand;
+    shellOutput?: ShellOutput;
+}
+/**
+ * Structured per-turn view of a run.
+ *
+ * @public
+ */
+type ConversationTurn = {
+    type: "agentConversationTurn";
+    turn: AgentConversationTurn;
+} | {
+    type: "shellConversationTurn";
+    turn: ShellConversationTurn;
+};
+
+/**
+ * Plain text content block emitted by the assistant or user.
+ *
+ * @public
+ */
+interface TextBlock {
+    type: "text";
+    text: string;
+}
+/**
+ * Tool invocation block emitted by the assistant.
+ *
+ * @public
+ */
+interface ToolUseBlock {
+    type: "tool_use";
+    id: string;
+    name: string;
+    /** Tool args are not part of the stable schema. Treat as unknown and parse defensively. */
+    input: unknown;
+}
+/**
+ * Init metadata. Emitted once at the start of a run.
+ *
+ * @public
+ */
+interface SDKSystemMessage {
+    type: "system";
+    subtype?: "init";
+    agent_id: string;
+    run_id: string;
+    model?: ModelSelection;
+    tools?: string[];
+}
+/**
+ * Echo of the user prompt for this run.
+ *
+ * @public
+ */
+interface SDKUserMessageEvent {
+    type: "user";
+    agent_id: string;
+    run_id: string;
+    message: {
+        role: "user";
+        content: TextBlock[];
+    };
+}
+/**
+ * Model text output for this run.
+ *
+ * @public
+ */
+interface SDKAssistantMessage {
+    type: "assistant";
+    agent_id: string;
+    run_id: string;
+    message: {
+        role: "assistant";
+        content: Array<TextBlock | ToolUseBlock>;
+    };
+}
+/**
+ * Reasoning content.
+ *
+ * @public
+ */
+interface SDKThinkingMessage {
+    type: "thinking";
+    agent_id: string;
+    run_id: string;
+    text: string;
+    thinking_duration_ms?: number;
+}
+/**
+ * Tool invocation lifecycle event. Emitted at start with `args`, then again on
+ * completion with `result`.
+ *
+ * Tool `args` and `result` are NOT part of the stable schema — treat as unknown.
+ *
+ * @public
+ */
+interface SDKToolUseMessage {
+    type: "tool_call";
+    agent_id: string;
+    run_id: string;
+    call_id: string;
+    name: string;
+    status: "running" | "completed" | "error";
+    args?: unknown;
+    result?: unknown;
+    truncated?: {
+        args?: boolean;
+        result?: boolean;
+    };
+}
+/**
+ * Cloud run lifecycle transitions.
+ *
+ * @public
+ */
+interface SDKStatusMessage {
+    type: "status";
+    agent_id: string;
+    run_id: string;
+    status: "CREATING" | "RUNNING" | "FINISHED" | "ERROR" | "CANCELLED" | "EXPIRED";
+    message?: string;
+}
+/**
+ * Task-level milestones and summaries.
+ *
+ * @public
+ */
+interface SDKTaskMessage {
+    type: "task";
+    agent_id: string;
+    run_id: string;
+    status?: string;
+    text?: string;
+}
+/**
+ * Awaiting user input or approval.
+ *
+ * @public
+ */
+interface SDKRequestMessage {
+    type: "request";
+    agent_id: string;
+    run_id: string;
+    request_id: string;
+}
+/**
+ * Partial object emitted during `Agent.streamObject<T>` streaming (ADR D45).
+ * `partial` is `DeepPartial<z.infer<T>>` at the typed iterator level but
+ * erased to `unknown` here because SDKMessage union is non-generic.
+ *
+ * @public
+ */
+interface SDKObjectDelta {
+    type: "object_delta";
+    agent_id: string;
+    run_id: string;
+    partial: unknown;
+    attempt: number;
+}
+/**
+ * Discriminated union of all stream events. Discriminate on `type`.
+ *
+ * All events include `agent_id` and `run_id`.
+ *
+ * @public
+ */
+type SDKMessage = SDKSystemMessage | SDKUserMessageEvent | SDKAssistantMessage | SDKThinkingMessage | SDKToolUseMessage | SDKStatusMessage | SDKTaskMessage | SDKRequestMessage | SDKObjectDelta;
+
+/**
+ * Public type contract for token usage + cost tracking (ADRs D376-D379).
+ *
+ * Surfaces via `RunResult.usage` + `RunResult.cost` after every Run.
+ * Re-exported through the package barrel; consumers import from
+ * `@theokit/sdk`.
+ *
+ * @public
+ */
+/**
+ * Token usage observed during a Run. 5 closed buckets (D376) cover
+ * 100% of providers in 2026: OpenAI Chat / OpenAI Responses (o-series
+ * with reasoning) / Anthropic Messages (with prompt caching).
+ *
+ * `totalTokens` is derived (`inputTokens + outputTokens`); EC-10
+ * invariant: SDK must never emit `totalTokens !== inputTokens + outputTokens`.
+ *
+ * `requests[]` is the per-request breakdown (mirror openai-agents-python)
+ * — populated only when the run made > 1 LLM call.
+ */
+interface TokenUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadTokens?: number;
+    readonly cacheWriteTokens?: number;
+    readonly reasoningTokens?: number;
+    readonly totalTokens: number;
+    /** Per-request breakdown; absent when the run made a single LLM call. */
+    readonly requests?: ReadonlyArray<Omit<TokenUsage, "requests">>;
+}
+/**
+ * Cost confidence level (D377).
+ * - `actual`: returned by a provider billing API (e.g. OpenRouter `/generation`).
+ * - `estimated`: computed from bundled pricing snapshot.
+ * - `included`: subscription-included route (Codex CLI, Claude Pro).
+ * - `unknown`: pricing data unavailable; `amountUsd` is undefined.
+ */
+type CostStatus = "actual" | "estimated" | "included" | "unknown";
+/** Source of the cost figure for caller-side audit. */
+type CostSource = "openrouter_api" | "litellm_snapshot" | "user_override" | "subscription_included" | "unknown";
+/**
+ * Cost breakdown attached to `RunResult.cost`. When `status === "unknown"`,
+ * `amountUsd` is `undefined` — DO NOT default to 0 (mentira). UI exibe
+ * `n/a` para unknown, `~$1.23` para estimated, `$1.23` para actual.
+ */
+interface CostBreakdown {
+    readonly amountUsd: number | undefined;
+    readonly status: CostStatus;
+    readonly currency: "USD";
+    readonly source: CostSource;
+    readonly pricingVersion: string | undefined;
+    readonly notes?: ReadonlyArray<string>;
+    /** Per-bucket detail (in USD) for caller analytics. */
+    readonly detail?: {
+        readonly input?: number;
+        readonly output?: number;
+        readonly cacheRead?: number;
+        readonly cacheWrite?: number;
+        readonly reasoning?: number;
+    };
+}
+
+/**
+ * Lifecycle status of a {@link Run}.
+ *
+ * @public
+ */
+type RunStatus = "running" | "finished" | "error" | "cancelled";
+/**
+ * Operations that may or may not be supported on a given {@link Run}, or on
+ * its parent agent.
+ *
+ * Runtime-specific availability — query at runtime with `run.supports(op)` and
+ * read the human reason via `run.unsupportedReason(op)`.
+ *
+ * @public
+ */
+type RunOperation = "stream" | "wait" | "cancel" | "conversation" | "listArtifacts" | "downloadArtifact" | "runUntil" | "fork" | "usePersonality" | "workflow";
+/**
+ * Git metadata attached to cloud runs.
+ *
+ * @public
+ */
+interface RunGitInfo {
+    branches: Array<{
+        repoUrl: string;
+        branch?: string;
+        prUrl?: string;
+    }>;
+}
+/**
+ * Terminal result of a {@link Run}.
+ *
+ * @public
+ */
+interface RunResult {
+    id: string;
+    status: "finished" | "error" | "cancelled";
+    result?: string;
+    model?: ModelSelection;
+    durationMs?: number;
+    git?: RunGitInfo;
+    /**
+     * Structured error detail, populated when `status === "error"`. Surfaces
+     * the diagnostic that emit-error-event pushes into the stream so callers
+     * that don't drain `run.stream()` still get the cause via `run.wait()`.
+     *
+     * For successful runs (`status: "finished"`) this is undefined.
+     *
+     * @public
+     */
+    error?: RunErrorDetail;
+    /**
+     * Token usage observed for this run (ADR D376). Populated in every
+     * status where ≥1 LLM call completed — including partial-failure
+     * runs (EC-5). `undefined` only when zero LLM calls executed (e.g.,
+     * abort before send).
+     *
+     * @public
+     */
+    usage?: TokenUsage;
+    /**
+     * Estimated/actual USD cost for this run (ADR D377). Always paired
+     * with `usage` when populated. `cost.status` tells caller how to
+     * trust the figure.
+     *
+     * @public
+     */
+    cost?: CostBreakdown;
+}
+/**
+ * Structured error attached to a {@link RunResult} when the underlying run
+ * transitioned to `"error"` status. `message` is always present; `code` is
+ * a stable identifier suitable for branching (e.g. `"llm_4xx"`,
+ * `"tool_dispatch_failed"`, `"mcp_init_failed"`); `cause` is the raw error
+ * for further inspection when available.
+ *
+ * @public
+ */
+interface RunErrorDetail {
+    message: string;
+    code?: string;
+    cause?: unknown;
+}
+/**
+ * Dimensions of an inline image attachment.
+ *
+ * @public
+ */
+interface SDKImageDimension {
+    width: number;
+    height: number;
+}
+/**
+ * Either a remote URL or inline base64 payload.
+ *
+ * @public
+ */
+type SDKImage = {
+    url: string;
+    dimension?: SDKImageDimension;
+} | {
+    data: string;
+    mimeType: string;
+    dimension?: SDKImageDimension;
+};
+/**
+ * Structured form of `agent.send()`'s message argument. Use it to send images
+ * alongside text.
+ *
+ * @public
+ */
+interface SDKUserMessage {
+    text: string;
+    images?: SDKImage[];
+}
+/**
+ * Per-send overrides and callbacks.
+ *
+ * @public
+ */
+interface SendOptions {
+    model?: ModelSelection;
+    /**
+     * Per-call system prompt override. Wins over `AgentOptions.systemPrompt`.
+     * String only — for dynamic resolvers, configure on `AgentOptions`. An
+     * empty string is honoured (it explicitly clears the system context).
+     */
+    systemPrompt?: string;
+    /** Fully replaces creation-time servers for this run (not merged). */
+    mcpServers?: Record<string, McpServerConfig>;
+    /**
+     * Per-call inline custom tools. Fully replaces `AgentOptions.tools` for
+     * this run (not merged). Local runtime only — cloud agents reject any
+     * non-empty per-call tools array with the same error code as creation
+     * (`cloud_custom_tools_rejected`). Semantics:
+     * - `undefined` → fall back to `AgentOptions.tools`
+     * - `[]` → explicitly clear (no custom tools for this run)
+     * - `[t1, t2]` → use exactly these tools for this run
+     */
+    tools?: CustomTool[];
+    onStep?: (args: {
+        step: ConversationStep;
+    }) => void | Promise<void>;
+    onDelta?: (args: {
+        update: InteractionUpdate;
+    }) => void | Promise<void>;
+    /** Local agents only. Expire a stuck active run before starting this message. */
+    local?: {
+        force?: boolean;
+    };
+    /**
+     * Optional `AbortSignal` propagated to memory adapter `pre_user_send`
+     * hooks (EC-H). Note: the LLM HTTP call itself is NOT cancellable
+     * mid-stream — same constraint as `Agent.batch` (ADR D140).
+     *
+     * @public
+     */
+    signal?: AbortSignal;
+    /**
+     * Opt-in task wrapping (ADRs D363, D374). When truthy, the entire
+     * run is registered as a `Task` in the SDK's observable registry —
+     * caller can list / inspect / cancel / subscribe via the `Task`
+     * namespace. Default behavior (no `task` option) is byte-identical
+     * to v1.1 (no Task overhead).
+     *
+     * Accepts:
+     * - `true` — auto-generate task id; no extra metadata.
+     * - `{ id, meta }` — user-supplied id (D368 grammar enforced) and/or
+     *   metadata attached to the handle's `meta` field.
+     *
+     * The work-fn `signal` is **merged** with `options.signal` (whichever
+     * aborts first wins). Local agents only — CloudAgent throws
+     * `UnsupportedTaskOperationError` (D370).
+     *
+     * @public
+     */
+    task?: true | {
+        id?: string;
+        meta?: Record<string, unknown>;
+    };
+}
+/**
+ * Handle to a single prompt submission.
+ *
+ * @public
+ */
+interface Run {
+    readonly id: string;
+    readonly agentId: string;
+    readonly status: RunStatus;
+    readonly result?: string;
+    readonly model?: ModelSelection;
+    readonly durationMs?: number;
+    readonly git?: RunGitInfo;
+    readonly createdAt?: number;
+    /** AsyncGenerator of normalized stream events. Discriminate on `event.type`. */
+    stream(): AsyncGenerator<SDKMessage, void>;
+    /** Resolves to the terminal {@link RunResult}. */
+    wait(): Promise<RunResult>;
+    /** Move status to `"cancelled"`, abort the stream, stop in-flight tool calls. */
+    cancel(): Promise<void>;
+    /** Structured per-turn view of the conversation. */
+    conversation(): Promise<ConversationTurn[]>;
+    /** Whether the given operation is available on this run's runtime. */
+    supports(operation: RunOperation): boolean;
+    /** Human-readable reason that `supports(operation)` returned `false`. */
+    unsupportedReason(operation: RunOperation): string | undefined;
+    /** Subscribe to status changes. Returns an unsubscribe function. */
+    onDidChangeStatus(listener: (status: RunStatus) => void): () => void;
+}
+
+export { HandoffReceiverDisposedError as $, type AgentOptions as A, type ContextBudget as B, type CloudOptions as C, type ContextManagerKind as D, type ContextSnapshot as E, type ContextSource as F, type GetAgentOptions as G, type HandoffOptions as H, type ContextSourceStatus as I, type ConversationStep as J, type ConversationTurn as K, type LocalOptions as L, type ModelSelection as M, type CostBreakdown as N, type CostSource as O, type ProviderRoutingSettings as P, type CostStatus as Q, type RunResult as R, type SystemPromptResolver as S, type GoalEvent as T, type GoalOptions as U, type GoalResult as V, type HandoffContext as W, type HandoffHistory as X, HandoffLoopError as Y, HandoffNameCollisionError as Z, HandoffPairLoopError as _, type MemorySettings as a, type ThinkingMessage as a$, type HandoffResult as a0, HandoffSelfReferenceError as a1, type InteractionUpdate as a2, type InvalidateCacheOptions as a3, type McpAuthConfig as a4, type McpHttpServerConfig as a5, type McpOAuthConfig as a6, type McpStdioServerConfig as a7, type MemoryAdapter as a8, type MemoryAdapterCapabilities as a9, type SDKRequestMessage as aA, type SDKStatusMessage as aB, type SDKSystemMessage as aC, type SDKTaskMessage as aD, type SDKThinkingMessage as aE, type SDKToolUseMessage as aF, type SDKUserMessage as aG, type SDKUserMessageEvent as aH, type SendOptions as aI, type SettingSource as aJ, type ShellCommand as aK, type ShellConversationTurn as aL, type ShellOutput as aM, type ShellOutputDeltaUpdate as aN, type StepCompletedUpdate as aO, type StepStartedUpdate as aP, type SummaryCompletedUpdate as aQ, type SummaryStartedUpdate as aR, type SummaryUpdate as aS, type SystemPromptContext as aT, type SystemPromptMemoryFact as aU, type SystemPromptSkillRef as aV, type TelemetrySettings as aW, type TextBlock as aX, type TextDeltaUpdate as aY, type ThinkingCompletedUpdate as aZ, type ThinkingDeltaUpdate as a_, type MemoryContext as aa, type MemoryFact as ab, type MemoryRevision as ac, type MemoryToolSchema as ad, type MemoryTurnMessage as ae, type ModelParameterValue as af, type PartialToolCallUpdate as ag, type PersonalityPreset as ah, type ProviderCapability as ai, type ProviderRoute as aj, type ResolvedProviderRoute as ak, type RunErrorDetail as al, type RunGitInfo as am, type RunOperation as an, type RunStatus as ao, type RunUntilIterator as ap, type SDKAgentPlugins as aq, type SDKAgentSkills as ar, type SDKArtifact as as, type SDKAssistantMessage as at, type SDKContextManager as au, type SDKImage as av, type SDKImageDimension as aw, type SDKObjectDelta as ax, type SDKPluginMetadata as ay, type SDKProvidersManager as az, type CustomTool as b, type TokenDeltaUpdate as b0, type TokenUsage as b1, type ToolCall as b2, type ToolCallCompletedUpdate as b3, type ToolCallStartedUpdate as b4, type ToolUseBlock as b5, type TurnEndedUpdate as b6, type UserMessage as b7, type UserMessageAppendedUpdate as b8, type McpServerConfig as c, type AgentDefinition as d, type ContextSettings as e, type PluginsSettings as f, type SkillsSettings as g, type SDKAgent as h, type ListAgentsOptions as i, type ListResult as j, type SDKAgentInfo as k, type ListRunsOptions as l, type Run as m, type GetRunOptions as n, type AgentOperationOptions as o, type HandoffDescriptor as p, type ConversationStorageAdapter as q, type StoredMessage as r, type MemoryId as s, type SDKProvider as t, type SDKMessage as u, type AgentConversationTurn as v, type AgentMemory as w, type AssistantMessage as x, type CloudEnv as y, type CloudRepo as z };