@theokit/sdk 1.5.0

package/dist/internal/runtime/cloud-payload-types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Canonical JSON contract that the SDK posts to TheoCloud at
+ * `POST /v1/agents/{id}/runs`. PaaS reads this to reconstruct the agent's
+ * tool catalog server-side (skills, plugins, hooks rules, MCP HTTP servers,
+ * subagents, providers, memory, context).
+ *
+ * Locked at `schemaVersion: "1.0"`. Adding fields is forward-compatible;
+ * removing or renaming requires a v2 ADR (see ADR D15).
+ *
+ * @internal
+ */
+export interface CloudPayloadCloud {
+    repos: ReadonlyArray<{
+        url: string;
+        startingRef?: string;
+    }>;
+    autoCreatePR?: boolean;
+}
+export interface HookRule {
+    event: string;
+    command?: string;
+    reject?: string;
+}
+export interface McpHttpRedacted {
+    type: "http";
+    url: string;
+}
+export interface McpStdioRedacted {
+    type: "stdio";
+    command: string;
+    args?: ReadonlyArray<string>;
+}
+export interface SubagentRef {
+    description?: string;
+    systemPrompt?: string;
+    model?: {
+        id: string;
+    };
+}
+export interface ProvidersRedacted {
+    routes?: ReadonlyArray<{
+        provider: string;
+        model?: string;
+    }>;
+    fallback?: ReadonlyArray<string>;
+}
+export interface MemoryPayload {
+    enabled: boolean;
+    index?: {
+        backend: "sqlite-vec" | "lance";
+        embedding?: {
+            provider: string;
+            model?: string;
+        };
+    };
+}

package/dist/internal/runtime/cloud-run.d.ts

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

package/dist/internal/runtime/cloud-tool-parity.d.ts

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

package/dist/internal/runtime/context-aggregator.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Aggregate context cap (T4.1, ADR D155).
+ *
+ * After per-file truncation, applies a second-level cap on the TOTAL
+ * size across all sources. Lower-priority sources are dropped when the
+ * sum would exceed `maxBytesTotal`. The last partially-fitting source
+ * is truncated to fit exactly into the remaining budget.
+ *
+ * EC-J: same-priority sources tie-break by absolute source path
+ * lex-ascending for deterministic ordering (prompt-cache stability).
+ *
+ * @internal
+ */
+/** Default aggregate cap (120k chars across all context files). D155. */
+export declare const DEFAULT_MAX_BYTES_TOTAL = 120000;
+export interface AggregatorSource {
+    readonly id: string;
+    readonly source: string;
+    readonly content: string;
+    readonly priority: number;
+    readonly truncated: boolean;
+}
+export interface AggregateResult {
+    readonly kept: AggregatorSource[];
+    readonly dropped: AggregatorSource[];
+}

package/dist/internal/runtime/context-discovery-runner.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Multi-format context discovery runner (T5.1, ADRs D150-D156).
+ *
+ * Walks `DEFAULT_DISCOVERY_SPECS` (or caller override), loads each
+ * spec via the appropriate parser, applies `@import` resolution where
+ * declared, and returns a flat list of `AggregatorSource[]` ready for
+ * the aggregate cap.
+ *
+ * **EC-E privacy fix:** source disambiguation uses
+ * `relative(gitRoot ?? cwd, ...)` — NEVER absolute paths in
+ * `<source name="">`.
+ *
+ * @internal
+ */
+import { type DiscoverySpec } from "./context-discovery.js";
+export interface DiscoveryRunnerOptions {
+    /** Workspace root passed to all discovery scopes. */
+    readonly cwd: string;
+    /** Per-file truncation cap (D155). */
+    readonly maxBytesPerFile: number;
+    /** Optional override of the default registry. */
+    readonly specs?: ReadonlyArray<DiscoverySpec>;
+    /** Cursor MDC: file paths the LLM has touched this turn (EC-I: empty at send-time). */
+    readonly touchedFiles?: ReadonlyArray<string>;
+    /** When true, skip `theokit-context` spec — caller already handles the legacy path. */
+    readonly skipLegacyTheokitContext?: boolean;
+}

