@axlsdk/axl 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1576 @@
+import { z, ZodError } from 'zod';
+import { EventEmitter } from 'node:events';
+import { Readable } from 'node:stream';
+
+/** Result type for concurrent operations (spawn, map) */
+type Result<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+/** Budget execution result */
+type BudgetResult<T> = {
+    value: T | null;
+    budgetExceeded: boolean;
+    totalCost: number;
+};
+/** Human decision from awaitHuman */
+type HumanDecision = {
+    approved: true;
+    data?: string;
+} | {
+    approved: false;
+    reason?: string;
+};
+/** Budget options */
+type BudgetOptions = {
+    cost: string;
+    onExceed?: 'finish_and_stop' | 'hard_stop' | 'warn';
+};
+/** Map options */
+type MapOptions = {
+    concurrency?: number;
+    quorum?: number;
+};
+/** Spawn options */
+type SpawnOptions = {
+    quorum?: number;
+};
+/** Vote strategies */
+type VoteStrategy = 'majority' | 'unanimous' | 'highest' | 'lowest' | 'mean' | 'median' | 'custom';
+/** Vote options */
+type VoteOptions<T> = {
+    strategy: VoteStrategy;
+    key?: string;
+    scorer?: (value: T) => number | Promise<number>;
+    reducer?: (values: T[]) => T | Promise<T>;
+};
+/** Verify options */
+type VerifyOptions<T> = {
+    retries?: number;
+    fallback?: T;
+};
+/** AwaitHuman options */
+type AwaitHumanOptions = {
+    channel: string;
+    prompt: string;
+    metadata?: Record<string, unknown>;
+};
+/** Ask options */
+type AskOptions<T = unknown> = {
+    schema?: z.ZodType<T>;
+    retries?: number;
+    /** Per-call metadata passed to dynamic model/system selector functions. */
+    metadata?: Record<string, unknown>;
+};
+/** Race options */
+type RaceOptions<T = unknown> = {
+    /** Schema to validate each result. Invalid results are discarded and the race continues. */
+    schema?: z.ZodType<T>;
+};
+/** Execution status */
+type ExecutionStatus = 'running' | 'completed' | 'failed' | 'waiting';
+/** Trace event */
+type TraceEvent = {
+    executionId: string;
+    step: number;
+    type: 'agent_call' | 'tool_call' | 'verify' | 'handoff' | 'tool_denied' | 'log' | 'workflow_start' | 'workflow_end' | 'guardrail';
+    workflow?: string;
+    agent?: string;
+    tool?: string;
+    promptVersion?: string;
+    model?: string;
+    cost?: number;
+    duration?: number;
+    data?: unknown;
+    timestamp: number;
+};
+/** Result of a guardrail check. */
+type GuardrailResult = {
+    block: boolean;
+    reason?: string;
+};
+/** Input guardrail function. Runs before the LLM call. */
+type InputGuardrail = (prompt: string, ctx: {
+    metadata: Record<string, unknown>;
+}) => GuardrailResult | Promise<GuardrailResult>;
+/** Output guardrail function. Runs after the LLM response. */
+type OutputGuardrail = (response: string, ctx: {
+    metadata: Record<string, unknown>;
+}) => GuardrailResult | Promise<GuardrailResult>;
+/** Handler for when a guardrail blocks. */
+type GuardrailBlockHandler = 'retry' | 'throw' | ((reason: string, ctx: {
+    metadata: Record<string, unknown>;
+}) => string | Promise<string>);
+/** Full guardrails configuration for an agent. */
+type GuardrailsConfig = {
+    input?: InputGuardrail;
+    output?: OutputGuardrail;
+    onBlock?: GuardrailBlockHandler;
+    maxRetries?: number;
+};
+/** Execution info */
+type ExecutionInfo = {
+    executionId: string;
+    workflow: string;
+    status: ExecutionStatus;
+    steps: TraceEvent[];
+    totalCost: number;
+    startedAt: number;
+    completedAt?: number;
+    duration: number;
+    error?: string;
+};
+type StreamEvent = {
+    type: 'token';
+    data: string;
+} | {
+    type: 'tool_call';
+    name: string;
+    args: unknown;
+} | {
+    type: 'tool_result';
+    name: string;
+    result: unknown;
+} | {
+    type: 'tool_approval';
+    name: string;
+    args: unknown;
+    approved: boolean;
+    reason?: string;
+} | {
+    type: 'agent_start';
+    agent: string;
+    model?: string;
+} | {
+    type: 'agent_end';
+    agent: string;
+    cost?: number;
+    duration?: number;
+} | {
+    type: 'handoff';
+    source: string;
+    target: string;
+    mode?: 'oneway' | 'roundtrip';
+} | {
+    type: 'step';
+    step: number;
+    data: unknown;
+} | {
+    type: 'done';
+    data: unknown;
+} | {
+    type: 'error';
+    error: Error;
+};
+/** Record of an agent handoff event (persisted in session metadata). */
+type HandoffRecord = {
+    source: string;
+    target: string;
+    mode: 'oneway' | 'roundtrip';
+    timestamp: number;
+    duration?: number;
+};
+/** Chat message types for provider communication */
+type ChatRole = 'system' | 'user' | 'assistant' | 'tool';
+type ChatMessage = {
+    role: ChatRole;
+    content: string;
+    name?: string;
+    tool_calls?: ToolCallMessage[];
+    tool_call_id?: string;
+};
+type ToolCallMessage = {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+};
+/** Provider response */
+type ProviderResponse = {
+    content: string;
+    tool_calls?: ToolCallMessage[];
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+        reasoning_tokens?: number;
+        cached_tokens?: number;
+    };
+    cost?: number;
+};
+
+/** Descriptor for a handoff target agent with optional description. */
+type HandoffDescriptor = {
+    agent: Agent;
+    description?: string;
+    /** Handoff mode: 'oneway' (default) exits source loop, 'roundtrip' returns result to source. */
+    mode?: 'oneway' | 'roundtrip';
+};
+/** Agent configuration */
+type AgentConfig = {
+    name?: string;
+    model: string | ((ctx: {
+        metadata?: Record<string, unknown>;
+    }) => string);
+    system: string | ((ctx: {
+        metadata?: Record<string, unknown>;
+    }) => string);
+    tools?: Tool[];
+    handoffs?: HandoffDescriptor[];
+    mcp?: string[];
+    mcpTools?: string[];
+    temperature?: number;
+    maxTurns?: number;
+    timeout?: string;
+    maxContext?: number;
+    version?: string;
+    guardrails?: GuardrailsConfig;
+};
+/** A defined agent instance */
+type Agent = {
+    readonly _config: AgentConfig;
+    readonly _name: string;
+    /** Direct invocation for prototyping (no workflow context) */
+    ask<T = string>(prompt: string, options?: AskOptions<T>): Promise<T>;
+    /** Resolve model string for given context */
+    resolveModel(ctx?: {
+        metadata?: Record<string, unknown>;
+    }): string;
+    /** Resolve system prompt for given context */
+    resolveSystem(ctx?: {
+        metadata?: Record<string, unknown>;
+    }): string;
+};
+/**
+ * Define an agent with a model, system prompt, tools, and optional handoffs.
+ * Agents are inert definitions until invoked via `ctx.ask()` or `agent.ask()`.
+ * @param config - Agent configuration: model URI, system prompt (static or dynamic), tools, temperature, etc.
+ * @returns An Agent instance that can be used with `ctx.ask()` inside workflows or called directly for prototyping.
+ */
+declare function agent(config: AgentConfig): Agent;
+
+/**
+ * Tool definition in OpenAI-compatible format.
+ * All providers normalize to this format internally.
+ */
+type ToolDefinition = {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: unknown;
+        strict?: boolean;
+    };
+};
+/**
+ * Options passed to provider chat/stream calls.
+ */
+type ChatOptions = {
+    model: string;
+    temperature?: number;
+    tools?: ToolDefinition[];
+    maxTokens?: number;
+    responseFormat?: ResponseFormat;
+    stop?: string[];
+    signal?: AbortSignal;
+    reasoningEffort?: 'low' | 'medium' | 'high';
+    toolChoice?: 'auto' | 'none' | 'required' | {
+        type: 'function';
+        function: {
+            name: string;
+        };
+    };
+};
+/**
+ * Response format for structured output (JSON mode).
+ */
+type ResponseFormat = {
+    type: 'text';
+} | {
+    type: 'json_object';
+} | {
+    type: 'json_schema';
+    json_schema: {
+        name: string;
+        strict?: boolean;
+        schema: unknown;
+    };
+};
+/**
+ * Chunks emitted during streaming.
+ */
+type StreamChunk = {
+    type: 'text_delta';
+    content: string;
+} | {
+    type: 'tool_call_delta';
+    id: string;
+    name?: string;
+    arguments?: string;
+} | {
+    type: 'done';
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+        reasoning_tokens?: number;
+        cached_tokens?: number;
+    };
+};
+/**
+ * Core provider interface. Every LLM adapter must implement this.
+ */
+interface Provider {
+    /** Human-readable name for the provider (e.g. "openai", "anthropic") */
+    readonly name?: string;
+    /**
+     * Send a chat completion request and return the full response.
+     */
+    chat(messages: ChatMessage[], options: ChatOptions): Promise<ProviderResponse>;
+    /**
+     * Stream a chat completion, yielding chunks as they arrive.
+     */
+    stream(messages: ChatMessage[], options: ChatOptions): AsyncGenerator<StreamChunk>;
+}
+/**
+ * Alias for Provider. Used for backward compatibility with index.ts exports.
+ */
+type ProviderAdapter = Provider;
+
+/** Configuration for OpenTelemetry integration. */
+type TelemetryConfig = {
+    /** Whether telemetry is enabled. Defaults to false. */
+    enabled?: boolean;
+    /** Custom TracerProvider. If not provided, uses the global OTel provider. */
+    tracerProvider?: unknown;
+    /** Tracer name. Defaults to 'axl'. */
+    serviceName?: string;
+};
+/** A handle to an active span for adding events and attributes. */
+interface SpanHandle {
+    setAttribute(key: string, value: string | number | boolean): void;
+    addEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
+    setStatus(code: 'ok' | 'error', message?: string): void;
+    end(): void;
+}
+/** Manages span creation and context propagation. */
+interface SpanManager {
+    /** Wrap an async function in a span. Child spans created inside auto-nest. */
+    withSpanAsync<T>(name: string, attributes: Record<string, string | number | boolean>, fn: (span: SpanHandle) => Promise<T>): Promise<T>;
+    /** Add an event to the currently active span (if any). */
+    addEventToActiveSpan(name: string, attributes?: Record<string, string | number | boolean>): void;
+    /** Gracefully shut down (flush pending spans). */
+    shutdown(): Promise<void>;
+}
+
+/** A single vector entry in the store. */
+type VectorEntry = {
+    id: string;
+    content: string;
+    embedding: number[];
+    metadata?: Record<string, unknown>;
+};
+/** A result from a vector similarity search. */
+type VectorResult = {
+    id: string;
+    content: string;
+    score: number;
+    metadata?: Record<string, unknown>;
+};
+/** Options for ctx.remember(). */
+type RememberOptions = {
+    /** 'session' (default) scopes to current session, 'global' scopes to all sessions. */
+    scope?: 'session' | 'global';
+    /** Arbitrary metadata stored alongside the value. */
+    metadata?: Record<string, unknown>;
+    /** When true and a vector store is configured, also embed for semantic search. */
+    embed?: boolean;
+};
+/** Options for ctx.recall(). */
+type RecallOptions = {
+    /** 'session' (default) scopes to current session, 'global' scopes to all sessions. */
+    scope?: 'session' | 'global';
+    /** When provided, performs semantic similarity search instead of exact key lookup. */
+    query?: string;
+    /** Number of results for semantic search. Defaults to 5. */
+    topK?: number;
+};
+/** Vector store interface for semantic memory. */
+interface VectorStore {
+    upsert(entries: VectorEntry[]): Promise<void>;
+    search(embedding: number[], topK: number): Promise<VectorResult[]>;
+    delete(ids: string[]): Promise<void>;
+    close?(): Promise<void>;
+}
+/** Embedder interface for converting text to vectors. */
+interface Embedder {
+    embed(texts: string[]): Promise<number[][]>;
+    readonly dimensions: number;
+}
+/** Memory configuration. */
+type MemoryConfig = {
+    /** Vector store for semantic memory (optional). */
+    vectorStore?: VectorStore;
+    /** Embedder for converting text to vectors (required if vectorStore is set). */
+    embedder?: Embedder;
+};
+
+/** Provider configuration */
+type ProviderConfig = {
+    apiKey?: string;
+    baseUrl?: string;
+};
+/** MCP server configuration */
+type McpServerConfig$1 = {
+    name: string;
+    command?: string;
+    uri?: string;
+    env?: Record<string, string>;
+};
+/** Trace configuration */
+type TraceConfig = {
+    enabled?: boolean;
+    level?: 'off' | 'steps' | 'full';
+    output?: 'console' | 'json' | 'file';
+    /** When true, redact prompt/response data from agent_call trace events to prevent PII leakage. */
+    redact?: boolean;
+};
+/** State store configuration */
+type StateConfig = {
+    store?: 'memory' | 'sqlite' | 'redis';
+    sqlite?: {
+        path: string;
+    };
+    redis?: {
+        url: string;
+    };
+};
+/** Global defaults */
+type DefaultsConfig = {
+    timeout?: string;
+    maxRetries?: number;
+    budgetPolicy?: 'finish_and_stop' | 'hard_stop' | 'warn';
+};
+/** Context window management configuration */
+type ContextManagementConfig = {
+    summaryModel?: string;
+    reserveTokens?: number;
+};
+
+/** Full Axl configuration */
+type AxlConfig = {
+    providers?: Record<string, ProviderConfig>;
+    defaultProvider?: string;
+    defaultModel?: string;
+    mcp?: {
+        servers?: McpServerConfig$1[];
+    };
+    state?: StateConfig;
+    trace?: TraceConfig;
+    defaults?: DefaultsConfig;
+    contextManagement?: ContextManagementConfig;
+    memory?: MemoryConfig;
+    telemetry?: TelemetryConfig;
+};
+/**
+ * Create a type-safe Axl configuration object for providers, state, tracing, and defaults.
+ * @param config - The full Axl configuration (providers, state store, tracing, defaults, context management).
+ * @returns The same configuration object, validated at the type level.
+ */
+declare function defineConfig(config: AxlConfig): AxlConfig;
+
+/**
+ * Resolved result from a provider:model URI.
+ */
+type ResolvedProvider = {
+    provider: Provider;
+    model: string;
+};
+type ProviderFactory = (config: AxlConfig) => Provider;
+/**
+ * Registry for LLM providers. Holds cached provider instances and supports
+ * custom provider registration.
+ *
+ * Usage:
+ *   const registry = new ProviderRegistry();
+ *   registry.register('custom', (config) => new MyProvider(config));
+ *   const { provider, model } = registry.resolve('openai:gpt-4o', config);
+ */
+declare class ProviderRegistry {
+    /** Cached provider instances, keyed by provider name */
+    private instances;
+    /** Factory functions, keyed by provider name */
+    private factories;
+    /** Fallback provider returned when no factory or instance matches */
+    private fallbackInstance?;
+    constructor();
+    /**
+     * Register a custom provider factory.
+     * If a provider with this name already exists, it is replaced and
+     * any cached instance is evicted.
+     */
+    register(name: string, factory: ProviderFactory): void;
+    /**
+     * Register a pre-instantiated provider directly.
+     */
+    registerInstance(name: string, provider: Provider): void;
+    /**
+     * Check whether a provider with the given name is registered.
+     */
+    has(name: string): boolean;
+    /**
+     * List all registered provider names.
+     */
+    list(): string[];
+    /**
+     * Set a fallback provider returned when no factory or instance matches.
+     * Useful for testing where a single mock provider covers all agents.
+     */
+    setFallback(provider: Provider): void;
+    /**
+     * Get a provider instance by name, creating it lazily via its factory.
+     */
+    get(name: string, config?: AxlConfig): Provider;
+    /**
+     * Resolve a "provider:model" URI string into a Provider instance and model name.
+     *
+     * Supported formats:
+     *   - "openai:gpt-4o"        -> provider=openai, model=gpt-4o
+     *   - "anthropic:claude-3"   -> provider=anthropic, model=claude-3
+     *   - "gpt-4o"               -> uses defaultProvider from config, model=gpt-4o
+     *   - undefined / empty      -> uses defaultProvider and defaultModel from config
+     *
+     * @param uri  Provider:model string, or just a model name
+     * @param config  Axl configuration for provider options and defaults
+     */
+    resolve(uri: string | undefined, config?: AxlConfig): ResolvedProvider;
+    /**
+     * Clear all cached provider instances. Useful for testing or reconfiguration.
+     */
+    clearCache(): void;
+    /**
+     * Clear all registered factories (including built-ins).
+     * Useful for test runtimes where only explicitly registered instances should be used.
+     */
+    clearFactories(): void;
+}
+
+/** A pending human decision awaiting resolution. */
+type PendingDecision = {
+    executionId: string;
+    channel: string;
+    prompt: string;
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+};
+/** Persisted execution state for suspend/resume. */
+type ExecutionState = {
+    workflow: string;
+    input: unknown;
+    step: number;
+    status: 'waiting' | 'running';
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Pluggable state persistence interface.
+ *
+ * Built-in implementations: MemoryStore (testing), SQLiteStore (file-based),
+ * Redis (production).
+ */
+interface StateStore {
+    saveCheckpoint(executionId: string, step: number, data: unknown): Promise<void>;
+    getCheckpoint(executionId: string, step: number): Promise<unknown | null>;
+    getLatestCheckpoint(executionId: string): Promise<{
+        step: number;
+        data: unknown;
+    } | null>;
+    saveSession(sessionId: string, history: ChatMessage[]): Promise<void>;
+    getSession(sessionId: string): Promise<ChatMessage[]>;
+    deleteSession(sessionId: string): Promise<void>;
+    saveSessionMeta(sessionId: string, key: string, value: unknown): Promise<void>;
+    getSessionMeta(sessionId: string, key: string): Promise<unknown | null>;
+    savePendingDecision(executionId: string, decision: PendingDecision): Promise<void>;
+    getPendingDecisions(): Promise<PendingDecision[]>;
+    resolveDecision(executionId: string, result: HumanDecision): Promise<void>;
+    saveExecutionState(executionId: string, state: ExecutionState): Promise<void>;
+    getExecutionState(executionId: string): Promise<ExecutionState | null>;
+    listPendingExecutions(): Promise<string[]>;
+    /** Save a memory entry (key-value). */
+    saveMemory?(scope: string, key: string, value: unknown): Promise<void>;
+    /** Get a memory entry by key. */
+    getMemory?(scope: string, key: string): Promise<unknown | null>;
+    /** Get all memory entries for a scope. */
+    getAllMemory?(scope: string): Promise<Array<{
+        key: string;
+        value: unknown;
+    }>>;
+    /** Delete a memory entry by key. */
+    deleteMemory?(scope: string, key: string): Promise<void>;
+    close?(): Promise<void>;
+    deleteCheckpoints?(executionId: string): Promise<void>;
+}
+
+/**
+ * MCP (Model Context Protocol) types for tool discovery and execution.
+ */
+/** A tool definition discovered from an MCP server. */
+type McpToolDefinition = {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+};
+/** Configuration for connecting to an MCP server. */
+type McpServerConfig = {
+    name: string;
+    /** Command to spawn for stdio transport (e.g. "npx -y @modelcontextprotocol/server-fs") */
+    command?: string;
+    /** Arguments for the command */
+    args?: string[];
+    /** HTTP/SSE endpoint URI for HTTP transport */
+    uri?: string;
+    /** Environment variables to pass to the spawned process */
+    env?: Record<string, string>;
+};
+/** Result from calling an MCP tool. */
+type McpToolResult = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    } | {
+        type: 'image';
+        data: string;
+        mimeType: string;
+    }>;
+    isError?: boolean;
+};
+/** A connected MCP server with its discovered tools. */
+type McpServer = {
+    name: string;
+    tools: McpToolDefinition[];
+    callTool(toolName: string, args: unknown): Promise<McpToolResult>;
+    close(): Promise<void>;
+};
+
+/**
+ * Manages connections to multiple MCP servers.
+ * Discovers tools, filters by agent config, and routes tool calls.
+ *
+ * MCP tools are namespaced internally as "server:tool_name" for disambiguation
+ * and trace output, but presented to the LLM with their original names
+ * (no prefix) to avoid confusing the model.
+ */
+declare class McpManager {
+    private servers;
+    private initPromise;
+    /**
+     * Initialize connections to all configured MCP servers.
+     * Safe to call multiple times — subsequent calls return the original promise.
+     */
+    initialize(configs: McpServerConfig[]): Promise<void>;
+    /**
+     * Get all tools from all connected servers.
+     */
+    getAllTools(): Array<{
+        server: string;
+        tool: McpToolDefinition;
+    }>;
+    /**
+     * Get the qualified name for an MCP tool: "server:tool_name".
+     * Used in traces and ACL declarations.
+     */
+    getQualifiedName(toolName: string): string | undefined;
+    /**
+     * Get tool definitions filtered for a specific agent's MCP configuration.
+     *
+     * @param agentMcp - Server names the agent has access to (undefined = all)
+     * @param agentMcpTools - Specific tool names the agent can use.
+     *   Accepts both plain names ("read_file") and qualified names ("fs-server:read_file").
+     *   Qualified names enable disambiguation when multiple servers expose same-named tools.
+     */
+    getToolsForAgent(agentMcp?: string[], agentMcpTools?: string[]): Array<{
+        server: string;
+        tool: McpToolDefinition;
+    }>;
+    /**
+     * Convert MCP tools to ToolDefinition format for sending to LLMs.
+     * Tools are presented with their original names (no server prefix)
+     * to avoid confusing the LLM.
+     */
+    getToolDefinitions(agentMcp?: string[], agentMcpTools?: string[]): ToolDefinition[];
+    /**
+     * Call a tool by name. Finds the correct server automatically.
+     *
+     * @param toolName - The tool name
+     * @param args - Arguments for the tool
+     * @param serverHint - Optional server name if known (for disambiguation)
+     */
+    callTool(toolName: string, args: unknown, serverHint?: string): Promise<McpToolResult>;
+    /**
+     * Check if a tool name belongs to an MCP server.
+     */
+    isMcpTool(toolName: string): boolean;
+    /**
+     * Shut down all MCP server connections.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get the number of connected servers.
+     */
+    get serverCount(): number;
+}
+
+/**
+ * Coordinates key-value memory and vector store for semantic search.
+ * All key-value operations delegate to the StateStore.
+ * Vector operations use the configured VectorStore + Embedder.
+ */
+declare class MemoryManager {
+    private vectorStore?;
+    private embedder?;
+    constructor(options?: {
+        vectorStore?: VectorStore;
+        embedder?: Embedder;
+    });
+    /**
+     * Store a key-value pair in memory.
+     * If a vector store and embedder are configured and embed is true,
+     * also embeds the value for semantic search.
+     */
+    remember(key: string, value: unknown, stateStore: StateStore, sessionId: string | undefined, options?: RememberOptions): Promise<void>;
+    /**
+     * Recall a value from memory by key, or perform semantic search if query is provided.
+     */
+    recall(key: string, stateStore: StateStore, sessionId: string | undefined, options?: RecallOptions): Promise<unknown | VectorResult[] | null>;
+    /** Delete a memory entry. If a vector store is configured, also removes the embedding. */
+    forget(key: string, stateStore: StateStore, sessionId: string | undefined, options?: {
+        scope?: 'session' | 'global';
+    }): Promise<void>;
+    /** Shut down the vector store if it has a close method. */
+    close(): Promise<void>;
+}
+
+type WorkflowContextInit = {
+    input: unknown;
+    executionId: string;
+    metadata?: Record<string, unknown>;
+    config: AxlConfig;
+    providerRegistry: ProviderRegistry;
+    sessionHistory?: ChatMessage[];
+    onTrace?: (event: TraceEvent) => void;
+    onToken?: (token: string) => void;
+    onToolCall?: (call: {
+        name: string;
+        args: unknown;
+    }) => void;
+    pendingDecisions?: Map<string, (d: HumanDecision) => void>;
+    budgetContext?: {
+        totalCost: number;
+        limit: number;
+        exceeded: boolean;
+        policy: string;
+        abortController?: AbortController;
+    };
+    stateStore?: StateStore;
+    signal?: AbortSignal;
+    workflowName?: string;
+    mcpManager?: McpManager;
+    /** SpanManager for OpenTelemetry instrumentation. */
+    spanManager?: SpanManager;
+    /** MemoryManager for ctx.remember() / ctx.recall() operations. */
+    memoryManager?: MemoryManager;
+    /** When true, the context replays from checkpoints before executing. */
+    resumeMode?: boolean;
+    /** Override tool handlers by name. Bypasses normal tool lookup in executeAgentCall. */
+    toolOverrides?: Map<string, (args: unknown) => Promise<unknown>>;
+    /** Handler for awaitHuman — when set, returns immediately instead of waiting for pendingDecisions. */
+    awaitHumanHandler?: (options: AwaitHumanOptions) => HumanDecision | Promise<HumanDecision>;
+    /** Callback fired when an agent LLM call is about to start. */
+    onAgentStart?: (info: {
+        agent: string;
+        model: string;
+    }) => void;
+    /** Callback fired after each ctx.ask() completes (once per ask invocation). */
+    onAgentCallComplete?: (call: {
+        agent: string;
+        prompt: string;
+        response: string;
+        model: string;
+        cost: number;
+        duration: number;
+        promptVersion?: string;
+    }) => void;
+};
+/**
+ * The central coordination object for all Axl primitives.
+ * Carries execution state, tracing, budget tracking, and session history.
+ */
+declare class WorkflowContext<TInput = unknown> {
+    readonly input: TInput;
+    readonly executionId: string;
+    readonly metadata: Record<string, unknown>;
+    private config;
+    private providerRegistry;
+    private sessionHistory;
+    private onTrace?;
+    private onToken?;
+    private onToolCall?;
+    private pendingDecisions?;
+    private budgetContext?;
+    private stateStore?;
+    private stepCounter;
+    private checkpointCounter;
+    private signal?;
+    private summaryCache?;
+    private workflowName?;
+    private mcpManager?;
+    private spanManager?;
+    private memoryManager?;
+    private resumeMode;
+    private toolOverrides?;
+    private awaitHumanHandler?;
+    private onAgentStart?;
+    private onAgentCallComplete?;
+    constructor(init: WorkflowContextInit);
+    /**
+     * Resolve the current abort signal.
+     * Branch-scoped signals (from race/spawn/map/budget) in AsyncLocalStorage
+     * take priority over the instance-level signal.
+     */
+    private get currentSignal();
+    ask<T = string>(agent: Agent, prompt: string, options?: AskOptions<T>): Promise<T>;
+    private executeAgentCall;
+    private buildToolDefs;
+    /**
+     * Summarize old messages to fit within context window.
+     * Keeps recent messages intact, summarizes older ones.
+     */
+    private summarizeHistory;
+    /**
+     * Execute a function with checkpoint-replay semantics.
+     *
+     * On first execution, runs `fn()`, saves the result, and returns it.
+     * On replay (resume after restart), returns the saved result without re-executing.
+     * This prevents duplicate side effects (double API calls, double refunds, etc.).
+     */
+    checkpoint<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Internal checkpoint implementation shared by both the public checkpoint()
+     * and the automatic checkpointing in ask/spawn/race/parallel/map.
+     */
+    private _checkpoint;
+    spawn<T>(n: number, fn: (index: number) => Promise<T>, options?: SpawnOptions): Promise<Result<T>[]>;
+    private _spawnImpl;
+    vote<T>(results: Result<T>[], options: VoteOptions<T>): T | Promise<T>;
+    private _voteImpl;
+    private asyncVote;
+    private majorityVote;
+    private unanimousVote;
+    private numericVote;
+    private meanVote;
+    private medianVote;
+    verify<T>(fn: (lastOutput?: unknown, errorMessage?: string) => Promise<unknown>, schema: z.ZodType<T>, options?: VerifyOptions<T>): Promise<T>;
+    budget<T>(options: BudgetOptions, fn: () => Promise<T>): Promise<BudgetResult<T>>;
+    /** Get the current budget status, or null if not inside a budget block. */
+    getBudgetStatus(): {
+        spent: number;
+        limit: number;
+        remaining: number;
+    } | null;
+    race<T>(fns: Array<() => Promise<T>>, options?: RaceOptions<T>): Promise<T>;
+    private _raceImpl;
+    parallel<T extends unknown[]>(fns: {
+        [K in keyof T]: () => Promise<T[K]>;
+    }): Promise<T>;
+    map<T, U>(items: T[], fn: (item: T, index: number) => Promise<U>, options?: MapOptions): Promise<Result<U>[]>;
+    private _mapImpl;
+    awaitHuman(options: AwaitHumanOptions): Promise<HumanDecision>;
+    private _awaitHumanImpl;
+    log(event: string, data?: unknown): void;
+    /**
+     * Store a value in memory, scoped to the current session (default) or globally.
+     * When a vector store is configured, the value is also embedded for semantic recall.
+     */
+    remember(key: string, value: unknown, options?: RememberOptions): Promise<void>;
+    /**
+     * Recall a value from memory by key, or perform semantic search if query option is provided.
+     */
+    recall(key: string, options?: RecallOptions): Promise<unknown | VectorResult[] | null>;
+    /** Delete a memory entry by key. */
+    forget(key: string, options?: {
+        scope?: 'session' | 'global';
+    }): Promise<void>;
+    private emitTrace;
+}
+
+/** Retry policy for tool handlers */
+type RetryPolicy = {
+    attempts?: number;
+    backoff?: 'none' | 'linear' | 'exponential';
+    on?: (error: Error & {
+        status?: number;
+    }) => boolean;
+};
+/** Lifecycle hooks for tool execution. */
+type ToolHooks<TInput = unknown, TOutput = unknown> = {
+    /** Transform input before the handler runs. Receives parsed input and workflow context. */
+    before?: (input: TInput, ctx: WorkflowContext) => TInput | Promise<TInput>;
+    /** Transform output after the handler runs. Receives handler result and workflow context. */
+    after?: (output: TOutput, ctx: WorkflowContext) => TOutput | Promise<TOutput>;
+};
+/** Tool configuration */
+type ToolConfig<TInput extends z.ZodTypeAny, TOutput = unknown> = {
+    name: string;
+    description: string;
+    input: TInput;
+    handler: (input: z.infer<TInput>) => TOutput | Promise<TOutput>;
+    retry?: RetryPolicy;
+    sensitive?: boolean;
+    /** Maximum string length for any string argument. Default: 10000. Set to 0 to disable. */
+    maxStringLength?: number;
+    /** When true, agent-initiated calls trigger ctx.awaitHuman() before execution. */
+    requireApproval?: boolean;
+    /** Lifecycle hooks: before/after the handler. */
+    hooks?: ToolHooks<z.infer<TInput>, TOutput>;
+};
+/** A defined tool instance */
+type Tool<TInput extends z.ZodTypeAny = z.ZodTypeAny, TOutput = unknown> = {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: TInput;
+    readonly sensitive: boolean;
+    readonly retry: RetryPolicy;
+    readonly requireApproval: boolean;
+    readonly hooks?: ToolHooks<z.infer<TInput>, TOutput>;
+    /** Run the tool directly from workflow code */
+    run(ctx: WorkflowContext, input: z.infer<TInput>): Promise<TOutput>;
+    /** Execute the handler (internal use — includes retry logic) */
+    _execute(input: z.infer<TInput>): Promise<TOutput>;
+};
+/**
+ * Define a tool with Zod-validated input, a handler function, and optional retry policy.
+ * @param config - Tool configuration: name, description, input schema, handler, retry, and sensitivity options.
+ * @returns A Tool instance that can be attached to agents and invoked via `tool.run()` or agent tool calling.
+ */
+declare function tool<TInput extends z.ZodTypeAny, TOutput = unknown>(config: ToolConfig<TInput, TOutput>): Tool<TInput, TOutput>;
+
+/** Workflow configuration */
+type WorkflowConfig<TInput extends z.ZodTypeAny = z.ZodTypeAny, TOutput extends z.ZodTypeAny = z.ZodTypeAny> = {
+    name: string;
+    input: TInput;
+    output?: TOutput;
+    handler: (ctx: WorkflowContext<z.infer<TInput>>) => Promise<z.infer<TOutput>>;
+};
+/** A defined workflow instance */
+type Workflow<TInput extends z.ZodTypeAny = z.ZodTypeAny, TOutput extends z.ZodTypeAny = z.ZodTypeAny> = {
+    readonly name: string;
+    readonly inputSchema: TInput;
+    readonly outputSchema: TOutput | undefined;
+    readonly handler: (ctx: WorkflowContext<z.infer<TInput>>) => Promise<z.infer<TOutput>>;
+};
+/**
+ * Define a named workflow with Zod-validated input/output and an async handler.
+ * Register workflows with `AxlRuntime.register()` to execute them.
+ * @param config - Workflow configuration: name, input schema, optional output schema, and async handler receiving a WorkflowContext.
+ * @returns A Workflow instance ready to be registered with an AxlRuntime.
+ */
+declare function workflow<TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny = z.ZodTypeAny>(config: WorkflowConfig<TInput, TOutput>): Workflow<TInput, TOutput>;
+
+/**
+ * A streamable workflow execution.
+ *
+ * Extends Node's Readable and implements AsyncIterable<StreamEvent>.
+ * Supports .on() events, for-await-of, .text iterator, and .pipe().
+ */
+declare class AxlStream extends Readable {
+    private bus;
+    private tokens;
+    private result;
+    private finished;
+    readonly promise: Promise<unknown>;
+    private eventQueue;
+    private waiters;
+    constructor();
+    private static readonly STREAM_EVENTS;
+    on(event: string, handler: (...args: unknown[]) => void): this;
+    off(event: string, handler: (...args: unknown[]) => void): this;
+    [Symbol.asyncIterator](): {
+        next: () => Promise<IteratorResult<StreamEvent>>;
+        [Symbol.asyncIterator](): /*elided*/ any;
+        [Symbol.asyncDispose](): Promise<void>;
+    };
+    get text(): AsyncIterable<string>;
+    get steps(): AsyncIterable<StreamEvent>;
+    pipe<T extends NodeJS.WritableStream>(destination: T, options?: {
+        end?: boolean;
+    }): T;
+    /** Push a stream event. Called by the runtime. */
+    _push(event: StreamEvent): void;
+    /** Signal successful completion. */
+    _done(result: unknown): void;
+    /** Signal an error. */
+    _error(error: Error): void;
+    get fullText(): string;
+}
+
+/** Options for configuring a session. */
+type SessionOptions = {
+    /** History management options. */
+    history?: {
+        /** Maximum number of messages to keep in history. Older messages are trimmed (or summarized if summarize is true). */
+        maxMessages?: number;
+        /** When true and maxMessages is exceeded, summarize old messages instead of dropping them. Requires summaryModel to be set. Default: false. */
+        summarize?: boolean;
+        /** Model URI to use for summarization (e.g., 'openai:gpt-4o-mini'). Required when summarize is true. */
+        summaryModel?: string;
+    };
+    /** Whether to persist session history to the state store. Default: true. */
+    persist?: boolean;
+};
+/**
+ * A stateful conversation session.
+ * Persists message history across multiple interactions.
+ */
+declare class Session {
+    private sessionId;
+    private runtime;
+    private store;
+    private closed;
+    private options;
+    constructor(sessionId: string, runtime: AxlRuntime, store: StateStore, options?: SessionOptions);
+    get id(): string;
+    send(workflowName: string, input: unknown): Promise<unknown>;
+    stream(workflowName: string, input: unknown): Promise<AxlStream>;
+    history(): Promise<ChatMessage[]>;
+    /** Get the handoff history for this session. */
+    handoffs(): Promise<HandoffRecord[]>;
+    end(): Promise<void>;
+    fork(newId: string): Promise<Session>;
+}
+
+type ExecuteOptions = {
+    metadata?: Record<string, unknown>;
+};
+/**
+ * The main entry point for executing Axl workflows.
+ * Manages workflow registration, provider resolution, state storage, tracing, MCP servers,
+ * and human-in-the-loop decision handling. Supports both synchronous (`execute`) and
+ * streaming (`stream`) execution modes, as well as multi-turn sessions.
+ */
+declare class AxlRuntime extends EventEmitter {
+    private config;
+    private workflows;
+    private providerRegistry;
+    private stateStore;
+    private executions;
+    private pendingDecisionResolvers;
+    private abortControllers;
+    private mcpManager?;
+    private memoryManager?;
+    private spanManager;
+    constructor(config?: AxlConfig);
+    /**
+     * Initialize MCP servers configured in the config.
+     * Call this before executing workflows that use MCP tools.
+     */
+    initializeMcp(): Promise<void>;
+    /**
+     * Initialize OpenTelemetry telemetry based on config.
+     * Call this before executing workflows to enable span creation.
+     */
+    initializeTelemetry(): Promise<void>;
+    /** Get the MCP manager (if initialized). */
+    getMcpManager(): McpManager | undefined;
+    private createStateStore;
+    /** Register a workflow with the runtime. */
+    register(workflow: Workflow): void;
+    /** Register a custom provider instance. */
+    registerProvider(name: string, provider: Provider): void;
+    /** Execute a workflow and return the result. */
+    execute(name: string, input: unknown, options?: ExecuteOptions): Promise<unknown>;
+    /** Execute a workflow and return a stream. */
+    stream(name: string, input: unknown, options?: ExecuteOptions): AxlStream;
+    /** Create or resume a session. */
+    session(id: string, options?: SessionOptions): Session;
+    /** Gracefully shut down the runtime, aborting in-flight executions and closing state stores and MCP servers. */
+    shutdown(): Promise<void>;
+    /** Abort a running execution by its ID. */
+    abort(executionId: string): void;
+    /** Get execution details by ID. */
+    getExecution(executionId: string): Promise<ExecutionInfo | undefined>;
+    /** List pending human decisions. */
+    getPendingDecisions(): Promise<PendingDecision[]>;
+    /** Resolve a pending human decision. */
+    resolveDecision(executionId: string, decision: HumanDecision): Promise<void>;
+    /**
+     * Resume a specific execution that was waiting for a human decision.
+     * Re-runs the workflow from scratch; the workflow should use checkpoint-replay
+     * to skip already-completed steps and pick up from the awaitHuman point.
+     */
+    resumeExecution(executionId: string): Promise<unknown>;
+    /**
+     * Resume all pending executions that were waiting for human decisions.
+     * Call this on startup to resume workflows that were interrupted by a restart.
+     * Returns the execution IDs that were resumed.
+     */
+    resumePending(): Promise<string[]>;
+    /**
+     * Summarize a list of chat messages into a concise summary string.
+     * Used by Session to summarize dropped messages when history.summarize is enabled.
+     */
+    summarizeMessages(messages: ChatMessage[], modelUri: string): Promise<string>;
+    /** Get the state store (for testing and advanced use cases). */
+    getStateStore(): StateStore;
+    /**
+     * Run an evaluation against a registered workflow.
+     * Requires `axl-eval` as a peer dependency.
+     *
+     * @see Spec Section 13.5
+     */
+    eval(config: {
+        workflow: string;
+        dataset: any;
+        scorers: any[];
+        concurrency?: number;
+        budget?: string;
+        metadata?: Record<string, any>;
+    }): Promise<any>;
+    /**
+     * Compare two evaluation results to detect regressions and improvements.
+     * Requires `axl-eval` as a peer dependency.
+     *
+     * @see Spec Section 13.6
+     */
+    evalCompare(baseline: any, candidate: any): Promise<any>;
+    /**
+     * Handle trace event output based on configuration.
+     *
+     * When trace is disabled or level is 'off', events are still emitted via
+     * EventEmitter (for programmatic subscribers) but nothing is logged to console.
+     * The emit('trace', event) call happens before this method is called, so
+     * programmatic subscribers always receive events regardless of trace config.
+     */
+    private outputTraceEvent;
+    private logTraceEvent;
+    /**
+     * Append a handoff record to session metadata.
+     * Note: The read-modify-write is not atomic. Concurrent handoffs in the same
+     * session could lose a record. In practice, trace events within a single
+     * execution are sequential (same event loop), so this is only a concern for
+     * cross-execution concurrency on the same session, which is unlikely.
+     */
+    private appendHandoffRecord;
+}
+
+/** Base error class for all Axl errors */
+declare class AxlError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Thrown when schema validation fails after all retries exhausted */
+declare class VerifyError extends AxlError {
+    readonly lastOutput: unknown;
+    readonly zodError: ZodError;
+    readonly retries: number;
+    constructor(lastOutput: unknown, zodError: ZodError, retries: number);
+}
+/** Thrown when quorum is not met in spawn */
+declare class QuorumNotMet extends AxlError {
+    readonly results: Result<unknown>[];
+    constructor(required: number, actual: number, results: Result<unknown>[]);
+}
+/** Thrown when vote cannot reach consensus */
+declare class NoConsensus extends AxlError {
+    constructor(reason: string);
+}
+/** Thrown when an operation exceeds its timeout */
+declare class TimeoutError extends AxlError {
+    constructor(operation: string, timeoutMs: number);
+}
+/** Thrown when a budget limit is exceeded */
+declare class BudgetExceededError extends AxlError {
+    readonly limit: number;
+    readonly spent: number;
+    readonly policy: string;
+    constructor(limit: number, spent: number, policy: string);
+}
+/** Thrown when an agent exceeds its maximum number of tool-calling turns */
+declare class MaxTurnsError extends AxlError {
+    readonly maxTurns: number;
+    constructor(operation: string, maxTurns: number);
+}
+/** Thrown when a guardrail blocks a request/response and the policy is 'throw'. */
+declare class GuardrailError extends AxlError {
+    readonly guardrailType: 'input' | 'output';
+    readonly reason: string;
+    constructor(guardrailType: 'input' | 'output', reason: string);
+}
+/** Internal: thrown when an agent tries to call a tool not in its ACL */
+declare class ToolDenied extends AxlError {
+    readonly toolName: string;
+    readonly agentName: string;
+    constructor(toolName: string, agentName: string);
+}
+
+/**
+ * OpenAI-compatible provider using raw fetch (no SDK dependency).
+ *
+ * Supports:
+ * - Chat completions
+ * - Tool calling
+ * - Streaming via SSE
+ * - Structured output via response_format (JSON mode / JSON schema)
+ * - Reasoning models (o1/o3/o4-mini) with developer role and reasoning_effort
+ */
+declare class OpenAIProvider implements Provider {
+    readonly name = "openai";
+    private baseUrl;
+    private apiKey;
+    constructor(options?: {
+        apiKey?: string;
+        baseUrl?: string;
+    });
+    chat(messages: ChatMessage[], options: ChatOptions): Promise<ProviderResponse>;
+    stream(messages: ChatMessage[], options: ChatOptions): AsyncGenerator<StreamChunk>;
+    private buildRequestBody;
+    /** Extract a human-readable message from an API error response body. */
+    private extractErrorMessage;
+    private formatMessage;
+    private parseSSEStream;
+}
+
+/**
+ * OpenAI Responses API provider using raw fetch (no SDK dependency).
+ *
+ * Maps the standard Provider interface to OpenAI's Responses API (`POST /v1/responses`).
+ * The Responses API is OpenAI's recommended path forward with better caching,
+ * built-in tools, and native reasoning support.
+ */
+declare class OpenAIResponsesProvider implements Provider {
+    readonly name = "openai-responses";
+    private baseUrl;
+    private apiKey;
+    constructor(options?: {
+        apiKey?: string;
+        baseUrl?: string;
+    });
+    chat(messages: ChatMessage[], options: ChatOptions): Promise<ProviderResponse>;
+    stream(messages: ChatMessage[], options: ChatOptions): AsyncGenerator<StreamChunk>;
+    private buildRequestBody;
+    private buildInput;
+    /**
+     * The Responses API uses `text.format` instead of `response_format`.
+     * For `json_schema`, the schema fields are flattened into the format object
+     * rather than nested under a `json_schema` key.
+     *
+     * Chat Completions: `{ type: "json_schema", json_schema: { name, strict, schema } }`
+     * Responses API:    `{ type: "json_schema", name, strict, schema }`
+     */
+    private mapResponseFormat;
+    private parseResponse;
+    private parseSSEStream;
+    private handleStreamEvent;
+    private extractErrorMessage;
+}
+
+/**
+ * Anthropic provider using raw fetch (no SDK dependency).
+ *
+ * Supports:
+ * - Chat completions via /v1/messages
+ * - Tool calling (tool_use / tool_result content blocks)
+ * - Streaming via SSE
+ *
+ * Message mapping:
+ * - "system" role messages are extracted and sent as the top-level `system` param
+ * - "tool" role messages are mapped to user messages with tool_result content blocks
+ * - "assistant" messages with tool_calls are mapped to tool_use content blocks
+ */
+declare class AnthropicProvider implements Provider {
+    readonly name = "anthropic";
+    private baseUrl;
+    private apiKey;
+    private currentModel?;
+    constructor(options?: {
+        apiKey?: string;
+        baseUrl?: string;
+    });
+    chat(messages: ChatMessage[], options: ChatOptions): Promise<ProviderResponse>;
+    stream(messages: ChatMessage[], options: ChatOptions): AsyncGenerator<StreamChunk>;
+    private buildHeaders;
+    /** Extract a human-readable message from an API error response body. */
+    private extractErrorMessage;
+    private buildRequestBody;
+    /**
+     * Map OpenAI-format ChatMessages to Anthropic message format.
+     *
+     * Key transformations:
+     * - assistant messages with tool_calls -> assistant with tool_use content blocks
+     * - tool messages (tool results) -> user messages with tool_result content blocks
+     */
+    private mapMessages;
+    /**
+     * Merge consecutive messages with the same role into a single message.
+     * This handles cases where multiple tool_result blocks need to be in one user message.
+     */
+    private mergeConsecutiveRoles;
+    private toContentBlocks;
+    /**
+     * Map an OpenAI-format ToolDefinition to Anthropic's tool format.
+     */
+    private mapToolDefinition;
+    private parseResponse;
+    private parseSSEStream;
+}
+
+/**
+ * Google Gemini provider using raw fetch (no SDK dependency).
+ *
+ * Supports:
+ * - Chat completions via generateContent
+ * - Tool calling (functionCall / functionResponse)
+ * - Streaming via SSE (streamGenerateContent)
+ * - Structured output via responseMimeType / responseSchema
+ *
+ * Message mapping:
+ * - "system" role messages are extracted into the top-level `system_instruction` param
+ * - "assistant" role is mapped to "model" role
+ * - "tool" role messages are mapped to user messages with functionResponse parts
+ * - assistant messages with tool_calls are mapped to functionCall parts
+ */
+declare class GeminiProvider implements Provider {
+    readonly name = "google";
+    private baseUrl;
+    private apiKey;
+    private callCounter;
+    constructor(options?: {
+        apiKey?: string;
+        baseUrl?: string;
+    });
+    chat(messages: ChatMessage[], options: ChatOptions): Promise<ProviderResponse>;
+    stream(messages: ChatMessage[], options: ChatOptions): AsyncGenerator<StreamChunk>;
+    private buildHeaders;
+    private extractErrorMessage;
+    private buildRequestBody;
+    /**
+     * Map OpenAI-format ChatMessages to Gemini content format.
+     *
+     * Key transformations:
+     * - assistant role -> model role
+     * - assistant messages with tool_calls -> model messages with functionCall parts
+     * - tool messages -> user messages with functionResponse parts
+     *
+     * Two-pass approach: first build a tool_call_id -> function name mapping
+     * from assistant messages, then use it when mapping tool result messages.
+     */
+    private mapMessages;
+    /**
+     * Merge consecutive messages with the same role into a single message.
+     * Gemini requires alternating user/model turns.
+     */
+    private mergeConsecutiveRoles;
+    private mapToolDefinition;
+    private parseResponse;
+    private parseSSEStream;
+}
+
+/**
+ * In-memory implementation of StateStore.
+ * Fast for development and testing, but lost on process restart.
+ *
+ * Exception: awaitHuman state (pending decisions + execution states with
+ * status "waiting") is persisted to a temporary file so it survives restarts.
+ * This is the one exception to "memory means ephemeral" — because a human
+ * could take hours to respond, and losing that state is unacceptable.
+ */
+declare class MemoryStore implements StateStore {
+    private checkpoints;
+    private sessions;
+    private sessionMeta;
+    private decisions;
+    private executionStates;
+    private memories;
+    constructor();
+    saveCheckpoint(executionId: string, step: number, data: unknown): Promise<void>;
+    getCheckpoint(executionId: string, step: number): Promise<unknown | null>;
+    getLatestCheckpoint(executionId: string): Promise<{
+        step: number;
+        data: unknown;
+    } | null>;
+    saveSession(sessionId: string, history: ChatMessage[]): Promise<void>;
+    getSession(sessionId: string): Promise<ChatMessage[]>;
+    deleteSession(sessionId: string): Promise<void>;
+    saveSessionMeta(sessionId: string, key: string, value: unknown): Promise<void>;
+    getSessionMeta(sessionId: string, key: string): Promise<unknown | null>;
+    savePendingDecision(executionId: string, decision: PendingDecision): Promise<void>;
+    getPendingDecisions(): Promise<PendingDecision[]>;
+    resolveDecision(executionId: string, _result: HumanDecision): Promise<void>;
+    saveExecutionState(executionId: string, state: ExecutionState): Promise<void>;
+    getExecutionState(executionId: string): Promise<ExecutionState | null>;
+    listPendingExecutions(): Promise<string[]>;
+    saveMemory(scope: string, key: string, value: unknown): Promise<void>;
+    getMemory(scope: string, key: string): Promise<unknown | null>;
+    getAllMemory(scope: string): Promise<Array<{
+        key: string;
+        value: unknown;
+    }>>;
+    deleteMemory(scope: string, key: string): Promise<void>;
+    close(): Promise<void>;
+    deleteCheckpoints(executionId: string): Promise<void>;
+    private persistAwaitHumanState;
+    private loadPersistedState;
+}
+
+/**
+ * SQLite-backed StateStore using better-sqlite3.
+ *
+ * Zero-config, file-based persistence suitable for single-process production.
+ * Uses prepared statements for all operations.
+ *
+ * Requires `better-sqlite3` as a peer dependency. If not installed,
+ * the constructor throws a clear error message.
+ */
+declare class SQLiteStore implements StateStore {
+    private db;
+    constructor(filePath: string);
+    private initTables;
+    saveCheckpoint(executionId: string, step: number, data: unknown): Promise<void>;
+    getCheckpoint(executionId: string, step: number): Promise<unknown | null>;
+    getLatestCheckpoint(executionId: string): Promise<{
+        step: number;
+        data: unknown;
+    } | null>;
+    saveSession(sessionId: string, history: ChatMessage[]): Promise<void>;
+    getSession(sessionId: string): Promise<ChatMessage[]>;
+    deleteSession(sessionId: string): Promise<void>;
+    saveSessionMeta(sessionId: string, key: string, value: unknown): Promise<void>;
+    getSessionMeta(sessionId: string, key: string): Promise<unknown | null>;
+    savePendingDecision(executionId: string, decision: PendingDecision): Promise<void>;
+    getPendingDecisions(): Promise<PendingDecision[]>;
+    resolveDecision(executionId: string, _result: HumanDecision): Promise<void>;
+    saveExecutionState(executionId: string, state: ExecutionState): Promise<void>;
+    getExecutionState(executionId: string): Promise<ExecutionState | null>;
+    listPendingExecutions(): Promise<string[]>;
+    saveMemory(scope: string, key: string, value: unknown): Promise<void>;
+    getMemory(scope: string, key: string): Promise<unknown | null>;
+    getAllMemory(scope: string): Promise<Array<{
+        key: string;
+        value: unknown;
+    }>>;
+    deleteMemory(scope: string, key: string): Promise<void>;
+    /** Close the database connection. */
+    close(): Promise<void>;
+    deleteCheckpoints(executionId: string): Promise<void>;
+}
+
+/**
+ * Redis-backed StateStore using ioredis.
+ *
+ * Designed for multi-process and sidecar deployments where
+ * multiple runtime instances need shared state.
+ *
+ * Requires `ioredis` as a peer dependency. If not installed,
+ * the constructor throws a clear error message.
+ */
+declare class RedisStore implements StateStore {
+    private client;
+    constructor(url?: string);
+    private checkpointKey;
+    private sessionKey;
+    private sessionMetaKey;
+    private decisionsKey;
+    private executionStateKey;
+    private pendingExecSetKey;
+    saveCheckpoint(executionId: string, step: number, data: unknown): Promise<void>;
+    getCheckpoint(executionId: string, step: number): Promise<unknown | null>;
+    getLatestCheckpoint(executionId: string): Promise<{
+        step: number;
+        data: unknown;
+    } | null>;
+    saveSession(sessionId: string, history: ChatMessage[]): Promise<void>;
+    getSession(sessionId: string): Promise<ChatMessage[]>;
+    deleteSession(sessionId: string): Promise<void>;
+    saveSessionMeta(sessionId: string, key: string, value: unknown): Promise<void>;
+    getSessionMeta(sessionId: string, key: string): Promise<unknown | null>;
+    savePendingDecision(executionId: string, decision: PendingDecision): Promise<void>;
+    getPendingDecisions(): Promise<PendingDecision[]>;
+    resolveDecision(executionId: string, _result: HumanDecision): Promise<void>;
+    saveExecutionState(executionId: string, state: ExecutionState): Promise<void>;
+    getExecutionState(executionId: string): Promise<ExecutionState | null>;
+    listPendingExecutions(): Promise<string[]>;
+    /** Close the Redis connection. */
+    close(): Promise<void>;
+    deleteCheckpoints(executionId: string): Promise<void>;
+}
+
+/**
+ * OpenAI embeddings via raw fetch (zero SDK dependency).
+ * Uses the /v1/embeddings endpoint.
+ */
+declare class OpenAIEmbedder implements Embedder {
+    private apiKey;
+    private model;
+    private baseUrl;
+    readonly dimensions: number;
+    constructor(options?: {
+        apiKey?: string;
+        model?: string;
+        baseUrl?: string;
+        dimensions?: number;
+    });
+    embed(texts: string[]): Promise<number[][]>;
+}
+
+/**
+ * In-memory vector store using brute-force cosine similarity.
+ * Suitable for testing and small datasets only.
+ */
+declare class InMemoryVectorStore implements VectorStore {
+    private entries;
+    upsert(entries: VectorEntry[]): Promise<void>;
+    search(embedding: number[], topK: number): Promise<VectorResult[]>;
+    delete(ids: string[]): Promise<void>;
+}
+
+/**
+ * SQLite-backed vector store using better-sqlite3.
+ * Uses a simple serialized embedding column with brute-force cosine similarity in JS.
+ * For production workloads, consider a dedicated vector database.
+ *
+ * This avoids dependency on sqlite-vec extension by computing similarity in JS
+ * after retrieving all rows (brute-force scan). Suitable for small-to-medium datasets.
+ */
+declare class SqliteVectorStore implements VectorStore {
+    private db;
+    constructor(options?: {
+        path?: string;
+    });
+    private initTables;
+    upsert(entries: VectorEntry[]): Promise<void>;
+    search(embedding: number[], topK: number): Promise<VectorResult[]>;
+    delete(ids: string[]): Promise<void>;
+    close(): Promise<void>;
+}
+
+/**
+ * No-op span manager. Zero overhead when OTel is not configured.
+ * All methods are synchronous no-ops that return immediately.
+ */
+declare class NoopSpanManager implements SpanManager {
+    withSpanAsync<T>(_name: string, _attributes: Record<string, string | number | boolean>, fn: (span: SpanHandle) => Promise<T>): Promise<T>;
+    addEventToActiveSpan(): void;
+    shutdown(): Promise<void>;
+}
+
+/**
+ * Create a SpanManager based on configuration.
+ * Returns NoopSpanManager when telemetry is disabled (zero overhead).
+ * Dynamically imports OTelSpanManager when enabled (avoids hard dep).
+ */
+declare function createSpanManager(config?: TelemetryConfig): Promise<SpanManager>;
+
+export { type Agent, type AgentConfig, AnthropicProvider, type AskOptions, type AwaitHumanOptions, type AxlConfig, AxlError, AxlRuntime, AxlStream, BudgetExceededError, type BudgetOptions, type BudgetResult, type ChatMessage, type ChatOptions, type Embedder, type ExecutionInfo, type ExecutionState, GeminiProvider, type GuardrailBlockHandler, GuardrailError, type GuardrailResult, type GuardrailsConfig, type HandoffDescriptor, type HandoffRecord, type HumanDecision, InMemoryVectorStore, type InputGuardrail, type MapOptions, MaxTurnsError, McpManager, type McpServer, type McpServerConfig, type McpToolDefinition, type McpToolResult, type MemoryConfig, MemoryManager, MemoryStore, NoConsensus, NoopSpanManager, OpenAIEmbedder, OpenAIProvider, OpenAIResponsesProvider, type OutputGuardrail, type PendingDecision, type Provider, type ProviderAdapter, ProviderRegistry, type ProviderResponse, QuorumNotMet, type RaceOptions, type RecallOptions, RedisStore, type RememberOptions, type Result, type RetryPolicy, SQLiteStore, Session, type SessionOptions, type SpanHandle, type SpanManager, type SpawnOptions, SqliteVectorStore, type StateStore, type StreamChunk, type StreamEvent, type TelemetryConfig, TimeoutError, type Tool, type ToolCallMessage, type ToolConfig, ToolDenied, type ToolHooks, type TraceEvent, type VectorEntry, type VectorResult, type VectorStore, VerifyError, type VerifyOptions, type VoteOptions, type Workflow, type WorkflowConfig, WorkflowContext, type WorkflowContextInit, agent, createSpanManager, defineConfig, tool, workflow };