framework-agents 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2842 @@
+import { z } from 'zod';
+
+/**
+ * Content blocks — standard, provider-neutral message payload
+ * Standard message payload: text, reasoning, multimodal and tool-call blocks.
+ * `content` stays `string | ContentBlock[]`: strings for simple cases,
+ * blocks for multimodal / reasoning / tool-call payloads.
+ */
+declare const TextBlockSchema: z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "text";
+    text: string;
+}, {
+    type: "text";
+    text: string;
+}>;
+declare const ReasoningBlockSchema: z.ZodObject<{
+    type: z.ZodLiteral<"reasoning">;
+    reasoning: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "reasoning";
+    reasoning: string;
+}, {
+    type: "reasoning";
+    reasoning: string;
+}>;
+declare const ImageBlockSchema: z.ZodObject<{
+    type: z.ZodLiteral<"image">;
+    url: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodString>;
+    mimeType: z.ZodOptional<z.ZodString>;
+    fileId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "image";
+    url?: string | undefined;
+    data?: string | undefined;
+    mimeType?: string | undefined;
+    fileId?: string | undefined;
+}, {
+    type: "image";
+    url?: string | undefined;
+    data?: string | undefined;
+    mimeType?: string | undefined;
+    fileId?: string | undefined;
+}>;
+declare const AudioBlockSchema: z.ZodObject<{
+    type: z.ZodLiteral<"audio">;
+    url: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodString>;
+    mimeType: z.ZodOptional<z.ZodString>;
+    fileId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "audio";
+    url?: string | undefined;
+    data?: string | undefined;
+    mimeType?: string | undefined;
+    fileId?: string | undefined;
+}, {
+    type: "audio";
+    url?: string | undefined;
+    data?: string | undefined;
+    mimeType?: string | undefined;
+    fileId?: string | undefined;
+}>;
+declare const FileBlockSchema: z.ZodObject<{
+    type: z.ZodLiteral<"file">;
+    url: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodString>;
+    mimeType: z.ZodOptional<z.ZodString>;
+    fileId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "file";
+    url?: string | undefined;
+    data?: string | undefined;
+    mimeType?: string | undefined;
+    fileId?: string | undefined;
+}, {
+    type: "file";
+    url?: string | undefined;
+    data?: string | undefined;
+    mimeType?: string | undefined;
+    fileId?: string | undefined;
+}>;
+declare const ToolCallBlockSchema: z.ZodObject<{
+    type: z.ZodLiteral<"tool_call">;
+    id: z.ZodString;
+    name: z.ZodString;
+    args: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    type: "tool_call";
+    id: string;
+    name: string;
+    args?: unknown;
+}, {
+    type: "tool_call";
+    id: string;
+    name: string;
+    args?: unknown;
+}>;
+declare const NonStandardBlockSchema: z.ZodObject<{
+    type: z.ZodLiteral<"non_standard">;
+    value: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    type: "non_standard";
+    value?: unknown;
+}, {
+    type: "non_standard";
+    value?: unknown;
+}>;
+declare const ContentBlockSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "text";
+    text: string;
+}, {
+    type: "text";
+    text: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"reasoning">;
+    reasoning: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "reasoning";
+    reasoning: string;
+}, {
+    type: "reasoning";
+    reasoning: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"image">;
+    url: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodString>;
+    mimeType: z.ZodOptional<z.ZodString>;
+    fileId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "image";
+    url?: string | undefined;
+    data?: string | undefined;
+    mimeType?: string | undefined;
+    fileId?: string | undefined;
+}, {
+    type: "image";
+    url?: string | undefined;
+    data?: string | undefined;
+    mimeType?: string | undefined;
+    fileId?: string | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"audio">;
+    url: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodString>;
+    mimeType: z.ZodOptional<z.ZodString>;
+    fileId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "audio";
+    url?: string | undefined;
+    data?: string | undefined;
+    mimeType?: string | undefined;
+    fileId?: string | undefined;
+}, {
+    type: "audio";
+    url?: string | undefined;
+    data?: string | undefined;
+    mimeType?: string | undefined;
+    fileId?: string | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"file">;
+    url: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodString>;
+    mimeType: z.ZodOptional<z.ZodString>;
+    fileId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "file";
+    url?: string | undefined;
+    data?: string | undefined;
+    mimeType?: string | undefined;
+    fileId?: string | undefined;
+}, {
+    type: "file";
+    url?: string | undefined;
+    data?: string | undefined;
+    mimeType?: string | undefined;
+    fileId?: string | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"tool_call">;
+    id: z.ZodString;
+    name: z.ZodString;
+    args: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    type: "tool_call";
+    id: string;
+    name: string;
+    args?: unknown;
+}, {
+    type: "tool_call";
+    id: string;
+    name: string;
+    args?: unknown;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"non_standard">;
+    value: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    type: "non_standard";
+    value?: unknown;
+}, {
+    type: "non_standard";
+    value?: unknown;
+}>]>;
+type ContentBlock = z.infer<typeof ContentBlockSchema>;
+type TextBlock = z.infer<typeof TextBlockSchema>;
+type ReasoningBlock = z.infer<typeof ReasoningBlockSchema>;
+type ImageBlock = z.infer<typeof ImageBlockSchema>;
+/** Plain-text view of any content shape — what the model "reads". */
+declare function textOf(content: string | ContentBlock[]): string;
+/**
+ * Text for re-sending history to a provider: reasoning blocks are dropped —
+ * a model's own past thinking must not come back as ordinary assistant text
+ * (duplicated context, and Anthropic rejects thinking-as-text turns).
+ */
+declare function wireTextOf(content: string | ContentBlock[]): string;
+declare function hasImages(content: string | ContentBlock[]): boolean;
+/** Images in wire-ready form (url or base64 data). */
+declare function imagesOf(content: string | ContentBlock[]): {
+    url?: string;
+    data?: string;
+    mimeType?: string;
+}[];
+
+type Brand<T, B extends string> = T & {
+    readonly __brand: B;
+};
+type AgentId = Brand<string, "AgentId">;
+type RunId = Brand<string, "RunId">;
+type ToolName = Brand<string, "ToolName">;
+declare const ChatMessageSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    role: z.ZodEnum<["system", "user", "assistant", "tool"]>;
+    content: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "text";
+        text: string;
+    }, {
+        type: "text";
+        text: string;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"reasoning">;
+        reasoning: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "reasoning";
+        reasoning: string;
+    }, {
+        type: "reasoning";
+        reasoning: string;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"image">;
+        url: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodString>;
+        mimeType: z.ZodOptional<z.ZodString>;
+        fileId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "image";
+        url?: string | undefined;
+        data?: string | undefined;
+        mimeType?: string | undefined;
+        fileId?: string | undefined;
+    }, {
+        type: "image";
+        url?: string | undefined;
+        data?: string | undefined;
+        mimeType?: string | undefined;
+        fileId?: string | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"audio">;
+        url: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodString>;
+        mimeType: z.ZodOptional<z.ZodString>;
+        fileId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "audio";
+        url?: string | undefined;
+        data?: string | undefined;
+        mimeType?: string | undefined;
+        fileId?: string | undefined;
+    }, {
+        type: "audio";
+        url?: string | undefined;
+        data?: string | undefined;
+        mimeType?: string | undefined;
+        fileId?: string | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"file">;
+        url: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodString>;
+        mimeType: z.ZodOptional<z.ZodString>;
+        fileId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "file";
+        url?: string | undefined;
+        data?: string | undefined;
+        mimeType?: string | undefined;
+        fileId?: string | undefined;
+    }, {
+        type: "file";
+        url?: string | undefined;
+        data?: string | undefined;
+        mimeType?: string | undefined;
+        fileId?: string | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"tool_call">;
+        id: z.ZodString;
+        name: z.ZodString;
+        args: z.ZodUnknown;
+    }, "strip", z.ZodTypeAny, {
+        type: "tool_call";
+        id: string;
+        name: string;
+        args?: unknown;
+    }, {
+        type: "tool_call";
+        id: string;
+        name: string;
+        args?: unknown;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"non_standard">;
+        value: z.ZodUnknown;
+    }, "strip", z.ZodTypeAny, {
+        type: "non_standard";
+        value?: unknown;
+    }, {
+        type: "non_standard";
+        value?: unknown;
+    }>]>, "many">]>;
+    /** Provider user-identification; behavior varies, optional. */
+    name: z.ZodOptional<z.ZodString>;
+    toolCallId: z.ZodOptional<z.ZodString>;
+    toolName: z.ZodOptional<z.ZodString>;
+    /** Pinned messages survive conversation-manager trimming. */
+    pinned: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | ({
+        type: "text";
+        text: string;
+    } | {
+        type: "reasoning";
+        reasoning: string;
+    } | {
+        type: "image";
+        url?: string | undefined;
+        data?: string | undefined;
+        mimeType?: string | undefined;
+        fileId?: string | undefined;
+    } | {
+        type: "audio";
+        url?: string | undefined;
+        data?: string | undefined;
+        mimeType?: string | undefined;
+        fileId?: string | undefined;
+    } | {
+        type: "file";
+        url?: string | undefined;
+        data?: string | undefined;
+        mimeType?: string | undefined;
+        fileId?: string | undefined;
+    } | {
+        type: "tool_call";
+        id: string;
+        name: string;
+        args?: unknown;
+    } | {
+        type: "non_standard";
+        value?: unknown;
+    })[];
+    id?: string | undefined;
+    name?: string | undefined;
+    toolCallId?: string | undefined;
+    toolName?: string | undefined;
+    pinned?: boolean | undefined;
+}, {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | ({
+        type: "text";
+        text: string;
+    } | {
+        type: "reasoning";
+        reasoning: string;
+    } | {
+        type: "image";
+        url?: string | undefined;
+        data?: string | undefined;
+        mimeType?: string | undefined;
+        fileId?: string | undefined;
+    } | {
+        type: "audio";
+        url?: string | undefined;
+        data?: string | undefined;
+        mimeType?: string | undefined;
+        fileId?: string | undefined;
+    } | {
+        type: "file";
+        url?: string | undefined;
+        data?: string | undefined;
+        mimeType?: string | undefined;
+        fileId?: string | undefined;
+    } | {
+        type: "tool_call";
+        id: string;
+        name: string;
+        args?: unknown;
+    } | {
+        type: "non_standard";
+        value?: unknown;
+    })[];
+    id?: string | undefined;
+    name?: string | undefined;
+    toolCallId?: string | undefined;
+    toolName?: string | undefined;
+    pinned?: boolean | undefined;
+}>;
+interface ChatMessage {
+    id?: string;
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | ContentBlock[];
+    name?: string;
+    toolCallId?: string;
+    toolName?: string;
+    pinned?: boolean;
+}
+interface AgentResult {
+    text: string;
+    messages: ChatMessage[];
+    toolCalls: ExecutedToolCall[];
+    usage: TokenUsage;
+    /** Typed answer when the agent ran with `responseFormat`. */
+    structuredResponse?: unknown;
+    /** The invocation state object (same reference mutated during the run). */
+    invocationState?: Record<string, unknown>;
+}
+interface ExecutedToolCall {
+    id: string;
+    name: string;
+    args: unknown;
+    output: unknown;
+    /** Downstream-only data (never sent to the model). See Tool.toResult. */
+    artifact?: unknown;
+}
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    /**
+     * Reasoning/thinking tokens, when the provider reports them. A SUBSET of
+     * `outputTokens` on every supported provider — count for reporting, never
+     * add on top for budgets or cost.
+     */
+    reasoningTokens?: number;
+    /** USD cost, when a price is known (see models/pricing). Never guessed. */
+    costUsd?: number;
+}
+type Result<T, E = AgentError> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+declare class AgentError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    constructor(code: string, message: string, retryable?: boolean);
+}
+/** Factory helpers — stable ids, no class hierarchy. */
+declare function system(content: string | ContentBlock[]): ChatMessage;
+declare function user(content: string | ContentBlock[], opts?: {
+    id?: string;
+    name?: string;
+}): ChatMessage;
+declare function assistant(content: string | ContentBlock[]): ChatMessage;
+declare function toolResult(toolCallId: string, toolName: string, content: string | ContentBlock[]): ChatMessage;
+/** Serialize history for persistence (plain JSON-safe objects). */
+declare function serializeMessages(messages: ChatMessage[]): unknown[];
+/** Deserialize + validate history (e.g. resume from disk). Throws on bad shape. */
+declare function deserializeMessages(raw: unknown[]): ChatMessage[];
+
+declare const ConfigSchema: z.ZodObject<{
+    TOGETHER_API_KEY: z.ZodDefault<z.ZodString>;
+    TOGETHER_BASE_URL: z.ZodDefault<z.ZodString>;
+    /** Small chat default — one model, no tiers. */
+    TOGETHER_MODEL: z.ZodDefault<z.ZodString>;
+    OPENAI_BASE_URL: z.ZodDefault<z.ZodString>;
+    OPENAI_API_KEY: z.ZodDefault<z.ZodString>;
+    OPENAI_MODEL: z.ZodDefault<z.ZodString>;
+    ANTHROPIC_API_KEY: z.ZodDefault<z.ZodString>;
+    ANTHROPIC_BASE_URL: z.ZodDefault<z.ZodString>;
+    ANTHROPIC_MODEL: z.ZodDefault<z.ZodString>;
+    OLLAMA_BASE_URL: z.ZodDefault<z.ZodString>;
+    OLLAMA_MODEL: z.ZodDefault<z.ZodString>;
+    E2E_MODEL: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    TOGETHER_API_KEY: string;
+    TOGETHER_BASE_URL: string;
+    TOGETHER_MODEL: string;
+    OPENAI_BASE_URL: string;
+    OPENAI_API_KEY: string;
+    OPENAI_MODEL: string;
+    ANTHROPIC_API_KEY: string;
+    ANTHROPIC_BASE_URL: string;
+    ANTHROPIC_MODEL: string;
+    OLLAMA_BASE_URL: string;
+    OLLAMA_MODEL: string;
+    E2E_MODEL: string;
+}, {
+    TOGETHER_API_KEY?: string | undefined;
+    TOGETHER_BASE_URL?: string | undefined;
+    TOGETHER_MODEL?: string | undefined;
+    OPENAI_BASE_URL?: string | undefined;
+    OPENAI_API_KEY?: string | undefined;
+    OPENAI_MODEL?: string | undefined;
+    ANTHROPIC_API_KEY?: string | undefined;
+    ANTHROPIC_BASE_URL?: string | undefined;
+    ANTHROPIC_MODEL?: string | undefined;
+    OLLAMA_BASE_URL?: string | undefined;
+    OLLAMA_MODEL?: string | undefined;
+    E2E_MODEL?: string | undefined;
+}>;
+type FrameworkConfig = z.infer<typeof ConfigSchema> & {
+    /** Resolved provider settings: TogetherAI wins when its key is set. */
+    active: {
+        baseUrl: string;
+        apiKey: string;
+        model: string;
+        source: "together" | "openai";
+    };
+};
+declare function loadConfig(env?: NodeJS.ProcessEnv): FrameworkConfig;
+/** Test-only: clear cache so tests can pass custom env objects. */
+declare function __resetConfig(): void;
+
+/**
+ * Typed run events with independent projections.
+ * Consume via `for await (const e of agent.stream(input))`.
+ */
+type StreamEvent = {
+    type: "step";
+    step: number;
+} | {
+    type: "token";
+    delta: string;
+} | {
+    type: "thinking";
+    delta: string;
+} | {
+    type: "tool_call";
+    name: string;
+    args: unknown;
+} | {
+    type: "tool_result";
+    name: string;
+    output: unknown;
+} | {
+    type: "done";
+    text: string;
+};
+/** Collect a stream into buckets — handy for tests and simple UIs. */
+declare function collectStream(stream: AsyncGenerator<StreamEvent, AgentResult>): Promise<{
+    events: StreamEvent[];
+    result: AgentResult;
+}>;
+
+/**
+ * State in three lifetimes:
+ * - Conversation history: messages (model-visible), via Memory.
+ * - Agent state: validated JSON key-value store, NEVER sent to the model.
+ * - Invocation state: per-run data + request handle, shared by reference
+ *   across hooks and tools within one run, returned on the result.
+ */
+type InvocationState = Record<string, unknown>;
+/** Key-value store outside the model context. Tools + app logic read/write freely. */
+declare class AgentState {
+    private data;
+    constructor(initial?: Record<string, unknown>);
+    get<T = unknown>(key?: string): T | Record<string, unknown> | undefined;
+    set(key: string, value: unknown): void;
+    delete(key: string): void;
+    /** Plain-object copy for snapshots/persistence. */
+    toJSON(): Record<string, unknown>;
+    static fromJSON(raw: Record<string, unknown>): AgentState;
+}
+/** What tools receive: agent identity + state + per-run invocation state. */
+interface ToolContext {
+    agentName: string;
+    state: AgentState;
+    invocationState: InvocationState;
+}
+
+interface OpenAICompatibleOptions {
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+    temperature?: number;
+    maxTokens?: number;
+    /** Stream responses (SSE) so text + thinking tokens flow via callbacks. Default false. */
+    stream?: boolean;
+    /** fetch-compatible; injectable for tests. Defaults to global fetch. */
+    fetchFn?: typeof fetch;
+}
+/**
+ * Minimal OpenAI-compatible chat provider (OpenAI, TogetherAI, vLLM, etc.).
+ * POST {baseUrl}/chat/completions with tools; no SDK dependency.
+ * - Images: fail fast with MODEL_CAPABILITY when the model can't see.
+ * - Thinking: reasoning_content streams through onThinking (SSE when stream: true).
+ */
+declare class OpenAICompatibleProvider implements ModelProvider {
+    readonly id: string;
+    readonly capabilities: {
+        structuredOutput: boolean;
+        streaming: boolean;
+    };
+    private opts;
+    constructor(opts: OpenAICompatibleOptions);
+    complete(options: CompleteOptions): Promise<ModelCompletion>;
+    private readJson;
+    /** SSE: `data: {...}` lines; delta.content -> onToken, delta.reasoning_content -> onThinking. */
+    private readStream;
+}
+/** Build a provider from env config (TogetherAI preferred when key present). */
+declare function providerFromEnv(active: {
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+}, extra?: Partial<OpenAICompatibleOptions>): OpenAICompatibleProvider;
+
+/**
+ * Model capability registry — researched defaults live here so users never
+ * pick tiers. Full per-model research (vision, tools, reasoning, context
+ * limits) lands later; until then: explicit allowlist + fail-fast error.
+ */
+type ModelCapability = "vision" | "tools" | "reasoning-stream";
+declare function supportsVision(modelId: string): boolean;
+/** Throw AgentError(MODEL_CAPABILITY) when input needs vision the model lacks. */
+declare function assertCanHandle(modelId: string, needsVision: boolean): void;
+
+/**
+ * Resolve `provider:model` strings to a configured provider.
+ * - `together:<id>` / bare `<id>` → TogetherAI (TOGETHER_API_KEY)
+ * - `openai:<id>` → OpenAI (OPENAI_API_KEY)
+ * - `anthropic:<id>` → Anthropic native API (ANTHROPIC_API_KEY)
+ * - `ollama:<id>` → local Ollama (no key; OLLAMA_BASE_URL or localhost:11434)
+ * - `custom:<id>` + baseUrl/apiKey → any OpenAI-compatible endpoint
+ */
+declare function initChatModel(spec: string, opts?: {
+    apiKey?: string;
+    baseUrl?: string;
+    temperature?: number;
+    maxTokens?: number;
+    stream?: boolean;
+    thinkingBudget?: number;
+}): ModelProvider;
+
+interface AnthropicOptions {
+    apiKey: string;
+    model: string;
+    baseUrl?: string;
+    maxTokens?: number;
+    temperature?: number;
+    /** Extended thinking budget (tokens). Enables thinking blocks. */
+    thinkingBudget?: number;
+    stream?: boolean;
+    fetchFn?: typeof fetch;
+}
+/**
+ * Native Anthropic Messages API (fetch-based, no SDK).
+ * - tools become `tools` with input_schema; tool results become tool_result blocks
+ * - thinking blocks stream/return via onThinking
+ * - no native json_schema mode: capabilities.structuredOutput is false,
+ *   so `auto` responseFormat correctly falls back to the tool strategy
+ */
+declare class AnthropicProvider implements ModelProvider {
+    readonly id: string;
+    readonly capabilities: {
+        structuredOutput: boolean;
+        streaming: boolean;
+    };
+    private opts;
+    constructor(opts: AnthropicOptions);
+    complete(options: CompleteOptions): Promise<ModelCompletion>;
+    private toCompletion;
+    private readJson;
+    private readStream;
+}
+
+interface OllamaOptions {
+    model: string;
+    /** Defaults to local Ollama. No key needed. */
+    baseUrl?: string;
+    temperature?: number;
+    maxTokens?: number;
+    stream?: boolean;
+    fetchFn?: typeof fetch;
+}
+/**
+ * Local-first Ollama provider via its OpenAI-compatible endpoint.
+ * No API key, no account, no network beyond localhost. Tool support
+ * depends on the model (qwen2.5, llama3.1+ work well).
+ * structuredOutput stays false → `auto` format uses the tool strategy.
+ */
+declare class OllamaProvider extends OpenAICompatibleProvider {
+    readonly id: string;
+    readonly capabilities: {
+        structuredOutput: boolean;
+        streaming: boolean;
+    };
+    constructor(opts: OllamaOptions);
+}
+declare function ollama(opts: OllamaOptions): OllamaProvider;
+
+/**
+ * Per-model prices (USD per 1M tokens). Researched defaults — verify against
+ * your provider bill: cloud prices change, and dedicated/self-hosted
+ * endpoints (Ollama, vLLM) cost $0 in API terms.
+ *
+ * Why a table: TogetherAI/OpenAI-compatible and Anthropic usage payloads
+ * carry token counts ONLY (no cost field). Cost is always computed
+ * client-side as usage × price. (OpenRouter is the exception — it returns
+ * cost directly; nothing to do there.)
+ */
+interface ModelPrice {
+    inputPerMillion: number;
+    outputPerMillion: number;
+}
+/** Look up a price by bare model id (provider prefixes like `openai:`/`ollama:` are stripped). */
+declare function priceFor(modelId: string): ModelPrice | undefined;
+/**
+ * USD cost for usage; unknown models return undefined (never a misleading zero).
+ * `outputTokens` already includes reasoning tokens on every supported provider
+ * (OpenAI: reasoning_tokens ⊂ completion_tokens; Anthropic: thinking ⊂ output_tokens),
+ * so they are billed at the output rate with no extra addition.
+ */
+declare function usageCost(usage: TokenUsage, modelId: string, override?: ModelPrice): number | undefined;
+
+interface ToolCallRequest {
+    /** Provider tool-call id; generated when the provider omits it. */
+    id: string;
+    name: string;
+    args: unknown;
+}
+interface ModelCompletion {
+    text: string;
+    /** Thinking/reasoning trace, when the provider exposes it. */
+    thinking?: string;
+    toolCalls: ToolCallRequest[];
+    usage: TokenUsage;
+    /**
+     * Provider stop reason when reported ("stop", "length"/"max_tokens",
+     * "tool_calls", ...). Consumers can detect truncation; a TOTAL truncation
+     * (no content at all) throws MODEL_ERROR at the provider instead.
+     */
+    finishReason?: string;
+}
+interface ResponseFormatWire {
+    name: string;
+    schema: Record<string, unknown>;
+    strict?: boolean;
+}
+interface CompleteOptions {
+    messages: ChatMessage[];
+    /** Tool metadata; `parametersSchema` (JSON Schema) lets models call with real args — omit only for zero-arg tools. */
+    tools: {
+        name: string;
+        description: string;
+        parametersSchema?: Record<string, unknown>;
+    }[];
+    /** Native structured output (OpenAI `response_format`). Honored when the provider supports it. */
+    responseFormat?: ResponseFormatWire;
+    /** Streamed text deltas (non-thinking). */
+    onToken?: (delta: string) => void;
+    /** Streamed thinking/reasoning deltas (reasoning_content). */
+    onThinking?: (delta: string) => void;
+    /** Aborts the in-flight provider request (fetch). */
+    signal?: AbortSignal;
+}
+/** Provider abstraction — implement OpenAI/Anthropic/etc. behind this. */
+interface ModelProvider {
+    readonly id: string;
+    readonly capabilities?: {
+        structuredOutput?: boolean;
+        vision?: boolean;
+        streaming?: boolean;
+    };
+    complete(options: CompleteOptions): Promise<ModelCompletion>;
+}
+/** Deterministic mock for tests/examples — no network. */
+declare class MockModelProvider implements ModelProvider {
+    readonly id = "mock";
+    readonly capabilities: {
+        structuredOutput: boolean;
+        streaming: boolean;
+    };
+    private calls;
+    complete(_options: CompleteOptions): Promise<ModelCompletion>;
+}
+
+interface ToolResult {
+    /** Model-visible content (string or blocks). */
+    content: string | ContentBlock[];
+    /** Downstream-only data — stored on the call record, never sent to the model. */
+    artifact?: unknown;
+}
+interface Tool<TArgs = any, TOutput = any> {
+    name: string;
+    description: string;
+    schema: z.ZodType<TArgs>;
+    /** Optional second arg receives ToolContext (state + invocationState). */
+    execute: (args: TArgs, ctx?: ToolContext) => Promise<TOutput>;
+    /**
+     * Split raw output into model-visible content + downstream artifact.
+     * Default: JSON/string content, no artifact. Override to keep raw payloads
+     * (retrieval metadata, debug blobs) out of the model's context.
+     */
+    toResult?: (output: any) => ToolResult;
+}
+declare function defaultToResult(output: unknown): ToolResult;
+declare function defineTool<TArgs, TOutput>(tool: Tool<TArgs, TOutput>): Tool<TArgs, TOutput>;
+/** Validating registry — single place tools are looked up + arg-checked. */
+declare class ToolRegistry {
+    private tools;
+    register(tool: Tool): this;
+    get(name: string): Tool | undefined;
+    list(): Tool[];
+    call<T>(name: string, rawArgs: unknown): Promise<T>;
+}
+
+/**
+ * Middleware — control the agent loop without forking it.
+ *
+ * Execution order:
+ * - beforeModel / beforeTool: registration order
+ * - afterModel / afterTool: REVERSE order
+ * - wrapModel / aroundTool: nested, first registered = outermost
+ */
+interface HookContext {
+    step: number;
+    /** Per-run data, shared by reference (never sent to the model). */
+    invocationState?: InvocationState;
+}
+interface ModelRequest {
+    messages: ChatMessage[];
+    tools: {
+        name: string;
+        description: string;
+        parametersSchema?: Record<string, unknown>;
+    }[];
+    responseFormat?: ResponseFormatWire;
+}
+interface ToolCallRef {
+    name: string;
+    args: unknown;
+}
+interface AgentMiddleware {
+    name: string;
+    /** Tools contributed by this middleware (merged into the agent's tool list). */
+    tools?: Tool[];
+    beforeModel?: (req: ModelRequest, ctx: HookContext) => Promise<ModelRequest | undefined> | ModelRequest | undefined;
+    wrapModel?: (req: ModelRequest, next: (req: ModelRequest) => Promise<ModelCompletion>, ctx: HookContext) => Promise<ModelCompletion>;
+    afterModel?: (res: ModelCompletion, req: ModelRequest, ctx: HookContext) => Promise<ModelCompletion | undefined> | ModelCompletion | undefined;
+    beforeTool?: (call: ToolCallRef, ctx: HookContext) => Promise<ToolCallRef | undefined> | ToolCallRef | undefined;
+    aroundTool?: (call: ToolCallRef, next: () => Promise<unknown>, ctx: HookContext) => Promise<unknown>;
+    afterTool?: (call: ToolCallRef, output: unknown, ctx: HookContext) => Promise<unknown> | unknown;
+}
+/** Identity factory — documents intent and locks the type. */
+declare function createMiddleware(m: AgentMiddleware): AgentMiddleware;
+/** Thrown (usually by approval middleware) to skip execution with feedback for the model. */
+declare class ToolRejection extends Error {
+    readonly feedback: string;
+    constructor(feedback: string);
+}
+/** Mark an error retryable (true) or fatal (false). Shape and type are untouched. */
+declare function stampRetryable<T extends Error>(err: T, retryable: boolean): T;
+/** Read a verdict: true/false, or undefined when never marked. AgentError maps to its flag. */
+declare function getRetryable(err: unknown): boolean | undefined;
+interface BackoffOptions {
+    maxRetries?: number;
+    initialDelayMs?: number;
+    backoffFactor?: number;
+    maxDelayMs?: number;
+    jitter?: boolean;
+}
+declare function backoffDelayMs(attempt: number, opts: Required<Omit<BackoffOptions, "maxRetries">>): number;
+type RetryFilter = ((error: Error) => boolean) | (new (...args: never[]) => Error)[];
+/** Cap model calls per run; exceeded -> AgentError(BUDGET_EXCEEDED). Stateless (uses step). */
+declare function modelCallLimit(maxCalls: number): AgentMiddleware;
+/** Retry failing tool executions with exponential backoff. AgentErrors pass through untouched. */
+declare function toolRetry(opts?: {
+    attempts?: number;
+    backoffMs?: number;
+}): AgentMiddleware;
+interface RetryMiddlewareOptions extends BackoffOptions {
+    retryOn?: RetryFilter;
+    onFailure?: "error" | "continue" | ((error: Error) => string);
+    /** Limit retries to these tool names (tool retry only). */
+    tools?: string[];
+}
+/**
+ * Full tool retry: exponential backoff + jitter, error-class filtering,
+ * per-tool scoping, and exhausted-failure behavior (continue as tool
+ * message vs rethrow). Honors stampRetryable verdicts.
+ */
+declare function toolRetryMiddleware(opts?: RetryMiddlewareOptions): AgentMiddleware;
+/**
+ * Model retry with the same backoff/filter/onFailure semantics.
+ * onFailure "continue" synthesizes an empty-text completion so the loop ends gracefully.
+ */
+declare function modelRetryMiddleware(opts?: RetryMiddlewareOptions): AgentMiddleware;
+/** Fall back across providers when the primary model fails (first success wins). */
+declare function modelFallbackMiddleware(...fallbacks: ModelProvider[]): AgentMiddleware;
+/** Per-run tool-call budgets (global + per-tool). Exceeded calls are blocked with feedback or throw. */
+declare function toolCallLimitMiddleware(opts: {
+    toolName?: string;
+    runLimit?: number;
+    exitBehavior?: "continue" | "error";
+}): AgentMiddleware;
+type HitlDecision = "approve" | {
+    edit: unknown;
+} | {
+    reject: string;
+} | {
+    suspend: true;
+};
+/** Thrown to suspend a run for human review. Persisted by checkpoint when checkpointer+threadId are set. */
+declare class HitlInterrupt extends Error {
+    readonly interruptId: string;
+    readonly tool: string;
+    readonly args: unknown;
+    constructor(interruptId: string, tool: string, args: unknown);
+}
+/** Stable key binding a decision to one tool call (used across suspend/resume). */
+declare function hitlKey(tool: string, args: unknown): string;
+interface HitlDecideRequest {
+    name: string;
+    args: unknown;
+    allowed: ("approve" | "edit" | "reject")[];
+    interruptId: string;
+}
+/**
+ * Human-in-the-loop: pause tool execution for approval/edit/reject.
+ * Single-process version — `decide` is called inline (CLI prompt, API
+ * handler, test stub). Checkpointed resume lands with durable runtime (P3).
+ */
+declare function humanInTheLoopMiddleware(opts: {
+    interruptOn: Record<string, boolean | {
+        allowedDecisions?: ("approve" | "edit" | "reject")[];
+    }>;
+    /** Inline decider. May return { suspend: true } to checkpoint + throw HitlInterrupt. Omit to always suspend. */
+    decide?: (req: HitlDecideRequest) => Promise<HitlDecision> | HitlDecision;
+}): AgentMiddleware;
+interface PIIMatch {
+    text: string;
+    start: number;
+    end: number;
+}
+type PIIDetector = RegExp | string | ((content: string) => PIIMatch[]);
+type PIIStrategy = "block" | "redact" | "mask" | "hash";
+/** PII detection with redact/mask/hash/block strategies across input, output, and tool results. */
+declare function piiMiddleware(piiType: string, opts?: {
+    strategy?: PIIStrategy;
+    detector?: PIIDetector;
+    applyToInput?: boolean;
+    applyToOutput?: boolean;
+    applyToToolResults?: boolean;
+}): AgentMiddleware;
+/**
+ * Auto-summarize history when estimated tokens pass `triggerTokens`,
+ * keeping the newest `keepMessages`. Text-oriented: summarized-away
+ * multimodal blocks survive only as prose (store media externally and
+ * pass URLs if images must persist).
+ */
+declare function summarizationMiddleware(opts: {
+    model: ModelProvider;
+    triggerTokens: number;
+    keepMessages?: number;
+    summaryPrefix?: string;
+    summarize?: (messages: ChatMessage[]) => Promise<string>;
+}): AgentMiddleware;
+interface ClearToolUsesOptions {
+    triggerTokens?: number;
+    keep?: number;
+    clearToolInputs?: boolean;
+    excludeTools?: string[];
+    placeholder?: string;
+}
+/** Clear older tool outputs past a token budget; newest `keep` results survive. */
+declare class ClearToolUsesEdit {
+    private opts;
+    constructor(opts?: ClearToolUsesOptions);
+    apply(messages: ChatMessage[]): ChatMessage[];
+    clearInputs(messages: ChatMessage[]): ChatMessage[];
+}
+declare function contextEditingMiddleware(opts: {
+    edits?: ClearToolUsesEdit[];
+}): AgentMiddleware;
+interface TodoItem {
+    content: string;
+    status: "pending" | "active" | "completed";
+}
+/** Task planning: contributes a `write_todos` tool and tracks state per run. */
+declare function todoListMiddleware(): AgentMiddleware & {
+    listTodos(): TodoItem[];
+};
+/** Narrow 10+ tools to the relevant few before the main model call. */
+declare function llmToolSelectorMiddleware(opts: {
+    model: ModelProvider;
+    maxTools?: number;
+    alwaysInclude?: string[];
+    systemPrompt?: string;
+}): AgentMiddleware;
+/** Emulate tool execution with an LLM — testing/prototyping without side effects. */
+declare function toolEmulatorMiddleware(opts?: {
+    tools?: string[];
+    model?: ModelProvider;
+}): AgentMiddleware;
+/** ls/read_file/write_file/edit_file scoped to `root` (escapes rejected). */
+declare function filesystemTools(root: string): Tool[];
+declare function filesystemMiddleware(opts: {
+    root: string;
+}): AgentMiddleware;
+/**
+ * Spawn named subagents via a `task` tool — isolates context so the
+ * supervisor stays clean while the subagent goes deep.
+ */
+declare function createSubAgentMiddleware(opts: {
+    model: ModelProvider;
+    subagents: {
+        name: string;
+        description: string;
+        systemPrompt?: string;
+        tools?: Tool[];
+    }[];
+}): AgentMiddleware;
+
+/**
+ * Conversation managers keep history within context limits.
+ * - apply(): after-run management (before memory.save).
+ * - beforeModel(): per-turn management inside the loop (sliding window).
+ * - reduce(): explicit shrink (overflow recovery / proactive triggers).
+ * Pinned messages are never removed. Tool/assistant-tool_call pairs are
+ * never orphaned: trimming drops leading dangling messages.
+ */
+interface ConversationManager {
+    readonly name: string;
+    /** Messages removed so far (lets session loading skip efficiently). */
+    removedCount: number;
+    apply(messages: ChatMessage[]): ChatMessage[] | Promise<ChatMessage[]>;
+    reduce(messages: ChatMessage[]): ChatMessage[] | Promise<ChatMessage[]>;
+    beforeModel?(messages: ChatMessage[], step: number): ChatMessage[] | Promise<ChatMessage[]>;
+}
+/** Drop leading messages that lost their pair (tool head, call-only assistant head). */
+declare function trimDangling(messages: ChatMessage[]): ChatMessage[];
+declare function messageTokens(m: ChatMessage): number;
+declare function historyTokens(messages: ChatMessage[]): number;
+/** Keeps full history. Pass explicitly to disable the default sliding window. */
+declare class NullConversationManager implements ConversationManager {
+    readonly name = "null";
+    removedCount: number;
+    apply(messages: ChatMessage[]): ChatMessage[];
+    reduce(messages: ChatMessage[]): ChatMessage[];
+}
+interface SlidingWindowOptions {
+    /** Max messages kept (excluding pinned). Default 40. */
+    windowSize?: number;
+    /** Permanently protect the first N messages. Default 0. */
+    pinFirst?: number;
+    /** Manage before every model call (true) or every N calls. Default false (after-run only). */
+    perTurn?: boolean | number;
+}
+declare class SlidingWindowConversationManager implements ConversationManager {
+    readonly name = "sliding-window";
+    removedCount: number;
+    private windowSize;
+    private pinFirst;
+    private perTurn;
+    constructor(opts?: SlidingWindowOptions);
+    private pin;
+    private trim;
+    apply(messages: ChatMessage[]): ChatMessage[];
+    reduce(messages: ChatMessage[]): ChatMessage[];
+    beforeModel(messages: ChatMessage[], step: number): ChatMessage[];
+}
+interface SummarizingOptions {
+    /** Fraction of oldest messages to summarize away (0.1–0.8). Default 0.3. */
+    summaryRatio?: number;
+    /** Newest messages always kept. Default 10. */
+    preserveRecent?: number;
+    pinFirst?: number;
+    summarizer?: (messages: ChatMessage[]) => Promise<string>;
+    /** Model used for summaries when no `summarizer` fn is given. */
+    model?: ModelProvider;
+    summaryPrefix?: string;
+}
+declare class SummarizingConversationManager implements ConversationManager {
+    readonly name = "summarizing";
+    removedCount: number;
+    private ratio;
+    private preserveRecent;
+    private pinFirst;
+    private summarizer?;
+    private model?;
+    private summaryPrefix;
+    /** Set when the last apply() summarized (tests/UI can assert on it). */
+    lastSummary?: string;
+    constructor(opts?: SummarizingOptions);
+    private summarizable;
+    private summarize;
+    apply(messages: ChatMessage[]): Promise<ChatMessage[]>;
+    reduce(messages: ChatMessage[]): ChatMessage[];
+}
+
+/**
+ * Local-first durability: file checkpointer + file locks. No services,
+ * no third-party deps. Checkpointed HITL resume works fully offline.
+ */
+interface ThreadCheckpoint {
+    threadId: string;
+    savedAt: string;
+    messages: ChatMessage[];
+    state: Record<string, unknown>;
+    pending: {
+        interruptId: string;
+        tool: string;
+        args: unknown;
+    }[];
+}
+interface Checkpointer {
+    save(threadId: string, checkpoint: Omit<ThreadCheckpoint, "threadId" | "savedAt">): Promise<void>;
+    load(threadId: string): Promise<ThreadCheckpoint | undefined>;
+    delete(threadId: string): Promise<void>;
+}
+/**
+ * Exclusive local lock via O_EXCL file creation. Stale locks (older than
+ * staleMs) are reclaimed. Single-machine correctness; distributed locking
+ * is explicitly out of scope (see roadmap P3).
+ */
+declare function withFileLock<T>(lockPath: string, fn: () => Promise<T>, opts?: {
+    staleMs?: number;
+}): Promise<T>;
+/** JSON-file checkpointer: <root>/threads/<threadId>/checkpoint.json, lock-guarded. */
+declare class FileCheckpointer implements Checkpointer {
+    private root;
+    constructor(root: string);
+    /** threadId lands in a filesystem path — keep it a single safe directory name. */
+    private threadDir;
+    private file;
+    private lock;
+    save(threadId: string, checkpoint: Omit<ThreadCheckpoint, "threadId" | "savedAt">): Promise<void>;
+    load(threadId: string): Promise<ThreadCheckpoint | undefined>;
+    delete(threadId: string): Promise<void>;
+}
+
+/**
+ * Sessions: persist agent state + history across restarts.
+ * - Storage: byte-moving backends (memory / local files).
+ * - SessionManager: latest snapshot + immutable checkpoints (UUID ids).
+ * - Agent snapshots: manual take/load with field selection + appData.
+ */
+interface Storage {
+    read(key: string): Promise<string | undefined>;
+    write(key: string, value: string): Promise<void>;
+    deletePrefix(prefix: string): Promise<void>;
+    list(prefix: string): Promise<string[]>;
+}
+declare class InMemoryStorage implements Storage {
+    private data;
+    read(key: string): Promise<string | undefined>;
+    write(key: string, value: string): Promise<void>;
+    deletePrefix(prefix: string): Promise<void>;
+    list(prefix: string): Promise<string[]>;
+}
+declare class LocalFileStorage implements Storage {
+    private root;
+    constructor(root: string);
+    private path;
+    read(key: string): Promise<string | undefined>;
+    write(key: string, value: string): Promise<void>;
+    deletePrefix(prefix: string): Promise<void>;
+    list(prefix: string): Promise<string[]>;
+}
+interface SnapshotData {
+    messages?: ChatMessage[];
+    state?: Record<string, unknown>;
+    systemPrompt?: string;
+}
+interface Snapshot {
+    id: string;
+    createdAt: string;
+    data: SnapshotData;
+    appData?: Record<string, unknown>;
+}
+type SnapshotField = "messages" | "state" | "systemPrompt";
+interface TakeSnapshotOptions {
+    /** Preset bundle. Currently only "session" (messages + state). */
+    preset?: "session";
+    include?: SnapshotField[];
+    exclude?: SnapshotField[];
+    appData?: Record<string, unknown>;
+}
+declare function selectSnapshotFields(full: Required<Pick<SnapshotData, "messages" | "state">> & Pick<SnapshotData, "systemPrompt">, opts?: TakeSnapshotOptions): SnapshotData;
+interface SessionManagerOptions {
+    sessionId?: string;
+    storage: Storage;
+    agentId?: string;
+}
+declare class SessionManager {
+    readonly sessionId: string;
+    readonly agentId: string;
+    private storage;
+    constructor(opts: SessionManagerOptions);
+    private scope;
+    saveLatest(data: SnapshotData): Promise<void>;
+    loadLatest(): Promise<SnapshotData | undefined>;
+    /** Immutable checkpoint; returns its id. */
+    saveSnapshot(data: SnapshotData, appData?: Record<string, unknown>): Promise<string>;
+    listSnapshotIds(): Promise<string[]>;
+    restoreSnapshot(id: string): Promise<Snapshot | undefined>;
+    deleteSession(): Promise<void>;
+}
+
+/**
+ * Structured output — typed agent results instead of parsed prose.
+ * Two strategies:
+ * - provider: native `response_format` (OpenAI-compatible APIs). Most reliable.
+ * - tool: synthetic `__structured_response` tool; validation errors return as
+ *   tool messages so the model self-repairs within maxSteps.
+ */
+type ResponseStrategy = "auto" | "provider" | "tool";
+interface ResponseFormat<T = unknown> {
+    schema: z.ZodType<T>;
+    /** Function/tool name. Default: "structured_response". */
+    name?: string;
+    strategy?: ResponseStrategy;
+    /** Tool message content on success (tool strategy). */
+    toolMessageContent?: string;
+    /** Validation retries before STRUCTURED_NO_MATCH (tool strategy). Default 2. */
+    maxAttempts?: number;
+}
+declare function toolStrategy<T>(schema: z.ZodType<T>, opts?: Omit<ResponseFormat<T>, "schema" | "strategy">): ResponseFormat<T>;
+declare function providerStrategy<T>(schema: z.ZodType<T>, opts?: Omit<ResponseFormat<T>, "schema" | "strategy">): ResponseFormat<T>;
+declare function responseFormatName<T>(format: ResponseFormat<T>): string;
+declare function responseFormatJsonSchema<T>(format: ResponseFormat<T>): Record<string, unknown>;
+/** Validate raw model output; throws AgentError STRUCTURED_INVALID (retryable) on mismatch. */
+declare function parseStructured<T>(format: ResponseFormat<T>, raw: unknown): T;
+
+interface Memory {
+    load(): Promise<ChatMessage[]>;
+    save(messages: ChatMessage[]): Promise<void>;
+    clear(): Promise<void>;
+}
+declare class InMemoryMemory implements Memory {
+    private messages;
+    private maxMessages;
+    constructor(maxMessages?: number);
+    load(): Promise<ChatMessage[]>;
+    save(messages: ChatMessage[]): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * File-backed JSON memory: same windowing as in-memory, persisted per
+ * write to `<dir>/memory.json`. Crash-safe enough for local-first use
+ * (write-then-rename atomicity, validated reload).
+ */
+declare class FileMemory implements Memory {
+    private cache?;
+    private file;
+    private maxMessages;
+    constructor(dir: string, maxMessages?: number);
+    private readAll;
+    private flush;
+    load(): Promise<ChatMessage[]>;
+    save(messages: ChatMessage[]): Promise<void>;
+    clear(): Promise<void>;
+}
+
+interface StepEvent {
+    step: number;
+    messages: ChatMessage[];
+}
+interface ToolCallEvent {
+    tool: string;
+    args: unknown;
+}
+interface ToolResultEvent {
+    tool: string;
+    output: unknown;
+}
+interface DoneEvent {
+    text: string;
+    toolCalls: AgentResult["toolCalls"];
+}
+/** Observability hooks — plug logger/tracer here, keep core dependency-free. */
+interface AgentEvents {
+    onStep?: (e: StepEvent) => void;
+    onToolCall?: (e: ToolCallEvent) => void;
+    onToolResult?: (e: ToolResultEvent) => void;
+    onDone?: (e: DoneEvent) => void;
+    /** Streamed text deltas. */
+    onToken?: (delta: string) => void;
+    /** Streamed thinking/reasoning deltas. */
+    onThinking?: (delta: string) => void;
+}
+/** Minimal ANSI colors, dependency-free. Honors NO_COLOR and non-TTY. */
+declare function supportsColor(): boolean;
+interface ConsoleEventsOptions {
+    prefix?: string;
+    /** Force colors on/off. Default: auto (TTY without NO_COLOR). */
+    colors?: boolean;
+}
+declare function consoleEvents(prefix?: string, opts?: ConsoleEventsOptions): AgentEvents;
+declare function consoleEvents(opts: ConsoleEventsOptions): AgentEvents;
+/** Red error line for failures (pairs with consoleEvents). */
+declare function logError(prefix: string, err: unknown, colors?: boolean): void;
+
+type OutputVersion = "v0" | "v1";
+interface AgentOptions {
+    name?: string;
+    /** One-line specialty, used by the router menu. */
+    description?: string;
+    systemPrompt?: string;
+    model: ModelProvider;
+    tools?: Tool[];
+    memory?: Memory;
+    maxSteps?: number;
+    /** Max tool executions per run; exceeded -> AgentError(BUDGET_EXCEEDED). Default: unlimited. */
+    maxToolCalls?: number;
+    /** Token/cost/deadline budgets enforced after every model call. */
+    budgets?: TokenBudgets;
+    /**
+     * Output version. v0: assistant messages carry plain text (thinking streams
+     * via events only). v1: thinking is also stored as `reasoning` blocks.
+     */
+    outputVersion?: OutputVersion;
+    /** Typed final answer (tool or provider strategy). Sets `structuredResponse` on the result. */
+    responseFormat?: ResponseFormat;
+    /** Middleware hooks (before/after model + tool). Run in order. */
+    middleware?: AgentMiddleware[];
+    /** Conversation history: seed prior messages to continue a conversation. */
+    initialMessages?: ChatMessage[];
+    /** Agent key-value state (never sent to the model). */
+    state?: Record<string, unknown> | AgentState;
+    /** History management. Default: NullConversationManager (keep everything; memory still windows). */
+    conversationManager?: ConversationManager;
+    /** Persist state + history across restarts. Restored on first run, saved after each run. */
+    sessionManager?: SessionManager;
+    events?: AgentEvents;
+}
+interface TimelineEntry {
+    rev: number;
+    kind: "run" | "edit" | "branch" | "resume" | "snapshot";
+    label?: string;
+    at: string;
+}
+interface TokenBudgets {
+    /** Total (input + output + reasoning) tokens per run. */
+    maxTokens?: number;
+    /** USD cap per run. Needs a known price (table lookup or `prices`) — never guessed. */
+    maxCostUsd?: number;
+    /** Price override when the model is missing from the pricing table. */
+    prices?: ModelPrice;
+    /** Wall-clock deadline per run. */
+    deadlineMs?: number;
+}
+interface RunOptions {
+    signal?: AbortSignal;
+    /** Per-run data: shared by reference across hooks/tools, returned on the result, never sent to the model. */
+    invocationState?: InvocationState;
+    /** Checkpointed HITL: persist + resume human approvals locally. */
+    checkpointer?: Checkpointer;
+    threadId?: string;
+}
+/**
+ * Minimal ReAct-style loop:
+ * 1. load memory -> messages
+ * 2. loop: model.complete -> tool calls -> execute -> append
+ * 3. save memory, return AgentResult
+ *
+ * `run()` drains `stream()`; both fire `events` hooks identically.
+ */
+declare class Agent {
+    private options;
+    private seeded;
+    private restored;
+    private lastMessages;
+    private revisions;
+    readonly agentState: AgentState;
+    private instanceSessionId?;
+    constructor(options: AgentOptions);
+    /** Public identity for orchestration menus and logs. */
+    get name(): string;
+    get description(): string;
+    get model(): ModelProvider;
+    /** Member tools (copy) — introspection for orchestration/menus. */
+    get tools(): Tool[];
+    /**
+     * Clone with extra tools. Memory, session, and state are NOT carried over
+     * (fresh per clone); model, tools, middleware, and formats are shared.
+     * Used by coordinators (swarm handoffs) that inject control tools.
+     */
+    withTools(...extra: Tool[]): Agent;
+    /** Key-value state (never sent to the model). */
+    get state(): AgentState;
+    /** Session handle: the manager's id, or a generated per-instance id. */
+    get sessionId(): string;
+    /** Full conversation history from the last run (system + memory + new turns). */
+    get messages(): ChatMessage[];
+    /** Version timeline: runs, edits, branches, resumes (append-only). */
+    get timeline(): TimelineEntry[];
+    private record;
+    /**
+     * Edit a message in the current history (by id or index) and keep the
+     * version in the timeline. History + memory stay in sync.
+     */
+    editMessage(idOrIndex: string | number, content: string | ContentBlock[]): Promise<ChatMessage>;
+    /**
+     * Branch the current history into an independent agent. Model, tools,
+     * middleware, and formats are shared; state is copied; memory is fresh
+     * (seeded with this history); sessions are NOT carried over (to avoid
+     * double-persist collisions). Both timelines record the branch.
+     */
+    branch(label: string, overrides?: Partial<AgentOptions>): Promise<Agent>;
+    /**
+     * Pause mid-conversation: persist history + state under threadId without
+     * needing an interrupt. Pair with resume() (empty decisions continue).
+     */
+    pause(threadId: string, opts: {
+        checkpointer: Checkpointer;
+    }): Promise<{
+        threadId: string;
+        messages: number;
+    }>;
+    /** Manual checkpoint: messages + state (+ system prompt on request) + appData. */
+    takeSnapshot(opts?: TakeSnapshotOptions): Snapshot;
+    /** Restore fields present in the snapshot; absent fields keep current values. */
+    loadSnapshot(snapshot: Snapshot): Promise<void>;
+    /**
+     * Resume a suspended run: restores the checkpoint, seeds human decisions,
+     * and continues the loop without new input. Decisions are keyed by
+     * `hitlKey(tool, args)` for an exact match, or by bare tool name to cover
+     * every re-issued call of that tool (models re-issue with regenerated arg
+     * text, so exact keys alone would never converge).
+     */
+    resume(threadId: string, decisions: Record<string, HitlDecision> | undefined, opts: {
+        checkpointer: Checkpointer;
+    } & RunOptions): Promise<AgentResult>;
+    private buildRuntime;
+    /** Continue the loop from restored history (no new user message). */
+    private iterateContinuation;
+    run(input: string | ContentBlock[], signal?: AbortSignal): Promise<AgentResult>;
+    run(input: string | ContentBlock[], opts?: RunOptions): Promise<AgentResult>;
+    stream(input: string | ContentBlock[], signal?: AbortSignal, invocationState?: InvocationState): AsyncGenerator<StreamEvent, AgentResult>;
+    stream(input: string | ContentBlock[], opts?: RunOptions): AsyncGenerator<StreamEvent, AgentResult>;
+    private iterate;
+    private runLoop;
+}
+
+/**
+ * Swarm: autonomous handoffs across specialists, no fixed path.
+ * Each member gets a `handoff_to_agent` tool; shared context (task,
+ * history, contributed knowledge, roster) is rebuilt for every turn.
+ * Safety: max handoffs / iterations / timeouts + ping-pong detection.
+ */
+interface SwarmOptions {
+    agents: Agent[];
+    /** First agent to run. Default: agents[0]. Accepts instance or name. */
+    entryPoint?: Agent | string;
+    maxHandoffs?: number;
+    maxIterations?: number;
+    executionTimeoutMs?: number;
+    nodeTimeoutMs?: number;
+    /** Ping-pong detection: window size + min unique agents (0 = disabled). */
+    loopDetectionWindow?: number;
+    minUniqueAgents?: number;
+}
+interface HandoffSignal {
+    to: string;
+    message: string;
+    context?: Record<string, unknown>;
+}
+type SwarmStatus = "COMPLETED" | "FAILED";
+interface SwarmResult {
+    status: SwarmStatus;
+    text: string;
+    nodeHistory: string[];
+    results: Record<string, AgentResult>;
+    iterations: number;
+    handoffs: number;
+    usage: TokenUsage;
+    sharedContext: Record<string, Record<string, unknown>>;
+    error?: string;
+}
+type SwarmStreamEvent = {
+    type: "node_start";
+    agent: string;
+} | {
+    type: "node_done";
+    agent: string;
+} | {
+    type: "handoff";
+    from: string;
+    to: string;
+} | {
+    type: "agent_event";
+    agent: string;
+    event: StreamEvent;
+} | {
+    type: "result";
+    result: SwarmResult;
+};
+declare function readHandoffSignal(err: unknown): HandoffSignal | undefined;
+declare class Swarm {
+    private agents;
+    private entryPoint;
+    private maxHandoffs;
+    private maxIterations;
+    private executionTimeoutMs?;
+    private nodeTimeoutMs?;
+    private loopWindow;
+    private minUniqueAgents;
+    constructor(opts: SwarmOptions);
+    private roster;
+    private buildInput;
+    private memberWithHandoff;
+    run(task: string | ContentBlock[], opts?: RunOptions & {
+        sharedState?: InvocationState;
+    }): Promise<SwarmResult>;
+    stream(task: string | ContentBlock[], opts?: RunOptions & {
+        sharedState?: InvocationState;
+    }): AsyncGenerator<SwarmStreamEvent, SwarmResult>;
+    private detectLoop;
+    private finish;
+}
+
+/**
+ * Agent-to-Agent (A2A) interop — The Framework agents calling agents on
+ * other platforms, and vice versa. Minimal core of the open protocol:
+ * agent-card discovery + JSON-RPC message/send over HTTP, with per-context
+ * isolation on the server side.
+ */
+interface AgentCard {
+    name: string;
+    description?: string;
+    version?: string;
+    skills?: {
+        name: string;
+        description?: string;
+    }[];
+}
+interface A2AClientOptions {
+    fetchFn?: typeof fetch;
+    timeoutMs?: number;
+}
+/** Consume a remote A2A agent like a local one. */
+declare class A2AClient {
+    readonly endpoint: string;
+    private fetchFn;
+    private timeoutMs;
+    constructor(endpoint: string, opts?: A2AClientOptions);
+    getCard(): Promise<AgentCard>;
+    send(text: string, contextId?: string): Promise<{
+        text: string;
+        contextId?: string;
+    }>;
+}
+/** Wrap a remote agent as a framework Tool for orchestrators. */
+declare function a2aAsTool(client: A2AClient, opts?: {
+    name?: string;
+    description?: string;
+}): Tool;
+interface A2AServerOptions {
+    card: AgentCard;
+    /**
+     * Fresh agent per contextId (isolation). Retained up to maxContexts (LRU).
+     * Return the SAME agent for a contextId to keep state in memory across
+     * turns of one conversation, but never share one instance across contexts —
+     * shared history leaks conversations between users.
+     */
+    agentFactory: (contextId: string) => Agent | Promise<Agent>;
+    maxContexts?: number;
+    port?: number;
+    host?: string;
+    /** Durable HITL threads: runs execute with { checkpointer, threadId: contextId }. */
+    checkpointer?: Checkpointer;
+    /** Browser frontends: reflected as Access-Control-Allow-Origin (+ OPTIONS handling). */
+    corsOrigins?: string[];
+    /** Max JSON-RPC request body bytes. Default 10 MiB. */
+    maxBodyBytes?: number;
+}
+/** Serve a Framework agent over A2A (card + message/send). */
+declare class A2AServer {
+    private opts;
+    private server?;
+    private contexts;
+    private maxContexts;
+    constructor(opts: A2AServerOptions);
+    private corsHeaders;
+    private runOpts;
+    private agentFor;
+    /** Read a request body with a hard cap; JSON.parse errors to the caller. */
+    private readBody;
+    private handle;
+    start(port?: number, host?: string): Promise<number>;
+    stop(): Promise<void>;
+}
+
+/**
+ * Frontend/server-component client for Framework agents.
+ * Framework-agnostic (fetch + async iterators): use directly in TanStack
+ * Query loaders, Next.js route handlers/components, Svelte, or plain DOM.
+ * React bindings live in @fabisch/react (thin layer over this client).
+ */
+interface AgentClientOptions {
+    fetchFn?: typeof fetch;
+    timeoutMs?: number;
+}
+declare class AgentClient {
+    private a2a;
+    private fetchFn;
+    readonly endpoint: string;
+    constructor(endpoint: string, opts?: AgentClientOptions);
+    card(): Promise<AgentCard>;
+    send(text: string, contextId?: string): Promise<{
+        text: string;
+        contextId?: string;
+    }>;
+    /** Live StreamEvents over SSE (`POST /stream`). Throws AgentError on server errors. */
+    stream(text: string, contextId?: string, signal?: AbortSignal, opts?: {
+        onContext?: (contextId: string) => void;
+    }): AsyncGenerator<StreamEvent>;
+}
+/**
+ * Next.js / TanStack Start route handler bridge: POST { text, contextId? }
+ * → SSE stream of agent events. `AgentClient.stream` posts to
+ * `${endpoint}/stream`, so mount this at `app/api/agent/stream/route.ts` and
+ * point `useAgent({ endpoint: "/api/agent" })` (or AgentClient) at the parent:
+ *
+ *   import { AgentClient, handleAgentRoute } from "@fabisch/agents";
+ *   const client = new AgentClient(process.env.AGENT_URL!);
+ *   export const POST = (req: Request) => handleAgentRoute(req, client);
+ *
+ * The browser disconnect (req.signal) stops the upstream agent run.
+ */
+declare function handleAgentRoute(req: Request, client: AgentClient): Promise<Response>;
+
+/**
+ * framework.json — declare agents, launch them as A2A servers.
+ * Relative paths resolve against the config file's directory.
+ */
+declare const AgentDefSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodDefault<z.ZodString>;
+    systemPrompt: z.ZodDefault<z.ZodString>;
+    model: z.ZodString;
+    port: z.ZodOptional<z.ZodNumber>;
+    skills: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    filesystem: z.ZodOptional<z.ZodString>;
+    todos: z.ZodDefault<z.ZodBoolean>;
+    maxSteps: z.ZodDefault<z.ZodNumber>;
+    sessionDir: z.ZodOptional<z.ZodString>;
+    /** Extra env file for this agent (keys override framework-level). */
+    envFile: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    model: string;
+    todos: boolean;
+    systemPrompt: string;
+    description: string;
+    maxSteps: number;
+    skills: string[];
+    filesystem?: string | undefined;
+    port?: number | undefined;
+    sessionDir?: string | undefined;
+    envFile?: string | undefined;
+}, {
+    name: string;
+    model: string;
+    todos?: boolean | undefined;
+    filesystem?: string | undefined;
+    systemPrompt?: string | undefined;
+    description?: string | undefined;
+    maxSteps?: number | undefined;
+    port?: number | undefined;
+    skills?: string[] | undefined;
+    sessionDir?: string | undefined;
+    envFile?: string | undefined;
+}>;
+declare const FrameworkFileSchema: z.ZodObject<{
+    server: z.ZodDefault<z.ZodObject<{
+        host: z.ZodDefault<z.ZodString>;
+        basePort: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        host: string;
+        basePort: number;
+    }, {
+        host?: string | undefined;
+        basePort?: number | undefined;
+    }>>;
+    /** Framework-level env file(s), loaded before agents resolve models. */
+    envFile: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+    /** Inline env mapping (applied after env files, overrides them). */
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    /** Local checkpoint dir for served agents (durable HITL threads). */
+    checkpointer: z.ZodOptional<z.ZodObject<{
+        dir: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        dir: string;
+    }, {
+        dir: string;
+    }>>;
+    http: z.ZodDefault<z.ZodObject<{
+        corsOrigins: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        corsOrigins: string[];
+    }, {
+        corsOrigins?: string[] | undefined;
+    }>>;
+    agents: z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodDefault<z.ZodString>;
+        systemPrompt: z.ZodDefault<z.ZodString>;
+        model: z.ZodString;
+        port: z.ZodOptional<z.ZodNumber>;
+        skills: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        filesystem: z.ZodOptional<z.ZodString>;
+        todos: z.ZodDefault<z.ZodBoolean>;
+        maxSteps: z.ZodDefault<z.ZodNumber>;
+        sessionDir: z.ZodOptional<z.ZodString>;
+        /** Extra env file for this agent (keys override framework-level). */
+        envFile: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        model: string;
+        todos: boolean;
+        systemPrompt: string;
+        description: string;
+        maxSteps: number;
+        skills: string[];
+        filesystem?: string | undefined;
+        port?: number | undefined;
+        sessionDir?: string | undefined;
+        envFile?: string | undefined;
+    }, {
+        name: string;
+        model: string;
+        todos?: boolean | undefined;
+        filesystem?: string | undefined;
+        systemPrompt?: string | undefined;
+        description?: string | undefined;
+        maxSteps?: number | undefined;
+        port?: number | undefined;
+        skills?: string[] | undefined;
+        sessionDir?: string | undefined;
+        envFile?: string | undefined;
+    }>, z.ZodObject<{
+        file: z.ZodString;
+    }, "strip", z.ZodUnknown, z.objectOutputType<{
+        file: z.ZodString;
+    }, z.ZodUnknown, "strip">, z.objectInputType<{
+        file: z.ZodString;
+    }, z.ZodUnknown, "strip">>]>, "many">;
+}, "strip", z.ZodTypeAny, {
+    server: {
+        host: string;
+        basePort: number;
+    };
+    http: {
+        corsOrigins: string[];
+    };
+    agents: ({
+        name: string;
+        model: string;
+        todos: boolean;
+        systemPrompt: string;
+        description: string;
+        maxSteps: number;
+        skills: string[];
+        filesystem?: string | undefined;
+        port?: number | undefined;
+        sessionDir?: string | undefined;
+        envFile?: string | undefined;
+    } | z.objectOutputType<{
+        file: z.ZodString;
+    }, z.ZodUnknown, "strip">)[];
+    checkpointer?: {
+        dir: string;
+    } | undefined;
+    envFile?: string | string[] | undefined;
+    env?: Record<string, string> | undefined;
+}, {
+    agents: ({
+        name: string;
+        model: string;
+        todos?: boolean | undefined;
+        filesystem?: string | undefined;
+        systemPrompt?: string | undefined;
+        description?: string | undefined;
+        maxSteps?: number | undefined;
+        port?: number | undefined;
+        skills?: string[] | undefined;
+        sessionDir?: string | undefined;
+        envFile?: string | undefined;
+    } | z.objectInputType<{
+        file: z.ZodString;
+    }, z.ZodUnknown, "strip">)[];
+    checkpointer?: {
+        dir: string;
+    } | undefined;
+    envFile?: string | string[] | undefined;
+    server?: {
+        host?: string | undefined;
+        basePort?: number | undefined;
+    } | undefined;
+    env?: Record<string, string> | undefined;
+    http?: {
+        corsOrigins?: string[] | undefined;
+    } | undefined;
+}>;
+
+type FrameworkFile = z.infer<typeof FrameworkFileSchema>;
+type ServedAgent = {
+    name: string;
+    url: string;
+    cardUrl: string;
+    server: A2AServer;
+};
+type ResolvedAgentDef = z.infer<typeof AgentDefSchema>;
+/** loadFrameworkConfig output: every entry resolved to a concrete agent def. */
+interface LoadedFrameworkFile {
+    server: {
+        host: string;
+        basePort: number;
+    };
+    envFile?: string | string[];
+    env?: Record<string, string>;
+    checkpointer?: {
+        dir: string;
+    };
+    http: {
+        corsOrigins: string[];
+    };
+    agents: ResolvedAgentDef[];
+}
+/**
+ * Load an env file if present (silent when missing). `override: false` fills
+ * gaps like plain dotenv (the process environment wins); `override: true`
+ * lets later files beat earlier ones — used for agent-level files, which the
+ * config schema documents as overriding framework-level keys.
+ */
+declare function loadEnvFile(path: string, override?: boolean): void;
+declare function loadFrameworkConfig(path: string): LoadedFrameworkFile;
+declare function buildServedAgent(def: ResolvedAgentDef, opts?: {
+    sessionId?: string;
+}): Promise<{
+    agent: Agent;
+    card: {
+        name: string;
+        description?: string;
+    };
+}>;
+declare function serveFramework(file: LoadedFrameworkFile): Promise<{
+    agents: ServedAgent[];
+    stop: () => Promise<void>;
+}>;
+
+/**
+ * Retrieval interface — no bundled vector DB (local-first).
+ * Adapters: InMemoryRetriever (TF-IDF, dependency-free), SparqlRetriever
+ * over any GraphStore. retrievalTool() exposes them to agents.
+ */
+interface ScoredDoc {
+    id: string;
+    text: string;
+    score: number;
+    meta?: Record<string, unknown>;
+}
+interface Retriever {
+    readonly id: string;
+    search(query: string, k?: number): Promise<ScoredDoc[]>;
+}
+/** Dependency-free TF-IDF retriever over static documents. */
+declare class InMemoryRetriever implements Retriever {
+    readonly id = "tfidf";
+    private docs;
+    private df;
+    constructor(docs: {
+        id: string;
+        text: string;
+        meta?: Record<string, unknown>;
+    }[]);
+    private idf;
+    search(query: string, k?: number): Promise<ScoredDoc[]>;
+}
+declare function retrievalTool(retriever: Retriever, opts?: {
+    k?: number;
+    name?: string;
+}): Tool<{
+    query: string;
+    k?: number | undefined;
+}, ScoredDoc[]>;
+/** SPARQL-backed retriever: keyword match over the closure, rendered as text. */
+declare function sparqlRetriever(store: {
+    match: (s: string | null, p: string | null, o: string | null) => Promise<{
+        subject: string;
+        predicate: string;
+        object: string;
+    }[]>;
+}, opts?: {
+    id?: string;
+}): Retriever;
+
+/**
+ * Sandboxed JavaScript execution (node:vm, fresh context per call).
+ * Code runs as a program (completion value returned — wrap object literals
+ * in parens). No require/fetch/process by default; timeout enforced; output
+ * must be JSON-serializable (returned) or a string. For untrusted code
+ * prefer an external container — this is a speed bump, not a security boundary.
+ */
+declare function runJavascriptTool(opts?: {
+    timeoutMs?: number;
+    maxOutputChars?: number;
+}): Tool<{
+    code: string;
+}, {} | null>;
+/**
+ * Sandbox backend (local-first): one rooted workspace with shell `execute`
+ * plus file tools, matching the Deep Agents backend shape (ls, read_file,
+ * write_file, edit_file, glob, grep + execute).
+ *
+ * Isolation, honestly scoped: fresh cwd jail per call, scrubbed env (no
+ * secrets/proxies inherited), timeouts, output caps with spill-to-file.
+ * This is NOT a container boundary: never put secrets in the sandbox env,
+ * gate `execute` with human-in-the-loop for sensitive work, and treat all
+ * outputs as untrusted input.
+ */
+interface SandboxOptions {
+    /** Workspace root. Defaults to cwd. */
+    root?: string;
+    timeoutMs?: number;
+    maxOutputChars?: number;
+    /** Extra env vars for shell commands (merged over the scrubbed base). */
+    env?: Record<string, string>;
+}
+interface SandboxBackend {
+    readonly root: string;
+    tools(): Tool[];
+}
+/** Minimal glob (*, ?, and double-star for crossing directories) over paths relative to root. */
+declare function matchGlob(pattern: string, path: string): boolean;
+declare function createSandboxBackend(opts?: SandboxOptions): SandboxBackend;
+
+/**
+ * Evals: JSONL datasets + scoring + pass-rate reporter.
+ * Offline by default (stub models); set EVAL_LIVE=1 to run cases
+ * against the configured provider instead.
+ */
+interface EvalExpect {
+    contains?: string[];
+    toolUsed?: string[];
+    noStructuredError?: boolean;
+}
+interface EvalCase {
+    id: string;
+    input: string;
+    expect?: EvalExpect;
+}
+interface EvalScore {
+    id: string;
+    pass: boolean;
+    detail: string;
+    usage: TokenUsage;
+}
+declare function loadJsonl(path: string): EvalCase[];
+declare function runEval(cases: EvalCase[], makeAgent: (c: EvalCase) => Agent): Promise<{
+    scores: EvalScore[];
+    passRate: number;
+}>;
+declare function printReport(scores: EvalScore[], passRate: number): void;
+
+/**
+ * Tracing exporter: OTel-shaped spans (trace/span ids, timestamps,
+ * attributes) from AgentEvents, sunk to console or JSONL. No OTel SDK —
+ * the shape is compatible, the transport is local-first. Adapters to
+ * Langfuse/LangSmith-style HTTP endpoints can POST these spans unchanged.
+ */
+interface Span {
+    traceId: string;
+    spanId: string;
+    parentId?: string;
+    name: string;
+    startedAt: string;
+    endedAt?: string;
+    attributes: Record<string, unknown>;
+}
+interface SpanSink {
+    emit(span: Span): void;
+}
+declare class ConsoleSpanSink implements SpanSink {
+    emit(span: Span): void;
+}
+declare class JsonlSpanSink implements SpanSink {
+    private path;
+    constructor(path: string);
+    emit(span: Span): void;
+}
+declare class MemorySpanSink implements SpanSink {
+    spans: Span[];
+    emit(span: Span): void;
+}
+/** Build AgentEvents that project run/step/tool lifecycle into spans. */
+declare function tracingEvents(sink: SpanSink, opts?: {
+    traceId?: string;
+}): AgentEvents;
+/**
+ * Policy filter: allow/deny tool calls by name pattern before execution.
+ * Denied calls become ToolRejection feedback (model continues) or throw
+ * POLICY_DENY with exitBehavior "error".
+ */
+declare function policyFilterMiddleware(opts: {
+    allow?: (string | RegExp)[];
+    deny?: (string | RegExp)[];
+    exitBehavior?: "continue" | "error";
+}): AgentMiddleware;
+
+/**
+ * Compaction: keep long runs inside the context window without losing meaning.
+ * Strategy (P1): oldest messages -> model/pluggable summarizer -> single
+ * boundary message. Semantic variant keeps extracted triples, drops prose.
+ */
+interface CompactionOptions {
+    /** Compact when messages exceed this count. Default 40. */
+    maxMessages?: number;
+    /** Summarizer: (messages to compress) -> summary text. Default: extractive stub. */
+    summarize?: (messages: ChatMessage[]) => Promise<string>;
+}
+declare function defaultSummarize(messages: ChatMessage[]): Promise<string>;
+/** Wrap any Memory with auto-compaction. */
+declare class CompactedMemory implements Memory {
+    private inner;
+    private opts;
+    constructor(inner: Memory, opts?: CompactionOptions);
+    load(): Promise<ChatMessage[]>;
+    save(messages: ChatMessage[]): Promise<void>;
+    clear(): Promise<void>;
+}
+
+interface Budget {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+/** Runtime guard: abort + timeout. Token/cost budgets land here in P1. */
+declare function runWithBudget<T>(fn: () => Promise<T>, budget?: Budget): Promise<T>;
+
+type OrchestrationStrategy = "sequential" | "parallel" | "router";
+interface OrchestrationPlan {
+    strategy: OrchestrationStrategy;
+    agents: Agent[];
+    /** Max concurrent agents for parallel. Default: all at once. */
+    concurrency?: number;
+    /** Model that picks the agent for router. Defaults to the first agent's model. */
+    routerModel?: ModelProvider;
+    events?: AgentEvents;
+}
+interface OrchestratedResult {
+    strategy: OrchestrationStrategy;
+    results: AgentResult[];
+    /** Combined text: last result (sequential/router), joined (parallel). */
+    text: string;
+    /** Router only: index of the chosen agent. */
+    routedTo?: number;
+}
+declare function runOrchestrated(plan: OrchestrationPlan, input: string, signal?: AbortSignal): Promise<OrchestratedResult>;
+declare function runOrchestrated(plan: OrchestrationPlan, input: string, opts?: RunOptions): Promise<OrchestratedResult>;
+
+/** DAG workflow node. `ctx` maps completed node ids to their results. */
+interface WorkflowNode {
+    id: string;
+    run: (ctx: Record<string, unknown>, invocationState?: InvocationState) => Promise<unknown>;
+    dependsOn?: string[];
+    /** Retry policy. Default: no retry (attempts: 1). Abort always rethrows. */
+    retry?: {
+        attempts?: number;
+        backoffMs?: number;
+    };
+}
+interface WorkflowOptions {
+    signal?: AbortSignal;
+    /** Shared per-run data passed to every node (never sent to models by itself). */
+    invocationState?: InvocationState;
+}
+/**
+ * Execute a DAG: topological levels run in order, nodes within a level
+ * run concurrently. Returns id -> result. Throws structured WORKFLOW_* errors.
+ */
+declare function runWorkflow(nodes: WorkflowNode[], opts?: WorkflowOptions): Promise<Record<string, unknown>>;
+
+/**
+ * Skills: portable capability packs (SKILL.md + optional tools/resources).
+ * Spec: a skill is a directory with SKILL.md frontmatter
+ * (name, description, version) + markdown body. Loader discovers,
+ * validates, and exposes skills as Tools or prompt injections.
+ */
+interface Skill {
+    name: string;
+    description: string;
+    version: string;
+    path: string;
+    body: string;
+    tools?: Tool[];
+}
+interface SkillLoaderOptions {
+    /** Directories to scan for SKILL.md files. */
+    dirs: string[];
+    /** If true, throw on invalid skill; else skip with warning. Default false. */
+    strict?: boolean;
+}
+/** Parse SKILL.md content -> { meta, body }. Pure, testable, no FS. */
+declare function parseSkillFile(content: string, path?: string): Omit<Skill, "tools">;
+/** Registry of loaded skills — activation is explicit, never magic. */
+declare class SkillRegistry {
+    private skills;
+    register(skill: Skill): this;
+    get(name: string): Skill | undefined;
+    list(): Skill[];
+    /** Expose each skill's tools (if any) for Agent consumption. */
+    asTools(): Tool[];
+}
+/**
+ * Scan directories for SKILL.md files (one level, plus direct files).
+ * Invalid skills are skipped (or throw when `strict`). Never throws for
+ * missing directories — returns what it finds.
+ */
+declare function discoverSkills(dirs: string[], opts?: {
+    strict?: boolean;
+}): Promise<Skill[]>;
+/** Load + register every discoverable skill. Duplicate names throw. */
+declare function loadSkillsInto(registry: SkillRegistry, dirs: string[], opts?: {
+    strict?: boolean;
+}): Promise<Skill[]>;
+/**
+ * Local skill routing — dependency-free TF-IDF cosine over skill
+ * name+description. Explicit `$name` mentions always win. No embedding
+ * APIs, no network. A pluggable embedder can replace `scoreSkills`
+ * later without changing `matchSkills`.
+ */
+declare function tokenize(text: string): string[];
+declare function scoreSkills(registry: SkillRegistry, input: string): {
+    skill: Skill;
+    score: number;
+}[];
+declare function matchSkills(registry: SkillRegistry, input: string, threshold?: number): Skill[];
+
+/**
+ * MCP (Model Context Protocol) client.
+ * - Streamable HTTP transport (POST JSON-RPC; JSON or SSE responses).
+ * - stdio transport (spawned server, line-delimited JSON-RPC).
+ * - `mcpToolsToFramework` bridges MCP tool defs to framework Tools,
+ *   converting JSON Schema input schemas to zod.
+ */
+interface McpToolDef {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+}
+interface McpClientOptions {
+    fetchFn?: typeof fetch;
+    headers?: Record<string, string>;
+    clientName?: string;
+}
+/** Minimal JSON Schema -> zod (objects, string/number/integer/boolean/array/enum/null; else unknown). */
+declare function jsonSchemaToZod(schema: Record<string, unknown>): z.ZodType<unknown>;
+/** MCP client over Streamable HTTP. */
+declare class McpHttpClient {
+    readonly serverId: string;
+    private url;
+    private headers;
+    private fetchFn;
+    private clientName;
+    private sessionId?;
+    private connected;
+    constructor(url: string, opts?: McpClientOptions & {
+        serverId?: string;
+    });
+    private rpc;
+    /** JSON-RPC notification — no id, no response expected. */
+    private notify;
+    private rpcInner;
+    connect(): Promise<{
+        name: string;
+        version?: string;
+    }>;
+    private requireConnected;
+    listTools(): Promise<McpToolDef[]>;
+    callTool(name: string, args: unknown): Promise<unknown>;
+    close(): Promise<void>;
+}
+/** MCP client over stdio (spawns `command args`, speaks line-delimited JSON-RPC). */
+declare class McpStdioClient {
+    private command;
+    private args;
+    readonly serverId: string;
+    private child?;
+    private buffer;
+    private pending;
+    private clientName;
+    constructor(command: string, args?: string[], opts?: {
+        serverId?: string;
+        clientName?: string;
+    });
+    connect(): Promise<void>;
+    private request;
+    listTools(): Promise<McpToolDef[]>;
+    callTool(name: string, args: unknown): Promise<unknown>;
+    close(): Promise<void>;
+}
+type AnyMcpClient = Pick<McpHttpClient, "serverId" | "listTools" | "callTool" | "close">;
+interface McpClient {
+    readonly serverId: string;
+    listTools(): Promise<McpToolDef[]>;
+    callTool(name: string, args: unknown): Promise<unknown>;
+    close(): Promise<void>;
+}
+/** Turn MCP tool defs into framework Tools (namespaced `server.tool` on collision). */
+declare function mcpToolsToFramework(client: McpClient, defs?: McpToolDef[]): Promise<Tool[]>;
+declare function connectMcpHttp(url: string, opts?: McpClientOptions): Promise<McpHttpClient>;
+declare function connectMcpStdio(command: string, args?: string[]): Promise<McpStdioClient>;
+
+interface PromptTemplate {
+    name: string;
+    version: string;
+    template: string;
+    render(vars: Record<string, string | number>): string;
+}
+declare function definePrompt(name: string, template: string, version?: string): PromptTemplate;
+/** Load `--- name, version ---` frontmatter + markdown body from disk. */
+declare function loadPromptFile(path: string): PromptTemplate;
+/** A/B variants: pick by traffic split (weighted random) or explicit variant. */
+declare function abPrompts(variants: {
+    name: string;
+    template: string;
+    version?: string;
+    weight?: number;
+}[], pick?: string): PromptTemplate;
+
+/**
+ * Remote SPARQL adapter (roadmap P2-sem): talk to real SPARQL endpoints —
+ * Wikidata Query Service, Fuseki, GraphDB, Virtuoso — with auth and pinned
+ * prefixes. The local GraphStore stays the read path for closures; this is
+ * for data that lives OUTSIDE the agent's own graph.
+ *
+ * Protocol: SPARQL 1.1 — SELECT via POST `application/sparql-query`,
+ * UPDATE via POST `application/sparql-update`; SELECT responses must be
+ * `application/sparql-results+json` (we ask for it in Accept).
+ */
+type SparqlAuth = {
+    type: "basic";
+    user: string;
+    password: string;
+} | {
+    type: "bearer";
+    token: string;
+} | {
+    type: "header";
+    name: string;
+    value: string;
+};
+interface RemoteSparqlOptions {
+    /** Query endpoint URL (e.g. https://query.wikidata.org/sparql). */
+    endpoint: string;
+    /** Update endpoint; defaults to `endpoint`. */
+    updateEndpoint?: string;
+    auth?: SparqlAuth;
+    /** Pinned prefixes, prepended to every query as PREFIX declarations. */
+    prefixes?: Record<string, string>;
+    /** Extra request headers (merged over the defaults below). */
+    headers?: Record<string, string>;
+    fetchFn?: typeof fetch;
+    /** Per-request timeout. Default 30s. */
+    timeoutMs?: number;
+    /**
+     * Built-in retries for transient endpoints (429/5xx/network). Rate limits
+     * are common on public SPARQL endpoints; the middleware retry is a separate
+     * layer for MODEL calls only. Default 2. Honors Retry-After when present.
+     */
+    maxRetries?: number;
+}
+/** One SELECT result row: variable name -> plain string term. */
+type SparqlRow = Record<string, string>;
+declare class RemoteSparqlAdapter {
+    readonly endpoint: string;
+    private readonly updateEndpoint;
+    private readonly prefixes;
+    private readonly extraHeaders;
+    private readonly fetchFn;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly auth?;
+    constructor(opts: RemoteSparqlOptions);
+    /** Prepend pinned PREFIX declarations so caller queries stay short. */
+    withPrefixes(query: string): string;
+    private headers;
+    private post;
+    /**
+     * SELECT over the remote endpoint. Returns rows of plain-string terms
+     * (same shape as the local `executeSelect`) so both path kinds compose.
+     */
+    select(query: string): Promise<SparqlRow[]>;
+    /**
+     * SPARQL 1.1 UPDATE (INSERT/DELETE DATA, DELETE WHERE...) against the
+     * update endpoint. Opt-in — never wire this into a read-only agent.
+     */
+    update(query: string): Promise<void>;
+}
+/** Agent-facing tool. SELECT always; UPDATE only when `allowUpdate`. */
+declare function remoteSparqlTool(adapter: RemoteSparqlAdapter, opts?: {
+    allowUpdate?: boolean;
+}): Tool;
+
+/**
+ * Entity linking (roadmap P2-sem): turn free-text mentions into graph IRIs.
+ * Case-insensitive label index (rdfs:label / skos:prefLabel / skos:altLabel)
+ * over the store closure, canonicalized through owl:sameAs groups — a
+ * mention linked through any alias resolves to ONE representative IRI.
+ *
+ * docs/07 rule 2, autonomy-first: the model calls `propose_mapping` and the
+ * mapping commits on proposal (default) as a provenance-carrying
+ * skos:altLabel the linker sees from then on — matching the autonomous write
+ * path everywhere else (graph_add). Human review is the opt-out:
+ * `new MappingProposals({ autonomy: false })` queues proposals for decide(),
+ * or gate the tool with humanInTheLoopMiddleware. Provenance is mandatory
+ * either way.
+ */
+declare const LABEL_PREDICATES: Set<string>;
+/** Prefixes used to expand/compact IRIs for JSON-LD I/O (nullable values pass through). */
+declare const JSONLD_PREFIXES: Record<string, string>;
+interface LinkedEntity {
+    /** Canonical (sameAs-group representative) IRI, in the store's term form. */
+    iri: string;
+    label?: string;
+    score: number;
+    /** Other IRIs the same entity is known as (the sameAs group). */
+    sameAsGroup: string[];
+}
+declare class EntityLinker {
+    private store;
+    constructor(store: GraphStore);
+    /** Union-find over owl:sameAs pairs: every alias cluster -> one representative. */
+    private sameAsGroups;
+    /** Mention -> candidate entities, best first, canonicalized via sameAs. */
+    link(mention: string, k?: number): Promise<LinkedEntity[]>;
+}
+/** link_entity agent tool: mention -> canonical IRIs with scores. */
+declare function linkEntityTool(linker: EntityLinker): Tool<{
+    mention: string;
+    k?: number | undefined;
+}, LinkedEntity[]>;
+interface MappingProposal {
+    id: string;
+    /** The source-side term: usually a raw column header / mention string. */
+    from: string;
+    /** The proposed target: a canonical ontology IRI. */
+    to: string;
+    /** Provenance for the eventual commit (required by GraphStore.validate). */
+    source: string;
+    status: "pending" | "approved" | "rejected";
+    /** True when autonomy committed it on proposal (no human turn). */
+    committedByAutonomy?: boolean;
+    proposedAt: string;
+}
+type MappingDecision = "approved" | "rejected";
+interface MappingProposalsOptions {
+    /**
+     * Autonomy: proposals commit IMMEDIATELY on proposal. DEFAULT ON — the
+     * agent's whole write path is autonomous (graph_add), so mapping should
+     * not be the one gate keeping a human in the loop. Set `autonomy: false`
+     * to queue proposals for human decide() instead, or gate the tool with
+     * humanInTheLoopMiddleware.
+     */
+    autonomy?: boolean;
+    /** Store to commit against. Without one there is nowhere to commit — proposals queue as pending. */
+    store?: GraphStore;
+}
+declare class MappingProposals {
+    private opts;
+    private seq;
+    private items;
+    constructor(opts?: MappingProposalsOptions);
+    /** True when proposals commit themselves (autonomy on AND a store bound). */
+    get autonomy(): boolean;
+    private commit;
+    /**
+     * Record an LLM-proposed mapping. With autonomy (default) + a bound store
+     * it commits right away, provenance required; with `autonomy: false` (or
+     * no store bound) it queues as pending until decide().
+     */
+    propose(from: string, to: string, source: string): Promise<MappingProposal>;
+    list(status?: MappingProposal["status"]): MappingProposal[];
+    /** Human decision. `approved` also commits the alias into the graph. */
+    decide(store: GraphStore, id: string, decision: MappingDecision): Promise<MappingProposal | undefined>;
+}
+declare function proposeMappingTool(proposals: MappingProposals): Tool<{
+    to: string;
+    from: string;
+    source: string;
+}, string | {
+    id: string;
+    status: string;
+    committed: boolean;
+    note?: undefined;
+} | {
+    id: string;
+    status: string;
+    note: string;
+    committed?: undefined;
+}>;
+/**
+ * Quads -> expanded JSON-LD. Named graphs round-trip: quads carrying a
+ * `graph` become JSON-LD named-graph entries ({"@id": graph, "@graph": ...}),
+ * graph-less quads land in the default graph. Provenance fields
+ * (source/rule) do not round-trip — JSON-LD carries the statements, the
+ * store keeps the evidence.
+ */
+declare function quadsToJsonLd(quads: Quad[], prefixes?: Record<string, string>): Record<string, unknown>;
+/** Expanded JSON-LD -> quads (named graphs preserved; prefixed terms restored where the map covers them). */
+declare function jsonldToQuads(doc: {
+    "@graph"?: unknown[];
+} & Record<string, unknown>, prefixes?: Record<string, string>): {
+    subject: string;
+    predicate: string;
+    object: string;
+    graph?: string;
+}[];
+
+/**
+ * Ontology evolution (roadmap P2-sem, docs/07 lifecycle stage "evolve"):
+ * TBox v3 -> v4 with a migration that is checked before AND after by a
+ * conformance battery, and that never destroys the old store.
+ *
+ * The store has no delete by design; migration therefore REBUILDS: explicit
+ * facts are exported from the old store, transformed (axiom add/remove,
+ * term renames, deprecations), re-validated and re-entailed into a fresh
+ * v4 store. The v3 store survives untouched — rollback is "don't adopt".
+ */
+interface ConformanceCheck {
+    id: string;
+    /**
+     * SPARQL-subset SELECT (see executeSelect). Passes when the row count is
+     * within [minRows, maxRows]. Default: at least one row (ask-style);
+     * `minRows: 0, maxRows: 0` asserts absence.
+     */
+    ask?: string;
+    minRows?: number;
+    maxRows?: number;
+    /** An extra SHACL shape the closure must satisfy. */
+    shape?: NodeShape;
+    /** Why this check matters — surfaces in failure reports. */
+    reason?: string;
+}
+interface ConformanceResult {
+    id: string;
+    passed: boolean;
+    detail: string;
+}
+interface ConformanceReport {
+    passed: boolean;
+    results: ConformanceResult[];
+}
+/** Run a battery of checks against a store's closure. */
+declare function runConformance(store: InMemoryGraphStore, battery: ConformanceCheck[]): Promise<ConformanceReport>;
+interface TBoxMigrationSpec {
+    from: string;
+    to: string;
+    /** New TBox axioms to add (provenance required by the store). */
+    added?: Quad[];
+    /** Exact axioms to retract (matched on subject|predicate|object). */
+    removed?: {
+        subject: string;
+        predicate: string;
+        object: string;
+    }[];
+    /**
+     * Term renames applied to BOTH the TBox and ABox in all three positions
+     * (subject/predicate/object): class splits, predicate renames, IRI moves.
+     */
+    renames?: {
+        from: string;
+        to: string;
+    }[];
+    /** Terms deprecated in this version; with `replacement`, uses are rewritten. */
+    deprecations?: {
+        term: string;
+        replacement?: string;
+        reason: string;
+    }[];
+    /** Shapes/rules carried by the NEW store (defaults to the old store's). */
+    shapes?: NodeShape[];
+    rules?: StoreOptions["rules"];
+}
+interface MigrationReport {
+    from: string;
+    to: string;
+    status: "migrated" | "aborted" | "failed";
+    addedQuads: number;
+    removedQuads: number;
+    rewrittenQuads: number;
+    /** Named graph the v4 TBox axioms were written to (match(.., ..., tboxGraph)). */
+    tboxGraph?: string;
+    deprecatedWarnings: string[];
+    errors: string[];
+    preBattery?: ConformanceReport;
+    postBattery?: ConformanceReport;
+}
+interface MigrationResult {
+    report: MigrationReport;
+    /** Present on success — the new-version store with a fresh closure. The v3 store is untouched. */
+    store?: InMemoryGraphStore;
+}
+/** Ontology-defining predicates: shared with the review auditor. */
+declare const TBOX_PREDICATES: Set<string>;
+/** rdf:type objects that mark a TERM declaration, not an instance fact. */
+declare const OWL_VOCAB: Set<string>;
+/**
+ * Migrate a TBox. Order: pre-battery (abort on failure) -> rebuild ->
+ * post-battery (report failure; caller decides whether to adopt).
+ */
+declare function migrateTBox(oldStore: InMemoryGraphStore, spec: TBoxMigrationSpec, opts?: {
+    battery?: ConformanceCheck[];
+    factory?: (opts: StoreOptions) => InMemoryGraphStore;
+    tboxGraph?: string | false;
+}): Promise<MigrationResult>;
+
+interface TermStat {
+    term: string;
+    kind: "class" | "property";
+    /** Explicit ABox uses: instance-of counts for classes, fact counts for properties. */
+    uses: number;
+    /** TBox axioms mentioning the term (declarations, subClassOf, domain/range, ...). */
+    axiomCount: number;
+    label?: string;
+}
+interface OntologyReview {
+    classes: TermStat[];
+    properties: TermStat[];
+    /** Used in data with zero TBox declarations — the "what to add" list. */
+    undeclared: TermStat[];
+    /** Declared but never used in any explicit fact. */
+    unused: string[];
+    /** Terms without rdfs:label / skos:prefLabel / altLabel. */
+    unlabeled: string[];
+    /** Properties missing rdfs:domain / rdfs:range axioms. */
+    missingDomain: string[];
+    missingRange: string[];
+    /** Explicit quads vs closure size — how much the ontology explains. */
+    explicitQuads: number;
+    closureQuads: number;
+}
+/** Audit the store: inventory + gap list. Pure read — never mutates. */
+declare function reviewOntology(store: InMemoryGraphStore): Promise<OntologyReview>;
+interface ShapeInductionOptions {
+    /** Classes with fewer instances produce no shape. Default 2. */
+    minInstances?: number;
+    /** Only emit a property shape when >= this fraction of instances have it. Default 0.5. */
+    coverage?: number;
+}
+/**
+ * Propose NodeShapes by observing explicit instance data: for each class,
+ * per-property coverage, cardinality, datatypes, node kinds across its
+ * instances. PROPOSAL ONLY per docs/07 (shapes are builder-owned).
+ */
+declare function proposeShapes(store: InMemoryGraphStore, opts?: ShapeInductionOptions): Promise<NodeShape[]>;
+/**
+ * Adopt proposed shapes: each shape is validated against the CURRENT closure
+ * in isolation — a shape the existing data already violates is rejected with
+ * its violations (1:1 mapping, no guesswork), the clean ones are registered.
+ * Versioned adoption: migrateTBox({ shapes }) instead.
+ */
+declare function adoptShapes(store: InMemoryGraphStore, shapes: NodeShape[]): Promise<{
+    adopted: NodeShape[];
+    rejected: {
+        shape: NodeShape;
+        violations: string[];
+    }[];
+}>;
+/** review_ontology agent tool: inventory + gaps, straight from the store. */
+declare function reviewOntologyTool(store: InMemoryGraphStore): Tool<{}, OntologyReview>;
+/** propose_shapes agent tool: SHACL candidates induced from instance data. */
+declare function proposeShapesTool(store: InMemoryGraphStore, opts?: ShapeInductionOptions): Tool<{}, NodeShape[]>;
+
+/**
+ * Semantic layer. See docs/07-semantics-governance.md.
+ * In-memory store: RDFS-subset + OWL property axioms entailment with proofs,
+ * SHACL-subset validation, versioned CONSTRUCT-style rules, SPARQL-subset
+ * read tools, and GraphMemory. Remote SPARQL, entity linking + JSON-LD I/O,
+ * and TBox evolution live in sibling modules, re-exported here.
+ */
+interface Quad {
+    subject: string;
+    predicate: string;
+    object: string;
+    graph?: string;
+    /** Provenance: who vouched, source URI, valid-until. Required on agent writes. */
+    source?: string;
+    derivedFrom?: string;
+    rule?: string;
+}
+interface ShapeReport {
+    valid: boolean;
+    violations: {
+        message: string;
+        node?: string;
+        path?: string;
+    }[];
+}
+/** Minimal triple-store contract — N3 in-memory first, remote SPARQL later. */
+interface GraphStore {
+    add(quads: Quad[]): Promise<void>;
+    /**
+     * Match by pattern; null/undefined = wildcard (including the graph slot).
+     * Queries the entailment closure. A `graph` value selects ONE named
+     * graph — the same s/p/o CAN live in several graphs; identity includes it.
+     */
+    match(s?: string | null, p?: string | null, o?: string | null, g?: string | null): Promise<Quad[]>;
+    validate(quads: Quad[]): Promise<ShapeReport>;
+    /** Proof chain for an entailed fact: premises + rule id. Null for explicit facts. */
+    why(quad: Quad): Promise<{
+        premises: Quad[];
+        rule: string;
+    } | null>;
+}
+/** SHACL-subset shape: class-scoped property constraints. */
+interface PropertyShape {
+    path: string;
+    minCount?: number;
+    maxCount?: number;
+    datatype?: string;
+    nodeKind?: "iri" | "literal";
+    hasValue?: string;
+}
+interface NodeShape {
+    targetClass: string;
+    properties: PropertyShape[];
+}
+/** Versioned CONSTRUCT-style rule over triple patterns (?vars). */
+interface TriplePattern {
+    subject: string;
+    predicate: string;
+    object: string;
+}
+interface GraphRule {
+    id: string;
+    version?: string;
+    where: TriplePattern[];
+    construct: TriplePattern[];
+}
+interface StoreOptions {
+    shapes?: NodeShape[];
+    rules?: GraphRule[];
+}
+declare class InMemoryGraphStore implements GraphStore {
+    private quads;
+    private derivations;
+    private shapes;
+    private rules;
+    constructor(opts?: StoreOptions);
+    addShapes(...shapes: NodeShape[]): this;
+    addRules(...rules: GraphRule[]): this;
+    /** Registered SHACL shapes (carried to new stores by TBox migrations). */
+    ontologyShapes(): NodeShape[];
+    /** Registered CONSTRUCT rules (versioned with the ontology they encode). */
+    ontologyRules(): GraphRule[];
+    /** Identity includes the named graph: the same s/p/o in two graphs are two quads. */
+    private key;
+    add(quads: Quad[]): Promise<void>;
+    match(s?: string | null, p?: string | null, o?: string | null, g?: string | null): Promise<Quad[]>;
+    /** Structural + provenance check. Full SHACL engine lands in P1-sem. */
+    validate(quads: Quad[]): Promise<ShapeReport>;
+    why(quad: Quad): Promise<{
+        premises: Quad[];
+        rule: string;
+    } | null>;
+    /** Functional properties must have at most one value per subject (conflict, not a second fact). */
+    private checkFunctional;
+    /** SHACL-subset validation over a quad set. */
+    checkShapes(quads: Quad[]): ShapeReport;
+    private insert;
+    /**
+     * RDFS subset + OWL property axioms + versioned rules, to fixpoint:
+     * - RDFS-SUB-TRANS / RDFS-TYPE / RDFS-SUBPROP-TRANS / RDFS-SUBPROP / RDFS-DOMAIN / RDFS-RANGE
+     * - OWL-TRANSITIVE / OWL-SYMMETRIC / OWL-INVERSE (inverseOf both directions)
+     * - <ruleId>@<version> for each applied GraphRule (premises tracked for why())
+     */
+    private entailToFixpoint;
+    private applyOwl;
+    private applyRules;
+}
+interface PatternBinding {
+    vars: Map<string, string>;
+    quads: Quad[];
+}
+/** Conjunctive matching of patterns against quads (nested-loop join). */
+declare function matchPatterns(patterns: TriplePattern[], quads: Quad[]): PatternBinding[];
+declare function instantiate(term: string, vars: Map<string, string>): string;
+interface SparqlSelect {
+    variables: string[];
+    patterns: TriplePattern[];
+}
+/**
+ * Minimal SELECT parser: `SELECT ?a ?b WHERE { s p o . ... }`.
+ * Terms: ?vars, <iris>, prefixed names, "literals" (^^datatype/@lang ok).
+ * Anything else throws — this is a documented subset, not full SPARQL.
+ */
+declare function parseSelect(query: string): SparqlSelect;
+/** Execute a SELECT against the store closure. Returns variable bindings. */
+declare function executeSelect(store: GraphStore, query: string): Promise<Record<string, string>[]>;
+
+/** Read-only SPARQL SELECT over the entailment closure. */
+declare function sparqlSelectTool(store: GraphStore): Tool<{
+    query: string;
+}, Record<string, string>[]>;
+/** Ontology lookup: find classes/properties/labels matching a term. */
+declare function ontologyLookupTool(store: GraphStore): Tool<{
+    term: string;
+    limit?: number | undefined;
+}, {
+    subject: string;
+    predicate: string;
+    object: string;
+}[]>;
+declare const TurtleQuadSchema: z.ZodObject<{
+    subject: z.ZodString;
+    predicate: z.ZodString;
+    object: z.ZodString;
+    source: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    object: string;
+    source: string;
+    subject: string;
+    predicate: string;
+}, {
+    object: string;
+    source: string;
+    subject: string;
+    predicate: string;
+}>;
+/**
+ * Autonomous validated write: SHACL + provenance + functional checks run
+ * inside the store. Violations return as tool results (not throws) so the
+ * model repairs and retries on its own — autonomy without anarchy.
+ */
+declare function graphAddTool(store: GraphStore): Tool<{
+    quads: {
+        object: string;
+        source: string;
+        subject: string;
+        predicate: string;
+    }[];
+}, string | {
+    committed: number;
+    inferred: number;
+}>;
+type ClaimVerdict = "grounded" | "unknown" | "contradicted";
+/**
+ * Anti-hallucination primitive: is this triple in the closure (grounded),
+ * absent (unknown — do not assert), or clashing with a functional value
+ * (contradicted)? Ask before answering from memory.
+ */
+declare function claimCheckTool(store: GraphStore): Tool<{
+    object: string;
+    subject: string;
+    predicate: string;
+}, {
+    verdict: ClaimVerdict;
+    proof: {
+        premises: Quad[];
+        rule: string;
+    } | null;
+} | {
+    verdict: ClaimVerdict;
+    proof: {
+        existing: string[];
+        related?: undefined;
+    };
+} | {
+    verdict: ClaimVerdict;
+    proof: {
+        related: string[];
+        existing?: undefined;
+    } | null;
+}>;
+
+/**
+ * Session memory + long-term store in one:
+ * - load(): recent messages + top-k closure facts relevant to the latest
+ *   user turn (keyword overlap), rendered as a knowledge message.
+ * - save(): delegates to inner memory (extraction of triples from prose
+ *   stays model-driven via graph_add — never silent parsing).
+ * - exportState()/importState(): quads JSON for SessionManager snapshots (LTS).
+ */
+declare class GraphMemory implements Memory {
+    private store;
+    private inner;
+    private opts;
+    constructor(store: GraphStore, inner: Memory, opts?: {
+        facts?: number;
+    });
+    load(): Promise<ChatMessage[]>;
+    save(messages: ChatMessage[]): Promise<void>;
+    clear(): Promise<void>;
+    /** Serialize the closure for snapshots / long-term persistence. */
+    exportState(): Promise<{
+        quads: Quad[];
+    }>;
+    /** Restore a previously exported closure (facts become explicit again). */
+    importState(state: {
+        quads: Quad[];
+    }): Promise<void>;
+}
+
+declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Local token estimate — dependency-free approximation, not a BPE.
+ * Counts word-ish runs, numbers, CJK characters, and punctuation clusters
+ * separately (close to subword behavior on prose; ±30% on code).
+ * Calibrated so `estimateTokens("abcd") === 1`. Prefer provider usage
+ * metadata when available; use this for budgets and triggers only.
+ */
+declare function estimateTokens(text: string): number;
+/** Rough USD cost for usage against a per-1M-token price table. */
+declare function estimateCostUsd(usage: {
+    inputTokens: number;
+    outputTokens: number;
+}, price: {
+    inputPerMillion: number;
+    outputPerMillion: number;
+}): number;
+
+export { A2AClient, type A2AClientOptions, A2AServer, type A2AServerOptions, Agent, type AgentCard, AgentClient, type AgentClientOptions, AgentError, type AgentEvents, type AgentId, type AgentMiddleware, type AgentOptions, type AgentResult, AgentState, type AnthropicOptions, AnthropicProvider, type AnyMcpClient, AudioBlockSchema, type BackoffOptions, type Brand, type Budget, type ChatMessage, ChatMessageSchema, type Checkpointer, type ClaimVerdict, ClearToolUsesEdit, type ClearToolUsesOptions, CompactedMemory, type CompactionOptions, type CompleteOptions, type ConformanceCheck, type ConformanceReport, type ConformanceResult, type ConsoleEventsOptions, ConsoleSpanSink, type ContentBlock, ContentBlockSchema, type ConversationManager, type DoneEvent, EntityLinker, type EvalCase, type EvalExpect, type EvalScore, type ExecutedToolCall, FileBlockSchema, FileCheckpointer, FileMemory, type FrameworkConfig, type FrameworkFile, FrameworkFileSchema, GraphMemory, type GraphRule, type GraphStore, type HandoffSignal, type HitlDecideRequest, type HitlDecision, HitlInterrupt, type HookContext, type ImageBlock, ImageBlockSchema, InMemoryGraphStore, InMemoryMemory, InMemoryRetriever, InMemoryStorage, type InvocationState, JSONLD_PREFIXES, JsonlSpanSink, LABEL_PREDICATES, type LinkedEntity, type LoadedFrameworkFile, LocalFileStorage, type MappingDecision, type MappingProposal, MappingProposals, type MappingProposalsOptions, type McpClient, type McpClientOptions, McpHttpClient, McpStdioClient, type McpToolDef, type Memory, MemorySpanSink, type MigrationReport, type MigrationResult, MockModelProvider, type ModelCapability, type ModelCompletion, type ModelPrice, type ModelProvider, type ModelRequest, type NodeShape, NonStandardBlockSchema, NullConversationManager, OWL_VOCAB, type OllamaOptions, OllamaProvider, type OntologyReview, type OpenAICompatibleOptions, OpenAICompatibleProvider, type OrchestratedResult, type OrchestrationPlan, type OrchestrationStrategy, type OutputVersion, type PIIDetector, type PIIMatch, type PIIStrategy, type PatternBinding, type PromptTemplate, type PropertyShape, type Quad, type ReasoningBlock, ReasoningBlockSchema, RemoteSparqlAdapter, type RemoteSparqlOptions, type ResolvedAgentDef, type ResponseFormat, type ResponseFormatWire, type ResponseStrategy, type Result, type Retriever, type RetryFilter, type RetryMiddlewareOptions, type RunId, type RunOptions, type SandboxBackend, type SandboxOptions, type ScoredDoc, type ServedAgent, SessionManager, type SessionManagerOptions, type ShapeInductionOptions, type ShapeReport, type Skill, type SkillLoaderOptions, SkillRegistry, SlidingWindowConversationManager, type SlidingWindowOptions, type Snapshot, type SnapshotData, type SnapshotField, type Span, type SpanSink, type SparqlAuth, type SparqlRow, type SparqlSelect, type StepEvent, type Storage, type StoreOptions, type StreamEvent, SummarizingConversationManager, type SummarizingOptions, Swarm, type SwarmOptions, type SwarmResult, type SwarmStatus, type SwarmStreamEvent, TBOX_PREDICATES, type TBoxMigrationSpec, type TakeSnapshotOptions, type TermStat, type TextBlock, TextBlockSchema, type ThreadCheckpoint, type TimelineEntry, type TodoItem, type TokenBudgets, type TokenUsage, type Tool, ToolCallBlockSchema, type ToolCallEvent, type ToolCallRef, type ToolCallRequest, type ToolContext, type ToolName, ToolRegistry, ToolRejection, type ToolResult, type ToolResultEvent, type TriplePattern, TurtleQuadSchema, type WorkflowNode, type WorkflowOptions, __resetConfig, a2aAsTool, abPrompts, adoptShapes, assertCanHandle, assistant, backoffDelayMs, buildServedAgent, claimCheckTool, collectStream, connectMcpHttp, connectMcpStdio, consoleEvents, contextEditingMiddleware, createMiddleware, createSandboxBackend, createSubAgentMiddleware, defaultSummarize, defaultToResult, definePrompt, defineTool, deserializeMessages, discoverSkills, estimateCostUsd, estimateTokens, executeSelect, filesystemMiddleware, filesystemTools, getRetryable, graphAddTool, handleAgentRoute, hasImages, historyTokens, hitlKey, humanInTheLoopMiddleware, imagesOf, initChatModel, instantiate, jsonSchemaToZod, jsonldToQuads, linkEntityTool, llmToolSelectorMiddleware, loadConfig, loadEnvFile, loadFrameworkConfig, loadJsonl, loadPromptFile, loadSkillsInto, logError, matchGlob, matchPatterns, matchSkills, mcpToolsToFramework, messageTokens, migrateTBox, modelCallLimit, modelFallbackMiddleware, modelRetryMiddleware, ollama, ontologyLookupTool, parseSelect, parseSkillFile, parseStructured, piiMiddleware, policyFilterMiddleware, priceFor, printReport, proposeMappingTool, proposeShapes, proposeShapesTool, providerFromEnv, providerStrategy, quadsToJsonLd, readHandoffSignal, remoteSparqlTool, responseFormatJsonSchema, responseFormatName, retrievalTool, reviewOntology, reviewOntologyTool, runConformance, runEval, runJavascriptTool, runOrchestrated, runWithBudget, runWorkflow, scoreSkills, selectSnapshotFields, serializeMessages, serveFramework, sleep, sparqlRetriever, sparqlSelectTool, stampRetryable, summarizationMiddleware, supportsColor, supportsVision, system, textOf, todoListMiddleware, tokenize, toolCallLimitMiddleware, toolEmulatorMiddleware, toolResult, toolRetry, toolRetryMiddleware, toolStrategy, tracingEvents, trimDangling, usageCost, user, wireTextOf, withFileLock };