@theokit/sdk 0.0.0-compat-580-20260905204608

package/dist/internal/local-agent/local-agent-bootstrap.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `LocalAgent` constructor bootstrap helpers (extracted for G8 ≤400 LoC).
+ *
+ * Each helper builds one optional submanager from `AgentOptions` and
+ * the resolved workspace cwd. The constructor itself stays focused on
+ * the agentId / model wiring; submanager bootstrap is delegated here.
+ *
+ * @internal
+ */
+import { ProvidersManagerImpl } from "../runtime/config/providers-manager.js";
+import { FileContextManager } from "../runtime/context/context-manager.js";
+import { type PluginMetadata, PluginsManager } from "../runtime/plugin-loader/plugins-manager.js";
+import { type SkillsHandle, SkillsManager } from "../runtime/skills/skills-manager.js";
+export declare function registerLocalAgent(args: {
+    agentId: string;
+    model: ModelSelection | undefined;
+    options: AgentOptions;
+    workspaceCwd: string;
+}): void;
+export interface BootstrappedSubmanagers {
+    context?: FileContextManager;
+    providers?: ProvidersManagerImpl;
+    skillsManager?: SkillsManager;
+    skills?: SkillsHandle;
+    pluginsManager?: PluginsManager;
+    plugins?: {
+        list: () => Promise<PluginMetadata[]>;
+    };
+}
+interface BootstrapArgs {
+    options: AgentOptions;
+    workspaceCwd: string;
+    settingSourcesIncludeProject: boolean;
+    settingSourcesIncludePlugins: boolean;
+}
+export declare function bootstrapSubmanagers(args: BootstrapArgs): BootstrappedSubmanagers;
+export {};

package/dist/internal/local-agent/local-agent-capabilities.d.ts

@@ -0,0 +1,38 @@
+/**
+ * What a local agent cannot do, answered without throwing.
+ *
+ * `SDKAgent` is one interface over two runtimes, and a local agent genuinely has no artifacts — the
+ * LSP finding this closes is that `downloadArtifact` rejected with `UnsupportedRunOperationError`
+ * and nothing let a caller ASK first. `supports`/`unsupportedReason` are that question, and they
+ * live here rather than on the class because the answer is a property of the RUNTIME, not of any
+ * particular agent instance: it needs no field, no lock and no session.
+ *
+ * Kept a module and not a static on the class so `local-agent.ts` carries one fewer concern; the
+ * class keeps two one-line delegations, which is the surface `SDKAgent` requires.
+ */
+import type { AgentOperation, SDKArtifact } from "../../types/sdk-agent.js";
+/** Whether the local runtime implements `operation`. */
+export declare function localAgentSupports(operation: AgentOperation): boolean;
+/** Why `operation` is unavailable, or `undefined` when it is available. */
+export declare function localAgentUnsupportedReason(operation: AgentOperation): string | undefined;
+/** A local agent has no artifacts, so the list is empty rather than an error. */
+export declare function localAgentListArtifacts(): Promise<SDKArtifact[]>;
+/**
+ * Downloading one IS an error, and a typed one — the asymmetry is deliberate. An empty list is a
+ * true answer about a local agent; a download is a request the runtime cannot honour, and
+ * `supports("downloadArtifact")` is how a caller finds that out without provoking the rejection.
+ */
+export declare function localAgentDownloadArtifact(): Promise<Buffer>;
+/**
+ * The four answers as one object, so a consumer imports one name.
+ *
+ * Not decoration: `local-agent.ts` sits against a 400-line budget and a four-name import block costs
+ * five lines there. It is also the shape this package already uses for a namespace of related
+ * functions — see the static-namespace convention in `tests/lint/static-namespace-names-its-product.test.ts`.
+ */
+export declare const localAgentCapabilities: {
+    readonly supports: typeof localAgentSupports;
+    readonly unsupportedReason: typeof localAgentUnsupportedReason;
+    readonly listArtifacts: typeof localAgentListArtifacts;
+    readonly downloadArtifact: typeof localAgentDownloadArtifact;
+};