package/dist/internal/runtime/context-discovery.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Context file discovery (T1.1, ADRs D150 / D151).
+ *
+ * Discovers context files via three scopes:
+ *  - `cwd-only` — single dir, single path lookup
+ *  - `git-root-walk` — walk cwd → git-root, collect every directory's match
+ *    (nearest-first ordering)
+ *  - `globbed` — glob pattern relative to cwd (e.g. `.cursor/rules/*.mdc`)
+ *
+ * Pure `existsSync` checks — **no `.gitignore` parsing** (EC-A, KISS) and
+ * **no invented `.theokitignore`** (EC-B). Paths normalized via
+ * `realpath` to dedup symlink chains pointing to the same physical file
+ * (EC-F). Git worktrees work transparently because `.git` exists as a
+ * file in that case (EC-N).
+ *
+ * @internal
+ */
+/** Single filename ("AGENTS.md") or relative glob (".cursor/rules/*.mdc"). */
+export type DiscoveryScope = "cwd-only" | "git-root-walk" | "globbed";
+/** Parser to apply once file is read. */
+export type DiscoveryParser = "plain-markdown" | "mdc" | "frontmatter-zod";

package/dist/internal/runtime/context-frontmatter.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Context source frontmatter schema (ADR D76 — mirrors D10 / hooks-frontmatter).
+ *
+ * Used by the markdown context loader (`context/<name>.md`). Each .md file
+ * represents one context source with structured frontmatter + optional
+ * prose body explaining why this source is part of the agent's context.
+ *
+ * @internal
+ */
+export declare const ContextSourceFrontmatterSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    path: z.ZodString;
+    enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ContextSourceFrontmatter = z.infer<typeof ContextSourceFrontmatterSchema>;

package/dist/internal/runtime/context-import-resolver.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `@path/to/file` import resolver (T2.1, ADR D156).
+ *
+ * Anthropic/Gemini convention: lines that are EXACTLY `@path` get
+ * replaced with the imported file's content, recursively (5-hop cap),
+ * with cycle detection. Inline `see @x.md, also @y.md` references are
+ * NOT resolved (EC-Q — own-line only, mirrors Anthropic's actual
+ * behavior).
+ *
+ * EC-D fix: every imported file is itself capped at `maxBytesPerFile`
+ * via `loadPlainMarkdown` BEFORE concatenation. Prevents a CLAUDE.md
+ * with 5 imports of 30k each from ballooning to 150k of imported
+ * content before the outer cap fires.
+ *
+ * @internal
+ */
+export interface ResolveImportsOptions {
+    /** Absolute paths already resolved (cycle detection). */
+    readonly visited: Set<string>;
+    /** Current recursion depth — caps at MAX_HOPS. */
+    readonly depth: number;
+    /** Per-import file cap (EC-D). Forwarded to loadPlainMarkdown. */
+    readonly maxBytesPerFile: number;
+}

package/dist/internal/runtime/context-loaders.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Context file loaders + truncation (T1.2, ADRs D154 / D155 / D159).
+ *
+ * Reads context source files from disk, applies the per-file size cap
+ * with 70%/20% head/tail truncation, and emits the
+ * `context_files_truncated` telemetry counter when the cap fires.
+ * Pure (no I/O) for `truncateWithMarker` — testable in isolation.
+ *
+ * @internal
+ */
+/** Default per-file cap (40k chars ≈ 10k tokens). D155. */
+export declare const DEFAULT_MAX_BYTES_PER_FILE = 40000;
+export interface LoadedSource {
+    /** Absolute path the content came from. */
+    readonly source: string;
+    readonly content: string;
+    readonly originalBytes: number;
+    readonly truncated: boolean;
+}
+export interface TruncateResult {
+    readonly truncated: boolean;
+    readonly finalContent: string;
+}
+/**
+ * Cap `content` at `max` characters with 70%/20% head/tail truncation
+ * and an explicit marker. Pure — no I/O, no telemetry.
+ *
+ * EC-C: when `max <= MARKER.length`, skip the marker entirely and
+ * return a head-only slice. Without this guard, `budget = max -
+ * MARKER.length` would go negative and `content.slice(-tailBytes)`
+ * would slice from the END of the string rather than truncating.
+ *
+ * EC-H: codepoint integrity — `String.slice()` operates on UTF-16
+ * code units, which can split surrogate pairs. We accept that
+ * trailing/leading replacement chars (U+FFFD) may appear at boundaries.
+ * Modern LLMs tolerate them; byte-exact safety would require Buffer
+ * slicing + TextDecoder with `fatal: true` retry, which adds complexity
+ * without value.
+ *
+ * @public
+ */
+export declare function truncateWithMarker(content: string, max: number): TruncateResult;

