@ailu-ai/graph-sdk 2.0.0

package/dist/index.d.ts

@@ -0,0 +1,4260 @@
+import { ModelLike } from '@ailu-ai/model-core';
+export { ChatMessage, DEFAULT_KEY_ENV, InvokeOptions, MissingProviderKeyError, Model, ModelLike, ModelOptions, ModelResponse, ModelSpec, ModelUsage, NoProviderInEnvError, OpenAICompatibleModel, OutputSchema, ProviderEntry, ProviderSlug, ResolvedKeys, SpecModel, TypedModel, UnknownProviderError, assertKnownProvider, model, models, openaiCompatible, parseModelString, resolveProviderKeys, toModelSpec } from '@ailu-ai/model-core';
+import { z } from 'zod';
+import { KeyObject } from 'node:crypto';
+
+type MessageId = Brand<string, "MessageId">;
+type ToolCall = {
+    id: string;
+    name: string;
+    input: unknown;
+};
+type BaseMessage = {
+    id: MessageId;
+    createdAt: Date;
+    metadata?: Record<string, unknown>;
+};
+type HumanMessage = BaseMessage & {
+    role: "human";
+    content: string;
+};
+type AIMessage = BaseMessage & {
+    role: "ai";
+    content: string;
+    toolCalls?: ToolCall[];
+};
+type ToolMessage = BaseMessage & {
+    role: "tool";
+    toolCallId: string;
+    content: string;
+};
+type SystemMessage = BaseMessage & {
+    role: "system";
+    content: string;
+};
+type Message = HumanMessage | AIMessage | ToolMessage | SystemMessage;
+
+type Brand<T, TBrand extends string> = T & {
+    readonly __brand: TBrand;
+};
+type NodeId = Brand<string, "NodeId">;
+type EdgeId = Brand<string, "EdgeId">;
+type GraphId = Brand<string, "GraphId">;
+type RunId = Brand<string, "RunId">;
+type ChannelReducer = "replace" | "append" | "merge";
+type ChannelDefinition<T> = {
+    type: string;
+    reducer: ChannelReducer;
+    default?: T;
+    /** ADR 0032: never emit this channel's value in run events/logs (masked; still checkpointed). */
+    noLog?: boolean;
+};
+type ChannelsSchema = Record<string, ChannelDefinition<unknown>>;
+type ResolvedChannels<TChannels extends ChannelsSchema> = {
+    [K in keyof TChannels]: TChannels[K] extends ChannelDefinition<infer TValue> ? TValue : never;
+};
+declare const NODE_TYPES: readonly ["action", "agent", "tool", "human-gate", "subgraph"];
+type NodeType = (typeof NODE_TYPES)[number];
+/** ADR 0076 (product repo) — `"error"` routes from a node to a designated handler once its
+ * `retryPolicy` is exhausted, instead of failing the whole run. Absent (the common case): failure
+ * behavior is unchanged — the run terminates exactly as before this type existed. */
+declare const EDGE_TYPES: readonly ["default", "conditional", "error"];
+type EdgeType = (typeof EDGE_TYPES)[number];
+/** ADR 0076 — coarse classification of why a node's handler threw, attached to `node_failed`/
+ * `node_error_routed` events so a governed error path can react differently to a transient
+ * failure (worth a human-visible retry) vs a permanent one (worth surfacing, not retrying).
+ * Derived by `graph-runtime` from a thrown error's own `failureCategory` property when present
+ * (a convention, not an interface — any thrower, e.g. `llm-gateway`, can set it); defaults to
+ * `"unknown"` for a plain `Error`/thrown value that doesn't declare one. */
+declare const FAILURE_CATEGORIES: readonly ["transient", "permanent", "unknown"];
+type FailureCategory = (typeof FAILURE_CATEGORIES)[number];
+/** `cancelled` (ADR 0044): terminal, reached when the embedder's cancellation seam returned
+ *  true at a node BOUNDARY — the run stopped before scheduling its next node, with its last
+ *  checkpoint durable and authoritative. Distinct from `failed` (no error occurred) and from
+ *  `suspended` (it is not waiting on a decision). A cancelled run stays replayable. */
+declare const GRAPH_STATUSES: readonly ["idle", "running", "suspended", "completed", "failed", "cancelled"];
+type GraphStatus = (typeof GRAPH_STATUSES)[number];
+type RetryPolicy = {
+    maxAttempts: number;
+    backoffMs: number;
+};
+type Command<TChannels extends ChannelsSchema = ChannelsSchema> = {
+    goto: NodeId | NodeId[];
+    update?: Partial<ResolvedChannels<TChannels>>;
+};
+type NodeDefinition = {
+    id: NodeId;
+    type: NodeType;
+    label: string;
+    subgraphId?: GraphId;
+    inputMapping?: Record<string, string>;
+    outputMapping?: Record<string, string>;
+    fanOut?: {
+        parallelTo: NodeId[];
+        joinAt: NodeId;
+    };
+    /** ADR 0042 D2/D3 (product ADR 0068 — child workflows): dynamic N-child subgraph fan-out.
+     * Present on a `type: "subgraph"` node ALONGSIDE its `subgraphId` (never duplicated here) —
+     * `overChannel` is read as a JSON array at execution time, one child spawn per item, run
+     * concurrently; results land in `joinAt` as a JSON array, input order preserved. Absent (the
+     * common case): the node runs its subgraph exactly once, unchanged. */
+    mapSubgraph?: {
+        overChannel: string;
+        joinAt: string;
+    };
+    retryPolicy?: RetryPolicy;
+    metadata?: Record<string, unknown>;
+};
+type EdgeDefinition = {
+    id: EdgeId;
+    from: NodeId;
+    to: NodeId;
+    type: EdgeType;
+    condition?: string;
+};
+type GraphState<TChannels extends ChannelsSchema = ChannelsSchema> = {
+    runId: RunId;
+    graphId: GraphId;
+    currentNodeId: NodeId;
+    status: GraphStatus;
+    channels: ResolvedChannels<TChannels>;
+    version: number;
+    checkpointId?: string;
+    createdAt: string;
+    updatedAt: string;
+};
+type GraphDefinition<TChannels extends ChannelsSchema = ChannelsSchema> = {
+    id: GraphId;
+    version: string;
+    name: string;
+    recursionLimit?: number;
+    channels: TChannels;
+    nodes: NodeDefinition[];
+    edges: EdgeDefinition[];
+    entryNodeId: NodeId;
+    metadata?: Record<string, unknown>;
+};
+
+declare const GraphStateSchema: z.ZodObject<{
+    runId: z.ZodBranded<z.ZodString, "RunId">;
+    graphId: z.ZodBranded<z.ZodString, "GraphId">;
+    currentNodeId: z.ZodBranded<z.ZodString, "NodeId">;
+    status: z.ZodEnum<["idle", "running", "suspended", "completed", "failed", "cancelled"]>;
+    channels: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    version: z.ZodNumber;
+    checkpointId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    status: "idle" | "running" | "suspended" | "completed" | "failed" | "cancelled";
+    runId: string & z.BRAND<"RunId">;
+    graphId: string & z.BRAND<"GraphId">;
+    currentNodeId: string & z.BRAND<"NodeId">;
+    channels: Record<string, unknown>;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    checkpointId?: string | undefined;
+}, {
+    status: "idle" | "running" | "suspended" | "completed" | "failed" | "cancelled";
+    runId: string;
+    graphId: string;
+    currentNodeId: string;
+    channels: Record<string, unknown>;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    checkpointId?: string | undefined;
+}>;
+
+declare const GRAPH_VALIDATION_ERROR_CODES: {
+    readonly DUPLICATE_NODE_ID: "DUPLICATE_NODE_ID";
+    readonly DUPLICATE_EDGE_ID: "DUPLICATE_EDGE_ID";
+    readonly MISSING_ENTRY_NODE: "MISSING_ENTRY_NODE";
+    readonly INVALID_EDGE_REFERENCE: "INVALID_EDGE_REFERENCE";
+    readonly CYCLE_DETECTED: "CYCLE_DETECTED";
+    readonly INVALID_CONDITION_FORMAT: "INVALID_CONDITION_FORMAT";
+    readonly MULTIPLE_ERROR_EDGES: "MULTIPLE_ERROR_EDGES";
+};
+type GraphValidationErrorCode = (typeof GRAPH_VALIDATION_ERROR_CODES)[keyof typeof GRAPH_VALIDATION_ERROR_CODES];
+type GraphValidationPath = (string | number)[];
+declare class GraphValidationError extends Error {
+    readonly code: GraphValidationErrorCode;
+    readonly path: GraphValidationPath;
+    constructor(code: GraphValidationErrorCode, message: string, path?: GraphValidationPath);
+}
+
+declare const validateGraph: (def: GraphDefinition) => GraphValidationError[];
+
+type ArtifactId = string & {
+    readonly __brand: "ArtifactId";
+};
+type ArtifactVersion = number;
+declare const ARTIFACT_MEDIA_TYPES: readonly ["application/json", "text/plain", "text/markdown", "application/octet-stream"];
+type ArtifactMediaType = (typeof ARTIFACT_MEDIA_TYPES)[number];
+type Artifact = {
+    id: ArtifactId;
+    runId: RunId;
+    nodeId: NodeId;
+    name: string;
+    mediaType: ArtifactMediaType;
+    version: ArtifactVersion;
+    content: unknown;
+    createdAt: Date;
+    metadata?: Record<string, unknown>;
+};
+type ArtifactRef = {
+    id: ArtifactId;
+    version: ArtifactVersion;
+};
+
+interface ArtifactStore {
+    write(artifact: Omit<Artifact, "id" | "version" | "createdAt">): Promise<Artifact>;
+    read(id: ArtifactId): Promise<Artifact | undefined>;
+    readVersion(id: ArtifactId, version: ArtifactVersion): Promise<Artifact | undefined>;
+    listByRun(runId: RunId): Promise<Artifact[]>;
+    listVersions(id: ArtifactId): Promise<Artifact[]>;
+}
+
+type ArtifactWriteInput = Omit<Artifact, "id" | "version" | "createdAt">;
+declare class InMemoryArtifactStore implements ArtifactStore {
+    private readonly artifactsById;
+    private readonly latestIdByRunAndName;
+    write(artifact: ArtifactWriteInput): Promise<Artifact>;
+    read(id: ArtifactId): Promise<Artifact | undefined>;
+    readVersion(id: ArtifactId, version: ArtifactVersion): Promise<Artifact | undefined>;
+    listByRun(runId: RunId): Promise<Artifact[]>;
+    listVersions(id: ArtifactId): Promise<Artifact[]>;
+}
+
+type MemoryNamespace = string[];
+type MemoryKey = string;
+type MemoryItem = {
+    namespace: MemoryNamespace;
+    key: MemoryKey;
+    value: unknown;
+    createdAt: string;
+    updatedAt: string;
+    embedding?: number[];
+};
+
+interface BaseStore {
+    get(namespace: MemoryNamespace, key: MemoryKey): Promise<MemoryItem | undefined>;
+    put(namespace: MemoryNamespace, key: MemoryKey, value: unknown): Promise<MemoryItem>;
+    delete(namespace: MemoryNamespace, key: MemoryKey): Promise<void>;
+    search(namespace: MemoryNamespace, query: string, topK: number): Promise<MemoryItem[]>;
+    list(namespace: MemoryNamespace, prefix?: string): Promise<MemoryItem[]>;
+}
+
+type BaseCallbackEvent = {
+    runId: string;
+    nodeId?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    timestamp: string;
+};
+type CallbackEvent = (BaseCallbackEvent & {
+    type: "onLLMStart";
+    input: unknown;
+}) | (BaseCallbackEvent & {
+    type: "onLLMToken";
+    token: string;
+}) | (BaseCallbackEvent & {
+    type: "onLLMEnd";
+    output: unknown;
+}) | (BaseCallbackEvent & {
+    type: "onLLMError";
+    error: string;
+}) | (BaseCallbackEvent & {
+    type: "onToolStart";
+    tool: string;
+    input: unknown;
+}) | (BaseCallbackEvent & {
+    type: "onToolEnd";
+    tool: string;
+    output: unknown;
+}) | (BaseCallbackEvent & {
+    type: "onToolError";
+    tool: string;
+    error: string;
+}) | (BaseCallbackEvent & {
+    type: "onNodeStart";
+    input: unknown;
+}) | (BaseCallbackEvent & {
+    type: "onNodeEnd";
+    output: unknown;
+}) | (BaseCallbackEvent & {
+    type: "onNodeError";
+    error: string;
+}) | (BaseCallbackEvent & {
+    type: "onChainStart";
+    input: unknown;
+}) | (BaseCallbackEvent & {
+    type: "onChainEnd";
+    output: unknown;
+}) | (BaseCallbackEvent & {
+    type: "onChainError";
+    error: string;
+}) | (BaseCallbackEvent & {
+    type: "onAgentAction";
+    action: string;
+    payload?: unknown;
+}) | (BaseCallbackEvent & {
+    type: "onAgentFinish";
+    result: unknown;
+});
+
+interface CallbackHandler {
+    onLLMStart?(event: Extract<CallbackEvent, {
+        type: "onLLMStart";
+    }>): void | Promise<void>;
+    onLLMToken?(event: Extract<CallbackEvent, {
+        type: "onLLMToken";
+    }>): void | Promise<void>;
+    onLLMEnd?(event: Extract<CallbackEvent, {
+        type: "onLLMEnd";
+    }>): void | Promise<void>;
+    onLLMError?(event: Extract<CallbackEvent, {
+        type: "onLLMError";
+    }>): void | Promise<void>;
+    onToolStart?(event: Extract<CallbackEvent, {
+        type: "onToolStart";
+    }>): void | Promise<void>;
+    onToolEnd?(event: Extract<CallbackEvent, {
+        type: "onToolEnd";
+    }>): void | Promise<void>;
+    onToolError?(event: Extract<CallbackEvent, {
+        type: "onToolError";
+    }>): void | Promise<void>;
+    onNodeStart?(event: Extract<CallbackEvent, {
+        type: "onNodeStart";
+    }>): void | Promise<void>;
+    onNodeEnd?(event: Extract<CallbackEvent, {
+        type: "onNodeEnd";
+    }>): void | Promise<void>;
+    onNodeError?(event: Extract<CallbackEvent, {
+        type: "onNodeError";
+    }>): void | Promise<void>;
+    onChainStart?(event: Extract<CallbackEvent, {
+        type: "onChainStart";
+    }>): void | Promise<void>;
+    onChainEnd?(event: Extract<CallbackEvent, {
+        type: "onChainEnd";
+    }>): void | Promise<void>;
+    onChainError?(event: Extract<CallbackEvent, {
+        type: "onChainError";
+    }>): void | Promise<void>;
+    onAgentAction?(event: Extract<CallbackEvent, {
+        type: "onAgentAction";
+    }>): void | Promise<void>;
+    onAgentFinish?(event: Extract<CallbackEvent, {
+        type: "onAgentFinish";
+    }>): void | Promise<void>;
+}
+interface CallbackManager {
+    addHandler(handler: CallbackHandler): void;
+    removeHandler(handler: CallbackHandler): void;
+    emit(event: CallbackEvent): Promise<void>;
+    createChild(tags?: string[], metadata?: Record<string, unknown>): CallbackManager;
+}
+
+declare const LLM_PROVIDERS: readonly ["openai", "anthropic", "mistral", "google", "ollama", "mock"];
+type LLMProvider = (typeof LLM_PROVIDERS)[number];
+type LLMModel = string;
+/** A text span in a structured message. */
+type LLMTextBlock = {
+    type: "text";
+    text: string;
+};
+/** An assistant turn requesting a tool call. */
+type LLMToolUseBlock = {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: unknown;
+};
+/** A user turn returning a tool's result, paired to a prior `tool_use` by id. */
+type LLMToolResultBlock = {
+    type: "tool_result";
+    toolUseId: string;
+    content: string;
+    isError?: boolean;
+};
+type LLMContentBlock = LLMTextBlock | LLMToolUseBlock | LLMToolResultBlock;
+type LLMMessage = {
+    role: "system" | "user" | "assistant";
+    /**
+     * Either plain text or a list of content blocks. Blocks carry `tool_use` /
+     * `tool_result` turns so a tool-calling agent can hold a real multi-turn
+     * conversation with the provider instead of stuffing observations into text.
+     */
+    content: string | LLMContentBlock[];
+};
+/**
+ * Tool definition exposed to the provider. Part of the cacheable prefix: the tool
+ * list must be deterministic (stable order, stable schema) or it busts the cache.
+ */
+type LLMToolDef = {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+};
+type LLMRequest = {
+    provider: LLMProvider;
+    model: LLMModel;
+    messages: LLMMessage[];
+    /**
+     * Immutable system prompt. Forms the cacheable prefix together with `tools`.
+     * Keep volatile content (dates, timestamps, session ids) OUT of here.
+     */
+    system?: string;
+    tools?: LLMToolDef[];
+    maxTokens?: number;
+    temperature?: number;
+    stream?: boolean;
+};
+/** A structured tool call surfaced by the provider (e.g. an Anthropic `tool_use` block). */
+type LLMToolCall = {
+    id: string;
+    name: string;
+    input: unknown;
+};
+type LLMResponse = {
+    content: string;
+    /**
+     * Structured tool calls the model wants executed. Present when the provider
+     * stops on a tool-use turn; consumers should run these instead of parsing the
+     * text content for a tool protocol.
+     */
+    toolCalls?: LLMToolCall[];
+    /** Why the model stopped — `"tool_use"` signals it is waiting on tool results. */
+    stopReason?: "end_turn" | "tool_use" | "max_tokens" | "stop_sequence" | string;
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        /** Tokens served from the prompt cache (~0.1x cost). */
+        cacheReadTokens?: number;
+        /** Tokens written to the prompt cache this call (~1.25x cost). */
+        cacheWriteTokens?: number;
+    };
+    model: string;
+    provider: LLMProvider;
+};
+type LLMStreamChunk = {
+    delta: string;
+    done: boolean;
+};
+
+interface LLMProviderAdapter {
+    provider: LLMProvider;
+    complete(req: LLMRequest): Promise<LLMResponse>;
+    stream(req: LLMRequest): AsyncIterable<LLMStreamChunk>;
+}
+interface LLMGateway {
+    complete(req: LLMRequest): Promise<LLMResponse>;
+    stream(req: LLMRequest): AsyncIterable<LLMStreamChunk>;
+    registerAdapter(adapter: LLMProviderAdapter): void;
+}
+
+type WorkingMemory = {
+    shortTerm: Message[];
+    longTerm: BaseStore;
+};
+
+type AgentId = string & {
+    readonly __brand: "AgentId";
+};
+type Blocker = {
+    code: string;
+    message: string;
+    nodeId?: NodeId;
+};
+type AgentResult = {
+    artifacts: ArtifactRef[];
+    blockers: Blocker[];
+    approvalRequests: Array<{
+        subject: ArtifactRef | {
+            description: string;
+        };
+        reason: string;
+    }>;
+    confidence: number;
+    reasoning: string;
+    requiresHumanReview: boolean;
+    /**
+     * Token usage summed across the run's LLM calls (ADR 0028 phase 7a — observability / cost).
+     * Present on results produced by the Rust engine; the control plane maps it to cost and to
+     * span/trace attributes. Omitted when no LLM call was made.
+     */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        cacheReadTokens?: number;
+        cacheWriteTokens?: number;
+    };
+    /**
+     * The validated structured output (ADR 0029 phase 8): the parsed JSON value that conformed to
+     * the agent's `structuredOutput` middleware schema. Present only when that middleware ran and
+     * produced a valid value; omitted otherwise (no schema requested, or lenient mode never
+     * validated). The shape is the caller's schema — typed as `unknown`, validate/narrow at the
+     * boundary.
+     */
+    structuredOutput?: unknown;
+};
+
+interface Agent<TInput = unknown> {
+    id: AgentId;
+    name: string;
+    description: string;
+    run(input: TInput, state: GraphState, context: {
+        memory: BaseStore;
+        workingMemory: WorkingMemory;
+        callbacks?: CallbackManager;
+    }): Promise<AgentResult>;
+}
+
+type ZodSchema<T> = {
+    parse(input: unknown): T;
+};
+type ToolId = string & {
+    readonly __brand: "ToolId";
+};
+type ToolDefinition<TInput, TOutput> = {
+    id: ToolId;
+    name: string;
+    description: string;
+    inputSchema: ZodSchema<TInput>;
+    outputSchema: ZodSchema<TOutput>;
+    permissions: string[];
+    requiresApproval?: boolean;
+    /**
+     * JSON Schema for the tool's input, advertised to the LLM. `inputSchema` only
+     * validates (`.parse`); this is what the provider needs to emit tool calls.
+     */
+    jsonSchema?: Record<string, unknown>;
+};
+type ToolHandler<TInput, TOutput> = (input: TInput) => Promise<TOutput>;
+interface ToolRegistry {
+    register<TInput, TOutput>(definition: ToolDefinition<TInput, TOutput>, handler: ToolHandler<TInput, TOutput>): void;
+    resolve(id: ToolId): {
+        definition: ToolDefinition<unknown, unknown>;
+        handler: ToolHandler<unknown, unknown>;
+    } | undefined;
+    list(): ToolDefinition<unknown, unknown>[];
+}
+declare class InMemoryToolRegistry implements ToolRegistry {
+    private readonly entries;
+    register<TInput, TOutput>(definition: ToolDefinition<TInput, TOutput>, handler: ToolHandler<TInput, TOutput>): void;
+    resolve(id: ToolId): {
+        definition: ToolDefinition<unknown, unknown>;
+        handler: ToolHandler<unknown, unknown>;
+    } | undefined;
+    list(): ToolDefinition<unknown, unknown>[];
+}
+
+/**
+ * The `writeTodos` planning tool and its checkpointed state shape — phase 1 of the
+ * governed deep-agent harness (ADR 0022/0023). Behaviour-identical to the Rust
+ * `agents-core` `todos.rs`: a pure state-write tool the model calls to (re)emit the
+ * **authoritative full** todo list. The engine (Rust) executes it and the agent
+ * node persists the latest list into {@link TODOS_CHANNEL}.
+ *
+ * This module is the shared-shape source of truth (types + {@link normalizeTodos})
+ * plus the tool definition SDK consumers reference; the real execution path is the
+ * Rust engine (the SDK runs Rust-only — ADR 0016).
+ */
+type TodoStatus = "pending" | "in_progress" | "completed";
+type TodoItem = {
+    id: string;
+    text: string;
+    status: TodoStatus;
+};
+/**
+ * Reserved channel the agent node persists the latest todo list into. Replace
+ * semantics: `writeTodos` always writes the full authoritative list, so the channel
+ * must not declare an append/merge reducer. Matches the Rust `TODOS_CHANNEL`.
+ */
+declare const TODOS_CHANNEL = "__todos";
+/** The `writeTodos` tool name. Matches the Rust `WRITE_TODOS_TOOL`. */
+declare const WRITE_TODOS_TOOL_NAME = "writeTodos";
+type WriteTodosInput = {
+    todos: Array<{
+        id?: string;
+        text: string;
+        status: TodoStatus;
+    }>;
+};
+/**
+ * Normalize raw tool input into an authoritative todo list. Lenient and
+ * deterministic — **byte-for-byte parity** with the Rust `normalize_todos`:
+ * - iterate `input.todos` in order;
+ * - drop any item whose `text` is missing or blank (after trimming);
+ * - an item with a missing or blank `id` gets `todo-{n}`, where `n` is its
+ *   **1-based position in the incoming list** (dropped items still advance `n`);
+ * - an unknown or absent `status` coerces to `pending`.
+ *
+ * A missing / non-array `todos` field yields an empty list.
+ */
+declare function normalizeTodos(input: unknown): TodoItem[];
+/** JSON Schema advertised to the LLM — identical to the Rust `write_todos_tool` schema. */
+declare const writeTodosJsonSchema: Record<string, unknown>;
+/**
+ * The `writeTodos` tool definition + handler. `requiresApproval` is always false —
+ * planning is cheap and never gated. The handler returns the normalized list.
+ */
+declare const writeTodosTool: {
+    definition: ToolDefinition<WriteTodosInput, TodoItem[]>;
+    handler: ToolHandler<WriteTodosInput, TodoItem[]>;
+};
+
+/**
+ * Versioned prompt registry. Agents reference prompts by id (+ optional version)
+ * instead of hardcoding them inline (rule 090). The `system` text is the immutable,
+ * cacheable prefix — keep volatile/dynamic values out of it and pass those in the
+ * per-call user message instead.
+ */
+type PromptTemplate$1 = {
+    id: string;
+    version: string;
+    system: string;
+    description?: string;
+};
+interface PromptRegistry {
+    register(template: PromptTemplate$1): void;
+    get(id: string, version?: string): PromptTemplate$1;
+    list(): PromptTemplate$1[];
+}
+declare class InMemoryPromptRegistry implements PromptRegistry {
+    private readonly byId;
+    private readonly latest;
+    register(template: PromptTemplate$1): void;
+    get(id: string, version?: string): PromptTemplate$1;
+    list(): PromptTemplate$1[];
+}
+
+type ReActAgentOptions = {
+    id: AgentId;
+    name: string;
+    description: string;
+    llm: LLMGateway;
+    tools?: ToolRegistry;
+    maxIterations?: number;
+    provider?: LLMProvider;
+    model?: string;
+    /** System prompt source — agents reference prompts by id, never inline them. */
+    promptRegistry?: PromptRegistry;
+    promptId?: string;
+    promptVersion?: string;
+    /**
+     * Names of `requiresApproval` tools that have already been granted human
+     * approval (e.g. injected into state on resume). Listed tools execute instead
+     * of being gated again — this is how a suspended-for-approval run continues.
+     */
+    approvedToolNames?: string[];
+};
+declare class ReActAgent<TInput> implements Agent<TInput> {
+    readonly id: AgentId;
+    readonly name: string;
+    readonly description: string;
+    private readonly llm;
+    private readonly tools?;
+    private readonly maxIterations;
+    private readonly provider;
+    private readonly model;
+    private readonly promptRegistry?;
+    private readonly promptId?;
+    private readonly promptVersion?;
+    private readonly approvedToolNames;
+    constructor(options: ReActAgentOptions);
+    run(input: TInput, state: GraphState, context: {
+        memory: BaseStore;
+        workingMemory: WorkingMemory;
+        callbacks?: CallbackManager;
+    }): Promise<AgentResult>;
+    /**
+     * Resolve a tool by name and either execute it or gate it. Shared by the native
+     * tool_use path and the legacy ACTION: text protocol so both honour the approval
+     * rule identically: a `requiresApproval` tool is never self-executed.
+     */
+    private executeToolCall;
+    private resolveSystemPrompt;
+    private buildToolDefs;
+}
+
+type CheckpointId = string & {
+    readonly __brand: "CheckpointId";
+};
+type Checkpoint<TChannels extends ChannelsSchema = ChannelsSchema> = {
+    id: CheckpointId;
+    runId: RunId;
+    graphState: GraphState<TChannels>;
+    createdAt: string;
+};
+type RunEvent = {
+    type: "node_started";
+    runId: RunId;
+    nodeId: NodeId;
+    timestamp: string;
+} | {
+    type: "node_completed";
+    runId: RunId;
+    nodeId: NodeId;
+    output: unknown;
+    timestamp: string;
+} | {
+    type: "node_failed";
+    runId: RunId;
+    nodeId: NodeId;
+    error: string;
+    attempt: number;
+    category: FailureCategory;
+    timestamp: string;
+} | {
+    type: "node_error_routed";
+    runId: RunId;
+    nodeId: NodeId;
+    errorEdgeId: EdgeId;
+    toNodeId: NodeId;
+    category: FailureCategory;
+    error: string;
+    timestamp: string;
+} | {
+    type: "run_suspended";
+    runId: RunId;
+    nodeId: NodeId;
+    reason: string;
+    timestamp: string;
+} | {
+    type: "run_resumed";
+    runId: RunId;
+    nodeId: NodeId;
+    timestamp: string;
+} | {
+    type: "run_completed";
+    runId: RunId;
+    finalState: GraphState<ChannelsSchema>;
+    timestamp: string;
+} | {
+    type: "run_failed";
+    runId: RunId;
+    error: string;
+    timestamp: string;
+} | {
+    type: "run_cancelled";
+    runId: RunId;
+    nodeId: NodeId;
+    timestamp: string;
+} | {
+    type: "token_delta";
+    runId: RunId;
+    nodeId: NodeId;
+    messageId: string;
+    delta: string;
+    parentRunId?: RunId;
+    spawnId?: number;
+    timestamp: string;
+};
+
+type NodeExecutionContext = {
+    memory: BaseStore;
+};
+type NodeHandler<TChannels extends ChannelsSchema = ChannelsSchema, TInput = unknown, TOutput extends Partial<ResolvedChannels<TChannels>> | Command<TChannels> = Partial<ResolvedChannels<TChannels>> | Command<TChannels>> = (input: TInput, state: GraphState<TChannels>, context: NodeExecutionContext) => Promise<TOutput>;
+interface NodeRegistry {
+    register(nodeId: NodeId, handler: NodeHandler): void;
+    resolve(nodeId: NodeId): NodeHandler | undefined;
+}
+type ConditionFn = (state: GraphState) => boolean;
+interface ConditionRegistry {
+    register(name: string, fn: ConditionFn): void;
+    resolve(name: string): ConditionFn | undefined;
+}
+interface Checkpointer {
+    save(checkpoint: Checkpoint): Promise<void>;
+    load(runId: RunId): Promise<Checkpoint | undefined>;
+    loadById(id: CheckpointId): Promise<Checkpoint | undefined>;
+    list(runId: RunId): Promise<Checkpoint[]>;
+}
+interface EventBus {
+    emit(event: RunEvent): void;
+    subscribe(handler: (event: RunEvent) => void): () => void;
+}
+
+type StepBudget = {
+    maxSteps: number;
+    currentSteps: number;
+};
+
+declare class InMemoryNodeRegistry implements NodeRegistry {
+    private readonly handlers;
+    register(nodeId: NodeId, handler: NodeHandler): void;
+    resolve(nodeId: NodeId): NodeHandler | undefined;
+}
+
+declare class InMemoryConditionRegistry implements ConditionRegistry {
+    private readonly conditions;
+    register(name: string, fn: ConditionFn): void;
+    resolve(name: string): ConditionFn | undefined;
+}
+
+declare class InMemoryCheckpointer implements Checkpointer {
+    private readonly checkpointsById;
+    private readonly latestCheckpointByRunId;
+    private readonly checkpointIdsByRunId;
+    save(checkpoint: Checkpoint): Promise<void>;
+    load(runId: RunId): Promise<Checkpoint | undefined>;
+    loadById(id: CheckpointId): Promise<Checkpoint | undefined>;
+    list(runId: RunId): Promise<Checkpoint[]>;
+}
+
+declare class InMemoryEventBus implements EventBus {
+    private readonly subscribers;
+    emit(event: RunEvent): void;
+    subscribe(handler: (event: RunEvent) => void): () => void;
+}
+
+declare const STREAM_MODES: readonly ["values", "updates", "debug", "messages"];
+type StreamMode = (typeof STREAM_MODES)[number];
+type StreamEvent = {
+    type: "state_value";
+    state: GraphState;
+} | {
+    type: "state_update";
+    delta: Record<string, unknown>;
+    nodeId: NodeId;
+} | {
+    type: "message_delta";
+    delta: string;
+    nodeId: NodeId;
+    messageId: string;
+} | {
+    type: "tool_call";
+    toolId: string;
+    input: unknown;
+    nodeId: NodeId;
+} | {
+    type: "debug";
+    payload: unknown;
+    nodeId: NodeId;
+};
+
+type InterruptConfig = {
+    before?: NodeId[];
+    after?: NodeId[];
+};
+declare class DynamicInterrupt extends Error {
+    readonly reason: string;
+    readonly patch?: Record<string, unknown>;
+    constructor(reason: string, patch?: Record<string, unknown>);
+}
+
+type GraphRuntimeDeps = {
+    graph: GraphDefinition<ChannelsSchema>;
+    nodeRegistry: NodeRegistry;
+    conditionRegistry: ConditionRegistry;
+    checkpointer: Checkpointer;
+    eventBus: EventBus;
+    callbackManager?: CallbackManager;
+    memory?: BaseStore;
+    stepBudget?: StepBudget;
+    subgraphResolver?: (graphId: GraphId) => GraphDefinition | undefined;
+    interruptConfig?: InterruptConfig;
+};
+declare class GraphRuntime {
+    private readonly graph;
+    private readonly nodeRegistry;
+    private readonly conditionRegistry;
+    private readonly checkpointer;
+    private readonly eventBus;
+    private readonly callbackManager;
+    readonly memory: BaseStore;
+    readonly stepBudget: StepBudget;
+    private readonly nodeById;
+    private readonly subgraphResolver?;
+    private readonly interruptConfig?;
+    private readonly stateHistoryByRunId;
+    private readonly stepsByRunId;
+    private readonly inboxByRunId;
+    constructor(deps: GraphRuntimeDeps);
+    start(runId: RunId, initialData: Record<string, unknown>): Promise<GraphState>;
+    stream(runId: RunId, initialData: Record<string, unknown>, mode: StreamMode): AsyncIterable<StreamEvent>;
+    resume(runId: RunId): Promise<GraphState>;
+    executeNode(nodeId: NodeId, state: GraphState): Promise<GraphState>;
+    nextNode(currentNodeId: NodeId, state: GraphState): NodeId | null;
+    send(runId: RunId, nodeId: NodeId, input: unknown): Promise<void>;
+    /** ADR 0076 — at most one `"error"` edge per node is enforced at validation time
+     * (`GRAPH_VALIDATION_ERROR_CODES.MULTIPLE_ERROR_EDGES`), so the first match is unambiguous. */
+    private findErrorEdge;
+    private selectNextEdge;
+    private runLoop;
+    private persistCheckpoint;
+    getHistory(runId: RunId): GraphState<ChannelsSchema>[];
+    updateState(runId: RunId, patch: Partial<Record<string, unknown>>, resumeFrom?: NodeId): Promise<GraphState>;
+    getCheckpoints(runId: RunId): Promise<Checkpoint[]>;
+    replayFrom(runId: RunId, checkpointId: CheckpointId): Promise<GraphState>;
+    applyUpdate(channels: Record<string, unknown>, partialUpdate: Partial<Record<string, unknown>>): Record<string, unknown>;
+    private buildInitialChannels;
+    private applyInputMapping;
+    private applyOutputMapping;
+    private setSubgraphRunId;
+    private getOrCreateSubgraphRunId;
+    private readInterruptMeta;
+    private clearInterruptMeta;
+    private suspendRun;
+    private computeDelta;
+    private areEqual;
+    private assertRecursionLimit;
+    private consumeStepBudget;
+    private consumeInjectedInput;
+    private resolveCommand;
+    private resolveNextNode;
+    private executeFanOut;
+    private extractMessageEvents;
+    private extractToolCallEvents;
+}
+
+/**
+ * Discriminated-union result type used across the SDK's "safe" entry points
+ * (e.g. {@link GraphBuilder.safeCompile}). Mirrors Zod's `safeParse` ergonomics.
+ */
+type Result<T, E> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: E;
+};
+/** The "teach" metadata every Ailu error carries (ADR: errors-that-teach) — a stable
+ * machine-readable `code`, a one-line `hint` (the fix), and a deep `docUrl`. An AI agent or a
+ * human reads these to self-correct without leaving the stack trace. */
+type ErrorTeach = {
+    code: string;
+    hint?: string;
+    docUrl?: string;
+};
+/** Base class for every error thrown by `@ailu-ai/graph-sdk`. Carries a stable `code`,
+ * an actionable `hint`, and a `docUrl` — the `.message` stays exactly what was thrown
+ * (so existing assertions hold); the teaching lives in the extra fields + {@link format}. */
+declare class AiluSdkError extends Error {
+    readonly code: string;
+    readonly hint?: string;
+    readonly docUrl: string;
+    constructor(message: string, teach: ErrorTeach);
+    /** Message + hint + doc link, for logs / CLI / an agent reading the failure to self-correct. */
+    format(): string;
+}
+/** Thrown when `.compile()` is called on a graph that fails validation. */
+declare class GraphCompileError extends AiluSdkError {
+    readonly errors: GraphValidationError[];
+    constructor(errors: GraphValidationError[]);
+}
+/** Thrown when two nodes are added under the same id. */
+declare class DuplicateNodeError extends AiluSdkError {
+    constructor(nodeId: string);
+}
+/** Thrown when an action node is added without an executable handler. */
+declare class MissingHandlerError extends AiluSdkError {
+    constructor(nodeId: string);
+}
+/** Thrown when a builder method references a node id that has not been added yet. */
+declare class UnknownNodeError extends AiluSdkError {
+    constructor(nodeId: string, context: string);
+}
+/**
+ * Thrown when an agent's `middleware[]` names a GOVERNANCE kind (redact / approvalGate /
+ * fsPolicy). The governed layer is engine-injected and sealed — a user may only append
+ * EFFICIENCY middleware (compress / terse / contextBudget) — so an ungoverned stack is
+ * unrepresentable (ADR 0025 phase 3d, the governed-by-construction invariant).
+ */
+declare class GovernanceMiddlewareRejectedError extends AiluSdkError {
+    constructor(kind: string);
+}
+/** Thrown when `resume`/`approve` is called but no suspended state exists for that run id on
+ * this `CompiledGraph` instance (the Rust path keeps suspended state per-instance). */
+declare class ResumeStateNotFoundError extends AiluSdkError {
+    constructor(runId: string);
+}
+/** Thrown when `approveAndResume` is called without naming who approved (`resolvedBy`). */
+declare class ApproverRequiredError extends AiluSdkError {
+    constructor();
+}
+/**
+ * Thrown by `resumeCatalogGraph` with an `approvalEngine` when the engine has not authorized the
+ * resume: a request is still pending, a human gate was rejected, or a granted tool has no matching
+ * approved request. `problems` lists each one; nothing ran.
+ */
+declare class ApprovalNotGrantedError extends AiluSdkError {
+    readonly problems: string[];
+    constructor(runId: string, problems: string[]);
+}
+
+/**
+ * A structured, machine-readable account of where a run stands (ADR errors-that-teach / AI-DX):
+ * what state it's in, why it suspended, what it's waiting for, what failed. An AI agent or a
+ * human reads this to decide the next move — resume, deliver a signal, fix an input — without
+ * trawling the raw event log. Channel **names** only (never values) so it never leaks payloads.
+ */
+type RunExplanation = {
+    runId: string;
+    status: string;
+    currentNode: string;
+    /** One-line, human/agent-readable summary of the situation + the next action. */
+    summary: string;
+    /** Present when suspended: why, on which node, and what unblocks it. */
+    suspended?: {
+        reason: string;
+        node: string;
+        awaitingSignal?: string;
+        wakeAt?: string;
+        /** The concrete next action to resume. */
+        nextAction: string;
+    };
+    /** Present when the run (or a node) failed. */
+    failure?: {
+        node?: string;
+        error: string;
+    };
+    /** The channel names present (not their values). */
+    channels: string[];
+    /** The last few lifecycle events, type + node only (when an event log is provided). */
+    recentEvents?: {
+        type: string;
+        node?: string;
+    }[];
+};
+/**
+ * Explain a run from its {@link GraphState} (and, optionally, its lifecycle event log).
+ * Pure + read-only — safe to call on any state.
+ */
+declare function explainRun(state: GraphState, events?: readonly RunEvent[]): RunExplanation;
+
+declare class DefaultLLMGateway implements LLMGateway {
+    private readonly adapters;
+    registerAdapter(adapter: LLMProviderAdapter): void;
+    complete(req: LLMRequest): Promise<LLMResponse>;
+    stream(req: LLMRequest): AsyncIterable<LLMStreamChunk>;
+    private validateRequest;
+}
+
+type MockAdapterOptions = {
+    provider: LLMProvider;
+    response?: LLMResponse;
+    /**
+     * Scripted responses replayed one per `complete()` call (the last repeats once
+     * exhausted). Lets a test drive a multi-turn agent — e.g. a `tool_use` turn
+     * followed by a final-answer turn. Takes precedence over `response`.
+     */
+    responses?: LLMResponse[];
+    chunks?: LLMStreamChunk[];
+};
+declare class MockLLMProviderAdapter implements LLMProviderAdapter {
+    readonly provider: LLMProvider;
+    private readonly responses;
+    private readonly chunks;
+    private index;
+    constructor(options: MockAdapterOptions);
+    complete(): Promise<LLMResponse>;
+    stream(): AsyncIterable<LLMStreamChunk>;
+}
+
+/**
+ * Provider-shaped request the adapter assembles. This is the cache seam: the
+ * `system` and `tools` blocks carry the cache_control breakpoints and must stay
+ * byte-stable across calls. The default port translates this into the SDK request;
+ * tests fake the port and assert on this shape directly.
+ */
+type AnthropicCreateParams = {
+    model: string;
+    maxTokens: number;
+    system?: Array<{
+        type: "text";
+        text: string;
+        cacheable?: boolean;
+    }>;
+    tools?: Array<{
+        name: string;
+        description?: string;
+        inputSchema: Record<string, unknown>;
+        cacheable?: boolean;
+    }>;
+    messages: Array<{
+        role: "user" | "assistant";
+        content: string | LLMContentBlock[];
+    }>;
+};
+/** Structural subset of the SDK `Message` the adapter actually reads. */
+type AnthropicRawResponse = {
+    content: Array<{
+        type: string;
+        text?: string;
+        id?: string;
+        name?: string;
+        input?: unknown;
+    }>;
+    stop_reason?: string | null;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_input_tokens?: number | null;
+        cache_creation_input_tokens?: number | null;
+    };
+};
+/**
+ * The only seam onto the Anthropic SDK. The default implementation wraps a real
+ * client; tests supply a fake so the cache + accounting logic is covered without
+ * a network call or an API key.
+ */
+interface AnthropicClientPort {
+    create(params: AnthropicCreateParams): Promise<AnthropicRawResponse>;
+    stream(params: AnthropicCreateParams): AsyncIterable<LLMStreamChunk>;
+}
+type AnthropicAdapterOptions = {
+    /** Override the model used when the request does not name a Claude model. */
+    defaultModel?: string;
+    /** Inject a client port (tests) or an API key (production). */
+    port?: AnthropicClientPort;
+    apiKey?: string;
+};
+declare class AnthropicProviderAdapter implements LLMProviderAdapter {
+    readonly provider: "anthropic";
+    private readonly port;
+    private readonly defaultModel;
+    constructor(options?: AnthropicAdapterOptions);
+    complete(req: LLMRequest): Promise<LLMResponse>;
+    stream(req: LLMRequest): AsyncIterable<LLMStreamChunk>;
+    /**
+     * Assemble the provider request. The cacheable prefix is `tools` then `system`
+     * (Anthropic render order); a breakpoint on the last tool and on the system block
+     * caches that prefix. Sampling params are intentionally dropped — Opus 4.7/4.8
+     * reject `temperature`/`top_p`/`top_k`. No date/timestamp is added here.
+     */
+    private buildParams;
+    private collectSystem;
+    private resolveModel;
+    private toResponse;
+}
+
+/**
+ * The OpenAI `/v1/chat/completions` request body the adapter assembles. This is the
+ * seam tests assert against directly: {@link buildRequestBody} is a pure function, so
+ * the request mapping is covered without a network call or an API key.
+ */
+type OpenAIChatRequestBody = {
+    model: string;
+    messages: OpenAIChatMessage[];
+    tools?: Array<{
+        type: "function";
+        function: {
+            name: string;
+            description?: string;
+            parameters: Record<string, unknown>;
+        };
+    }>;
+    temperature?: number;
+    max_tokens?: number;
+};
+/** A single message in the OpenAI chat shape. */
+type OpenAIChatMessage = {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    tool_call_id?: string;
+    tool_calls?: Array<{
+        id: string;
+        type: "function";
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+};
+/** Structural subset of the OpenAI chat completion response the adapter reads. */
+type OpenAIChatResponse = {
+    choices: Array<{
+        message: {
+            content?: string | null;
+            tool_calls?: Array<{
+                id: string;
+                type?: string;
+                function: {
+                    name: string;
+                    arguments: string;
+                };
+            }> | null;
+        };
+        finish_reason?: string | null;
+    }>;
+    usage?: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+    };
+};
+/**
+ * The only seam onto the HTTP transport. The default implementation POSTs the body to
+ * `baseUrl + '/chat/completions'` via global `fetch`; tests supply a fake so the
+ * request/response mapping is covered without a network call.
+ */
+interface OpenAICompatibleTransportPort {
+    send(body: OpenAIChatRequestBody): Promise<OpenAIChatResponse>;
+}
+type OpenAICompatibleAdapterOptions = {
+    /** Provider key this adapter registers under in the gateway map. Default `'mistral'`. */
+    provider?: LLMProvider;
+    /** API base, e.g. `https://api.mistral.ai/v1` or `http://localhost:11434/v1`. */
+    baseUrl: string;
+    /** Model used when the request does not name a model id for this provider. */
+    defaultModel: string;
+    /** Bearer token; omitted for keyless servers such as a local Ollama. */
+    apiKey?: string;
+    /** Inject a transport port (tests) instead of the default `fetch`-backed one. */
+    port?: OpenAICompatibleTransportPort;
+};
+/**
+ * One adapter for any server speaking the OpenAI `/v1/chat/completions` shape. Both
+ * a local **Ollama** server (`http://localhost:11434/v1`, keyless) and **Mistral
+ * cloud** (`https://api.mistral.ai/v1`, bearer key) are driven by this same class;
+ * use {@link OpenAICompatibleProviderAdapter.ollama} / `.mistral` to construct them.
+ */
+declare class OpenAICompatibleProviderAdapter implements LLMProviderAdapter {
+    readonly provider: LLMProvider;
+    private readonly port;
+    private readonly baseUrl;
+    private readonly defaultModel;
+    constructor(options: OpenAICompatibleAdapterOptions);
+    /** Mistral cloud: bearer-keyed, hosted at `https://api.mistral.ai/v1`. */
+    static mistral(apiKey?: string, model?: string): OpenAICompatibleProviderAdapter;
+    /** Google Gemini via its OpenAI-compatible endpoint; registers under the `google` provider. */
+    static google(apiKey?: string, model?: string): OpenAICompatibleProviderAdapter;
+    /** OpenAI cloud (the canonical OpenAI-compatible API); registers under the `openai` provider. */
+    static openai(apiKey?: string, model?: string): OpenAICompatibleProviderAdapter;
+    /**
+     * A local Ollama server (keyless, `http://localhost:11434/v1`). Registers under the
+     * `'mistral'` provider key so it routes through the same gateway slot as Mistral cloud.
+     */
+    static ollama(model?: string, baseUrl?: string): OpenAICompatibleProviderAdapter;
+    complete(req: LLMRequest): Promise<LLMResponse>;
+    stream(req: LLMRequest): AsyncIterable<LLMStreamChunk>;
+    private toResponse;
+}
+
+/**
+ * An abstract capability tier. Wire-compatible (camelCase) with the Rust
+ * `ModelTier` enum in `crates/llm-gateway`.
+ */
+type ModelTier = "frontier" | "balanced" | "fast" | "creative";
+/** All four tiers, in declaration order — handy for seeding tables. */
+declare const MODEL_TIERS: readonly ModelTier[];
+/**
+ * The outcome of {@link ModelPolicy.resolve}: a concrete provider + model, plus
+ * whether the model came from the recommended per-tier defaults (`true`) or from
+ * an explicit override (`false`).
+ */
+type ModelChoice = {
+    provider: LLMProvider;
+    model: string;
+    recommended: boolean;
+};
+/** `tier -> model` for a single provider. */
+type TierModelTable = Record<ModelTier, string>;
+/** Optional override passed to {@link ModelPolicy.resolve}. */
+type ResolveOverride = {
+    provider?: LLMProvider;
+    model?: string;
+};
+/**
+ * The shared capability-tier contract defaults: the recommended model for each
+ * provider at each tier. Mirrors the Rust `ModelPolicy::default` table exactly.
+ */
+declare const DEFAULT_TIER_TABLE: Partial<Record<LLMProvider, TierModelTable>>;
+/** The default cross-provider preference order, highest first. */
+declare const DEFAULT_PREFERENCE: readonly LLMProvider[];
+/**
+ * Capability-tier model policy: map an abstract capability tier
+ * (`frontier` / `balanced` / `fast` / `creative`) onto a concrete
+ * `{ provider, model }` choice, given which providers are actually available.
+ *
+ * Mirrors the Rust `crates/llm-gateway` `ModelPolicy` byte for byte in behaviour
+ * and wire shape. The point: "I only have Mistral" -> every tier resolves to the
+ * mistral column; "only Anthropic" -> `fast` -> haiku, `frontier` -> opus,
+ * `creative` -> fable.
+ */
+declare class ModelPolicy {
+    private readonly table;
+    private readonly preference;
+    /**
+     * Construct a policy. Either argument may be omitted to keep the contract
+     * default for that piece.
+     */
+    constructor(options?: {
+        table?: Partial<Record<LLMProvider, TierModelTable>>;
+        preference?: readonly LLMProvider[];
+    });
+    /**
+     * Which providers are usable given the current process environment:
+     * `anthropic` iff `ANTHROPIC_API_KEY` is set; `mistral` iff `MISTRAL_API_KEY`
+     * is set; `ollama` iff `AILU_USE_OLLAMA=1`. Order follows the policy
+     * preference so callers get a deterministic list.
+     */
+    availableFromEnv(env?: NodeJS.ProcessEnv): LLMProvider[];
+    /**
+     * Resolve a capability tier to a concrete `{ provider, model, recommended }`.
+     *
+     * - An explicit `override.provider` and/or `override.model` wins, with
+     *   `recommended = false`. When only one of the two is given, the other is
+     *   filled from the policy: an override provider maps the tier to that
+     *   provider's recommended model; an override model rides on the first
+     *   available provider (or the override provider if also given).
+     * - Otherwise the highest-preference provider that is both available and
+     *   present in the table supplies its tier model, with `recommended = true`.
+     * - If nothing is available, the mock provider is returned.
+     */
+    resolve(tier: ModelTier, available: readonly LLMProvider[], override?: ResolveOverride): ModelChoice;
+    /** The recommended model for a provider+tier from the table, if present. */
+    private modelFor;
+    /** The first preference-ordered provider that is in `available`. */
+    private firstAvailable;
+}
+
+type ApprovalId = string & {
+    readonly __brand: "ApprovalId";
+};
+declare const APPROVAL_STATUSES: readonly ["pending", "approved", "rejected"];
+type ApprovalStatus = (typeof APPROVAL_STATUSES)[number];
+type ApprovalRequest = {
+    id: ApprovalId;
+    runId: RunId;
+    nodeId: NodeId;
+    requestedBy: string;
+    subject: ArtifactRef | {
+        description: string;
+    };
+    status: ApprovalStatus;
+    resolvedBy?: string;
+    resolvedAt?: Date;
+    rejectionReason?: string;
+    createdAt: Date;
+    /** Tenant scope (ADR 0036 #4) — set by the control plane; the engine is tenant-agnostic. */
+    tenantId?: string;
+};
+
+type RequestApprovalParams = {
+    runId: RunId;
+    nodeId: NodeId;
+    requestedBy: string;
+    subject: ArtifactRef | {
+        description: string;
+    };
+    /**
+     * Tenant the approval belongs to (ADR 0036 #4). Optional + back-compat: the engine itself is
+     * tenant-agnostic and omits it; the CONTROL PLANE supplies it so an approval can be tenant-scoped
+     * at the persistence layer (and so off-run gates — e.g. A2A outbound delegation — carry a tenant
+     * even without a real run row). When set, an impl SHOULD persist + filter on it.
+     */
+    tenantId?: string;
+};
+interface ApprovalEngine {
+    request(params: RequestApprovalParams): Promise<ApprovalRequest>;
+    approve(id: ApprovalId, resolvedBy: string): Promise<ApprovalRequest>;
+    reject(id: ApprovalId, resolvedBy: string, reason: string): Promise<ApprovalRequest>;
+    getPending(runId?: RunId): Promise<ApprovalRequest[]>;
+    getById(id: ApprovalId): Promise<ApprovalRequest | undefined>;
+}
+
+declare class ApprovalSelfApprovalError extends Error {
+    constructor(approvalId: ApprovalId);
+}
+declare class ApprovalAlreadyResolvedError extends Error {
+    constructor(approvalId: ApprovalId);
+}
+declare class ApprovalNotFoundError extends Error {
+    constructor(approvalId: ApprovalId);
+}
+
+declare class InMemoryApprovalEngine implements ApprovalEngine {
+    private readonly approvals;
+    request(params: RequestApprovalParams): Promise<ApprovalRequest>;
+    approve(id: ApprovalId, resolvedBy: string): Promise<ApprovalRequest>;
+    reject(id: ApprovalId, resolvedBy: string, reason: string): Promise<ApprovalRequest>;
+    getPending(runId?: RunId): Promise<ApprovalRequest[]>;
+    getById(id: ApprovalId): Promise<ApprovalRequest | undefined>;
+    private getOrThrow;
+    private ensureCanResolve;
+}
+
+/**
+ * Tamper-evident attestation of approval decisions.
+ *
+ * Each resolved approval is hashed (over a canonical, key-sorted view) and signed
+ * with Ed25519. Records are chained — every signature covers the previous record's
+ * hash — so neither a single field nor the ordering of decisions can be altered
+ * after the fact without breaking verification. This is the audit primitive a
+ * regulated environment needs: "what did the agents do, and who approved it" becomes
+ * cryptographically verifiable.
+ */
+type AttestationView = {
+    approvalId: string;
+    runId: string;
+    status: "approved" | "rejected";
+    resolvedBy: string;
+    subject: string;
+    decidedAt: string;
+};
+type AttestationRecord = AttestationView & {
+    algorithm: "ed25519";
+    /** SHA-256 (hex) of the canonical {@link AttestationView}. */
+    payloadHash: string;
+    /** Previous record's `payloadHash`, linking the chain. `null` for the first. */
+    prevHash: string | null;
+    /** Base64 SPKI/DER public key that verifies `signature`. */
+    publicKey: string;
+    /** Base64 Ed25519 signature over the chain hash. */
+    signature: string;
+};
+/** Deterministic JSON: object keys sorted recursively so the hash is stable. */
+declare const canonicalJson: (value: unknown) => string;
+/** Signs approval decisions with an Ed25519 key pair. */
+declare class Ed25519Attestor {
+    private readonly privateKey;
+    private readonly publicKeyB64;
+    constructor(keys?: {
+        privateKey: KeyObject;
+        publicKey: KeyObject;
+    });
+    /** Sign a resolved approval, chaining it after `prevHash`. */
+    attest(request: ApprovalRequest, prevHash?: string | null): AttestationRecord;
+}
+/** Verify a single record: its payload hash is intact and the signature is valid. */
+declare const verifyAttestation: (record: AttestationRecord) => boolean;
+/** Verify a full chain: every record valid and correctly linked to its predecessor. */
+declare const verifyChain: (records: AttestationRecord[]) => boolean;
+
+/** Default channel an agent node writes its {@link import("@ailu-ai/agents-core").AgentResult} into. */
+declare const DEFAULT_AGENT_OUTPUT_CHANNEL = "agentResult";
+/**
+ * Channel holding the names of tools whose human approval has been granted. The
+ * control plane writes it (see `CompiledGraph.approveAndResume`) before resuming a
+ * run that suspended for approval; the agent then executes those tools.
+ */
+declare const APPROVED_TOOLS_CHANNEL = "__approvedTools";
+/** Reason carried by the dynamic interrupt an agent node raises when it needs approval. */
+declare const AGENT_APPROVAL_INTERRUPT = "agent-approval-required";
+/**
+ * Channel holding the ApprovalEngine request ids created when a run suspends for
+ * approval. On resume the node looks each up; the ones the engine reports as
+ * `approved` unlock their tools — the engine is the source of truth, not a flag.
+ */
+declare const APPROVAL_IDS_CHANNEL = "__approvalIds";
+/** Where an agent node gets its system prompt. */
+type AgentPromptSource = {
+    registry: PromptRegistry;
+    id: string;
+    version?: string;
+}
+/** Inline convenience: the SDK registers this string and references it by id. */
+ | {
+    system: string;
+};
+/**
+ * Governed long-term memory overlay for an agent node (ADR 0026 phase 11). `namespace` is the
+ * tenant-scoped memory partition; `topK`/`recall` tune retrieval. The principal is sealed by the
+ * engine. The OSS engine recalls/persists in-memory; the control plane swaps a Neo4j-backed store
+ * (native vector index + entity graph) behind the same seam.
+ */
+type MemoryConfig = {
+    namespace: string;
+    topK?: number;
+    recall?: "vector" | "graph" | "both";
+};
+/**
+ * Governed skills overlay for an agent node (ADR 0035 phase 12) — progressive disclosure for deep
+ * agents. The engine selects skills (explicit `required` pins by `name@version` + advisory vector
+ * top-k over descriptions, capped by `advisoryK`) from this `namespace` before the run and prepends
+ * their bodies to the seed. The `namespace` is tenant-scoped (sealed by the engine); a skill that
+ * grants capability (`requires`) stays withheld until granted. Applies to this agent AND its
+ * `mapAgents`/`taskNode` sub-agents (same build path → deepagents parity). The OSS engine selects
+ * from an in-memory registry; the control plane swaps a Postgres-backed store behind the same seam.
+ */
+type SkillConfig = {
+    namespace: string;
+    /** Explicit `name@version` pins — the must-apply playbooks, always loaded (when granted). */
+    required?: string[];
+    /** Cap on advisory (vector-selected) skills. Default 3; 0 = pins only. */
+    advisoryK?: number;
+};
+/**
+ * One skill RECORD supplied by the control plane for a run (ADR 0049 B-3) — the store contents the
+ * engine builds its run-scoped `SkillStore` from. Matches Rust `Skill` (camelCase). `description` is the
+ * always-resident L1 index; `body` is the on-demand L2; `requires` are approval-gated capability keys.
+ * `allowedTools`/`license`/`metadata` are open-standard SKILL.md fields (ADR 0065 D1) — stored and
+ * round-tripped through import/export, but `allowedTools` is NOT enforced by `SkillMiddleware` yet
+ * (distinct from `requires`, which is the actual capability gate).
+ */
+type SkillRecord = {
+    name: string;
+    version: string;
+    namespace: string;
+    description: string;
+    body?: string;
+    requires?: string[];
+    allowedTools?: string[];
+    license?: string;
+    metadata?: Record<string, unknown>;
+    resources?: Array<{
+        kind?: string;
+        ref: string;
+    }>;
+};
+/** Config for {@link GraphBuilder.agentNode}. */
+type AgentNodeConfig = {
+    /**
+     * @deprecated Ignored: the engine calls the model itself. Use {@link AgentNodeConfig.model}
+     * (`model.openai("gpt-4o")`), and `AILU_LLM_MOCK=1` to run offline.
+     */
+    llm?: LLMGateway;
+    prompt: AgentPromptSource;
+    tools?: ToolRegistry;
+    /**
+     * @deprecated Use {@link AgentNodeConfig.model}: `model.openai("gpt-4o")` or `"openai:gpt-4o"`.
+     * An unknown provider throws `UnknownProviderError`.
+     */
+    provider?: LLMProvider;
+    /**
+     * The model to run: `model.openai("gpt-4o")`, `model.fast`, or a `"provider:model"` string
+     * (`"openai:gpt-4o"`). A bare model id without a provider runs on Anthropic. The model's
+     * provider and tier win over the deprecated flat `provider`/`tier` fields.
+     */
+    model?: string | ModelLike;
+    /**
+     * @deprecated Use a tier model: `model.fast`, `model.mistral.frontier`. Capability tier
+     * (`"frontier" | "balanced" | "fast" | "creative"`), resolved by the engine against the
+     * provider keys present in the environment.
+     */
+    tier?: ModelTier;
+    /**
+     * A named {@link AgentProfile} (`"fast" | "frontier-careful" | "governed-deep"`, ADR 0025
+     * phase 3d) that sets the model tier, efficiency middleware, and suspend/fs defaults in one
+     * shot. Explicit fields (`tier`, `suspendForApproval`, `enableFs`, `middleware`, the flat
+     * `outputStyle`/`contextBudget` knobs) always override the profile's defaults. The governed
+     * layer (redaction, approval gate, fs policy) is identical regardless of profile.
+     */
+    profile?: AgentProfile;
+    /**
+     * Extra EFFICIENCY middleware to append (ADR 0025 phase 3d), e.g. `[{ kind: "compress" }]`.
+     * Efficiency-only by type: governance kinds (redact / approval gate / fs policy) are
+     * engine-injected and rejected here ({@link GovernanceMiddlewareRejectedError}), so an
+     * ungoverned stack is unrepresentable. Merged after the profile + the flat knobs, with
+     * an explicit entry of the same `kind` winning (dedup, last-writer).
+     */
+    middleware?: EfficiencyMiddlewareSpec[];
+    maxIterations?: number;
+    name?: string;
+    description?: string;
+    /** Channel that receives the agent's result. Defaults to {@link DEFAULT_AGENT_OUTPUT_CHANNEL}. */
+    outputChannel?: string;
+    /**
+     * Token-efficiency (ADR 0014). `"terse"` appends a compact-output directive to the
+     * system prompt — cuts output tokens on **prose** stages (lossy; not for code). Default off.
+     */
+    outputStyle?: "terse";
+    /**
+     * Cap (in chars) on the agent's seed message — the injected `Input: <input>\nState:
+     * <state>` dump — to avoid re-feeding an unbounded channel map to every agent. The cap
+     * covers the whole seed message (ADR 0014 intent), not the `State` portion alone. Default: no cap.
+     */
+    contextBudget?: number;
+    /**
+     * Durable channel the agent's `writeTodos` list is persisted into (ADR 0022/0023,
+     * phase 1). When set and the agent has the `writeTodos` tool, the engine writes the
+     * authoritative todo list here in the same checkpointed update as the result, so
+     * downstream nodes can read the plan. Default: no durable sink (the list still
+     * appears in the result). Conventionally {@link import("@ailu-ai/agents-core").TODOS_CHANNEL} (`"__todos"`).
+     */
+    todosChannel?: string;
+    /**
+     * Channel carrying this run's multimodal input (ADR 0030 phase 9e): a `ContentBlock[]`
+     * value (`{ type: "image" | "audio" | "file", source }` + optional `{ type: "text" }`).
+     * When set, the agent's seed message becomes multimodal — a text Input/State digest plus
+     * the media blocks — and this channel is excluded from the stringified State (so binary
+     * bytes are never re-fed as text). Seed the channel via the run's `initialData`. Default:
+     * text-only seed.
+     */
+    inputBlocksChannel?: string;
+    /** The only channels the agent is shown in its seed state (context isolation); default all. */
+    visibleChannels?: string[];
+    /**
+     * Governed long-term memory (ADR 0026 phase 11). When set, the engine recalls from this
+     * namespace before the run (vector) and persists the run's reasoning after, attributed. The
+     * `namespace` is tenant-scoped (the control plane validates access) and the principal is
+     * sealed by the engine — never user-routable. `topK`/`recall` tune retrieval quality.
+     */
+    memory?: MemoryConfig;
+    /**
+     * Governed skills — progressive disclosure (ADR 0035 phase 12). When set, the engine selects
+     * skills (explicit `required` pins + advisory vector top-k) from this `namespace` before the run
+     * and prepends their bodies to the seed. Capability-granting (`requires`) skills are withheld
+     * until granted. Applies to `mapAgents`/`taskNode` sub-agents too (deepagents parity).
+     */
+    skills?: SkillConfig;
+    /**
+     * Opt this agent into the governed virtual filesystem tools (ADR 0024 phase 2b):
+     * `read_file`/`ls`/`glob`/`grep`/`write_file`/`edit_file`/`delete_file`/`move_file`,
+     * run-scoped over a versioned artifact store and enforced by the graph's
+     * {@link GraphBuilder.fsPolicy} (fail-closed read-only by default). Default off.
+     */
+    enableFs?: boolean;
+    /**
+     * When true, the node suspends the whole run (a dynamic interrupt) the moment the
+     * agent needs approval, instead of just flagging `requiresHumanReview`. Resume with
+     * `CompiledGraph.approveAndResume(runId, { approvedTools })` to continue. Default false.
+     */
+    suspendForApproval?: boolean;
+    /**
+     * @deprecated Removed: a graph that sets it fails to compile. Use `suspendForApproval` with
+     * `approveAndResume`, or pass the engine to the catalog runner:
+     * `runCatalogGraph(app.definition, { approvalEngine })`.
+     */
+    approvalEngine?: ApprovalEngine;
+    label?: string;
+};
+/**
+ * A signed-off agent profile (ADR 0025 phase 3d) — a named bundle that expands to a model
+ * tier, an efficiency-middleware set, and suspend/fs defaults. The GOVERNED layer (PII
+ * redaction, the approval gate, fs policy) is identical across all profiles — you cannot
+ * "buy out" of governance. Explicit `tier`/`suspendForApproval`/`enableFs`/`middleware` on
+ * the config always win over the profile's defaults.
+ *
+ * - `fast` — `fast` tier, full efficiency (compress + terse + tight 4k context budget), no
+ *   suspend. For high-throughput, low-stakes prose work.
+ * - `frontier-careful` — `frontier` tier, NO compression (preserve fidelity), a roomy 16k
+ *   budget, reflection, suspend-on-approval. For high-stakes reasoning where lossy compression
+ *   is unsafe.
+ * - `governed-deep` — the deep-agent one-liner: `balanced` tier, full efficiency (12k budget),
+ *   reflection, suspend-on-approval, and the governed virtual filesystem enabled.
+ */
+type AgentProfile = "fast" | "frontier-careful" | "governed-deep";
+/**
+ * An EFFICIENCY / quality middleware a user may append to an agent (ADR 0025 phase 3d/3e). The
+ * governance kinds (`redact` / `approvalGate` / `fsPolicy`) are deliberately NOT part of this
+ * union — they are engine-injected and sealed, so a user cannot express an ungoverned stack
+ * (the governed-by-construction invariant). `retry` / `rateLimit` stay deferred (retry belongs
+ * at the gateway; a rate-limit delay would conflict with the engine's determinism).
+ *
+ * - `compress` — route messages through the prompt-compression service (no-op if unconfigured).
+ * - `terse` — append a compact-output directive to the system prompt (lossy; prose only).
+ * - `contextBudget` — cap the agent's seed message (the injected `Input`/`State` dump) to `chars` characters.
+ * - `reflection` — one self-critique after the run (ADR 0025 phase 3e): a weak result is flagged in
+ *   the reasoning (`reflection:needs_review:<issues>`) for observability / downstream routing (a
+ *   conditional edge can gate on it). It does NOT set `requiresHumanReview` — that would re-suspend
+ *   forever on resume. Additive — the full critique→revise loop stays the standalone reflection
+ *   node. `threshold` (0..1, default 0.8) is the acceptance bar.
+ * - `structuredOutput` — constrain the agent's output to a JSON Schema (ADR 0029 phase 8). The
+ *   engine sets the provider's native constraint (OpenAI `response_format`, Anthropic forced tool,
+ *   Gemini `responseSchema`) AND validates the result in-engine (the floor). The validated value
+ *   lands on `AgentResult.structuredOutput`. `mode: "required"` (default) fails closed with a typed
+ *   error after `retryCap` (default 2) deterministic re-prompts; `mode: "lenient"` falls back to raw
+ *   text. It is an EFFICIENCY kind (output-shaping), and the approval gate stays intrinsic — so it
+ *   cannot route around governance.
+ */
+type EfficiencyMiddlewareSpec = {
+    kind: "compress";
+} | {
+    kind: "terse";
+} | {
+    kind: "contextBudget";
+    params: {
+        chars: number;
+    };
+} | {
+    kind: "reflection";
+    params?: {
+        threshold?: number;
+    };
+} | {
+    kind: "structuredOutput";
+    params: {
+        schema: Record<string, unknown>;
+        name?: string;
+        strict?: boolean;
+        mode?: "required" | "lenient";
+        retryCap?: number;
+    };
+};
+/**
+ * Governance middleware kinds the SDK rejects in {@link AgentNodeConfig.middleware}: they are
+ * engine-injected (the GOVERNED layer), never user-supplied. Shared so the SDK throw-gate and
+ * the contracts efficiency-only schema list the SAME kinds (they cannot drift). Passing one to
+ * the builder throws `GovernanceMiddlewareRejectedError`. (The runtime enforcer on the Rust
+ * side is independent: the bridge match only honours efficiency kinds and ignores these.)
+ */
+declare const GOVERNANCE_MIDDLEWARE_KINDS: readonly ["redact", "approvalGate", "fsPolicy"];
+/** A filesystem permission verb (ADR 0024): `deny` < `read` < `gate` < `write`. */
+type FsPermVerb = "deny" | "read" | "write" | "gate";
+/**
+ * A per-path filesystem permission rule (ADR 0024 phase 2b): a glob (`*` within a
+ * path segment, `**` across) mapped to a verb. Compiled into the run's fail-closed
+ * path policy ({@link GraphBuilder.fsPolicy}). An unmatched path resolves to `read`.
+ */
+type FsPolicyRule = {
+    glob: string;
+    verb: FsPermVerb;
+};
+/**
+ * Config for {@link GraphBuilder.mapAgents} — a dynamic fan-out (ADR 0027 phase 4b): run
+ * `subAgent` once per item in the `overChannel` array, concurrently, and write the per-item
+ * results — in input order (deterministic) — into `joinAt` as an array. Each spawn gets one item
+ * as its input and shares the run's channels.
+ */
+type MapAgentNodeConfig = {
+    /** Channel holding the array of items to map the sub-agent over. */
+    overChannel: string;
+    /** The sub-agent to run per item (its own ReAct agent config). */
+    subAgent: AgentNodeConfig;
+    /** Channel the array of per-item results lands in (one entry per item, in input order). */
+    joinAt: string;
+    /** When true, a spawn that needs approval suspends the whole map (default false). */
+    suspendForApproval?: boolean;
+    label?: string;
+};
+/** The wire projection of a {@link MapAgentNodeConfig} the Rust bridge consumes (`map_agents`). */
+type RustMapAgentConfig = {
+    overChannel: string;
+    joinAt: string;
+    agent: RustAgentConfig;
+    suspendForApproval: boolean;
+};
+/** Config for {@link GraphBuilder.toolNode}. */
+type ToolNodeConfig = {
+    tools: ToolRegistry;
+    /** Execute all tool calls concurrently instead of sequentially. */
+    parallel?: boolean;
+    label?: string;
+};
+/**
+ * Config for {@link GraphBuilder.taskNode} — spawn a sub-agent in an isolated context
+ * that returns a single compressed report (ADR 0022/0023, phase 1). The spawn is sugar
+ * over a one-node subgraph, so it inherits the runtime's guarantees: checkpointed,
+ * audited, and human-gate-preserving (a sub-agent that suspends for approval suspends
+ * the whole run).
+ */
+type TaskNodeConfig = {
+    /** The sub-agent to spawn (its own ReAct agent config). */
+    subAgent: AgentNodeConfig;
+    /**
+     * The channel that feeds the sub-agent its objective — the ONLY channel projected
+     * into the child (isolation). Default `"objective"`.
+     */
+    objectiveChannel?: string;
+    /**
+     * The channel the sub-agent's report lands in — the ONLY channel projected back to
+     * the parent (a single value out). Default `"report"`.
+     */
+    reportChannel?: string;
+    /**
+     * Run the sub-agent with `outputStyle: "terse"` so the report is a summary, not a
+     * full transcript. Default true.
+     */
+    compress?: boolean;
+    label?: string;
+};
+/**
+ * A tool's name plus its TS `execute` fn — the data the Rust bridge needs to back a
+ * `jsToolName` with a JS callback. The Rust engine never imports the tool registry;
+ * it calls this `execute` over the napi seam (`on_node` with `kind:"tool"`).
+ */
+type RustToolBinding = {
+    name: string;
+    execute: (input: unknown) => Promise<unknown>;
+};
+/**
+ * How one of an agent's tools is advertised to the LLM (→ Rust `AgentSpec.toolSpecs`): the tool's
+ * `description` and the JSON Schema of its input (`ToolDefinition.jsonSchema`). Serializable, so
+ * it also rides the persisted agent carrier.
+ */
+type RustToolSpec = {
+    name: string;
+    description?: string;
+    jsonSchema?: Record<string, unknown>;
+};
+/**
+ * The serializable shape of an agent node, plus its JS-backed tool executes, that
+ * the Rust engine bridge consumes (see `EngineSpec.agents` / `jsToolNames`). It is a
+ * pure projection of {@link AgentNodeConfig} — the system prompt is the *resolved*
+ * string (never a registry reference), since the bridge has no prompt registry.
+ *
+ * The LLM gateway itself is **not** carried: the Rust agent path builds its own
+ * gateway (env adapters or a deterministic mock). A graph whose agents rely on a
+ * specific TS `AgentNodeConfig.llm` therefore keeps its semantics only on the TS
+ * engine; the Rust path is opt-in for agents (see `CompiledGraph`).
+ */
+type RustAgentConfig = {
+    provider: string;
+    model?: string;
+    /**
+     * Abstract capability tier carried to the Rust `AgentSpec.tier`. When set with no
+     * explicit `model`, the Rust bridge resolves the concrete model via `ModelPolicy`
+     * against the process env. An explicit `model` always wins.
+     */
+    tier?: ModelTier;
+    /**
+     * A custom OpenAI-compatible endpoint (`model.openaiCompatible({ baseURL })`). The Rust bridge
+     * serves the agent through the OpenAI-wire adapter at this URL, with the key read only from
+     * {@link apiKeyEnv} (never `OPENAI_API_KEY`).
+     */
+    baseURL?: string;
+    /** Env var holding the key for {@link baseURL}; unset means a keyless endpoint. */
+    apiKeyEnv?: string;
+    /** Resolved system prompt string. */
+    system?: string;
+    toolNames: string[];
+    /** What the LLM is told about each tool: its description and input JSON Schema. */
+    toolSpecs?: RustToolSpec[];
+    maxIterations?: number;
+    suspendForApproval: boolean;
+    /** Tools (by name) requiring approval — those marked `requiresApproval`. */
+    approvalToolNames: string[];
+    outputChannel: string;
+    /** ADR 0014 — terse output directive on the system prompt. */
+    outputStyle?: "terse";
+    /** ADR 0014 — cap (chars) on the injected seed message (the `Input`/`State` dump). */
+    contextBudget?: number;
+    /** ADR 0022/0023 — durable channel the `writeTodos` list is persisted into. */
+    todosChannel?: string;
+    /** ADR 0030 phase 9e — channel carrying the run's multimodal input blocks. */
+    inputBlocksChannel?: string;
+    /** The only channels the agent is shown in its seed state (context isolation); default all. */
+    visibleChannels?: string[];
+    /** ADR 0026 phase 11 — governed long-term memory overlay. */
+    memory?: MemoryConfig;
+    /** ADR 0035 phase 12 — governed skills (progressive disclosure) overlay. */
+    skills?: SkillConfig;
+    /** ADR 0024 phase 2b — opt this agent into the governed virtual filesystem tools. */
+    enableFs?: boolean;
+    /**
+     * ADR 0025 phase 3d — the SDK-resolved EFFICIENCY middleware list: the profile + explicit
+     * `middleware[]` + the legacy `outputStyle`/`contextBudget` knobs expanded into one ordered
+     * list of `{ kind, params }` data entries the Rust bridge turns into `push_efficiency`
+     * calls. The governed layer is never carried here (the bridge injects it). Always present
+     * (possibly empty) on the live builder path; absent on a pre-3d persisted carrier (the Rust
+     * bridge then falls back to the legacy flat knobs).
+     */
+    resolvedMiddleware?: EfficiencyMiddlewareSpec[];
+    /** JS-backed tool executes, one per tool in the registry. */
+    toolBindings: RustToolBinding[];
+    /**
+     * SDK-only (never serialized to the wire): whether this agent node sets the removed
+     * `approvalEngine` option, which makes the graph fail to compile (see `CompiledGraph`).
+     */
+    usesApprovalEngine: boolean;
+};
+/**
+ * The approval binding an agent node contributes to {@link CompiledGraph}: the principal that
+ * *requests* approvals on this node's behalf (`config.name ?? nodeId`) and the names of its
+ * approval-gated tools. {@link CompiledGraph.approveAndResume} uses it to stamp each granted
+ * tool's `requestedBy` for the engine's no-self-approval check.
+ */
+type AgentApprovalBinding = {
+    approvalEngine?: ApprovalEngine;
+    requestedBy: string;
+    approvalToolNames: string[];
+};
+/** Project an {@link AgentNodeConfig} into its {@link AgentApprovalBinding}. */
+declare const toAgentApprovalBinding: (nodeId: string, config: AgentNodeConfig) => AgentApprovalBinding;
+/**
+ * Project an {@link AgentNodeConfig} into the {@link RustAgentConfig} the Rust engine
+ * bridge consumes. Resolves the system prompt to a concrete string, pulls the tool
+ * names / approval flags / executes out of the registry, and desugars the profile +
+ * middleware into a {@link RustAgentConfig.resolvedMiddleware} list. Pure — no LLM call.
+ */
+declare const toRustAgentConfig: (nodeId: string, config: AgentNodeConfig) => RustAgentConfig;
+/** Config for {@link streamAgentTokens}. */
+type StreamAgentConfig = {
+    llm: LLMGateway;
+    prompt: AgentPromptSource;
+    provider?: LLMProvider;
+    model?: string;
+};
+/**
+ * Stream an agent's reply token by token through the gateway's `stream()`. This is
+ * the single-turn (no-tools) path — ideal for a chat UI that wants live output.
+ * Yields text deltas as they arrive and returns when the provider signals done.
+ *
+ * ```ts
+ * for await (const delta of streamAgentTokens({ llm, prompt: { system } }, "Bonjour ?")) {
+ *   process.stdout.write(delta);
+ * }
+ * ```
+ */
+declare function streamAgentTokens(config: StreamAgentConfig, input: unknown): AsyncIterable<string>;
+declare const createAgentNodeHandler: (nodeId: string, config: AgentNodeConfig) => NodeHandler;
+/**
+ * Build the handler for a tool node: executes the tool calls emitted by the last
+ * AI message in the `messages` channel. Tools flagged `requiresApproval` suspend
+ * the run via a dynamic interrupt instead of executing.
+ */
+declare const createToolNodeHandler: (config: ToolNodeConfig) => NodeHandler;
+
+/**
+ * The component library surface: pure (no-LLM) compute building blocks addressable
+ * by a string `kind` plus a `params` object. Mirrors the Rust `ailu_components`
+ * library (`crates/components`) one-for-one in kind, params and behaviour.
+ *
+ * Each factory in {@link components} returns a {@link ComponentDescriptor}: the Phase
+ * C carrier the Rust engine needs (`{ kind, params }`, surfaced as the graph's
+ * `componentNodes` map) **and** a faithful TypeScript `handler` for the fallback path
+ * when the native addon is absent. The components are simple and pure, so the two
+ * implementations agree byte-for-byte on ASCII input.
+ *
+ * Use {@link GraphBuilder.component} to push a node carrying both:
+ *
+ * ```ts
+ * import { createGraph, components } from "@ailu-ai/graph-sdk";
+ *
+ * const app = createGraph({ name: "prompt" })
+ *   .channel("name", { type: "string", default: "" })
+ *   .channel("prompt", { type: "string", default: "" })
+ *   .component("build", components.promptBuilder({ template: "Hi {{name}}", into: "prompt" }))
+ *   .compile();
+ * ```
+ */
+
+/** The component kinds the library knows, matching `ComponentRegistry::kinds()`. */
+type ComponentKind = "promptBuilder" | "jsonValidator" | "outputParser" | "router" | "retriever" | "reranker" | "textCleaner" | "documentSplitter" | "htmlToText" | "csvParser" | "documentJoiner" | "deduplicator" | "truncator" | "regexExtractor" | "answerBuilder" | "fieldMapper" | "fieldExtractor" | "bm25Retriever" | "keywordRetriever" | "sentenceWindowSplitter" | "languageDetector" | "metadataFilter" | "listJoiner" | "mergeRanker" | "evaluator" | "chatMessageBuilder" | "conditionalRouter" | "documentWriter";
+/**
+ * The serializable projection of a component node the Rust engine bridge consumes
+ * (the Phase C `componentNodes` carrier, camelCase): a component `kind` plus its
+ * validated `params` object. Pure data — no closures.
+ */
+type RustComponentConfig = {
+    kind: ComponentKind;
+    params: Record<string, unknown>;
+};
+/**
+ * What a component factory returns: the Phase C carrier (`kind` + `params`) so the
+ * node runs natively on Rust, plus an equivalent TS {@link NodeHandler} for the
+ * fallback path. {@link GraphBuilder.component} pushes a node from this descriptor.
+ */
+type ComponentDescriptor = RustComponentConfig & {
+    /** The faithful TS-equivalent handler used when the native addon is absent. */
+    handler: NodeHandler;
+};
+/**
+ * What an **integration component** factory returns (the vendor-I/O pattern, e.g.
+ * {@link components.httpFetch} / {@link components.webSearch}). Unlike a
+ * {@link ComponentDescriptor}, an integration component is **not** a Rust component:
+ * it has no `kind`/`params` carrier and is **not** registered in `componentNodes`.
+ * It is a plain `NodeHandler` (an injectable closure over an injected I/O impl) added
+ * as a regular JS node via {@link import("./builder.js").GraphBuilder.node}; on the
+ * Rust engine it runs over the async JS seam (`on_node`) like any other JS handler.
+ *
+ * ```ts
+ * createGraph({ name: "fetch" })
+ *   .channel("body", { type: "json", default: null })
+ *   .node("get", components.httpFetch({ url: "https://x", into: "body", fetchImpl: fake }));
+ * ```
+ */
+type IntegrationComponentHandler = NodeHandler;
+/** ADR 0044 D3 (ailu#578) capsule-assembly config for {@link components.promptBuilder}.
+ * `chunksFrom`/`queryFrom` are required, `discardedFrom` is optional (defaults to none) — a
+ * capsule-assembly node needs to be told explicitly which upstream channel holds the query and
+ * which channels hold this pipeline's discarded candidates (they can be scattered across several
+ * stages — D2's `{into}Discarded` channels are stage-local, not a single sibling of `chunksFrom`). */
+type PromptBuilderCapsuleConfig = {
+    into: string;
+    chunksFrom: string;
+    queryFrom: string;
+    discardedFrom?: string[];
+};
+/** Params for {@link components.promptBuilder}. */
+type PromptBuilderParams = {
+    /** Template with `{{var}}` placeholders filled from the channels. */
+    template: string;
+    /** Channel the rendered string is written into. */
+    into: string;
+    /** Optional retrieval-proof-capsule assembly (ADR 0044 D3) — captures the exact set that
+     * influenced the model, hashed at the ONE node that knows what text was actually templated. */
+    capsule?: PromptBuilderCapsuleConfig;
+};
+/** Params for {@link components.jsonValidator}. */
+type JsonValidatorParams = {
+    /** Channel whose value is validated. */
+    from: string;
+    /** Required object keys to assert present. */
+    requiredKeys?: string[];
+    /** Expected JSON type (`"object" | "array" | "string" | ...`). */
+    expectType?: "string" | "number" | "boolean" | "object" | "array" | "null";
+    /** Channel receiving the `boolean` validity flag. */
+    okInto: string;
+    /** Channel receiving the `string[]` of validation errors. */
+    errorsInto: string;
+};
+/** Params for {@link components.outputParser}. */
+type OutputParserParams = {
+    /** Text channel to extract the first JSON value from. */
+    from: string;
+    /** Channel receiving the parsed value (or `null` when none is found). */
+    into: string;
+};
+/** One routing rule for {@link components.router}. */
+type RouterRule = {
+    /** Exact match against the textual form of the `from` value. */
+    equals?: string;
+    /** Substring match against the textual form of the `from` value. */
+    contains?: string;
+    /** The route string emitted when this rule matches. */
+    route: string;
+};
+/** Params for {@link components.router}. */
+type RouterParams = {
+    /** Channel whose value is matched against the rules. */
+    from: string;
+    /** Ordered rules; the first match wins. */
+    rules: RouterRule[];
+    /** Route emitted when no rule matches. */
+    defaultRoute: string;
+    /** Channel the chosen route string is written into. */
+    into: string;
+};
+/** A candidate document for {@link components.retriever}. */
+type RetrieverDoc = {
+    id: string;
+    content: string;
+};
+/** Params for {@link components.retriever}. */
+type RetrieverParams = {
+    /** Channel holding the query text (falls back to this literal when the channel is empty). */
+    query: string;
+    /** Channel receiving the top-`k` `{ id, content, score }` array. */
+    into: string;
+    /** Number of results to keep (default 4). */
+    k?: number;
+    /** The corpus to score against. */
+    docs: RetrieverDoc[];
+};
+/** Params for {@link components.reranker}. */
+type RerankerParams = {
+    /** Channel holding the retrieval-result array to reorder. */
+    from: string;
+    /** Channel receiving the reordered array. */
+    into: string;
+    /** Optional channel holding the query text the cross-encoder (`AILU_RERANK_ENDPOINT`)
+     * re-scores against. Without an endpoint, items keep their upstream order (by `score`). */
+    query?: string;
+};
+/** Params for {@link components.textCleaner}. */
+type TextCleanerParams = {
+    /** Channel whose text is normalised. */
+    from: string;
+    /** Channel receiving the cleaned text. */
+    into: string;
+    /** Lowercase the text. Defaults to `false`. */
+    lowercase?: boolean;
+    /** Strip `<…>` HTML tags. Defaults to `false`. */
+    stripHtml?: boolean;
+    /** Collapse runs of whitespace to a single space. Defaults to `false`. */
+    collapseWhitespace?: boolean;
+    /** Trim leading/trailing whitespace. Defaults to `false`. */
+    trim?: boolean;
+};
+/** Params for {@link components.documentSplitter}. */
+type DocumentSplitterParams = {
+    /** Channel holding the text to split. */
+    from: string;
+    /** Channel receiving the `string[]` of chunks. */
+    into: string;
+    /** Split unit: `"chars"` sliding windows or greedy `"sentences"` packing. */
+    by: "chars" | "sentences";
+    /** Window size in characters (`by:"chars"`) or sentences (`by:"sentences"`). Must be > 0. */
+    size: number;
+    /** Overlap repeated at the start of each next chunk. Must be smaller than `size`. Defaults to 0. */
+    overlap?: number;
+};
+/** Params for {@link components.htmlToText}. */
+type HtmlToTextParams = {
+    /** Channel holding the HTML text. */
+    from: string;
+    /** Channel receiving the tag-stripped, entity-decoded text. */
+    into: string;
+};
+/** Params for {@link components.csvParser}. */
+type CsvParserParams = {
+    /** Channel holding the CSV text. */
+    from: string;
+    /** Channel receiving the parsed rows array. */
+    into: string;
+    /** Single-character cell delimiter. Defaults to `","`. */
+    delimiter?: string;
+    /** When `true` (default) the first row supplies object keys; otherwise rows are arrays. */
+    header?: boolean;
+};
+/** Params for {@link components.documentJoiner}. */
+type DocumentJoinerParams = {
+    /** Channels whose array values are concatenated in order. */
+    fromChannels: string[];
+    /** Channel receiving the merged array. */
+    into: string;
+    /** Optional object field to de-duplicate the merged items by. */
+    dedupeBy?: string;
+};
+/** Params for {@link components.deduplicator}. */
+type DeduplicatorParams = {
+    /** Channel holding the array to de-duplicate. */
+    from: string;
+    /** Channel receiving the de-duplicated array. */
+    into: string;
+    /** Optional object field to compare items by (else whole-value compare). */
+    key?: string;
+};
+/** Params for {@link components.truncator}. */
+type TruncatorParams = {
+    /** Channel holding the text to truncate. */
+    from: string;
+    /** Channel receiving the (possibly truncated) text. */
+    into: string;
+    /** Maximum character length (the ellipsis counts against this budget). */
+    maxChars: number;
+    /** Suffix appended when truncated. Defaults to `"…"`. */
+    ellipsis?: string;
+};
+/** Params for {@link components.regexExtractor}. */
+type RegexExtractorParams = {
+    /** Channel holding the text to match against. */
+    from: string;
+    /** Channel receiving the match (or matches when `all`). */
+    into: string;
+    /**
+     * Literal-substring pattern with optional leading `^` (start) and trailing `$`
+     * (end) anchors. No character classes / quantifiers / capture groups.
+     */
+    pattern: string;
+    /** Accepted for forward-compat; only `0` (the whole match) is supported. Defaults to 0. */
+    group?: number;
+    /** When `true`, return every non-overlapping occurrence as an array. Defaults to `false`. */
+    all?: boolean;
+};
+/** Params for {@link components.answerBuilder}. */
+type AnswerBuilderParams = {
+    /** Channel supplying the core answer text. */
+    from: string;
+    /** Channel receiving the assembled answer. */
+    into: string;
+    /** Optional channel holding a retrieval-result array rendered as numbered citations. */
+    contextFrom?: string;
+    /** Optional `{{answer}}`/`{{citations}}` template controlling the layout. */
+    template?: string;
+};
+/** Params for {@link components.fieldMapper}. */
+type FieldMapperParams = {
+    /** Channel holding the source object. */
+    from: string;
+    /** Channel receiving the remapped object. */
+    into: string;
+    /** `{ outKey: inKeyPath }` map; `inKeyPath` is a dotted path into the source. */
+    mapping: Record<string, string>;
+};
+/** Params for {@link components.fieldExtractor}. */
+type FieldExtractorParams = {
+    /** Channel holding the source value. */
+    from: string;
+    /** Channel receiving the extracted scalar. */
+    into: string;
+    /** Optional dotted path descended into the `from` value (else the whole value). */
+    path?: string;
+    /**
+     * When `true`, if the resulting value is a string containing a `"final:"` marker,
+     * return only the text after the **last** `"final:"` (trimmed) — reduces an
+     * agent reasoning trace to its final answer. Non-strings pass through. Defaults to `false`.
+     */
+    finalOnly?: boolean;
+};
+/** A candidate document for the lexical retrievers. */
+type LexicalDoc = {
+    id: string;
+    content: string;
+};
+/** Params for {@link components.bm25Retriever}. */
+type Bm25RetrieverParams = {
+    /** Channel holding the query text (falls back to this literal when empty). */
+    query: string;
+    /** Channel receiving the top-`k` `{ id, content, score }` array. */
+    into: string;
+    /** Number of results to keep (default 4). */
+    k?: number;
+    /** The corpus to rank. */
+    docs: LexicalDoc[];
+    /** BM25 term-frequency saturation. Defaults to 1.2. */
+    k1?: number;
+    /** BM25 length-normalization. Defaults to 0.75. */
+    b?: number;
+};
+/** Params for {@link components.keywordRetriever}. */
+type KeywordRetrieverParams = {
+    /** Channel holding the query text (falls back to this literal when empty). */
+    query: string;
+    /** Channel receiving the top-`k` `{ id, content, score }` array. */
+    into: string;
+    /** Number of results to keep (default 4). */
+    k?: number;
+    /** The corpus to rank. */
+    docs: LexicalDoc[];
+};
+/** Params for {@link components.sentenceWindowSplitter}. */
+type SentenceWindowSplitterParams = {
+    /** Channel holding the text to split. */
+    from: string;
+    /** Channel receiving the `string[]` of overlapping sentence windows. */
+    into: string;
+    /** Sentences per window. Defaults to 3. */
+    windowSize?: number;
+    /** Sentences advanced between windows (`1 <= stride <= windowSize`). Defaults to 1. */
+    stride?: number;
+};
+/** Params for {@link components.languageDetector}. */
+type LanguageDetectorParams = {
+    /** Channel holding the text to classify. */
+    from: string;
+    /** Channel receiving the detected language code (`"en" | "fr" | ... | "und"`). */
+    into: string;
+    /** Optional channel receiving the winning language's share of hits in `[0, 1]`. */
+    confidenceInto?: string;
+};
+/** A predicate operator shared by {@link components.metadataFilter} and {@link components.conditionalRouter}. */
+type PredicateOp = "equals" | "notEquals" | "contains" | "exists" | "absent" | "gt" | "gte" | "lt" | "lte";
+/** Params for {@link components.metadataFilter}. */
+type MetadataFilterParams = {
+    /** Channel holding the array to filter. */
+    from: string;
+    /** Channel receiving the filtered array. */
+    into: string;
+    /** Dotted path into each item compared by the predicate. */
+    field: string;
+    /** The predicate operator. */
+    op: PredicateOp;
+    /** The comparison value (required except for `exists`/`absent`). */
+    value?: unknown;
+};
+/** Params for {@link components.listJoiner}. */
+type ListJoinerParams = {
+    /** Channels whose array values are combined. */
+    fromChannels: string[];
+    /** Channel receiving the combined array. */
+    into: string;
+    /** Combine mode: `"concat"` (default), `"union"` (dedupe), or `"interleave"`. */
+    mode?: "concat" | "union" | "interleave";
+};
+/** Params for {@link components.mergeRanker}. */
+type MergeRankerParams = {
+    /** Channels each holding a retrieval-result array to fuse. */
+    fromChannels: string[];
+    /** Channel receiving the fused `{ id, content, score }` array. */
+    into: string;
+    /** Object field identifying items across lists. Defaults to `"id"`. */
+    idKey?: string;
+    /** Keep only the top-`k` fused results (default: keep all). */
+    k?: number;
+    /** Reciprocal Rank Fusion constant. Defaults to 60. */
+    rrfK?: number;
+};
+/** Params for {@link components.evaluator}. */
+type EvaluatorParams = {
+    /** Channel holding the expected/reference text. */
+    expectedFrom: string;
+    /** Channel holding the actual/candidate text. */
+    actualFrom: string;
+    /** Channel receiving the numeric score in `[0, 1]`. */
+    into: string;
+    /** Scoring metric. Defaults to `"tokenF1"`. */
+    metric?: "tokenF1" | "overlap" | "exact";
+    /** Optional channel receiving a boolean `score >= threshold`. */
+    passInto?: string;
+    /** Pass threshold for `passInto`. Defaults to 0.5. */
+    threshold?: number;
+};
+/** One message spec for {@link components.chatMessageBuilder}. */
+type ChatMessageSpec = {
+    /** The message role. */
+    role: "system" | "user" | "assistant";
+    /** A literal body, rendered through the `{{var}}` template engine. */
+    content?: string;
+    /** A channel name whose value supplies the body verbatim. */
+    contentFrom?: string;
+};
+/** Params for {@link components.chatMessageBuilder}. */
+type ChatMessageBuilderParams = {
+    /** Channel receiving the `[{ role, content }]` array. */
+    into: string;
+    /** The ordered message specs. */
+    messages: ChatMessageSpec[];
+    /** Optional channel prepended as a leading system message when non-empty. */
+    systemFrom?: string;
+};
+/** One branch for {@link components.conditionalRouter}. */
+type ConditionalRouterBranch = {
+    /** The predicate evaluated against the channels (`field` is a dotted path). */
+    when: {
+        field: string;
+        op: PredicateOp;
+        value?: unknown;
+    };
+    /** The route string emitted when `when` holds. */
+    route: string;
+};
+/** Params for {@link components.conditionalRouter}. */
+type ConditionalRouterParams = {
+    /** Channel the chosen route string is written into. */
+    into: string;
+    /** Route emitted when no branch matches. */
+    defaultRoute: string;
+    /** Ordered branches; the first matching branch wins. */
+    branches: ConditionalRouterBranch[];
+};
+/** Params for {@link components.documentWriter}. */
+type DocumentWriterParams = {
+    /** Channel holding the incoming documents array to append. */
+    from: string;
+    /** Channel receiving the accumulated store array. */
+    into: string;
+    /** Channel holding the current store. Defaults to `into`. */
+    store?: string;
+    /** Optional object field to de-duplicate the merged store by. */
+    dedupeBy?: string;
+};
+/**
+ * The result of an HTTP fetch surfaced into the `into` channel.
+ *
+ * The default impl never throws on a non-2xx response or a transport error — a
+ * failure is surfaced as data so a graph degrades gracefully instead of crashing
+ * the run:
+ *  - on a completed response: `{ status, ok, body, json }` (`json` is the parsed
+ *    body when the `content-type` is JSON, else `undefined`; `ok` mirrors
+ *    `Response.ok`, i.e. a 2xx status);
+ *  - on a transport error / timeout: `{ ok: false, error }` (`status`/`body` absent).
+ */
+type HttpFetchResult = {
+    /** The HTTP status code, when a response was received. */
+    status?: number;
+    /** `true` for a 2xx response; `false` on a non-2xx response or a transport error. */
+    ok: boolean;
+    /** The response body as text, when a response was received. */
+    body?: string;
+    /** The parsed JSON body, present only when the response `content-type` was JSON. */
+    json?: unknown;
+    /** The error message, present only on a transport error / timeout. */
+    error?: string;
+};
+/**
+ * The transport an {@link HttpFetchImpl} is invoked with: the resolved URL plus the
+ * request options the default impl assembled from the params (method/headers/body/
+ * the abort `signal` driving the timeout). Mirrors the `(input, init)` shape of the
+ * WHATWG `fetch`, so `globalThis.fetch` is itself a valid impl.
+ */
+type HttpFetchRequestInit = {
+    method: string;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+};
+/**
+ * An injectable fetch implementation. Receives the resolved URL and the assembled
+ * request init, and must resolve to something `Response`-shaped (`status`, `ok`,
+ * `text()`, `headers.get()`). The real `globalThis.fetch` satisfies this — the
+ * default impl simply calls it — so a test can inject a fake `Response`-like object.
+ */
+type HttpFetchImpl = (url: string, init: HttpFetchRequestInit) => Promise<HttpFetchResponseLike> | HttpFetchResponseLike;
+/** The minimal `Response`-shaped surface the default httpFetch impl consumes. */
+type HttpFetchResponseLike = {
+    status: number;
+    ok: boolean;
+    text(): Promise<string> | string;
+    headers: {
+        get(name: string): string | null;
+    };
+};
+/** Params for {@link components.httpFetch}. */
+type HttpFetchParams = {
+    /** A literal URL to fetch (mutually exclusive with `urlFrom`). */
+    url?: string;
+    /** A channel whose value supplies the URL (takes precedence when its channel is set). */
+    urlFrom?: string;
+    /** Channel receiving the {@link HttpFetchResult}. */
+    into: string;
+    /** HTTP method. Defaults to `"GET"`. */
+    method?: string;
+    /** Request headers sent with the call. */
+    headers?: Record<string, string>;
+    /** Request body (sent verbatim) for non-GET methods. */
+    body?: string;
+    /** Abort the request after this many milliseconds (drives an `AbortController`). */
+    timeoutMs?: number;
+    /**
+     * The transport to call. Defaults to the real `globalThis.fetch`. Inject a fake
+     * (a `Response`-like returning function) to keep a test offline, or to point the
+     * call at a stub transport.
+     */
+    fetchImpl?: HttpFetchImpl;
+};
+/** One web-search result: a title, a url and a snippet. */
+type WebSearchResult = {
+    title: string;
+    url: string;
+    snippet: string;
+};
+/**
+ * What the web-search connector writes into the `into` channel: the normalized
+ * `results` plus an optional `note`. The default connector populates `note` when it
+ * degrades gracefully (e.g. no `TAVILY_API_KEY`), leaving `results` empty so a graph
+ * runs without crashing.
+ */
+type WebSearchOutcome = {
+    results: WebSearchResult[];
+    note?: string;
+};
+/**
+ * An injectable web-search implementation. Receives the query + `k`, returns either a
+ * bare `WebSearchResult[]` (which is wrapped as `{ results }`) or a full
+ * {@link WebSearchOutcome} (so an impl can attach its own `note`).
+ */
+type WebSearchImpl = (query: string, k: number) => Promise<WebSearchResult[] | WebSearchOutcome> | WebSearchResult[] | WebSearchOutcome;
+/**
+ * The minimal transport the default Tavily connector posts through: a function with
+ * the WHATWG `fetch` `(url, init)` shape resolving to a `Response`-like object. The
+ * real `globalThis.fetch` satisfies it; a test injects a fake to stay offline.
+ */
+type WebSearchTransport = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<HttpFetchResponseLike> | HttpFetchResponseLike;
+/** Params for {@link components.webSearch}. */
+type WebSearchParams = {
+    /** A literal query (mutually exclusive with `queryFrom`). */
+    query?: string;
+    /** A channel whose value supplies the query (takes precedence when its channel is set). */
+    queryFrom?: string;
+    /** Channel receiving the {@link WebSearchOutcome}. */
+    into: string;
+    /** Number of results to request. Defaults to 3. */
+    k?: number;
+    /**
+     * The search implementation to call. Defaults to a real Tavily connector behind the
+     * `TAVILY_API_KEY` env var: when the key is set it POSTs to the Tavily API; when it
+     * is absent it degrades gracefully (no network, empty results + a note). Inject a
+     * fake to keep a test offline or to point at another provider.
+     */
+    searchImpl?: WebSearchImpl;
+    /**
+     * The HTTP transport the default Tavily connector posts through. Defaults to the real
+     * `globalThis.fetch`. Inject a fake to exercise the connector offline. Ignored when
+     * `searchImpl` is supplied.
+     */
+    transport?: WebSearchTransport;
+};
+/**
+ * The component factory surface. Each factory validates nothing here (the Rust
+ * `ComponentRegistry::build_handler` validates `params` at graph-build time, and the
+ * TS handlers tolerate the same shapes), returning a {@link ComponentDescriptor}
+ * carrying both the native carrier and a faithful TS handler.
+ */
+declare const components: {
+    /** Render `{{var}}` placeholders from the channels into a target channel. */
+    readonly promptBuilder: (params: PromptBuilderParams) => ComponentDescriptor;
+    /** Validate a channel value's type / required keys, writing an ok flag + errors. */
+    readonly jsonValidator: (params: JsonValidatorParams) => ComponentDescriptor;
+    /** Extract the first JSON object/array from a text channel into a target channel. */
+    readonly outputParser: (params: OutputParserParams) => ComponentDescriptor;
+    /** Pick a route string from a channel value (pairs with a conditional edge). */
+    readonly router: (params: RouterParams) => ComponentDescriptor;
+    /** Score candidate docs against a query and keep the top-`k`. */
+    readonly retriever: (params: RetrieverParams) => ComponentDescriptor;
+    /** Reorder a retrieval-result array, optionally re-scoring against a query. */
+    readonly reranker: (params: RerankerParams) => ComponentDescriptor;
+    /** Normalise a text channel: strip HTML, lowercase, collapse whitespace, trim. */
+    readonly textCleaner: (params: TextCleanerParams) => ComponentDescriptor;
+    /** Split a text channel into an array of chunk strings by chars or sentences. */
+    readonly documentSplitter: (params: DocumentSplitterParams) => ComponentDescriptor;
+    /** Strip HTML tags from a text channel and decode the common named entities. */
+    readonly htmlToText: (params: HtmlToTextParams) => ComponentDescriptor;
+    /** Parse a CSV text channel into an array of row objects (or arrays). */
+    readonly csvParser: (params: CsvParserParams) => ComponentDescriptor;
+    /** Concatenate the array values across several channels into one merged array. */
+    readonly documentJoiner: (params: DocumentJoinerParams) => ComponentDescriptor;
+    /** De-duplicate an array channel, keeping the first occurrence and order. */
+    readonly deduplicator: (params: DeduplicatorParams) => ComponentDescriptor;
+    /** Truncate a text channel to at most `maxChars` characters with an ellipsis. */
+    readonly truncator: (params: TruncatorParams) => ComponentDescriptor;
+    /** Extract literal-pattern matches (with `^`/`$` anchors) from a text channel. */
+    readonly regexExtractor: (params: RegexExtractorParams) => ComponentDescriptor;
+    /** Assemble a final answer string, optionally appending numbered citations. */
+    readonly answerBuilder: (params: AnswerBuilderParams) => ComponentDescriptor;
+    /** Remap an object channel's fields (by dotted path) into a new object. */
+    readonly fieldMapper: (params: FieldMapperParams) => ComponentDescriptor;
+    /** Extract a scalar from a channel (optional dotted path; finalOnly reduces an agent trace to its final answer). */
+    readonly fieldExtractor: (params: FieldExtractorParams) => ComponentDescriptor;
+    /** Lexical BM25 ranking of a corpus against a query; keep the top-`k`. */
+    readonly bm25Retriever: (params: Bm25RetrieverParams) => ComponentDescriptor;
+    /** Keyword-overlap ranking of a corpus against a query; keep the top-`k`. */
+    readonly keywordRetriever: (params: KeywordRetrieverParams) => ComponentDescriptor;
+    /** Split text into overlapping windows of whole sentences. */
+    readonly sentenceWindowSplitter: (params: SentenceWindowSplitterParams) => ComponentDescriptor;
+    /** Heuristic language detection over a small set of common languages. */
+    readonly languageDetector: (params: LanguageDetectorParams) => ComponentDescriptor;
+    /** Filter an array channel by a dotted-path metadata predicate. */
+    readonly metadataFilter: (params: MetadataFilterParams) => ComponentDescriptor;
+    /** Combine several array channels by concat / union / interleave. */
+    readonly listJoiner: (params: ListJoinerParams) => ComponentDescriptor;
+    /** Fuse several retrieval streams into one ranking with Reciprocal Rank Fusion. */
+    readonly mergeRanker: (params: MergeRankerParams) => ComponentDescriptor;
+    /** Score actual vs expected text (token-F1 / overlap / exact), with an optional pass flag. */
+    readonly evaluator: (params: EvaluatorParams) => ComponentDescriptor;
+    /** Assemble a role-tagged chat-message array an LLM generator consumes. */
+    readonly chatMessageBuilder: (params: ChatMessageBuilderParams) => ComponentDescriptor;
+    /** Multi-branch rule routing over the channels (pairs with a conditional edge). */
+    readonly conditionalRouter: (params: ConditionalRouterParams) => ComponentDescriptor;
+    /** Append documents into an in-state document store array (optionally de-duplicating). */
+    readonly documentWriter: (params: DocumentWriterParams) => ComponentDescriptor;
+    /**
+     * **Integration component (vendor I/O).** Perform an HTTP request, writing an
+     * {@link HttpFetchResult} (`{ status, ok, body, json }`) to `into`. This is **not**
+     * a Rust component: it returns a plain {@link NodeHandler} added with
+     * {@link import("./builder.js").GraphBuilder.node} and runs over the JS seam on the
+     * Rust engine. The default transport is the real `globalThis.fetch` (supports
+     * `method`/`headers`/`body`/`timeoutMs` via an `AbortController`); it never throws —
+     * a non-2xx is surfaced via `ok`/`status`, and an error/timeout writes
+     * `{ ok: false, error }`. Inject `fetchImpl` to override the transport (e.g. offline
+     * in tests).
+     */
+    readonly httpFetch: (params: HttpFetchParams) => IntegrationComponentHandler;
+    /**
+     * **Integration component (vendor I/O).** Run a web search, writing a
+     * {@link WebSearchOutcome} (`{ results, note? }`) to `into`. This is **not** a Rust
+     * component: it returns a plain {@link NodeHandler} added with
+     * {@link import("./builder.js").GraphBuilder.node} and runs over the JS seam on the
+     * Rust engine. The default is a real Tavily connector behind `TAVILY_API_KEY`
+     * (POSTs to `https://api.tavily.com/search`, normalizing results to
+     * `[{ title, url, snippet }]`); when the key is absent it degrades gracefully with
+     * **no** network call (empty results + a note). Inject `searchImpl` to override the
+     * provider, or `transport` to keep the Tavily connector offline.
+     */
+    readonly webSearch: (params: WebSearchParams) => IntegrationComponentHandler;
+};
+
+/** A map of channel name → value type. The generic that flows through the builder. */
+type ChannelValues = Record<string, unknown>;
+/** The starting (channel-less) state of a fresh {@link import("./builder.js").GraphBuilder}. */
+type EmptyChannels = Record<never, never>;
+/** {@link GraphState} with strongly-typed channels. */
+type TypedGraphState<TState extends ChannelValues> = Omit<GraphState, "channels"> & {
+    channels: TState;
+};
+/**
+ * What a node handler may return: a partial update to the declared channels
+ * (type-checked) plus any additional keys (the runtime passes unknown keys
+ * through), or a routing {@link Command}.
+ */
+type ChannelUpdate<TState extends ChannelValues> = (Partial<TState> & Record<string, unknown>) | Command;
+/** A node handler with strongly-typed state and return value. */
+type TypedNodeHandler<TState extends ChannelValues> = (input: unknown, state: TypedGraphState<TState>, context: NodeExecutionContext) => Promise<ChannelUpdate<TState>>;
+/** A conditional-edge predicate over strongly-typed state. */
+type TypedCondition<TState extends ChannelValues> = (state: TypedGraphState<TState>) => boolean;
+/** Initial data accepted by a run: declared channels (typed) plus arbitrary extras. */
+type InitialData<TState extends ChannelValues> = Partial<TState> & Record<string, unknown>;
+
+/** Options for {@link CompiledGraph.approveAndResume}. */
+type ApproveAndResumeOptions = {
+    /**
+     * Approval-gated tools the human has granted; they execute on resume. A bare string
+     * grants a tool by name; `{ name, key }` grants a CONTENT-SCOPED guarded fs write
+     * (ADR 0024 phase 2c) pinned to the exact call — pass the `approvalKey` surfaced on the
+     * suspended run's pending approval, so only the approved path+content unlocks.
+     */
+    approvedTools: Array<string | {
+        name: string;
+        key?: string;
+    }>;
+    /**
+     * Who approved: a person, never the agent that requested the tool. Required. It is
+     * recorded as each granted tool's `resolvedBy` and carried to the Rust engine, which
+     * rejects the resume if it equals the tool's requester (no self-approval).
+     */
+    resolvedBy: string;
+};
+/** Wiring assembled by {@link GraphBuilder.compile} and handed to a {@link CompiledGraph}. */
+type CompiledGraphParts = {
+    definition: GraphDefinition;
+    handlers: Map<string, NodeHandler>;
+    conditions: Map<string, ConditionFn>;
+    /**
+     * Per agent node, the serializable config + JS tool executes the Rust engine bridge
+     * needs (see {@link RustAgentConfig}). Empty for graphs with no agent nodes.
+     */
+    agentConfigs?: Map<string, RustAgentConfig>;
+    /**
+     * Per agent node, the principal that requests approvals and the node's gated tool names.
+     * {@link CompiledGraph.approveAndResume} uses it to stamp each granted tool's `requestedBy`
+     * for the engine's no-self-approval check. Empty for graphs with no agent nodes.
+     */
+    agentApprovals?: Map<string, AgentApprovalBinding>;
+    /**
+     * Per component node, the `{ kind, params }` carrier the Rust engine bridge needs to
+     * run the native component handler (see {@link RustComponentConfig}). Empty for
+     * graphs with no component nodes.
+     */
+    componentConfigs?: Map<string, RustComponentConfig>;
+    /**
+     * Per `mapAgents` node, the dynamic-fan-out carrier (over-channel, join channel, the sub-agent
+     * config) the Rust bridge needs (ADR 0027 phase 4b). Empty for graphs with no mapAgents nodes.
+     */
+    mapAgentConfigs?: Map<string, RustMapAgentConfig>;
+    /**
+     * Child graphs that `subgraph`-type nodes resolve into (their node handlers /
+     * conditions / agent / component configs are already merged into the maps above, by
+     * global node id). Carried to the Rust engine as `EngineSpec.subgraphs`. Empty for
+     * graphs with no subgraph nodes.
+     */
+    subgraphs?: GraphDefinition[];
+    /**
+     * Per-path filesystem permission rules (ADR 0024 phase 2b) applied run-wide to every
+     * fs-enabled agent. Carried to the Rust engine as `EngineSpec.fsPolicy`. Empty/omitted
+     * = fail-closed read-only everywhere.
+     */
+    fsPolicy?: FsPolicyRule[];
+};
+/** Options accepted by {@link CompiledGraph.run} / {@link CompiledGraph.stream}. */
+type RunOptions = {
+    /** Provide a stable run id (e.g. to correlate with an external system). */
+    runId?: RunId;
+    /**
+     * Pre-queue dynamic-message inputs (`send`) before the run: per node id, a FIFO list
+     * each consumed by that node's next execution via the reserved `__injected` channel
+     * (read it with {@link import("./send.js").readInjected}). The map-reduce seam.
+     */
+    inbox?: Record<string, unknown[]>;
+};
+/**
+ * `AILU_SDK_ENGINE`, read when a graph compiles. The Rust engine is the only engine:
+ * - `"auto"` (default) and `"rust"`: run on the Rust engine. Under `"auto"`, a graph whose
+ *   agent node sets the removed `approvalEngine` option fails to compile instead.
+ * - `"ts"`: removed; compiling fails with {@link RustEngineRequiredError}.
+ */
+type EnginePreference = "auto" | "rust" | "ts";
+/**
+ * Thrown at compile time when the graph cannot run on the **Rust engine**. The SDK is a thin
+ * surface over the native engine and has **no TypeScript fallback** — it never silently degrades.
+ */
+declare class RustEngineRequiredError extends AiluSdkError {
+    constructor(preference: EnginePreference);
+}
+/**
+ * A validated, runnable graph. Holds the engine wiring (registries, checkpointer, event bus) so
+ * callers don't touch the lower-level `@ailu-ai/graph-runtime` primitives unless they want to.
+ *
+ * Execution runs **exclusively on the Rust engine** via `@ailu-ai/napi` (a required dependency).
+ * There is **no TypeScript fallback** — {@link CompiledGraph} throws {@link RustEngineRequiredError}
+ * at compile time if the native engine cannot run the graph.
+ */
+declare class CompiledGraph<TState extends ChannelValues = ChannelValues> {
+    readonly definition: GraphDefinition;
+    private readonly checkpointer;
+    private readonly eventBus;
+    private readonly runtime;
+    /**
+     * The Rust runner. Never `null` once constructed (the constructor throws otherwise).
+     * Typed on `ChannelValues` (not `TState`) on purpose: the runner round-trips state as
+     * serialized `GraphState`/JSON, so it never needs the precise channel shape — and
+     * keeping `TState` out of every *field* keeps `CompiledGraph<TState>` variance-friendly
+     * (a `CompiledGraph<Specific>` stays assignable to `CompiledGraph<ChannelValues>`,
+     * e.g. when stored in a heterogeneous registry). The public methods re-narrow to
+     * `TState` at their boundary.
+     */
+    private readonly rustRunner;
+    /** The last suspended state seen per run id, fed back into the Rust resume/approve. */
+    private readonly suspendedStates;
+    /** Per agent node, the approval principal used by {@link approveAndResume}. */
+    private readonly agentApprovals;
+    constructor(parts: CompiledGraphParts);
+    /**
+     * Build the Rust runner, or return `null` when the graph can't run: the native addon is
+     * missing, `AILU_SDK_ENGINE=ts` is set, or (under `auto`) an agent node sets the removed
+     * `approvalEngine` option. The constructor turns `null` into {@link RustEngineRequiredError}.
+     *
+     * Agents run natively with the engine's own gateway (the `llm` option is ignored). JS node
+     * handlers and tool `execute` functions are called over the napi seam, which awaits them. A
+     * handler returning a routing `Command` (`{ goto }`) has its `goto` ignored: route with a
+     * conditional edge instead.
+     */
+    private maybeCreateRustRunner;
+    /**
+     * Adapt the (async) JS node handlers into the async producers the Rust seam needs.
+     * The Rust side awaits the returned promise, so a handler doing real async work
+     * round-trips faithfully. A handler that returns a routing {@link Command} keeps only
+     * its `update` map (see {@link toUpdateObject}): the engine routes by the graph's edges.
+     */
+    private buildNodeFns;
+    /** Async tool executes for every JS-backed tool across all agent nodes. */
+    private buildToolFns;
+    /** The named condition predicates, retyped for the Rust seam (already synchronous). */
+    private buildConditionFns;
+    /** True when this graph executes on the Rust engine. */
+    get usesRustEngine(): boolean;
+    /** Start a fresh run from the entry node and execute until completion or suspension. */
+    run(initialData?: InitialData<TState>, options?: RunOptions): Promise<TypedGraphState<TState>>;
+    /** Resume a previously suspended run from its latest checkpoint. */
+    resume(runId: RunId): Promise<TypedGraphState<TState>>;
+    /**
+     * Grant approval for the named tools and resume a run that suspended for approval
+     * (an agent node with `suspendForApproval`). The approved tools are written into
+     * `__approvedTools` by the engine before resuming, so the agent re-runs and executes
+     * the now-approved tools instead of gating them again. An agent never approves its own
+     * tools; this is the human seam.
+     */
+    approveAndResume(runId: RunId, options: ApproveAndResumeOptions): Promise<TypedGraphState<TState>>;
+    /**
+     * Deliver an external signal to a run suspended on a `waitForSignal` node, then
+     * resume it: the payload is injected into the `__signals` channel under `name` and
+     * the run advances past the waiting node. The seam a control plane uses to wake a
+     * run on an external event (a webhook, a message, an approval-out-of-band).
+     *
+     * Durable timers + external signals run natively on the **Rust engine** (the only
+     * runtime). The seam a control plane uses to wake a run on an external event.
+     */
+    signal(runId: RunId, name: string, payload?: unknown): Promise<TypedGraphState<TState>>;
+    /**
+     * Project granted tool names into the wire shape the Rust engine validates: each
+     * tool carries the principal that requested it (the owning agent node) and the
+     * distinct principal granting it. Names are sorted so the wire payload is
+     * deterministic regardless of the caller's ordering.
+     */
+    private toApprovedToolWire;
+    /** The agent node that declared `toolName` as approval-gated, as the request principal. */
+    private requesterOfTool;
+    /**
+     * Stream events as the graph executes. See {@link StreamMode} for the available
+     * shapes. The modes are projected, incrementally, over the run-event feed that crosses
+     * napi:
+     * - `updates` — a `state_update` per node completion (`delta` = the node's output).
+     * - `values` — a full `state_value` per node completion, accumulated by replaying the
+     *   node deltas through the channel reducers (the SDK mirrors the engine's reducers),
+     *   plus a final authoritative `state_value` from the resolved run.
+     * - `messages` — a `message_delta` per new entry appended to the `messages` channel,
+     *   plus (ADR 0033, when the run opts into `streamTokens`) a `message_delta` per LLM
+     *   token delta, grouped by `messageId`.
+     * - `debug` — every run-lifecycle event wrapped as a `debug` payload.
+     */
+    stream(initialData: InitialData<TState>, mode: StreamMode, options?: RunOptions): AsyncIterable<StreamEvent>;
+    /** Seed a running channel map from the graph's channel defaults + the run's input. */
+    private seedChannels;
+    /** Apply a node delta to the running channels via the declared reducers (engine parity). */
+    private applyDelta;
+    /**
+     * Drive the Rust run and project its forwarded run-event feed into {@link StreamEvent}s,
+     * incrementally for every mode. Events arrive via the runner's subscriber while the run
+     * promise is in flight; a small wake/queue interleaves them with the run's completion.
+     */
+    private streamViaRust;
+    /** A channels-only synthetic GraphState for a `values` stream step. */
+    private syntheticState;
+    /** Subscribe to the run-event lifecycle stream. Returns an unsubscribe function. */
+    onEvent(handler: (event: RunEvent) => void): () => void;
+    /**
+     * @deprecated The in-process TypeScript runtime. It does not run this graph: the Rust engine
+     * does, through `run` / `resume` / `approveAndResume` / `signal` / `stream`.
+     */
+    get engine(): GraphRuntime;
+    /**
+     * Explain where a run stands (ADR AI-DX): its status, why it suspended, what unblocks it, and
+     * what failed — a structured account a human or an AI agent reads to pick the next move. Reads
+     * the suspended state this instance retains; an unknown run id (it completed, failed, or runs on
+     * another instance) returns a `status: "unknown"` explanation. For an arbitrary run, pass its
+     * `GraphState` to {@link explainRun} directly.
+     */
+    explain(runId: RunId): RunExplanation;
+    /** Record a run's state if it suspended, so resume/approve can feed it back to Rust. */
+    private captureSuspension;
+    private requireSuspendedState;
+}
+
+/** Options passed to {@link createGraph}. */
+type CreateGraphOptions = {
+    name: string;
+    /** Defaults to a slugified `name`. */
+    id?: string;
+    /** Semver-ish version string. Defaults to `"0.0.0"`. */
+    version?: string;
+    recursionLimit?: number;
+    metadata?: Record<string, unknown>;
+};
+/** Channel shorthand: `reducer` defaults to `"replace"`. The value type is inferred from `default`. */
+type ChannelInput<TValue = unknown> = {
+    type: string;
+    reducer?: ChannelReducer;
+    default?: TValue;
+    /** ADR 0032: never emit this channel's value in run events/logs (masked; still checkpointed). */
+    noLog?: boolean;
+};
+/** Config form for non-trivial nodes. A bare handler is the common case. */
+type NodeInput<TState extends ChannelValues> = {
+    type?: NodeType;
+    handler?: TypedNodeHandler<TState>;
+    label?: string;
+    retryPolicy?: RetryPolicy;
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Fluent builder for an Ailu graph. Add channels, nodes and edges, then
+ * {@link GraphBuilder.compile} into a runnable {@link CompiledGraph}.
+ *
+ * The `TState` type parameter accumulates the declared channels as you call
+ * `.channel(...)`, so handler state and the result of `run`/`resume` are fully
+ * typed without any manual annotation.
+ *
+ * Conditions are always **named predicates** registered here — never `eval`'d
+ * strings — which is what keeps conditional routing safe and inspectable.
+ */
+declare class GraphBuilder<TState extends ChannelValues = EmptyChannels> {
+    private readonly options;
+    private readonly channels;
+    private readonly nodes;
+    private readonly edges;
+    private readonly handlers;
+    private readonly conditions;
+    /** Per agent node, the serializable config the Rust engine bridge needs. */
+    private readonly agentConfigs;
+    private readonly mapAgentConfigs;
+    /** Per agent node, the governance binding (approval engine + requester) for resume. */
+    private readonly agentApprovals;
+    /** Per component node, the `{ kind, params }` carrier the Rust engine bridge needs. */
+    private readonly componentConfigs;
+    /** Child graphs registered as `subgraph` nodes, keyed by their (global) graph id. */
+    private readonly subgraphDefs;
+    /** Per-path filesystem permission rules (ADR 0024 phase 2b), applied run-wide. */
+    private readonly fsPolicyRules;
+    private entryNodeId;
+    constructor(options: CreateGraphOptions);
+    /** Reinterpret `this` under a wider channel type after declaring a new channel. */
+    private widen;
+    /** Declare a state channel. `reducer` defaults to `"replace"`; value type inferred from `default`. */
+    channel<TName extends string, TValue = unknown>(name: TName, definition: ChannelInput<TValue>): GraphBuilder<TState & {
+        [K in TName]: TValue;
+    }>;
+    /** Declare an append-reduced `messages` channel (the conversational default). */
+    messagesChannel<TName extends string = "messages">(name?: TName): GraphBuilder<TState & {
+        [K in TName]: Message[];
+    }>;
+    /** Shared node-registration path: dedupe, register the handler, default the entry. */
+    private pushNode;
+    /** Declare a channel only if it hasn't been declared yet (for node helpers that need one). */
+    private ensureChannel;
+    /** Add a node. Pass a handler for the common action case, or a config object. */
+    node(id: string, handlerOrConfig: TypedNodeHandler<TState> | NodeInput<TState>): this;
+    /** Convenience for a `human-gate` node that suspends the run for approval. */
+    humanGate(id: string, options?: {
+        label?: string;
+    }): this;
+    /**
+     * Add an agent node: a ReAct agent driven by an LLM gateway. Its result lands in
+     * `config.outputChannel` (default `"agentResult"`), which is auto-declared and
+     * added to the typed state. Route on `result.requiresHumanReview` to gate
+     * sensitive tool use.
+     */
+    agentNode<TOut extends string = typeof DEFAULT_AGENT_OUTPUT_CHANNEL>(id: string, config: AgentNodeConfig & {
+        outputChannel?: TOut;
+    }): GraphBuilder<TState & {
+        [K in TOut]: AgentResult;
+    }>;
+    /**
+     * Add a tool node: executes the tool calls emitted by the last AI message in the
+     * `messages` channel (auto-declared as an append-reduced messages channel).
+     */
+    toolNode(id: string, config: ToolNodeConfig): GraphBuilder<TState & {
+        messages: Message[];
+    }>;
+    /**
+     * Add a **component node**: a pure (no-LLM) compute building block from
+     * {@link import("./components.js").components} (e.g. `promptBuilder`, `router`,
+     * `retriever`). The node carries the `{ kind, params }` carrier and runs natively on the
+     * Rust engine: the bridge routes a `componentNodes` entry to the native handler.
+     *
+     * ```ts
+     * createGraph({ name: "p" })
+     *   .channel("name", { type: "string", default: "" })
+     *   .channel("prompt", { type: "string", default: "" })
+     *   .component("build", components.promptBuilder({ template: "Hi {{name}}", into: "prompt" }));
+     * ```
+     */
+    component(id: string, descriptor: ComponentDescriptor, options?: {
+        label?: string;
+    }): this;
+    /**
+     * Add a **subgraph node**: nest another graph (built with its own
+     * {@link GraphBuilder}) as a single node. On entry the parent's channels are
+     * projected into the child via `inputMapping` (`childKey → parentKey`; omit to copy
+     * all parent channels); on completion the child's channels are merged back via
+     * `outputMapping` (`parentKey → childKey`; omit to spread all child channels onto
+     * the parent). If the child suspends (e.g. an internal human gate), the parent
+     * suspends at this node and a parent `resume` re-attaches to the child.
+     *
+     * The child's wiring (node handlers, conditions, agent/component configs) is merged
+     * into the parent — child runs share the parent's registries, keyed by GLOBAL node
+     * id — so child node ids must not collide with the parent's. Declare on the parent
+     * any channels the `outputMapping` writes into.
+     *
+     * ```ts
+     * const child = createGraph({ name: "double", id: "double" })
+     *   .channel("in", { type: "number", default: 0 })
+     *   .channel("out", { type: "number", default: 0 })
+     *   .node("calc", (s) => ({ out: (s.in as number) * 2 }));
+     * createGraph({ name: "parent" })
+     *   .channel("x", { type: "number", default: 21 })
+     *   .channel("y", { type: "number", default: 0 })
+     *   .subgraph("sub", child, { inputMapping: { in: "x" }, outputMapping: { y: "out" } });
+     * ```
+     */
+    subgraph<TChild extends ChannelValues>(id: string, child: GraphBuilder<TChild>, options?: {
+        inputMapping?: Record<string, string>;
+        outputMapping?: Record<string, string>;
+        label?: string;
+    }): this;
+    /**
+     * Add a **task node** (ADR 0022/0023, phase 1): spawn a sub-agent in an isolated
+     * context that returns a single compressed report. It is sugar over
+     * {@link GraphBuilder.subgraph} — the sub-agent runs as a one-node child graph, so
+     * the spawn is a real node: **checkpointed, audited, and human-gate-preserving**.
+     * If the sub-agent suspends for approval, the whole run suspends and a parent
+     * `resume`/`approveAndResume` re-attaches to it. No new runtime path is added.
+     *
+     * Isolation: only `objectiveChannel` crosses into the child (`inputMapping`), and
+     * only the child's `reportChannel` crosses back (`outputMapping`) — the sub-agent
+     * never sees the parent's other channels, and the parent never sees the child's
+     * intermediate work. With `compress` (default), the sub-agent runs
+     * `outputStyle: "terse"` so the report is a summary, not a full transcript.
+     *
+     * ```ts
+     * createGraph({ name: "research" })
+     *   .channel("objective", { type: "string", default: "" })
+     *   .taskNode("dig", { subAgent: { llm, prompt: { system: "Research deeply." } } });
+     *   // -> state.report : AgentResult
+     * ```
+     */
+    taskNode<TReport extends string = "report">(id: string, config: TaskNodeConfig & {
+        reportChannel?: TReport;
+    }): GraphBuilder<TState & {
+        [K in TReport]: AgentResult;
+    }>;
+    /**
+     * Add a **mapAgents node** (ADR 0027 phase 4b — dynamic fan-out): run `config.subAgent` once
+     * per item in the `config.overChannel` array, **concurrently**, and write the per-item results
+     * — in **input order** (deterministic, resumable) — into `config.joinAt` as an array. Each spawn
+     * gets one item as its `input` and shares the run's channels. If a spawn needs approval and
+     * `suspendForApproval` is set, the whole map suspends; resume re-runs it.
+     *
+     * ```ts
+     * createGraph({ name: "fanout" })
+     *   .channel("items", { type: "json", default: [] })
+     *   .mapAgents("research", {
+     *     overChannel: "items",
+     *     subAgent: { llm, prompt: { system: "Summarise the item." } },
+     *     joinAt: "summaries"
+     *   });
+     * ```
+     */
+    mapAgents<TJoin extends string>(id: string, config: MapAgentNodeConfig & {
+        joinAt: TJoin;
+    }): GraphBuilder<TState & {
+        [K in TJoin]: AgentResult[];
+    }>;
+    /**
+     * @internal Extract this builder's wiring so it can be nested as a subgraph by a
+     * parent {@link GraphBuilder.subgraph}. Returns live maps (the parent merges them);
+     * not part of the public authoring API.
+     */
+    toSubgraphParts(): {
+        definition: GraphDefinition;
+        handlers: Map<string, NodeHandler>;
+        conditions: Map<string, ConditionFn>;
+        agentConfigs: Map<string, RustAgentConfig>;
+        mapAgentConfigs: Map<string, RustMapAgentConfig>;
+        agentApprovals: Map<string, AgentApprovalBinding>;
+        componentConfigs: Map<string, RustComponentConfig>;
+        subgraphDefs: Map<string, GraphDefinition>;
+    };
+    /**
+     * Fan out from an existing node to a fixed set of branch nodes that run
+     * **concurrently** on the Rust engine, then join at `joinAt`. Each branch executes
+     * from the same pre-fan-out state snapshot and the branch updates are merged in the
+     * declared `parallelTo` order (deterministic, regardless of which branch finishes
+     * first — ADR 0015). The `from` node runs first (its handler/agent), then its branches
+     * scatter; control resumes at `joinAt` once every branch completes.
+     *
+     * This is the supported way to run **N parallel LLM calls** (each branch an
+     * {@link GraphBuilder.agentNode}) on the public SDK — no static edges are needed for
+     * the fan-out itself (it is its own routing). `parallelTo` is a fixed set declared at
+     * build time; dynamic per-item map over a runtime-sized list is a separate primitive.
+     *
+     * `from` must already be added; `parallelTo` and `joinAt` are validated at compile.
+     */
+    fanOut(from: string, parallelTo: string[], joinAt: string): this;
+    /** Add an unconditional edge from one node to another. */
+    edge(from: string, to: string): this;
+    /**
+     * Add a conditional edge guarded by a named predicate. The predicate is
+     * registered under `conditionName` and evaluated against the live (typed) state.
+     */
+    conditionalEdge(from: string, to: string, conditionName: string, predicate: TypedCondition<TState>): this;
+    /**
+     * ADR 0076 — governed error branch: once `from`'s `retryPolicy` is exhausted, the run reroutes
+     * to `to` instead of failing (`node_error_routed` event, `channels.__lastError` populated)
+     * rather than the run terminating (`run_failed`). At most one per node (enforced at compile via
+     * `validateGraph`). Implemented in BOTH the Rust engine (`crates/graph-core`/`graph-runtime`,
+     * the path every catalog/native run takes) and the TS legacy `@ailu-ai/graph-runtime` —
+     * this builder always compiles to Rust, so this edge type works end to end here.
+     */
+    errorEdge(from: string, to: string): this;
+    /** Override the entry node (defaults to the first node added). */
+    entry(nodeId: string): this;
+    private buildDefinition;
+    /**
+     * Declare per-path filesystem permission rules (ADR 0024 phase 2b) applied run-wide
+     * to every agent created with `enableFs: true`. Verbs: `deny|read|write|gate`;
+     * resolution is most-specific-glob-wins, fail-closed — an unmatched path resolves to
+     * `read`, so writes need an explicit `write` rule (`gate` is enforced from phase 2c).
+     * Repeated calls append. `*` matches within a path segment, `**` across segments.
+     *
+     * ```ts
+     * createGraph({ name: "deep" })
+     *   .fsPolicy([{ glob: "scratch/**", verb: "write" }, { glob: "secret/**", verb: "deny" }])
+     *   .agentNode("worker", { llm, prompt: { system: "..." }, enableFs: true });
+     * ```
+     */
+    fsPolicy(rules: FsPolicyRule[]): this;
+    /** Validate and compile, returning a {@link Result} instead of throwing. */
+    safeCompile(): Result<CompiledGraph<TState>, GraphCompileError>;
+    /** Validate and compile into a runnable graph. Throws {@link GraphCompileError} on failure. */
+    compile(): CompiledGraph<TState>;
+}
+/** Entry point: start building a graph. */
+declare const createGraph: (options: CreateGraphOptions) => GraphBuilder<EmptyChannels>;
+
+/**
+ * Durable-timer / external-signal helpers for node handlers (ADR 0009). A node handler
+ * returns one of these to make the run SUSPEND after applying its channel update:
+ * - {@link sleepUntil} — a durable timer: the run waits until an external scheduler
+ *   resumes it at `wakeAt` (the engine never sleeps — `wakeAt` is opaque data).
+ * - {@link waitForSignal} — wait for a named external signal delivered via
+ *   {@link import("./compiled-graph.js").CompiledGraph.signal}; optionally with a
+ *   timeout `wakeAt` (signal-or-timeout).
+ *
+ * Both are reserved-key markers the Rust engine recognises across the napi seam; they
+ * run on the Rust engine (the production runtime), not the TypeScript dev fallback.
+ */
+/** Reserved handler-return key requesting a durable-timer suspension. */
+declare const SLEEP_UNTIL_KEY = "__sleepUntil";
+/** Reserved handler-return key requesting a signal-wait suspension. */
+declare const WAIT_FOR_SIGNAL_KEY = "__waitForSignal";
+/** Channel key carrying the suspend reason + scheduler hints on a suspended run. */
+declare const SUSPEND_META_KEY = "__suspend";
+/** Channel key carrying delivered signal payloads, keyed by signal name. */
+declare const SIGNALS_KEY = "__signals";
+/** Why a run is suspended, with any timer / signal scheduler hints. */
+type SuspendMeta = {
+    /** `"human-gate" | "interrupt" | "timer" | "signal"`. */
+    reason: string;
+    /** For a durable timer (or signal-or-timeout): when to resume. Opaque to the engine. */
+    wakeAt?: string;
+    /** For a signal wait: the signal name a `signal(...)` must deliver. */
+    awaitingSignal?: string;
+};
+/**
+ * Node-handler return: suspend as a **durable timer** until `wakeAt`, applying `update`
+ * to the channels first. `wakeAt` is an opaque deadline (e.g. ISO-8601) — the engine
+ * stores it and never reads a clock; the control-plane scheduler resumes the run then.
+ * On resume the run advances past this node.
+ */
+declare const sleepUntil: (wakeAt: string, update?: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * Node-handler return: suspend awaiting the external signal `name`, applying `update`
+ * first. Deliver it with {@link import("./compiled-graph.js").CompiledGraph.signal};
+ * the payload lands in `__signals[name]`. Pass `wakeAt` for a signal-OR-timeout (the
+ * run also wakes at `wakeAt` if the signal never arrives).
+ */
+declare const waitForSignal: (name: string, options?: {
+    wakeAt?: string;
+    update?: Record<string, unknown>;
+}) => Record<string, unknown>;
+/**
+ * Read the suspend metadata off a (suspended) run state — the control-plane scheduler
+ * uses `wakeAt` to know when to resume a timer and `awaitingSignal` to route a signal.
+ * Returns `undefined` when the run is not suspended on a timer / signal.
+ */
+declare const readSuspendMeta: (state: Pick<GraphState, "channels">) => SuspendMeta | undefined;
+/** Read a delivered signal's payload from a run state's `__signals` channel. */
+declare const readSignal: (state: Pick<GraphState, "channels">, name: string) => unknown;
+
+/**
+ * Dynamic-message (`send`) helpers. Pre-queue inputs for a node via
+ * {@link import("./compiled-graph.js").RunOptions.inbox}; each node execution consumes
+ * the next queued input, exposed under the reserved `__injected` channel. A node handler
+ * reads it with {@link readInjected}. The map-reduce / dynamic-dispatch seam.
+ */
+/** Reserved channel exposing a `send`-injected input to a node handler (per execution). */
+declare const INJECTED_KEY = "__injected";
+/**
+ * Read the `send`-injected input from a node's state, if the node consumed a queued
+ * input this execution; `undefined` otherwise. The value is visible to the handler only
+ * and is never persisted into the run's channels.
+ */
+declare const readInjected: (state: Pick<GraphState, "channels">) => unknown;
+
+/**
+ * Canonical example graphs authored with the SDK. Shipped so the Studio can render
+ * them and the control plane can seed them — one source of truth for both. Only the
+ * `.definition` (plain data) is meant to cross boundaries.
+ */
+type ExampleGraph = {
+    slug: string;
+    name: string;
+    description: string;
+    definition: GraphDefinition;
+};
+/** Build the example graph definitions. Pure — no LLM call, no I/O. */
+declare const exampleGraphs: () => ExampleGraph[];
+
+/** One member's answer to the query. */
+type MemberAnswer = {
+    memberId: string;
+    content: string;
+};
+/** An answer stripped of its author, relabeled + shuffled so a reviewer can't favour its own. */
+type AnonymizedAnswer = {
+    label: string;
+    content: string;
+    memberId: string;
+};
+/**
+ * Strip authorship, relabel `A,B,C,…`, and shuffle deterministically by `seed` (so the same run
+ * replays identically). Reviewers see only `{ label, content }`; the `memberId` is retained so the
+ * control plane can de-anonymize the audit trail after ranking — never shown to a reviewer.
+ */
+declare const anonymizeAndShuffle: (answers: MemberAnswer[], seed: string) => AnonymizedAnswer[];
+/**
+ * Aggregate reviewer rankings into a consensus order (Borda count). Each ranking is an ordered list
+ * of labels, best-first; a label at position `p` of `n` scores `n - p`. Unranked labels score 0.
+ * Returns the labels best-first; ties break by label asc (deterministic). A ranking's duplicate or
+ * unknown labels are ignored.
+ */
+declare const aggregateRanks: (rankings: string[][], labels: string[]) => string[];
+/**
+ * Parse a reviewer's free-text reply into an ordered list of labels (the labels it names, in order,
+ * deduped) — tolerant of prose like "I rank B first, then A, then C". Only whole words exactly equal
+ * to a label count (case-sensitive, so the article "a" is not label A; "Answer" is not label A
+ * either). Unknown labels are dropped.
+ */
+declare const parseRanking: (text: string, labels: string[]) => string[];
+/** A council seat (member / reviewer / chair) — an agent-node config minus its output channel. */
+type CouncilSeat = Omit<AgentNodeConfig, "outputChannel">;
+type CouncilOptions = {
+    /** Channel holding the query text. Default `"query"`. */
+    queryChannel?: string;
+    /** The member agents (fixed N). Each answers the query independently, in parallel. */
+    members: CouncilSeat[];
+    /** Reviewers that rank the anonymized field. Default: one reviewer per member. */
+    reviewers?: CouncilSeat[];
+    /** The chair that synthesizes the final answer from the aggregated field (writes `answer`). */
+    chair: CouncilSeat;
+    /** Suspend on a human gate before the chair synthesizes (high-stakes). Default false. */
+    humanGate?: boolean;
+    /** Seed for the deterministic anonymize-shuffle (replay). Default `"council"`. */
+    seed?: string;
+};
+/**
+ * Build a governed LLM Council (ADR 0013 / ADR 0061) as a native **catalog** GraphDefinition: dispatch
+ * → members (fan-out) → `councilAnonymize` → reviewers (fan-out, rank the field) → `councilAggregate` →
+ * [optional human gate] → chair synthesis. Members/reviewers/chair are agent-carrier nodes, each
+ * shown only the channels it needs: a reviewer ranks labelled answers without seeing who wrote them
+ * (the label → member key goes to `fieldKey`, for the audit trail); anonymize/aggregate are Rust catalog components
+ * (their deterministic logic mirrors the exported pure helpers). Every node carries a `component`/
+ * `agent` carrier, so the graph runs on the Rust engine via `runCatalogGraph` — no JS handlers. Fixed N
+ * (the member list length) via the runtime fan-out. Returns the definition; run it with
+ * `runCatalogGraph(council(...))`.
+ */
+declare const council: (options: CouncilOptions) => GraphDefinition;
+
+/**
+ * The Doc-QA REFERENCE GRAPH — a complete input → output retrieval-augmented
+ * question-answering pipeline, composed entirely from the catalog (pure components +
+ * one prebuilt-style agent), authored once and runnable two ways:
+ *
+ *   1. as a {@link CompiledGraph} via {@link buildDocQaReference} — runs on the Rust engine;
+ *   2. as a plain {@link GraphDefinition} via {@link docQaReferenceDefinition} — every
+ *      node carries the shared `node.metadata.component` / `node.metadata.agent`
+ *      carrier, so the control plane can persist it, the Studio can render it, and the
+ *      catalog run path (`runCatalogGraph`) can execute it on the Rust engine.
+ *
+ * ── THE PIPELINE ──────────────────────────────────────────────────────────────
+ *   INPUT { question, documents }
+ *     → clean      (textCleaner)        normalise the raw documents text
+ *     → split      (documentSplitter)   chunk it into passages
+ *     → retrieve   (retriever)          deterministic mock-embedding top-k over the corpus
+ *     → rerank     (reranker)           reorder the hits against the question
+ *     → prompt     (promptBuilder)      build a grounded prompt from context + question
+ *     → answer     (AGENT, balanced)    a grounded RAG answerer writes its AgentResult
+ *     → extract    (fieldExtractor)     reduce AgentResult.reasoning to the final answer text
+ *     → assemble   (answerBuilder)      answer text + numbered citations → OUTPUT { answer }
+ *   OUTPUT { answer }
+ *
+ * Single input set, single output channel. Runs on Mistral's balanced-tier model
+ * (`MISTRAL_API_KEY`), or offline and deterministic with `AILU_LLM_MOCK=1`.
+ *
+ * The retriever scores against a fixed corpus baked into its params (the Rust
+ * `retriever` component's `docs` are configuration, not a channel). The `documents`
+ * INPUT channel feeds the clean → split ingestion-prep stages so the graph exercises a
+ * real document-preparation front-end; the corpus the retriever ranks is the same
+ * knowledge the documents describe, kept in params so the run is fully reproducible.
+ */
+
+/** The default knowledge corpus the retriever ranks against. */
+declare const DEFAULT_REFERENCE_CORPUS: RetrieverDoc[];
+/** Options for {@link buildDocQaReference} / {@link docQaReferenceDefinition}. */
+type DocQaReferenceOptions = {
+    /** @deprecated Ignored: the engine calls the model itself. Use `AILU_LLM_MOCK=1` to run offline. */
+    llm?: LLMGateway;
+    /** The corpus the retriever ranks against. Defaults to {@link DEFAULT_REFERENCE_CORPUS}. */
+    corpus?: RetrieverDoc[];
+    /** How many documents the retriever keeps before reranking. Defaults to 3. */
+    k?: number;
+    /** The answerer's capability tier. Defaults to `"balanced"`. */
+    tier?: ModelTier;
+    /** The answerer's provider. Defaults to `"mistral"`. */
+    provider?: "openai" | "anthropic" | "mistral";
+};
+/**
+ * Build the Doc-QA reference graph as a runnable {@link CompiledGraph}. Drive it with
+ * a single input set and read the single output channel:
+ *
+ * ```ts
+ * const app = buildDocQaReference();
+ * const out = await app.run({ question: "How does Ailu resume after a crash?", documents: "…" });
+ * console.log(out.channels.answer);
+ * ```
+ */
+declare const buildDocQaReference: (options?: DocQaReferenceOptions) => CompiledGraph;
+/**
+ * The Doc-QA reference graph as a plain {@link GraphDefinition} carrying the shared
+ * `node.metadata.component` / `node.metadata.agent` carrier on every node. This is the
+ * form the control plane persists, the Studio renders, and `runCatalogGraph` executes
+ * on the Rust engine. Pure data — no handler closures, no LLM gateway.
+ */
+declare const docQaReferenceDefinition: (options?: DocQaReferenceOptions) => GraphDefinition;
+
+/**
+ * Prebuilt, tier-tagged micro-agent graphs. Each factory returns a runnable
+ * {@link CompiledGraph} pre-wired with its capability {@link ModelTier} (matching the
+ * Rust `PrebuiltAgent` definitions in `crates/components`), so the concrete model is
+ * resolved by the {@link ModelPolicy} from the providers actually available — on Rust
+ * by the bridge, on the TS fallback path by the SDK.
+ *
+ * A prebuilt agent is a one-agent graph, except {@link prebuilt.ragAnswerer}, which
+ * composes the `retriever` + `reranker` components with an agent step.
+ *
+ * ```ts
+ * import { prebuilt } from "@ailu-ai/graph-sdk";
+ *
+ * const result = await prebuilt.summarizer().run({ question: "long text…" });
+ * console.log(result.channels.summary);
+ * ```
+ *
+ * Each agent reads its provider's API key from the environment and fails with an error
+ * naming the variable when none is set; `AILU_LLM_MOCK=1` runs it on the engine's
+ * deterministic offline mock instead. Supply `model` to pin a concrete model, or
+ * `tierOverride` to change the capability tier.
+ */
+
+/** Light options accepted by every prebuilt-agent factory. */
+type PrebuiltOptions = {
+    /**
+     * @deprecated Ignored: the Rust engine builds the gateway from the model and the
+     * environment's API keys (`AILU_LLM_MOCK=1` for the offline mock).
+     */
+    llm?: LLMGateway;
+    /** Override the capability tier the agent's model is resolved from. */
+    tierOverride?: ModelTier;
+    /**
+     * Pin a concrete model, bypassing tier resolution (the explicit-override
+     * precedence: an explicit model always wins over the tier).
+     */
+    model?: string;
+    /**
+     * The provider slot for the request (and the slot the default mock gateway
+     * registers under). Defaults to `"anthropic"`. The actual adapter is the mock
+     * unless a custom `llm` is supplied.
+     */
+    provider?: LLMProvider;
+};
+/** Options for {@link prebuilt.ragAnswerer}: the simple options plus its retrieval corpus. */
+type RagAnswererOptions = PrebuiltOptions & {
+    /** The corpus the retriever scores against. Defaults to a small built-in set. */
+    docs?: RetrieverDoc[];
+    /** How many documents the retriever keeps before reranking. Defaults to 4. */
+    k?: number;
+    /** Channel the question is read from (the retriever query). Defaults to `"question"`. */
+    questionChannel?: string;
+};
+/**
+ * The prebuilt micro-agent surface. Each factory returns a runnable
+ * {@link CompiledGraph} pre-wired with the agent's tier (matching the Rust
+ * `PrebuiltAgent` definitions).
+ */
+declare const prebuilt: {
+    /** Condense input text into a short, faithful summary (writes `summary`). */
+    readonly summarizer: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Assign the input to one label from a fixed set (writes `label`). */
+    readonly classifier: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Extract structured fields from text as JSON (writes `extracted`). */
+    readonly extractor: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Generate a SQL query from a natural-language request (writes `sql`). */
+    readonly sqlGenerator: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Answer a question grounded in retrieved documents (retriever + reranker + agent). */
+    readonly ragAnswerer: (options?: RagAnswererOptions) => CompiledGraph;
+    /** Decide on a refund, gated behind human approval before the `refund` tool runs. */
+    readonly refundApprover: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Translate input text into a target language (fast; writes `translation`). */
+    readonly translator: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Classify the emotional tone of the input (fast; writes `sentiment`). */
+    readonly sentimentAnalyzer: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Extract named entities from text as a JSON array (fast; writes `entities`). */
+    readonly entityExtractor: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Redact personally identifiable information from text (fast; writes `redacted`). */
+    readonly piiRedactor: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Map the input to a single conversational intent label (fast; writes `intent`). */
+    readonly intentClassifier: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Generate a short, descriptive title for the input (fast; writes `title`). */
+    readonly titleGenerator: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Extract the key terms from the input as a JSON array (fast; writes `keywords`). */
+    readonly keywordExtractor: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Answer a question directly and concisely (balanced; writes `answer`). */
+    readonly questionAnswerer: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Review a code snippet or diff for correctness and quality (frontier; writes `review`). */
+    readonly codeReviewer: (options?: PrebuiltOptions) => CompiledGraph;
+    /** Polish prose for clarity, grammar, flow, and tone (creative; writes `edited`). */
+    readonly copyEditor: (options?: PrebuiltOptions) => CompiledGraph;
+};
+
+/**
+ * Real text embeddings as an exported SDK helper (NOT a catalog component kind).
+ *
+ * {@link createEmbeddings} returns an {@link Embeddings} whose `embed` turns a batch of
+ * texts into dense vectors. The default transport POSTs to the provider's embeddings API
+ * (`/embeddings` with `{ model, input }` and a `Bearer` key), parsing `data[].embedding` —
+ * both Mistral and OpenAI's embeddings APIs share this exact response shape, so ONE parser
+ * and ONE transport builder serve both. The {@link CreateEmbeddingsOptions.transport} hook
+ * overrides the network call so a test can return deterministic vectors with no real
+ * network. This is the embedding backbone behind
+ * {@link import("./semantic-retriever.js").semanticRetriever}.
+ *
+ * ```ts
+ * import { createEmbeddings } from "@ailu-ai/graph-sdk";
+ *
+ * const embeddings = createEmbeddings({ apiKey: process.env.MISTRAL_API_KEY });
+ * const [a, b] = await embeddings.embed(["hello", "world"]);
+ *
+ * // A second provider (issue #541 — product-side gap: only one provider was ever wired):
+ * const openai = createEmbeddings({ provider: "openai", apiKey: process.env.OPENAI_API_KEY });
+ * ```
+ */
+/** An embedder: turn a batch of texts into one dense vector each (order-preserving). */
+type Embeddings = {
+    /** Embed `texts` into a `number[][]` of the same length and order. */
+    embed(texts: string[]): Promise<number[][]>;
+};
+/**
+ * The transport an embeddings client posts through: it receives the assembled request
+ * body and must resolve to the parsed JSON response (the `{ data: [{ embedding }] }`
+ * shape both Mistral's and OpenAI's embeddings APIs return). The real default builds this
+ * from `fetch`; a test injects a fake to stay offline.
+ */
+type EmbeddingsTransport = (body: EmbeddingsRequestBody) => Promise<unknown> | unknown;
+/** The request body POSTed to the embeddings endpoint (`{ model, input }`). `dimensions` is
+ *  OpenAI-specific (its `text-embedding-3-*` models support down-projecting via this field);
+ *  omitted from the body entirely when not set, so it's a no-op for a provider that ignores it. */
+type EmbeddingsRequestBody = {
+    model: string;
+    input: string[];
+    dimensions?: number;
+};
+/** The embeddings providers `createEmbeddings` knows how to reach directly. */
+type EmbeddingsProvider = "mistral" | "openai";
+/** Options for {@link createEmbeddings}. */
+type CreateEmbeddingsOptions = {
+    /** The embeddings provider. Defaults to `"mistral"` (unchanged from before this option existed). */
+    provider?: EmbeddingsProvider;
+    /** API key. Defaults to `process.env.MISTRAL_API_KEY`/`OPENAI_API_KEY` per `provider`. Required
+     *  unless `transport` is injected. */
+    apiKey?: string;
+    /** Embedding model. Defaults to the provider's own default (`mistral-embed` / `text-embedding-3-small`). */
+    model?: string;
+    /** API base URL. Defaults to the provider's own default. */
+    baseUrl?: string;
+    /** Down-project the output vectors to this many dimensions (OpenAI `text-embedding-3-*` only —
+     *  a provider that doesn't support it silently ignores an unset field, never sent unless set). */
+    dimensions?: number;
+    /**
+     * An injectable transport overriding the default `fetch`-based call. Receives the
+     * request body and returns the parsed JSON response. Inject a fake to keep a test
+     * offline (or to point at a stub) — when set, no API key is required.
+     */
+    transport?: EmbeddingsTransport;
+};
+/** Raised when no API key and no transport were supplied, so a real call is impossible. */
+declare class MissingEmbeddingsKeyError extends Error {
+    constructor(provider?: EmbeddingsProvider, envVar?: string);
+}
+/** Raised when the embeddings response doesn't carry the expected `data[].embedding` shape. */
+declare class EmbeddingsResponseError extends Error {
+    constructor(detail: string);
+}
+/**
+ * Create an {@link Embeddings} client for `options.provider` (defaults to `"mistral"`,
+ * unchanged from before this option existed). With the default transport it POSTs to the
+ * provider's own base URL with `{ model, input: texts, dimensions? }` and `Authorization:
+ * Bearer (apiKey || process.env[<provider's env var>])`, parsing `data[].embedding` (the
+ * same response shape for both wired providers). Inject `transport` to override that for
+ * offline tests. Throws {@link MissingEmbeddingsKeyError} when neither a key nor a
+ * transport is available.
+ */
+declare const createEmbeddings: (options?: CreateEmbeddingsOptions) => Embeddings;
+
+/**
+ * A small embedding-backed vector store as an exported SDK helper (NOT a catalog
+ * component kind). {@link createVectorStore} keeps `{ id, content, embedding, metadata? }`
+ * items and answers nearest-neighbour {@link VectorStore.query} calls by cosine
+ * similarity (descending). In-memory by default; when `persistPath` is set the store is
+ * persisted to / loaded from a round-trippable JSON file (synchronous `fs`). The exported
+ * {@link cosineSimilarity} powers the ranking and is reusable on its own.
+ *
+ * ```ts
+ * import { createVectorStore } from "@ailu-ai/graph-sdk";
+ *
+ * const store = createVectorStore();
+ * store.upsert([{ id: "a", content: "hello", embedding: [1, 0] }]);
+ * const hits = store.query([1, 0], 1); // [{ id: "a", content: "hello", score: 1 }]
+ * ```
+ */
+/** An item stored in the vector store: an id, its text, its embedding and optional metadata. */
+type VectorStoreItem = {
+    id: string;
+    content: string;
+    embedding: number[];
+    metadata?: Record<string, unknown>;
+};
+/** A single nearest-neighbour result: the item (minus its embedding) plus a cosine score. */
+type VectorStoreMatch = {
+    id: string;
+    content: string;
+    score: number;
+    metadata?: Record<string, unknown>;
+};
+/** The vector store surface returned by {@link createVectorStore}. */
+type VectorStore = {
+    /** Insert or replace items by `id` (last write wins); persists when `persistPath` is set. */
+    upsert(items: VectorStoreItem[]): void;
+    /** Return the top-`k` items by cosine similarity to `embedding`, highest score first. */
+    query(embedding: number[], k: number): VectorStoreMatch[];
+    /** The number of items currently held. */
+    size(): number;
+};
+/** Options for {@link createVectorStore}. */
+type CreateVectorStoreOptions = {
+    /**
+     * When set, the store loads its items from this JSON file on creation (if present) and
+     * rewrites it on every {@link VectorStore.upsert}. The file is a round-trippable JSON
+     * array of {@link VectorStoreItem}. Omit for a purely in-memory store.
+     */
+    persistPath?: string;
+};
+/**
+ * Cosine similarity of two vectors. Compares over the shorter length (missing
+ * components count as 0) and returns `0` when either vector has zero magnitude, so a
+ * degenerate input never produces `NaN`.
+ */
+declare const cosineSimilarity: (a: number[], b: number[]) => number;
+/**
+ * Create a {@link VectorStore}. In-memory by default; with `persistPath` it loads any
+ * existing JSON file on creation and rewrites it on every upsert (round-trippable).
+ */
+declare const createVectorStore: (options?: CreateVectorStoreOptions) => VectorStore;
+
+/**
+ * A semantic (vector-store) retrieval connector as an exported SDK helper — the "real
+ * embeddings" sibling of the deterministic mock `components.retriever`. It is NOT a new
+ * catalog component kind: {@link semanticRetriever} returns a plain {@link NodeHandler}
+ * added with {@link import("./builder.js").GraphBuilder.node} (the same vendor-I/O shape
+ * as `components.httpFetch` / `components.webSearch`), so on the Rust engine it runs over
+ * the async JS seam (`on_node`) like any other JS node.
+ *
+ * On each run it (optionally) embeds `docs` into the {@link VectorStore}, embeds the
+ * query, then writes the top-`k` `{ id, content, score }` matches to the `into` channel.
+ * `embeddings` defaults to a real Mistral client ({@link createEmbeddings}); inject a
+ * fake {@link Embeddings} to keep a test offline and deterministic.
+ *
+ * ```ts
+ * import { createGraph, semanticRetriever } from "@ailu-ai/graph-sdk";
+ *
+ * createGraph({ name: "semantic" })
+ *   .channel("q", { type: "string", default: "" })
+ *   .channel("hits", { type: "json", default: [] })
+ *   .node("retrieve", semanticRetriever({
+ *     queryFrom: "q",
+ *     into: "hits",
+ *     k: 3,
+ *     docs: [{ id: "d1", content: "Ailu is a graph runtime." }],
+ *     embeddings: fakeEmbeddings // deterministic in tests
+ *   }));
+ * ```
+ */
+
+/** A candidate document to embed into the store before querying. */
+type SemanticRetrieverDoc = {
+    id: string;
+    content: string;
+};
+/** Params for {@link semanticRetriever}. */
+type SemanticRetrieverParams = {
+    /** A literal query (mutually exclusive with `queryFrom`). */
+    query?: string;
+    /** A channel whose value supplies the query (takes precedence when its channel is set). */
+    queryFrom?: string;
+    /** Channel receiving the top-`k` `{ id, content, score }` array. */
+    into: string;
+    /** Number of results to keep. Defaults to 4. */
+    k?: number;
+    /**
+     * Documents to embed into the store before querying. Each run embeds and upserts these
+     * (idempotent by id). Omit to query against an already-populated injected `store`.
+     */
+    docs?: SemanticRetrieverDoc[];
+    /**
+     * The vector store to upsert into / query. Defaults to a fresh in-memory store created
+     * per factory call. Inject a shared/persistent store to reuse embeddings across runs.
+     */
+    store?: VectorStore;
+    /**
+     * The embeddings client. Defaults to a real Mistral client ({@link createEmbeddings}).
+     * Inject a fake (deterministic vectors) to keep a test offline.
+     */
+    embeddings?: Embeddings;
+};
+/**
+ * Build the semantic-retriever node handler. Each invocation embeds any supplied `docs`
+ * into the store, embeds the resolved query, and writes the top-`k`
+ * {@link VectorStoreMatch} array (`{ id, content, score }`) to `into`. Throws no special
+ * error class — it surfaces the underlying embeddings error if the real client can't run
+ * (no key / no transport), which is the honest failure mode for a real connector.
+ */
+declare const semanticRetriever: (params: SemanticRetrieverParams) => NodeHandler;
+
+/**
+ * The static catalog metadata that backs the API's `/catalog` endpoint: one entry per
+ * component, prebuilt agent and capability tier. This is the SDK's source of truth for
+ * the building-block library; the API validates these arrays against the
+ * `@ailu-ai/contracts` catalog DTOs and forwards them to Studio unchanged.
+ *
+ * The arrays mirror, one-for-one:
+ *  - the 30 component factories in {@link import("./components.js").components} (28 pure
+ *    Rust-backed components + 2 vendor-I/O integration components), with their real
+ *    factory params;
+ *  - the 16 prebuilt micro-agent definitions (the Rust `PrebuiltAgent` table);
+ *  - the 4 capability tiers, each carrying the {@link DEFAULT_TIER_TABLE} per-provider
+ *    recommended models.
+ *
+ * The shapes are deliberately plain data (no closures) so they map 1:1 onto the
+ * contracts DTOs and serialize over the wire as-is.
+ */
+
+/** The category buckets a component falls into in the library. */
+type ComponentCategory = "prompt" | "validation" | "parsing" | "routing" | "retrieval" | "text" | "data" | "integration" | "splitter" | "generation" | "evaluation" | "writer";
+/** A single parameter a component factory accepts. */
+type ComponentParamMeta = {
+    name: string;
+    type: string;
+    required: boolean;
+    description: string;
+};
+/** One entry in the component library: a `kind` plus its presentation + params. */
+type ComponentCatalogEntry = {
+    /** The component kind — a {@link ComponentKind} for pure components, or an integration name. */
+    kind: ComponentKind | "httpFetch" | "webSearch";
+    title: string;
+    category: ComponentCategory;
+    description: string;
+    params: ComponentParamMeta[];
+    /** `true` for the vendor-I/O integration components (httpFetch / webSearch). */
+    integration: boolean;
+};
+/** One entry in the prebuilt-agent catalog, mirroring the Rust `PrebuiltAgent` table. */
+type PrebuiltAgentCatalogEntry = {
+    name: string;
+    title: string;
+    description: string;
+    tier: ModelTier;
+    tools: string[];
+    suspendForApproval: boolean;
+    outputChannel: string;
+};
+/** Describes one capability tier plus its recommended per-provider models. */
+type ModelTierInfo = {
+    tier: ModelTier;
+    description: string;
+    /** `provider -> model` recommended defaults for this tier. */
+    models: Record<string, string>;
+};
+/**
+ * The 30 component catalog entries: 28 pure Rust-backed components (whose `kind`
+ * matches {@link ComponentKind} / `ComponentRegistry::kinds()`) plus 2 vendor-I/O
+ * integration components. Params mirror the real factory `*Params` types in
+ * `./components.ts`.
+ */
+declare const componentCatalog: readonly ComponentCatalogEntry[];
+/**
+ * The 16 prebuilt micro-agent catalog entries, mirroring the Rust `PrebuiltAgent`
+ * table (`crates/components/src/prebuilt.rs`) and the SDK `prebuilt-agents.ts` `DEFS`:
+ * name, tier, description, tools, suspend flag and output channel.
+ */
+declare const prebuiltCatalog: readonly PrebuiltAgentCatalogEntry[];
+/**
+ * The 4 capability tiers, each carrying its description and the per-provider
+ * recommended models from {@link DEFAULT_TIER_TABLE} (anthropic / mistral / ollama).
+ * Derived from the gateway table so the catalog tracks the source of truth.
+ */
+declare const tierCatalog: readonly ModelTierInfo[];
+
+/**
+ * Generate `llms.txt` (the [llmstxt.org](https://llmstxt.org) convention): a single, accurate
+ * ground-truth file an AI coding agent reads to use Ailu **without hallucinating the API**.
+ * Built from the same catalogs the engine validates against, so it cannot drift. Pure — no I/O.
+ */
+declare function generateLlmsTxt(): string;
+
+/**
+ * A minimal JSON Schema (the subset we emit). Enough for an AI agent or a validator to know a
+ * component's parameter shape before compiling a graph (ADR AI-DX). Generated from the catalog's
+ * declared param `type` strings — the single source of truth, so it can't drift from the docs.
+ */
+type JsonSchema = {
+    type?: string;
+    enum?: string[];
+    items?: JsonSchema;
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    additionalProperties?: boolean;
+};
+/** Map a catalog param `type` string (a TS-ish annotation) to a JSON Schema fragment. */
+declare function paramTypeToJsonSchema(type: string): JsonSchema;
+/** One component's identity + its parameter JSON Schema. */
+type ComponentSchema = {
+    kind: string;
+    title: string;
+    category: string;
+    description: string;
+    integration: boolean;
+    paramsSchema: JsonSchema;
+};
+/** The JSON Schema of one catalog entry's params. */
+declare function componentSchema(entry: ComponentCatalogEntry): ComponentSchema;
+/** Per-node JSON Schemas for the whole component library — what `list_catalog_with_schemas`
+ * (MCP) and the docs reference emit. Keyed by `kind`. */
+declare function componentSchemas(): Record<string, ComponentSchema>;
+
+/**
+ * `ailu dev` — the local run inspector (ADR DX batch 4). Run a graph and **watch it think** in
+ * the browser: a live node-by-node timeline, the lifecycle-event stream, each node's output, and a
+ * **governance lens** that marks exactly where the run suspended (human gate / approval) and why —
+ * with `explain()` and a one-click resume. Dependency-free (node:http only) and self-contained
+ * (the page is inline HTML/JS — no CDN, no build step), so it drops into any project.
+ *
+ * v1 streams a single run live. The replay-from-checkpoint primitive now exists —
+ * {@link replayCatalogGraph} forks a deterministic re-execution from any checkpoint (ADR 0038) and
+ * {@link verifyReplayDecisions} proves it reproduces the attested decisions. Wiring that into a
+ * one-click "rewind & replay" governance lens in this page is the remaining v2 surface.
+ */
+type InspectorHandle = {
+    /** The URL the inspector is served at. */
+    url: string;
+    /** A promise that resolves when the inspected run settles (completed / failed / suspended). */
+    done: Promise<void>;
+    /** Shut the server down. */
+    close: () => Promise<void>;
+};
+type InspectorOptions = {
+    /** Port to listen on (default 4517; 0 picks a free port). */
+    port?: number;
+    /** Host to bind (default 127.0.0.1 — local only). */
+    host?: string;
+};
+/** Serve a live inspector for a single run of `app`. Drives `app.run(initialData)`, streaming
+ * every lifecycle event to the page over SSE; surfaces `explain()` on suspend/settle. */
+declare function serveInspector<TState extends ChannelValues>(app: CompiledGraph<TState>, initialData: InitialData<TState>, options?: InspectorOptions): Promise<InspectorHandle>;
+
+/** True when graph validation is being served by the Rust core. */
+declare const rustValidatorActive: () => boolean;
+
+/** True when the native addon exposes the async run bridge (execution can use Rust). */
+declare const rustEngineAvailable: () => boolean;
+/**
+ * One granted tool on the approve path, with the governance provenance the Rust
+ * guard-rail validates (matches Rust `ApprovedTool`, camelCase): the principal who
+ * *requested* the approval and the (distinct) principal who *resolved* it. The bridge
+ * rejects the resume if `resolvedBy` is empty or equals `requestedBy` (no self-approval).
+ */
+type ApprovedToolWire = {
+    name: string;
+    requestedBy: string;
+    resolvedBy: string;
+    /**
+     * Content-scoped grant key (ADR 0024 phase 2c): `"<name>#<sha256(input)>"` for a
+     * guarded fs write, pinning the grant to the exact call. When set, the engine writes
+     * THIS key (not the bare name) into `__approvedTools`. Omitted for a name-only grant.
+     */
+    key?: string;
+};
+
+/**
+ * Observability (ADR 0028 phase 7): turn a run's lifecycle events into **OTLP spans** and ship
+ * them to any OpenTelemetry endpoint — LangSmith, Langfuse, Phoenix, Datadog, Grafana, … — plus
+ * a **cost** mapping from the token usage the engine now reports on `AgentResult.usage`.
+ *
+ * This lives in the SDK, not the engine: the engine already emits a `RunEvent` per node
+ * transition (the audit journal) and `AgentResult.usage` per agent — observability is a *read
+ * view* over that, an integration concern. The engine stays lean; nothing here can alter a run.
+ *
+ * ```ts
+ * const stop = exportTracesToOtlp(app, { endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT });
+ * await app.run({ … });
+ * stop(); // flushes + unsubscribes (also auto-flushes on run_completed / run_failed)
+ * ```
+ */
+
+/** Price of a model, in US dollars per 1,000,000 tokens. */
+type ModelPrice = {
+    inPerMtok: number;
+    outPerMtok: number;
+};
+/** A price table keyed by model id (the `AgentResult.usage` carries the model on its calls). */
+type PriceBook = Record<string, ModelPrice>;
+/** Token usage shape (matches `AgentResult.usage` / the engine's `LlmUsage`). */
+type TokenUsage = {
+    promptTokens: number;
+    completionTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+};
+/**
+ * A small default price book ($/Mtok, indicative — prices drift; supply your own to override).
+ * Keys are model ids; an unknown model costs `0` (and is reported as such, never guessed).
+ */
+declare const DEFAULT_PRICE_BOOK: PriceBook;
+/**
+ * Compute the US-dollar cost of a usage record against a price book. Cache-read tokens (when
+ * priced separately) are not modelled here — they fold into prompt tokens at the input rate, a
+ * conservative upper bound. Returns `0` for an unknown model (never a guess).
+ */
+declare function computeCost(usage: TokenUsage, model: string, book?: PriceBook): number;
+/** Minimal `fetch` shape, so the exporter is injectable for tests (no real network). */
+type OtlpFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+}>;
+type OtelExporterOptions = {
+    /** OTLP/HTTP traces endpoint. Defaults to `AILU_OTEL_EXPORTER_URL` env. */
+    endpoint?: string;
+    /** `service.name` resource attribute. Default `"ailu"`. */
+    serviceName?: string;
+    /** Extra headers (e.g. an API key for LangSmith / Langfuse). */
+    headers?: Record<string, string>;
+    /** Price book for the `ailu.cost.usd` span attribute. Default {@link DEFAULT_PRICE_BOOK}. */
+    priceBook?: PriceBook;
+    /** Injected `fetch` (tests). Defaults to the global `fetch`. */
+    fetchImpl?: OtlpFetch;
+};
+type OpenSpan = {
+    spanId: string;
+    name: string;
+    startNano: string;
+    nodeId?: string;
+};
+type FinishedSpan = OpenSpan & {
+    endNano: string;
+    status: 0 | 1 | 2;
+    attributes: Record<string, string | number | boolean>;
+};
+/**
+ * Build the OTLP/HTTP-JSON `traces` payload for one run: a root span for the run plus one span
+ * per completed/failed node, each tagged with `ailu.run_id` / `ailu.node_id`, and agent
+ * nodes additionally with token usage + computed cost.
+ */
+declare function buildOtlpPayload(runId: string, spans: FinishedSpan[], serviceName: string): string;
+/**
+ * Subscribe to `app`'s run-lifecycle events and export each run as an OTLP trace. Returns an
+ * unsubscribe fn; the run is flushed automatically on `run_completed` / `run_failed` (and on the
+ * returned fn). **Fail-open**: an export error is swallowed (best-effort observability never
+ * fails a run). A missing endpoint disables export (the returned fn is a no-op).
+ */
+declare function exportTracesToOtlp(app: CompiledGraph, options?: OtelExporterOptions): () => void;
+
+/**
+ * Run a **catalog graph** on the Rust engine.
+ *
+ * A catalog graph is a plain {@link GraphDefinition} (e.g. one authored in the Studio
+ * graph editor, persisted as data, with no in-process TS handlers) whose nodes carry
+ * the SHARED CARRIER in `node.metadata`:
+ *
+ *   - a COMPONENT node carries `node.metadata.component = { kind, params }`
+ *   - an AGENT node carries `node.metadata.agent = { provider?, model?, tier?, system?,
+ *     toolNames?, maxIterations?, suspendForApproval?, approvalToolNames?, outputChannel? }`
+ *
+ * This is the seam the control plane (`apps/api`) uses to EXECUTE a graph built from
+ * the catalog: it reads each node's metadata, assembles the engine's
+ * `EngineSpec.componentNodes` + `agents` maps + the `jsNodeIds` for plain
+ * action/tool nodes, and drives the run on the **Rust engine** via `@ailu-ai/napi`.
+ *
+ * Unlike {@link import("./builder.js").GraphBuilder}, there are no TS handler closures
+ * here — components and agents run **natively** in Rust, and plain action/tool nodes
+ * are inert JS seams (they return an empty channel update). The carrier IS the wiring.
+ *
+ * The carrier readers below mirror the canonical Zod schema in
+ * `@ailu-ai/contracts` (`node-metadata.ts`); the SDK stays dependency-free of the
+ * contracts package, so the narrowing is duplicated structurally here. The control
+ * plane is free to validate the carrier with the contracts schema before handing the
+ * definition to this runner.
+ */
+
+/** The component carrier on `node.metadata.component`. Mirrors the contracts schema. */
+type ComponentCarrier = {
+    kind: string;
+    params: Record<string, unknown>;
+};
+/** The agent carrier on `node.metadata.agent`. Mirrors the contracts schema. */
+type AgentCarrier = {
+    provider?: string;
+    model?: string;
+    tier?: ModelTier;
+    /** A custom OpenAI-compatible endpoint, and the env var naming its key (`model.openaiCompatible`). */
+    baseURL?: string;
+    apiKeyEnv?: string;
+    system?: string;
+    toolNames?: string[];
+    /** Each tool's description + input JSON Schema, as the LLM sees them. */
+    toolSpecs?: RustToolSpec[];
+    maxIterations?: number;
+    suspendForApproval?: boolean;
+    approvalToolNames?: string[];
+    outputChannel?: string;
+    /** ADR 0014 — terse output directive on the system prompt. */
+    outputStyle?: "terse";
+    /** ADR 0014 — cap (chars) on the agent's seed message (the injected `Input`/`State` dump). */
+    contextBudget?: number;
+    /** ADR 0022/0023 — durable channel the agent's `writeTodos` list is persisted into. */
+    todosChannel?: string;
+    /** ADR 0030 phase 9e — channel carrying the run's multimodal input blocks. */
+    inputBlocksChannel?: string;
+    /** The only channels the agent is shown in its seed state (context isolation). */
+    visibleChannels?: string[];
+    /** ADR 0026 phase 11 — governed long-term memory overlay. */
+    memory?: {
+        namespace: string;
+        topK?: number;
+        recall?: "vector" | "graph" | "both";
+    };
+    /** ADR 0035 phase 12 — governed skills (progressive disclosure) overlay. */
+    skills?: {
+        namespace: string;
+        required?: string[];
+        advisoryK?: number;
+    };
+    /** ADR 0024 — opt this agent into the governed virtual filesystem tools. */
+    enableFs?: boolean;
+    /**
+     * ADR 0075 (issue #566 G3) — attach an external MCP server's tools to this agent, mid-run. The
+     * control plane resolves this to a connection, discovers the server's tools, and merges them into
+     * `toolNames`/`approvalToolNames` before the run reaches this carrier — the Rust engine itself
+     * never resolves an MCP connection.
+     */
+    mcpConnectionId?: string;
+    /**
+     * Issue #566 G19 — governed action-tool connectors, keyed by provider id ("slack" first).
+     * Resolved the same way as `mcpConnectionId`; generalized to a map so future providers don't
+     * need a new engine field/release each time.
+     */
+    actionConnections?: Record<string, string>;
+    /**
+     * ADR 0025 phase 3d — the resolved efficiency middleware list. Present on graphs built by
+     * the phase-3d SDK; absent on a pre-3d persisted node (the Rust bridge then falls back to
+     * the legacy `outputStyle`/`contextBudget` knobs above, so old graphs keep their behaviour).
+     */
+    resolvedMiddleware?: EfficiencyMiddlewareSpec[];
+};
+/**
+ * The mapAgents carrier on `node.metadata.mapAgents` (ADR 0027 phase 4b — dynamic fan-out). Mirrors
+ * the contracts schema: run `subAgent` once per item in `overChannel` and collect the per-item results
+ * (input order) into `joinAt`. The sub-agent is a full agent carrier → skills/memory/fs/planning apply.
+ */
+type MapAgentCarrier = {
+    overChannel: string;
+    joinAt: string;
+    subAgent: AgentCarrier;
+    suspendForApproval?: boolean;
+};
+/** Outcome of a catalog-graph run: the terminal/suspended state and a flat status. */
+type CatalogRunOutcome = {
+    /** The final (or suspended) graph state, channels included. */
+    state: GraphState;
+    /** `"running" | "suspended" | "completed" | "failed" | "cancelled"` — the state's status.
+     *  `"cancelled"` (ADR 0044) means the run stopped at a node boundary because `options.signal`
+     *  was aborted; its last checkpoint is durable, so it stays resumable and replayable. */
+    status: string;
+    /** True when execution ran on the Rust engine (always, since this seam requires it). */
+    usedRustEngine: true;
+    /**
+     * Replay-as-evidence (ADR 0038): the recorded LLM I/O + clock journal (`{ decisions, clock }`
+     * JSON) when the run executed in record mode (`AILU_LLM_RECORD`); `undefined` otherwise. The
+     * control plane persists it to re-feed a later replay (`verify-replay`).
+     */
+    replayJournal?: string;
+    /**
+     * Replay-as-evidence (ADR 0040): the run's ENTRY state (initial state, before the entry node ran),
+     * surfaced only on a record-mode run; `undefined` otherwise. The control plane persists it as the
+     * checkpoint a later `verify-replay` seeds {@link replayCatalogGraph} from.
+     */
+    entryState?: GraphState;
+    /**
+     * The pending approvals — the subjects the run requested when it suspended on a gate (empty if it
+     * completed without gating). On a {@link replayCatalogGraph} this is what the deterministic
+     * re-execution requested: the faithfulness signal `verify-replay` compares to the attested chain.
+     */
+    pendingApprovals?: {
+        subject: string;
+        reason: string;
+        approvalKey?: string;
+        input?: unknown;
+    }[];
+};
+/** Options for {@link runCatalogGraph} / {@link resumeCatalogGraph}. */
+type RunCatalogGraphOptions = {
+    /** A stable run id. Defaults to a generated one. */
+    runId?: RunId;
+    /** Initial channel data seeding the run. */
+    initialData?: Record<string, unknown>;
+    /** Subscribe to forwarded run-lifecycle events (every node transition). */
+    onEvent?: (event: RunEvent) => void;
+    /**
+     * Cooperative cancellation (ADR 0044) — the kill switch. Abort this signal and the engine
+     * stops the run at the **next node boundary**: it finishes the node it is on, writes that
+     * node's checkpoint, emits a `run_cancelled` event and returns a terminal
+     * {@link CatalogRunOutcome} with `status: "cancelled"`.
+     *
+     * It is **cooperative, never pre-emptive**. A node already executing (an agent mid-LLM-call,
+     * a tool mid-HTTP-request) always runs to completion — so cancelling can never tear state,
+     * and the last checkpoint always remains authoritative. That also means cancellation is not
+     * instantaneous: its latency is the duration of the node in flight. A caller that needs a
+     * *bounded* stop must impose its own deadline around this call; the engine deliberately
+     * offers no hard abort, because killing a run mid-node is precisely what would break the
+     * checkpoint-per-node guarantee everything else depends on.
+     *
+     * An ALREADY-aborted signal stops the run before its first node executes. Omit for the
+     * previous behaviour (a run that can only complete, suspend or fail).
+     */
+    signal?: AbortSignal;
+    /**
+     * Opt into per-token streaming (ADR 0033 phase 13 / ADR 0060). When true, an agent node's LLM call
+     * streams real provider deltas, surfaced as `token_delta` {@link RunEvent}s over {@link onEvent} — so
+     * a catalog run (e.g. Governed Ask) can stream its answer token-by-token, not just return a final
+     * result. The assembled state is byte-identical either way (deltas bypass the checkpoint/journal —
+     * observational only). Default false (the run returns its terminal state with no token events).
+     */
+    streamTokens?: boolean;
+    /**
+     * Route the run's approvals through an {@link ApprovalEngine}. When present, the
+     * agents run natively on Rust as usual, but the moment the run suspends for approval
+     * the seam files one request per gated tool (`requestedBy = nodeId`, the agent's own
+     * subject) and stashes the engine ids in the `__approvalIds` channel of the returned
+     * state — so a human resolves them out of band (the engine forbids self-approval).
+     * Pass the same engine to {@link resumeCatalogGraph}: it refuses to resume until the
+     * engine has approved what the run waits on. Absent: the run is ungoverned.
+     */
+    approvalEngine?: ApprovalEngine;
+    /**
+     * Per-provider API keys injected by the control plane (ADR 0010), keyed by provider
+     * slug (`openai`, `anthropic`, `mistral`, …). Threaded into the Rust `EngineSpec` so
+     * the gateway resolves each agent's key tenant-key-first then host env. Omit to rely
+     * purely on the host env (local dev, tests).
+     */
+    providerKeys?: Record<string, string>;
+    /**
+     * Per-path filesystem permission rules (ADR 0024 phase 2d) the control plane resolved
+     * for this run (from its owner-only `fs_path_policy` table), compiled into the engine's
+     * `EngineSpec.fsPolicy` and applied to every fs-enabled agent. Omit for fail-closed
+     * read-only everywhere.
+     */
+    fsPolicy?: FsPolicyRule[];
+    /**
+     * The tenant's governed skills for this run (ADR 0049 B-3) — the control plane's skill store. The
+     * engine builds a run-scoped, tenant-isolated store from these and each agent's SkillMiddleware
+     * selects from it. Omit/empty → the OSS shared in-memory store (no skills).
+     */
+    skills?: SkillRecord[];
+    /**
+     * Host tools for this run (ADR 0041 D1): JS-backed `{ name, execute }` bindings made callable by
+     * ANY catalog agent whose `toolNames` includes the name — through the same napi host-tool seam the
+     * in-process builder path uses (`on_node` `kind:"tool"`). Names NOT bound here keep the no-op stub
+     * behaviour, so a graph remains pure data and existing runs are untouched. Supplied per CALL, never
+     * persisted with the graph. NOTE (ADR 0041 E2): until the replay journal records host-tool results,
+     * the caller must not combine `tools` with record-mode replay evidence — a replayed run would
+     * re-execute the tools and may diverge.
+     */
+    tools?: RustToolBinding[];
+    /**
+     * Child graph definitions for `subgraph`-type nodes (ADR 0042, product ADR 0068 — child
+     * workflows). A catalog node with `type: "subgraph"` + `subgraphId` resolves against this list,
+     * exactly like the in-process builder path (`GraphBuilder.subgraph()` → `CompiledGraph`) already
+     * does — `execute_subgraph` (the Rust engine) recursively starts/resumes the child sharing this
+     * run's checkpointer, propagates the child's suspension to the parent, and propagates a child
+     * failure as the parent's own error. Omit/empty for a graph with no subgraph nodes (today's
+     * behaviour, unchanged).
+     */
+    subgraphs?: GraphDefinition[];
+};
+/** Raised when the native engine is unavailable — catalog graphs require it. */
+declare class RustEngineUnavailableError extends Error {
+    constructor();
+}
+/** Narrow a node's open metadata bag to its COMPONENT carrier, if present and valid. */
+declare const readComponentCarrier: (metadata: Record<string, unknown> | undefined) => ComponentCarrier | undefined;
+/** Narrow a node's open metadata bag to its AGENT carrier, if present and valid. */
+declare const readAgentCarrier: (metadata: Record<string, unknown> | undefined) => AgentCarrier | undefined;
+/** Narrow a node's open metadata bag to its mapAgents (dynamic fan-out) carrier, if present + valid. */
+declare const readMapAgentCarrier: (metadata: Record<string, unknown> | undefined) => MapAgentCarrier | undefined;
+/**
+ * Run a catalog {@link GraphDefinition} (whose nodes carry `node.metadata.component`
+ * and `node.metadata.agent`) to completion or suspension on the **Rust engine**.
+ *
+ * Throws {@link RustEngineUnavailableError} when the native addon is absent.
+ */
+declare const runCatalogGraph: (definition: GraphDefinition, options?: RunCatalogGraphOptions) => Promise<CatalogRunOutcome>;
+/**
+ * Resume a previously-suspended catalog run (e.g. past a human gate) from its
+ * serialized {@link GraphState}, on the **Rust engine**. The bridge seeds its
+ * checkpointer with this state and resumes from it.
+ *
+ * With an `approvalEngine`, the resume first checks the engine: every request the run
+ * waits on must be decided, no human gate may be rejected, and every granted tool must
+ * match an approved request. Otherwise it throws {@link ApprovalNotGrantedError} and
+ * nothing runs.
+ *
+ * Throws {@link RustEngineUnavailableError} when the native addon is absent.
+ */
+declare const resumeCatalogGraph: (definition: GraphDefinition, state: GraphState, options?: Pick<RunCatalogGraphOptions, "onEvent" | "approvalEngine" | "providerKeys" | "fsPolicy" | "skills" | "tools" | "subgraphs" | "signal"> & {
+    /**
+     * Human-granted tools to unlock on resume, each carrying its `{ name, requestedBy,
+     * resolvedBy }` provenance. Passed straight through to the Rust bridge, which
+     * re-validates the no-self-approval invariant per tool on `Entry::Resume` and writes
+     * only the validated names into `__approvedTools`. With an `approvalEngine`, each
+     * grant must also match a request the engine records as approved by `resolvedBy`.
+     * Omitted/empty: an ordinary resume that unlocks no tools.
+     */
+    approvedTools?: ApprovedToolWire[];
+}) => Promise<CatalogRunOutcome>;
+/**
+ * Replay-as-evidence (ADR 0038): re-execute a recorded catalog run from `checkpointId`, re-feeding
+ * its `replayJournal` (LLM outputs + timestamps from a record-mode {@link runCatalogGraph}) on the
+ * Rust engine so the re-derivation is deterministic. A forked, READ-ONLY run — it never files
+ * approval requests or opens gates. Returns the replayed state; the caller compares its governed
+ * decisions to the attested chain via {@link verifyReplayDecisions}. Requires a native addon with
+ * replay support (`engineReplay`); throws otherwise.
+ */
+declare const replayCatalogGraph: (definition: GraphDefinition, state: GraphState, checkpointId: string, replayJournal: string, options?: Pick<RunCatalogGraphOptions, "onEvent" | "providerKeys" | "fsPolicy" | "skills" | "subgraphs">) => Promise<CatalogRunOutcome>;
+/**
+ * Subject prefix for a `human-gate` node's own {@link ApprovalEngine} request (issue
+ * #496), distinct from {@link TOOL_SUBJECT_PREFIX}-style tool subjects an agent files —
+ * the control plane uses this to tell a rejected GATE apart from a rejected TOOL when
+ * deciding whether a run becomes `"rejected"` (a tool rejection just leaves a tool
+ * unlocked; a gate rejection must block `resume()` outright).
+ */
+declare const GATE_SUBJECT_PREFIX = "gate:";
+/** Type guard a node carries either catalog carrier. Useful to decide the run path. */
+declare const isCatalogGraph: (definition: GraphDefinition) => boolean;
+
+/** One governance decision, reduced to what a replay can faithfully reproduce. */
+type ReplayDecision = {
+    /** `"approved" | "rejected"`. */
+    status: string;
+    /** The decision subject, derived identically to the attestation (`description || canonicalJson`). */
+    subject: string;
+};
+/** The result of comparing the attested decisions to the replayed ones, in order. */
+type VerifyReplayResult = {
+    /** True iff every attested decision is reproduced, in the same order, by the replay. */
+    ok: boolean;
+    attested: ReplayDecision[];
+    replayed: ReplayDecision[];
+    /** Per-position divergences (missing on either side, or a status/subject differs). */
+    mismatches: {
+        index: number;
+        attested?: ReplayDecision;
+        replayed?: ReplayDecision;
+    }[];
+};
+/**
+ * Compare the ordered `{ status, subject }` decision sets of the attested chain and a replayed run.
+ * Order matters (a dropped, reordered, or status-flipped decision is a mismatch). Pure + crypto-free.
+ */
+declare const verifyReplayDecisions: (attested: ReplayDecision[], replayed: ReplayDecision[]) => VerifyReplayResult;
+
+/**
+ * The final answer of an agent run: the text after the last `final:` marker in its `reasoning`
+ * (the whole `reasoning` when there is no marker). An empty string for a missing result.
+ *
+ * ```ts
+ * const out = await app.run({ question: "What is a checkpoint?" });
+ * console.log(finalAnswer(out.channels.agentResult));
+ * ```
+ *
+ * For a typed answer, run the agent with a `structuredOutput` middleware and read
+ * `result.structuredOutput` instead.
+ */
+declare const finalAnswer: (result: Pick<AgentResult, "reasoning"> | undefined) => string;
+
+type Loc$1 = {
+    line: number;
+    col: number;
+    file: string;
+};
+
+type Diagnostic$1 = {
+    code: string;
+    message: string;
+    loc: Loc$1;
+    severity: "error" | "warning";
+};
+
+declare const compileGraphFile: (content: string, file: string) => {
+    result?: GraphDefinition;
+    diagnostics: Diagnostic$1[];
+};
+
+type Loc = {
+    line: number;
+    col: number;
+    file: string;
+};
+
+type Diagnostic = {
+    code: string;
+    message: string;
+    loc: Loc;
+    severity: "error" | "warning";
+};
+
+type PromptTemplate = {
+    name: string;
+    template: string;
+    diagnostics: Diagnostic[];
+    render: (variables: Record<string, unknown>) => {
+        content: string;
+        diagnostics: Diagnostic[];
+    };
+};
+type AgentConfig = {
+    id: string;
+    description: string;
+    prompt: string;
+    tools: string[];
+};
+type ChainDefinition = {
+    id: string;
+    steps: Array<{
+        agentId: string;
+        input?: Record<string, unknown>;
+    }>;
+};
+
+type CompileResult = PromptTemplate | AgentConfig | ChainDefinition;
+declare const compileFile: (content: string, file: string) => {
+    result?: CompileResult;
+    diagnostics: Diagnostic[];
+};
+
+/**
+ * Resource-search seam types (ADR 0011). A `SearchDocument` is what a producer (graphs, KB,
+ * agent-types) pushes into the index; a `SearchHit` is what a query returns. These are the
+ * wire-neutral shapes the engine owns — the control plane maps them to/from contracts DTOs.
+ */
+/** The kinds of resource the unified search indexes. */
+type SearchResourceType = "graph" | "agent" | "kb";
+/** One indexable resource. `tenantId === null` marks a global resource (catalog graph, agent
+ * type) visible to every tenant. `namespace` is carried for KB docs (used in the href / display). */
+interface SearchDocument {
+    type: SearchResourceType;
+    /** Unique within its `type` (e.g. a graph id, a `namespace:path` for KB). */
+    id: string;
+    tenantId: string | null;
+    namespace?: string;
+    /** Short, high-weight label shown as the result title. */
+    title: string;
+    /** Full searchable body (description, content, labels…). */
+    text: string;
+    /** Studio route to open the resource. */
+    href: string;
+    /** ISO-8601 last-updated, for tie-breaking / display. */
+    updatedAt?: string;
+}
+/** One ranked result. */
+interface SearchHit {
+    type: SearchResourceType;
+    id: string;
+    tenantId: string | null;
+    namespace?: string;
+    title: string;
+    /** A short excerpt around the match (or the title when the body did not match). */
+    snippet: string;
+    href: string;
+    /** Higher is more relevant. Backend-specific scale; only the ordering is meaningful. */
+    score: number;
+}
+/** Query scoping. `tenantId` is mandatory — a search is always tenant-scoped (global docs are
+ * additionally included). `types` restricts to a subset; omitted means all. */
+interface SearchQueryOptions {
+    tenantId: string;
+    types?: SearchResourceType[];
+    limit?: number;
+}
+/**
+ * Pluggable search backend. The engine ships {@link InMemorySearchProvider}; the control plane
+ * provides an Elasticsearch implementation behind the same interface (ADR 0011).
+ */
+interface SearchProvider {
+    /** Idempotent one-time setup (create the ES index/mapping). No-op for in-memory. */
+    ensureReady(): Promise<void>;
+    /** Upsert documents (keyed by `type` + `id`). */
+    index(documents: SearchDocument[]): Promise<void>;
+    /** Remove one document by `type` + `id`. Missing ids are ignored. */
+    remove(type: SearchResourceType, id: string): Promise<void>;
+    /** Tenant-scoped ranked search. Returns at most `opts.limit` hits (default 10). */
+    search(query: string, opts: SearchQueryOptions): Promise<SearchHit[]>;
+}
+/** Default result cap when a query omits `limit`. */
+declare const DEFAULT_SEARCH_LIMIT = 10;
+
+/**
+ * Dependency-free {@link SearchProvider}: token-overlap scoring over an in-memory map, with
+ * tenant + type filtering and snippeting. The OSS default and the dev/test/no-Elasticsearch
+ * backend (ADR 0011). Title matches weigh more than body matches.
+ */
+declare class InMemorySearchProvider implements SearchProvider {
+    private readonly docs;
+    ensureReady(): Promise<void>;
+    index(documents: SearchDocument[]): Promise<void>;
+    remove(type: SearchResourceType, id: string): Promise<void>;
+    search(query: string, opts: SearchQueryOptions): Promise<SearchHit[]>;
+}
+
+export { AGENT_APPROVAL_INTERRUPT, type AIMessage, APPROVAL_IDS_CHANNEL, APPROVED_TOOLS_CHANNEL, type AgentApprovalBinding, type AgentCarrier, type AgentId, type AgentNodeConfig, type AgentProfile, type AgentPromptSource, type AgentResult, AiluSdkError, type AnonymizedAnswer, type AnswerBuilderParams, AnthropicProviderAdapter, ApprovalAlreadyResolvedError, type ApprovalEngine, type ApprovalId, ApprovalNotFoundError, ApprovalNotGrantedError, type ApprovalRequest, ApprovalSelfApprovalError, type ApproveAndResumeOptions, type ApprovedToolWire, ApproverRequiredError, type Artifact, type ArtifactId, type ArtifactStore, type ArtifactVersion, type AttestationRecord, type BaseStore, type Bm25RetrieverParams, type CatalogRunOutcome, type ChannelInput, type ChannelReducer, type ChannelUpdate, type ChannelValues, type ChatMessageBuilderParams, type ChatMessageSpec, type Checkpoint, type CheckpointId, type Checkpointer, type Command, CompiledGraph, type CompiledGraphParts, type ComponentCarrier, type ComponentCatalogEntry, type ComponentCategory, type ComponentDescriptor, type ComponentKind, type ComponentParamMeta, type ComponentSchema, type ConditionFn, type ConditionalRouterBranch, type ConditionalRouterParams, type CouncilOptions, type CouncilSeat, type CreateEmbeddingsOptions, type CreateGraphOptions, type CreateVectorStoreOptions, type CsvParserParams, DEFAULT_AGENT_OUTPUT_CHANNEL, DEFAULT_PREFERENCE, DEFAULT_PRICE_BOOK, DEFAULT_REFERENCE_CORPUS, DEFAULT_SEARCH_LIMIT, DEFAULT_TIER_TABLE, type DeduplicatorParams, DefaultLLMGateway, type DocQaReferenceOptions, type DocumentJoinerParams, type DocumentSplitterParams, type DocumentWriterParams, DuplicateNodeError, DynamicInterrupt, Ed25519Attestor, type EdgeDefinition, type EdgeId, type EfficiencyMiddlewareSpec, type Embeddings, type EmbeddingsProvider, type EmbeddingsRequestBody, EmbeddingsResponseError, type EmbeddingsTransport, type EmptyChannels, type EvaluatorParams, type ExampleGraph, type FieldMapperParams, type FsPermVerb, type FsPolicyRule, GATE_SUBJECT_PREFIX, GOVERNANCE_MIDDLEWARE_KINDS, GovernanceMiddlewareRejectedError, GraphBuilder, GraphCompileError, type GraphDefinition, type GraphId, GraphRuntime, type GraphState, GraphStateSchema, type GraphStatus, GraphValidationError, type HtmlToTextParams, type HttpFetchImpl, type HttpFetchParams, type HttpFetchRequestInit, type HttpFetchResponseLike, type HttpFetchResult, INJECTED_KEY, InMemoryApprovalEngine, InMemoryArtifactStore, InMemoryCheckpointer, InMemoryConditionRegistry, InMemoryEventBus, InMemoryNodeRegistry, InMemoryPromptRegistry, InMemorySearchProvider, InMemoryToolRegistry, type InitialData, type InspectorHandle, type InspectorOptions, type IntegrationComponentHandler, type InterruptConfig, type JsonSchema, type JsonValidatorParams, type KeywordRetrieverParams, type LLMGateway, type LLMModel, type LLMProvider, type LLMProviderAdapter, type LLMRequest, type LLMResponse, type LLMStreamChunk, type LLMToolCall, type LanguageDetectorParams, type LexicalDoc, type ListJoinerParams, MODEL_TIERS, type MapAgentCarrier, type MapAgentNodeConfig, type MemberAnswer, type MemoryItem, type MemoryKey, type MemoryNamespace, type MergeRankerParams, type Message, type MessageId, type MetadataFilterParams, MissingEmbeddingsKeyError, MissingHandlerError, MockLLMProviderAdapter, type ModelChoice, ModelPolicy, type ModelPrice, type ModelTier, type ModelTierInfo, type NodeDefinition, type NodeHandler, type NodeId, type NodeInput, type NodeType, type OpenAIChatRequestBody, type OpenAIChatResponse, type OpenAICompatibleAdapterOptions, OpenAICompatibleProviderAdapter, type OpenAICompatibleTransportPort, type OtelExporterOptions, type OtlpFetch, type OutputParserParams, type PrebuiltAgentCatalogEntry, type PrebuiltOptions, type PredicateOp, type PriceBook, type PromptBuilderParams, type PromptRegistry, type RagAnswererOptions, ReActAgent, type RegexExtractorParams, type ReplayDecision, type RequestApprovalParams, type RerankerParams, type ResolveOverride, type Result, ResumeStateNotFoundError, type RetrieverDoc, type RetrieverParams, type RouterParams, type RouterRule, type RunCatalogGraphOptions, type RunEvent, type RunExplanation, type RunId, type RunOptions, type RustAgentConfig, type RustComponentConfig, RustEngineRequiredError, RustEngineUnavailableError, type RustMapAgentConfig, type RustToolBinding, type RustToolSpec, SIGNALS_KEY, SLEEP_UNTIL_KEY, SUSPEND_META_KEY, type SearchDocument, type SearchHit, type SearchProvider, type SearchQueryOptions, type SearchResourceType, type SemanticRetrieverDoc, type SemanticRetrieverParams, type SentenceWindowSplitterParams, type SkillConfig, type SkillRecord, type StreamAgentConfig, type StreamEvent, type StreamMode, type SuspendMeta, TODOS_CHANNEL, type TaskNodeConfig, type TextCleanerParams, type TierModelTable, type TodoItem, type TodoStatus, type TokenUsage, type ToolCall, type ToolDefinition, type ToolId, type ToolNodeConfig, type ToolRegistry, type TruncatorParams, type TypedCondition, type TypedGraphState, type TypedNodeHandler, UnknownNodeError, type VectorStore, type VectorStoreItem, type VectorStoreMatch, type VerifyReplayResult, WAIT_FOR_SIGNAL_KEY, WRITE_TODOS_TOOL_NAME, type WebSearchImpl, type WebSearchOutcome, type WebSearchParams, type WebSearchResult, type WebSearchTransport, type WriteTodosInput, aggregateRanks, anonymizeAndShuffle, buildDocQaReference, buildOtlpPayload, canonicalJson, compileFile, compileGraphFile, componentCatalog, componentSchema, componentSchemas, components, computeCost, cosineSimilarity, council, createAgentNodeHandler, createEmbeddings, createGraph, createToolNodeHandler, createVectorStore, docQaReferenceDefinition, exampleGraphs, explainRun, exportTracesToOtlp, finalAnswer, generateLlmsTxt, isCatalogGraph, normalizeTodos, paramTypeToJsonSchema, parseRanking, prebuilt, prebuiltCatalog, readAgentCarrier, readComponentCarrier, readInjected, readMapAgentCarrier, readSignal, readSuspendMeta, replayCatalogGraph, resumeCatalogGraph, runCatalogGraph, rustEngineAvailable, rustValidatorActive, semanticRetriever, serveInspector, sleepUntil, streamAgentTokens, tierCatalog, toAgentApprovalBinding, toRustAgentConfig, validateGraph, verifyAttestation, verifyChain, verifyReplayDecisions, waitForSignal, writeTodosJsonSchema, writeTodosTool };