package/dist/internal/local-agent/local-agent-dispatch.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Dispatch helpers extracted from `LocalAgent` to keep its file under
+ * G8 (≤400 LoC). Builds the args for real-LLM and fixture run paths.
+ *
+ * @internal
+ */
+import type { AgentDefinition, AgentOptions, ModelSelection } from "../../types/agent.js";
+import type { Run, SDKUserMessage, SendOptions } from "../../types/run.js";
+import type { MemoryToolSpec } from "../agent-loop/types.js";
+import type { PersonalityPreset } from "../personality/types.js";
+import type { PluginManager } from "../plugins/manager.js";
+import type { HooksExecutor } from "../runtime/hooks/hooks-executor.js";
+import type { MemoryFact } from "../runtime/memory-glue/memory-store.js";
+import { createRealLocalRun } from "./real-local-run.js";
+export interface DispatchInputs {
+    agentId: string;
+    model: ModelSelection | undefined;
+    options: AgentOptions;
+    workspaceCwd: string;
+    hooksExecutor: HooksExecutor;
+    pluginManager: PluginManager;
+    resolvedSubagents: Record<string, AgentDefinition>;
+    settingSourcesIncludeProject: boolean;
+}
+export declare function buildRealRunOptions(args: {
+    inputs: DispatchInputs;
+    message: string | SDKUserMessage;
+    options: SendOptions;
+    systemPrompt: string | undefined;
+    priorMessages: ReadonlyArray<{
+        role: "user" | "assistant";
+        text: string;
+    }>;
+    memoryTools: ReadonlyArray<MemoryToolSpec> | undefined;
+    personalityToolWhitelist?: ReadonlyArray<string>;
+    personalityName?: string;
+}): Parameters<typeof createRealLocalRun>[0];
+export declare function createFixtureRunHelper(args: {
+    inputs: DispatchInputs;
+    message: string | SDKUserMessage;
+    options: SendOptions;
+    systemPrompt: string | undefined;
+    memoryFacts: ReadonlyArray<MemoryFact>;
+}): Promise<Run>;
+export declare function dispatchLocalRun(args: {
+    inputs: DispatchInputs;
+    message: string | SDKUserMessage;
+    sendOptions: SendOptions;
+    systemPrompt: string | undefined;
+    memoryFacts: ReadonlyArray<MemoryFact>;
+    priorMessages: ReadonlyArray<{
+        role: "user" | "assistant";
+        text: string;
+    }>;
+    memoryTools: ReadonlyArray<MemoryToolSpec> | undefined;
+    activePreset: PersonalityPreset | undefined;
+}): Promise<Run>;

