@theokit/sdk 4.53.1 → 4.55.0

package/dist/{agent-nLqeXKIX.d.cts → agent-DIu6FooJ.d.ts}

@@ -1,5 +1,5 @@
-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, C as CustomTool, c as PermissionMode, a as McpServerConfig, P as Processor } from './run-C8FBAC8o.cjs';
-import * as zod from 'zod';
+import { m as MemoryFact, j as MemoryAdapter, S as SDKAgent, l as MemoryContext, D as SystemPromptSkillRef, C as ContextSettings, P as ProviderRoutingSettings, a as PluginsSettings } from './sdk-agent-D8qJVkuV.js';
+import { C as CustomTool, c as PermissionMode, M as ModelSelection, a as McpServerConfig, P as Processor } from './run-BYSHf58D.js';
 
 /**
  * `SessionRecord` — the native on-disk transcript record shape (SE40).
@@ -15,7 +15,6 @@ import * as zod from 'zod';
  *
  * @public
  */
-/** One transcript record (one JSONL line). `message` absent on `system` (compact_boundary) records. */
 /** A content block inside {@link TranscriptMessage}. */
 type TranscriptBlock = {
     type: "text";
@@ -60,6 +59,24 @@ interface TranscriptMessage {
     type?: "message";
     model?: string;
 }
+/**
+ * One transcript record — a single line of the session JSONL file, and the unit the pluggable
+ * `SessionStore` seam reads and writes.
+ *
+ * Records form a `uuid`/`parentUuid` DAG, not a flat list: `parentUuid` names the preceding record
+ * and is `null` at the root. Thread a session by following those links; a reader that assumes file
+ * order is linear will mis-thread one that branched.
+ *
+ * `message` is absent on `system` records — a compaction boundary carries `compactMetadata` instead —
+ * so it is optional even on records you would expect to be conversational, and `type` is what tells
+ * you which you are holding.
+ *
+ * Reading is deliberately tolerant: a malformed line is skipped rather than failing the whole read.
+ * Every record you receive is well-formed, but the file may have contained more than you got back,
+ * so this is not the type to use for an exact-count audit of what was written.
+ *
+ * @public
+ */
 interface SessionRecord {
     type: "user" | "assistant" | "system";
     uuid: string;
@@ -144,182 +161,6 @@ interface SessionStore {
     appendRecords(agentId: string, records: readonly SessionRecord[]): Promise<void>;
 }
 
-/**
- * Public `MemoryAdapter` contract (T1.1, ADRs D141 / D147).
- *
- * The plugin extension point `{ kind: "memory" }` (ADR D98) declares a
- * `createProvider` factory; this file types its return value formally.
- * Adapters implement `write` / `recall` / `delete` plus optional methods
- * gated by `capabilities`. `MemoryId` is a branded string prefixed with
- * the adapter id so cross-adapter use throws on `extractRawId` (EC-B).
- *
- * Each provider-specific package (`@theokit-memory-supermemory`, etc)
- * exports a factory returning a `Plugin { kind: "memory" }` whose
- * `createProvider` resolves to a `MemoryAdapter` instance.
- *
- * @public
- */
-/**
- * Branded provider memory ID. Format: `${adapterId}:${rawProviderId}`.
- * Use `mkMemoryId` / `extractRawId` from `../memory-adapter-helpers.js`
- * to construct and unwrap with cross-adapter safety (EC-B).
- *
- * @public
- */
-type MemoryId = string & {
-    readonly __brand: "MemoryId";
-};
-/**
- * Portable identity context. `userId` is the only required field —
- * the lowest common denominator across Supermemory / Honcho / Mem0.
- * Adapter implementations translate the optional fields to their
- * provider's native primitives (Honcho session, Mem0 run_id, etc).
- *
- * @public
- */
-interface MemoryContext {
-    /** End-user identity. */
-    userId: string;
-    /** Agent / persona writing the memory. */
-    agentId?: string;
-    /** Logical conversation / run boundary. */
-    sessionId?: string;
-    /** Tenant / workspace partition. */
-    tenantId?: string;
-    /** Free-form tags for filtering / categorization. */
-    tags?: string[];
-    /** Provider-passthrough metadata. */
-    metadata?: Record<string, unknown>;
-}
-/**
- * A single memory fact returned by `recall` or `get`.
- *
- * @public
- */
-interface MemoryFact {
-    id: MemoryId;
-    content: string;
-    /** Semantic relevance score (provider-defined scale) when result of `recall`. */
-    score?: number;
-    /** ISO 8601 timestamp of creation. */
-    createdAt?: string;
-    metadata?: Record<string, unknown>;
-}
-/**
- * Versioned snapshot of a memory's history. Only emitted by providers
- * with `capabilities.history === true` (Mem0 today).
- *
- * @public
- */
-interface MemoryRevision {
-    id: MemoryId;
-    content: string;
-    version: number;
-    changedAt: string;
-}
-/**
- * Statically declared adapter feature flags. Consumers feature-detect
- * at compile time via `if (adapter.capabilities.history)`.
- *
- * @public
- */
-interface MemoryAdapterCapabilities {
-    /** Returns prior versions of a memory via `history(id)`. */
-    history: boolean;
-    /** First-class `sessionId` scoping. */
-    sessions: boolean;
-    /** First-class `tenantId` scoping. */
-    tenancy: boolean;
-    /** Provider performs reasoning over memory (e.g., Honcho dialectic). */
-    reasoning: boolean;
-    /** Exposes LLM-callable function-calling schemas. */
-    toolSchemas: boolean;
-    /** Supports background prefetch (currently informational). */
-    prefetch: boolean;
-}
-/**
- * One assistant-turn message in the canonical `{role, content}` shape
- * an adapter may receive instead of a flat string when writing a turn.
- *
- * @public
- */
-interface MemoryTurnMessage {
-    role: "user" | "assistant" | "system";
-    content: string;
-}
-/**
- * OpenAI-format function-calling schema exposed to the LLM.
- *
- * @public
- */
-interface MemoryToolSchema {
-    name: string;
-    description: string;
-    parameters: Record<string, unknown>;
-}
-/**
- * Portable third-party memory adapter contract. Implementations live
- * in `@theokit-memory-*` packages; the SDK never imports them.
- *
- * @public
- */
-interface MemoryAdapter {
-    /** Short identifier — matches the `${adapterId}` prefix in `MemoryId`. */
-    readonly id: string;
-    readonly capabilities: MemoryAdapterCapabilities;
-    /** Synchronous availability probe — no network, no I/O. */
-    isAvailable(): boolean;
-    /** One-shot initialization. Idempotent: safe to call multiple times. */
-    initialize?(): Promise<void>;
-    /**
-     * Persist a fact or full turn to memory. Returns the stored
-     * `MemoryId`. Throws `MemoryAdapterError(code: "invalid_input")` on
-     * empty content or invalid identifiers in `ctx`.
-     */
-    write(content: string | MemoryTurnMessage[], ctx: MemoryContext): Promise<MemoryId>;
-    /**
-     * Semantic recall — top-`k` facts ordered by relevance. Returns
-     * empty array when `k === 0` or no matches.
-     */
-    recall(query: string, ctx: MemoryContext, k?: number): Promise<MemoryFact[]>;
-    /**
-     * Delete a memory by id. Throws `MemoryAdapterError(code:
-     * "invalid_input")` when the id was minted by a different adapter
-     * (EC-B). Throws `code: "not_found"` when the id does not exist.
-     */
-    delete(id: MemoryId): Promise<void>;
-    list?(ctx: MemoryContext, opts?: {
-        cursor?: string;
-        limit?: number;
-    }): AsyncIterable<MemoryFact>;
-    get?(id: MemoryId): Promise<MemoryFact | null>;
-    history?(id: MemoryId): Promise<MemoryRevision[]>;
-    /** Empty array when `capabilities.toolSchemas === false`. */
-    getToolSchemas?(): MemoryToolSchema[];
-    handleToolCall?(name: string, args: Record<string, unknown>, ctx: MemoryContext): Promise<string>;
-    /** Graceful shutdown — flush queues, close connections. */
-    shutdown?(): Promise<void>;
-}
-/**
- * Direct memory API exposed on `SDKAgent.memory`. Resolves to whichever
- * memory adapter(s) are registered via `Agent.create({ plugins: [...] })`.
- *
- * @public
- */
-interface AgentMemory {
-    /**
-     * Persist a fact. Returns the first adapter's id; in multi-adapter
-     * setups all adapters receive the write (fan-out).
-     */
-    write(content: string | MemoryTurnMessage[], ctx?: Partial<MemoryContext>): Promise<MemoryId>;
-    /** Semantic recall — merged + deduped across registered adapters. */
-    recall(query: string, ctx?: Partial<MemoryContext>, k?: number): Promise<MemoryFact[]>;
-    /** Delete a memory by id — routes to the owning adapter via prefix. */
-    delete(id: MemoryId): Promise<void>;
-    /** Returns the first registered adapter or `null` when none exists. */
-    adapter(): MemoryAdapter | null;
-}
-
 /**
  * A discovered skill's metadata. The skill BODY is never included — only the
  * strict frontmatter fields plus the resolved `source` path.
@@ -453,665 +294,6 @@ interface BudgetTracker {
     nextIteration?(): void;
 }
 
-/**
- * Context manager backend.
- *
- * - `"file"` — Read `.theokit/context.json` from the workspace (local) or the
- *   cloned repo (cloud).
- *
- * @public
- */
-type ContextManagerKind = "file";
-/**
- * Context configuration accepted by `Agent.create()` via {@link AgentOptions.context}.
- *
- * @public
- */
-interface ContextSettings {
-    /** Which backend reads context. Defaults to `"file"`. */
-    manager?: ContextManagerKind;
-    /** Hard cap on tokens emitted into the agent's system prompt. */
-    maxTokens?: number;
-    /**
-     * Per-file truncation cap in characters. Default 40_000 (~10k tokens).
-     * Larger files are truncated with 70%/20% head/tail + marker (ADR D155).
-     *
-     * @public
-     */
-    maxBytesPerFile?: number;
-    /**
-     * Aggregate cap across all context files in characters. Default 120_000.
-     * When total exceeds this, lower-priority sources are dropped (ADR D155).
-     *
-     * Note: context snapshot is **refresh-time** (EC-T); modifying context
-     * files mid-flight does not auto-update. Call `agent.reload()` to pick
-     * up changes.
-     *
-     * @public
-     */
-    maxBytesTotal?: number;
-}
-/**
- * Inclusion state of a single context source in a {@link ContextSnapshot}.
- *
- * @public
- */
-type ContextSourceStatus = "included" | "excluded" | "summarized";
-/**
- * A single context source resolved by the context manager.
- *
- * @public
- */
-interface ContextSource {
-    /** Stable identifier — usually the filename without extension. */
-    name: string;
-    /** Path relative to the workspace root, when applicable. */
-    path?: string;
-    /** Whether the source was included, dropped, or summarized to fit the budget. */
-    status: ContextSourceStatus;
-    /** Free-text reason when `status !== "included"`. */
-    reason?: string;
-}
-/**
- * Token budget used by the context manager for a single agent.
- *
- * @public
- */
-interface ContextBudget {
-    maxTokens?: number;
-    /**
-     * Either a token count or a list of token strings extracted from source
-     * content. Normalized to `<tokens>` in golden comparisons.
-     */
-    usedTokens?: number | string[];
-}
-/**
- * Result of `agent.context.snapshot()`. Public and secret-free by design — safe
- * to log and persist. Raw secrets, local absolute paths, and exact token values
- * are never present.
- *
- * @public
- */
-interface ContextSnapshot {
-    runtime: "local" | "cloud";
-    sources: ContextSource[];
-    budget?: ContextBudget;
-}
-/**
- * Public context manager handle exposed as `agent.context`.
- *
- * @public
- */
-interface SDKContextManager {
-    /** Inspect what the context manager actually loaded for the agent. */
-    snapshot(): Promise<ContextSnapshot>;
-}
-
-/**
- * Fork primitive public type contracts (T1.2, ADRs D110-D114).
- *
- * Extracted into a leaf type module (arch-review ADR 0001) so the public
- * `types/agent.ts` barrel can reference `ForkOptions`/`ForkResult` without
- * importing the `internal/runtime/lifecycle/fork-agent.ts` implementation — which in
- * turn imports back from `types/agent.ts`. That mutual reference created a
- * type-only `madge` cycle. These interfaces are self-contained (no SDKAgent
- * / AgentOptions references), so co-locating them here breaks the cycle with
- * no runtime change. `fork-agent.ts` re-exports them for back-compat.
- */
-/**
- * Caller-supplied fork configuration. See `forkAgentImpl`.
- *
- * @public
- */
-interface ForkOptions {
-    /**
-     * Tool subset visible to the fork. Names must match the canonical (post-repair)
-     * tool name — typically lowercase. Tools not in this set return a `tool_result`
-     * with `"Tool blocked by fork whitelist"` content (EC-H).
-     */
-    allowedTools: Set<string>;
-    /** Task prompt sent to the fork. */
-    prompt: string;
-    /** Override system prompt. Default: byte-identical inheritance from parent (D112). */
-    systemPrompt?: string;
-    /** Memory write provenance tag (D114). Default `"fork"`. */
-    forkOrigin?: string;
-}
-/**
- * Outcome of a fork run.
- *
- * @public
- */
-interface ForkResult {
-    /** Final agent response text (`undefined` when the fork produced no result). */
-    result: string | undefined;
-    /** Tool calls executed inside the fork. */
-    toolCalls: ReadonlyArray<{
-        name: string;
-        input: Record<string, unknown>;
-    }>;
-    /** Aggregate token usage reported by the run. */
-    usage: {
-        inputTokens: number;
-        outputTokens: number;
-    };
-}
-
-/**
- * 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;
-}
-/**
- * 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;
-    /** 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>;
-}
-interface SDKAgentSkills {
-    list(): Promise<ReadonlyArray<SystemPromptSkillRef>>;
-    /**
-     * SE20 — resolve a skill by name INCLUDING its body (`instructions`). Returns
-     * `undefined` when no enabled skill matches. `list()` stays lean (name +
-     * description); full bodies come only through `get`.
-     */
-    get(name: string): Promise<SDKAgentSkillDetail | undefined>;
-}
-/**
- * Public plugin metadata returned by `agent.plugins.list()`. Mirrors the
- * `.theokit/plugins/<name>/MANIFEST.json` allow-listed shape; never exposes
- * raw plugin bodies, credentials, or internal hooks.
- *
- * @public
- */
-interface SDKPluginMetadata {
-    name: string;
-    description?: string;
-}
-/**
- * Public plugin listing handle exposed as `agent.plugins`. Populated when
- * `settingSources` includes `"plugins"` OR when `plugins.enabled` is set
- * on the agent options.
- *
- * @public
- */
-interface SDKAgentPlugins {
-    list(): Promise<ReadonlyArray<SDKPluginMetadata>>;
-}
-/**
- * Artifact produced inside an agent's workspace. Cloud-only.
- *
- * @public
- */
-interface SDKArtifact {
-    path: string;
-    sizeBytes: number;
-    updatedAt: string;
-}
-/**
- * Handle returned by `Agent.create()` and `Agent.resume()`.
- *
- * @public
- */
-interface SDKAgent {
-    readonly agentId: string;
-    readonly model: ModelSelection | undefined;
-    /**
-     * Context manager for this agent. Populated when context is enabled via
-     * {@link AgentOptions.context}. See {@link SDKContextManager}.
-     */
-    readonly context?: SDKContextManager;
-    /**
-     * Provider routing inspector for this agent. Populated when at least one
-     * provider route is configured (via {@link AgentOptions.providers}, plugins,
-     * or model-implied providers). See {@link SDKProvidersManager}.
-     */
-    readonly providers?: SDKProvidersManager;
-    /**
-     * Skill listing for this agent. Populated when project-scoped skills are
-     * enabled (`settingSources: ["project"]`) or when `skills.enabled` is set.
-     * See {@link SDKAgentSkills}.
-     */
-    readonly skills?: SDKAgentSkills;
-    /**
-     * Plugin listing for this agent. Populated when project-scoped plugins are
-     * enabled (`settingSources: ["plugins"]`) or when `plugins.enabled` is set.
-     * See {@link SDKAgentPlugins}.
-     */
-    readonly plugins?: SDKAgentPlugins;
-    send(message: string | SDKUserMessage, options?: SendOptions): Promise<Run>;
-    /**
-     * SE9 — integrated structured output. Runs the normal tool loop (the tools run
-     * first) then coerces the final answer into the `output` Zod schema, returning a
-     * validated, inferred-typed object. Sugar over `Agent.generateObject` (ADR D33).
-     */
-    generate<T extends zod.ZodType>(message: string | SDKUserMessage, options: GenerateOptions<T>): Promise<GenerateRunResult<zod.z.infer<T>>>;
-    /** Fire-and-forget disposal. */
-    close(): void;
-    /** Re-read filesystem config (context, hooks, project MCP, subagents) without disposing. */
-    reload(): Promise<void>;
-    /**
-     * Async disposal. Idempotent — calling more than once is a no-op (per ADR D5).
-     * Prefer `await using agent = await Agent.create(...)` over explicit
-     * `dispose()` for resource safety.
-     */
-    dispose(): Promise<void>;
-    /**
-     * `await using` support per ADR D5. Identical semantics to `dispose()` —
-     * idempotent across both surfaces.
-     */
-    [Symbol.asyncDispose](): Promise<void>;
-    /** Cloud-only. Local returns an empty array. */
-    listArtifacts(): Promise<SDKArtifact[]>;
-    /** Cloud-only. Local throws `UnsupportedRunOperationError`. */
-    downloadArtifact(path: string): Promise<Buffer>;
-    /**
-     * Signal that prompt cache should be invalidated. By default deferred —
-     * applied at the start of the next `send()`. Pass `{ applyNow: true }` to
-     * force immediate disposal (caller must `Agent.create()` again to use).
-     *
-     * Cache invalidation is a cost regression (provider charges full price
-     * for the rebuilt cache; see ADRs D94-D95). Use sparingly and deliberately.
-     *
-     * Cloud agents: no-op (cloud runtime reconstructs state per request).
-     *
-     * @public
-     */
-    invalidateCache?(reason: string, options?: InvalidateCacheOptions): Promise<void>;
-    /**
-     * Goal-driven Ralph loop (ADRs D115-D121). Iterates `agent.send` →
-     * judge → continuation until the auxiliary judge model returns `done`,
-     * the judge fails too many times in a row, max turns are exhausted,
-     * or the caller aborts via `AbortSignal`.
-     *
-     * Yields {@link import("./goal-events.js").GoalEvent} per state
-     * transition; returns a {@link import("./goal-events.js").GoalResult}
-     * summary as the generator's final value.
-     *
-     * Cloud agents throw {@link import("../errors.js").UnsupportedRunOperationError}
-     * **synchronously** (no AsyncGenerator returned) — wrap in try/catch
-     * if you support both runtimes.
-     *
-     * Caveat: do not call `agent.dispose()` mid-iteration; the next `send`
-     * propagates the disposal error through the generator to the consumer.
-     *
-     * @public
-     */
-    runUntil?(goal?: string, options?: GoalOptions): RunUntilIterator;
-    /**
-     * Fork a short-lived sub-agent with parent's credentials + system
-     * prompt byte-identical (ADR D112 — cache hit) and a restricted tool
-     * whitelist (ADR D111 — AsyncLocalStorage isolation).
-     *
-     * Cloud agents throw {@link import("../errors.js").UnsupportedRunOperationError}.
-     *
-     * @public
-     */
-    fork?(options: ForkOptions): Promise<ForkResult>;
-    /**
-     * Drive `send` to completion across iteration-ceiling truncations (M1 Phase 3).
-     * When a `send` stops at the loop's iteration cap (`RunResult.stoppedAtIterationLimit`),
-     * this re-sends a short continuation prompt — the agent's stateful session
-     * preserves the conversation — until a genuine terminal: `done` (finished),
-     * `step_limit` (`maxRounds` exhausted), or `no_progress` (two empty rounds).
-     *
-     * Local agents only. Cloud agents throw
-     * {@link import("../errors.js").UnsupportedRunOperationError} (the cloud
-     * runtime manages its own continuation policy server-side).
-     *
-     * @public
-     */
-    runToCompletion?(message: string, options?: RunToCompletionOptions): Promise<RunToCompletionResult>;
-    /**
-     * STREAMING continuation driver (V3-4) — the streaming twin of
-     * {@link SDKAgent.runToCompletion}. Returns an `AsyncGenerator` that yields each
-     * round's {@link import("./messages.js").SDKMessage}s LIVE (for a UI), reusing the
-     * same terminal policy (`done`/`step_limit`/`no_progress` + bounded re-prompt).
-     *
-     * The {@link import("./run.js").StreamToCompletionResult} is the generator's RETURN
-     * value — read it via a manual `gen.next()` loop (`while (!res.done) res = await
-     * gen.next()` → `res.value`); a plain `for await...of` consumes the yielded
-     * messages but discards the return value.
-     *
-     * Local agents only. Cloud agents throw
-     * {@link import("../errors.js").UnsupportedRunOperationError}.
-     *
-     * @public
-     */
-    streamToCompletion?(message: string, options?: RunToCompletionOptions): AsyncGenerator<SDKMessage, StreamToCompletionResult>;
-    /**
-     * Direct API to third-party memory adapter(s) registered via
-     * `plugins: [...]` (ADR D141 / D142). Returns `null` when no adapter
-     * is registered. In multi-adapter setups `write` fans out to all;
-     * `recall` merges + dedupes; `delete` routes by `MemoryId` prefix.
-     *
-     * @public
-     */
-    memory?: AgentMemory;
-    /**
-     * Activate a personality preset for the next `send` (Hermes #26).
-     * Reserved names `"none"`, `"default"`, and `"neutral"` clear the
-     * active preset. Returns the resolved preset (or `null` when cleared).
-     *
-     * Persistence: pass `{ save: true }` to persist across process
-     * restarts (stored under `$THEOKIT_HOME/personality.json`).
-     *
-     * History: by default the conversation history is preserved across
-     * the switch. Pass `{ reset: true }` to also clear the session.
-     *
-     * Cloud agents throw {@link import("../errors.js").UnsupportedRunOperationError}.
-     *
-     * @public
-     */
-    usePersonality?(name: string, opts?: {
-        save?: boolean;
-        reset?: boolean;
-    }): Promise<PersonalityPreset | null>;
-}
-/**
- * Resolved personality preset surfaced via {@link SDKAgent.usePersonality}
- * (Hermes #26, ADRs D160-D169). Re-declared here so the public DTS bundle
- * never crosses the `internal/` path boundary. The implementation type in
- * `internal/personality/types.ts` is structurally identical.
- *
- * @public
- */
-interface PersonalityPreset {
-    readonly name: string;
-    readonly description: string | undefined;
-    readonly tools: ReadonlyArray<string> | undefined;
-    readonly model: string | undefined;
-    readonly tags: ReadonlyArray<string> | undefined;
-    readonly systemPrompt: string;
-    readonly source: "project" | "user";
-    readonly sourcePath: string;
-}
-/**
- * Options for {@link SDKAgent.invalidateCache}.
- *
- * @public
- */
-interface InvalidateCacheOptions {
-    /**
-     * When `true`, dispose the agent immediately so caller must recreate it
-     * to continue. Default `false` (deferred — applied on next `send()`).
-     */
-    applyNow?: boolean;
-}
-
 /**
  * `MemoryProvider` — kernel-facing port for the memory subsystem
  * (SDK 2.0 Phase 1 / T1.1 — Hexagonal Architecture / Ports & Adapters,
@@ -1316,6 +498,25 @@ interface ProviderTransform {
     /** A fetch to use for this provider's requests (refresh-aware / fully provider-controlled). */
     fetch?(ctx: ProviderTransformContext): typeof fetch;
 }
