@dudko.dev/agent-web 0.0.19 → 0.0.21

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as ai from 'ai';
-import { LanguageModel, ToolSet, Tool, ModelMessage, generateText, streamText } from 'ai';
+import { LanguageModel, ToolSet, Tool, FilePart, SystemModelMessage, ModelMessage, generateText, streamText } from 'ai';
 import { V as VaultOptions } from './vault-BHlMmKXM.js';
 export { I as IndexedDBVault } from './vault-BHlMmKXM.js';
 import { z, ZodType } from 'zod';
@@ -23,6 +23,12 @@ interface IUsage {
     inputTokens: number;
     outputTokens: number;
     totalTokens: number;
+    /** Output tokens spent thinking (a subset of outputTokens). */
+    reasoningTokens?: number;
+    /** Input tokens served from the provider's prompt cache. */
+    cachedInputTokens?: number;
+    /** Input tokens written to the provider's prompt cache. */
+    cacheWriteTokens?: number;
 }
 interface IToolCall {
     name: string;
@@ -38,6 +44,126 @@ interface IStepResult {
     blocked: boolean;
 }
 
+/**
+ * Thinking (a.k.a. reasoning) activation, portable across providers.
+ *
+ * The AI SDK exposes a top-level `reasoning` level on every call and translates
+ * it to each provider's native API (OpenAI reasoning effort, Anthropic adaptive
+ * thinking, Gemini thinking level, …). An exact token budget is not portable,
+ * so a `budgetTokens` is mapped to the provider-specific options of the two
+ * providers that take one (Anthropic, Google); provider options win over the
+ * portable level by the SDK's precedence rules.
+ *
+ * WebLLM ignores the portable level: its thinking models (Qwen3) are switched
+ * by `extra_body.enable_thinking`, so every setting carries that too.
+ */
+type ThinkingLevel = 'provider-default' | 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+interface ThinkingConfig {
+    /** Portable effort level (default 'medium'). */
+    level?: ThinkingLevel;
+    /** Exact thinking budget — mapped to Anthropic `thinking` / Google `thinkingConfig`. */
+    budgetTokens?: number;
+    /** Stream the model's thoughts where the provider can (default true). */
+    includeThoughts?: boolean;
+}
+/**
+ * `false`/undefined → leave the provider default alone; `true` → 'medium';
+ * a level string → that level; an object → full control.
+ */
+type ThinkingSetting = boolean | ThinkingLevel | ThinkingConfig;
+type ThinkingStage = 'planner' | 'executor' | 'replanner' | 'synthesizer';
+/** Provider-keyed options, the shape of the AI SDK's `providerOptions`. */
+type ProviderOptionsMap = Record<string, Record<string, unknown>>;
+interface ResolvedThinking {
+    reasoning?: ThinkingLevel;
+    providerOptions?: ProviderOptionsMap;
+}
+/**
+ * Turn a thinking setting into call options: the portable `reasoning` level
+ * plus the provider-specific extras for an exact budget or streamed thoughts.
+ * Pure — unit-tested.
+ */
+declare const resolveThinking: (setting: ThinkingSetting | undefined) => ResolvedThinking;
+/** The setting that applies to one stage: a stage entry wins over the top level. */
+declare const thinkingFor: (stage: ThinkingStage, top: ThinkingSetting | undefined, perStage: Partial<Record<ThinkingStage, ThinkingSetting>> | undefined) => ThinkingSetting | undefined;
+/**
+ * Deep-merge provider-option maps left to right (later wins). Returns undefined
+ * when there is nothing to send, so callers can spread it unconditionally.
+ */
+declare const mergeProviderOptions: (...maps: (ProviderOptionsMap | undefined)[]) => ProviderOptionsMap | undefined;
+
+/**
+ * Prompt caching. Every stage's SYSTEM prompt holds only run-stable content
+ * (role, domain context, skills, tool catalogue) and the dynamic parts go to
+ * the user prompt — so OpenAI's and Gemini's automatic prefix caches hit.
+ * Anthropic caches only behind an explicit breakpoint, placed on the system
+ * message; OpenAI additionally routes by `promptCacheKey`. Other providers
+ * ignore option keys that are not theirs.
+ */
+type PromptCachingSetting = boolean | {
+    ttl?: '5m' | '1h';
+    key?: string;
+};
+interface ResolvedCaching {
+    enabled: boolean;
+    ttl?: '5m' | '1h';
+    key?: string;
+}
+declare const resolveCaching: (s: PromptCachingSetting | undefined) => ResolvedCaching;
+/**
+ * The conversation with a rolling cache breakpoint on its LAST message — the
+ * agent-loop pattern Claude Code uses: every tool-calling round re-sends the
+ * rounds before it, and with the breakpoint moved to the newest message each
+ * request reads all of them from the cache and writes only the new tail.
+ * Earlier message breakpoints are removed (the SDK carries a round's messages
+ * into the next one), so a request holds at most two: system + newest —
+ * Anthropic rejects more than four.
+ */
+declare const withRollingBreakpoint: <M extends {
+    providerOptions?: unknown;
+}>(messages: M[], caching: ResolvedCaching) => M[];
+
+/**
+ * Run-level token budgets. Every cap is cumulative over one `run()` and soft:
+ * it is checked between steps and at every tool-calling round inside a step,
+ * so a run stops at the next boundary after crossing it and then writes its
+ * final answer (synthesis still runs, bounded by `perCall.synthesizer`).
+ */
+interface TokenLimits {
+    /** Cumulative input (prompt) tokens per run. */
+    maxInputTokens?: number;
+    /** Cumulative output tokens per run, thinking included. */
+    maxOutputTokens?: number;
+    /** Cumulative thinking tokens per run. */
+    maxReasoningTokens?: number;
+    /** Cumulative input + output tokens per run. */
+    maxTotalTokens?: number;
+    /** Max output tokens of ONE model call, per phase (wins over the legacy `budgets`). */
+    perCall?: {
+        planner?: number;
+        executor?: number;
+        replanner?: number;
+        synthesizer?: number;
+        compaction?: number;
+    };
+}
+type LimitKind = 'input' | 'output' | 'reasoning' | 'total' | 'tool-calls';
+interface LimitBreach {
+    kind: LimitKind;
+    tokens: number;
+    cap: number;
+}
+/**
+ * The first cap the usage has reached, or undefined. Order: total, input,
+ * output, reasoning — the broadest budget is reported first. Pure.
+ */
+declare const checkLimits: (usage: IUsage, limits: TokenLimits | undefined) => LimitBreach | undefined;
+/** Raised by a tool call that would exceed `maxToolCalls`. */
+declare class ToolBudgetError extends Error {
+    constructor(cap: number);
+    toJSON(): string;
+}
+
 interface StoredMessage {
     role: 'system' | 'user' | 'assistant';
     content: string;
@@ -59,6 +185,86 @@ declare class MemoryStore implements ContextStore {
     clear(sessionId: string): Promise<void>;
 }
 
+/**
+ * Context compaction. A model's window is finite and every token in it is paid
+ * for on every call, so long transcripts and long runs are folded into a
+ * summary: the oldest material is summarised by a model, the most recent is
+ * kept verbatim.
+ */
+interface CompactionConfig {
+    /** Compact automatically before planning and between steps (default true). */
+    auto?: boolean;
+    /** The model's context window, in tokens (default 128 000). */
+    contextWindowTokens?: number;
+    /** Compact once the estimated context exceeds this (default: half the window). */
+    thresholdTokens?: number;
+    /** Transcript messages kept verbatim (default 4). */
+    keepRecentTurns?: number;
+    /** Executed steps kept verbatim in the run's trace (default 3). */
+    keepRecentSteps?: number;
+    /** Output cap of a summary call (default 1024). */
+    summaryMaxTokens?: number;
+    /** Cap on ONE tool result as the model sees it, in chars (default 20 000; 0 = no cap). */
+    maxToolOutputChars?: number;
+    /**
+     * Inside one step's tool loop: once its context passes this many tokens,
+     * replace the oldest tool results with one-line stubs (context editing;
+     * default: a quarter of the window; 0 = never).
+     */
+    clearToolResultsAfterTokens?: number;
+    /** Most recent tool results kept verbatim when clearing (default 3). */
+    keepToolResults?: number;
+}
+interface ResolvedCompaction {
+    auto: boolean;
+    contextWindowTokens: number;
+    thresholdTokens: number;
+    keepRecentTurns: number;
+    keepRecentSteps: number;
+    summaryMaxTokens: number;
+    maxToolOutputChars: number;
+    clearToolResultsAfterTokens: number;
+    keepToolResults: number;
+}
+declare const resolveCompaction: (c: CompactionConfig | undefined) => ResolvedCompaction;
+/** Cheap, provider-independent token estimate (~4 chars per token). */
+declare const estimateTokens: (text: string) => number;
+declare const messageTokens: (msgs: StoredMessage[]) => number;
+interface CompressOptions {
+    /** Compress once the transcript exceeds this many characters (0 = never). */
+    maxChars?: number;
+    /** Compress once the transcript's estimated tokens exceed this (wins over maxChars). */
+    thresholdTokens?: number;
+    /** How many most-recent messages to keep verbatim. */
+    keepRecent?: number;
+    /** Output cap of the summary call. */
+    summaryMaxTokens?: number;
+    /** Compact even when below the threshold (manual "compact now"). */
+    force?: boolean;
+    /** Time-box the summarisation call so it can never hang the caller. */
+    timeoutMs?: number;
+    abortSignal?: AbortSignal;
+    /** Receives the summary call's token usage. */
+    onUsage?: (usage: IUsage) => void;
+}
+/**
+ * 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[]>;
+/** Alias with the sibling package's name; same behaviour as compressHistory. */
+declare const compactHistory: (messages: StoredMessage[], model: LanguageModel, opts?: CompressOptions) => Promise<StoredMessage[]>;
+/**
+ * Fold the oldest entries of a run's step log into one summary entry, keeping
+ * the last `keepRecent` verbatim. Returns the input unchanged when it fits the
+ * threshold or on any failure; never throws.
+ */
+declare const compactSteps: (done: string[], model: LanguageModel, opts: CompressOptions & {
+    thresholdTokens: number;
+}) => Promise<string[]>;
+
 /**
  * Leveled logging for the agent. The host passes a console-like sink and a
  * level; everything below the level is a no-op. Default: 'warn' onto the
@@ -151,6 +357,15 @@ declare const isProviderSpec: (m: unknown) => m is ProviderModelSpec;
  *   out an exact JSON shape and (for the executor) include a tool catalogue;
  *   the output is salvaged by parse.ts.
  *
+ * Layout matters for prompt caching: the SYSTEM part holds only what is stable
+ * for a whole run (role, skills, the planner's tool catalogue), the user
+ * prompt holds everything that changes (goal, state, history, progress), so a
+ * provider's prefix cache can reuse the system part across calls.
+ *
+ * The agent is autonomous by design: it plans tool use for anything the tools
+ * can do or look up, never asks the user for confirmation (consent is the
+ * host's `toolApproval` policy), and states assumptions instead of asking.
+ *
  * Override any builder via `BrowserAgentConfig.prompts`.
  */
 type ToolCallMode = 'native' | 'prompted';
@@ -168,6 +383,10 @@ interface PlannerPromptContext {
         role: string;
         content: string;
     }[];
+    /** "- name: description" index of the configured skills, when any. */
+    skills?: string;
+    /** The catalogue is condensed and the executor can search the rest (large catalogues). */
+    searchMode?: boolean;
 }
 interface ExecutorPromptContext {
     goal: string;
@@ -176,8 +395,15 @@ interface ExecutorPromptContext {
     index: number;
     total: number;
     toolCatalog: string;
+    /** Earlier steps of this run, each with its outcome and key data. */
     done: string[];
     mode: ToolCallMode;
+    /** "- name: description" index of the configured skills, when any. */
+    skills?: string;
+    /** Full instructions of the skills active in this run. */
+    activeSkills?: string;
+    /** The executor can call find_tools to activate more tools. */
+    searchMode?: boolean;
 }
 interface ReplannerPromptContext {
     goal: string;
@@ -185,11 +411,15 @@ interface ReplannerPromptContext {
     done: string[];
     remaining: string[];
     mode: ToolCallMode;
+    activeSkills?: string;
 }
 interface SynthesizerPromptContext {
     goal: string;
     state?: string;
     done: string[];
+    /** Excerpts of what the tools returned, for answering with real data. */
+    findings?: string[];
+    activeSkills?: string;
 }
 interface Prompts {
     planner(ctx: PlannerPromptContext): PromptParts;
@@ -228,6 +458,122 @@ declare class MemoryCredentialStore implements CredentialStore {
     deleteApiKey(ref: string): Promise<void>;
 }
 
+/**
+ * Skills — reusable instruction bundles in the agentskills.io shape
+ * (`SKILL.md` with `name`/`description` frontmatter, a markdown body, optional
+ * bundled text files). Progressive disclosure: only the one-line index sits in
+ * the prompts; a skill's full instructions enter the context when the planner
+ * selects it or the executor loads it with `load_skill`.
+ */
+interface Skill {
+    /** Stable id: lowercase letters, digits and dashes, 1–64 chars. */
+    name: string;
+    /** When to use it — the only part always shown to the model. */
+    description: string;
+    /** Full instructions (the markdown body of SKILL.md). */
+    content: string;
+    /** Bundled text resources, addressed by skill-relative POSIX paths. */
+    files?: {
+        path: string;
+        content: string;
+    }[];
+}
+/** Names of the built-in skill tools (reserved when skills are configured). */
+declare const SKILL_TOOL_NAMES: readonly ["load_skill", "read_skill_file"];
+/** Validate a skill definition and return it (throws a precise error). */
+declare const defineSkill: (skill: Skill) => Skill;
+/**
+ * Parse a SKILL.md document into a {@link Skill}. Frontmatter must provide
+ * `name` and `description`; the markdown body becomes `content`.
+ */
+declare const parseSkillMarkdown: (markdown: string, files?: {
+    path: string;
+    content: string;
+}[]) => Skill;
+interface LoadSkillOptions {
+    /** Bundled files to fetch, relative to the SKILL.md URL. */
+    files?: string[];
+    fetch?: typeof fetch;
+}
+/** Fetch a SKILL.md (and optionally its bundled files) over HTTP. */
+declare const loadSkillFromUrl: (url: string, opts?: LoadSkillOptions) => Promise<Skill>;
+/** "- name: description" lines for the prompts. */
+declare const renderSkillIndex: (skills: Skill[]) => string;
+/** The full instructions of the active skills, within a total character budget. */
+declare const renderActiveSkills: (skills: Skill[]) => string;
+/**
+ * The built-in `load_skill` / `read_skill_file` tools. `onLoad` fires when a
+ * skill is loaded so the runner can keep it active for later steps.
+ */
+declare const createSkillTools: (skills: Skill[], onLoad?: (skill: Skill) => void) => ToolSet;
+
+/**
+ * Tool consent. Every tool call passes a gate that decides allow / ask / deny:
+ *
+ * - `autopilot`   — run everything (default; explicit `rules` still apply);
+ * - `ask-writes`  — run read-only tools, ask before anything that may change state;
+ * - `ask-all`     — ask before every call;
+ * - `read-only`   — run read-only tools, refuse the rest without asking.
+ *
+ * A tool is read-only when its MCP annotations say so (`readOnlyHint`) or the
+ * host marked it (`defineTool({ readOnly: true })` / `markReadOnly`). Unknown =
+ * may write: the safe assumption.
+ */
+type ToolApprovalMode = 'autopilot' | 'ask-writes' | 'ask-all' | 'read-only';
+type ToolPermission = 'allow' | 'ask' | 'deny';
+declare const TOOL_APPROVAL_MODES: readonly ToolApprovalMode[];
+interface ToolApprovalRequest {
+    /** Unique per request — echo it back from a UI. */
+    id: string;
+    toolName: string;
+    input: unknown;
+    readOnly: boolean;
+    step?: IPlanStep;
+}
+/**
+ * `true`/`false`, or an object. `remember: true` on an approval allows this
+ * tool for the rest of the agent's life ("always allow").
+ */
+type ToolApprovalDecision = boolean | {
+    approved: boolean;
+    reason?: string;
+    remember?: boolean;
+};
+interface ToolApprovalConfig {
+    /** Default policy (default 'autopilot'). */
+    mode?: ToolApprovalMode;
+    /**
+     * Per-tool overrides by exact name or `*` glob, e.g. `{ 'github__delete_*': 'deny' }`.
+     * They win over the mode — an explicit 'ask' still asks under autopilot.
+     */
+    rules?: Record<string, ToolPermission>;
+    /** Resolves an approval request (a UI prompt, a policy service, …). */
+    onRequest?: (req: ToolApprovalRequest) => ToolApprovalDecision | Promise<ToolApprovalDecision>;
+    /** No decision within this many ms → deny. Default: wait indefinitely. */
+    timeoutMs?: number;
+}
+/** Raised by a denied tool call; recorded as a failed call the replanner sees. */
+declare class ToolDeniedError extends Error {
+    constructor(reason?: string);
+    toJSON(): string;
+}
+/** Mark a tool as read-only so `ask-writes` / `read-only` let it through. Returns it. */
+declare const markReadOnly: <T extends object>(tool: T, readOnly?: boolean) => T;
+declare const isReadOnlyTool: (tool: Tool | undefined) => boolean;
+/** The most specific matching rule: an exact name, else the longest glob. Pure. */
+declare const matchRule: (rules: Record<string, ToolPermission> | undefined, toolName: string) => ToolPermission | undefined;
+/**
+ * What the gate does for one call, before any human is involved. Order:
+ * remembered "always allow" → most specific rule → mode default. Pure.
+ */
+declare const decideToolPermission: (opts: {
+    toolName: string;
+    readOnly: boolean;
+    mode: ToolApprovalMode;
+    rules?: Record<string, ToolPermission>;
+    remembered?: ReadonlySet<string>;
+}) => ToolPermission;
+
 /**
  * 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
@@ -238,6 +584,7 @@ declare class MemoryCredentialStore implements CredentialStore {
  */
 type AgentTool = Tool & {
     promptHint?: string;
+    readOnly?: boolean;
 };
 /** A named collection of tools — a plain AI SDK ToolSet, usable directly. */
 type AgentToolSet = ToolSet;
@@ -259,8 +606,12 @@ type ReplanTrigger = 'failure' | 'always' | ((result: IStepResult) => boolean |
  * '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.
+ * 'search'        — for large catalogues: the executor starts with the step's
+ *                   suggestedTools plus a `find_tools` meta-tool that activates
+ *                   more on demand; the planner sees a condensed catalogue.
+ * 'auto'          — 'all' up to `toolSearchThreshold` tools, 'search' above (default).
  */
-type ToolSelectionStrategy = 'all' | 'plan-narrowed';
+type ToolSelectionStrategy = 'all' | 'plan-narrowed' | 'search' | 'auto';
 /** Per-phase generation budgets (max output tokens). */
 interface PhaseBudgets {
     planner?: number;
@@ -286,7 +637,14 @@ interface BrowserAgentConfig {
     excludedTools?: string[];
     /** Force native/prompted tool-calling; 'auto' picks per model (default 'auto'). */
     toolMode?: ToolMode;
+    /** How the executor sees the tool catalogue (default 'auto'). */
     toolSelectionStrategy?: ToolSelectionStrategy;
+    /** Catalogue size above which 'auto' switches to 'search' (default 40). */
+    toolSearchThreshold?: number;
+    /** Consent policy for tool calls: autopilot, ask before writes, ask always, read-only. */
+    toolApproval?: ToolApprovalConfig;
+    /** Reusable instruction bundles (SKILL.md) the planner/executor can pull in. */
+    skills?: Skill[];
     /** Prepended to every phase's system prompt. */
     systemPrompt?: string;
     /** Override any phase prompt builder. */
@@ -306,17 +664,47 @@ interface BrowserAgentConfig {
     maxStepsPerTask?: number;
     /** Cap on replanner "revise" decisions per run (default 2). */
     maxRevisions?: number;
+    /** Cap on tool calls per run (default: unlimited). */
+    maxToolCalls?: number;
+    /** Cap on the steps of one plan (default 8). */
+    maxPlanSteps?: number;
     /** Per-call timeout so a hang can't freeze a run (default 120000). */
     chatTimeoutMs?: number;
+    /** Legacy per-phase output caps; `limits.perCall` wins when both are set. */
     budgets?: PhaseBudgets;
+    /** Run-level token budgets (input / output / thinking / total) + per-call output caps. */
+    limits?: TokenLimits;
     temperature?: number;
+    /** Thinking for every stage: true, a level ('low'…'xhigh'), or { level, budgetTokens }. */
+    thinking?: ThinkingSetting;
+    /** Per-stage thinking; a stage entry wins over `thinking`. */
+    stageThinking?: Partial<Record<ThinkingStage, ThinkingSetting>>;
+    /**
+     * Whether the model accepts images. Default: inferred (`supportsImages`) —
+     * local/prompted models are text-only; unknown models are tried and a
+     * refusal is reported as ImagesNotSupportedError.
+     */
+    vision?: boolean;
+    /** Per-kind override of what the model takes as attachments (`images` wins over `vision`). */
+    inputs?: {
+        images?: boolean;
+        pdf?: boolean;
+        files?: boolean;
+    };
+    /** Provider prompt caching (default true): stable system prefixes + Anthropic breakpoints. */
+    promptCaching?: PromptCachingSetting;
+    /** Context compaction (auto + manual `agent.compact()`); see CompactionConfig. */
+    compaction?: CompactionConfig;
     /** Master switch for the replan phase (default true). */
     replan?: boolean;
     /** What triggers the replanner when it is on (default 'failure'). */
     replanAfter?: ReplanTrigger;
     /** Write a final natural-language summary (default true). */
     synthesize?: boolean;
-    /** Compress stored history past this many chars (0 = off, default 12000). */
+    /**
+     * Legacy: compress stored history past this many chars after each run
+     * (0 = off). Used only when `compaction` is not set.
+     */
     compressAfterChars?: number;
     /** Verbosity: 'silent' | 'error' | 'warn' (default) | 'info' | 'debug'. */
     logLevel?: LogLevel;
@@ -328,22 +716,32 @@ interface ResolvedConfig {
     sessionId: string;
     toolMode: ToolMode;
     toolSelectionStrategy: ToolSelectionStrategy;
+    toolSearchThreshold: number;
     maxIterations: number;
     maxStepsPerTask: number;
     maxRevisions: number;
+    maxToolCalls: number;
+    maxPlanSteps: number;
     chatTimeoutMs: number;
-    budgets: Required<PhaseBudgets>;
+    /** Effective per-call output caps (limits.perCall over budgets). */
+    budgets: Required<PhaseBudgets> & {
+        compaction: number;
+    };
+    limits: TokenLimits;
     temperature: number | undefined;
     replan: boolean;
     replanAfter: ReplanTrigger;
     synthesize: boolean;
     compressAfterChars: number;
+    compaction: ResolvedCompaction;
     logLevel: LogLevel;
 }
 declare const resolveConfig: (c: BrowserAgentConfig) => ResolvedConfig;
 
 type ReplanMode = 'continue' | 'revise' | 'finish';
 type Phase = 'plan' | 'execute' | 'replan' | 'synthesize';
+/** Phases a `usage` event can be charged to: the four stages plus compaction and subagents. */
+type UsagePhase = Phase | 'compact' | 'subagent';
 /**
  * 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
@@ -381,6 +779,12 @@ type AgentEvent = {
     type: 'step.text-delta';
     step: IPlanStep;
     delta: string;
+}
+/** The executor model's streamed thoughts (thinking enabled + provider support). */
+ | {
+    type: 'step.reasoning-delta';
+    step: IPlanStep;
+    delta: string;
 } | {
     type: 'step.tool-call';
     step: IPlanStep;
@@ -403,18 +807,92 @@ type AgentEvent = {
 } | {
     type: 'final.text-delta';
     delta: string;
+}
+/** The synthesizer's streamed thoughts. */
+ | {
+    type: 'final.reasoning-delta';
+    delta: string;
 } | {
     type: 'final';
     text: string;
 } | {
     type: 'usage';
-    phase: Phase;
+    phase: UsagePhase;
     usage: IUsage;
 } | {
     type: 'retry';
     phase: Phase;
     attempt: number;
     error: string;
+}
+/** A run-level limit was reached; the run stops executing and writes its answer. */
+ | {
+    type: 'budget.exceeded';
+    kind: LimitKind;
+    tokens: number;
+    cap: number;
+}
+/** Older context was summarised to fit the window. */
+ | {
+    type: 'context.compacted';
+    /** history = stored transcript; trace = the run's done steps; tool-results = stale results inside a step's tool loop. */
+    scope: 'history' | 'trace' | 'tool-results';
+    beforeTokens: number;
+    afterTokens: number;
+}
+/** A skill's instructions entered the context (picked by the planner, or loaded by a tool call). */
+ | {
+    type: 'skill.activated';
+    name: string;
+    by: 'plan' | 'tool';
+}
+/** find_tools activated more tools (large-catalogue search mode). */
+ | {
+    type: 'tools.discovered';
+    step?: IPlanStep;
+    query: string;
+    names: string[];
+}
+/** A tool call is waiting for the user's consent (see `toolApproval`). */
+ | {
+    type: 'tool.approval-requested';
+    id: string;
+    name: string;
+    input: unknown;
+    readOnly: boolean;
+    step?: IPlanStep;
+}
+/** A consent decision: from the user, or `automatic` (policy denial). */
+ | {
+    type: 'tool.approval-resolved';
+    id: string;
+    name: string;
+    approved: boolean;
+    reason?: string;
+    automatic: boolean;
+} | {
+    type: 'subagent.start';
+    id: string;
+    name: string;
+    task: string;
+}
+/** An event of a running subagent, forwarded verbatim. */
+ | {
+    type: 'subagent.event';
+    id: string;
+    name: string;
+    event: AgentEvent;
+} | {
+    type: 'subagent.complete';
+    id: string;
+    name: string;
+    text: string;
+    usage: IUsage;
+} | {
+    type: 'subagent.error';
+    id: string;
+    name: string;
+    error: string;
 } | {
     type: 'stopped';
 } | {
@@ -424,11 +902,164 @@ type AgentEvent = {
 };
 type AgentEventHandler = (event: AgentEvent) => void;
 
+/**
+ * Tool search for large catalogues. Several MCP servers easily add up to
+ * hundreds of tools — sending every schema on every call wastes the context
+ * window (and OpenAI rejects more than 128 tools outright). In 'search' mode
+ * the executor starts each step with a handful of tools and a `find_tools`
+ * meta-tool that activates more on demand.
+ */
+interface ToolCatalogEntry {
+    name: string;
+    description: string;
+    /** The MCP server a tool came from ("server__tool" prefix), when known. */
+    server?: string;
+    readOnly?: boolean;
+}
+declare const FIND_TOOLS_NAME = "find_tools";
+/** Build catalogue entries from a ToolSet ("server__tool" names yield a server). */
+declare const toolCatalogOf: (tools: ToolSet) => ToolCatalogEntry[];
+/** Lowercased word tokens; snake_case, kebab-case and camelCase are split. */
+declare const tokenize: (s: string) => string[];
+interface SearchToolsOptions {
+    /** Only tools from this server. */
+    server?: string;
+    /** Max results (default 8, capped at 20). */
+    limit?: number;
+    /** Names to leave out (e.g. already active). */
+    exclude?: ReadonlySet<string>;
+}
+/**
+ * Rank catalogue entries against a keyword query: each query term scores
+ * 3 for a name hit, 2 for a server hit and 1 for a description hit (prefix
+ * matching for terms of 3+ chars). Ties keep catalogue order; zero scores are
+ * dropped. Pure and deterministic — no embeddings, no model call.
+ */
+declare const searchTools: (catalog: ToolCatalogEntry[], query: string, opts?: SearchToolsOptions) => ToolCatalogEntry[];
+/**
+ * The planner's view of a large catalogue: grouped by server, short
+ * descriptions, within a character budget.
+ */
+declare const renderSearchCatalog: (catalog: ToolCatalogEntry[], budget?: number) => string;
+/**
+ * The `find_tools` meta-tool. `onFound` receives the matched names so the
+ * caller can activate them (native: prepareStep activeTools; prompted: the
+ * next round's catalogue).
+ */
+declare const createFindToolsTool: (catalog: () => ToolCatalogEntry[], onFound: (query: string, names: string[]) => void, hintOf?: (name: string) => string | undefined) => Tool;
+
+/**
+ * Attachments sent with a run: images, PDFs and other files the provider can
+ * read, given as bytes / base64 / a data URL — or as an http(s) URL, which
+ * providers that accept links (Gemini, Claude, OpenAI) fetch themselves and the
+ * AI SDK downloads for the rest (from the browser: subject to CORS).
+ */
+interface RunFile {
+    /** Base64 (no prefix), a data URL ("data:image/png;base64,…"), raw bytes, or an http(s) URL. */
+    data: string | Uint8Array | URL;
+    /** e.g. "image/png", "application/pdf" — read from a data URL when omitted. */
+    mediaType?: string;
+    /** Shown in the transcript, in memory and in errors. */
+    name?: string;
+}
+/** An image attachment (same shape; kept as its own name for clarity). */
+type RunImage = RunFile;
+/** The kinds of attachment the agent reasons about separately. */
+type AttachmentKind = 'image' | 'pdf' | 'file';
+/** The media type of an attachment (declared, from a data URL, or from a URL's extension). */
+declare const mediaTypeOf: (f: RunFile) => string | undefined;
+declare const attachmentKind: (f: RunFile) => AttachmentKind;
+/** Raised when attachments are sent to a model that cannot take them. */
+declare class AttachmentsNotSupportedError extends Error {
+    readonly kind: AttachmentKind;
+    constructor(model: string, kind: AttachmentKind, detail?: string);
+    toJSON(): string;
+}
+/** The image flavour of {@link AttachmentsNotSupportedError}. */
+declare class ImagesNotSupportedError extends AttachmentsNotSupportedError {
+    constructor(model: string, detail?: string);
+}
+/**
+ * An AI SDK file part (images included — the v7 SDK deprecates the separate
+ * image part). An http(s) URL is passed as a URL: providers that accept links
+ * fetch it themselves, and the SDK downloads it for the rest.
+ */
+declare const toFilePart: (f: RunFile) => FilePart;
+/** Back-compat name. */
+declare const toImagePart: (f: RunFile) => FilePart;
+/** Does a provider error look like a refusal of attachment input? */
+declare const isAttachmentRefusal: (err: unknown) => boolean;
+/** Back-compat name. */
+declare const isImageRefusal: (err: unknown) => boolean;
+
+/** The effective tool-selection strategy of a run ('auto' already resolved). */
+type EffectiveToolStrategy = 'all' | 'plan-narrowed' | 'search';
+/** 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;
+    /** The run's tools (host + MCP + built-ins), already wrapped by the consent gate. */
+    tools: AgentToolSet;
+    /** The catalogue as the planner sees it (condensed in search mode). */
+    toolCatalog: string;
+    prompts: Prompts;
+    emit: (event: AgentEvent) => void;
+    /** Leveled logger (config.logLevel over config.logger ?? console). */
+    log: AgentLogger;
+    signal?: AbortSignal;
+    /** Current world state for grounding, or undefined when no describeState is configured. */
+    state: () => Promise<string | undefined>;
+    /** Session transcript loaded from memory BEFORE this run's goal was appended. */
+    history?: StoredMessage[];
+    /** Effective tool selection for this run. */
+    strategy?: EffectiveToolStrategy;
+    /** Prompt caching, resolved. */
+    caching?: ResolvedCaching;
+    /** All configured skills. */
+    skills?: Skill[];
+    /** Skills whose instructions are in play for this run. */
+    activeSkills?: () => Skill[];
+    /** Tools find_tools activated during this run (search mode). */
+    discovered?: () => string[];
+    /** Built-in tool names (find_tools, skill tools) — always callable. */
+    builtinTools?: ReadonlySet<string>;
+    /** Parameter hint of a tool, for prompted catalogues. */
+    toolHint?: (name: string) => string | undefined;
+    /** Run usage so far (for in-step budget checks). */
+    usageSoFar?: () => IUsage;
+    /** True when the run's limits are reached given extra usage spent inside the current call. */
+    overBudget?: (extra: IUsage) => boolean;
+    /** Tracks the step being executed (tools read it via their run context). */
+    setCurrentStep?: (step: IPlanStep | undefined) => void;
+    /** Images / PDFs / files the user sent with this run's goal. */
+    images?: RunFile[];
+}
+
 interface RunOptions {
     onEvent?: AgentEventHandler;
     signal?: AbortSignal;
     /** Override the config's sessionId for this run. */
     sessionId?: string;
+    /**
+     * Images sent with the goal (pasted screenshots, photos). They reach the
+     * planner, the executor and the synthesizer of a vision-capable model; a
+     * model known not to take images ends the run at once with
+     * ImagesNotSupportedError's message (see `capabilities.images`).
+     */
+    images?: RunImage[];
+    /**
+     * Other attachments: PDFs and files the provider reads natively, as data or
+     * as an http(s) URL. Same rules as `images`, per kind (`capabilities.pdf`,
+     * `capabilities.files`).
+     */
+    files?: RunFile[];
 }
 interface RunResult {
     goal: string;
@@ -440,9 +1071,50 @@ interface RunResult {
     applied: number;
     stopped: boolean;
     usage: IUsage;
+    /** Skills whose instructions were active in this run. */
+    skills: string[];
+    /** The limit that stopped the run early, if any. */
+    budgetExceeded?: LimitBreach;
+}
+interface CompactOptions {
+    /** Session to compact (default: the config's sessionId). */
+    sessionId?: string;
+    signal?: AbortSignal;
+    /** Compact even when below the threshold (default true for a manual call). */
+    force?: boolean;
+}
+interface CompactResult {
+    compacted: boolean;
+    beforeTokens: number;
+    afterTokens: number;
+    usage: IUsage;
 }
 interface Agent {
     run(goal: string, opts?: RunOptions): Promise<RunResult>;
+    /** Summarise the stored transcript (needs `memory`); returns the before/after size. */
+    compact(opts?: CompactOptions): Promise<CompactResult>;
+    /** Switch the consent policy — e.g. the "autopilot" toggle. Applies to the next tool call. */
+    setToolApprovalMode(mode: ToolApprovalMode): void;
+    readonly toolApprovalMode: ToolApprovalMode;
+    /** The tool catalogue (host + MCP tools after filtering). */
+    listTools(): ToolCatalogEntry[];
+    /** The effective tool selection ('auto' resolved by catalogue size). */
+    readonly toolStrategy: EffectiveToolStrategy;
+    /** Configured skills (name + description). */
+    readonly skills: {
+        name: string;
+        description: string;
+    }[];
+    /**
+     * What the executor model can take, per attachment kind: true / false, or
+     * undefined when unknown (the run tries, and a provider refusal becomes a
+     * clear error).
+     */
+    readonly capabilities: {
+        images: boolean | undefined;
+        pdf: boolean | undefined;
+        files: boolean | undefined;
+    };
     /** The resolved models, for hosts that want to reuse them (e.g. warm-up). */
     readonly models: {
         planner: LanguageModel;
@@ -474,12 +1146,13 @@ declare const PlanSchema: z.ZodObject<{
         expectedOutcome: z.ZodOptional<z.ZodString>;
         suggestedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
+    skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 declare const ReplanSchema: z.ZodObject<{
     decision: z.ZodEnum<{
+        finish: "finish";
         continue: "continue";
         revise: "revise";
-        finish: "finish";
     }>;
     reason: z.ZodString;
     plan: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -487,43 +1160,22 @@ declare const ReplanSchema: z.ZodObject<{
 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;
-    /** Leveled logger (config.logLevel over config.logger ?? console). */
-    log: AgentLogger;
-    signal?: AbortSignal;
-    /** Current world state for grounding, or undefined when no describeState is configured. */
-    state: () => Promise<string | undefined>;
-    /** Session transcript loaded from memory BEFORE this run's goal was appended. */
-    history?: StoredMessage[];
+interface PlanOutcome {
+    plan: IPlan;
+    usage: IUsage;
+    /** Names of configured skills the planner picked (validated). */
+    skills: string[];
 }
-
 /**
  * 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).
+ * runner to answer directly (greeting / small talk).
  */
 declare const createPlan: (ctx: AgentContext, goal: string, 
 /** Extra instruction appended to the goal (used by the empty-plan retry). */
-nudge?: string) => Promise<{
-    plan: IPlan;
-    usage: IUsage;
-}>;
+nudge?: string) => Promise<PlanOutcome>;
 
 /**
  * Split the executor's reply into a clean summary and a structural `blocked`
@@ -539,6 +1191,7 @@ declare const splitBlocker: (raw: string) => {
 declare const executeStep: (ctx: AgentContext, goal: string, step: IPlanStep, index: number, total: number, done: string[]) => Promise<{
     result: IStepResult;
     usage: IUsage;
+    stoppedByBudget?: boolean;
 }>;
 /**
  * The replanner runs when a step was blocked or a tool call failed and stayed
@@ -583,6 +1236,8 @@ declare const normalizeSteps: (arr: unknown, cap?: number) => string[];
 interface PlannerResult {
     reply: string;
     plan: string[];
+    /** Skill names the planner picked (empty when none / not asked). */
+    skills: string[];
 }
 declare const parsePlannerResponse: (raw: string) => PlannerResult;
 interface ExecutorResult {
@@ -615,17 +1270,257 @@ interface ReplanOutcome {
 declare const decideReplan: (ctx: AgentContext, goal: string, done: string[], remaining: string[]) => Promise<ReplanOutcome>;
 
 /**
- * Write the final natural-language summary of what the run accomplished,
- * streaming it as `final.text-delta` events. Plain text only (parsePlainText
- * strips any stray JSON; deltas are suppressed entirely when the model drifts
- * into JSON, so raw structure never reaches a UI). Falls back to a default
- * sentence if the model returns nothing usable.
+ * Write the final natural-language answer of the run, streaming it as
+ * `final.text-delta` events (and thoughts as `final.reasoning-delta`). Plain
+ * text only (parsePlainText strips any stray JSON; deltas are suppressed
+ * entirely when the model drifts into JSON, so raw structure never reaches a
+ * UI). Falls back to a default sentence if the model returns nothing usable.
  */
-declare const synthesizeAnswer: (ctx: AgentContext, goal: string, done: string[]) => Promise<{
+declare const synthesizeAnswer: (ctx: AgentContext, goal: string, done: string[], 
+/** Excerpts of what the tools returned — the data the answer is made of. */
+findings?: string[]) => Promise<{
     text: string;
     usage: IUsage;
 }>;
 
+/**
+ * The wire protocol between a parent agent and a subagent running in a Web
+ * Worker. Every message is structured-cloneable; anything that is not (an
+ * Error, a function in a tool output) is flattened before it is posted.
+ */
+/** A host tool the worker can call back into the main thread for. */
+interface ProxiedToolSpec {
+    name: string;
+    description: string;
+    /** JSON Schema of the tool input. */
+    inputSchema: unknown;
+    readOnly?: boolean;
+}
+type ParentToWorker = {
+    type: 'run';
+    task: string;
+    /** Serializable agent config (model is a ProviderModelSpec). */
+    config: Record<string, unknown>;
+    proxied: ProxiedToolSpec[];
+} | {
+    type: 'abort';
+} | {
+    type: 'tool-result';
+    callId: string;
+    ok: boolean;
+    output: unknown;
+};
+type WorkerToParent = {
+    type: 'event';
+    event: AgentEvent;
+} | {
+    type: 'tool-call';
+    callId: string;
+    name: string;
+    input: unknown;
+} | {
+    type: 'done';
+    text: string;
+    usage: IUsage;
+    steps: number;
+} | {
+    type: 'error';
+    error: string;
+};
+/**
+ * The slice of the Worker / DedicatedWorkerGlobalScope / MessagePort API we
+ * use. Structural, so a real `Worker`, a worker's `self`, or a MessageChannel
+ * port (tests) all fit.
+ */
+interface MessageEndpoint {
+    postMessage(message: unknown): void;
+    addEventListener(type: string, listener: (ev: any) => void): void;
+    removeEventListener?(type: string, listener: (ev: any) => void): void;
+}
+/** A worker as the parent sees it. */
+interface WorkerLike extends MessageEndpoint {
+    terminate?(): void;
+}
+
+/** The serializable slice of BrowserAgentConfig a worker subagent can be built from. */
+type SubagentWorkerConfig = Pick<BrowserAgentConfig, 'clientName' | 'systemPrompt' | 'availableTools' | 'excludedTools' | 'toolMode' | 'toolSelectionStrategy' | 'toolSearchThreshold' | 'skills' | 'maxIterations' | 'maxStepsPerTask' | 'maxRevisions' | 'maxToolCalls' | 'maxPlanSteps' | 'chatTimeoutMs' | 'budgets' | 'limits' | 'temperature' | 'thinking' | 'stageThinking' | 'promptCaching' | 'compaction' | 'replan' | 'synthesize' | 'logLevel'> & {
+    /** The child's model, resolved inside the worker (by its `resolveModel`, or the registry). */
+    model: ProviderModelSpec;
+    /** Consent policy inside the worker — mode and rules only (no callbacks cross threads). */
+    toolApproval?: {
+        mode?: 'autopilot' | 'read-only';
+        rules?: Record<string, 'allow' | 'deny'>;
+    };
+};
+interface SubagentToolOptions {
+    /** Label for events and logs (the tool's KEY in your ToolSet is up to you). */
+    name: string;
+    /** What the subagent is for — the parent model reads this to decide when to delegate. */
+    description: string;
+    /** In-process subagent: a full config (models, tools, …) for the child agent. */
+    config?: BrowserAgentConfig;
+    /**
+     * Worker subagent: builds a fresh Worker per delegated task, e.g.
+     * `() => new Worker(new URL('./agent.worker.ts', import.meta.url), { type: 'module' })`.
+     * The worker module calls `serveSubagentWorker()`.
+     */
+    worker?: () => WorkerLike;
+    /** Worker subagent: the child's serializable config. */
+    workerConfig?: SubagentWorkerConfig;
+    /**
+     * Resolves `workerConfig.model.credentialRef` in the main thread; the key is
+     * posted to the worker for that one task and never stored there.
+     */
+    credentials?: CredentialStore;
+    /**
+     * Host tools the subagent may call. In-process they are merged into the
+     * child's tools; with a worker they stay in the main thread and are called
+     * over RPC. Either way each call passes the PARENT's consent gate.
+     */
+    tools?: ToolSet;
+    /** Parallel delegations allowed at once (default 4); extra calls queue. */
+    maxConcurrent?: number;
+    /** Give up on one delegated task after this many ms (default: none). */
+    timeoutMs?: number;
+    /** Cap on the text handed back to the parent model (default 8000 chars). */
+    outputMaxChars?: number;
+    /** Mark the tool read-only for the parent's consent gate (default false). */
+    readOnly?: boolean;
+}
+/**
+ * Expose a subagent as a tool: the parent delegates `{ task }`, the child runs
+ * its own plan → execute → synthesize loop — in this thread, or isolated in a
+ * Web Worker — and its final answer comes back as the tool result. Several
+ * delegations in one model step run in parallel (bounded by `maxConcurrent`).
+ *
+ * The parent sees `subagent.start` / `subagent.event` / `subagent.complete` /
+ * `subagent.error` events, and the child's tokens are charged to the parent
+ * run (a `usage` event with phase 'subagent'), so the parent's limits apply.
+ */
+declare const createSubagentTool: (opts: SubagentToolOptions) => AgentTool;
+
+interface ServeSubagentOptions {
+    /**
+     * Build the child's model from its spec. Pass one when your bundler can't
+     * resolve the core's dynamic provider imports inside a worker (Vite): import
+     * the provider factories statically in the worker module and build here.
+     * Default: the core registry (dynamic import of the optional peer).
+     */
+    resolveModel?: (spec: ProviderModelSpec) => LanguageModel | Promise<LanguageModel>;
+    /**
+     * Worker-local tools — they run in the worker thread, so CPU-heavy work
+     * (search, parsing, simulation) never blocks the page.
+     */
+    tools?: ToolSet;
+    /** The worker's message endpoint (default: the worker global scope). */
+    scope?: MessageEndpoint;
+}
+/**
+ * Serve subagent tasks inside a Web Worker. Call it once at the top of your
+ * worker module; the parent's `createSubagentTool({ worker })` posts a task,
+ * this builds a child agent (worker-local tools + the parent's host tools
+ * proxied over RPC), runs it, streams its events back and answers with the
+ * final text.
+ *
+ * ```ts
+ * // agent.worker.ts
+ * import { serveSubagentWorker } from '@dudko.dev/agent-web'
+ * import { createGoogleGenerativeAI } from '@ai-sdk/google'
+ * serveSubagentWorker({
+ *   resolveModel: (spec) => createGoogleGenerativeAI({ apiKey: spec.apiKey })(spec.model),
+ *   tools: { heavy_search: defineTool({ … }) },
+ * })
+ * ```
+ */
+declare const serveSubagentWorker: (opts?: ServeSubagentOptions) => void;
+
+/**
+ * A small virtual file system for the browser — the agent's (and the user's)
+ * workspace: attachments the user drops in, reports the agent writes, images
+ * pasted into the chat. Persistent in IndexedDB by default, in-memory on
+ * request (tests, private mode). Paths are POSIX-like and always absolute
+ * ("/notes/todo.md"); there are no real directories — a "directory" is a path
+ * prefix.
+ */
+interface VirtualFile {
+    path: string;
+    /** Text, or base64 for binary content (see `encoding`). */
+    content: string;
+    encoding: 'utf8' | 'base64';
+    mimeType: string;
+    /** Size of the decoded content in bytes. */
+    size: number;
+    updatedAt: number;
+}
+/** A listing entry (no content). */
+type VirtualFileInfo = Omit<VirtualFile, 'content'>;
+interface VirtualFileSystemOptions {
+    /** Keep files in memory only (default false: IndexedDB). */
+    memory?: boolean;
+    /** IndexedDB database name, forwarded to the shared owner (default 'agent-web'). */
+    dbName?: string;
+    /** Isolates several file systems in one database (default 'default'). */
+    namespace?: string;
+    /** Refuse a single file larger than this many bytes (default 10 MB). */
+    maxFileBytes?: number;
+}
+type VfsListener = (change: {
+    type: 'write' | 'delete';
+    path: string;
+}) => void;
+/** A best-effort MIME type from a file name. */
+declare const mimeFromPath: (path: string) => string;
+/** True for MIME types the agent can read as text. */
+declare const isTextMime: (mime: string) => boolean;
+/**
+ * Normalise a path: absolute, forward slashes, no "." / ".." / empty segments.
+ * Throws on a path that escapes the root.
+ */
+declare const normalizePath: (input: string) => string;
+/** Base64 of bytes, chunked so a large file can't blow the call stack. */
+declare const bytesToBase64: (bytes: Uint8Array) => string;
+declare class VirtualFileSystem {
+    private readonly memory?;
+    private readonly dbName?;
+    private readonly ns;
+    private readonly maxFileBytes;
+    private readonly listeners;
+    constructor(opts?: VirtualFileSystemOptions);
+    private key;
+    /** Subscribe to writes and deletes (e.g. to refresh a file list). Returns an unsubscribe. */
+    onChange(listener: VfsListener): () => void;
+    private notify;
+    write(path: string, content: string | Uint8Array, opts?: {
+        mimeType?: string;
+        encoding?: VirtualFile['encoding'];
+    }): Promise<VirtualFileInfo>;
+    /** Store a data URL ("data:image/png;base64,…") as a file. */
+    writeDataUrl(path: string, dataUrl: string): Promise<VirtualFileInfo>;
+    read(path: string): Promise<VirtualFile | undefined>;
+    /** The file as a data URL (for <img src>, downloads). */
+    readDataUrl(path: string): Promise<string | undefined>;
+    delete(path: string): Promise<boolean>;
+    /** Files under a prefix ("/" = all), sorted by path. */
+    list(prefix?: string): Promise<VirtualFileInfo[]>;
+    /** Remove every file (of this namespace). */
+    clear(): Promise<void>;
+}
+
+interface FileToolsOptions {
+    /** Tool-name prefix (default 'fs_' → fs_list, fs_read, fs_write, fs_delete). */
+    prefix?: string;
+    /** Mount only the read tools (default false). */
+    readOnly?: boolean;
+    /** Cap on the text fs_read returns (default 50 000 chars; the rest is cut with a marker). */
+    maxReadChars?: number;
+}
+/**
+ * Tools that give the agent the virtual file system: list, read, write and
+ * delete. Listing and reading are marked read-only, so the `ask-writes`
+ * consent mode lets them through and asks before writes and deletes.
+ */
+declare const createFileTools: (vfs: VirtualFileSystem, opts?: FileToolsOptions) => ToolSet;
+
 /**
  * Resolve one stage to either a ready model or a fully-resolved spec, layering
  * an optional override on the base:
@@ -716,6 +1611,19 @@ declare const supportsStructuredOutput: (p: ProviderType) => boolean;
  * - `xai` / `deepseek`: unreliable from the browser; prefer a proxy.
  */
 declare const directBrowserOk: (p: ProviderType) => boolean;
+/**
+ * Whether a model accepts image input: `true` (expected to), `false` (known
+ * not to — local runtimes, DeepSeek, text-only families), or `undefined`
+ * (unknown, e.g. an OpenAI-compatible server — the agent tries and turns a
+ * provider refusal into a clear error). Override per agent with `vision`.
+ */
+declare const supportsImages: (model: unknown) => boolean | undefined;
+/**
+ * Whether a model reads PDF files natively: `false` for local runtimes and
+ * text-only families, `true` for Gemini, Claude and OpenAI's vision models,
+ * `undefined` when unknown (tried; a refusal becomes a clear error).
+ */
+declare const supportsPdf: (model: unknown) => boolean | undefined;
 
 /**
  * Fetch (or lazily create) the vault's AES-GCM key. The key is generated
@@ -747,6 +1655,7 @@ interface AgentWebDBOptions {
 declare const KEYS_STORE = "keys";
 declare const SECRETS_STORE = "secrets";
 declare const SESSIONS_STORE = "sessions";
+declare const FILES_STORE = "files";
 /**
  * The single owner of the IndexedDB database. Every persistent store — the
  * non-extractable crypto key, encrypted secrets, and session transcripts —
@@ -758,12 +1667,17 @@ declare const openAgentWebDB: (opts?: AgentWebDBOptions) => Promise<IDBPDatabase
 
 /** Options shared by the low-level generation helpers. Provide `prompt` OR `messages`. */
 interface GenerateOptions {
-    system?: string;
+    /** The system prompt — a string, or a SystemModelMessage (e.g. with a cache breakpoint). */
+    system?: string | SystemModelMessage;
     prompt?: string;
     messages?: ModelMessage[];
     tools?: ToolSet;
     maxOutputTokens?: number;
     temperature?: number;
+    /** Portable thinking level (see `resolveThinking`). */
+    reasoning?: ThinkingLevel;
+    /** Provider-keyed options (thinking budgets, cache keys, …). */
+    providerOptions?: ProviderOptionsMap;
     abortSignal?: AbortSignal;
     /** Time-box the call; combined with `abortSignal` (0/undefined = no timeout). */
     timeoutMs?: number;
@@ -785,36 +1699,90 @@ declare const stream: (model: LanguageModel, opts?: GenerateOptions) => ReturnTy
  */
 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>>;
 
+/**
+ * Context editing inside one tool loop — what Anthropic's
+ * `clear_tool_uses` and Claude Code's micro-compaction do: once the loop's
+ * conversation grows past `triggerTokens`, the OLDEST tool results are replaced
+ * with a one-line stub (the calls themselves stay, so the model knows what it
+ * did and can call again), keeping the `keep` most recent results verbatim.
+ *
+ * Clearing is sticky — a result cleared once stays cleared — so the prefix the
+ * provider cached does not flip back and forth between rounds.
+ */
+interface ToolResultClearing {
+    /** Clear once the loop's estimated tokens exceed this. */
+    triggerTokens: number;
+    /** Most recent tool results kept verbatim (default 3). */
+    keep?: number;
+}
+interface ClearedInfo {
+    cleared: number;
+    beforeTokens: number;
+    afterTokens: number;
+}
+/**
+ * A stateful clearer for one loop: call it with each round's messages; it
+ * returns the (possibly) edited copy and reports what it newly cleared.
+ */
+declare const createToolResultClearer: (opts: ToolResultClearing, onCleared?: (info: ClearedInfo) => void) => ((messages: ModelMessage[]) => ModelMessage[]);
+
 interface ToolLoopCallbacks {
     onTextDelta?: (delta: string) => void;
+    /** The model's streamed thoughts (native mode, thinking enabled). */
+    onReasoningDelta?: (delta: string) => void;
     onToolCall?: (name: string, input: unknown) => void;
     onToolResult?: (name: string, output: unknown, ok: boolean) => void;
+    /** Older tool results were replaced with stubs (see `clearToolResults`). */
+    onToolResultsCleared?: (info: ClearedInfo) => void;
 }
 interface ToolLoopOptions {
     /** 'native' = SDK function-calling; 'prompted' = parse JSON out of plain text. */
     mode: 'native' | 'prompted';
-    system?: string;
+    system?: string | SystemModelMessage;
     prompt?: string;
     messages?: ModelMessage[];
     /** In native mode: the callable tools. In prompted mode: used to dispatch salvaged calls. */
     tools: ToolSet;
     /**
-     * Restrict callable tools to these names (plan-narrowed). Native mode passes
-     * them to the SDK's `activeTools`; prompted mode bounds `dispatch` to them.
+     * Restrict callable tools to these names (plan-narrowed / search). Native mode
+     * passes them to the SDK's `activeTools`; prompted mode bounds `dispatch` to
+     * them. A function is re-read before every round, so a tool that activates
+     * others (find_tools) takes effect on the next round.
+     */
+    activeTools?: string[] | (() => string[]);
+    /**
+     * Prompted mode: render catalogue lines for tools that became active during
+     * the call, so the model learns their names and parameters.
      */
-    activeTools?: string[];
+    describeTools?: (names: string[]) => string;
     /** Cap on tool-calling rounds within this call, in both modes (default 4). */
     maxSteps?: number;
+    /**
+     * Checked with the usage of the rounds so far, at every round boundary —
+     * return true to stop (e.g. a run-level token budget is spent).
+     */
+    shouldStop?: (usageSoFar: IUsage) => boolean;
     maxOutputTokens?: number;
     temperature?: number;
+    reasoning?: ThinkingLevel;
+    providerOptions?: ProviderOptionsMap;
     abortSignal?: AbortSignal;
     timeoutMs?: number;
+    /**
+     * Prompt caching: with it enabled, every round moves a cache breakpoint to
+     * the newest message, so the rounds before it are read from the cache.
+     */
+    caching?: ResolvedCaching;
+    /** Clear the oldest tool results once the loop's context grows past a threshold. */
+    clearToolResults?: ToolResultClearing;
     callbacks?: ToolLoopCallbacks;
 }
 interface ToolLoopResult {
     text: string;
     toolCalls: IToolCall[];
     usage: IUsage;
+    /** True when `shouldStop` cut the call short. */
+    stoppedByBudget?: boolean;
 }
 /**
  * Run tool-calling in whichever mode the model needs, returning a normalised
@@ -826,12 +1794,24 @@ interface ToolLoopResult {
  */
 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?: {
+/** The AI SDK usage shape, every field optional (providers omit what they don't report). */
+interface SdkUsageLike {
     inputTokens?: number;
     outputTokens?: number;
     totalTokens?: number;
-}) => IUsage;
+    inputTokenDetails?: {
+        cacheReadTokens?: number;
+        cacheWriteTokens?: number;
+    };
+    outputTokenDetails?: {
+        reasoningTokens?: number;
+    };
+    /** Pre-v6 flat fields, still emitted by some providers. */
+    reasoningTokens?: number;
+    cachedInputTokens?: number;
+}
+/** Normalise the AI SDK usage shape (fields can be undefined) into IUsage. */
+declare const normalizeUsage: (u?: SdkUsageLike) => IUsage;
 
 /**
  * Define a host tool. Thin wrapper over the AI SDK `tool()`: pass a
@@ -846,7 +1826,9 @@ declare const normalizeUsage: (u?: {
  *
  * 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.
+ * weak local models that can't do native function-calling — and `readOnly:
+ * true` for tools that never change state (the `ask-writes` and `read-only`
+ * approval modes let those run without asking).
  *
  * @example
  *   const tools = {
@@ -860,14 +1842,16 @@ declare const normalizeUsage: (u?: {
  */
 declare const defineTool: <INPUT = unknown, OUTPUT = unknown>(config: Tool<INPUT, OUTPUT> & {
     promptHint?: string;
+    readOnly?: boolean;
 }) => 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.
+ * when present, else from `hintOf` (the agent derives one from the tool's JSON
+ * schema, so MCP tools get one too); weak local models lean on it to fill args.
  */
-declare const renderCatalog: (tools: AgentToolSet) => string;
+declare const renderCatalog: (tools: AgentToolSet, hintOf?: (name: string) => string | undefined) => string;
 interface DispatchContext {
     abortSignal?: AbortSignal;
     messages?: ModelMessage[];
@@ -890,6 +1874,39 @@ declare const dispatch: (action: RawAction, tools: ToolSet, ctx?: DispatchContex
  */
 declare const selectToolMode: (model: LanguageModel, mode?: ToolMode) => "native" | "prompted";
 
+/**
+ * What a tool's `execute` can reach of the run that called it, passed as
+ * `options.agentRun`. Subagent tools use it to stream nested events and to
+ * charge their usage to the parent run.
+ */
+interface ToolRunContext {
+    emit: (event: AgentEvent) => void;
+    /** The plan step being executed, when there is one. */
+    step?: IPlanStep;
+    signal?: AbortSignal;
+    /** Add tokens spent on the parent's behalf (e.g. by a subagent) to the run. */
+    addUsage: (usage: IUsage) => void;
+    /**
+     * Run the agent's consent gate for a call made on its behalf (e.g. a host
+     * tool a subagent calls). Resolves when allowed, throws ToolDeniedError.
+     */
+    approve: (toolName: string, input: unknown, readOnly: boolean) => Promise<void>;
+}
+/** Read the run context the agent passes to a tool's execute (undefined outside a run). */
+declare const toolRunContextOf: (options: unknown) => ToolRunContext | undefined;
+type ToModelOutput = NonNullable<Tool['toModelOutput']>;
+/**
+ * Cap what the MODEL sees of a tool result at `maxChars` (the raw output still
+ * reaches events and the trace). A tool's own `toModelOutput` runs first.
+ */
+declare const limitModelOutput: (original: Tool["toModelOutput"], maxChars: number) => ToModelOutput;
+/**
+ * A short parameter hint ("{ text: string, x?: number }") derived from a
+ * tool's JSON schema — so tools without a hand-written `promptHint` (every MCP
+ * tool) still tell a prompted model what to pass. Undefined when unknown.
+ */
+declare const schemaHintOf: (t: Tool) => Promise<string | undefined>;
+
 interface IndexedDBStoreOptions {
     /** Database name, forwarded to the shared IDB owner (default 'agent-web'). */
     dbName?: string;
@@ -910,21 +1927,4 @@ declare class IndexedDBStore implements ContextStore {
     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;
-    /** Time-box the summarisation call so it can never hang the caller. */
-    timeoutMs?: number;
-    abortSignal?: AbortSignal;
-}
-/**
- * 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 AgentLogger, type AgentLoggerSink, 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, KEYS_STORE, type LogLevel, 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 ReplanTrigger, 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, VaultOptions, type WebLLMModelOptions, buildModelFromStage, compressHistory, createAgent, createLogger, createPlan, createWebLLMModel, decideReplan, decryptJSON, defaultPrompts, defineTool, directBrowserOk, dispatch, encryptJSON, executeStep, generate, generateStructured, getOrCreateVaultKey, isDirectModel, isProviderSpec, isWebGPUAvailable, looksLikeJson, normalizeSteps, normalizeUsage, openAgentWebDB, parseExecutorResponse, parsePlainText, parsePlannerResponse, parseReplannerResponse, preloadWebLLMModel, promptHintOf, renderCatalog, replanWanted, resolveConfig, resolveModel, resolveStage, runToolLoop, selectToolMode, shouldReplan, splitBlocker, stream, supportsNativeTools, supportsStructuredOutput, synthesizeAnswer, unloadWebLLMModel, withSystem };
+export { type Agent, type AgentContext, type AgentEvent, type AgentEventHandler, type AgentLogger, type AgentLoggerSink, type AgentTool, type AgentToolSet, type AgentWebDBOptions, type AttachmentKind, AttachmentsNotSupportedError, type BrowserAgentConfig, type ClearedInfo, type CompactOptions, type CompactResult, type CompactionConfig, type CompressOptions, type ContextStore, type CredentialStore, type EffectiveToolStrategy, type EncryptedBlob, type ExecutorPromptContext, type ExecutorResult, FILES_STORE, FIND_TOOLS_NAME, type FileToolsOptions, type GenerateOptions, type IPlan, type IPlanStep, type IStepResult, type IToolCall, type IUsage, ImagesNotSupportedError, IndexedDBStore, type IndexedDBStoreOptions, KEYS_STORE, type LimitBreach, type LimitKind, type LoadSkillOptions, type LogLevel, MemoryCredentialStore, MemoryStore, type MessageEndpoint, type ModelInput, type ParentToWorker, type Phase, type PhaseBudgets, PlanSchema, type PlanShape, PlanStepSchema, type PlannerPromptContext, type PlannerResult, type PromptCachingSetting, type PromptParts, type Prompts, type ProviderModelSpec, type ProviderOptionsMap, type ProviderType, type ProxiedToolSpec, type RawAction, type ReplanDecision, type ReplanMode, ReplanSchema, type ReplanShape, type ReplanTrigger, type ReplannerPromptContext, type ReplannerResult, type ResolvedCaching, type ResolvedCompaction, type ResolvedConfig, type ResolvedStage, type ResolvedThinking, type RunFile, type RunImage, type RunOptions, type RunResult, SECRETS_STORE, SESSIONS_STORE, SKILL_TOOL_NAMES, type SearchToolsOptions, type ServeSubagentOptions, type Skill, type StageInput, type StageOverride, type StoredMessage, type SubagentToolOptions, type SubagentWorkerConfig, type SynthesizerPromptContext, TOOL_APPROVAL_MODES, type ThinkingConfig, type ThinkingLevel, type ThinkingSetting, type ThinkingStage, type TokenLimits, type ToolApprovalConfig, type ToolApprovalDecision, type ToolApprovalMode, type ToolApprovalRequest, ToolBudgetError, type ToolCallMode, type ToolCatalogEntry, ToolDeniedError, type ToolLoopCallbacks, type ToolLoopOptions, type ToolLoopResult, type ToolMode, type ToolPermission, type ToolResultClearing, type ToolRunContext, type ToolSelectionStrategy, type UsagePhase, VaultCredentialStore, VaultOptions, type VfsListener, type VirtualFile, type VirtualFileInfo, VirtualFileSystem, type VirtualFileSystemOptions, type WebLLMModelOptions, type WorkerLike, type WorkerToParent, attachmentKind, buildModelFromStage, bytesToBase64, checkLimits, compactHistory, compactSteps, compressHistory, createAgent, createFileTools, createFindToolsTool, createLogger, createPlan, createSkillTools, createSubagentTool, createToolResultClearer, createWebLLMModel, decideReplan, decideToolPermission, decryptJSON, defaultPrompts, defineSkill, defineTool, directBrowserOk, dispatch, encryptJSON, messageTokens as estimateMessagesTokens, estimateTokens, executeStep, generate, generateStructured, getOrCreateVaultKey, isAttachmentRefusal, isDirectModel, isImageRefusal, isProviderSpec, isReadOnlyTool, isTextMime, isWebGPUAvailable, limitModelOutput, loadSkillFromUrl, looksLikeJson, markReadOnly, matchRule, mediaTypeOf, mergeProviderOptions, mimeFromPath, normalizePath, normalizeSteps, normalizeUsage, openAgentWebDB, parseExecutorResponse, parsePlainText, parsePlannerResponse, parseReplannerResponse, parseSkillMarkdown, preloadWebLLMModel, promptHintOf, renderActiveSkills, renderCatalog, renderSearchCatalog, renderSkillIndex, replanWanted, resolveCaching, resolveCompaction, resolveConfig, resolveModel, resolveStage, resolveThinking, runToolLoop, schemaHintOf, searchTools, selectToolMode, serveSubagentWorker, shouldReplan, splitBlocker, stream, supportsImages, supportsNativeTools, supportsPdf, supportsStructuredOutput, synthesizeAnswer, thinkingFor, toFilePart, toImagePart, tokenize, toolCatalogOf, toolRunContextOf, unloadWebLLMModel, withRollingBreakpoint, withSystem };