@dudko.dev/agent-web 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,835 @@
+import * as ai from 'ai';
+import { LanguageModel, ToolSet, Tool, ModelMessage, generateText, streamText, tool } from 'ai';
+import { z, ZodType } from 'zod';
+import { IDBPDatabase } from 'idb';
+
+interface StoredMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+    ts?: number;
+}
+/** Persists an agent session's transcript. Swap in any backend. */
+interface ContextStore {
+    load(sessionId: string): Promise<StoredMessage[]>;
+    append(sessionId: string, message: StoredMessage): Promise<void>;
+    replace(sessionId: string, messages: StoredMessage[]): Promise<void>;
+    clear(sessionId: string): Promise<void>;
+}
+/** Non-persistent fallback (tests, SSR, private mode). */
+declare class MemoryStore implements ContextStore {
+    private readonly data;
+    load(sessionId: string): Promise<StoredMessage[]>;
+    append(sessionId: string, message: StoredMessage): Promise<void>;
+    replace(sessionId: string, messages: StoredMessage[]): Promise<void>;
+    clear(sessionId: string): Promise<void>;
+}
+
+/**
+ * Providers the browser registry can resolve from a spec. This is deliberately
+ * a browser-safe subset of the Node sibling's list: Amazon Bedrock (SigV4
+ * signing), Google Vertex (ADC via google-auth-library) and Cloudflare
+ * (Worker bindings / process.env) are Node-only and omitted; Azure folds into
+ * `openai-compatible`. `web-llm` is the local WebGPU pseudo-provider (no API
+ * key). Any other runtime — Chrome/Edge built-in AI, a custom LanguageModel —
+ * is passed to the agent directly and never touches this registry.
+ */
+type ProviderType = 'openai' | 'anthropic' | 'google' | 'openai-compatible' | 'xai' | 'deepseek' | 'gateway' | 'web-llm';
+/** A model described by provider + id, resolved through the registry (+ vault). */
+interface ProviderModelSpec {
+    providerType: ProviderType;
+    /** Model id, e.g. "gpt-4o-mini", "claude-haiku-4-5", "Llama-3.2-3B-Instruct-q4f16_1-MLC". */
+    model: string;
+    /** Provider endpoint override. Required for `openai-compatible`; a proxy URL for the rest. */
+    baseURL?: string;
+    /** Id under which the API key is stored in the CredentialStore / vault. Preferred. */
+    credentialRef?: string;
+    /**
+     * Dev-only inline API key. Prefer `credentialRef` so the key lives encrypted
+     * in the vault, not on a long-lived config object. Using this logs a warning.
+     */
+    apiKey?: string;
+    /** Extra request headers merged into the provider factory (e.g. a proxy auth header). */
+    headers?: Record<string, string>;
+    /** Escape hatch spread into the SDK factory after baseURL / apiKey / headers. */
+    providerOptions?: Record<string, unknown>;
+}
+/**
+ * A per-stage override that inherits the base provider + credentials and
+ * changes only the fields it sets (typically just `model`). Distinguished from
+ * a full ProviderModelSpec by the absence of `providerType`.
+ */
+interface StageOverride {
+    model?: string;
+    baseURL?: string;
+    credentialRef?: string;
+    apiKey?: string;
+    headers?: Record<string, string>;
+    providerOptions?: Record<string, unknown>;
+}
+/** What a caller hands us for a model: a ready AI SDK model, or a spec to resolve. */
+type ModelInput = LanguageModel | ProviderModelSpec;
+/** A model input, plus the partial-override form usable for per-stage layering. */
+type StageInput = ModelInput | StageOverride;
+/** Outcome of resolving one stage: either a ready model, or a fully-resolved spec. */
+type ResolvedStage = {
+    type: 'direct';
+    model: LanguageModel;
+} | {
+    type: 'spec';
+    spec: ProviderModelSpec;
+};
+/** True for a ready AI SDK model: a gateway model-id string or a LanguageModelV* object. */
+declare const isDirectModel: (m: unknown) => m is LanguageModel;
+/** True for a full provider spec (carries the `providerType` discriminator). */
+declare const isProviderSpec: (m: unknown) => m is ProviderModelSpec;
+
+/**
+ * Default phase prompts. Each builder returns `{ system, prompt }` strings.
+ * Because the agent runs in two tool-modes, the builders switch on `ctx.mode`:
+ *
+ * - `native`   — the model calls tools / emits schema-constrained JSON via the
+ *   AI SDK, so the prompts describe the task and let the SDK enforce structure.
+ * - `prompted` — weak local models can't do that reliably, so the prompts spell
+ *   out an exact JSON shape and (for the executor) include a tool catalogue;
+ *   the output is salvaged by parse.ts.
+ *
+ * Override any builder via `BrowserAgentConfig.prompts`.
+ */
+type ToolCallMode = 'native' | 'prompted';
+interface PromptParts {
+    system: string;
+    prompt: string;
+}
+interface PlannerPromptContext {
+    goal: string;
+    state?: string;
+    toolCatalog: string;
+    mode: ToolCallMode;
+}
+interface ExecutorPromptContext {
+    goal: string;
+    state?: string;
+    step: string;
+    index: number;
+    total: number;
+    toolCatalog: string;
+    done: string[];
+    mode: ToolCallMode;
+}
+interface ReplannerPromptContext {
+    goal: string;
+    state?: string;
+    done: string[];
+    remaining: string[];
+    mode: ToolCallMode;
+}
+interface SynthesizerPromptContext {
+    goal: string;
+    state?: string;
+    done: string[];
+}
+interface Prompts {
+    planner(ctx: PlannerPromptContext): PromptParts;
+    executor(ctx: ExecutorPromptContext): PromptParts;
+    replanner(ctx: ReplannerPromptContext): PromptParts;
+    synthesizer(ctx: SynthesizerPromptContext): PromptParts;
+}
+declare const defaultPrompts: Prompts;
+/** Prepend a host-supplied systemPrompt to a phase system prompt, if present. */
+declare const withSystem: (base: string, extra?: string) => string;
+
+interface VaultOptions {
+    /** Database name, forwarded to the shared IDB owner (default 'agent-web'). */
+    dbName?: string;
+}
+/**
+ * Encrypted key/value secret store backed by IndexedDB. Values are encrypted at
+ * rest with the non-extractable AES-GCM vault key (see crypto.ts).
+ *
+ * ── THREAT MODEL (read before shipping any app-owned key to a browser) ──
+ * This vault PROTECTS secrets **at rest** — an IndexedDB / disk dump yields
+ * only ciphertext — and against **casual DevTools inspection** — no plaintext
+ * key is stored, and the AES key cannot be exported even by in-page script.
+ *
+ * It does **NOT** defend against **active XSS on your origin**: any script that
+ * already runs on the page can call `getSecret()`, or use the live `CryptoKey`
+ * to decrypt. Browser storage is not a secrets manager.
+ *
+ * Therefore this vault is for the **end user's OWN key on their OWN device**
+ * (bring-your-own-key). A shared, app-owned key must NEVER reach the client —
+ * put it behind a server proxy (`ProviderModelSpec.baseURL`) or the Vercel AI
+ * Gateway instead.
+ */
+declare class IndexedDBVault {
+    private readonly dbName?;
+    constructor(opts?: VaultOptions);
+    private key;
+    /** Encrypt and store a secret string under `id`. */
+    setSecret(id: string, value: string): Promise<void>;
+    /** Fetch and decrypt a secret, or undefined if absent. */
+    getSecret(id: string): Promise<string | undefined>;
+    deleteSecret(id: string): Promise<void>;
+    listSecretIds(): Promise<string[]>;
+}
+
+/**
+ * The seam the provider registry uses to fetch API keys at model-build time.
+ * Swap in any backend: the encrypted vault (default), an in-memory map (tests /
+ * SSR), or a `fetch` to your own short-lived-token endpoint.
+ */
+interface CredentialStore {
+    getApiKey(ref: string): Promise<string | undefined>;
+    setApiKey(ref: string, key: string): Promise<void>;
+    deleteApiKey(ref: string): Promise<void>;
+}
+/** Default CredentialStore: encrypted, IndexedDB-backed (see IndexedDBVault). */
+declare class VaultCredentialStore implements CredentialStore {
+    private readonly vault;
+    constructor(opts?: VaultOptions);
+    getApiKey(ref: string): Promise<string | undefined>;
+    setApiKey(ref: string, key: string): Promise<void>;
+    deleteApiKey(ref: string): Promise<void>;
+}
+/** Non-persistent CredentialStore for tests / SSR / ephemeral sessions. */
+declare class MemoryCredentialStore implements CredentialStore {
+    private readonly map;
+    constructor(initial?: Record<string, string>);
+    getApiKey(ref: string): Promise<string | undefined>;
+    setApiKey(ref: string, key: string): Promise<void>;
+    deleteApiKey(ref: string): Promise<void>;
+}
+
+/**
+ * The canonical tool shape is the AI SDK `Tool` — the same object the native
+ * tool-calling path passes straight to `streamText({ tools })`, and the same
+ * shape MCP tools take. We add one optional field, `promptHint`, a short
+ * human-readable parameter hint (e.g. "{ text: string, x?: number }") used only
+ * by the prompted/salvage path when it renders the tool catalogue into a text
+ * prompt for weak local models.
+ */
+type AgentTool = Tool & {
+    promptHint?: string;
+};
+/** A named collection of tools — a plain AI SDK ToolSet, usable directly. */
+type AgentToolSet = ToolSet;
+/** Read the optional promptHint attached by defineTool, if any. */
+declare const promptHintOf: (tool: Tool) => string | undefined;
+
+/** Force a tool-calling strategy, or let the agent pick per model ('auto'). */
+type ToolMode = 'auto' | 'native' | 'prompted';
+/**
+ * 'all'           — the executor sees the full ToolSet on every step.
+ * 'plan-narrowed' — the executor sees only a step's suggestedTools (the planner
+ *                   must populate them). Empty means a reasoning-only step.
+ */
+type ToolSelectionStrategy = 'all' | 'plan-narrowed';
+/** Per-phase generation budgets (max output tokens). */
+interface PhaseBudgets {
+    planner?: number;
+    executor?: number;
+    replanner?: number;
+    synthesizer?: number;
+}
+interface BrowserAgentConfig {
+    /** The default (executor) model: a ready AI SDK model, or a ProviderModelSpec to resolve. */
+    model: ModelInput;
+    /** Optional per-stage model overrides. A partial override inherits base provider/creds. */
+    planner?: StageInput;
+    synthesizer?: StageInput;
+    /** Fetches API keys for ProviderModelSpec models. Default: none (inline keys only). */
+    credentials?: CredentialStore;
+    /** Propagated to the openai-compatible provider name and the MCP client. */
+    clientName?: string;
+    /** Host tools the executor may call (an AI SDK ToolSet; use defineTool). */
+    tools?: AgentToolSet;
+    availableTools?: string[];
+    excludedTools?: string[];
+    /** Force native/prompted tool-calling; 'auto' picks per model (default 'auto'). */
+    toolMode?: ToolMode;
+    toolSelectionStrategy?: ToolSelectionStrategy;
+    /** Prepended to every phase's system prompt. */
+    systemPrompt?: string;
+    /** Override any phase prompt builder. */
+    prompts?: Partial<Prompts>;
+    /** Serialize the host's current world state into prompt context (grounding). */
+    describeState?: () => string | Promise<string>;
+    /** Persist the transcript (e.g. new IndexedDBStore()). */
+    memory?: ContextStore;
+    sessionId?: string;
+    /** Hard cap on executed steps incl. replans (default 8). */
+    maxIterations?: number;
+    /** Cap on LLM steps inside a single native executor call (default 4). */
+    maxStepsPerTask?: number;
+    /** Cap on replanner "revise" decisions per run (default 2). */
+    maxRevisions?: number;
+    /** Per-call timeout so a hang can't freeze a run (default 120000). */
+    chatTimeoutMs?: number;
+    budgets?: PhaseBudgets;
+    temperature?: number;
+    /** Replan after a blocked/failed step (default true). */
+    replan?: boolean;
+    /** Write a final natural-language summary (default true). */
+    synthesize?: boolean;
+    /** Compress stored history past this many chars (0 = off, default 12000). */
+    compressAfterChars?: number;
+}
+interface ResolvedConfig {
+    clientName: string;
+    sessionId: string;
+    toolMode: ToolMode;
+    toolSelectionStrategy: ToolSelectionStrategy;
+    maxIterations: number;
+    maxStepsPerTask: number;
+    maxRevisions: number;
+    chatTimeoutMs: number;
+    budgets: Required<PhaseBudgets>;
+    temperature: number | undefined;
+    replan: boolean;
+    synthesize: boolean;
+    compressAfterChars: number;
+}
+declare const resolveConfig: (c: BrowserAgentConfig) => ResolvedConfig;
+
+/** A single step of a plan. Mirrors the Node sibling's IPlanStep. */
+interface IPlanStep {
+    id: string;
+    description: string;
+    expectedOutcome?: string;
+    /** Tools the planner thinks this step needs (drives 'plan-narrowed' selection). */
+    suggestedTools?: string[];
+    /** Set by the pipeline when suggestedTools were named but all were unknown. */
+    requiresTools?: boolean;
+}
+interface IPlan {
+    thought: string;
+    steps: IPlanStep[];
+}
+interface IUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+}
+interface IToolCall {
+    name: string;
+    input: unknown;
+    output: unknown;
+    ok: boolean;
+}
+interface IStepResult {
+    step: IPlanStep;
+    summary: string;
+    toolCalls: IToolCall[];
+    /** True when the executor signalled it could not complete the step ([BLOCKER]). */
+    blocked: boolean;
+}
+
+type ReplanMode = 'continue' | 'revise' | 'finish';
+type Phase = 'plan' | 'execute' | 'replan' | 'synthesize';
+/**
+ * Everything the agent does is streamed as a typed event so any UI (or none)
+ * can render progress. The final answer arrives as a `final` event; there is no
+ * built-in rendering. This is a browser-focused subset of the Node sibling's
+ * event taxonomy (no persistence/otel events), plus `model.load` for WebLLM
+ * weight-download progress.
+ */
+type AgentEvent = {
+    type: 'run.start';
+    goal: string;
+} | {
+    type: 'model.load';
+    progress: number;
+    text: string;
+} | {
+    type: 'plan.thought-delta';
+    delta: string;
+} | {
+    type: 'plan.step-added';
+    step: IPlanStep;
+    index: number;
+} | {
+    type: 'plan.created';
+    plan: IPlan;
+} | {
+    type: 'plan.revised';
+    plan: IPlan;
+    reason: string;
+} | {
+    type: 'step.start';
+    step: IPlanStep;
+    index: number;
+    total: number;
+} | {
+    type: 'step.text-delta';
+    step: IPlanStep;
+    delta: string;
+} | {
+    type: 'step.tool-call';
+    step: IPlanStep;
+    name: string;
+    input: unknown;
+} | {
+    type: 'step.tool-result';
+    step: IPlanStep;
+    name: string;
+    output: unknown;
+    ok: boolean;
+} | {
+    type: 'step.complete';
+    step: IPlanStep;
+    result: IStepResult;
+} | {
+    type: 'replan.decision';
+    mode: ReplanMode;
+    reason: string;
+} | {
+    type: 'final.text-delta';
+    delta: string;
+} | {
+    type: 'final';
+    text: string;
+} | {
+    type: 'usage';
+    phase: Phase;
+    usage: IUsage;
+} | {
+    type: 'retry';
+    phase: Phase;
+    attempt: number;
+    error: string;
+} | {
+    type: 'stopped';
+} | {
+    type: 'error';
+    phase: Phase | 'run';
+    error: string;
+};
+type AgentEventHandler = (event: AgentEvent) => void;
+
+interface RunOptions {
+    onEvent?: AgentEventHandler;
+    signal?: AbortSignal;
+    /** Override the config's sessionId for this run. */
+    sessionId?: string;
+}
+interface RunResult {
+    goal: string;
+    final: string;
+    plan: IPlan;
+    trace: IStepResult[];
+    steps: number;
+    /** Total successful tool calls across the run. */
+    applied: number;
+    stopped: boolean;
+    usage: IUsage;
+}
+interface Agent {
+    run(goal: string, opts?: RunOptions): Promise<RunResult>;
+    /** The resolved models, for hosts that want to reuse them (e.g. warm-up). */
+    readonly models: {
+        planner: LanguageModel;
+        executor: LanguageModel;
+        synthesizer: LanguageModel;
+    };
+}
+/**
+ * Create a headless plan → execute → replan → synthesize agent. Models are
+ * resolved eagerly (dynamic provider imports + vault key fetch), so this is
+ * async. Each `run` streams typed AgentEvents for any UI to render.
+ */
+declare const createAgent: (config: BrowserAgentConfig) => Promise<Agent>;
+
+/**
+ * Structured-output schemas for the native path (generateObject). Kept free of
+ * `.max()`/`.min()` constraints — some providers reject or mis-handle them in
+ * JSON-schema mode; we cap/clean in code instead (see parse.ts normalizeSteps).
+ */
+declare const PlanStepSchema: z.ZodObject<{
+    description: z.ZodString;
+    expectedOutcome: z.ZodOptional<z.ZodString>;
+    suggestedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+declare const PlanSchema: z.ZodObject<{
+    thought: z.ZodString;
+    steps: z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        expectedOutcome: z.ZodOptional<z.ZodString>;
+        suggestedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const ReplanSchema: z.ZodObject<{
+    decision: z.ZodEnum<{
+        continue: "continue";
+        revise: "revise";
+        finish: "finish";
+    }>;
+    reason: z.ZodString;
+    plan: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type PlanShape = z.infer<typeof PlanSchema>;
+type ReplanShape = z.infer<typeof ReplanSchema>;
+
+/** Everything the phase functions (planner/executor/replanner/synthesizer) share. */
+interface AgentContext {
+    config: ResolvedConfig;
+    raw: BrowserAgentConfig;
+    plannerModel: LanguageModel;
+    executorModel: LanguageModel;
+    synthesizerModel: LanguageModel;
+    /** Tool-mode for the planner/replanner (from the planner model). */
+    plannerMode: ToolCallMode;
+    /** Tool-mode for the executor (from the executor model). */
+    executorMode: ToolCallMode;
+    tools: AgentToolSet;
+    toolCatalog: string;
+    prompts: Prompts;
+    emit: (event: AgentEvent) => void;
+    signal?: AbortSignal;
+    /** Current world state for grounding, or undefined when no describeState is configured. */
+    state: () => Promise<string | undefined>;
+}
+
+/**
+ * Build the initial plan. Native mode uses generateObject(PlanSchema); prompted
+ * mode salvages `{ reply, plan }` from plain text. Native failures (a weak model
+ * that can't satisfy the schema) fall back to the prompted parse rather than
+ * throwing, so the run degrades gracefully. An empty `steps` list signals the
+ * runner to answer directly (greeting / question / unclear).
+ */
+declare const createPlan: (ctx: AgentContext, goal: string) => Promise<{
+    plan: IPlan;
+    usage: IUsage;
+}>;
+
+/**
+ * Split the executor's reply into a clean summary and a structural `blocked`
+ * flag. The [BLOCKER] sentinel — emitted by the executor when it can't complete
+ * a step — is language-agnostic and drives the replanner; we strip every copy
+ * so it never leaks into downstream prompts.
+ */
+declare const splitBlocker: (raw: string) => {
+    summary: string;
+    blocked: boolean;
+};
+/** Execute one plan step: run the tool loop (native or prompted) and emit events. */
+declare const executeStep: (ctx: AgentContext, goal: string, step: IPlanStep, index: number, total: number, done: string[]) => Promise<{
+    result: IStepResult;
+    usage: IUsage;
+}>;
+/** The replanner runs when a step was blocked or any of its tool calls failed. */
+declare const shouldReplan: (result: IStepResult) => boolean;
+
+/**
+ * Robust parsing of model output. Small in-browser models emit JSON wrapped in
+ * prose or code fences, truncate it mid-token when they loop, or drift to plain
+ * text. Every parser here is defensive: it salvages what it can and NEVER
+ * throws, and it never surfaces raw JSON as user-facing text. This is the
+ * backbone of the "prompted" tool-mode (see tools/mode.ts).
+ */
+/** A tool the executor asked to run. */
+interface RawAction {
+    tool: string;
+    args: Record<string, unknown>;
+}
+type ReplanDecision = 'continue' | 'revise' | 'finish';
+/** True when a string is (or is dominated by) raw JSON — kept out of the UI. */
+declare const looksLikeJson: (s: string) => boolean;
+/** Trim, drop empties, de-duplicate (case-insensitive), cap length. */
+declare const normalizeSteps: (arr: unknown, cap?: number) => string[];
+interface PlannerResult {
+    reply: string;
+    plan: string[];
+}
+declare const parsePlannerResponse: (raw: string) => PlannerResult;
+interface ExecutorResult {
+    reply: string;
+    actions: RawAction[];
+}
+declare const parseExecutorResponse: (raw: string) => ExecutorResult;
+interface ReplannerResult {
+    decision: ReplanDecision;
+    reason: string;
+    plan: string[];
+}
+declare const parseReplannerResponse: (raw: string) => ReplannerResult;
+/** Extracts a clean human sentence, never raw JSON. */
+declare const parsePlainText: (raw: string) => string;
+
+interface ReplanOutcome {
+    decision: ReplanDecision;
+    reason: string;
+    /** Replacement remaining steps (descriptions) when decision is 'revise'. */
+    plan: string[];
+    usage: IUsage;
+}
+/**
+ * Decide whether to continue, revise the remaining plan, or finish, after a
+ * blocked/failed step. Native mode uses generateObject(ReplanSchema); prompted
+ * mode salvages the decision from text. Any failure degrades to 'continue' so a
+ * flaky replanner never aborts the run.
+ */
+declare const decideReplan: (ctx: AgentContext, goal: string, done: string[], remaining: string[]) => Promise<ReplanOutcome>;
+
+/**
+ * Write the final natural-language summary of what the run accomplished. Plain
+ * text only (parsePlainText strips any stray JSON). Falls back to a default
+ * sentence if the model returns nothing usable.
+ */
+declare const synthesizeAnswer: (ctx: AgentContext, goal: string, done: string[]) => Promise<{
+    text: string;
+    usage: IUsage;
+}>;
+
+/**
+ * Resolve one stage to either a ready model or a fully-resolved spec, layering
+ * an optional override on the base:
+ *  - a direct model (or full spec) override wins outright;
+ *  - a partial StageOverride inherits the base provider + credentials, changing
+ *    only the fields it sets (e.g. `{ model: 'gpt-4o-mini' }`);
+ *  - a full-spec override that switches provider MUST carry its own key
+ *    (credentialRef/apiKey) — inheriting a key across vendors is a footgun.
+ */
+declare const resolveStage: (base: ModelInput, override: StageInput | undefined, stageName: string) => ResolvedStage;
+/**
+ * Turn a resolved stage into an AI SDK `LanguageModel`. Direct models pass
+ * through untouched; specs are built by dynamically importing the provider's
+ * optional-peer package and fetching the API key from the CredentialStore.
+ */
+declare const buildModelFromStage: (resolved: ResolvedStage, credentials?: CredentialStore, clientName?: string) => Promise<LanguageModel>;
+/** Resolve a single ModelInput straight to a LanguageModel (no per-stage layering). */
+declare const resolveModel: (input: ModelInput, credentials?: CredentialStore, clientName?: string) => Promise<LanguageModel>;
+
+/** WebGPU feature-detect — WebLLM requires it. Call before offering local models. */
+declare const isWebGPUAvailable: () => boolean;
+interface WebLLMModelOptions {
+    /**
+     * Progress callback for weight download / engine init. `report.progress` is
+     * 0..1. Forwarded to WebLLM's `initProgressCallback`.
+     */
+    initProgressCallback?: (report: {
+        progress: number;
+        text: string;
+    }) => void;
+    /** Any other @browser-ai/web-llm setting (temperature, worker handler, …). */
+    [k: string]: unknown;
+}
+/**
+ * Build an AI SDK `LanguageModel` backed by WebLLM (WebGPU) via the community
+ * provider `@browser-ai/web-llm` (an optional peer, dynamically imported so it
+ * is code-split and never loads until a local model is actually used). Accepts
+ * any WebLLM prebuilt model id, e.g. "Llama-3.2-3B-Instruct-q4f16_1-MLC".
+ */
+declare const createWebLLMModel: (model: string, options?: WebLLMModelOptions) => Promise<LanguageModel>;
+
+/** Whether native tool-calling is reliable enough to be the default for a provider. */
+declare const supportsNativeTools: (p: ProviderType) => boolean;
+/** Whether native structured output (generateObject) is the default for a provider. */
+declare const supportsStructuredOutput: (p: ProviderType) => boolean;
+/**
+ * Whether calling this provider straight from a browser origin with a BYOK key
+ * is expected to work (CORS + browser-access policy). Hosts can use this to
+ * warn users before a direct call fails.
+ *
+ * - `google`: Gemini's endpoint is CORS-enabled — the most reliable direct BYOK path.
+ * - `gateway` / `openai-compatible`: the host controls the endpoint / CORS.
+ * - `anthropic`: works, but only with the direct-browser-access header, which
+ *   the registry injects automatically.
+ * - `openai`: api.openai.com does NOT reliably send CORS for browser calls —
+ *   route through a proxy `baseURL` or the gateway.
+ * - `xai` / `deepseek`: unreliable from the browser; prefer a proxy.
+ */
+declare const directBrowserOk: (p: ProviderType) => boolean;
+
+/**
+ * Fetch (or lazily create) the vault's AES-GCM key. The key is generated
+ * NON-EXTRACTABLE and stored as a live `CryptoKey` in IndexedDB — a CryptoKey
+ * is structured-cloneable, so it persists across reloads WITHOUT its raw bytes
+ * ever being exposed to JavaScript. Not even in-page script can read it out; it
+ * can only be used to encrypt / decrypt. That is what makes at-rest storage of
+ * the secrets meaningful (see IndexedDBVault's threat model).
+ */
+declare const getOrCreateVaultKey: (dbName?: string) => Promise<CryptoKey>;
+interface EncryptedBlob {
+    /** 96-bit random IV, fresh per write. */
+    iv: Uint8Array;
+    ciphertext: ArrayBuffer;
+}
+/** Encrypt a JSON-serialisable value with a fresh 96-bit IV (AES-GCM). */
+declare const encryptJSON: (key: CryptoKey, value: unknown) => Promise<EncryptedBlob>;
+/** Decrypt a blob produced by encryptJSON. Throws if the key or blob don't match. */
+declare const decryptJSON: <T = unknown>(key: CryptoKey, blob: EncryptedBlob) => Promise<T>;
+
+interface AgentWebDBOptions {
+    /** Database name (default 'agent-web'). Use a distinct name to isolate apps. */
+    dbName?: string;
+}
+declare const KEYS_STORE = "keys";
+declare const SECRETS_STORE = "secrets";
+declare const SESSIONS_STORE = "sessions";
+/**
+ * The single owner of the IndexedDB database. Every persistent store — the
+ * non-extractable crypto key, encrypted secrets, and session transcripts —
+ * lives under ONE database name + version. Centralising `openDB` here prevents
+ * the classic bug where two modules open the same DB name with different store
+ * sets and the second call throws a VersionError.
+ */
+declare const openAgentWebDB: (opts?: AgentWebDBOptions) => Promise<IDBPDatabase>;
+
+/** Options shared by the low-level generation helpers. Provide `prompt` OR `messages`. */
+interface GenerateOptions {
+    system?: string;
+    prompt?: string;
+    messages?: ModelMessage[];
+    tools?: ToolSet;
+    maxOutputTokens?: number;
+    temperature?: number;
+    abortSignal?: AbortSignal;
+    /** Time-box the call; combined with `abortSignal` (0/undefined = no timeout). */
+    timeoutMs?: number;
+}
+/**
+ * One-shot text generation. Thin, provider-agnostic wrapper over the AI SDK's
+ * `generateText` — the same call works against a cloud model, a local WebLLM
+ * model, or Chrome/Edge built-in AI. Returns the full AI SDK result (`.text`,
+ * `.usage`, `.toolCalls`, `.steps`, …).
+ */
+declare const generate: (model: LanguageModel, opts?: GenerateOptions) => ReturnType<typeof generateText>;
+/** Streaming text generation. Returns the AI SDK `streamText` result (`.textStream`, `.fullStream`). */
+declare const stream: (model: LanguageModel, opts?: GenerateOptions) => ReturnType<typeof streamText>;
+/**
+ * Structured output constrained to a Zod schema, via the AI SDK's
+ * `generateObject`. Cloud models and WebLLM both support this; tiny local
+ * models can be unreliable — the agent's prompted mode is the fallback.
+ * Returns the AI SDK result (`.object`, `.usage`).
+ */
+declare const generateStructured: <OBJECT>(model: LanguageModel, schema: ZodType<OBJECT>, opts?: GenerateOptions) => Promise<ai.GenerateObjectResult<(OBJECT extends string ? "enum" : "object") extends infer T ? T extends (OBJECT extends string ? "enum" : "object") ? T extends "array" ? OBJECT[] : OBJECT : never : never>>;
+
+interface ToolLoopCallbacks {
+    onTextDelta?: (delta: string) => void;
+    onToolCall?: (name: string, input: unknown) => void;
+    onToolResult?: (name: string, output: unknown, ok: boolean) => void;
+}
+interface ToolLoopOptions {
+    /** 'native' = SDK function-calling; 'prompted' = parse JSON out of plain text. */
+    mode: 'native' | 'prompted';
+    system?: string;
+    prompt?: string;
+    messages?: ModelMessage[];
+    /** In native mode: the callable tools. In prompted mode: used to dispatch salvaged calls. */
+    tools: ToolSet;
+    /** Native mode: restrict callable tools to these names (plan-narrowed). */
+    activeTools?: string[];
+    /** Native mode: cap on internal tool-calling steps (default 4). */
+    maxSteps?: number;
+    maxOutputTokens?: number;
+    temperature?: number;
+    abortSignal?: AbortSignal;
+    timeoutMs?: number;
+    callbacks?: ToolLoopCallbacks;
+}
+interface ToolLoopResult {
+    text: string;
+    toolCalls: IToolCall[];
+    usage: IUsage;
+}
+/**
+ * Run one round of tool-calling in whichever mode the model needs, returning a
+ * normalised result. Native mode streams the SDK's multi-step function-calling;
+ * prompted mode does a single generation, salvages a `{ reply, actions }` JSON
+ * from the text, and dispatches each action through the tool's own execute.
+ * Both call the exact same tool implementations.
+ */
+declare const runToolLoop: (model: LanguageModel, opts: ToolLoopOptions) => Promise<ToolLoopResult>;
+
+/** Normalise the AI SDK usage shape (fields can be undefined) into IUsage. */
+declare const normalizeUsage: (u?: {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+}) => IUsage;
+
+type ToolConfig = Parameters<typeof tool>[0];
+/**
+ * Define a host tool. Thin wrapper over the AI SDK `tool()`: pass a
+ * `description`, an `inputSchema` (a Zod schema or the result of `jsonSchema()`),
+ * and an `execute` function. The returned tool works unchanged on the native
+ * tool-calling path.
+ *
+ * Optionally add `promptHint` — a short parameter hint like
+ * "{ text: string, x?: number }" — which the prompted/salvage path shows to
+ * weak local models that can't do native function-calling.
+ *
+ * @example
+ *   const tools = {
+ *     add_text: defineTool({
+ *       description: 'Add a text block to the page.',
+ *       inputSchema: z.object({ text: z.string(), x: z.number().optional() }),
+ *       promptHint: '{ text: string, x?: number }',
+ *       execute: async ({ text, x }) => addTextBlock(text, x),
+ *     }),
+ *   }
+ */
+declare const defineTool: (config: ToolConfig & {
+    promptHint?: string;
+}) => AgentTool;
+
+/**
+ * Render a ToolSet into a plain-text catalogue for the prompted/salvage path:
+ * `- name(hint): description`. The hint comes from `defineTool({ promptHint })`
+ * when present; weak local models lean on it to fill args correctly.
+ */
+declare const renderCatalog: (tools: AgentToolSet) => string;
+interface DispatchContext {
+    abortSignal?: AbortSignal;
+    messages?: ModelMessage[];
+    toolCallId?: string;
+}
+/**
+ * Validate and execute a single salvaged tool call against the ToolSet, using
+ * the tool's OWN `execute` and `inputSchema` — the identical implementation the
+ * native path calls. Unknown tools, schema-invalid args, and thrown errors all
+ * become a failed IToolCall rather than throwing.
+ */
+declare const dispatch: (action: RawAction, tools: ToolSet, ctx?: DispatchContext) => Promise<IToolCall>;
+
+/**
+ * Decide the tool-calling strategy for a resolved model. An explicit
+ * config.toolMode of 'native'/'prompted' always wins; 'auto' (default) inspects
+ * the model's provider id — local/on-device runtimes → 'prompted', cloud → 'native'.
+ */
+declare const selectToolMode: (model: LanguageModel, mode?: ToolMode) => "native" | "prompted";
+
+interface IndexedDBStoreOptions {
+    /** Database name, forwarded to the shared IDB owner (default 'agent-web'). */
+    dbName?: string;
+}
+/**
+ * IndexedDB-backed transcript store — one record (message array) per session,
+ * in the shared `sessions` object store (see storage/db.ts). Also exposes
+ * session utilities: list and delete.
+ */
+declare class IndexedDBStore implements ContextStore {
+    private readonly dbName?;
+    constructor(opts?: IndexedDBStoreOptions);
+    load(sessionId: string): Promise<StoredMessage[]>;
+    replace(sessionId: string, messages: StoredMessage[]): Promise<void>;
+    append(sessionId: string, message: StoredMessage): Promise<void>;
+    clear(sessionId: string): Promise<void>;
+    /** List all stored session ids. */
+    listSessions(): Promise<string[]>;
+}
+
+interface CompressOptions {
+    /** Compress once the transcript exceeds this many characters (0 = never). */
+    maxChars?: number;
+    /** How many most-recent messages to keep verbatim. */
+    keepRecent?: number;
+}
+/**
+ * When the transcript grows too long, summarise everything except the last
+ * `keepRecent` messages into a single system message (via the model), so the
+ * session stays within the model's context window. Returns the same array
+ * unchanged when no compression is needed; never throws.
+ */
+declare const compressHistory: (messages: StoredMessage[], model: LanguageModel, opts?: CompressOptions) => Promise<StoredMessage[]>;
+
+export { type Agent, type AgentContext, type AgentEvent, type AgentEventHandler, type AgentTool, type AgentToolSet, type AgentWebDBOptions, type BrowserAgentConfig, type CompressOptions, type ContextStore, type CredentialStore, type EncryptedBlob, type ExecutorPromptContext, type ExecutorResult, type GenerateOptions, type IPlan, type IPlanStep, type IStepResult, type IToolCall, type IUsage, IndexedDBStore, type IndexedDBStoreOptions, IndexedDBVault, KEYS_STORE, MemoryCredentialStore, MemoryStore, type ModelInput, type Phase, type PhaseBudgets, PlanSchema, type PlanShape, PlanStepSchema, type PlannerPromptContext, type PlannerResult, type PromptParts, type Prompts, type ProviderModelSpec, type ProviderType, type RawAction, type ReplanDecision, type ReplanMode, ReplanSchema, type ReplanShape, type ReplannerPromptContext, type ReplannerResult, type ResolvedConfig, type ResolvedStage, type RunOptions, type RunResult, SECRETS_STORE, SESSIONS_STORE, type StageInput, type StageOverride, type StoredMessage, type SynthesizerPromptContext, type ToolCallMode, type ToolLoopCallbacks, type ToolLoopOptions, type ToolLoopResult, type ToolMode, type ToolSelectionStrategy, VaultCredentialStore, type VaultOptions, type WebLLMModelOptions, buildModelFromStage, compressHistory, createAgent, createPlan, createWebLLMModel, decideReplan, decryptJSON, defaultPrompts, defineTool, directBrowserOk, dispatch, encryptJSON, executeStep, generate, generateStructured, getOrCreateVaultKey, isDirectModel, isProviderSpec, isWebGPUAvailable, looksLikeJson, normalizeSteps, normalizeUsage, openAgentWebDB, parseExecutorResponse, parsePlainText, parsePlannerResponse, parseReplannerResponse, promptHintOf, renderCatalog, resolveConfig, resolveModel, resolveStage, runToolLoop, selectToolMode, shouldReplan, splitBlocker, stream, supportsNativeTools, supportsStructuredOutput, synthesizeAnswer, withSystem };