package/dist/internal/runtime/context-manager.d.ts

@@ -0,0 +1,11 @@
+import type { ContextSettings, ContextSnapshot, SDKContextManager } from "../../types/context.js";
+export declare class FileContextManager implements SDKContextManager {
+    private readonly cwd;
+    private readonly settings;
+    private readonly settingSourcesIncludeProject;
+    private state;
+    constructor(cwd: string, settings: ContextSettings, settingSourcesIncludeProject: boolean);
+    initialize(): Promise<void>;
+    refresh(): Promise<void>;
+    snapshot(): Promise<ContextSnapshot>;
+}

package/dist/internal/runtime/context-mdc-parser.d.ts

@@ -0,0 +1,24 @@
+/**
+ * MDC (Markdown Cursor) parser for `.cursor/rules/*.mdc` (T3.1, ADR D154).
+ *
+ * Parses YAML frontmatter with `description` / `globs` / `alwaysApply`
+ * fields. Honors activation per Cursor's docs:
+ *  - `alwaysApply: true` → activates unconditionally.
+ *  - `alwaysApply: false` + matching glob in `touchedFiles` → activates.
+ *  - `alwaysApply: false` + no glob match → skipped.
+ *
+ * **EC-I (v1 semantic):** at `agent.send()` time, `touchedFiles` is
+ * empty. Only `alwaysApply: true` rules activate. Per-glob activation
+ * arrives in v2 when we hook the file-read pipeline. Description-based
+ * "agent requested" classification is out of scope.
+ *
+ * Glob matching uses a tiny in-house `*` → `.*` regex (no new dep)
+ * sufficient for the patterns Cursor itself recommends.
+ *
+ * @internal
+ */
+export type McdFrontmatter = z.infer<typeof McdFrontmatterSchema>;
+export interface McdParseResult {
+    readonly frontmatter: McdFrontmatter;
+    readonly body: string;
+}

package/dist/internal/runtime/default-model.d.ts

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

package/dist/internal/runtime/fixture-events.d.ts

@@ -0,0 +1,12 @@
+import type { SDKAssistantMessage, SDKRequestMessage, SDKStatusMessage, SDKSystemMessage, SDKTaskMessage, SDKThinkingMessage, SDKToolUseMessage, SDKUserMessageEvent } from "../../types/messages.js";
+import type { FixtureRequest } from "./fixture-types.js";
+export declare function systemEvent(request: FixtureRequest, tools: string[]): SDKSystemMessage;
+export declare function userEvent(request: FixtureRequest): SDKUserMessageEvent;
+export declare function assistantText(request: FixtureRequest, text: string): SDKAssistantMessage;
+export declare function thinkingEvent(request: FixtureRequest, text: string): SDKThinkingMessage;
+export declare function toolCallRunning(request: FixtureRequest, callId: string, name: string): SDKToolUseMessage;
+export declare function toolCallCompleted(request: FixtureRequest, callId: string, name: string): SDKToolUseMessage;
+export declare function cloudStatus(request: FixtureRequest, status: SDKStatusMessage["status"]): SDKStatusMessage;
+export declare function taskEvent(request: FixtureRequest, status: string): SDKTaskMessage;
+export declare function requestEvent(request: FixtureRequest): SDKRequestMessage;
+export declare function defaultLocalTools(request: FixtureRequest): string[];

package/dist/internal/runtime/fixture-responder.d.ts

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

package/dist/internal/runtime/fixture-run-base.d.ts

