la-machina-engine 0.3.0

package/dist/index.d.cts

@@ -0,0 +1,3587 @@
+import * as zod from 'zod';
+import { z, ZodTypeAny } from 'zod';
+import { ContentBlockParam, MessageParam } from '@anthropic-ai/sdk/resources/messages';
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * StorageAdapter — abstract filesystem interface for la-machina-engine.
+ *
+ * All paths are relative to the adapter's root. The adapter enforces
+ * path safety (no traversal, no absolute paths, no null bytes) and
+ * provides a filesystem-shaped API that subsystems can use without
+ * knowing whether the backend is local disk, R2, or any other
+ * S3-compatible object store.
+ *
+ * Implementations ship in this package:
+ * - `LocalStorageAdapter` (src/storage/localAdapter.ts) — fs-backed
+ * - `R2StorageAdapter` (src/storage/r2Adapter.ts) — S3-compatible
+ *
+ * Users may supply custom adapters implementing this interface.
+ */
+interface FileStat {
+    readonly size: number;
+    readonly mtime: Date;
+}
+interface StorageAdapter {
+    /** Read a file as UTF-8 text. Returns null if file doesn't exist. */
+    readFile(relativePath: string): Promise<string | null>;
+    /** Write a file atomically. Creates parent directories if needed. */
+    writeFile(relativePath: string, content: string): Promise<void>;
+    /** Append to a file. Creates it if it doesn't exist. */
+    appendFile(relativePath: string, content: string): Promise<void>;
+    /** Delete a file. No-op if it doesn't exist. */
+    deleteFile(relativePath: string): Promise<void>;
+    /** Check if a file or directory exists. */
+    exists(relativePath: string): Promise<boolean>;
+    /**
+     * List entries in a directory. Returns just the names (not full paths).
+     * Returns an empty array if the directory doesn't exist.
+     */
+    listDir(relativePath: string): Promise<string[]>;
+    /** Create a directory (recursive). No-op on S3-like backends. */
+    mkdir(relativePath: string): Promise<void>;
+    /** Check if a path is a directory. */
+    isDirectory(relativePath: string): Promise<boolean>;
+    /** Get file metadata. Returns null if file doesn't exist. */
+    stat(relativePath: string): Promise<FileStat | null>;
+}
+/**
+ * Two-root storage model:
+ *
+ * - `global`:    rooted at `{rootPath}/.claude/` — identity, universal rules
+ * - `workspace`: rooted at `{rootPath}/workspaces/{workspaceId}/.claude/` —
+ *                project-specific memory, skills, sessions, episodes
+ *
+ * Every consumer gets a pair of adapters via `createEngineStorage()`.
+ */
+interface EngineStorage {
+    readonly global: StorageAdapter;
+    readonly workspace: StorageAdapter;
+}
+/**
+ * Error thrown by all storage operations. `cause` is preserved as-is
+ * (usually an `ErrnoException` or AWS SDK error) so callers can inspect
+ * the underlying failure.
+ */
+declare class StorageError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+
+/**
+ * R2BindingStorageAdapter — Cloudflare Workers R2 binding (NOT S3 SDK).
+ *
+ * Unlike `R2StorageAdapter` which talks to R2 over the S3 REST protocol,
+ * this adapter uses the native R2 binding exposed to Workers runtime:
+ *
+ *   [[r2_buckets]]
+ *   binding = "BUCKET"
+ *   bucket_name = "my-bucket"
+ *
+ *   // In code:
+ *   new R2BindingStorageAdapter(env.BUCKET, 'tenant/acme')
+ *
+ * Why use this over `R2StorageAdapter` on Workers?
+ *   - `@aws-sdk/client-s3` is heavy (~500 KB) and the Workers-compatibility
+ *     story for ListObjectsV2 XML parsing is brittle; CommonPrefixes come
+ *     back empty in some runtimes, silently breaking `listDir`.
+ *   - The R2 binding API (`bucket.list`, `bucket.get`, `bucket.put`,
+ *     `bucket.delete`) is native, typed, and uses native JSON responses.
+ *   - No AWS credentials, no endpoint URL — the binding handles auth.
+ *
+ * Use `R2StorageAdapter` on Node or anywhere you don't have a Workers
+ * binding (local dev with Miniflare's S3 endpoint, backfills, etc).
+ * Use this adapter inside Workers for reliability and bundle size.
+ *
+ * All pure JS — no `node:` imports, Workers-compatible.
+ */
+
+interface R2Object {
+    key: string;
+    size: number;
+    uploaded: Date;
+    httpMetadata?: R2HTTPMetadata;
+    customMetadata?: Record<string, string>;
+}
+interface R2ObjectBody extends R2Object {
+    text(): Promise<string>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    blob?(): Promise<Blob>;
+}
+interface R2Objects {
+    objects: R2Object[];
+    truncated: boolean;
+    cursor?: string;
+    delimitedPrefixes?: string[];
+}
+interface R2HTTPMetadata {
+    contentType?: string;
+    contentLanguage?: string;
+    contentDisposition?: string;
+    contentEncoding?: string;
+    cacheControl?: string;
+    cacheExpiry?: Date;
+}
+interface R2ListOptions {
+    prefix?: string;
+    delimiter?: string;
+    cursor?: string;
+    limit?: number;
+    include?: Array<'httpMetadata' | 'customMetadata'>;
+}
+interface R2PutOptions {
+    httpMetadata?: R2HTTPMetadata;
+    customMetadata?: Record<string, string>;
+}
+/**
+ * Structural type for `env.BUCKET` — intentionally not imported from
+ * `@cloudflare/workers-types` so this adapter has no extra peer deps.
+ */
+interface R2BucketBinding {
+    head(key: string): Promise<R2Object | null>;
+    get(key: string): Promise<R2ObjectBody | null>;
+    put(key: string, value: string | ArrayBuffer | ArrayBufferView | ReadableStream | Blob | null, options?: R2PutOptions): Promise<R2Object>;
+    delete(keys: string | string[]): Promise<void>;
+    list(options?: R2ListOptions): Promise<R2Objects>;
+}
+declare class R2BindingStorageAdapter implements StorageAdapter {
+    private readonly bucket;
+    private readonly rootPrefix;
+    constructor(bucket: R2BucketBinding, rootPrefix: string);
+    private key;
+    readFile(rel: string): Promise<string | null>;
+    writeFile(rel: string, content: string): Promise<void>;
+    appendFile(rel: string, content: string): Promise<void>;
+    deleteFile(rel: string): Promise<void>;
+    exists(rel: string): Promise<boolean>;
+    /**
+     * List direct children of `rel` (files + subdirectory names). Returns
+     * just the names (not full keys). Empty array if path doesn't exist.
+     *
+     * Uses the native R2 list API with `delimiter: '/'` which returns
+     * `delimitedPrefixes` for "subdirectories" and `objects` for files —
+     * equivalent to S3's CommonPrefixes + Contents but parsed by the
+     * binding itself (no XML, no SDK).
+     */
+    listDir(rel: string): Promise<string[]>;
+    mkdir(rel: string): Promise<void>;
+    isDirectory(rel: string): Promise<boolean>;
+    stat(rel: string): Promise<FileStat | null>;
+}
+
+/**
+ * Compaction config + result types.
+ */
+
+type CompactionStrategy = 'drop-middle' | 'summarize' | 'session-memory' | 'auto';
+interface ResolvedCompactionConfig {
+    /** Which strategy to use. 'auto' picks the best one at runtime. */
+    readonly strategy: CompactionStrategy;
+    /** Fraction (0-1) of context window that triggers compaction. */
+    readonly threshold: number;
+    /** How many recent messages to keep after compaction. */
+    readonly keepLast: number;
+    /** Max tokens for the LLM-generated summary. */
+    readonly summaryMaxTokens: number;
+    /** Enable time-based microcompaction of old tool results. */
+    readonly microcompact: boolean;
+    /** Age in ms after which tool results are eligible for microcompaction. */
+    readonly microcompactAgeMs: number;
+}
+
+/**
+ * Coordinator config types.
+ */
+interface ResolvedCoordinatorConfig {
+    /** Whether coordinator mode is active. Default: false. */
+    readonly enabled: boolean;
+    /**
+     * Tools available to worker agents. Workers deliberately lack Agent
+     * (no sub-delegation) and typically lack MCP (coordinator controls
+     * external access). Default: core file/search tools only.
+     */
+    readonly workerTools: readonly string[];
+    /** Max concurrent workers the coordinator can spawn. Default: 5. */
+    readonly maxConcurrentWorkers: number;
+}
+
+/**
+ * streaming — normalize raw Anthropic stream events into a small,
+ * well-shaped union that the engine's agent loop can consume.
+ *
+ * The Anthropic SDK emits a discriminated union of six raw events per
+ * stream:
+ *   message_start        — metadata and initial usage
+ *   content_block_start  — begin a text or tool_use block
+ *   content_block_delta  — partial text or input_json chunk
+ *   content_block_stop   — end of a block
+ *   message_delta        — stop_reason + final output_tokens
+ *   message_stop         — terminal event
+ *
+ * This module collects deltas into complete blocks and emits a cleaner
+ * union: `text` / `tool_use` / `message_stop`. Tool_use input JSON is
+ * assembled and parsed once at content_block_stop so downstream code
+ * sees a typed object rather than raw partial JSON.
+ *
+ * Errors:
+ * - Malformed tool_use JSON → `StreamParseError`
+ * - Stream ends without `message_stop` → `StreamIncompleteError`
+ */
+
+interface TokenUsage$1 {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheCreationInput?: number | undefined;
+    readonly cacheReadInput?: number | undefined;
+}
+/**
+ * Common Anthropic stop reasons. The `(string & {})` pattern preserves
+ * autocomplete for the documented values while still allowing arbitrary
+ * strings from third-party proxies that may use other vocabularies.
+ */
+type StopReason = 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence' | 'refusal' | 'pause_turn' | (string & Record<never, never>);
+type NormalizedEvent = {
+    readonly type: 'text';
+    readonly index: number;
+    readonly text: string;
+} | {
+    readonly type: 'tool_use';
+    readonly index: number;
+    readonly id: string;
+    readonly name: string;
+    readonly input: unknown;
+} | {
+    readonly type: 'thinking';
+    readonly index: number;
+    readonly thinking: string;
+} | {
+    readonly type: 'message_stop';
+    readonly stopReason: StopReason;
+    readonly usage: TokenUsage$1;
+};
+
+/**
+ * Orchestrator types — plan schema, step results, retry policy,
+ * orchestrator config, and the public OrchestratorResult.
+ */
+
+declare const PlanStepSchema: z.ZodObject<{
+    id: z.ZodString;
+    description: z.ZodString;
+    action: z.ZodEnum<["research", "implement", "verify", "review", "custom"]>;
+    files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    spec: z.ZodOptional<z.ZodString>;
+    dependsOn: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    description: string;
+    action: "custom" | "research" | "implement" | "verify" | "review";
+    files?: string[] | undefined;
+    spec?: string | undefined;
+    dependsOn?: string[] | undefined;
+}, {
+    id: string;
+    description: string;
+    action: "custom" | "research" | "implement" | "verify" | "review";
+    files?: string[] | undefined;
+    spec?: string | undefined;
+    dependsOn?: string[] | undefined;
+}>;
+declare const PlanSchema: z.ZodObject<{
+    summary: z.ZodString;
+    steps: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+        action: z.ZodEnum<["research", "implement", "verify", "review", "custom"]>;
+        files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        spec: z.ZodOptional<z.ZodString>;
+        dependsOn: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        description: string;
+        action: "custom" | "research" | "implement" | "verify" | "review";
+        files?: string[] | undefined;
+        spec?: string | undefined;
+        dependsOn?: string[] | undefined;
+    }, {
+        id: string;
+        description: string;
+        action: "custom" | "research" | "implement" | "verify" | "review";
+        files?: string[] | undefined;
+        spec?: string | undefined;
+        dependsOn?: string[] | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    summary: string;
+    steps: {
+        id: string;
+        description: string;
+        action: "custom" | "research" | "implement" | "verify" | "review";
+        files?: string[] | undefined;
+        spec?: string | undefined;
+        dependsOn?: string[] | undefined;
+    }[];
+}, {
+    summary: string;
+    steps: {
+        id: string;
+        description: string;
+        action: "custom" | "research" | "implement" | "verify" | "review";
+        files?: string[] | undefined;
+        spec?: string | undefined;
+        dependsOn?: string[] | undefined;
+    }[];
+}>;
+type PlanStep = z.infer<typeof PlanStepSchema>;
+type Plan = z.infer<typeof PlanSchema>;
+type StepStatus = 'done' | 'failed' | 'skipped' | 'reverted';
+interface StepResult {
+    readonly stepId: string;
+    readonly action: string;
+    readonly status: StepStatus;
+    readonly output?: string | undefined;
+    readonly error?: string | undefined;
+    readonly attempts: number;
+    readonly agentId?: string | undefined;
+}
+interface FileSnapshot {
+    readonly path: string;
+    /** null = file didn't exist before (delete on revert). */
+    readonly content: string | null;
+}
+interface RetryPolicy {
+    readonly maxAttempts: number;
+    readonly backoffMs: number;
+    readonly onExhausted: 'revert' | 'skip' | 'fail';
+}
+interface ResolvedRetryPolicies {
+    readonly plan: RetryPolicy;
+    readonly research: RetryPolicy;
+    readonly implement: RetryPolicy;
+    readonly verify: RetryPolicy;
+    readonly review: RetryPolicy;
+}
+interface ResolvedOrchestratorConfig {
+    readonly enabled: boolean;
+    readonly retries: ResolvedRetryPolicies;
+    readonly maxParallelResearchers: number;
+    readonly enableReview: boolean;
+    readonly enableRollback: boolean;
+    readonly maxPlanSteps: number;
+    /** Max turns per internal agent run (planner, researcher, implementer, verifier). Default: 15. */
+    readonly agentMaxTurns: number;
+}
+interface OrchestratorResult {
+    readonly status: 'done' | 'partial' | 'failed';
+    readonly output: string;
+    readonly plan: Plan | null;
+    readonly steps: readonly StepResult[];
+    readonly tokensUsed: TokenUsage$1;
+    readonly agentRuns: number;
+    readonly reverted: readonly string[];
+    readonly durationMs: number;
+}
+interface OrchestrateOptions {
+    readonly runId: string;
+    readonly nodeId: string;
+    readonly task: string;
+    /** Optional pre-built plan — skip the Planner agent. */
+    readonly plan?: Plan | undefined;
+}
+
+/**
+ * Tool contract — the shape every tool implements, plus a registry to
+ * collect them by name.
+ *
+ * The contract is intentionally minimal:
+ *
+ *   1. A tool has a `name`, a `description`, and a Zod `inputSchema`.
+ *      Zod gives both runtime validation and a TypeScript-inferred
+ *      input type for `execute()`.
+ *   2. `execute(input, context)` returns a `ToolResult` (or rejects).
+ *      The runtime catches rejections and turns them into error
+ *      results — a misbehaving tool can never crash the agent loop.
+ *   3. The runtime supplies a `ToolContext` carrying at least an
+ *      `AbortSignal` for cancellation.
+ *
+ * Phase 5 ships the types and the registry. Phase 6 fills the registry
+ * with the core tool set (Bash, Read, Write, Edit, Glob, Grep, WebFetch).
+ * Custom tools come from `config.tools.custom` at engine init time.
+ */
+
+/**
+ * The execution context passed to every tool. Phase 5 keeps this
+ * minimal — only an AbortSignal — so the contract stays portable.
+ * Later phases extend with storage, run/node ids, hook handles, etc.
+ */
+interface ToolContext {
+    readonly signal: AbortSignal;
+}
+/**
+ * The result of a single tool invocation. The runtime wraps thrown
+ * errors in this shape so the agent loop only ever sees success/error
+ * as data, not exceptions.
+ */
+interface ToolResult {
+    /** Human- and model-readable output. The agent's next turn sees this. */
+    readonly content: string;
+    /** True when the tool failed. */
+    readonly isError?: boolean;
+    /** Optional structured metadata for hooks / observability. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * A tool definition. Generic on a Zod schema so that `execute()`'s
+ * input parameter is statically typed via `z.infer<TSchema>`.
+ *
+ * Tool authors normally use `defineTool()` to get the inference
+ * without writing the generic by hand.
+ */
+interface Tool$1<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: TSchema;
+    /**
+     * Optional raw JSON Schema to send to the Anthropic API as
+     * `input_schema`, bypassing Zod-to-JSON-Schema conversion. Used by
+     * MCP-sourced tools whose schema is authored in JSON Schema directly
+     * and whose Zod schema is a `z.unknown()` passthrough.
+     *
+     * When set, `toAnthropicTool()` in the agent loop prefers this over
+     * running `zodToJsonSchema(inputSchema)`. Normal in-process tools
+     * defined via `defineTool()` should leave this undefined.
+     */
+    readonly anthropicSchemaOverride?: Record<string, unknown>;
+    /**
+     * Returns true if this tool is safe to run concurrently with other
+     * concurrency-safe tools. Read-only tools (Read, Glob, Grep, etc.)
+     * should return true; mutating tools (Write, Edit, Bash) should
+     * return false. Default: false (fail-closed).
+     *
+     * The agent loop uses this to batch consecutive safe tool calls
+     * into a single `Promise.all()` for parallel execution, while
+     * running unsafe tools serially.
+     *
+     * Input is typed as `unknown` (not `z.infer<TSchema>`) so that
+     * `Tool<ZodObject<...>>` remains assignable to `Tool<ZodTypeAny>`
+     * under `exactOptionalPropertyTypes`.
+     */
+    isConcurrencySafe?: ((input: unknown) => boolean) | undefined;
+    execute(input: z.infer<TSchema>, context: ToolContext): Promise<ToolResult>;
+}
+/**
+ * Identity helper that locks in the schema generic so callers don't have
+ * to write it. Use this whenever defining a tool — it costs nothing at
+ * runtime and gives you full inference inside `execute()`.
+ *
+ * @example
+ * ```ts
+ * const Echo = defineTool({
+ *   name: 'Echo',
+ *   description: 'Echoes its input back',
+ *   inputSchema: z.object({ msg: z.string() }),
+ *   execute: async ({ msg }) => ({ content: msg }),
+ * })
+ * ```
+ */
+declare function defineTool<TSchema extends z.ZodTypeAny>(tool: Tool$1<TSchema>): Tool$1<TSchema>;
+/**
+ * In-memory registry of tools by name. Used by the engine's tool runtime
+ * to dispatch tool calls. Re-registering the same name throws so typos
+ * surface immediately rather than silently shadowing.
+ */
+declare class ToolRegistry {
+    private readonly tools;
+    register(tool: Tool$1): void;
+    registerAll(tools: ReadonlyArray<Tool$1>): void;
+    unregister(name: string): void;
+    get(name: string): Tool$1 | undefined;
+    has(name: string): boolean;
+    list(): Tool$1[];
+    count(): number;
+}
+
+/**
+ * Hook event payloads + handler types.
+ *
+ * Six lifecycle slots match the `config.hooks` shape from Phase 1:
+ *
+ *   preRun        — fires once before the agent loop starts
+ *   postRun       — fires once when the run exits (done | paused | failed)
+ *   preTurn       — fires before each turn's API call
+ *   postTurn      — fires after each turn's tool dispatches complete
+ *   preToolCall   — fires before each tool execution
+ *   postToolCall  — fires after each tool execution (always — even on error)
+ *
+ * Hooks are functions: `(event) => void | Promise<void>`. They run in
+ * registration order, sequentially. Errors thrown by a hook are
+ * isolated — they never abort the run.
+ */
+
+interface PreRunEvent {
+    readonly runId: string;
+    readonly nodeId: string;
+    readonly task: string;
+}
+interface PostRunEvent {
+    readonly runId: string;
+    readonly nodeId: string;
+    readonly status: 'done' | 'paused' | 'failed';
+    readonly tokensUsed: TokenUsage$1;
+    readonly turnsUsed: number;
+    readonly output?: string;
+    readonly error?: Error;
+    /** Number of tool calls dispatched during the run. */
+    readonly toolCallCount?: number;
+    /** Transcript path for this run (e.g. "projects/{runId}/nodes/{nodeId}"). */
+    readonly transcriptPath?: string;
+}
+interface PreTurnEvent {
+    readonly runId: string;
+    readonly nodeId: string;
+    readonly turnIndex: number;
+    readonly messageCount: number;
+}
+interface PostTurnEvent {
+    readonly runId: string;
+    readonly nodeId: string;
+    readonly turnIndex: number;
+    readonly tokensUsed: TokenUsage$1;
+}
+/**
+ * Stop hook event — fired after each turn completes (tool dispatch or
+ * terminal). Ported from La-Machina's stopHooks.ts. The hook can
+ * inspect the full turn state and optionally prevent continuation.
+ */
+interface StopHookEvent {
+    readonly runId: string;
+    readonly nodeId: string;
+    readonly turnIndex: number;
+    readonly tokensUsed: TokenUsage$1;
+    readonly lastAssistantText: string;
+    readonly toolsCalled: readonly string[];
+    readonly status: 'tool_use' | 'end_turn';
+}
+/**
+ * Stop hook result. Return `{ preventContinuation: true }` to stop
+ * the run gracefully after this turn. The run returns status 'done'
+ * with the last assistant output. If multiple stop hooks run, any
+ * one returning preventContinuation stops the run.
+ */
+interface StopHookResult {
+    readonly preventContinuation?: boolean;
+    readonly reason?: string;
+}
+interface PreToolCallEvent$1 {
+    readonly toolName: string;
+    readonly input: unknown;
+}
+interface PostToolCallEvent$1 {
+    readonly toolName: string;
+    readonly input: unknown;
+    readonly result: ToolResult;
+    readonly durationMs: number;
+}
+/**
+ * Gate decision returned by `gateBeforeTool`. `allow: true` lets the
+ * dispatch proceed; `allow: false` pauses the run with `reason` captured
+ * in the transcript snapshot.
+ */
+interface GateDecision$1 {
+    readonly allow: boolean;
+    readonly reason?: string;
+}
+type PreRunHook = (event: PreRunEvent) => void | Promise<void>;
+type PostRunHook = (event: PostRunEvent) => void | Promise<void>;
+type PreTurnHook = (event: PreTurnEvent) => void | Promise<void>;
+type PostTurnHook = (event: PostTurnEvent) => void | Promise<void>;
+type PreToolCallHook = (event: PreToolCallEvent$1) => void | Promise<void>;
+type PostToolCallHook = (event: PostToolCallEvent$1) => void | Promise<void>;
+/**
+ * Stop hook — fires after each turn. Can return `{ preventContinuation: true }`
+ * to stop the run gracefully. Ported from La-Machina's executeStopHooks().
+ */
+type StopHook = (event: StopHookEvent) => StopHookResult | void | Promise<StopHookResult | void>;
+/**
+ * Gate hook signature — synchronous or async. Receives the tool name and
+ * the validated input, returns a `GateDecision`. Distinct from the other
+ * hook slots because its return value drives pause/resume behavior.
+ */
+type GateBeforeToolHook = (toolName: string, input: unknown) => GateDecision$1 | Promise<GateDecision$1>;
+
+/**
+ * MCP config types.
+ *
+ * Three transport variants (discriminated on `type`):
+ *   - `stdio` — subprocess spawning, most common
+ *   - `http`  — Streamable HTTP (modern MCP spec, preferred for cloud)
+ *   - `sse`   — Server-Sent Events (legacy, still in use by many servers)
+ */
+interface McpToolDef {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+}
+interface McpCallResult {
+    readonly content: string;
+    readonly isError?: boolean;
+}
+type McpServerState = 'uninitialized' | 'connecting' | 'connected' | 'failed' | 'disconnected';
+interface ResolvedMcpStdioServerConfig {
+    readonly type: 'stdio';
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly env: Readonly<Record<string, string>> | undefined;
+    readonly cwd: string | undefined;
+    readonly isolateEnv: boolean;
+    /** See `ResolvedMcpHttpServerConfig.allowSampling`. */
+    readonly allowSampling?: boolean | undefined;
+}
+interface ResolvedMcpHttpServerConfig {
+    readonly type: 'http';
+    /** Full URL of the MCP server endpoint, e.g. `https://mcp.example.com/v1`. */
+    readonly url: string;
+    /** Optional headers sent on every request (auth tokens, API keys). */
+    readonly headers: Readonly<Record<string, string>> | undefined;
+    /**
+     * Use the Workers-friendly plain-POST transport (`BindingHttpTransport`)
+     * instead of the default `StreamableHTTPClientTransport`. Enable when
+     * running on Cloudflare Workers — the SDK's streaming transport can
+     * hang on Workers after `initialize`. Default: false.
+     */
+    readonly preferBindingTransport?: boolean | undefined;
+    /**
+     * Per-request dynamic header provider. When set, called before every
+     * MCP send and its result is merged OVER the static `headers`. Use
+     * for OAuth tokens that need refresh. On HTTP 401 the engine invokes
+     * the provider a second time and retries the request once.
+     *
+     * Must be idempotent — may be called many times per run. Not called
+     * for stdio servers (their env is immutable post-spawn).
+     */
+    readonly headersProvider?: (() => Promise<Readonly<Record<string, string>>>) | undefined;
+    /**
+     * Allow this server to request LLM completions via MCP's
+     * `sampling/createMessage`. OFF by default — sampling consumes the
+     * engine's LLM budget, so opt-in is explicit per server. See Plan 018 §2.
+     */
+    readonly allowSampling?: boolean | undefined;
+}
+interface ResolvedMcpSseServerConfig {
+    readonly type: 'sse';
+    /** Full URL of the SSE endpoint, e.g. `https://mcp.example.com/sse`. */
+    readonly url: string;
+    /** Optional headers sent on every request. */
+    readonly headers: Readonly<Record<string, string>> | undefined;
+    /** See `ResolvedMcpHttpServerConfig.headersProvider`. */
+    readonly headersProvider?: (() => Promise<Readonly<Record<string, string>>>) | undefined;
+    /** See `ResolvedMcpHttpServerConfig.allowSampling`. */
+    readonly allowSampling?: boolean | undefined;
+}
+type ResolvedMcpServerConfig = ResolvedMcpStdioServerConfig | ResolvedMcpHttpServerConfig | ResolvedMcpSseServerConfig;
+interface ResolvedMcpConfig {
+    readonly servers: Readonly<Record<string, ResolvedMcpServerConfig>>;
+    readonly connectTimeoutMs: number;
+    readonly callTimeoutMs: number;
+    /** Timeout for shutdownAll() before force-killing servers. Default: 5000. */
+    readonly shutdownTimeoutMs: number;
+}
+
+/**
+ * Permission system types.
+ *
+ * Three modes:
+ *   - `'open'`   — every tool is allowed (v0.1 behavior, default)
+ *   - `'rules'`  — evaluate rule strings in order, first match wins
+ *   - `'locked'` — only safe-allowlist tools pass, everything else denied
+ *
+ * Rule syntax:
+ *   - `'allow:Read'`          — allow the Read tool
+ *   - `'deny:Bash'`           — deny the Bash tool
+ *   - `'allow:mcp__fs__*'`    — glob: allow all tools from the fs MCP server
+ *   - `'deny:*'`              — deny everything not explicitly allowed above
+ *
+ * Rules are evaluated top-to-bottom. The first matching rule wins. If no
+ * rule matches, the decision falls to the mode's default:
+ *   - `'rules'` mode → deny (fall-closed)
+ *   - `'open'` mode  → allow (rules are informational only)
+ *   - `'locked'` mode → rules field is ignored entirely
+ */
+type PermissionMode = 'open' | 'rules' | 'locked';
+type PermissionAction = 'allow' | 'deny';
+interface PermissionRule {
+    readonly action: PermissionAction;
+    readonly pattern: string;
+}
+type PermissionDecision = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly reason: string;
+};
+interface ResolvedPermissionsConfig {
+    readonly mode: PermissionMode;
+    readonly rules: readonly string[];
+}
+
+/** Placeholder for the Phase 5 tool contract. */
+type Tool = unknown;
+/**
+ * Structured log record emitted by the engine to `config.logging.sink`.
+ * `ts` is an ISO-8601 timestamp. `meta` is any caller-supplied context.
+ */
+interface LogEntry {
+    readonly level: LogLevel;
+    readonly msg: string;
+    readonly ts: string;
+    readonly meta?: Record<string, unknown>;
+}
+type ModelProvider = 'anthropic' | 'openai' | 'google' | 'openai-compatible' | 'bedrock' | 'vertex' | 'proxy';
+type StorageProvider = 'local' | 'r2' | 'r2-binding';
+type MemoryMode = 'off' | 'read-only' | 'read-write';
+type MemoryScope = 'workspace' | 'global';
+type FlushPolicy = 'turn-end' | 'entry' | 'manual';
+type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+type LogSink = 'stderr' | 'none' | ((entry: LogEntry) => void);
+interface ResolvedR2Config {
+    readonly bucket: string;
+    readonly region: string;
+    readonly accessKeyId: string;
+    readonly secretAccessKey: string;
+    readonly endpoint?: string | undefined;
+}
+interface ResolvedModelConfig {
+    readonly provider: ModelProvider;
+    readonly modelId: string;
+    readonly apiKey: string;
+    readonly baseURL?: string | undefined;
+    readonly maxTokens: number;
+    readonly temperature: number;
+    /** Max retries on transient API errors (429, 500). 0 = no retry. Default: 2. */
+    readonly maxRetries: number;
+}
+interface ResolvedStorageConfig {
+    readonly provider: StorageProvider;
+    readonly rootPath: string;
+    readonly workspaceId: string;
+    readonly r2?: ResolvedR2Config | undefined;
+    /**
+     * Cloudflare R2 binding object (env.BUCKET) — required when
+     * provider === 'r2-binding'. Structurally: { head, get, put, delete, list }.
+     * Not serializable — kept as-is and used only inside the factory.
+     */
+    readonly r2Binding?: R2BucketBinding | undefined;
+}
+interface ResolvedMemoryConfig {
+    readonly mode: MemoryMode;
+    readonly scope: MemoryScope;
+}
+interface ResolvedToolsConfig {
+    readonly enabled: readonly string[];
+    readonly disabled: readonly string[];
+    readonly custom: readonly Tool[];
+}
+interface ResolvedAgentsConfig {
+    readonly builtins: readonly string[];
+    readonly customPath?: string | undefined;
+}
+interface ResolvedSkillsConfig {
+    readonly path?: string | undefined;
+    readonly autoload: boolean;
+    /**
+     * SSRF allowlist for per-run `InlineSkillSource` URL fetches.
+     * When undefined / empty, any URL is allowed (development default).
+     * Production deployments should set this to their CDN / R2 host(s).
+     */
+    readonly allowedHosts?: readonly string[] | undefined;
+}
+interface ResolvedExecutionConfig {
+    readonly maxTurns: number;
+    readonly maxSubagentDepth: number;
+    readonly turnTimeoutMs: number;
+    readonly runTimeoutMs: number;
+    /** Context window size in tokens. Used by compaction to decide when to compact. Default: 200_000. */
+    readonly contextLimit: number;
+    /** Max number of concurrency-safe tools to execute in parallel. Default: 10. */
+    readonly maxToolConcurrency: number;
+}
+interface ResolvedTranscriptConfig {
+    readonly enabled: boolean;
+    readonly flushPolicy: FlushPolicy;
+    readonly idleFlushMs: number;
+}
+interface ResolvedHooksConfig {
+    readonly preRun: readonly PreRunHook[];
+    readonly postRun: readonly PostRunHook[];
+    readonly preTurn: readonly PreTurnHook[];
+    readonly postTurn: readonly PostTurnHook[];
+    readonly preToolCall: readonly PreToolCallHook[];
+    readonly postToolCall: readonly PostToolCallHook[];
+    /**
+     * Optional gate called before every tool dispatch. Returning
+     * `{ allow: false, reason? }` pauses the run with the pending tool
+     * captured in the snapshot. `undefined` means no gate — the default.
+     *
+     * This is the only real pause pathway in v0.1. Setting this enables
+     * human-in-the-loop workflows without bypassing `initEngine()`.
+     */
+    readonly gateBeforeTool: GateBeforeToolHook | undefined;
+    /**
+     * When true, the parent's gate propagates into every spawned
+     * subagent's inner loop. A gate denial inside the child pauses the
+     * parent run with `RunSnapshot.pendingSubagent` populated so
+     * observers can see which subagent tool was blocked. Default: false.
+     *
+     * Only the parent engine reads this flag; subagents don't re-read it.
+     * The `Agent` tool factory receives the effective gate callback at
+     * construction time.
+     */
+    readonly propagateGateToSubagents?: boolean | undefined;
+    /**
+     * Stop hooks — fire after each turn. Can return `{ preventContinuation: true }`
+     * to stop the run gracefully. Ported from La-Machina's executeStopHooks().
+     */
+    readonly stopHooks: readonly StopHook[];
+}
+interface ResolvedLoggingConfig {
+    readonly level: LogLevel;
+    readonly sink: LogSink;
+}
+interface ResolvedConfig {
+    readonly model: ResolvedModelConfig;
+    readonly storage: ResolvedStorageConfig;
+    readonly memory: ResolvedMemoryConfig;
+    readonly tools: ResolvedToolsConfig;
+    readonly agents: ResolvedAgentsConfig;
+    readonly skills: ResolvedSkillsConfig;
+    readonly execution: ResolvedExecutionConfig;
+    readonly transcript: ResolvedTranscriptConfig;
+    readonly hooks: ResolvedHooksConfig;
+    readonly logging: ResolvedLoggingConfig;
+    readonly mcp: ResolvedMcpConfig;
+    readonly permissions: ResolvedPermissionsConfig;
+    readonly compaction: ResolvedCompactionConfig;
+    readonly coordinator: ResolvedCoordinatorConfig;
+    readonly orchestrator: ResolvedOrchestratorConfig;
+}
+
+type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
+    -readonly [K in keyof T]?: DeepPartial<T[K]> | undefined;
+} : T;
+type UserConfig = DeepPartial<ResolvedConfig>;
+
+/**
+ * ModelAdapter — the interface every LLM provider must implement.
+ *
+ * Same pattern as StorageAdapter. The engine calls `streamMessage()`
+ * and gets back a normalized async generator of events. The adapter
+ * handles provider-specific HTTP translation behind the scenes.
+ *
+ * Two implementations ship:
+ *   - AnthropicAdapter  → @anthropic-ai/sdk (existing, default)
+ *   - AISdkAdapter      → Vercel AI SDK (75+ providers)
+ *
+ * NormalizedEvent and TokenUsage types come from api/streaming.ts —
+ * the canonical definitions. Adapters produce these; the agent loop
+ * consumes them. No duplicate type definitions.
+ */
+
+interface ModelToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+}
+interface ModelMessage {
+    readonly role: 'user' | 'assistant';
+    readonly content: unknown;
+}
+interface StreamRequest {
+    readonly messages: readonly ModelMessage[];
+    readonly system?: string | undefined;
+    readonly tools?: readonly ModelToolDefinition[] | undefined;
+    readonly maxTokens?: number | undefined;
+    readonly temperature?: number | undefined;
+}
+
+interface ModelAdapter {
+    streamMessage(request: StreamRequest): AsyncGenerator<NormalizedEvent, void, void>;
+}
+
+/**
+ * MCP sampling — Plan 018 §2.
+ *
+ * MCP servers can issue `sampling/createMessage` requests asking the
+ * *client* to run an LLM completion on their behalf. The canonical use
+ * case is a tool that needs to summarize / classify / structure some
+ * text internally without carrying its own API key.
+ *
+ * This module provides:
+ *
+ *   - `SamplingHandler` — the function callers can install via
+ *     `EngineInternals.samplingHandler` to customize routing.
+ *   - `defaultSamplingHandler(modelAdapter)` — a ready-to-use default
+ *     that routes every request to the engine's own model adapter.
+ *     Same model, same API key, same billing.
+ *   - Request/response shapes mirroring MCP's schema closely enough to
+ *     translate both directions without leaking SDK internals into the
+ *     rest of the engine.
+ *
+ * Safety: calling sampling is OFF by default per MCP server
+ * (`allowSampling: false`). When a server attempts sampling and the
+ * flag is off, the McpClient responds with a protocol error instead
+ * of invoking the handler. The handler itself is only called after
+ * the gate passes.
+ */
+
+/** Content block shape accepted from / sent to the MCP server. */
+interface SamplingTextBlock {
+    readonly type: 'text';
+    readonly text: string;
+}
+interface SamplingMessage {
+    readonly role: 'user' | 'assistant';
+    readonly content: SamplingTextBlock | ReadonlyArray<SamplingTextBlock>;
+}
+interface SamplingModelPreferences {
+    readonly hints?: ReadonlyArray<{
+        readonly name?: string;
+    }>;
+    readonly costPriority?: number;
+    readonly speedPriority?: number;
+    readonly intelligencePriority?: number;
+}
+interface SamplingRequest {
+    readonly messages: ReadonlyArray<SamplingMessage>;
+    readonly systemPrompt?: string;
+    readonly maxTokens: number;
+    readonly temperature?: number;
+    readonly stopSequences?: ReadonlyArray<string>;
+    readonly modelPreferences?: SamplingModelPreferences;
+    readonly includeContext?: 'none' | 'thisServer' | 'allServers';
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface SamplingResponse {
+    readonly role: 'assistant';
+    readonly model: string;
+    /** The assistant text. */
+    readonly content: SamplingTextBlock;
+    readonly stopReason?: 'endTurn' | 'stopSequence' | 'maxTokens' | 'error';
+}
+interface SamplingContext {
+    /** MCP server that issued the request. */
+    readonly serverName: string;
+    /** Engine runId for the run this handler was invoked inside. */
+    readonly runId?: string;
+    /** Engine nodeId for the run. */
+    readonly nodeId?: string;
+    /**
+     * Nesting depth — incremented when sampling itself triggers another
+     * sampling request. Guards against loops: handlers MAY refuse when
+     * `depth` exceeds a threshold (default implementation refuses at 3).
+     */
+    readonly depth: number;
+}
+type SamplingHandler = (request: SamplingRequest, context: SamplingContext) => Promise<SamplingResponse>;
+/** Max depth the default handler will recurse through. */
+declare const DEFAULT_SAMPLING_MAX_DEPTH = 3;
+/**
+ * Build a default handler that routes every sampling request to the
+ * provided `ModelAdapter`. Consumes the stream, concatenates the text
+ * blocks, and maps the stop reason into the MCP vocabulary.
+ *
+ * If you want a different model per server, provide a custom
+ * handler via `EngineInternals.samplingHandler`.
+ */
+declare function defaultSamplingHandler(modelAdapter: ModelAdapter): SamplingHandler;
+
+/**
+ * SubagentRegistry — tracks parent→child relationships across a single
+ * `engine.run()`. Mints unique `agentId`s, computes spawn depth, and
+ * enforces `maxDepth` so a runaway loop can't recursively spawn forever.
+ *
+ * The registry's lifetime is one engine run. A fresh instance is built
+ * inside `engine.run()` and shared with every Agent tool invocation
+ * during that run, including children that themselves spawn grandchildren.
+ *
+ * Tracking is in-memory only. We don't persist parent→child relationships
+ * to the transcript here — that's the runner's job, which writes
+ * `subagent_spawn` and `subagent_done` entries to the parent's transcript.
+ */
+interface SubagentRegistryOptions {
+    /** Maximum spawn depth. Depth 1 = a direct child of the root run. */
+    readonly maxDepth: number;
+}
+interface SpawnResult {
+    readonly agentId: string;
+    readonly depth: number;
+}
+/** Result from a background agent, stored on completion. */
+interface BackgroundAgentResult {
+    readonly agentId: string;
+    readonly output: string;
+    readonly isError: boolean;
+    readonly description?: string;
+}
+/** Serialized form for persistence alongside transcripts. */
+interface SerializedAgent {
+    readonly agentId: string;
+    readonly parentId: string | null;
+    readonly depth: number;
+    readonly name?: string;
+    readonly status: 'running' | 'stopped' | 'completed';
+}
+declare class SubagentRegistry {
+    private readonly maxDepth;
+    private readonly agents;
+    constructor(options: SubagentRegistryOptions);
+    /**
+     * Mint a new subagent under `parentAgentId` (null = direct child of
+     * the root run). Throws if the resulting depth would exceed `maxDepth`.
+     */
+    spawn(parentAgentId: string | null): SpawnResult;
+    getDepth(agentId: string): number;
+    getParent(agentId: string): string | null;
+    count(): number;
+    /** Set a human-readable name for routing (e.g. subagent_type or task description). */
+    setName(agentId: string, name: string): void;
+    /** Find an agent by its human-readable name. Returns the first match. */
+    findByName(name: string): string | undefined;
+    setStatus(agentId: string, status: 'running' | 'stopped' | 'completed'): void;
+    getStatus(agentId: string): 'running' | 'stopped' | 'completed';
+    /** Queue a message for a running agent. */
+    queueMessage(agentId: string, message: string): void;
+    /** Drain all pending messages. Returns empty array if none. */
+    drainMessages(agentId: string): string[];
+    /** Mark an agent as background (fire-and-forget). */
+    setBackground(agentId: string): void;
+    /** Track a background agent's Promise for drain-before-pause. */
+    setBackgroundPromise(agentId: string, promise: Promise<void>): void;
+    /** Store a background agent's result on completion. */
+    setBackgroundResult(agentId: string, result: BackgroundAgentResult): void;
+    /**
+     * Drain all completed background agent results. Returns them and
+     * clears the stored results so they're only delivered once.
+     * Called at the top of each turn in agentLoop.
+     */
+    drainCompletedBackgroundResults(): BackgroundAgentResult[];
+    /**
+     * Wait for all running background agents to complete (with timeout).
+     * Called before pause to drain in-flight work. Returns results from
+     * agents that finished within the timeout.
+     */
+    awaitBackgroundAgents(timeoutMs?: number): Promise<BackgroundAgentResult[]>;
+    /** Serialize all agents for sidecar persistence. */
+    toJSON(): SerializedAgent[];
+    /** Rebuild registry from serialized data (e.g. on resume). */
+    static fromJSON(data: SerializedAgent[], maxDepth: number): SubagentRegistry;
+    private requireAgent;
+}
+
+/**
+ * Smart memory type definitions.
+ *
+ * The Engram is the fundamental unit of memory — named for Karl Lashley's
+ * concept of the physical substrate of a memory trace. Each engram has a
+ * kind (always / never / when / lesson / profile), a scope (global vs.
+ * workspace), a confidence level, and a topic.
+ */
+type EngramKind = 'always' | 'never' | 'when' | 'lesson' | 'profile';
+type EngramScope = 'global' | 'workspace';
+type EngramConfidence = 'high' | 'medium' | 'low';
+type EngramSource = 'user' | 'consolidation' | 'llm';
+interface Engram {
+    readonly text: string;
+    readonly kind: EngramKind;
+    readonly scope: EngramScope;
+    readonly confidence: EngramConfidence;
+    readonly topic: string;
+    readonly source: EngramSource;
+}
+/**
+ * Episodic memory entry — a single turn snapshot. JSONL-encoded for
+ * append-only logging via the storage adapter.
+ */
+interface Episode {
+    readonly ts: string;
+    readonly session: string;
+    readonly turn: number;
+    readonly role: 'user' | 'assistant' | 'tool_call' | 'tool_result';
+    readonly content: string;
+    readonly meta: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * EpisodicMemory — append-only JSONL log of every turn in a run.
+ *
+ * Ported from La-Machina with TS-strict cleanup. The episodic log
+ * captures the raw timeline of conversation turns (user input,
+ * assistant text, tool calls, tool results) for later inspection,
+ * search, or training data extraction.
+ *
+ * Design rules:
+ * - **Fire-and-forget**: `logTurn()` returns synchronously and never
+ *   throws. Storage errors are swallowed so logging cannot break the
+ *   agent loop.
+ * - **Disabled = total no-op**: when `enabled` is false, no file is
+ *   created and `logTurn()` does nothing. Used to implement
+ *   `memory.mode === 'off'` at the engine config layer.
+ * - **Per-session file**: each `startSession()` mints a fresh JSONL
+ *   under `{subdir}/{sessionId}.jsonl`. Format `YYYYMMDD_HHMMSS`.
+ * - **Truncation**: tool_call and tool_result content is capped at
+ *   2000 characters to keep individual entries small.
+ */
+
+declare class EpisodicMemory {
+    private readonly storage;
+    private readonly subdir;
+    private _enabled;
+    private _sessionId;
+    private _filePath;
+    /**
+     * Serialization chain — every log() chains its appendFile onto the
+     * previous one so on-disk order matches call order. Without this,
+     * two concurrent unawaited appendFile calls can land in arbitrary
+     * order even though each individual O_APPEND is atomic.
+     */
+    private writeChain;
+    constructor(storage: StorageAdapter, subdir?: string, enabled?: boolean);
+    get enabled(): boolean;
+    set enabled(value: boolean);
+    get currentSessionId(): string | null;
+    /**
+     * Start a new session — mints a timestamp-based id and creates an
+     * empty JSONL file under `{subdir}/`. Returns the session id, or
+     * empty string if disabled.
+     */
+    startSession(): Promise<string>;
+    resumeSession(sessionId: string): Promise<string>;
+    /**
+     * Log a single episode entry. Fire-and-forget — never blocks, never
+     * throws. Disabled mode and missing session both produce silent
+     * no-ops so callers don't have to guard.
+     */
+    log(episode: Episode): void;
+    /** Convenience wrapper that builds an Episode and logs it. */
+    logTurn(turn: number, role: Episode['role'], content: string, meta?: Readonly<Record<string, unknown>>): void;
+}
+
+/**
+ * Transcript entry types and schemas.
+ *
+ * A transcript is a sequence of `Entry` records persisted as newline-
+ * delimited JSON (NDJSON) sharded across numbered `.jsonl` files. This
+ * module defines the entry type union, their Zod schemas, and the
+ * serialize/parse helpers used by the writer and reader.
+ *
+ * The entry vocabulary is deliberately minimal — seven types. Everything
+ * CLI-UX-specific in La-Machina's 19-type union has been dropped. Only
+ * what a workflow engine needs to replay, audit, and learn from:
+ *
+ *   user            — user message (prompt, tool result from the client)
+ *   assistant       — assistant message (text + tool_use blocks)
+ *   tool_result     — result of a tool call dispatched by the engine
+ *   subagent_spawn  — a child agent was created
+ *   subagent_done   — a child agent returned its final output
+ *   meta            — session-scoped metadata (title, tags, workflow ctx)
+ *   error           — engine-level failure (tool crash, stream break, etc.)
+ */
+
+declare const EntrySchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    message: z.ZodObject<{
+        role: z.ZodEnum<["user", "assistant"]>;
+        content: z.ZodArray<z.ZodUnknown, "many">;
+    }, "strict", z.ZodTypeAny, {
+        role: "user" | "assistant";
+        content: unknown[];
+    }, {
+        role: "user" | "assistant";
+        content: unknown[];
+    }>;
+    uuid: z.ZodString;
+    parentUuid: z.ZodNullable<z.ZodString>;
+    ts: z.ZodString;
+    type: z.ZodLiteral<"user">;
+}, "strict", z.ZodTypeAny, {
+    type: "user";
+    message: {
+        role: "user" | "assistant";
+        content: unknown[];
+    };
+    uuid: string;
+    parentUuid: string | null;
+    ts: string;
+}, {
+    type: "user";
+    message: {
+        role: "user" | "assistant";
+        content: unknown[];
+    };
+    uuid: string;
+    parentUuid: string | null;
+    ts: string;
+}>, z.ZodObject<{
+    message: z.ZodObject<{
+        role: z.ZodEnum<["user", "assistant"]>;
+        content: z.ZodArray<z.ZodUnknown, "many">;
+    }, "strict", z.ZodTypeAny, {
+        role: "user" | "assistant";
+        content: unknown[];
+    }, {
+        role: "user" | "assistant";
+        content: unknown[];
+    }>;
+    uuid: z.ZodString;
+    parentUuid: z.ZodNullable<z.ZodString>;
+    ts: z.ZodString;
+    type: z.ZodLiteral<"assistant">;
+}, "strict", z.ZodTypeAny, {
+    type: "assistant";
+    message: {
+        role: "user" | "assistant";
+        content: unknown[];
+    };
+    uuid: string;
+    parentUuid: string | null;
+    ts: string;
+}, {
+    type: "assistant";
+    message: {
+        role: "user" | "assistant";
+        content: unknown[];
+    };
+    uuid: string;
+    parentUuid: string | null;
+    ts: string;
+}>, z.ZodObject<{
+    toolUseId: z.ZodString;
+    content: z.ZodUnknown;
+    isError: z.ZodOptional<z.ZodBoolean>;
+    uuid: z.ZodString;
+    parentUuid: z.ZodNullable<z.ZodString>;
+    ts: z.ZodString;
+    type: z.ZodLiteral<"tool_result">;
+}, "strict", z.ZodTypeAny, {
+    type: "tool_result";
+    uuid: string;
+    toolUseId: string;
+    parentUuid: string | null;
+    ts: string;
+    content?: unknown;
+    isError?: boolean | undefined;
+}, {
+    type: "tool_result";
+    uuid: string;
+    toolUseId: string;
+    parentUuid: string | null;
+    ts: string;
+    content?: unknown;
+    isError?: boolean | undefined;
+}>, z.ZodObject<{
+    agentId: z.ZodString;
+    agentType: z.ZodString;
+    uuid: z.ZodString;
+    parentUuid: z.ZodNullable<z.ZodString>;
+    ts: z.ZodString;
+    type: z.ZodLiteral<"subagent_spawn">;
+}, "strict", z.ZodTypeAny, {
+    type: "subagent_spawn";
+    uuid: string;
+    agentId: string;
+    parentUuid: string | null;
+    ts: string;
+    agentType: string;
+}, {
+    type: "subagent_spawn";
+    uuid: string;
+    agentId: string;
+    parentUuid: string | null;
+    ts: string;
+    agentType: string;
+}>, z.ZodObject<{
+    agentId: z.ZodString;
+    output: z.ZodString;
+    uuid: z.ZodString;
+    parentUuid: z.ZodNullable<z.ZodString>;
+    ts: z.ZodString;
+    type: z.ZodLiteral<"subagent_done">;
+}, "strict", z.ZodTypeAny, {
+    type: "subagent_done";
+    uuid: string;
+    output: string;
+    agentId: string;
+    parentUuid: string | null;
+    ts: string;
+}, {
+    type: "subagent_done";
+    uuid: string;
+    output: string;
+    agentId: string;
+    parentUuid: string | null;
+    ts: string;
+}>, z.ZodObject<{
+    key: z.ZodString;
+    value: z.ZodUnknown;
+    uuid: z.ZodString;
+    ts: z.ZodString;
+    type: z.ZodLiteral<"meta">;
+}, "strict", z.ZodTypeAny, {
+    type: "meta";
+    uuid: string;
+    ts: string;
+    key: string;
+    value?: unknown;
+}, {
+    type: "meta";
+    uuid: string;
+    ts: string;
+    key: string;
+    value?: unknown;
+}>, z.ZodObject<{
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        stack: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        code: string;
+        message: string;
+        stack?: string | undefined;
+    }, {
+        code: string;
+        message: string;
+        stack?: string | undefined;
+    }>;
+    uuid: z.ZodString;
+    ts: z.ZodString;
+    type: z.ZodLiteral<"error">;
+}, "strict", z.ZodTypeAny, {
+    type: "error";
+    error: {
+        code: string;
+        message: string;
+        stack?: string | undefined;
+    };
+    uuid: string;
+    ts: string;
+}, {
+    type: "error";
+    error: {
+        code: string;
+        message: string;
+        stack?: string | undefined;
+    };
+    uuid: string;
+    ts: string;
+}>]>;
+type Entry = z.infer<typeof EntrySchema>;
+
+/**
+ * TranscriptMeta — the small sidecar at `{logPath}/meta.json` that the
+ * writer updates on every flush.
+ *
+ * The meta document serves two purposes:
+ * 1. **Fast session listing**: upstream callers (Nikaido, dashboard)
+ *    can stat this file to know turn count, status, and last update
+ *    without reading the transcript shards.
+ * 2. **Resume anchor**: on pause/resume, the snapshot points to the
+ *    last shard index recorded here, letting the reader skip straight
+ *    to where it left off.
+ *
+ * The document is tiny (<1KB) and written frequently, so the cost of
+ * overwriting on every flush is negligible. Writes go through the
+ * storage adapter's atomic `writeFile`.
+ */
+
+type TranscriptStatus = 'pending' | 'running' | 'paused' | 'done' | 'failed';
+declare const TranscriptMetaSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    status: z.ZodEnum<["pending", "running", "paused", "done", "failed"]>;
+    startedAt: z.ZodString;
+    updatedAt: z.ZodString;
+    turnCount: z.ZodNumber;
+    messageCount: z.ZodNumber;
+    lastShardIndex: z.ZodNullable<z.ZodNumber>;
+    shardCount: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    status: "paused" | "done" | "failed" | "running" | "pending";
+    version: 1;
+    messageCount: number;
+    lastShardIndex: number | null;
+    startedAt: string;
+    updatedAt: string;
+    turnCount: number;
+    shardCount: number;
+}, {
+    status: "paused" | "done" | "failed" | "running" | "pending";
+    version: 1;
+    messageCount: number;
+    lastShardIndex: number | null;
+    startedAt: string;
+    updatedAt: string;
+    turnCount: number;
+    shardCount: number;
+}>;
+type TranscriptMeta = z.infer<typeof TranscriptMetaSchema>;
+
+/**
+ * Permission evaluator — the decision pipeline.
+ *
+ * Pipeline (evaluated in order, first match wins):
+ *
+ *   1. Mode check:
+ *      - `'open'`   → allow immediately (no further evaluation)
+ *      - `'locked'` → check allowlist only (skip rules entirely)
+ *      - `'rules'`  → proceed to step 2
+ *
+ *   2. Safe-tool allowlist fast-path:
+ *      - If the tool is on the safe allowlist → allow (skip rules)
+ *
+ *   3. Rule evaluation (top-to-bottom):
+ *      - First matching rule wins
+ *      - `allow:X` → allow
+ *      - `deny:X`  → deny with reason
+ *
+ *   4. Fall-closed:
+ *      - If no rule matched → deny ("no matching rule, mode is rules")
+ *
+ * The evaluator is a pure function: no side effects, no LLM calls.
+ * The gate hook (`hooks.gateBeforeTool`) runs AFTER this evaluation in
+ * the engine's tool dispatch — it can override a permission allow with
+ * a pause, but it cannot override a permission deny.
+ */
+
+/**
+ * Compiled permission policy — call `check(toolName)` to get a decision.
+ * Built once at engine construction time from the resolved config.
+ */
+interface PermissionPolicy {
+    check(toolName: string): PermissionDecision;
+}
+/**
+ * Build a `PermissionPolicy` from a resolved config. The returned
+ * object is reusable across all runs on the same engine instance.
+ */
+declare function buildPermissionPolicy(config: ResolvedPermissionsConfig): PermissionPolicy;
+
+/**
+ * ToolExecutor — runs tools by name with input validation, timeouts,
+ * cancellation, error isolation, and lifecycle hooks.
+ *
+ * Responsibilities:
+ * 1. Resolve a tool by name from a `ToolRegistry`. Unknown name →
+ *    typed error result, never an exception.
+ * 2. Validate the caller-supplied input against the tool's Zod schema.
+ *    Invalid input → typed error result.
+ * 3. Build a `ToolContext` with an `AbortSignal` that fires on either
+ *    timeout or external cancellation.
+ * 4. Race the tool's `execute()` against `timeoutMs` (when set). On
+ *    timeout, return an error result and abort the context signal.
+ * 5. Catch any synchronous or asynchronous throw from the tool and
+ *    wrap it as `{ content, isError: true }`. **A misbehaving tool
+ *    must never crash the agent loop.**
+ * 6. Fire `preToolCall` and `postToolCall` hooks. `postToolCall` runs
+ *    in a finally semantic — even on error, even on timeout. Hook
+ *    failures are isolated; they never propagate.
+ *
+ * The executor is stateless except for the registry reference; a
+ * single instance per engine run is fine.
+ */
+
+interface PreToolCallEvent {
+    readonly toolName: string;
+    readonly input: unknown;
+}
+interface PostToolCallEvent {
+    readonly toolName: string;
+    readonly input: unknown;
+    readonly result: ToolResult;
+    readonly durationMs: number;
+}
+interface ToolExecutorHooks {
+    readonly preToolCall?: (event: PreToolCallEvent) => void | Promise<void>;
+    readonly postToolCall?: (event: PostToolCallEvent) => void | Promise<void>;
+}
+interface ToolExecutorOptions {
+    readonly registry: ToolRegistry;
+    /** Per-call timeout in milliseconds. Omit or 0 to disable. */
+    readonly timeoutMs?: number;
+    readonly hooks?: ToolExecutorHooks;
+    /** Permission policy. When set, every tool dispatch is checked before
+     *  execution. Denied tools get an isError result without running. */
+    readonly permissions?: PermissionPolicy;
+}
+interface ExecuteOptions {
+    /** Optional external AbortSignal that can cancel the tool early. */
+    readonly signal?: AbortSignal;
+}
+declare class ToolExecutor {
+    private readonly registry;
+    private readonly timeoutMs;
+    private readonly hooks;
+    private readonly permissions;
+    constructor(options: ToolExecutorOptions);
+    execute(toolName: string, rawInput: unknown, options?: ExecuteOptions): Promise<ToolResult>;
+    private executeInner;
+    private runWithTimeout;
+    private firePreHook;
+    private firePostHook;
+}
+
+/**
+ * SkillSource — abstraction over skill discovery and lazy body loading.
+ *
+ * Two implementations live alongside this file:
+ *   - `StorageSkillSource` (storageSkillSource.ts) — reads `SKILL.md`
+ *     files from a storage adapter (the current default behavior).
+ *   - `InlineSkillSource` (inlineSkillSource.ts) — takes an explicit
+ *     list of overrides passed per-run via `RunOptions.skills`.
+ *
+ * Downstream code (prompt builder, SkillPage tool) accepts `SkillSource`
+ * rather than reaching into storage directly, so the two paths share
+ * every contract: model sees the same catalogue, `SkillPage` returns
+ * bodies the same way, and errors surface the same error shape.
+ */
+/**
+ * Minimal descriptor the system prompt needs to list a skill. The full
+ * body stays unloaded until `getSkillFile` / `getPage` is invoked.
+ */
+interface ResolvedSkill {
+    /** Unique identifier — `[a-zA-Z0-9_-]+`. */
+    readonly name: string;
+    /** One-line human description. Rendered in the system prompt catalogue. */
+    readonly description: string;
+    /** True when supplemental `pages/*.md` are available. */
+    readonly hasPages: boolean;
+}
+/**
+ * Pluggable skill source used by the engine at run time.
+ *
+ * - `list()` runs once at run start. Cheap — names + descriptions only.
+ * - `getSkillFile()` / `getPage()` are invoked by the `SkillPage` tool
+ *   when the model decides a skill is relevant. They MAY fetch from the
+ *   network; they SHOULD cache within a run.
+ *
+ * Implementations MUST return `null` for unknown skills / pages (never
+ * throw for "not found"). They MAY throw for infrastructure failures
+ * (fetch errors, disallowed hosts) — the `SkillPage` tool converts
+ * those to tool errors.
+ */
+interface SkillSource {
+    /** Enumerate available skills. Safe to call multiple times per run. */
+    list(): Promise<ReadonlyArray<ResolvedSkill>>;
+    /** Load the main `SKILL.md` body for a skill. `null` if unknown. */
+    getSkillFile(skill: string): Promise<string | null>;
+    /** Load a named page for a skill. `null` if skill or page is unknown. */
+    getPage(skill: string, page: string): Promise<string | null>;
+    /**
+     * Return the list of page names available for a skill. Used by the
+     * `SkillPage` tool to render a "did you mean?" suggestion when a page
+     * name misses. Returns `[]` for unknown skills or skills with no pages.
+     */
+    listPages(skill: string): Promise<ReadonlyArray<string>>;
+}
+/**
+ * Shape the caller passes to `RunOptions.skills` / `ResumeOptions.skills`
+ * to override disk-based discovery for exactly this run.
+ *
+ * Rules:
+ * - `name` must match `/^[a-zA-Z0-9_-]+$/` — rejected at construction.
+ * - `description` is required (needed for the prompt catalogue without fetch).
+ * - Either `body` OR `url` for the main file. `body` wins when both set.
+ *   Omitting both is valid — the skill is listed but reading it errors.
+ * - `pages` follow the same `body`/`url` rules per-page.
+ * - `headers` travel with both the main fetch and every page fetch.
+ */
+interface SkillOverride {
+    readonly name: string;
+    readonly description: string;
+    readonly body?: string;
+    readonly url?: string;
+    readonly pages?: Readonly<Record<string, SkillPageOverride>>;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+interface SkillPageOverride {
+    readonly body?: string;
+    readonly url?: string;
+}
+
+/**
+ * Engine-facing types for `run()` and `resume()`.
+ *
+ * Phase 1 defines the interface shapes. Actual behavior (streaming, tool
+ * calls, pause/resume logic) arrives in Phases 7–10. These types are
+ * exported from the public API so callers can compile against them.
+ */
+interface RunOptions {
+    /** Unique run identifier. Optional — auto-generated as `run_<uuid>` if omitted. */
+    readonly runId?: string;
+    readonly nodeId: string;
+    readonly task: string;
+    readonly tools?: readonly string[] | undefined;
+    readonly context?: Readonly<Record<string, unknown>> | undefined;
+    /** Override maxTurns for this run only. Used by the orchestrator for per-phase budgets. */
+    readonly maxTurns?: number | undefined;
+    /**
+     * Token budget for this run. When total tokens used (input + output)
+     * exceeds this value, the run stops gracefully with the last assistant
+     * output. Ported from La-Machina's task_budget enforcement.
+     */
+    readonly tokenBudget?: number | undefined;
+    /**
+     * Output format. Default: 'text'.
+     * - 'text': model responds freely, result.output is raw string
+     * - 'json': engine injects schema instructions into system prompt,
+     *   parses the model's final response as JSON, validates against
+     *   outputSchema if provided, retries once on failure.
+     *   result.data contains the parsed+validated value.
+     */
+    readonly outputFormat?: 'text' | 'json' | undefined;
+    /**
+     * Zod schema for structured output. Only used when outputFormat is 'json'.
+     * Injected into system prompt as JSON Schema description, used to
+     * validate the model's response. If validation fails, retries once.
+     */
+    readonly outputSchema?: zod.ZodTypeAny | undefined;
+    /**
+     * Per-run skill override (Plan 017). When present, the engine IGNORES
+     * `config.skills.autoload` + `config.skills.path` and uses this list
+     * instead. Each override carries a description (always required) plus
+     * either an inline `body` or an HTTPS `url` that is fetched on demand
+     * by the `SkillPage` tool.
+     */
+    readonly skills?: ReadonlyArray<SkillOverride> | undefined;
+}
+interface TokenUsage {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheCreationInput?: number | undefined;
+    readonly cacheReadInput?: number | undefined;
+}
+/**
+ * Why a run paused.
+ *
+ * v0.1 only ever produces `'gate_required'` — that's the one path the agent
+ * loop uses to pause (`gateBeforeTool` callback returning `{ allow: false }`).
+ *
+ * The other three values are reserved for v0.2:
+ *   - `'max_turns'`  — currently returns `{ status: 'failed', error: ERR_MAX_TURNS }`
+ *                      instead. See `agentLoop.ts` + tests at
+ *                      `test/unit/engine/agentLoop.test.ts` and
+ *                      `test/integration/engine/run-with-mockapi.test.ts`.
+ *   - `'timeout'`    — `execution.runTimeoutMs` is declared but not enforced.
+ *   - `'explicit'`   — no explicit-pause API exists yet.
+ *
+ * Kept in the union so the v0.2 change is backwards-compatible (no type
+ * narrowing in callers that already switch on the full set).
+ */
+type PauseReason = 'gate_required' | 'subagent_gate_required' | 'max_turns' | 'explicit' | 'timeout';
+interface RunSnapshot {
+    readonly version: 1;
+    readonly status: 'paused';
+    readonly runId: string;
+    readonly nodeId: string;
+    readonly pausedAt: string;
+    readonly pauseReason: PauseReason;
+    readonly messageCount: number;
+    readonly lastShardIndex: number;
+    readonly lastMessageUuid: string;
+    readonly pendingToolCall?: {
+        toolName: string;
+        toolUseId: string;
+        input: unknown;
+        calledAt: string;
+    } | undefined;
+    /**
+     * Nested-pause pointer set when a subagent's own gate fired. The parent
+     * is paused on its Agent tool call; this field records the child's
+     * snapshot so observers can inspect which inner tool was blocked.
+     * Populated only when `hooks.propagateGateToSubagents: true`.
+     */
+    readonly pendingSubagent?: {
+        subagentType: string;
+        parentToolUseId: string;
+        childSnapshot: RunSnapshot;
+    } | undefined;
+    readonly tokensUsedSoFar: TokenUsage;
+    readonly turnsUsed: number;
+}
+interface TranscriptLocation {
+    readonly path: string;
+    readonly lastShardIndex: number;
+}
+type RunResult = {
+    readonly status: 'done';
+    readonly output: string;
+    /** Parsed + validated data when outputFormat is 'json'. Undefined for 'text' or if parsing failed. */
+    readonly data?: unknown;
+    readonly tokensUsed: TokenUsage;
+    readonly turns: number;
+} | {
+    readonly status: 'paused';
+    readonly snapshot: RunSnapshot;
+    readonly reason: PauseReason;
+} | {
+    readonly status: 'failed';
+    readonly error: Error;
+    readonly transcript: TranscriptLocation;
+};
+interface ResumeOptions {
+    /** The runId of the paused run. Engine loads snapshot from storage. */
+    readonly runId: string;
+    /** Optional nodeId to disambiguate if multiple nodes have paused under this runId. */
+    readonly nodeId?: string;
+    readonly gateAnswer?: unknown;
+    readonly outputFormat?: 'text' | 'json' | undefined;
+    readonly outputSchema?: zod.ZodTypeAny | undefined;
+    /**
+     * Optional: pass snapshot directly instead of loading from storage.
+     * Used internally and for advanced cases. Most clients should just pass runId.
+     */
+    readonly snapshot?: RunSnapshot;
+    /**
+     * Per-resume skill override (Plan 017). Mirrors `RunOptions.skills` —
+     * pass the same list you used on start() to keep tool availability
+     * consistent. Overrides are not persisted in the snapshot.
+     */
+    readonly skills?: ReadonlyArray<SkillOverride> | undefined;
+}
+
+/**
+ * Result of `gateBeforeTool` callback. `allow: true` runs the tool;
+ * `allow: false` pauses the run with the given reason. The pending
+ * tool call is captured in the snapshot.
+ */
+interface GateDecision {
+    readonly allow: boolean;
+    readonly reason?: string;
+}
+type GateBeforeTool = (toolName: string, input: unknown) => GateDecision | Promise<GateDecision>;
+/**
+ * Progress payload fired by `onProgress` at turn boundaries. Maps
+ * directly to `RunStateManager.RunProgress` on the engine side.
+ */
+interface LoopProgress {
+    /** Current turn index (1-based). */
+    readonly turns: number;
+    /** Cumulative token usage across all turns so far. */
+    readonly tokensUsed: TokenUsage$1;
+    /** What the loop is doing right now. */
+    readonly currentActivity: 'idle' | 'streaming' | 'tool_dispatch' | 'compacting';
+    /** Most recent tool name (when `currentActivity === 'tool_dispatch'`). */
+    readonly lastTool?: string;
+}
+interface ToolBatch {
+    concurrent: boolean;
+    calls: Array<{
+        id: string;
+        name: string;
+        input: unknown;
+    }>;
+}
+/**
+ * Partition tool calls into batches: consecutive concurrency-safe tools
+ * are grouped together for parallel execution; each unsafe tool becomes
+ * its own serial batch. Mirrors La-Machina's toolOrchestration.ts pattern.
+ */
+declare function partitionToolCalls(calls: ReadonlyArray<{
+    id: string;
+    name: string;
+    input: unknown;
+}>, registry?: ToolRegistry): ToolBatch[];
+
+/**
+ * EngineResponse — unified response shape for the public API.
+ *
+ * Every engine.run() and engine.resume() returns this single flat shape.
+ * Internal code uses RunResult (the discriminated union); this module
+ * converts it to the client-facing format.
+ *
+ * {
+ *   status: 'done' | 'paused' | 'failed',
+ *   data: any,           // user-defined — text or JSON from outputSchema
+ *   meta: { ... },       // tokens, turns, timing, snapshot, transcript
+ *   errors: [],           // structured error array
+ *   timestamp: number,    // unix ms
+ * }
+ */
+
+interface ResponseError {
+    readonly code: string;
+    readonly message: string;
+    readonly details?: unknown;
+}
+interface ResponseMeta {
+    readonly nodeId: string;
+    readonly turns?: number;
+    readonly tokensUsed?: TokenUsage;
+    readonly durationMs?: number;
+    readonly output?: string;
+    readonly snapshot?: RunSnapshot;
+    readonly pendingToolCall?: RunSnapshot['pendingToolCall'];
+    readonly pauseReason?: PauseReason;
+    readonly transcript?: TranscriptLocation;
+    /** Additional context-specific fields (e.g., activity, lastTool, cancelled). */
+    readonly [key: string]: unknown;
+}
+interface EngineResponse {
+    /** Unique run identifier — client's primary handle. Use this for resume. */
+    readonly runId: string;
+    readonly status: 'done' | 'paused' | 'failed' | 'queued' | 'running' | 'cancelled' | 'not_found';
+    readonly data: unknown;
+    readonly meta: ResponseMeta;
+    readonly errors: readonly ResponseError[];
+    readonly timestamp: number;
+}
+/**
+ * Convert internal RunResult to the unified EngineResponse shape.
+ */
+declare function toResponse(result: RunResult, extra: {
+    runId: string;
+    nodeId: string;
+    durationMs: number;
+    logPath?: string;
+}): EngineResponse;
+
+/**
+ * RunState — durable per-run state stored in state.json.
+ *
+ * Lives alongside transcript shards and snapshot.json:
+ *   projects/{runId}/nodes/{nodeId}/state.json
+ *
+ * Enables:
+ * - Async run tracking (getStatus, waitFor)
+ * - Crash recovery (detect orphaned running runs via stale heartbeat)
+ * - Webhook delivery history (retry tracking)
+ * - Full response persistence (data + meta + errors) — getStatus returns
+ *   the same shape as sync engine.run()
+ *
+ * All pure JS — no `node:` imports, Workers-compatible.
+ */
+
+type RunStatus = 'queued' | 'running' | 'paused' | 'done' | 'failed' | 'cancelled';
+interface RunProgress {
+    readonly turns: number;
+    readonly tokensUsed: TokenUsage;
+    readonly currentActivity: 'idle' | 'streaming' | 'tool_dispatch' | 'compacting';
+    readonly lastTool?: string;
+}
+type WebhookEvent = 'paused' | 'done' | 'failed';
+interface WebhookDelivery {
+    readonly id: string;
+    readonly event: WebhookEvent;
+    readonly attempt: number;
+    readonly scheduledAt: number;
+    readonly deliveredAt?: number;
+    readonly status: 'pending' | 'delivered' | 'failed';
+    readonly httpCode?: number;
+    readonly error?: string;
+}
+interface WebhookConfig {
+    readonly url: string;
+    readonly events: readonly WebhookEvent[];
+    readonly secret?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly deliveries: readonly WebhookDelivery[];
+}
+interface RunState {
+    readonly version: 1;
+    readonly runId: string;
+    readonly nodeId: string;
+    readonly status: RunStatus;
+    readonly startedAt: number;
+    readonly lastHeartbeat: number;
+    readonly progress: RunProgress;
+    readonly response: EngineResponse | null;
+    readonly webhook?: WebhookConfig;
+}
+/**
+ * Reads, writes, and updates state.json files via the storage adapter.
+ * Concurrent writes are NOT synchronized — callers are responsible for
+ * serializing updates (in practice: only one process writes per run).
+ */
+declare class RunStateManager {
+    private readonly storage;
+    constructor(storage: StorageAdapter);
+    private path;
+    write(state: RunState): Promise<void>;
+    read(runId: string, nodeId: string): Promise<RunState | null>;
+    /**
+     * Merge patch into current state and write back. Returns the new state.
+     * If no state exists, throws — use `write()` for initial creation.
+     */
+    update(runId: string, nodeId: string, patch: Partial<RunState>): Promise<RunState>;
+    /**
+     * Update just the heartbeat + progress (cheap, called every turn).
+     */
+    heartbeat(runId: string, nodeId: string, progress: Partial<RunProgress>): Promise<void>;
+    /**
+     * Mark terminal state with response. Used at end of run/resume.
+     */
+    finalize(runId: string, nodeId: string, response: EngineResponse): Promise<RunState>;
+    /**
+     * List all state files under a runId (one per node). Returns empty array
+     * if the runId directory doesn't exist.
+     */
+    scanRun(runId: string): Promise<RunState[]>;
+    /**
+     * Scan all state files and return those with stale heartbeats.
+     * Used by recoverOrphanedRuns().
+     */
+    findOrphaned(staleThresholdMs: number): Promise<RunState[]>;
+    /** Helper to build a fresh state for a new run. */
+    static initial(runId: string, nodeId: string, webhook?: WebhookConfig): RunState;
+}
+
+/**
+ * BackgroundExecutor — abstracts how async runs are dispatched.
+ *
+ * Node.js: NodeBackgroundExecutor uses `void Promise` fire-and-forget.
+ * Cloudflare Workers: user provides a DurableObjectExecutor (Worker-side
+ * code that dispatches to a DO with a longer execution budget).
+ *
+ * All pure JS — no `node:` imports, Workers-compatible.
+ */
+/**
+ * Contract for async run dispatch. Engine calls `schedule()` with a work
+ * function; executor is responsible for running it eventually.
+ */
+interface BackgroundExecutor {
+    /**
+     * Schedule a work function to run in the background. Must return
+     * immediately — the function will be invoked asynchronously.
+     *
+     * The returned AbortSignal fires if `cancel(runId)` is called.
+     * Work functions should pass this to agentLoop for early termination.
+     */
+    schedule(runId: string, work: (signal: AbortSignal) => Promise<void>): void;
+    /**
+     * Cancel a scheduled/running execution. Fires the AbortSignal so the
+     * work function can exit gracefully.
+     */
+    cancel(runId: string): Promise<void>;
+    /** True if this executor is currently tracking a run. */
+    isActive(runId: string): boolean;
+}
+/**
+ * Default Node.js implementation — fire-and-forget via `void` Promise.
+ * Works in Node, Bun, Deno. Does NOT work on Cloudflare Workers because
+ * the Worker instance terminates when the request handler returns.
+ */
+declare class NodeBackgroundExecutor implements BackgroundExecutor {
+    private readonly running;
+    schedule(runId: string, work: (signal: AbortSignal) => Promise<void>): void;
+    cancel(runId: string): Promise<void>;
+    isActive(runId: string): boolean;
+    /** For tests/observability — current count of running tasks. */
+    size(): number;
+}
+
+/** Config for webhook delivery when using async APIs. */
+interface WebhookOptions {
+    readonly url: string;
+    readonly secret?: string;
+    readonly events?: readonly WebhookEvent[];
+    readonly headers?: Record<string, string>;
+}
+/** Options for engine.start() — extends RunOptions with webhook. */
+interface StartOptions extends RunOptions {
+    readonly webhook?: WebhookOptions;
+}
+/** Options for engine.resumeAsync() — extends ResumeOptions with webhook. */
+interface ResumeAsyncOptions extends ResumeOptions {
+    readonly webhook?: WebhookOptions;
+}
+/** Options for engine.waitFor() — blocks until terminal state. */
+interface WaitForOptions {
+    readonly nodeId?: string;
+    readonly timeoutMs?: number;
+    readonly pollIntervalMs?: number;
+}
+interface EngineInternals {
+    /** Override the fetch implementation used by the API client. Tests only. */
+    readonly fetch?: typeof globalThis.fetch;
+    /**
+     * Optional pre-tool gate. When set, every tool dispatch is checked
+     * by this callback. Returning `{ allow: false }` pauses the run.
+     */
+    readonly gateBeforeTool?: GateBeforeTool;
+    /**
+     * Background executor for async runs (engine.start, engine.resumeAsync).
+     * Defaults to NodeBackgroundExecutor. On Cloudflare Workers, provide a
+     * DurableObjectExecutor that dispatches to a DO.
+     */
+    readonly backgroundExecutor?: BackgroundExecutor;
+    /**
+     * Override the storage factory. When set, the engine calls this
+     * instead of `createEngineStorage(config.storage)` for every run.
+     *
+     * Use this on Cloudflare Workers to build an `EngineStorage` pair
+     * backed by `R2BindingStorageAdapter` (which uses the native R2
+     * binding, not the S3 SDK). Example:
+     *
+     *   new Engine(config, {
+     *     buildStorage: async () => ({
+     *       global:    new R2BindingStorageAdapter(env.BUCKET, 'root/.claude'),
+     *       workspace: new R2BindingStorageAdapter(env.BUCKET, `root/workspaces/${ws}/.claude`),
+     *     }),
+     *   })
+     */
+    readonly buildStorage?: () => Promise<EngineStorage>;
+    /**
+     * Handler invoked when an MCP server with `allowSampling: true`
+     * requests an LLM completion via `sampling/createMessage`. Defaults
+     * to a handler that routes through the engine's own ModelAdapter
+     * (same API key, same billing). Override to route to a cheaper
+     * model, enforce budget limits, or refuse specific servers.
+     */
+    readonly samplingHandler?: SamplingHandler;
+}
+declare class Engine {
+    readonly config: ResolvedConfig;
+    private readonly internals;
+    private readonly mcpManager;
+    private readonly permissionPolicy;
+    private readonly backgroundExecutor;
+    private readonly webhookDispatcher;
+    constructor(config: ResolvedConfig, internals?: EngineInternals);
+    run(options: RunOptions): Promise<EngineResponse>;
+    resume(options: ResumeOptions): Promise<EngineResponse>;
+    /**
+     * Load a paused snapshot from storage using runId (and optional nodeId).
+     * If nodeId is not provided, finds the most recently paused node.
+     */
+    private loadSnapshot;
+    /**
+     * Start a run asynchronously. Writes initial state, schedules the run
+     * in the background, and returns immediately. Clients should track the
+     * returned runId and poll via `getStatus(runId)` or wait for a webhook.
+     *
+     * Workers compatibility: provide a DurableObjectExecutor via
+     * EngineInternals.backgroundExecutor — the default NodeBackgroundExecutor
+     * uses fire-and-forget Promises which won't survive Worker request exit.
+     */
+    start(options: StartOptions): Promise<{
+        runId: string;
+        nodeId: string;
+        status: RunStatus;
+    }>;
+    /**
+     * Resume a paused run asynchronously. Equivalent to engine.resume() but
+     * dispatched via the background executor. Returns immediately.
+     */
+    resumeAsync(options: ResumeAsyncOptions): Promise<{
+        runId: string;
+        nodeId: string;
+        status: RunStatus;
+    }>;
+    /**
+     * Read the current status of a run. Returns the full EngineResponse once
+     * terminal; returns a provisional response with status='running'|'queued'
+     * otherwise. If nodeId is omitted, picks the most recently updated node.
+     */
+    getStatus(runId: string, nodeId?: string): Promise<EngineResponse>;
+    /**
+     * Poll until the run reaches a terminal state (done | failed | paused |
+     * cancelled) or the timeout expires. Returns the final EngineResponse.
+     */
+    waitFor(runId: string, opts?: WaitForOptions): Promise<EngineResponse>;
+    /**
+     * Cancel an async run. Aborts the background executor and marks the
+     * state as cancelled. Idempotent — safe to call on already-terminal runs.
+     */
+    cancelRun(runId: string, nodeId?: string): Promise<void>;
+    /**
+     * Retry a specific webhook delivery. Useful when the client acknowledges
+     * they missed an event (e.g., after downtime).
+     */
+    retryWebhook(runId: string, deliveryId: string, nodeId?: string): Promise<void>;
+    /**
+     * Scan all runs for stale heartbeats and mark them as failed. Clients
+     * should call this on startup to recover from crashes.
+     *
+     * @param opts.staleThresholdMs - Heartbeat age after which a running run
+     *   is considered orphaned. Default: 5 minutes.
+     */
+    recoverOrphanedRuns(opts?: {
+        staleThresholdMs?: number;
+    }): Promise<readonly RunState[]>;
+    private maybeFireWebhook;
+    private dispatchWebhookWithRetries;
+    /**
+     * Shut down engine-owned background resources — currently just the
+     * `McpManager`'s connection pool. Long-running hosts (servers,
+     * daemons) SHOULD call this before dropping their engine reference,
+     * otherwise MCP subprocesses leak until the parent process exits.
+     *
+     * Idempotent. Safe to call multiple times.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Structured orchestration — decomposes a task into a plan, executes
+     * each step with specialized agents (planner, researcher, implementer,
+     * verifier, reviewer, finalizer), enforces retry policies, and reverts
+     * failed implementations.
+     *
+     * Unlike `run()` (single agent, best effort), `orchestrate()` guarantees
+     * a result: done (all steps passed), partial (some failed + reverted),
+     * or failed (planning failed entirely).
+     *
+     * Requires `config.orchestrator.enabled = true` or the method throws.
+     * The orchestrator calls `engine.run()` internally for each phase —
+     * it's a state machine layer above the existing agent loop.
+     *
+     * Pure JS — works on both Node.js and Cloudflare Workers.
+     */
+    orchestrate(options: OrchestrateOptions): Promise<OrchestratorResult>;
+    /**
+     * Emit a terminal log line per run. `done` is info; `paused` is info;
+     * `failed` is error (with the error message in `meta.error`).
+     */
+    private logRunEnd;
+    /**
+     * Collect the names of all tools that will be registered — used to
+     * populate the system prompt's tool-specific instructions BEFORE
+     * building the registry itself (the prompt goes into the registry's
+     * Agent tool as the child system prompt, so the prompt must exist
+     * first).
+     */
+    private collectToolNames;
+    /**
+     * Resolve the subagent catalogue the Agent tool will dispatch against.
+     *
+     * Merge semantics:
+     * 1. Start with `config.agents.builtins` — each name becomes a
+     *    placeholder definition that inherits the parent's system prompt.
+     *    (The only builtin v0.1 knows about is `'general-purpose'`.)
+     * 2. If `config.agents.customPath` is set, load any `.md` files from
+     *    that directory (relative to the workspace adapter) and append as
+     *    full `AgentDefinition` records with their own system prompts.
+     * 3. Custom-loaded agents with the same name as a builtin REPLACE the
+     *    builtin — last-wins dedup happens inside `createAgentTool`.
+     *
+     * Throws `ConfigError` if the merged list is empty.
+     */
+    private resolveAgents;
+    /**
+     * Pick the effective gate callback:
+     * 1. `EngineInternals.gateBeforeTool` (test seam)  — highest priority
+     * 2. `config.hooks.gateBeforeTool` (user config)   — the public path
+     * 3. `undefined` (no gate)                          — default
+     */
+    private resolveGate;
+    /**
+     * Start the run-level timeout. Returns an AbortController signal if
+     * `runTimeoutMs > 0`, otherwise returns an empty handle. The caller
+     * MUST invoke `clear()` in a finally block to cancel the timer.
+     */
+    private startRunTimeout;
+    private firePostRunHook;
+    private finalizeResult;
+    /**
+     * Pick the effective `SkillSource` for a run.
+     *
+     *   - Per-run override (`options.skills`) → `InlineSkillSource`
+     *   - else `config.skills.autoload === true` → `StorageSkillSource`
+     *   - else → undefined (SkillPage tool not registered)
+     */
+    private resolveSkillSource;
+    /**
+     * Build a throttled heartbeat callback for agentLoop's `onProgress` hook.
+     *
+     * Only writes to `state.json` if one already exists for this run
+     * (i.e., the run was started via `engine.start()` or `resumeAsync()`).
+     * Sync `engine.run()` callers without a pre-existing state file get a
+     * no-op heartbeat.
+     *
+     * Throttled to at most one write per 500ms AND only when activity
+     * changes, so R2 writes stay cheap even for long runs.
+     */
+    private buildHeartbeat;
+    /**
+     * Build the engine's storage pair. Uses the `EngineInternals.buildStorage`
+     * override when provided (for Workers / custom adapters), otherwise
+     * defers to the standard `createEngineStorage()` factory.
+     */
+    private buildStorage;
+    private buildClient;
+}
+
+/**
+ * providerSelector — translate a `ResolvedModelConfig` into a typed
+ * `ProviderPlan` describing what API client to construct and how.
+ *
+ * The plan is a thin, validated intermediate between user config and the
+ * actual SDK construction so that:
+ * 1. Invalid combinations (proxy provider without baseURL, anthropic
+ *    without apiKey) are rejected at this layer, not at runtime inside
+ *    the SDK's message send
+ * 2. Deferred backends (Bedrock, Vertex, Foundry) can be flagged here
+ *    with a clear `NotImplementedError` pointing at the v0.2 milestone
+ * 3. Tests can exercise selection logic independently of actual client
+ *    construction
+ */
+
+interface AnthropicProviderPlan {
+    readonly kind: 'anthropic';
+    readonly modelId: string;
+    readonly apiKey: string;
+    readonly baseURL: string | undefined;
+    readonly maxTokens: number;
+    readonly temperature: number;
+    readonly maxRetries: number;
+}
+interface ProxyProviderPlan {
+    readonly kind: 'proxy';
+    readonly modelId: string;
+    readonly apiKey: string;
+    readonly baseURL: string;
+    readonly maxTokens: number;
+    readonly temperature: number;
+    readonly maxRetries: number;
+}
+type ProviderPlan = AnthropicProviderPlan | ProxyProviderPlan;
+
+/**
+ * AnthropicClient — thin wrapper around `@anthropic-ai/sdk`.
+ *
+ * Responsibilities:
+ * 1. Construct an `Anthropic` instance from a `ProviderPlan` (anthropic
+ *    first-party or proxy). Passes a custom `fetch` when supplied so
+ *    tests can drive the client with a scripted fetch without any real
+ *    network I/O.
+ * 2. Expose `streamMessage(request)` as an async generator of
+ *    `NormalizedEvent`, with Anthropic SDK stream events passed through
+ *    `normalizeStream` on the way out.
+ * 3. Translate SDK-level errors into the engine's typed error taxonomy
+ *    (`AuthError`, `RateLimitError`, `ApiError`, etc.) so callers can
+ *    discriminate without instanceof-checking third-party classes.
+ *
+ * The client is stateless — each `streamMessage` call is independent.
+ * Callers should reuse a single `AnthropicClient` per run; the
+ * underlying SDK already pools HTTP connections internally.
+ */
+
+interface AnthropicClientOptions {
+    readonly plan: ProviderPlan;
+    /** Custom fetch for tests. Defaults to globalThis.fetch. */
+    readonly fetch?: typeof globalThis.fetch;
+}
+
+/**
+ * AnthropicAdapter — wraps the existing @anthropic-ai/sdk client as a
+ * ModelAdapter. Default provider.
+ */
+
+declare class AnthropicAdapter implements ModelAdapter {
+    private readonly client;
+    constructor(options: AnthropicClientOptions);
+    streamMessage(request: StreamRequest): AsyncGenerator<NormalizedEvent, void, void>;
+}
+
+/**
+ * AISdkAdapter — ModelAdapter using the Vercel AI SDK for 75+ providers.
+ *
+ * Properly converts Anthropic-format messages to AI SDK v4 ModelMessage
+ * format, including tool_use/tool_result round-trips. The key is that
+ * AI SDK v4 requires tool result output as { type: 'text', value: '...' }
+ * (not a plain string or generic object).
+ */
+
+interface AISdkAdapterOptions {
+    readonly provider: string;
+    readonly modelId: string;
+    readonly apiKey: string;
+    readonly baseURL?: string | undefined;
+    readonly maxRetries?: number | undefined;
+}
+declare class AISdkAdapter implements ModelAdapter {
+    private readonly options;
+    private model;
+    constructor(options: AISdkAdapterOptions);
+    streamMessage(request: StreamRequest): AsyncGenerator<NormalizedEvent, void, void>;
+    private getModel;
+}
+
+/**
+ * Model adapter factory — routes config to the right adapter.
+ *
+ * Same pattern as storage/factory.ts:
+ *   createEngineStorage(config.storage) → StorageAdapter
+ *   createModelAdapter(config.model)    → ModelAdapter
+ */
+
+interface CreateModelAdapterOptions {
+    /** Custom fetch for the Anthropic adapter (OpenRouter auth override). */
+    readonly fetch?: typeof globalThis.fetch | undefined;
+}
+/**
+ * Create a ModelAdapter from the resolved model config.
+ *
+ * Routing:
+ *   - 'anthropic' (no sdk override) → AnthropicAdapter (@anthropic-ai/sdk)
+ *   - 'proxy' → AnthropicAdapter with baseURL
+ *   - 'openai', 'google', 'openai-compatible' → AISdkAdapter
+ *   - 'anthropic' + sdk: 'ai-sdk' → AISdkAdapter with @ai-sdk/anthropic
+ */
+declare function createModelAdapter(config: ResolvedModelConfig, options?: CreateModelAdapterOptions): ModelAdapter;
+
+/**
+ * WebhookDispatcher — delivers status changes to client URLs.
+ *
+ * Features:
+ * - HMAC-SHA256 signing via Web Crypto API (works everywhere)
+ * - Exponential backoff retries: 10s → 60s → 5min → 30min → give up
+ * - HTTP 4xx → no retry (client bug); 5xx/network → retry
+ * - HTTP 410 Gone → give up immediately (resource deliberately removed)
+ * - Delivery tracking: each attempt recorded in state.json
+ *
+ * All pure JS — no `node:` imports, Workers-compatible.
+ */
+
+/** Milliseconds to wait before attempt N (1-indexed). */
+declare const RETRY_DELAYS_MS: readonly [0, 10000, 60000, number, number];
+declare const MAX_ATTEMPTS: 5;
+/**
+ * Sign a webhook payload with HMAC-SHA256 using Web Crypto API.
+ * Returns the full header value: `sha256=<hex>`.
+ */
+declare function signPayload(secret: string, timestamp: number, body: string): Promise<string>;
+interface DeliverOptions {
+    readonly url: string;
+    readonly event: WebhookEvent;
+    readonly payload: EngineResponse;
+    readonly secret?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly attempt?: number;
+    readonly deliveryId?: string;
+    readonly timeoutMs?: number;
+    readonly fetch?: typeof globalThis.fetch;
+}
+interface DeliverResult {
+    readonly delivery: WebhookDelivery;
+    readonly shouldRetry: boolean;
+    readonly nextRetryDelayMs?: number;
+}
+declare class WebhookDispatcher {
+    private readonly fetchImpl;
+    constructor(fetchImpl?: typeof globalThis.fetch);
+    /**
+     * Attempt one delivery. Returns a delivery record and whether to retry.
+     */
+    deliver(options: DeliverOptions): Promise<DeliverResult>;
+}
+
+/**
+ * Error taxonomy for la-machina-engine.
+ *
+ * Every thrown error must be a subclass of `EngineError`, so callers can
+ * `instanceof` discriminate at the library boundary. Phase 1 defines only
+ * the errors needed for config resolution and unimplemented methods.
+ * Later phases extend this hierarchy (see plan 002 §4 Phase 4).
+ */
+declare class EngineError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Thrown when config is invalid or incomplete. Raised by `initEngine()` when
+ * `apiKey` cannot be resolved, or when schema validation fails.
+ */
+declare class ConfigError extends EngineError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a method is called in a phase where its implementation has
+ * not yet landed. Used by `engine.run()` and `engine.resume()` during
+ * Phases 1–6 before the loop is wired, and by provider selectors for
+ * backends deferred to v0.2 (Bedrock, Vertex, Foundry).
+ */
+declare class NotImplementedError extends EngineError {
+    constructor(feature: string, target: string);
+}
+/**
+ * Thrown when the provider rejects a request with HTTP 401/403 (missing
+ * or invalid API key). Callers should not retry.
+ */
+declare class AuthError extends EngineError {
+    constructor(message: string);
+}
+/**
+ * Thrown when the provider returns HTTP 429 (rate limited). Callers
+ * should back off and retry. `retryAfterMs` reflects the provider's
+ * hint when available, otherwise null.
+ */
+declare class RateLimitError extends EngineError {
+    readonly retryAfterMs: number | null;
+    constructor(message: string, retryAfterMs?: number | null);
+}
+/**
+ * Thrown when a streaming response can't be parsed into a normalized
+ * event — typically malformed SSE or a JSON parse failure in a delta.
+ * This is a hard error; the stream is not recoverable.
+ */
+declare class StreamParseError extends EngineError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a streaming response ends without a terminal event
+ * (`message_stop`). The caller cannot know whether the assistant
+ * actually finished — almost always safer to fail the run and retry.
+ */
+declare class StreamIncompleteError extends EngineError {
+    constructor(message: string);
+}
+/**
+ * Generic provider-side API error — non-auth, non-rate-limit failures
+ * like 500s, network drops, and unrecognized shapes. `status` is the
+ * HTTP status code when available, otherwise null.
+ */
+declare class ApiError extends EngineError {
+    readonly status: number | null;
+    constructor(message: string, status?: number | null);
+}
+/**
+ * Thrown when a run exceeds `execution.runTimeoutMs`. The agent loop is
+ * aborted at the next checkpoint (top of the turn loop or after a tool
+ * dispatch). The transcript so far is preserved.
+ */
+declare class RunTimeoutError extends EngineError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+
+/**
+ * Structured JSON output — schema injection, parsing, validation.
+ *
+ * When `outputFormat: 'json'` is set on RunOptions:
+ *   1. buildSchemaPrompt() injects output instructions into the system prompt
+ *   2. tryParseJSON() extracts JSON from the model's response (handles fences, preamble)
+ *   3. validateOutput() checks against the Zod schema
+ *
+ * All pure JS — no `node:` imports, Workers-compatible.
+ */
+
+/**
+ * Build the output format section to append to the system prompt.
+ * Called when outputFormat is 'json'.
+ */
+declare function buildSchemaPrompt(schema?: ZodTypeAny): string;
+interface ParseResult {
+    readonly ok: boolean;
+    readonly value?: unknown;
+    readonly error?: string;
+}
+/**
+ * Extract JSON from model output. Tries multiple strategies:
+ *   1. Raw parse (entire text is JSON)
+ *   2. Strip markdown fences (```json ... ```)
+ *   3. Find first { ... } or [ ... ] block
+ */
+declare function tryParseJSON(text: string): ParseResult;
+/**
+ * Validate parsed JSON against a Zod schema.
+ * Returns the validated data or an error message.
+ */
+declare function validateOutput(value: unknown, schema: ZodTypeAny): {
+    ok: true;
+    data: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+
+/**
+ * StreamingToolExecutor — stateful tool queue with ordered result yielding,
+ * concurrency control, and sibling error cascading.
+ *
+ * Ported 1:1 from La-Machina's StreamingToolExecutor.ts. Key behaviors:
+ *
+ * - Tools are enqueued via `addTool()` and executed as they become eligible
+ * - `canExecute()` enforces: concurrent-safe tools run in parallel; unsafe
+ *   tools run alone (exclusive access)
+ * - Results are yielded in **original enqueue order** regardless of
+ *   completion order (preserves tool_result ordering for the API)
+ * - On **Bash error**, `siblingAbortController.abort()` cancels all queued
+ *   siblings with synthetic error results. Only Bash cascades — Read/Grep/
+ *   WebFetch errors are independent.
+ * - All pure JS — no `node:` imports, Workers-compatible.
+ */
+
+declare class StreamingToolExecutor {
+    private readonly tools;
+    private readonly executor;
+    private readonly siblingAbort;
+    private bashErrorDesc;
+    constructor(executor: ToolExecutor);
+    /**
+     * Enqueue a tool call. Eligible tools start executing immediately.
+     */
+    addTool(id: string, name: string, input: unknown, isConcurrencySafe: boolean): void;
+    /**
+     * Yield results in original enqueue order. Waits for each tool to
+     * complete before yielding — guarantees the API sees tool_result
+     * blocks in the same order as the tool_use blocks.
+     */
+    results(): AsyncGenerator<{
+        id: string;
+        result: ToolResult;
+    }>;
+    /**
+     * Can this tool start now? Mirrors La-Machina's canExecuteTool():
+     * - If nothing is executing → yes
+     * - If only concurrent-safe tools are executing AND this tool is safe → yes
+     * - Otherwise → no (wait for exclusive access)
+     */
+    private canExecute;
+    /**
+     * Walk the queue and start any eligible tools. Called after enqueue
+     * and after each tool completes (to unblock the next batch).
+     */
+    private processQueue;
+    private startTool;
+    private executeTool;
+}
+
+/**
+ * SendMessage tool — inter-agent communication within a single run.
+ *
+ * Routes messages to agents tracked in the SubagentRegistry:
+ *
+ * - **Running agent**: Message is queued via `registry.queueMessage()`.
+ *   The child's agentLoop drains queued messages at the start of
+ *   each turn (injected as a user message).
+ *
+ * - **Stopped agent**: Returns an error — auto-resume is deferred to v0.5.
+ *
+ * - **Completed agent**: Returns an error — can't send to finished agents.
+ *
+ * Ported from La-Machina's SendMessageTool.ts (918 lines). The engine
+ * version omits mailbox/UDS/bridge routing (CLI-only) and structured
+ * messages (shutdown_request, plan_approval) — headless mode doesn't
+ * need them.
+ */
+
+declare const inputSchema$1: z.ZodObject<{
+    to: z.ZodString;
+    message: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    to: string;
+}, {
+    message: string;
+    to: string;
+}>;
+interface SendMessageToolOptions {
+    readonly registry: SubagentRegistry;
+}
+declare function createSendMessageTool(options: SendMessageToolOptions): Tool$1<typeof inputSchema$1>;
+
+/**
+ * Fork subagent — child inherits parent's full message context.
+ *
+ * Ported 1:1 from La-Machina's forkSubagent.ts. When `subagent_type`
+ * is omitted, the Agent tool forks a child that sees the parent's
+ * entire conversation history + a directive. This enables "continue
+ * this but focus on X" delegation without starting from scratch.
+ *
+ * Key behaviors:
+ * - Placeholder tool_results are byte-identical across all forks
+ *   (enables prompt cache sharing)
+ * - Recursion guard via `<fork-boilerplate>` tag detection
+ * - Fork children are instructed NOT to spawn sub-agents
+ *
+ * All pure JS — no `node:` imports, Workers-compatible.
+ */
+
+/**
+ * Detect whether the current message history contains a fork boilerplate
+ * tag — prevents recursive forking (child can't re-fork).
+ */
+declare function isInForkChild(messages: readonly MessageParam[]): boolean;
+/**
+ * Build the messages a forked child sees. The child gets:
+ *   1. All of the parent's existing messages (passed separately)
+ *   2. A cloned assistant message with tool_use blocks
+ *   3. Placeholder tool_results + fork directive
+ *
+ * The placeholder text is identical across all forks so the LLM
+ * provider can cache-share the prefix.
+ */
+declare function buildForkedMessages(directive: string, assistantContent: readonly ContentBlockParam[]): MessageParam[];
+
+/**
+ * LocalStorageAdapter — filesystem-backed `StorageAdapter`.
+ *
+ * Ported from La-Machina's production implementation. Wraps Node
+ * `fs/promises` with:
+ *
+ * - **Atomic writes** (temp file + rename pattern)
+ * - **Path safety** via `validateRelativePath` — blocks traversal, absolute
+ *   paths, null bytes at every entrypoint
+ * - **Null-on-missing semantics** — `readFile`/`stat` return `null` instead
+ *   of throwing `ENOENT`; `listDir` returns `[]` for missing directories
+ * - **Recursive directory creation** on all write operations
+ *
+ * Errors from the underlying `fs` module are wrapped in `StorageError` with
+ * the original error preserved as `.cause`.
+ */
+
+declare class LocalStorageAdapter implements StorageAdapter {
+    private readonly root;
+    constructor(root: string);
+    private resolve;
+    readFile(rel: string): Promise<string | null>;
+    writeFile(rel: string, content: string): Promise<void>;
+    appendFile(rel: string, content: string): Promise<void>;
+    deleteFile(rel: string): Promise<void>;
+    exists(rel: string): Promise<boolean>;
+    listDir(rel: string): Promise<string[]>;
+    mkdir(rel: string): Promise<void>;
+    isDirectory(rel: string): Promise<boolean>;
+    stat(rel: string): Promise<FileStat | null>;
+    getRoot(): string;
+    rootExists(): Promise<boolean>;
+}
+
+/**
+ * R2StorageAdapter — Cloudflare R2 (S3-compatible) implementation.
+ *
+ * Ported from La-Machina. Uses `@aws-sdk/client-s3` since R2 speaks the S3
+ * protocol. Path semantics:
+ *
+ * - Files become objects keyed at `${rootPrefix}/${relativePath}`
+ * - Directories are synthetic — S3 has no real directory concept. `mkdir`
+ *   is a no-op; `listDir` uses `Delimiter: '/'` to separate files from
+ *   "subdirectories" (common prefixes).
+ * - `appendFile` is read-modify-write (S3 has no native append primitive).
+ *   OK for small files (JSONL episode logs); prohibitively expensive for
+ *   large files.
+ * - `writeFile` is a single atomic PutObject — no temp+rename dance.
+ *
+ * The backing S3Client is constructed from config. Tests use
+ * `aws-sdk-client-mock` to intercept `.send()` without needing DI.
+ */
+
+interface R2ClientConfig {
+    readonly bucket: string;
+    readonly region: string;
+    readonly accessKeyId: string;
+    readonly secretAccessKey: string;
+    readonly endpoint?: string | undefined;
+}
+declare class R2StorageAdapter implements StorageAdapter {
+    private readonly client;
+    private readonly bucket;
+    private readonly rootPrefix;
+    constructor(config: R2ClientConfig, rootPrefix: string);
+    private key;
+    readFile(rel: string): Promise<string | null>;
+    writeFile(rel: string, content: string): Promise<void>;
+    appendFile(rel: string, content: string): Promise<void>;
+    deleteFile(rel: string): Promise<void>;
+    exists(rel: string): Promise<boolean>;
+    listDir(rel: string): Promise<string[]>;
+    mkdir(rel: string): Promise<void>;
+    isDirectory(rel: string): Promise<boolean>;
+    stat(rel: string): Promise<FileStat | null>;
+}
+
+/**
+ * Hippocampus — memory encoding and retrieval engine.
+ *
+ * Ported from La-Machina. Named for the brain's hippocampus, which
+ * encodes new traces (writing) and pattern-completes partial cues into
+ * full memories (reading).
+ *
+ * Each Hippocampus instance manages one scope's files via a
+ * StorageAdapter:
+ *   - profile.md  → identity (full rewrite, not append)
+ *   - rules.md    → behavioral gates (always / never / when sections)
+ *   - lessons.md  → semantic facts (append + dedup, token-budgeted recall)
+ *   - topics/*.md → per-topic deep dives
+ *
+ * The storage backend is fully abstracted — the same instance works
+ * against local fs or R2. Read-modify-write paths use the adapter's
+ * atomic `writeFile` so concurrent writers see one or the other, never
+ * a partial.
+ */
+
+declare class Hippocampus {
+    private readonly storage;
+    private readonly subdir;
+    private readonly profilePath;
+    private readonly rulesPath;
+    private readonly lessonsPath;
+    private readonly topicsDir;
+    constructor(storage: StorageAdapter, subdir?: string);
+    recallIdentity(): Promise<string>;
+    recallRules(): Promise<string>;
+    /**
+     * Load semantic knowledge most recent first, within a token budget
+     * (rough heuristic: 4 chars per token). The header lines (# Lessons,
+     * blank lines) always survive; entry lines fill the remaining budget
+     * starting from the most recent.
+     */
+    recallLessons(tokenBudget?: number): Promise<string>;
+    recallTopic(slug: string): Promise<string>;
+    encodeRule(text: string, kind: 'always' | 'never' | 'when', confidence?: EngramConfidence, source?: EngramSource): Promise<void>;
+    encodeLesson(text: string, topic?: string, source?: EngramSource): Promise<void>;
+    /**
+     * Replace the identity snapshot — full rewrite, not append. Identity
+     * is a coherent snapshot, not an append log.
+     */
+    rewriteIdentity(entries: ReadonlyArray<string>): Promise<void>;
+    entryCount(): Promise<number>;
+    getStorage(): StorageAdapter;
+    get rulesPathRelative(): string;
+    get lessonsPathRelative(): string;
+    get subdirPath(): string;
+    /**
+     * Extract normalized entry texts from a markdown memory file.
+     * Strips the "- " prefix and trailing `<!-- ... -->` metadata so
+     * dedup works regardless of the comment payload.
+     */
+    static extractEntryTexts(content: string): Set<string>;
+    /** Sanitize a topic name into a safe file slug. */
+    static sanitizeSlug(name: string): string;
+}
+
+/**
+ * memoryConfig — applies the engine's `memory.mode` and `memory.scope`
+ * gates to a wrapped Hippocampus + EpisodicMemory pair.
+ *
+ * Three modes from `ResolvedMemoryConfig`:
+ *
+ * - `'off'`         — All reads return empty, all writes are no-ops.
+ *                     The wrapped Hippocampus is built but never touched.
+ * - `'read-only'`   — Reads pass through to the wrapped Hippocampus,
+ *                     writes are silent no-ops.
+ * - `'read-write'`  — Both reads and writes pass through.
+ *
+ * Two scopes:
+ * - `'workspace'`   — Hippocampus reads/writes the workspace adapter.
+ * - `'global'`      — Hippocampus reads/writes the global adapter.
+ *
+ * The factory returns a thin façade that exposes Hippocampus's read +
+ * write surface plus the EpisodicMemory instance. The agent loop and
+ * tools talk to this façade, never the raw Hippocampus.
+ */
+
+interface SmartMemoryConfig {
+    readonly mode: MemoryMode;
+    readonly scope: MemoryScope;
+}
+interface SmartMemoryOptions {
+    readonly storage: EngineStorage;
+    readonly config: SmartMemoryConfig;
+}
+interface SmartMemory {
+    readonly mode: MemoryMode;
+    readonly scope: MemoryScope;
+    readonly episodes: EpisodicMemory;
+    recallIdentity(): Promise<string>;
+    recallRules(): Promise<string>;
+    recallLessons(tokenBudget?: number): Promise<string>;
+    recallTopic(slug: string): Promise<string>;
+    encodeRule(text: string, kind: 'always' | 'never' | 'when', confidence?: EngramConfidence, source?: EngramSource): Promise<void>;
+    encodeLesson(text: string, topic?: string, source?: EngramSource): Promise<void>;
+    rewriteIdentity(entries: ReadonlyArray<string>): Promise<void>;
+}
+declare function createSmartMemory(options: SmartMemoryOptions): SmartMemory;
+
+/**
+ * Skills loader — discovers `SKILL.md` files under a base directory.
+ *
+ * The skill format is intentionally minimal:
+ *
+ *   skills/
+ *   ├── alpha/
+ *   │   ├── SKILL.md          ← required (name + description)
+ *   │   └── pages/            ← optional (multi-page skill)
+ *   │       ├── intro.md
+ *   │       └── advanced.md
+ *   └── beta/
+ *       └── SKILL.md
+ *
+ * The loader returns one `LoadedSkill` per discovered `SKILL.md`. The
+ * description is extracted from the first non-empty body line (anything
+ * after the title heading) — falling back to the heading text itself if
+ * the file has no body.
+ *
+ * The result feeds into:
+ *   - the system prompt builder (Phase 12+) which injects skill names +
+ *     descriptions so the model knows what's available
+ *   - the SkillPage tool, which lets the model load specific pages on
+ *     demand for multi-page skills
+ */
+
+interface LoadedSkill {
+    /** Folder name (also used as the lookup key in SkillPage). */
+    readonly name: string;
+    /** Human-readable description, extracted from SKILL.md. */
+    readonly description: string;
+    /** Whether the skill has a pages/ subdirectory with content. */
+    readonly hasPages: boolean;
+    /** Full relative path to the skill folder, e.g. "skills/alpha". */
+    readonly path: string;
+    /** Full relative path to the SKILL.md file. */
+    readonly skillFilePath: string;
+}
+/**
+ * Walk the given base directory and return one entry per discovered
+ * skill. Returns an empty array when the base directory does not exist
+ * or contains no skills.
+ */
+declare function loadSkills(storage: StorageAdapter, baseDir: string): Promise<LoadedSkill[]>;
+
+/**
+ * SkillPage tool — loads skill content on demand via a `SkillSource`.
+ *
+ * The tool is pluggable: the engine constructs it with either
+ * `StorageSkillSource` (disk-backed, default) or `InlineSkillSource`
+ * (per-run override). The tool itself only knows the interface.
+ *
+ * Input:
+ *   { skill: string, page?: string }
+ *
+ * - When `page` is omitted, the main `SKILL.md` body is returned.
+ * - When `page` is set, the supplemental page body is returned.
+ *
+ * Errors surface as `{ isError: true, content }`:
+ *   - invalid skill / page name (path traversal shape)
+ *   - unknown skill (returned null from the source)
+ *   - unknown page
+ *   - upstream source throws (network error, SSRF block, etc.)
+ */
+
+declare const inputSchema: z.ZodObject<{
+    skill: z.ZodString;
+    page: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    skill: string;
+    page?: string | undefined;
+}, {
+    skill: string;
+    page?: string | undefined;
+}>;
+interface SkillPageToolOptions {
+    /** The skill source the tool reads through. */
+    readonly source: SkillSource;
+}
+declare function createSkillPageTool(options: SkillPageToolOptions): Tool$1<typeof inputSchema>;
+
+/**
+ * StorageSkillSource — the default `SkillSource`.
+ *
+ * Reads `SKILL.md` files (and optional `pages/*.md`) from a storage
+ * adapter pair. Lookup precedence is workspace-first, global-fallback —
+ * matching the pre-017 behavior so existing deployments see no change.
+ *
+ * Empty/missing `baseDir` → `list()` returns `[]` (equivalent to "no
+ * skills configured"). `autoload: false` at the config layer is handled
+ * upstream — this source does not read that flag.
+ */
+
+interface StorageSkillSourceOptions {
+    readonly storage: EngineStorage;
+    /** Directory under each scope's adapter root. Default: `'skills'`. */
+    readonly baseDir?: string;
+}
+declare class StorageSkillSource implements SkillSource {
+    private readonly storage;
+    private readonly baseDir;
+    constructor(options: StorageSkillSourceOptions);
+    list(): Promise<ReadonlyArray<ResolvedSkill>>;
+    getSkillFile(skill: string): Promise<string | null>;
+    getPage(skill: string, page: string): Promise<string | null>;
+    listPages(skill: string): Promise<ReadonlyArray<string>>;
+    private listPagesIn;
+    private findFile;
+    private readIfExists;
+}
+
+/**
+ * InlineSkillSource — the per-run override `SkillSource`.
+ *
+ * Takes a list of `SkillOverride` records and resolves bodies from
+ * inline `body` (fast path, no network) or `url` (HTTPS fetch on
+ * demand, cached per instance). Designed for Cloudflare Workers —
+ * zero `node:*` imports, plain `fetch`.
+ *
+ * Security:
+ * - Optional `allowedHosts` gate. When set, URL fetches outside the
+ *   allowlist throw before making the request. When unset (default),
+ *   any URL is allowed — fine for local dev, risky for production.
+ * - `timeoutMs` aborts stuck fetches (default: 15s).
+ *
+ * Caching:
+ * - Bodies (main + each page) are memoized within the instance, so
+ *   repeated `SkillPage` calls within one run never refetch.
+ * - No cross-run cache. Each run constructs a fresh InlineSkillSource.
+ */
+
+interface InlineSkillSourceOptions {
+    /** Fetch implementation. Defaults to `globalThis.fetch`. */
+    readonly fetch?: typeof globalThis.fetch;
+    /**
+     * Host allowlist for URL fetches. When empty/undefined, any URL is
+     * allowed. When set, each URL's host must exactly match an entry or
+     * be a subdomain of one (`api.example.com` matches `example.com`).
+     */
+    readonly allowedHosts?: ReadonlyArray<string>;
+    /** Per-request fetch timeout. Default 15_000 ms. */
+    readonly timeoutMs?: number;
+}
+declare class InlineSkillSource implements SkillSource {
+    private readonly byName;
+    private readonly cache;
+    private readonly fetchImpl;
+    private readonly allowedHosts;
+    private readonly timeoutMs;
+    constructor(overrides: ReadonlyArray<SkillOverride>, options?: InlineSkillSourceOptions);
+    list(): Promise<ReadonlyArray<ResolvedSkill>>;
+    getSkillFile(skill: string): Promise<string | null>;
+    getPage(skill: string, page: string): Promise<string | null>;
+    listPages(skill: string): Promise<ReadonlyArray<string>>;
+    private resolve;
+    private assertUrlAllowed;
+}
+
+/**
+ * Runtime detection — determines whether the engine is running in
+ * Node.js or a restricted runtime (Cloudflare Workers, etc.)
+ *
+ * Detection strategy:
+ *   - Node.js has `process.versions.node` set to a version string
+ *   - Workers have `process` (polyfilled) but `process.versions` is
+ *     undefined or `process.versions.node` is undefined
+ *   - As a fallback, probe whether child_process.spawn is functional
+ */
+type RuntimeKind = 'node' | 'worker';
+/**
+ * Detect the runtime. Result is cached after first call.
+ */
+declare function detectRuntime(): RuntimeKind;
+/**
+ * Whether subprocess spawning (Bash, ripgrep, MCP stdio) is available.
+ */
+declare function canSpawnProcesses(): boolean;
+/**
+ * Whether process lifecycle hooks (process.on('exit')) are available.
+ */
+declare function hasProcessLifecycle(): boolean;
+
+/**
+ * Logger — structured log emission gated by `config.logging.level` and
+ * routed to `config.logging.sink`.
+ *
+ * Levels (ascending verbosity):
+ *
+ *   silent < error < warn < info < debug
+ *
+ * `silent` suppresses everything (no-op Logger). Any other level passes
+ * records at that rank OR ANY RANK ABOVE IT through to the sink.
+ *
+ * Sinks:
+ *   - `'stderr'` — `console.error(JSON.stringify(entry))` per record.
+ *     Structured output that's cheap to grep/pipe through `jq`.
+ *   - `'none'`   — true no-op. Use when embedding the engine inside a
+ *     host that has its own observability stack and doesn't want the
+ *     engine yelling into stderr.
+ *   - `(entry) => void` — callable sink. The engine hands the full
+ *     `LogEntry` to the caller on every emission. Use this to route into
+ *     OpenTelemetry, Pino, Winston, Sentry, a worker queue, etc.
+ *
+ * The returned logger is intentionally small: `{ error, warn, info, debug }`.
+ * Each method takes a short message and an optional structured `meta`
+ * object. The engine calls these at known checkpoints (run start/end,
+ * turn boundaries, tool dispatch, pauses, failures) — see engine.ts for
+ * the full emission schedule.
+ */
+
+interface Logger {
+    error(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    info(msg: string, meta?: Record<string, unknown>): void;
+    debug(msg: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * Build a Logger from a resolved logging config.
+ *
+ * Silent-level shortcuts to a true no-op so hot paths don't even
+ * allocate the meta object. Non-silent loggers filter per-call against
+ * the level rank before dispatching to the sink.
+ */
+declare function createLogger(config: ResolvedLoggingConfig): Logger;
+
+/**
+ * Orchestrate — the main state machine.
+ *
+ * Pure JS. No platform APIs. Calls engine.run() internally for each
+ * agent phase. Enforces retry policies, file snapshots for rollback,
+ * dependency ordering, and parallel research execution.
+ *
+ * Flow:
+ *   1. Plan  — Planner agent produces a JSON plan (or use caller-supplied plan)
+ *   2. Execute — for each step in dependency order:
+ *      - research: spawn N researchers in parallel
+ *      - implement: synthesize spec from research → run implementer with retry
+ *      - verify: run verifier → on fail, retry implementer or revert
+ *      - review: optional code review
+ *   3. Finalize — Finalizer agent assembles the report
+ *   4. Return — OrchestratorResult with full provenance
+ */
+
+/**
+ * Execute a structured orchestration. This is the internal implementation
+ * called by engine.orchestrate().
+ */
+declare function orchestrate(engine: Engine, options: OrchestrateOptions, config: ResolvedOrchestratorConfig, storage: StorageAdapter, logger: Logger): Promise<OrchestratorResult>;
+
+/**
+ * Plan parser — extract and validate a JSON plan from LLM output.
+ *
+ * The Planner agent may wrap JSON in markdown fences, include preamble
+ * text, or produce slightly malformed JSON. This parser is tolerant:
+ *   1. Strips markdown ```json ... ``` fences
+ *   2. Finds the first { ... } block in the text
+ *   3. Parses as JSON
+ *   4. Validates against PlanSchema with Zod
+ */
+
+/**
+ * Extract a valid Plan from raw LLM output. Returns null if the output
+ * can't be parsed into a valid plan.
+ */
+declare function parsePlan(raw: string, maxSteps: number): Plan | null;
+
+/**
+ * Generic retry-with-backoff wrapper. Pure JS — no platform APIs
+ * beyond setTimeout.
+ */
+
+interface RetryResult<T> {
+    readonly success: boolean;
+    readonly value?: T;
+    readonly error?: string;
+    readonly attempts: number;
+}
+/**
+ * Execute `fn` up to `policy.maxAttempts` times with exponential backoff.
+ * Returns the first successful result or the last error.
+ */
+declare function runWithRetry<T>(fn: () => Promise<T>, policy: RetryPolicy): Promise<RetryResult<T>>;
+
+/**
+ * File snapshot + restore — rollback mechanism for implementation failures.
+ * Operates through the StorageAdapter abstraction — works on both
+ * local filesystem and R2.
+ */
+
+/**
+ * Read and store the current content of a list of files. Files that
+ * don't exist get `content: null` — restoring them will delete the file
+ * (reversing a create).
+ */
+declare function snapshotFiles(storage: StorageAdapter, paths: readonly string[]): Promise<FileSnapshot[]>;
+/**
+ * Restore files to their snapshotted state. Files that didn't exist
+ * (content === null) are deleted. Files that existed are overwritten
+ * with their original content.
+ */
+declare function restoreSnapshot(storage: StorageAdapter, snapshots: readonly FileSnapshot[]): Promise<string[]>;
+
+/**
+ * Synthesize — combine research findings into an implementation spec.
+ *
+ * This is CODE, not an LLM call. It takes the research step results
+ * for a given implementation step and produces a combined spec string
+ * that the Implementer agent receives as its task.
+ *
+ * The synthesis is deliberately simple: concatenate research findings
+ * with the step's description and any file paths. The Implementer
+ * LLM does the actual reasoning — the synthesizer just assembles context.
+ */
+
+/**
+ * Build an implementation spec from the step's description, prior
+ * research results, and file list.
+ */
+declare function synthesizeSpec(step: PlanStep, allResults: readonly StepResult[]): string;
+
+/**
+ * Agent tool — lets the parent assistant spawn a child agent.
+ *
+ * The Agent tool is a closure factory that captures the parent's
+ * subsystems (storage, API client, registry, subagent registry,
+ * config) at engine.run() time. When the parent calls it via the
+ * usual tool dispatch mechanism, the closure runs `runAgent` to drive
+ * a child loop and returns the child's final answer as the
+ * tool_result content.
+ *
+ * Depth and uniqueness are enforced via `SubagentRegistry`. If the
+ * spawn would exceed `maxSubagentDepth`, the tool returns an error
+ * result instead of throwing — the parent assistant can read the
+ * error and adapt.
+ *
+ * The factory's `parentAgentId` parameter is null at the top level
+ * (root run) and set to the parent's agentId for nested invocations.
+ */
+
+/**
+ * A subagent definition the parent can dispatch to via `Agent({ subagent_type })`.
+ *
+ * `systemPrompt` overrides the parent's system prompt when the child runs.
+ * Leave it undefined to inherit the parent's prompt — which is what the
+ * `'general-purpose'` builtin does.
+ */
+interface AgentDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly systemPrompt?: string;
+    /**
+     * When true, marks this agent as safe for parallel execution
+     * alongside other readOnly agents. The Agent tool uses this via
+     * `isConcurrencySafe` so the batch dispatcher can run multiple
+     * research agents concurrently. Default: false.
+     */
+    readonly readOnly?: boolean;
+}
+
+/**
+ * Agents loader — discovers custom subagent definitions under a directory.
+ *
+ * Format (intentionally minimal, no YAML dependency):
+ *
+ *   {customPath}/
+ *   ├── researcher.md
+ *   └── reviewer.md
+ *
+ * Each `.md` file defines one agent:
+ *
+ *   # researcher
+ *
+ *   One-line description. This is what the parent model sees in the Agent
+ *   tool's description catalogue.
+ *
+ *   ---
+ *
+ *   You are a research subagent. You have access to the web and filesystem...
+ *
+ * Parsing rules:
+ *
+ * - The **filename** (sans `.md`) is the agent's `name`. It must match
+ *   `^[a-zA-Z0-9_-]+$` or the file is skipped.
+ * - The **first non-empty line** (after stripping leading `# `) is the
+ *   agent's `description`. One liner.
+ * - The **rest of the file after the `---` separator** is the agent's
+ *   `systemPrompt`. If no `---` separator exists, the entire body after
+ *   the description is the system prompt. If there is no body at all,
+ *   `systemPrompt` is undefined and the agent inherits the parent's prompt.
+ */
+
+/**
+ * Walk `baseDir` under the given storage adapter and return one
+ * `AgentDefinition` per valid `.md` file. Returns an empty array when
+ * the directory is missing or empty.
+ */
+declare function loadAgents(storage: StorageAdapter, baseDir: string): Promise<AgentDefinition[]>;
+
+/**
+ * Coordinator mode — resolves config, builds the worker agent definition,
+ * and determines the effective system prompt and tool restrictions.
+ */
+
+/**
+ * Check whether the engine is running in coordinator mode.
+ */
+declare function isCoordinatorMode(config: ResolvedConfig): boolean;
+/**
+ * Build the worker agent definition. Workers get a restricted tool set
+ * and a simple system prompt. The coordinator dispatches to them via
+ * `Agent({ subagent_type: 'worker', ... })`.
+ */
+declare function buildWorkerAgent(config: ResolvedCoordinatorConfig): AgentDefinition;
+/**
+ * Get the coordinator's system prompt override. Used by the engine's
+ * prompt builder when coordinator mode is active.
+ */
+declare function getCoordinatorBasePrompt(): string;
+
+/**
+ * Coordinator system prompt — ported from La-Machina's coordinatorMode.ts.
+ *
+ * 370+ lines of behavioral instructions that transform the agent from
+ * an implementer into an orchestrator. The prompt enforces:
+ *   - Research → Synthesis → Implementation → Verification phases
+ *   - Anti-lazy-delegation (must synthesize before directing workers)
+ *   - Parallel reads, serial writes
+ *   - Worker prompt quality standards
+ *
+ * Adapted for headless: no slash commands, no terminal UI, no interactive
+ * approval dialogs. Tool names are parameterized.
+ */
+declare function getCoordinatorSystemPrompt(): string;
+
+interface McpClientOptions {
+    readonly serverName: string;
+    readonly config: ResolvedMcpServerConfig;
+    readonly connectTimeoutMs: number;
+    readonly callTimeoutMs: number;
+    readonly logger: Logger;
+    readonly transportOverride?: Transport;
+    /**
+     * Handler invoked when this server issues a `sampling/createMessage`
+     * request. Only called when `config.allowSampling === true`. When
+     * absent, sampling requests are refused with a protocol error.
+     */
+    readonly samplingHandler?: SamplingHandler;
+}
+declare class McpClient {
+    readonly serverName: string;
+    private readonly options;
+    private sdkClient;
+    private toolCache;
+    private connected;
+    /** PID of the child process (stdio only). Used for synchronous orphan kill. */
+    private childPid;
+    constructor(options: McpClientOptions);
+    get isConnected(): boolean;
+    /** PID of the spawned child process (stdio only). Null for HTTP/SSE. */
+    get pid(): number | null;
+    connect(): Promise<void>;
+    listTools(): readonly McpToolDef[];
+    callTool(toolName: string, input: unknown): Promise<McpCallResult>;
+    close(): Promise<void>;
+    /**
+     * Synchronously kill the child process (stdio only). Used by
+     * McpManager's process.on('exit') handler where async work is not
+     * possible. No-op for HTTP/SSE transports.
+     */
+    killSync(): void;
+    /**
+     * Register the engine-side handler for MCP `sampling/createMessage`.
+     * Runs user-supplied SamplingHandler, converts result to the MCP
+     * `CreateMessageResult` shape.
+     */
+    private installSamplingHandler;
+    private buildTransport;
+}
+
+/**
+ * BindingHttpTransport — plain-POST JSON-RPC MCP transport for Cloudflare
+ * Workers.
+ *
+ * The upstream `StreamableHTTPClientTransport` opens a long-lived `fetch()`
+ * with a streaming SSE response for server-push notifications. On the
+ * Workers runtime that stream can hang unpredictably after `initialize`,
+ * causing `tools/list` and `tools/call` to stall. This transport sidesteps
+ * that entirely: every message is a short, stateless POST; the response
+ * is parsed once and handed to `onmessage`. No persistent reader, no SSE.
+ *
+ * Trade-off: server-push notifications (logs, progress) don't work. That's
+ * fine for the tool-calling use case — `tools/list` and `tools/call` are
+ * request/response only.
+ *
+ * Implements just enough of the MCP transport contract for the engine's
+ * `McpClient` to use. All pure JS — no `node:*` imports, Workers-safe.
+ */
+
+interface BindingHttpTransportOptions {
+    /** Full URL of the MCP Streamable-HTTP endpoint (e.g. https://mcp.example.com/mcp). */
+    readonly url: string;
+    /** Extra headers sent on every POST (auth tokens, API keys). */
+    readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * Per-request dynamic header factory. When set, called before every
+     * send; its result is merged OVER the static `headers`. On HTTP 401
+     * the transport calls the factory again (invalidating any token
+     * cache inside) and retries the request once.
+     */
+    readonly resolveHeaders?: () => Promise<Readonly<Record<string, string>>>;
+    /** Override fetch (tests only). Defaults to globalThis.fetch. */
+    readonly fetch?: typeof globalThis.fetch;
+    /** Per-request timeout in milliseconds. Default: 30_000. */
+    readonly timeoutMs?: number;
+}
+/**
+ * MCP transport that speaks JSON-RPC 2.0 over bare POST. No persistent
+ * connection. Not suitable for servers that rely on async notifications.
+ */
+declare class BindingHttpTransport implements Transport {
+    readonly url: string;
+    private readonly headers;
+    private readonly resolveHeaders;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private started;
+    private closed;
+    sessionId?: string;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: (message: JSONRPCMessage) => void;
+    constructor(options: BindingHttpTransportOptions);
+    start(): Promise<void>;
+    send(message: JSONRPCMessage): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Perform a single POST, applying current headers (static + dynamic).
+     * Does not retry — the 401-refresh loop lives in `send()`.
+     */
+    private doFetch;
+}
+
+interface McpInstructionDelta {
+    readonly connected: string[];
+    readonly disconnected: string[];
+}
+declare class McpManager {
+    private readonly logger;
+    private readonly servers;
+    private readonly shutdownTimeoutMs;
+    private exitHandler;
+    /** Tracks which servers connected/disconnected since last delta retrieval. */
+    private pendingConnected;
+    private pendingDisconnected;
+    constructor(config: ResolvedMcpConfig, logger: Logger, options?: {
+        samplingHandler?: SamplingHandler;
+    });
+    get connectedCount(): number;
+    /**
+     * Lazily connect every configured server and return the full set of
+     * tools. Detects dead connections and retries them. Per-server failures
+     * are isolated.
+     */
+    getTools(): Promise<ReadonlyArray<Tool$1>>;
+    /**
+     * Retrieve and clear pending instruction deltas (connected/disconnected
+     * servers since last call). Used by agentLoop to announce MCP changes
+     * to the model. Ported from La-Machina's mcpInstructionsDelta.ts.
+     */
+    getInstructionDeltas(): McpInstructionDelta;
+    /**
+     * Graceful shutdown with a timeout. Attempts `client.close()` for
+     * every active server within `SHUTDOWN_TIMEOUT_MS`. Servers that don't
+     * respond in time are force-killed (SIGKILL for stdio, no-op for HTTP/SSE).
+     *
+     * Removes the process.on('exit') handler after cleanup.
+     */
+    shutdownAll(): Promise<void>;
+    /**
+     * Synchronously SIGKILL every known child PID. Used by the
+     * process.on('exit') handler (where async is not possible) and by the
+     * shutdown timeout fallback.
+     */
+    private killAllSync;
+    private removeExitHandler;
+    private connectServer;
+    private doConnect;
+}
+
+/**
+ * MCP error taxonomy.
+ *
+ * Three error classes, all subclasses of `EngineError`:
+ *
+ *   - `McpConnectionError` — a server failed to spawn, initialize, or list
+ *     tools. Swallowed by `McpManager`: logged as warn, server's tools are
+ *     absent from the registry, run proceeds.
+ *
+ *   - `McpProtocolError` — a server returned a malformed JSON-RPC response
+ *     or an unexpected capability mismatch. Usually a server bug. Surfaces
+ *     in `tool_result` as `isError: true` when it happens during a call.
+ *
+ *   - `McpTimeoutError` — a tool call exceeded `mcp.callTimeoutMs`.
+ *     Surfaces in `tool_result` as `isError: true` so the agent loop can
+ *     recover (retry, use a different tool, report back).
+ *
+ * The principle: MCP is best-effort. A run must never fail because one
+ * of its MCP servers went wrong.
+ */
+
+declare class McpConnectionError extends EngineError {
+    readonly serverName: string;
+    constructor(serverName: string, cause: string);
+}
+declare class McpProtocolError extends EngineError {
+    readonly serverName: string;
+    constructor(serverName: string, cause: string);
+}
+declare class McpTimeoutError extends EngineError {
+    readonly serverName: string;
+    readonly toolName: string;
+    readonly timeoutMs: number;
+    constructor(serverName: string, toolName: string, timeoutMs: number);
+}
+
+/**
+ * adaptMcpTool — convert an `McpToolDef` into an engine `Tool`.
+ *
+ * The returned tool:
+ *
+ *   - Has its name prefixed with `mcp__{serverName}__` so it cannot
+ *     collide with built-in or custom tools.
+ *   - Carries the server's description verbatim (the model sees this
+ *     as the tool's "what does it do" text).
+ *   - Uses `z.unknown()` as the engine-side input schema. MCP tools
+ *     author their validation in JSON Schema, not Zod, and the server
+ *     itself validates on receipt. Rather than run a lossy
+ *     JSON-Schema → Zod conversion at adapter time, we let the server
+ *     be the source of truth and pass input through unchanged.
+ *   - Sets `anthropicSchemaOverride` to the raw MCP JSON Schema — this
+ *     is what the engine ships to the Anthropic API so the model sees
+ *     a proper `input_schema` with typed parameters.
+ *   - Dispatches to `McpClient.callTool()`, turning `McpCallResult`
+ *     into the engine's `ToolResult` and catching any thrown MCP errors
+ *     into `{ isError: true }` results so the agent loop can recover.
+ *
+ * Why not use `z.any().passthrough()` instead of `z.unknown()`?
+ *   `z.unknown()` validates nothing (matches any value, including
+ *   `undefined`). `z.any()` is semantically equivalent but linters
+ *   frown on it. Either works; we pick `unknown` for stricter types.
+ */
+
+/** Build the engine-side tool name for an MCP tool. */
+declare function mcpToolName(serverName: string, toolName: string): string;
+declare function adaptMcpTool(client: McpClient, serverName: string, def: McpToolDef): Tool$1<z.ZodUnknown>;
+
+/**
+ * buildSystemPrompt — assemble the full system prompt from static
+ * sections, dynamic per-run sections, and optional memory/skill recall.
+ *
+ * Section order (matches La-Machina's cacheable/dynamic split):
+ *
+ *   ── STATIC (cacheable prefix — identical across runs) ──
+ *   1. Base identity + capabilities
+ *   2. Doing tasks (behavioral rules)
+ *   3. Executing actions with care (reversibility, blast radius)
+ *   4. Using your tools (tool-specific instructions)
+ *   5. Tone and style + output efficiency
+ *
+ *   ── DYNAMIC (changes per-run) ──
+ *   6. Environment (OS, CWD, model, date)
+ *   7. MCP tools (when config.mcp.servers is populated)
+ *   8. Identity (smart memory profile.md)
+ *   9. Rules (smart memory rules.md)
+ *  10. Lessons (smart memory lessons.md, token-budgeted)
+ *  11. Skills (loadSkills() output as name/description list)
+ *  12. Custom base (caller-supplied override, appended last)
+ *
+ * The function is async because memory recall and skill discovery both
+ * involve storage adapter reads. It's pure-ish — no writes, no side
+ * effects beyond the reads themselves.
+ */
+
+interface BuildSystemPromptOptions {
+    /** Custom base instruction appended to the system prompt. */
+    readonly base?: string;
+    /** SmartMemory façade — reads are gated by memory mode. */
+    readonly memory: SmartMemory;
+    /** Storage adapter pair — used to enumerate skills. */
+    readonly storage: EngineStorage;
+    /** Whether to scan and inject the skill index. */
+    readonly skillsAutoload: boolean;
+    /** Directory to scan for skills (relative to each scope's adapter root). */
+    readonly skillsDir?: string;
+    /**
+     * Pre-resolved skill catalogue. When set, takes precedence over the
+     * disk scan (`skillsAutoload` + `skillsDir`). Used by the engine when
+     * `RunOptions.skills` supplies an inline list via `InlineSkillSource`.
+     */
+    readonly skillList?: ReadonlyArray<{
+        name: string;
+        description: string;
+    }>;
+    /** Token budget for the lessons section (default: 1000). */
+    readonly lessonsTokenBudget?: number;
+    /** Model ID for the environment section. */
+    readonly modelId?: string;
+    /** Provider name for the environment section. */
+    readonly provider?: string;
+    /** Working directory override for the environment section. */
+    readonly cwd?: string;
+    /** Registered tool names — drives tool-specific prompt instructions. */
+    readonly registeredToolNames?: ReadonlySet<string>;
+    /** MCP-sourced tools — listed in a dedicated prompt section. */
+    readonly mcpTools?: ReadonlyArray<Tool$1>;
+    /** When true, skip normal static sections (base/doingTasks/etc.) —
+     *  the coordinator prompt replaces them via `base`. */
+    readonly coordinatorMode?: boolean;
+}
+declare function buildSystemPrompt(options: BuildSystemPromptOptions): Promise<string>;
+
+/**
+ * Safe tool allowlist — tools that are always safe to run without
+ * human approval or rule evaluation.
+ *
+ * Ported from La-Machina's `SAFE_YOLO_ALLOWLISTED_TOOLS`. These tools
+ * are read-only or purely informational — they cannot modify the
+ * filesystem, send messages, or cause side effects beyond reading state.
+ *
+ * Used by `'locked'` mode: only these tools pass, everything else is
+ * denied. Also used as a fast-path in `'rules'` mode: allowlisted tools
+ * skip rule evaluation entirely.
+ */
+declare const SAFE_TOOL_ALLOWLIST: ReadonlySet<string>;
+/**
+ * Check if a tool name is on the safe allowlist.
+ */
+declare function isSafeTool(toolName: string): boolean;
+
+/**
+ * Rule parser + matcher.
+ *
+ * Rule string format: `"action:pattern"`
+ *   - action: `allow` or `deny`
+ *   - pattern: exact tool name or glob with `*` wildcard
+ *
+ * Examples:
+ *   - `"allow:Read"`           → allow the Read tool
+ *   - `"deny:Bash"`            → deny the Bash tool
+ *   - `"allow:mcp__fs__*"`     → allow all tools from the fs MCP server
+ *   - `"deny:mcp__*"`          → deny all MCP tools
+ *   - `"deny:*"`               → deny everything (catch-all)
+ *   - `"allow:*"`              → allow everything (catch-all)
+ *
+ * Invalid rule strings are silently skipped (logged at warn level by
+ * the evaluator).
+ */
+
+/**
+ * Parse a rule string into a structured `PermissionRule`. Returns null
+ * if the string is malformed.
+ */
+declare function parseRule(raw: string): PermissionRule | null;
+/**
+ * Parse an array of rule strings into structured rules, skipping
+ * malformed entries.
+ */
+declare function parseRules(raw: readonly string[]): readonly PermissionRule[];
+/**
+ * Check if a tool name matches a rule's pattern. Uses picomatch for
+ * glob support (same library the engine uses for Glob/Grep tools).
+ */
+declare function matchesRule(toolName: string, rule: PermissionRule): boolean;
+
+/**
+ * la-machina-engine — public API.
+ *
+ * The single entry point is `initEngine()`. Every config option has a
+ * default; `initEngine()` with no arguments must work, so long as either
+ * `config.model.apiKey` is set OR `ANTHROPIC_API_KEY` is in the environment.
+ *
+ * See plans/002-la-machina-engine.md for the full spec.
+ */
+
+declare const ENGINE_VERSION = "0.0.0";
+/**
+ * Initialize an Engine with (optional) user config merged over defaults.
+ *
+ * @param user Partial config. Every field is optional.
+ * @returns A fully-configured Engine ready to `run()` (once Phase 7 lands).
+ * @throws {ConfigError} If config validation fails or `apiKey` cannot be
+ *   resolved from either `config.model.apiKey` or `ANTHROPIC_API_KEY` env.
+ */
+declare function initEngine(user?: UserConfig): Engine;
+
+export { AISdkAdapter, type AgentDefinition, AnthropicAdapter, ApiError, AuthError, type BackgroundAgentResult, type BackgroundExecutor, BindingHttpTransport, type BuildSystemPromptOptions, ConfigError, DEFAULT_SAMPLING_MAX_DEPTH, ENGINE_VERSION, Engine, EngineError, type EngineInternals, type EngineResponse, type EngineStorage, type Engram, type EngramConfidence, type EngramKind, type EngramScope, type EngramSource, type Entry, type Episode, EpisodicMemory, type FileSnapshot, type FileStat, type FlushPolicy, type GateBeforeToolHook, type GateDecision$1 as GateDecision, Hippocampus, InlineSkillSource, type LoadedSkill, LocalStorageAdapter, type LogEntry, type LogLevel, type LogSink, type Logger, type LoopProgress, MAX_ATTEMPTS, type McpCallResult, McpClient, McpConnectionError, type McpInstructionDelta, McpManager, McpProtocolError, type McpServerState, McpTimeoutError, type McpToolDef, type MemoryMode, type MemoryScope, type ModelAdapter, type ModelMessage, type ModelProvider, type ModelToolDefinition, NodeBackgroundExecutor, type NormalizedEvent, NotImplementedError, type OrchestrateOptions, type OrchestratorResult, type PauseReason, type PermissionAction, type PermissionDecision, type PermissionMode, type PermissionPolicy, type PermissionRule, type Plan, PlanSchema, type PlanStep, PlanStepSchema, type PostRunEvent, type PostRunHook, type PostToolCallEvent$1 as PostToolCallEvent, type PostToolCallHook, type PostTurnEvent, type PostTurnHook, type PreRunEvent, type PreRunHook, type PreToolCallEvent$1 as PreToolCallEvent, type PreToolCallHook, type PreTurnEvent, type PreTurnHook, R2BindingStorageAdapter, type R2BucketBinding, type R2ClientConfig, R2StorageAdapter, RETRY_DELAYS_MS, RateLimitError, type ResolvedAgentsConfig, type ResolvedConfig, type ResolvedCoordinatorConfig, type ResolvedExecutionConfig, type ResolvedHooksConfig, type ResolvedLoggingConfig, type ResolvedMcpConfig, type ResolvedMcpHttpServerConfig, type ResolvedMcpServerConfig, type ResolvedMcpSseServerConfig, type ResolvedMcpStdioServerConfig, type ResolvedMemoryConfig, type ResolvedModelConfig, type ResolvedOrchestratorConfig, type ResolvedPermissionsConfig, type ResolvedR2Config, type ResolvedSkill, type ResolvedSkillsConfig, type ResolvedStorageConfig, type ResolvedToolsConfig, type ResolvedTranscriptConfig, type ResponseError, type ResponseMeta, type ResumeAsyncOptions, type ResumeOptions, type RetryPolicy, type RunOptions, type RunProgress, type RunResult, type RunSnapshot, type RunState, RunStateManager, type RunStatus, RunTimeoutError, type RuntimeKind, SAFE_TOOL_ALLOWLIST, type SamplingContext, type SamplingHandler, type SamplingMessage, type SamplingModelPreferences, type SamplingRequest, type SamplingResponse, type SamplingTextBlock, type SerializedAgent, type SkillOverride, type SkillPageOverride, type SkillSource, type SmartMemory, type SmartMemoryConfig, type SpawnResult, type StartOptions, type StepResult, type StepStatus, type StopHook, type StopHookEvent, type StopHookResult, type StorageAdapter, StorageError, type StorageProvider, StorageSkillSource, StreamIncompleteError, StreamParseError, type StreamRequest, StreamingToolExecutor, SubagentRegistry, type SubagentRegistryOptions, type TokenUsage, type Tool$1 as Tool, type ToolContext, ToolRegistry, type ToolResult, type TranscriptLocation, type TranscriptMeta, type TranscriptStatus, type UserConfig, type WaitForOptions, type WebhookConfig, type WebhookDelivery, WebhookDispatcher, type WebhookEvent, type WebhookOptions, adaptMcpTool, buildForkedMessages, buildPermissionPolicy, buildSchemaPrompt, buildSystemPrompt, buildWorkerAgent, canSpawnProcesses, createLogger, createModelAdapter, createSendMessageTool, createSkillPageTool, createSmartMemory, defaultSamplingHandler, defineTool, detectRuntime, getCoordinatorBasePrompt, getCoordinatorSystemPrompt, hasProcessLifecycle, initEngine, isCoordinatorMode, isInForkChild, isSafeTool, loadAgents, loadSkills, matchesRule, mcpToolName, orchestrate, parsePlan, parseRule, parseRules, partitionToolCalls, restoreSnapshot, runWithRetry, signPayload, snapshotFiles, synthesizeSpec, toResponse, tryParseJSON, validateOutput };