+/**
+ * A data-only declaration of an LLM provider: its name, HTTP dialect, auth style, base URL and
+ * fallback models. There is nothing to implement — the router selects the transport from `apiMode` —
+ * so any OpenAI- or Anthropic-compatible endpoint (Groq, Together, Fireworks, a private gateway)
+ * becomes a provider without new code.
+ *
+ * A profile does nothing by itself. Wrap it with `Provider.create(profile)` and pass the resulting
+ * plugin to `Agent.create({ plugins: [...] })`; from there you route to it with the `provider/model`
+ * id prefix or through `providers.routes`.
+ *
+ * `name` is the routing prefix and `aliases` adds alternatives to it. `envVars` lists the environment
+ * variables that may supply the credential, and `authType` says what kind of credential that is.
+ *
+ * Reach for `transform` only when static data genuinely is not enough — a provider that computes
+ * headers per request or refreshes its own token. Leaving it absent keeps the profile on the pure
+ * data path. If you do supply `headers`, note that they are spread AFTER the transport's own
+ * `authorization` and `content-type`, so returning either key replaces the base header rather than
+ * adding to it.
+ */
 interface ProviderProfile {
     name: string;
     apiMode: ApiMode;
@@ -1350,9 +551,58 @@ interface ProviderProfile {
      * Default off — only enable for routes/models known to leak (e.g. a qwen3-coder profile variant).
      */
     extractToolCallsFromContent?: boolean;
+    /**
+     * Opt-in encrypted-reasoning carry for `apiMode: "responses_api"` (usetheokit/theokit-sdk#383).
+     * When `true`, the request adds `include: ["reasoning.encrypted_content"]` and
+     * `reasoning.context: "all_turns"`, and the transport replays the ciphertext the provider returned
+     * so the model does not re-derive its chain of thought on every round of a turn.
+     *
+     * Default off, and deliberately per-profile rather than per-`apiMode`: `include` is a documented
+     * Responses-API field but `reasoning.context` is not, so a provider that validates strictly
+     * answers it with `400`. Enable it only for a backend measured to accept both — the builtin
+     * `openai-chatgpt` profile is one, because issue #383 captured OpenAI Codex sending exactly these
+     * fields to that endpoint. Ignored by every other `apiMode`.
+     */
+    encryptedReasoning?: boolean;
 }
 
+/**
+ * The fixed set of points a `"general"` plugin may attach to through `PluginContext.on`. A closed
+ * enum rather than an open string, so a plugin cannot register for a hook the loop never fires.
+ *
+ * What separates them is what the SDK does with the handler's return value, and that is the thing to
+ * settle before writing one:
+ *
+ * - `pre_tool_call` is the only VETO point. Return `{ block: true, message }` to stop the call; the
+ *   first handler that blocks wins and the remaining handlers are not consulted.
+ * - `transform_tool_result` and `transform_llm_output` are CHAINED. Each handler receives what the
+ *   previous one returned; `undefined` keeps the current value and anything else — `null` included —
+ *   replaces it.
+ * - `pre_user_send` returns `{ recalledContext }`, which the loop concatenates across handlers and
+ *   injects ahead of the user prompt.
+ * - Everything else (`post_tool_call`, `pre_llm_call`, `post_llm_call`, `on_session_start`,
+ *   `on_session_end`, `post_assistant_reply`) is fire-and-forget: the return value is DISCARDED. A
+ *   policy that needs to change a tool result belongs on `transform_tool_result` — put it on
+ *   `post_tool_call` and it quietly degrades to observation.
+ *
+ * Failure is asymmetric too. A fire-and-forget or transform handler that throws is caught, logged to
+ * stderr, and the run continues. A `pre_tool_call` handler that throws is NOT caught by the hook
+ * dispatcher, so its exception escapes into the tool-dispatch path — a permission-style handler
+ * should resolve its own errors to an explicit block rather than relying on that.
+ */
 type HookName = "pre_tool_call" | "post_tool_call" | "pre_llm_call" | "post_llm_call" | "on_session_start" | "on_session_end" | "transform_tool_result" | "transform_llm_output" | "pre_user_send" | "post_assistant_reply";
+/**
+ * What a `pre_tool_call` handler is given: the tool about to run, the arguments the model produced
+ * for it, and the identity of the run asking.
+ *
+ * `args` came from the model, not from a validated caller. A handler that gates on argument values
+ * must treat every field as untrusted and survive one that is missing or of the wrong type.
+ *
+ * `permissionMode` is the run's resolved mode — `SendOptions.permissionMode` falling back to
+ * `AgentOptions.permissionMode` — threaded here so a permission-style plugin can gate per run rather
+ * than at construction time. Absent means neither was set, and the plugin's own default applies;
+ * plugins that are not about permissions ignore it.
+ */
 interface PreToolCallContext {
     name: string;
     args: Record<string, unknown>;
@@ -1366,6 +616,19 @@ interface PreToolCallContext {
      */
     permissionMode?: PermissionMode;
 }
+/**
+ * The veto a `pre_tool_call` handler returns to stop a tool call. Returning `undefined` allows it —
+ * there is no approval value, and `block` is the literal `true`, so `{ block: false }` is not
+ * expressible and cannot be used to force a call through.
+ *
+ * The first blocking handler decides; later `pre_tool_call` handlers never run.
+ *
+ * `message` is not a log line. The loop turns the veto into a `tool_result` reading "Plugin blocked
+ * this tool call: <message>", deliberately NOT flagged as an error, so the model reads it and can
+ * choose another route instead of the run failing. Write it for the model: say what was refused and
+ * what it might do instead. It also reaches observability — as the `stderr` of a tool-completed event
+ * with exit code 126, and as the message on a `permission_denied` run event.
+ */
 interface PreToolCallDecision {
     block: true;
     message: string;
@@ -1460,6 +723,18 @@ interface PostAssistantReplyContext {
     reply: string;
     agentId: string;
     runId: string;
+    /**
+     * `true` when the run that produced `reply` called at least one tool (#358).
+     *
+     * A reply produced by a tool call is not safely replayable: re-serving the text hands a later
+     * caller the RESULT of a `write_file` / HTTP POST / payment without the side effect having
+     * happened. A semantic cache must skip storing such a reply, and before this field existed it
+     * had nothing to key on and assumed `false`.
+     *
+     * Derived from the run's replayed event stream, so it counts tool calls the run actually made,
+     * not tools the agent merely has.
+     */
+    usedTools: boolean;
     memoryContext?: MemoryContext;
 }
 type HookHandler = (ctx: unknown) => unknown | Promise<unknown>;
@@ -1467,6 +742,21 @@ type CommandHandler = (args: Record<string, unknown>) => Promise<string> | strin
 interface CommandOptions {
     description?: string;
 }
+/**
+ * The registration surface passed to a `"general"` plugin's `register(ctx)`, and the plugin's only
+ * route into the agent. Outside production it is a sealed Proxy that throws when a plugin assigns a
+ * property of its own, so smuggling state onto the context fails loudly in development.
+ *
+ * `register` runs ONCE, when the plugin is registered — never per run. Anything the plugin wants to
+ * do during a turn has to be attached here as a hook; there is no later entry point. Each plugin gets
+ * its own context, so registrations stay attributable to the plugin that made them.
+ *
+ * Two things worth knowing before writing one. Commands registered here are consumed by CLI and bot
+ * wrappers only — the agent loop never dispatches them, so a plugin that ships nothing but commands
+ * has no effect on a programmatic run. And `on` drops a handler that is not a function, with a
+ * warning on stderr rather than an error at registration: the gentler failure, and the easier one to
+ * miss.
+ */
 interface PluginContext {
     /** Register a custom tool. Equivalent to passing in `AgentOptions.tools`. */
     registerTool(tool: CustomTool): void;
@@ -1481,6 +771,30 @@ interface BasePlugin {
     name: string;
     version: string;
 }
+/**
+ * Memory provider factory shape (ADR D141). Returns a `MemoryAdapter`
+ * (sync) or a Promise resolving to one (lazy HTTP probe / config load).
+ *
+ * Adapters live in `@theokit-memory-*` packages; the SDK never imports
+ * them. Factory rejection is caught by the plugin manager and surfaced
+ * as `ConfigurationError(code: "plugin_factory_failed")` (EC-F) — never
+ * an unhandled rejection.
+ *
+ * PUBLIC, deliberately (#335). This type is the shape a consumer must satisfy
+ * to write a memory plugin: it is named by the PUBLIC `Plugin` union below, in
+ * the `createProvider` position. It used to carry the internal-visibility JSDoc
+ * tag, which made `stripInternal` delete the declaration while the union went
+ * on referencing it — so the published `.d.ts` named a type it did not declare.
+ * Invisible under `skipLibCheck`, and an `error`-typed graph for any consumer
+ * running type-aware lint. A type reachable from a public signature is public
+ * whatever the tag says; the tag was the thing that was wrong.
+ *
+ * Do NOT write that tag's literal spelling anywhere in this comment. It is
+ * matched as text, so a JSDoc block that merely MENTIONS it is stripped exactly
+ * as if it had declared it — which is how the first attempt at this fix failed,
+ * with a build error naming a symbol whose own explanation had re-hidden it.
+ */
+type MemoryProviderFactory = (cwd: string) => MemoryAdapter | Promise<MemoryAdapter>;
 type Plugin = (BasePlugin & {
     kind: "general";
     register: (ctx: PluginContext) => void | Promise<void>;
@@ -1498,12 +812,48 @@ type Plugin = (BasePlugin & {
  * @public
  */
 type SettingSource = "project" | "user" | "team" | "mdm" | "plugins" | "all";
+/**
+ * A tool the SDK declares to the model on its own initiative — not one the consumer passed in
+ * {@link AgentOptions.tools}, and not one an MCP server exposed.
+ *
+ * These three names are also the ones the SDK reserves: a custom tool may not claim them. Listing
+ * one in {@link AgentOptions.withheldBuiltinTools} both stops it being declared and releases the
+ * name, because nothing of the SDK's is occupying it any more.
+ *
+ * Named for usetheokit/theokit-sdk#381, which is the report that the catalog had no opt-out.
+ *
+ * @public
+ */
+type BuiltinToolName = "shell" | "memory_search" | "memory_get";
 /**
  * Local agent configuration.
  *
+ * TWO THINGS A LOCAL AGENT DOES BY DEFAULT, both reported as surprises (#338):
+ *
+ * 1. **A `shell` tool is always registered**, including when you pass `tools: []`. Every local
+ *    agent can therefore read any file reachable from {@link LocalOptions.cwd}. One report describes
+ *    an evaluation invalidated this way: the working directory held the benchmark's answer key, and
+ *    two transcripts show the model citing it. Deny it explicitly if that matters —
+ *    `{ tool: "shell", action: "deny" }` on a {@link PermissionEngine} rule is terminal under every
+ *    permission mode, including `bypass`. A deny rule still leaves the tool in the advertised
+ *    catalog, so the model may attempt it and be refused; to keep it out of the catalog entirely,
+ *    pass `withheldBuiltinTools: ["shell"]` on {@link AgentOptions} (usetheokit/theokit-sdk#381).
+ *
+ * 2. **Finished runs write a transcript to disk**, at `.theokit/memory/sessions/<runId>.md` under
+ *    the workspace `cwd`, with the full prompt and reply. This happens with no `memory` config and
+ *    with `settingSources: []` — it is what `memory_search({ corpus: "sessions" })` reads. Opt out
+ *    with `memory: { enabled: false }`, which suppresses the write entirely
+ *    (usetheokit/theokit-sdk#382). Leaving `memory`
+ *    unset still writes, so if the workspace is a git repository, add `.theokit/` to `.gitignore`:
+ *    one report describes a transcript reaching a public repo before it was noticed.
+ *
  * @public
  */
 interface LocalOptions {
+    /**
+     * Workspace root(s). Also the reach of the always-present `shell` tool — see the note on
+     * {@link LocalOptions}, and the transcript written under `.theokit/memory/sessions/` here.
+     */
     cwd?: string | string[];
     settingSources?: SettingSource[];
     sandboxOptions?: {
@@ -1765,8 +1115,11 @@ interface MemorySettings {
  * 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`.
+ * `@opentelemetry/api` is an OPTIONAL peer dependency — declared, so your package manager can
+ * tell you the version range, and not installed for you. Without it, telemetry is a NO-OP even
+ * when `enabled: true`: the tracer is loaded lazily inside a try/catch, so nothing throws and
+ * nothing is recorded. A run that reports no spans with `enabled: true` is almost always this,
+ * not a misconfigured collector.
  *
  * @public
  */
@@ -1896,6 +1249,32 @@ interface AgentOptions {
      * See {@link CustomTool}.
      */
     tools?: CustomTool[];
+    /**
+     * Builtin tools this agent must NOT declare to the model. Absent or empty ⇒ every builtin the
+     * rest of the configuration would register is declared, exactly as before this option existed.
+     *
+     * WHY WITHHOLDING IS NOT THE SAME AS DENYING. A consumer that cannot allow `shell` — because it
+     * reaches outside their own sandbox scope — can already refuse the call in a `pre_tool_call` hook
+     * or with a {@link PermissionEngine} deny rule. That stops the execution and pays for the offer
+     * twice over: the schema rides in EVERY request of EVERY round (measured at 267 characters for
+     * `shell`, 1,462 for `memory_search` + `memory_get` together — usetheokit/theokit-sdk#381), and
+     * the model can spend a whole round discovering a refusal it had no way to anticipate. Declaring
+     * a tool that is guaranteed to be refused is the wrong shape; withholding removes it from the
+     * catalog, so the model is never offered what it cannot have.
+     *
+     * WITHHOLDING RELEASES THE NAME. `withheldBuiltinTools: ["shell"]` lets {@link AgentOptions.tools}
+     * declare a tool called `shell` without the `tool_reserved_name` error — the reservation exists to
+     * stop a collision with the SDK's own tool, and there is no longer one to collide with. Every
+     * builtin still declared stays reserved.
+     *
+     * This governs DECLARATION, not authorization. A withheld builtin is simply absent from the
+     * catalog: a model that invents the name anyway gets `Unknown tool <name>` (exit 127) rather than
+     * an execution, but nothing here evaluates a policy. Keep the deny rule if you need one that a
+     * per-send `tools` override cannot reopen.
+     *
+     * @public
+     */
+    withheldBuiltinTools?: readonly BuiltinToolName[];
     /**
      * SE37 — opt-in reasoning. When `true`, the agent gets a chain-of-thought
      * preamble prepended to its system prompt AND the `think` reasoning tool
@@ -2171,6 +1550,12 @@ interface AgentDescription {
 /**
  * Options for `Agent.list()`.
  *
+ * `limit`/`cursor` paginate (B-115): a `limit` bounds the page and, when more agents remain,
+ * `ListResult.nextCursor` is set — pass it back as `cursor` for the next page. Omitting `limit`
+ * returns every matching agent in one page, unpaginated, exactly as before (M107 declared imposing
+ * pagination order unconditionally a breaking change to every caller's observed order; pagination
+ * here is opt-in and only reorders the page it returns, never the unlimited default).
+ *
  * @public
  */
 type ListAgentsOptions = {
@@ -2183,13 +1568,19 @@ type ListAgentsOptions = {
     cwd?: string;
 } | {
     runtime: "cloud";
-    prUrl?: string;
+    /**
+     * Hide archived agents unless `true`. Default `false` (hidden) — B-115, this used to be
+     * accepted and silently ignored; every archived agent was always included.
+     */
     includeArchived?: boolean;
     apiKey?: string;
 });
 /**
  * Options for `Agent.get()`.
  *
+ * `cwd` (default `process.cwd()`) selects which workspace's on-disk registry to hydrate before the
+ * lookup — same rule `Agent.list` uses (B-115; this used to be accepted and silently ignored).
+ *
  * @public
  */
 interface GetAgentOptions {
@@ -2199,18 +1590,22 @@ interface GetAgentOptions {
 /**
  * Options for `Agent.listRuns()`.
  *
+ * `cwd` (default `process.cwd()`) hydrates that workspace's registry before validating the agent
+ * exists — same rule as `Agent.get` (B-115). `limit`/`cursor` paginate the SAME way as
+ * `Agent.list` — see its doc — except no reordering is ever needed: a single agent's runs are
+ * already returned in the stable order they were created.
+ *
+ * B-115 — `runtime` removed 2026-08-19. A single `agentId` already pins exactly one runtime;
+ * filtering an already-single-agent's runs by runtime filtered nothing and was never checked.
+ *
  * @public
  */
-type ListRunsOptions = {
-    limit?: number;
-    cursor?: string;
-} & ({
-    runtime?: "local";
+interface ListRunsOptions {
     cwd?: string;
-} | {
-    runtime: "cloud";
     apiKey?: string;
-});
+    limit?: number;
+    cursor?: string;
+}
 /**
  * Options for `Agent.getRun()`. Cloud requires the parent `agentId`.
  *
@@ -2243,4 +1638,4 @@ interface ListResult<T> {
     nextCursor?: string;
 }
 
-export { type MemoryProviderHandle as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type BudgetCheck as D, type BudgetTotal as E, type BudgetUsageEvent as F, type GetAgentOptions as G, type CloudEnv as H, type InlineSkill as I, type JudgeResult as J, type CloudRepo as K, type LocalOptions as L, type MemorySettings as M, type ContextBudget as N, type ContextManagerKind as O, type ProviderRoutingSettings as P, type ContextSnapshot as Q, type ContextSource as R, type SystemPromptResolver as S, type ContextSourceStatus as T, type CreateSkillSpec as U, type HookName as V, type InvalidateCacheOptions as W, type MemoryAdapter as X, type MemoryAdapterCapabilities as Y, type MemoryContext as Z, type MemoryFact as _, type AgentDefinition as a, type MemoryProviderInitOptions as a0, type MemoryRevision as a1, type MemoryToolSchema as a2, type MemoryTurnMessage as a3, type PersonalityPreset as a4, type PluginContext as a5, type PostAssistantReplyContext as a6, type PostToolCallContext as a7, type PreToolCallContext as a8, type PreUserSendContext as a9, type ToolCallSummary as aA, type ToolResultTransformContext as aB, type TransformContext as aC, type Verdict as aD, type PreUserSendResult as aa, type ProviderCapability as ab, type ProviderRoute as ac, type ProviderTransform as ad, type ProviderTransformContext as ae, type RecordSessionSummaryArgs as af, type ResolvedProviderRoute as ag, type RunUntilIterator as ah, type SDKAgentPlugins as ai, type SDKAgentSkillDetail as aj, type SDKAgentSkills as ak, type SDKArtifact as al, type SDKContextManager as am, type SDKPluginMetadata as an, type SDKProvidersManager as ao, type SessionLifecycleContext as ap, type SessionRecord as aq, type SessionStore as ar, type SettingSource as as, Skill as at, type SkillsResolver as au, type SkillsResolverContext as av, type SystemPromptContext as aw, type SystemPromptMemoryFact as ax, type SystemPromptSkillRef as ay, type TelemetrySettings as az, type ContextSettings as b, type PluginsSettings as c, type SkillsSettings as d, type SDKAgent as e, type ListAgentsOptions as f, type ListResult as g, type SDKAgentInfo as h, type ListRunsOptions as i, type GetRunOptions as j, type AgentOperationOptions as k, type AgentDescription as l, type Plugin as m, type ProviderProfile as n, type GoalOptions as o, type GoalEvent as p, type GoalResult as q, type MemoryProvider as r, type MemoryId as s, type PreToolCallDecision as t, type SDKProvider as u, type ActiveMemoryPassArgs as v, type ActiveMemoryPassResult as w, type AgentMemory as x, type AgentSubagentDescription as y, type AgentToolDescription as z };
+export { type SystemPromptMemoryFact as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type PluginContext as D, type PostAssistantReplyContext as E, type PostToolCallContext as F, type GetAgentOptions as G, type HookName as H, type InlineSkill as I, type PreToolCallContext as J, type PreUserSendContext as K, type LocalOptions as L, type MemorySettings as M, type PreUserSendResult as N, type ProviderTransform as O, type Plugin as P, type ProviderTransformContext as Q, type RecordSessionSummaryArgs as R, type SystemPromptResolver as S, type SessionLifecycleContext as T, type SessionRecord as U, type SessionStore as V, type SettingSource as W, Skill as X, type SkillsResolver as Y, type SkillsResolverContext as Z, type SystemPromptContext as _, type AgentDefinition as a, type TelemetrySettings as a0, type ToolCallSummary as a1, type ToolResultTransformContext as a2, type TransformContext as a3, type SkillsSettings as b, type ListAgentsOptions as c, type ListResult as d, type SDKAgentInfo as e, type ListRunsOptions as f, type GetRunOptions as g, type AgentOperationOptions as h, type AgentDescription as i, type ProviderProfile as j, type MemoryProvider as k, type PreToolCallDecision as l, type ActiveMemoryPassArgs as m, type ActiveMemoryPassResult as n, type AgentSubagentDescription as o, type AgentToolDescription as p, type BudgetCheck as q, type BudgetTotal as r, type BudgetUsageEvent as s, type BuiltinToolName as t, type CloudEnv as u, type CloudRepo as v, type CreateSkillSpec as w, type MemoryProviderFactory as x, type MemoryProviderHandle as y, type MemoryProviderInitOptions as z };