package/dist/internal/local-agent/local-agent-invalidate.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/local-agent/local-agent-lifecycle.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Lifecycle helpers for {@link import("./local-agent.js").LocalAgent} — writer-lease
+ * acquisition/release, `dispose()` teardown, and `reload()` re-discovery.
+ *
+ * Extracted from `local-agent.ts` to keep that file under the 400-LoC guard (G8),
+ * mirroring `local-agent-runtime-extensions.ts`. The grouping is by CONCEPT, not by
+ * leftover: all four helpers below answer "what does this agent own outside a single
+ * run, and how is it handed back?" — the store lease, the pooled MCP clients, the
+ * pending disk writes, and the file-discovered submanagers.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/local-agent/local-agent-memory-direct.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `agent.memory` direct API implementation (T2.2, ADR D141 / D142).
+ *
+ * Builds an `AgentMemory` impl over whichever third-party adapters
+ * the `PluginManager` aggregated. Lazy-resolves the adapter list on
+ * first access (EC-I: `initialize()` fires exactly once on first
+ * write/recall). Multi-adapter fan-out for writes; merge + dedupe by
+ * content for recalls.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/local-agent/local-agent-memory-hooks.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Memory hook wiring for `LocalAgent.sendLocked` (T2.1, ADRs D141 / D145).
+ *
+ * Two helpers extracted to keep `local-agent.ts` under G8 (≤400 LoC):
+ *  - `applyPreUserSendHook` — fires `pre_user_send`, caps recalled context
+ *    at `maxRecallContextBytes` (EC-A), injects `<memory-context>` fence.
+ *  - `wrapRunWithPostReplyHook` — Proxy-wraps the Run so
+ *    `post_assistant_reply` fires once after `wait()` (fire-and-forget,
+ *    errors → stderr per EC-O).
+ *
+ * @internal
+ */
+import type { Run, SDKUserMessage, SendOptions } from "../../types/run.js";
+import type { PluginManager } from "../plugins/manager.js";
+/**
+ * EC-A + EC-G + EC-H: fire `pre_user_send` hooks, cap recalled context,
+ * and prepend it as a `<memory-context>` fence around the original
+ * user text. Returns the (possibly wrapped) message preserving the
+ * `string | SDKUserMessage` shape the caller passed in.
+ */
+export declare function applyPreUserSendHook(args: {
+    pluginManager: PluginManager;
+    agentId: string;
+    options: AgentOptions;
+    original: string | SDKUserMessage;
+    userText: string;
+    sendOptions: SendOptions;
+}): Promise<string | SDKUserMessage>;
+/**
+ * Wrap a `Run` so `post_assistant_reply` fires once after `wait()`.
+ * Fire-and-forget — errors are surfaced to stderr (EC-O) so the caller
+ * never blocks on memory sync. Returns a Proxy preserving all other
+ * Run methods (stream, cancel, conversation).
+ */
+export declare function wrapRunWithPostReplyHook(args: {
+    pluginManager: PluginManager;
+    agentId: string;
+    options: AgentOptions;
+    run: Run;
+    userText: string;
+}): Run;