@@ -0,0 +1,45 @@
+import type { ModelSelection } from "../../types/agent.js";
+import type { ConversationTurn } from "../../types/conversation.js";
+import type { SDKMessage } from "../../types/messages.js";
+import type { Run, RunOperation, RunResult, RunStatus } from "../../types/run.js";
+import type { FixtureScript } from "./fixture-types.js";
+export declare abstract class FixtureRunBase implements Run {
+    readonly id: string;
+    readonly agentId: string;
+    status: RunStatus;
+    result?: string;
+    model?: ModelSelection;
+    durationMs?: number;
+    createdAt?: number;
+    protected readonly script: FixtureScript;
+    protected readonly startTime: number;
+    protected readonly supportedOps: Set<RunOperation>;
+    protected readonly listeners: Set<(status: RunStatus) => void>;
+    protected readonly terminationPromise: Promise<RunResult>;
+    protected resolveTermination: (value: RunResult) => void;
+    protected terminated: boolean;
+    private eventNotifier;
+    constructor(options: FixtureRunBaseOptions);
+    abstract bootstrap(): void;
+    /**
+     * Subclasses driving real (non-fixture) runtimes should call this after
+     * pushing a new event into `this.script.events` so that already-awaiting
+     * consumers of `stream()` wake up and yield it.
+     */
+    protected notifyNewEvents(): void;
+    stream(): AsyncGenerator<SDKMessage, void>;
+    wait(): Promise<RunResult>;
+    cancel(): Promise<void>;
+    conversation(): Promise<ConversationTurn[]>;
+    supports(op: RunOperation): boolean;
+    unsupportedReason(op: RunOperation): string | undefined;
+    onDidChangeStatus(listener: (status: RunStatus) => void): () => void;
+    protected transitionTo(nextStatus: RunStatus): void;
+    protected buildResult(status: RunStatus): RunResult;
+    /** Subclasses override to attach runtime-specific fields (e.g. cloud git info). */
+    protected extendRunResult(result: RunResult): RunResult;
+    /** Whether `onDidChangeStatus` should fire immediately with the current status. */
+    protected notifyImmediately(): boolean;
+    private notifyListener;
+    private notifyAllListeners;
+}

package/dist/internal/runtime/fixture-scripts.d.ts

@@ -0,0 +1,21 @@
+import type { FixtureRequest, FixtureScript } from "./fixture-types.js";
+export { extractMemoryFact, isMemoryWritePrompt } from "./memory-store.js";
+export declare function isMemoryRecallPrompt(message: string, request: FixtureRequest): boolean;
+export declare function memoryWriteScript(request: FixtureRequest): FixtureScript;
+export declare function memoryRecallScript(request: FixtureRequest): FixtureScript;
+export declare function returnAnswerScript(request: FixtureRequest, answer: string): FixtureScript;
+export declare function buildCloudScript(request: FixtureRequest): FixtureScript;
+export declare function slowRunScript(request: FixtureRequest): FixtureScript;
+export declare function errorRunScript(request: FixtureRequest): FixtureScript;
+export declare function returnOnlyScript(request: FixtureRequest): FixtureScript;
+export declare function shellWithApprovalScript(request: FixtureRequest): FixtureScript;
+export declare function twoShellCommandsScript(request: FixtureRequest): FixtureScript;
+export declare function shellExplainScript(request: FixtureRequest): FixtureScript;
+export declare function spawnSubagentsScript(request: FixtureRequest): FixtureScript;
+export declare function listMcpToolsScript(request: FixtureRequest): FixtureScript;
+export declare function webSearchScript(request: FixtureRequest): FixtureScript;
+export declare function providerFallbackScript(request: FixtureRequest): FixtureScript;
+export declare function printEnvScript(request: FixtureRequest): FixtureScript;
+export declare function useSkillScript(request: FixtureRequest, skillName: string): FixtureScript;
+export declare function contextAwareScript(request: FixtureRequest): FixtureScript;
+export declare function defaultFinishedScript(request: FixtureRequest): FixtureScript;

package/dist/internal/runtime/fixture-types.d.ts

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

package/dist/internal/runtime/fork-agent.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Fork agent primitive (T1.2, ADRs D110-D114).
+ *
+ * `forkAgentImpl(parent, options, deps)` creates a short-lived auxiliary
+ * agent that inherits the parent's credentials and **byte-identical**
+ * system prompt (D112 — cache hit) but runs with a reduced tool
+ * whitelist enforced via `AsyncLocalStorage` (D111). Memory plugins
+ * (`kind: "memory"`) are preserved so memory writes carry provenance
+ * (D114 + EC-B fix); general/model-provider plugins are dropped because
+ * the fork has its own `PluginManager.initialize` and double-registering
+ * is redundant.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/runtime/hooks-executor.d.ts

