@theokit/sdk 4.53.1 → 4.55.0

package/dist/sdk-agent-DEoKhA8a.d.cts

@@ -0,0 +1,860 @@
+import { M as ModelSelection, ad as SDKUserMessage, af as SendOptions, b as Run, G as GenerateOptions, n as GenerateRunResult, $ as RunToCompletionOptions, a0 as RunToCompletionResult, S as SDKMessage, am as StreamToCompletionResult } from './run-BYSHf58D.cjs';
+import * as zod from 'zod';
+
+/**
+ * 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. Typically "do I have the credentials I
+     * need".
+     *
+     * `false` DISABLES the adapter: the runtime skips it when building the agent's memory, warns
+     * naming this `id`, and carries on with whatever other adapters said yes. When every registered
+     * adapter declines, a `write` or `recall` fails with `no_memory_adapter` and a message saying so,
+     * rather than resolving without storing anything.
+     *
+     * It was mandatory and consulted by nothing until #360, which made it a contract that read as a
+     * guarantee and provided none — a missing key surfaced mid-conversation as `auth_failed` instead.
+     */
+    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>;
+}
+
+/**
+ * Fork primitive public type contracts (T1.2, ADRs D110-D114).
+ *
+ * Extracted into a leaf type module (arch-review ADR 0001) so the public
+ * `types/agent.ts` barrel can reference `ForkOptions`/`ForkResult` without
+ * importing the `internal/runtime/lifecycle/fork-agent.ts` implementation — which in
+ * turn imports back from `types/agent.ts`. That mutual reference created a
+ * type-only `madge` cycle. These interfaces are self-contained (no SDKAgent
+ * / AgentOptions references), so co-locating them here breaks the cycle with
+ * no runtime change. `fork-agent.ts` re-exports them for back-compat.
+ */
+/**
+ * Caller-supplied fork configuration. See `forkAgentImpl`.
+ *
+ * @public
+ */
+interface ForkOptions {
+    /**
+     * Tool subset visible to the fork. Names must match the canonical (post-repair)
+     * tool name — typically lowercase. Tools not in this set return a `tool_result`
+     * with `"Tool blocked by fork whitelist"` content (EC-H).
+     */
+    allowedTools: Set<string>;
+    /** Task prompt sent to the fork. */
+    prompt: string;
+    /** Override system prompt. Default: byte-identical inheritance from parent (D112). */
+    systemPrompt?: string;
+    /** Memory write provenance tag (D114). Default `"fork"`. */
+    forkOrigin?: string;
+}
+/**
+ * Outcome of a fork run.
+ *
+ * @public
+ */
+interface ForkResult {
+    /** Final agent response text (`undefined` when the fork produced no result). */
+    result: string | undefined;
+    /** Tool calls executed inside the fork. */
+    toolCalls: ReadonlyArray<{
+        name: string;
+        input: Record<string, unknown>;
+    }>;
+    /** Aggregate token usage reported by the run. */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+
+/**
+ * M80 — the terminal verdicts a judge can return.
+ *
+ * `"blocked"` was added here in this milestone. `GoalResult.status` already carried it, but the
+ * judge had no way to EMIT it: its vocabulary was `done | continue | skipped`, so facing a real
+ * blocker it could only say `continue` — and the loop repeated the same turn until it blew the
+ * budget, reporting `failed` on a limit rather than `blocked` on impossibility. Two different causes
+ * with the same visible outcome.
+ *
+ * @public
+ */
+type Verdict = "done" | "continue" | "skipped" | "blocked";
+/**
+ * M80 — the result of a judge call, now public.
+ *
+ * It was `internal/`, so a consumer wanting to type the return — to react to `blocked` without a
+ * magic string — had to redeclare the shape. It is the same duplication M78 closed for the error
+ * hierarchy: without a public surface, reimplementing is the only legal way out for anyone behind
+ * the layer boundary.
+ *
+ * @public
+ */
+interface JudgeResult {
+    verdict: Verdict;
+    reason: string;
+    /**
+     * `true` when the text did not start with one of the canonical prefixes. The verdict becomes
+     * `"continue"` (fail-safe) so the loop does not stop too early; the caller counts consecutive
+     * failures and gives up via `maxConsecutiveJudgeFailures`.
+     */
+    parseFailed: boolean;
+}
+/**
+ * Single event emitted while iterating a goal-driven loop — the public event type of
+ * {@link SDKAgent.runUntil} (ADRs D115-D117). Discriminated union by the `type` field so
+ * consumers can `switch (event.type)` with full TypeScript exhaustiveness; mirrors the
+ * {@link import("../stream-object.js").StreamObjectEvent} pattern (ADR D39).
+ *
+ * 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;
+    /** M80 — `"blocked"` was added: the judge can declare impossibility, not just "continue". */
+    verdict: "done" | "continue" | "skipped" | "blocked";
+    reason: string;
+    parseFailed: boolean;
+} | {
+    type: "continuation";
+    turn: number;
+    prompt: string;
+} | {
+    type: "status_change";
+    status: "active" | "paused" | "completed" | "failed" | "budget_limited" | "blocked";
+    reason: string;
+};
+/**
+ * Return value of the `runUntil` async generator. Consumer reads via
+ * `const { value } = await gen.next()` (when `done: true`).
+ *
+ * @public
+ */
+interface GoalResult {
+    status: "completed" | "failed" | "paused" | "budget_limited" | "blocked";
+    turnsUsed: number;
+    /** M55 — tokens summed across the loop (0 when `usage` was absent — fail-open). */
+    tokensUsed: number;
+    finalResponse: string | undefined;
+}
+/**
+ * Return type of {@link import("../internal/local-agent/local-agent.js").LocalAgent.runUntil}.
+ * Extracted so the LocalAgent method signature stays a single line (G8 LoC budget).
+ *
+ * @public
+ */
+type RunUntilIterator = AsyncGenerator<GoalEvent, GoalResult, void>;
+/**
+ * Per-call configuration for `Agent.runUntil`.
+ *
+ * @public
+ */
+interface GoalOptions {
+    /** Hard cap on iterations (safety net against runaway). Default `20`. */
+    maxTurns?: number;
+    /**
+     * M55 — token budget (Codex ext/goal parity, tool.rs:454-465). Sums `run.wait().usage.totalTokens`
+     * per turn; on crossing it, the loop stops with status `budget_limited`. Omitted => unlimited (only
+     * maxTurns). A missing `usage` never blows the budget (fail-open).
+     */
+    tokenBudget?: number;
+    /** Bail after N consecutive judge parse failures. Default `3` (ADR D121). */
+    maxConsecutiveJudgeFailures?: number;
+    /** Judge model identifier. Default `"openai/gpt-4o-mini"` (ADR D119). */
+    judgeModel?: string;
+    /** Override env for the judge auxiliary agent. Default `OPENROUTER_API_KEY` (EC-A). */
+    judgeApiKey?: string;
+    /**
+     * M80 — the model of the DRIVEN agent, the basis for deriving the judge when `judgeModel` is
+     * omitted.
+     *
+     * It exists because the fixed default (`openai/gpt-4o-mini`) only resolves on OpenRouter: an
+     * Anthropic key gives 404, an OAuth bearer gives 401, and the goal burned 3 turns before failing
+     * with a misleading reason. A judge running on the chat's own model works wherever chat works.
+     */
+    agentModel?: string;
+    /** Optional subgoals fed to the judge prompt. */
+    subgoals?: string[];
+    /**
+     * Cancel mid-loop via `AbortController.signal`. The generator yields
+     * a `status_change: paused` event and returns at the next turn
+     * boundary (ADR D117).
+     */
+    signal?: AbortSignal;
+}
+
+/**
+ * Capability slot a provider can fulfill.
+ *
+ * @public
+ */
+type ProviderCapability = "chat" | "web_search" | "image" | "embedding";
+/**
+ * A single user-declared routing rule. Maps a capability to a provider, and
+ * optionally pins a specific model.
+ *
+ * @public
+ */
+interface ProviderRoute {
+    capability: ProviderCapability;
+    provider: string;
+    model?: string;
+    /**
+     * Opt-in leaked-dialect safe-parse for this route's provider (theokit#58
+     * follow-up). When `true`, a `chat_completions` finish that carries ZERO
+     * native `tool_calls` has its assistant text scanned for the Hermes
+     * `<function=…></tool_call>` dialect, and any recovered calls are surfaced as
+     * real `tool_calls` so the loop executes them — for models (qwen3-coder via
+     * OpenRouter) that intermittently leak tool calls as text. Default `false`;
+     * fail-open (a partial/unclosed block never fabricates a call). Scoped to the
+     * resolved chat chain, so a non-leaking route is unaffected.
+     */
+    extractToolCallsFromContent?: boolean;
+}
+/**
+ * Provider routing configuration accepted by `Agent.create()` via
+ * {@link AgentOptions.providers}.
+ *
+ * @public
+ */
+interface ProviderRoutingSettings {
+    /** Explicit `{ capability → provider }` map. First match wins per capability. */
+    routes: ProviderRoute[];
+    /** Provider names to try in order when a route has no provider available. */
+    fallback?: string[];
+    /**
+     * Multiple API keys per provider for same-provider key rotation
+     * (credential pool — ADRs D123-D133). When a key hits HTTP 429, 402,
+     * or 401, the SDK rotates to the next entry transparently before
+     * falling back to a different provider.
+     *
+     * Example:
+     * ```ts
+     * apiKeys: { openrouter: ["sk-or-...", "sk-or-..."], anthropic: ["..."] }
+     * ```
+     *
+     * Empty arrays and empty strings are filtered out. If a provider has
+     * exactly 1 effective key, the pool is transparent (no rotation behavior).
+     *
+     * Conflicts with the single-key shape `AgentOptions.apiKey: "..."` —
+     * use one OR the other, not both.
+     *
+     * @public
+     */
+    apiKeys?: Record<string, string[]>;
+    /**
+     * Rotation strategy per provider for the credential pool. Default is
+     * `"fill_first"` (use entries[0] until exhausted). Only consulted when
+     * `apiKeys[provider]` has ≥2 entries.
+     *
+     * @public
+     */
+    credentialPoolStrategy?: Record<string, "fill_first" | "round_robin" | "least_used" | "random">;
+}
+/**
+ * Plugins configuration accepted by `Agent.create()` via
+ * {@link AgentOptions.plugins}.
+ *
+ * @public
+ */
+interface PluginsSettings {
+    /** Plugin names to enable. Plugin discovery is plugin-provider specific. */
+    enabled?: string[];
+}
+/**
+ * Resolved routing decision returned by `agent.providers.routes()`. Public and
+ * secret-free by design — safe to log.
+ *
+ * @public
+ */
+interface ResolvedProviderRoute {
+    capability: string;
+    provider: string;
+    model?: string;
+    /** Why the runtime picked this provider (e.g. `"explicit-model-provider"`). */
+    reason: string;
+}
+/**
+ * Public providers manager handle exposed as `agent.providers`.
+ *
+ * @public
+ */
+interface SDKProvidersManager {
+    /** Inspect which provider serves each capability for this agent. */
+    routes(): Promise<ResolvedProviderRoute[]>;
+}
+/**
+ * Provider catalog entry returned by `Theokit.providers.list()`.
+ *
+ * @public
+ */
+interface SDKProvider {
+    name: string;
+    displayName: string;
+    capabilities: string[];
+    isAvailable: boolean;
+    /** JSON Schema describing the env vars / fields needed to enable this provider. */
+    setupSchema: object;
+}
+
+/**
+ * Public skill metadata exposed to the system-prompt resolver. Mirrors the
+ * shape returned by `agent.skills.list()` — name + description only, never
+ * full skill bodies.
+ *
+ * @public
+ */
+interface SystemPromptSkillRef {
+    name: string;
+    description: string;
+}
+/**
+ * A skill resolved WITH its body, returned by {@link SDKAgentSkills.get}. Unlike
+ * {@link SystemPromptSkillRef} (name + description only), this carries the full
+ * `instructions` — read from the SKILL.md for filesystem skills or the inline
+ * `createSkill` body. @public
+ */
+interface SDKAgentSkillDetail {
+    name: string;
+    description: string;
+    instructions: string;
+    /** SE21 — supporting documents bundled with the skill (filename → content), when present. */
+    references?: Record<string, string>;
+}
+/**
+ * The skill handle exposed as `agent.skills`, present only when project-scoped skills are enabled
+ * (`settingSources: ["project"]`) or `skills.enabled` is set. The property is optional on the agent,
+ * and `undefined` there means skills were never turned on — not that none were found.
+ *
+ * The split between its two methods is the choice it asks of a caller. `list()` returns name and
+ * description only, which is what belongs in a system prompt: it stays cheap and it keeps skill
+ * bodies out of the context window. `get(name)` resolves one skill WITH its `instructions` — the
+ * SKILL.md body for a filesystem skill, the inline body for one built with `createSkill` — and
+ * returns `undefined` when no enabled skill matches that name. Ask for a body only when you are
+ * about to use it.
+ *
+ * @public
+ */
+interface SDKAgentSkills {
+    list(): Promise<ReadonlyArray<SystemPromptSkillRef>>;
+    /**
+     * SE20 — resolve a skill by name INCLUDING its body (`instructions`). Returns
+     * `undefined` when no enabled skill matches. `list()` stays lean (name +
+     * description); full bodies come only through `get`.
+     */
+    get(name: string): Promise<SDKAgentSkillDetail | undefined>;
+}
+/**
+ * Public plugin metadata returned by `agent.plugins.list()`. Mirrors the
+ * `.theokit/plugins/<name>/MANIFEST.json` allow-listed shape; never exposes
+ * raw plugin bodies, credentials, or internal hooks.
+ *
+ * @public
+ */
+interface SDKPluginMetadata {
+    name: string;
+    description?: string;
+}
+/**
+ * Public plugin listing handle exposed as `agent.plugins`. Populated when
+ * `settingSources` includes `"plugins"` OR when `plugins.enabled` is set
+ * on the agent options.
+ *
+ * @public
+ */
+interface SDKAgentPlugins {
+    list(): Promise<ReadonlyArray<SDKPluginMetadata>>;
+}
+/**
+ * Artifact produced inside an agent's workspace. Cloud-only.
+ *
+ * @public
+ */
+interface SDKArtifact {
+    path: string;
+    sizeBytes: number;
+    updatedAt: string;
+}
+/**
+ * Handle returned by `Agent.create()` and `Agent.resume()`.
+ *
+ * @public
+ */
+interface SDKAgent {
+    readonly agentId: string;
+    readonly model: ModelSelection | undefined;
+    /**
+     * Context manager for this agent. Populated when context is enabled via
+     * {@link AgentOptions.context}. See {@link SDKContextManager}.
+     */
+    readonly context?: SDKContextManager;
+    /**
+     * Provider routing inspector for this agent. Populated when at least one
+     * provider route is configured (via {@link AgentOptions.providers}, plugins,
+     * or model-implied providers). See {@link SDKProvidersManager}.
+     */
+    readonly providers?: SDKProvidersManager;
+    /**
+     * Skill listing for this agent. Populated when project-scoped skills are
+     * enabled (`settingSources: ["project"]`) or when `skills.enabled` is set.
+     * See {@link SDKAgentSkills}.
+     */
+    readonly skills?: SDKAgentSkills;
+    /**
+     * Plugin listing for this agent. Populated when project-scoped plugins are
+     * enabled (`settingSources: ["plugins"]`) or when `plugins.enabled` is set.
+     * See {@link SDKAgentPlugins}.
+     */
+    readonly plugins?: SDKAgentPlugins;
+    send(message: string | SDKUserMessage, options?: SendOptions): Promise<Run>;
+    /**
+     * SE9 — integrated structured output. Runs the normal tool loop (the tools run
+     * first) then coerces the final answer into the `output` Zod schema, returning a
+     * validated, inferred-typed object. Sugar over `Agent.generateObject` (ADR D33).
+     */
+    generate<T extends zod.ZodType>(message: string | SDKUserMessage, options: GenerateOptions<T>): Promise<GenerateRunResult<zod.z.infer<T>>>;
+    /** Fire-and-forget disposal. */
+    close(): void;
+    /** Re-read filesystem config (context, hooks, project MCP, subagents) without disposing. */
+    reload(): Promise<void>;
+    /**
+     * Async disposal. Idempotent — calling more than once is a no-op (per ADR D5).
+     * Prefer `await using agent = await Agent.create(...)` over explicit
+     * `dispose()` for resource safety.
+     */
+    dispose(): Promise<void>;
+    /**
+     * `await using` support per ADR D5. Identical semantics to `dispose()` —
+     * idempotent across both surfaces.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /** Cloud-only. Local returns an empty array. */
+    listArtifacts(): Promise<SDKArtifact[]>;
+    /** Cloud-only. Local throws `UnsupportedRunOperationError`. */
+    downloadArtifact(path: string): Promise<Buffer>;
+    /**
+     * Signal that prompt cache should be invalidated. By default deferred —
+     * applied at the start of the next `send()`. Pass `{ applyNow: true }` to
+     * force immediate disposal (caller must `Agent.create()` again to use).
+     *
+     * Cache invalidation is a cost regression (provider charges full price
+     * for the rebuilt cache; see ADRs D94-D95). Use sparingly and deliberately.
+     *
+     * Cloud agents: no-op (cloud runtime reconstructs state per request).
+     *
+     * @public
+     */
+    invalidateCache?(reason: string, options?: InvalidateCacheOptions): Promise<void>;
+    /**
+     * Goal-driven Ralph loop (ADRs D115-D121). Iterates `agent.send` →
+     * judge → continuation until the auxiliary judge model returns `done`,
+     * the judge fails too many times in a row, max turns are exhausted,
+     * or the caller aborts via `AbortSignal`.
+     *
+     * Yields {@link import("./goal-events.js").GoalEvent} per state
+     * transition; returns a {@link import("./goal-events.js").GoalResult}
+     * summary as the generator's final value.
+     *
+     * Cloud agents throw {@link import("../errors.js").UnsupportedRunOperationError}
+     * **synchronously** (no AsyncGenerator returned) — wrap in try/catch
+     * if you support both runtimes.
+     *
+     * Caveat: do not call `agent.dispose()` mid-iteration; the next `send`
+     * propagates the disposal error through the generator to the consumer.
+     *
+     * @public
+     */
+    runUntil?(goal?: string, options?: GoalOptions): RunUntilIterator;
+    /**
+     * Fork a short-lived sub-agent with parent's credentials + system
+     * prompt byte-identical (ADR D112 — cache hit) and a restricted tool
+     * whitelist (ADR D111 — AsyncLocalStorage isolation).
+     *
+     * Cloud agents throw {@link import("../errors.js").UnsupportedRunOperationError}.
+     *
+     * @public
+     */
+    fork?(options: ForkOptions): Promise<ForkResult>;
+    /**
+     * Drive `send` to completion across iteration-ceiling truncations (M1 Phase 3).
+     * When a `send` stops at the loop's iteration cap (`RunResult.stoppedAtIterationLimit`),
+     * this re-sends a short continuation prompt — the agent's stateful session
+     * preserves the conversation — until a genuine terminal: `done` (finished),
+     * `step_limit` (`maxRounds` exhausted), or `no_progress` (two empty rounds).
+     *
+     * Local agents only. Cloud agents throw
+     * {@link import("../errors.js").UnsupportedRunOperationError} (the cloud
+     * runtime manages its own continuation policy server-side).
+     *
+     * @public
+     */
+    runToCompletion?(message: string, options?: RunToCompletionOptions): Promise<RunToCompletionResult>;
+    /**
+     * STREAMING continuation driver (V3-4) — the streaming twin of
+     * {@link SDKAgent.runToCompletion}. Returns an `AsyncGenerator` that yields each
+     * round's {@link import("./messages.js").SDKMessage}s LIVE (for a UI), reusing the
+     * same terminal policy (`done`/`step_limit`/`no_progress` + bounded re-prompt).
+     *
+     * The {@link import("./run.js").StreamToCompletionResult} is the generator's RETURN
+     * value — read it via a manual `gen.next()` loop (`while (!res.done) res = await
+     * gen.next()` → `res.value`); a plain `for await...of` consumes the yielded
+     * messages but discards the return value.
+     *
+     * Local agents only. Cloud agents throw
+     * {@link import("../errors.js").UnsupportedRunOperationError}.
+     *
+     * @public
+     */
+    streamToCompletion?(message: string, options?: RunToCompletionOptions): AsyncGenerator<SDKMessage, StreamToCompletionResult>;
+    /**
+     * Direct API to third-party memory adapter(s) registered via
+     * `plugins: [...]` (ADR D141 / D142). Returns `null` when no adapter
+     * is registered. In multi-adapter setups `write` fans out to all;
+     * `recall` merges + dedupes; `delete` routes by `MemoryId` prefix.
+     *
+     * @public
+     */
+    memory?: AgentMemory;
+    /**
+     * Activate a personality preset for the next `send` (Hermes #26).
+     * Reserved names `"none"`, `"default"`, and `"neutral"` clear the
+     * active preset. Returns the resolved preset (or `null` when cleared).
+     *
+     * Persistence: pass `{ save: true }` to persist across process
+     * restarts (stored under `$THEOKIT_HOME/personality.json`).
+     *
+     * History: by default the conversation history is preserved across
+     * the switch. Pass `{ reset: true }` to also clear the session.
+     *
+     * Cloud agents throw {@link import("../errors.js").UnsupportedRunOperationError}.
+     *
+     * @public
+     */
+    usePersonality?(name: string, opts?: {
+        save?: boolean;
+        reset?: boolean;
+    }): Promise<PersonalityPreset | null>;
+}
+/**
+ * Resolved personality preset surfaced via {@link SDKAgent.usePersonality}
+ * (Hermes #26, ADRs D160-D169). Re-declared here so the public DTS bundle
+ * never crosses the `internal/` path boundary. The implementation type in
+ * `internal/personality/types.ts` is structurally identical.
+ *
+ * @public
+ */
+interface PersonalityPreset {
+    readonly name: string;
+    readonly description: string | undefined;
+    readonly tools: ReadonlyArray<string> | undefined;
+    readonly model: string | undefined;
+    readonly tags: ReadonlyArray<string> | undefined;
+    readonly systemPrompt: string;
+    readonly source: "project" | "user";
+    readonly sourcePath: string;
+}
+/**
+ * Options for {@link SDKAgent.invalidateCache}.
+ *
+ * @public
+ */
+interface InvalidateCacheOptions {
+    /**
+     * When `true`, dispose the agent immediately so caller must recreate it
+     * to continue. Default `false` (deferred — applied on next `send()`).
+     */
+    applyNow?: boolean;
+}
+
+export type { AgentMemory as A, SDKProvidersManager as B, ContextSettings as C, SystemPromptSkillRef as D, GoalOptions as G, InvalidateCacheOptions as I, JudgeResult as J, MemoryId as M, ProviderRoutingSettings as P, ResolvedProviderRoute as R, SDKAgent as S, Verdict as V, PluginsSettings as a, GoalEvent as b, GoalResult as c, SDKProvider as d, ContextBudget as e, ContextManagerKind as f, ContextSnapshot as g, ContextSource as h, ContextSourceStatus as i, MemoryAdapter as j, MemoryAdapterCapabilities as k, MemoryContext as l, MemoryFact as m, MemoryRevision as n, MemoryToolSchema as o, MemoryTurnMessage as p, PersonalityPreset as q, ProviderCapability as r, ProviderRoute as s, RunUntilIterator as t, SDKAgentPlugins as u, SDKAgentSkillDetail as v, SDKAgentSkills as w, SDKArtifact as x, SDKContextManager as y, SDKPluginMetadata as z };