package/dist/internal/local-agent/local-agent-memory-provider.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `createLocalAgentMemoryProvider` — bridges the legacy LocalAgentMemory
+ * rich impl (sdk-core's internal/memory/* subsystem) to the
+ * MemoryProvider port (SDK 2.0 Phase 1 physical Stage 2a — iter 19+).
+ *
+ * Goal: ONE memory path inside the kernel. Today there are TWO:
+ *   1. Legacy via `LocalAgentMemory` (when consumer didn't pass memoryProvider)
+ *   2. Port via `MemoryProvider` (when consumer passed memoryProvider in T1.3)
+ *
+ * This adapter wraps path 1 as a MemoryProvider, so the kernel can use
+ * the port uniformly. Stage 2b will refactor LocalAgent.send() to use
+ * the port + this adapter as default. Stage 3 will move the internal/
+ * memory/* sources to sdk-memory + ship a richer LanceDB-backed
+ * provider replacing this adapter.
+ *
+ * Why a separate file (not modifying LocalAgentMemory):
+ *   - Preserves LocalAgentMemory's existing public API for callers that
+ *     haven't migrated to the port yet.
+ *   - Adapter pattern: the rich logic stays where it is; the adapter
+ *     translates between LocalAgentMemory's signature and the port's.
+ *   - Allows incremental migration: kernel call sites move one at a
+ *     time from `memoryGlue.X()` direct calls to `provider.X(handle)`
+ *     calls.
+ *
+ * @internal — sdk-core's bridging glue. Replaced by sdk-memory rich impl
+ * in Stage 3.
+ */
+import type { MemoryProvider } from "../runtime/memory-glue/memory-provider.js";
+import type { TelemetryHandle } from "../telemetry/tracer.js";
+/**
+ * Options for `createLocalAgentMemoryProvider`. Mirrors what
+ * `LocalAgentMemory`'s constructor needs.
+ */
+export interface LocalAgentMemoryProviderOptions {
+    /** AgentOptions slice — required for memory subsystem config (cfg.memory). */
+    readonly agentOptions: AgentOptions;
+    /** Workspace cwd — used for `.theokit/memory/` paths. */
+    readonly workspaceCwd: string;
+    /** Agent id — required for per-agent cache + telemetry. */
+    readonly agentId: string;
+    /** Telemetry handle (optional) — forwarded to active-memory recall. */
+    readonly telemetry?: TelemetryHandle;
+}
+/**
+ * Build a `MemoryProvider` whose lifecycle methods delegate to an
+ * underlying `LocalAgentMemory` instance.
+ *
+ * Mapping:
+ *   - `init()`        → constructs LocalAgentMemory + warms tool cache via ensureTools()
+ *   - `buildTools()`  → wraps ensureTools() result, renaming `execute` to `handler`
+ *   - `runActivePass()` → calls runActiveMemoryIfEnabled() with synthesized args;
+ *                         returns the summary as `systemPromptAdditions`
+ *   - `sync()`        → calls syncIfReady()
+ *   - `dispose()`     → no-op (LocalAgentMemory's caches are per-agent + GC'd
+ *                       when the agent is GC'd)
+ */
+export declare function createLocalAgentMemoryProvider(opts: LocalAgentMemoryProviderOptions): MemoryProvider;

package/dist/internal/local-agent/local-agent-memory.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/local-agent/local-agent-personality-extensions.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Personality-preset runtime extensions for {@link LocalAgent}.
+ *
+ * Extracted from `local-agent.ts` to keep that file under the 400-LoC
+ * guard (G8). The functions here implement the personality-related
+ * behaviour declared by ADRs D160-D168:
+ *
+ * - `resolveActivePersonalityPreset` — read the active preset honoring
+ *   the fork ALS snapshot (D168 / EC-A).
+ * - `ensurePersonalityRegistryIfNeeded` — lazy-load registry when ANY
+ *   slug is active.
+ * - `applyPersonalityOverlay` — overlay preset body on the base prompt.
+ * - `localAgentUsePersonality` — the full `Agent.usePersonality` flow:
+ *   fork-scope no-op, registry lazy-load, then delegate to
+ *   `performPersonalitySwitch` under the per-agent send mutex (EC-E).
+ *
+ * @internal
+ */
+import { PersonalityRegistry } from "../personality/registry.js";
+import type { PersonalityStore } from "../personality/store.js";
+/**
+ * What `localAgentUsePersonality` needs from the agent — the narrow-target shape
+ * `LocalAgentDisposeTarget` established in `local-agent-lifecycle.ts`.
+ *
+ * It replaced an eleven-member args bag carrying TWO callbacks bound straight back to the caller's
+ * own members: `invalidateCache` and an `onRegistryLoaded` whose only job was to write
+ * `personalityRegistry` back. An extraction that hands its dependencies back as closures has
+ * relocated text without reducing coupling — the defect this file's own sibling avoids by taking
+ * the agent. `personalityRegistry` is mutable here on purpose: the lazy load assigns it directly,
+ * which is what the write-back callback was simulating.
+ *
+ * `disposed` is deliberately absent: the CALLER owns that flag and checks it, the same division
+ * `disposeLocalAgentSession` states — "the caller owns the `disposed` flag (idempotence guard)".
+ * Reaching into a private field to re-ask a question the caller already answered is what forced the
+ * bag to carry it.
+ */
+export interface LocalAgentPersonalityTarget {
+    readonly agentId: string;
+    readonly workspaceCwd: string;
+    readonly personalityStore: PersonalityStore;
+    personalityRegistry: PersonalityRegistry | undefined;
+    invalidateCache(reason: string): Promise<void>;
+}

package/dist/internal/local-agent/local-agent-runtime-extensions.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Background-work runtime extensions for {@link LocalAgent} (T4.2 + T4.3).
+ *
+ * Extracted from `local-agent.ts` to keep that file under the 400-LoC
+ * guard (G8). The two helpers below implement
+ * `LocalAgent.runUntil(goal, options)` and `LocalAgent.fork(options)`
+ * by lazy-importing the implementation modules and resolving
+ * `Agent.create` through the DI registry (see
+ * `agent-factory-registry.ts` for the cycle-avoidance rationale).
+ *
+ * @internal
+ */
+export {};

package/dist/internal/local-agent/local-agent-send.d.ts

@@ -0,0 +1,42 @@
+import type { SDKUserMessage, SendOptions } from "../../types/run.js";
+import type { MemoryToolSpec } from "../agent-loop/types.js";
+import type { MemoryProvider } from "../runtime/memory-glue/memory-provider.js";
+import type { MemoryFact } from "../runtime/memory-glue/memory-store.js";
+/**
+ * What one send needs assembled into a system prompt. The port took the same five values
+ * positionally, so the binding in `LocalAgent` read `(ut, bp, mf, ams, cp) => …` — five
+ * abbreviations relaying into a six-argument helper call.
+ */
+export interface SendAssemblyRequest {
+    readonly userText: string;
+    readonly baseSystemPrompt: string | undefined;
+    readonly memoryFacts: ReadonlyArray<MemoryFact>;
+    readonly activeMemorySummary: string | undefined;
+    readonly contextPaths: readonly string[] | undefined;
+}
+/**
+ * The arguments of one dispatch, as a record.
+ *
+ * They were seven positional parameters declared TWICE — here and on `LocalAgent.dispatchRun` — kept
+ * in step by hand behind a `jscpd:ignore` pair, and relayed by
+ * `(msg, o, sp, mf, pm, mt, mp) => this.dispatchRun(msg, o, sp, mf, pm, mt, mp)`. The abbreviations
+ * were not carelessness: the arrow is one line because of the 400-LoC file budget, and a one-line
+ * arrow has no room for real names. `pm` there is `priorMessages` while `pm` in a sibling lambda two
+ * declarations up is `pluginManager`.
+ *
+ * One named type: the relay becomes `(args) => this.dispatchRun(args)`, which fits on one line
+ * without abbreviating anything, and the duplicate declaration — with the suppression that hid it —
+ * is gone.
+ */
+export interface DispatchRunArgs {
+    readonly message: string | SDKUserMessage;
+    readonly options: SendOptions;
+    readonly systemPrompt: string | undefined;
+    readonly memoryFacts: ReadonlyArray<MemoryFact>;
+    readonly priorMessages: ReadonlyArray<{
+        role: "user" | "assistant";
+        text: string;
+    }>;
+    readonly memoryTools: ReadonlyArray<MemoryToolSpec> | undefined;
+    readonly memoryProviderOverride?: MemoryProvider | undefined;
+}

package/dist/internal/local-agent/local-agent-task-wrap.d.ts

@@ -0,0 +1,11 @@
+/**
+ * T3.2 — register a `Run` from `LocalAgent.send({ task: ... })` as a
+ * Task in the observable registry. Extracted from `local-agent.ts`
+ * to keep that file under the 400-LoC quality gate (G8).
+ *
+ * @internal
+ */
+export declare function registerRunAsTask(run: Run, agentId: string, taskOpt: true | {
+    id?: string;
+    meta?: Record<string, unknown>;
+}, userText: string): void;

package/dist/internal/local-agent/local-agent.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/local-agent/local-option-keys.d.ts

@@ -0,0 +1,2 @@
+/** The declared surface, for the lint that keeps it in step with the interface. */
+export declare function knownLocalOptionKeys(): ReadonlySet<string>;

package/dist/internal/local-agent/local-run.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/local-agent/mcp-pool.d.ts

@@ -0,0 +1,43 @@
+/**
+ * M77 — session-scoped MCP client pool.
+ *
+ * `buildMcpMap` (`real-local-run.ts`) builds a fresh `McpClient` on every run, so each `send` pays
+ * spawn + handshake again: 193 / 138 / 134 ms per turn, measured. The runtime is therefore anchored at
+ * the session and REPLACED rather than rebuilt.
+ *
+ * theokit#155: pooling the client OBJECT was never enough — the turn also has to stop closing what
+ * it does not own. See `runOwnsMcpClients` (`real-local-run.ts`) and the idempotent
+ * `StdioMcpClient.initialize()`.
+ *
+ * Generic over the client type on purpose: this file knows about keys, reuse and idleness, and
+ * nothing about MCP. That keeps it unit-testable without spawning a server, and keeps `McpClient`'s
+ * reconnect machinery (`internal/mcp/client.ts:165-171` — `dropped` + a single shared
+ * `reconnectPromise` with full-jitter backoff) exactly where it already lives. The pool must not
+ * reimplement surviving a dead server; it must not throw that capability away either.
+ *
+ * @internal
+ */
+export declare class McpClientPool<C> {
+    private readonly entries;
+    private readonly idleTtlMs;
+    private readonly now;
+    constructor(options?: McpClientPoolOptions);
+    /**
+     * Return the pooled client for `(sessionId, serverName, config)`, creating it via `factory` on
+     * first use. Every call refreshes idleness — the TTL measures time SINCE LAST USE, not age.
+     *
+     * Synchronous by design: `createMcpClient` is itself synchronous (the handshake happens later, on
+     * `initialize`), so there is no `await` between the lookup and the insert and two concurrent runs
+     * in the same session cannot both miss the cache.
+     */
+    acquire(sessionId: string, serverName: string, config: unknown, factory: () => C): C;
+    /**
+     * Close and forget every client of ONE session. Scoped deliberately: clearing the whole map would
+     * tear down the servers of every concurrent conversation.
+     */
+    disposeSession(sessionId: string, close: (client: C) => void): void;
+    /** Close and forget every client idle for longer than the TTL. */
+    reapIdle(close: (client: C) => void): void;
+    /** Live pooled-client count — for observability and tests. */
+    size(): number;
+}

package/dist/internal/local-agent/real-local-run-mcp.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The MCP client pool behind `mcpLifecycle: 'session'`, and who owns a run's clients.
+ *
+ * MOVED HERE 2026-09-02 from `real-local-run.ts`. It is a process-wide resource with its own
+ * lifecycle rules — acquisition, idle reaping, per-session disposal — living inside a file whose
+ * other five concerns were about assembling one run. Ownership (`runOwnsMcpClients`) is derived in
+ * ONE place so `buildMcpMap` and the run's `finally` cannot disagree about who releases a client;
+ * keeping that guarantee is the reason the two functions travel together.
+ *
+ * @internal
+ */
+import { type McpClient } from "../mcp/client.js";
+import type { CreateRealLocalRunOptions } from "./real-local-run-options.js";
+/** M77 — release one session's pooled MCP clients. Called from `LocalAgent.dispose()`. */
+export declare function disposeSessionMcpClients(agentId: string): void;
+/**
+ * theokit#155 — does THIS RUN own the MCP clients it was handed?
+ *
+ * Under the default `'run'` lifecycle the client is built for this send and dies with it, so the
+ * run closes it. Under `'session'` the pool owns it: closing it at the end of the turn SIGTERMs the
+ * child process, and the next turn spawns a new one — which is exactly why the option measured
+ * 0 ms of savings. Ownership is derived here, once, so `buildMcpMap` and the run's `finally` cannot
+ * disagree about who releases the resource.
+ */
+export declare function runOwnsMcpClients(agentOptions: AgentOptions): boolean;
+export declare function buildMcpMap(options: CreateRealLocalRunOptions): Map<string, McpClient>;

package/dist/internal/local-agent/real-local-run-options.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What one local run is built from.
+ *
+ * Its own module because `real-local-run.ts` and the two files split out of it —
+ * `real-local-run-provider.ts` and `real-local-run-mcp.ts` — all take it, and having any of them own
+ * it makes the other two import back into it. madge caught exactly that: the first version of the
+ * split put the interface in `real-local-run.ts` and produced a `provider -> run -> provider` pair.
+ *
+ * A type-only cycle erases at compile and breaks no build, but it is the same design statement in
+ * the wrong direction as any other, and this repo has a rule about it (`.dependency-cruiser.cjs`
+ * G7a, and `types/agent-prims.ts`, which exists for the identical reason).
+ *
+ *
+ * `SessionMessage` comes from `types/session-message.ts` and NOT from the `internal/session/` barrel:
+ * that barrel reaches back here through `compact-session.ts`, and madge reported the loop the moment
+ * this file existed. Importing the declaring module instead of the barrel is the cheaper half of the
+ * same lesson `types/agent-prims.ts` records.
+ *
+ * NAMED `-options` RATHER THAN `-types`: `tests/lint/types-module-naming.test.ts` refuses a
+ * `X-types.ts` in a folder with no bare `types.ts` to distinguish it from, on the grounds that the
+ * prefix then carries no information. The gate caught this file on its first commit, which is what
+ * it is for.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/local-agent/real-local-run-provider.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Provider inference helpers for the real local run — extracted from
+ * `real-local-run.ts` to keep it within the G8 LoC budget and give the
+ * "which provider?" heuristics one cohesive home.
+ *
+ * The precedence diagnostic joined them for the same two reasons: it answers the same question
+ * ("which provider, and was that what the caller asked for?"), and adding it inline pushed
+ * `real-local-run.ts` to 411 LoC against the 400 budget. The gate asked for a split and this is
+ * where the split already lives.
+ *
+ * @internal
+ */
+export declare function warnProviderPrecedenceOnce(asked: string | undefined, used: string): void;

package/dist/internal/local-agent/real-local-run-tools.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Custom-tool assembly for the real local run (extracted from `real-local-run.ts`
+ * for the G8 LoC budget — SRP: everything that builds the effective tool catalog
+ * for a run lives here).
+ *
+ * Merges, in order: caller/agent `tools`, declarative subagent delegation tools
+ * (file-based + inline), plugin tools, and — SE37 — the internal `think` tool when
+ * `reasoning: true` (guarded against a native reasoning model). Binds parent
+ * credentials onto delegation tools and applies the personality whitelist.
+ *
+ * @internal
+ */
+import type { AgentDefinition, AgentOptions, BuiltinToolName, CustomTool, ModelSelection } from "../../types/agent.js";
+import type { CustomToolSpec } from "../agent-loop/types.js";
+/**
+ * Resolve the tool-catalog slice of `AgentLoopInputs` for this run: which custom tools the loop
+ * declares, and which SDK builtins it must NOT.
+ *
+ * Precedence for the custom half (matches the mcpServers semantics — "fully replaces, not merged"):
+ *  - `sendOptions.tools === undefined` → fall back to `agentOptions.tools`
+ *  - `sendOptions.tools = []`         → explicitly clear (no custom tools)
+ *  - `sendOptions.tools = [t1, ...]`  → use exactly these for this run
+ *
+ * usetheokit/theokit-sdk#381 added the builtin half, and it is why this is no longer named for
+ * custom tools alone. It rides here rather than at the call site because the withhold list is
+ * part of the same answer — what this run declares to the model — and because a run that
+ * withholds nothing must produce the same `AgentLoopInputs` it produced before the option existed,
+ * which is easiest to guarantee where the rest of the catalog is already assembled.
+ *
+ * Note the two halves are independent: an agent with no custom tools at all can still withhold a
+ * builtin, so the "no tools" early return carries the withhold list out with it.
+ *
+ * ONE options record rather than eight positional parameters. Five of the eight were optional or
+ * nullable in adjacent slots — `ReadonlyArray<string> | undefined`, `string`, `string | undefined`,
+ * `Record | undefined`, `ModelSelection | undefined` — compatible enough that transposing two of
+ * them compiled. The single call site was already destructuring the same `CreateRealLocalRunOptions`
+ * value field by field, so the parameter list was re-deriving a record the caller held.
+ */
+export interface RunToolCatalogInputs {
+    readonly agentOptions: AgentOptions;
+    readonly sendOptions: {
+        tools?: CustomTool[];
+    } | undefined;
+    readonly pluginManager: import("../plugins/manager.js").PluginManager | undefined;
+    readonly personalityToolWhitelist: ReadonlyArray<string> | undefined;
+    readonly agentId: string;
+    readonly personalityName: string | undefined;
+    readonly subagents: Record<string, AgentDefinition> | undefined;
+    /** The per-send override applied, NOT `agentOptions.model` — they differ on an override. */
+    readonly effectiveModel: ModelSelection | undefined;
+}
+export declare function buildRunToolCatalogInput({ agentOptions, sendOptions, pluginManager, personalityToolWhitelist, agentId, personalityName, subagents, effectiveModel, }: RunToolCatalogInputs): {
+    customTools?: ReadonlyArray<CustomToolSpec>;
+    withheldBuiltinTools?: ReadonlyArray<BuiltinToolName>;
+};

package/dist/internal/local-agent/real-local-run.d.ts

@@ -0,0 +1,4 @@
+import type { Run } from "../../types/run.js";
+export type { CreateRealLocalRunOptions } from "./real-local-run-options.js";
+import type { CreateRealLocalRunOptions } from "./real-local-run-options.js";
+export declare function createRealLocalRun(options: CreateRealLocalRunOptions): Run;

package/dist/internal/mcp/client.d.ts

@@ -0,0 +1,16 @@
+import type { McpServerConfig } from "../../types/mcp.js";
+export interface McpToolCallResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}
+export interface McpClient {
+    readonly name: string;
+    initialize(): Promise<void>;
+    listTools(): Promise<McpTool[]>;
+    callTool(name: string, args: Record<string, unknown>): Promise<McpToolCallResult>;
+    close(): Promise<void>;
+}
+export declare function createMcpClient(name: string, config: McpServerConfig, fetchImpl?: typeof fetch): McpClient;

package/dist/internal/mcp/handshake-timeout.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Which deadline applies to one MCP call.
+ *
+ * Extracted from `BaseMcpClient.timeoutFor` — where it was a private method, and therefore only
+ * reachable through integration tests that spawn child processes and race a hand-picked millisecond
+ * count against the cost of starting Node. It is a pure function of three values and now says so.
+ *
+ * @internal
+ */
+/**
+ * Floor for the `initialize` handshake, whatever `requestTimeoutMs` says.
+ *
+ * Sized against what the handshake actually pays for — spawning a child process and waiting for a
+ * server to come up — rather than against a steady-state RPC.
+ */
+export declare const HANDSHAKE_FLOOR_MS = 10000;
+export interface HandshakeTimeoutInput {
+    /** The JSON-RPC method about to be sent. */
+    readonly method: string;
+    /** Whether the client is inside its own reconnect cycle. */
+    readonly reconnecting: boolean;
+    /** The caller's `requestTimeoutMs`, already defaulted. */
+    readonly requestTimeoutMs: number;
+}
+/**
+ * The deadline for one RPC. The reconnect handshake gets a floor; everything else gets
+ * `requestTimeoutMs`.
+ *
+ * `requestTimeoutMs` sizes a STEADY-STATE request. `initialize` is not one — it is preceded by a
+ * process spawn and the server's own startup, and the caller who set a tight request budget was
+ * sizing latency, not process creation. Binding both to that number made a tight budget silently
+ * unable to CONNECT, and worse, unable to RECONNECT: `reconnect()` spawns a fresh child and calls
+ * `initialize()`, so every one of its attempts tried to fit a spawn into a steady-state budget,
+ * exhausted the loop and surfaced `mcp_disconnected` — precisely the wedge the bounded-retry loop
+ * exists to prevent.
+ *
+ * A FLOOR, not a replacement: a caller who deliberately sets a LARGER request timeout keeps it.
+ * That clause was prose until 2026-09-02 — `Math.max` could have been a bare `HANDSHAKE_FLOOR_MS`
+ * and all three integration tests stayed green. `tests/internal/mcp/handshake-timeout.test.ts` is
+ * the oracle for it now.
+ *
+ * SCOPED TO THE RECONNECT HANDSHAKE, not to the first connect, and the difference is which failure
+ * is visible. A caller whose `requestTimeoutMs` is too small to connect at ALL finds out
+ * immediately, at the call they made, and that is their explicit choice to correct — an existing
+ * test pins it (`client-timeout.test.ts`: a silent server rejects within 2s at 150ms, and a floor on
+ * first connect would make it wait the floor instead). The reconnect is the SDK's own recovery,
+ * which the caller never sized and never sees until a drop happens.
+ *
+ * A floor on every METHOD would also be wrong for a third reason: it would turn `requestTimeoutMs`
+ * into a suggestion, which is a worse defect than the one it fixes. Both halves of the condition
+ * matter — the method AND the flag — so an ordinary call mid-reconnect keeps the caller's budget.
+ */
+export declare function handshakeAwareTimeout(input: HandshakeTimeoutInput): number;