@@ -0,0 +1,35 @@
+export interface HookCommand {
+    command: string;
+    /** Optional matcher restricting the hook to specific tools (regex). */
+    matcher?: string;
+    /** Optional timeout in ms; defaults to 30s. */
+    timeoutMs?: number;
+}
+export interface HookDecision {
+    decision: "allow" | "deny" | "feedback";
+    reason?: string;
+    feedback?: string;
+}
+export interface HookPayload {
+    event: HookEvent;
+    tool?: string;
+    input?: Record<string, unknown>;
+    output?: Record<string, unknown>;
+    agentId?: string;
+    runId?: string;
+}
+export interface HookExecutionResult {
+    decisions: HookDecision[];
+    blocked: boolean;
+    reason?: string;
+}
+export declare class HooksExecutor {
+    private readonly cwd;
+    private config;
+    constructor(cwd: string);
+    initialize(settingSourcesIncludeProject: boolean): Promise<void>;
+    /** Fire every hook registered for `event` and aggregate the decisions. */
+    run(payload: HookPayload): Promise<HookExecutionResult>;
+    private commandsFor;
+    private executeOne;
+}

package/dist/internal/runtime/hooks-frontmatter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Hook frontmatter schema (ADR D76 — mirrors D10 SkillFrontmatter pattern).
+ *
+ * Used by the markdown hooks loader (`hooks/<name>.md`). Each .md file
+ * represents one hook entry with structured frontmatter + optional prose
+ * body explaining rationale.
+ *
+ * @internal
+ */
+/** Hook events supported by the SDK runtime. Mirrors HookEvent in hooks-executor.ts. */
+export declare const HOOK_EVENTS: readonly ["preRun", "postRun", "preToolUse", "postToolUse", "stop"];
+export declare const HookFrontmatterSchema: z.ZodObject<{
+    event: z.ZodEnum<{
+        stop: "stop";
+        preRun: "preRun";
+        postRun: "postRun";
+        preToolUse: "preToolUse";
+        postToolUse: "postToolUse";
+    }>;
+    matcher: z.ZodString;
+    command: z.ZodString;
+    enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    priority: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type HookFrontmatter = z.infer<typeof HookFrontmatterSchema>;

package/dist/internal/runtime/hooks-source.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Single source of truth for loading the hooks config (T1.2, ADR D77).
+ *
+ * Detection order:
+ *   1. `.theokit/hooks/*.md` (markdown, frontmatter-validated) — canonical.
+ *   2. `.theokit/hooks.json` — legacy. Emits one-time deprecation warn.
+ *   3. Neither → empty config (no hooks).
+ *
+ * Consumed by `hooks-loader.ts` (boot-time validation) and
+ * `hooks-executor.ts` (runtime dispatch).
+ *
+ * @internal
+ */
+export type HookEvent = "preRun" | "postRun" | "preToolUse" | "postToolUse" | "stop";
+export interface HookCommand {
+    command: string;
+    matcher?: string;
+    timeoutMs?: number;
+}
+export interface HookConfig {
+    hooks?: Partial<Record<HookEvent, HookCommand[]>>;
+}

package/dist/internal/runtime/live-agent-registry.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Live-agent cache for production deploys (Production-Readiness #2, ADRs D307-D310).
+ *
+ * Caches `SDKAgent` instances by id with LRU eviction (when `size > maxAgents`)
+ * and an idle-timeout sweep (configurable interval, default 60s). Solves the
+ * "OOM at some point" failure mode of long-running Node servers that keep
+ * spawning fresh agents per conversation.
+ *
+ * **Distinct from `agent-registry.ts`** (the metadata registry that persists
+ * `RegisteredAgent` to `registry.json` per cwd). That module is the "address
+ * book"; this module is the "live cache". Conflating them violates SRP — see
+ * ADR D307.
+ *
+ * Defaults (ADR D308): `maxAgents: 100`, `idleTimeoutMs: 30 min`, sweep `60s`.
+ * Calibrated for indie/small-team Node deploys; high-traffic SaaS should
+ * `configure({ maxAgents: 1000 })`.
+ *
+ * @public (singleton exposed via `Agent.registry`)
+ */
+import type { SDKAgent } from "../../types/agent.js";
+export type EvictReason = "lru" | "idle" | "explicit";
+export interface AgentRegistryOptions {
+    /**
+     * Maximum number of agents kept alive simultaneously. LRU eviction when
+     * exceeded. Default: 100.
+     *
+     * Setting `0` disables the cache entirely — every `Agent.getOrCreate`
+     * re-initializes (high cost, but predictable memory).
+     */
+    maxAgents?: number;
+    /**
+     * Idle timeout in milliseconds. Agents not used for this duration are
+     * evicted on the next sweep tick. Default: 1_800_000 (30 minutes).
+     * Set `0` to disable idle eviction.
+     */
+    idleTimeoutMs?: number;
+    /**
+     * Sweep interval in milliseconds. Default: 60_000 (60s).
+     * Lower = more responsive eviction but more CPU. Higher = staler entries.
+     */
+    sweepIntervalMs?: number;
+    /**
+     * Called whenever an agent is evicted. Listener errors are swallowed
+     * with a one-shot stderr warn (do not crash the eviction loop).
+     */
+    onEvict?: (id: string, reason: EvictReason) => void;
+}
+export declare class LiveAgentRegistry {
+    #private;
+    /**
+     * Reconfigure registry behavior. Process-wide singleton (D310) — last
+     * configure call wins for all subsequent operations.
+     */
+    configure(opts: AgentRegistryOptions): void;
+    /**
+     * Lookup a cached agent. `get` is a use — refreshes `lastUsedAt` so the
+     * entry survives LRU eviction.
+     */
+    get(id: string): SDKAgent | undefined;
+    /**
+     * Insert or overwrite an agent in the cache. Triggers fire-and-forget LRU
+     * eviction when `size > maxAgents`.
+     *
+     * EC-4: when `id` already maps to a DIFFERENT agent instance, dispose the
+     * old one before overwriting (race protection against two `getOrCreate`
+     * calls creating two agents but only the second being cached — the first
+     * would leak file handles + lifecycle controllers).
+     */
+    set(id: string, agent: SDKAgent): void;
+    /**
+     * Explicitly evict an agent by id. Returns `true` when the entry was
+     * present (false = already gone). Calls `agent.dispose()` + `onEvict`
+     * with reason `"explicit"`.
+     */
+    evict(id: string): Promise<boolean>;
+    /**
+     * Evict every cached agent. Used by graceful shutdown (`process.on('SIGTERM')`)
+     * or end-of-test cleanup.
+     */
+    evictAll(): Promise<void>;
+    /** Number of currently cached agents. */
+    size(): number;
+    /** Ids of cached agents, newest first (by lastUsedAt). */
+    ids(): readonly string[];
+}
+/** Process-wide singleton (ADR D310). */
+export declare const liveAgentRegistry: LiveAgentRegistry;

package/dist/internal/runtime/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 { FileContextManager } from "./context-manager.js";
+import { type PluginMetadata, PluginsManager } from "./plugins-manager.js";
+import { ProvidersManagerImpl } from "./providers-manager.js";
+import { type SkillMetadata, SkillsManager } from "./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?: {
+        list: () => Promise<SkillMetadata[]>;
+    };
+    pluginsManager?: PluginsManager;
+    plugins?: {
+        list: () => Promise<PluginMetadata[]>;
+    };
+}
+export declare function bootstrapSubmanagers(args: {
+    options: AgentOptions;
+    workspaceCwd: string;
+    settingSourcesIncludeProject: boolean;
+    settingSourcesIncludePlugins: boolean;
+}): BootstrappedSubmanagers;

package/dist/internal/runtime/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/loop-types.js";
+import type { PersonalityPreset } from "../personality/types.js";
+import type { PluginManager } from "../plugins/manager.js";
+import type { HooksExecutor } from "./hooks-executor.js";
+import type { MemoryFact } from "./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/runtime/local-agent-invalidate.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `Agent.invalidateCache` helpers extracted from LocalAgent (T3.2 / T4.3,
+ * ADR D94). Keeps `local-agent.ts` under the 400-LoC gate while providing
+ * the deferred-vs-applyNow semantics + EC-7 failure-path cleanup.
+ *
+ * @internal
+ */
+export {};