@dudko.dev/agent-web 0.0.19 → 0.0.20

package/dist/index.cjs

@@ -77,6 +77,10 @@ var init_webllm = __esm({
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  AttachmentsNotSupportedError: () => AttachmentsNotSupportedError,
+  FILES_STORE: () => FILES_STORE,
+  FIND_TOOLS_NAME: () => FIND_TOOLS_NAME,
+  ImagesNotSupportedError: () => ImagesNotSupportedError,
   IndexedDBStore: () => IndexedDBStore,
   IndexedDBVault: () => IndexedDBVault,
   KEYS_STORE: () => KEYS_STORE,
@@ -87,28 +91,59 @@ __export(src_exports, {
   ReplanSchema: () => ReplanSchema,
   SECRETS_STORE: () => SECRETS_STORE,
   SESSIONS_STORE: () => SESSIONS_STORE,
+  SKILL_TOOL_NAMES: () => SKILL_TOOL_NAMES,
+  TOOL_APPROVAL_MODES: () => TOOL_APPROVAL_MODES,
+  ToolBudgetError: () => ToolBudgetError,
+  ToolDeniedError: () => ToolDeniedError,
   VaultCredentialStore: () => VaultCredentialStore,
+  VirtualFileSystem: () => VirtualFileSystem,
+  attachmentKind: () => attachmentKind,
   buildModelFromStage: () => buildModelFromStage,
+  bytesToBase64: () => bytesToBase64,
+  checkLimits: () => checkLimits,
+  compactHistory: () => compactHistory,
+  compactSteps: () => compactSteps,
   compressHistory: () => compressHistory,
   createAgent: () => createAgent,
+  createFileTools: () => createFileTools,
+  createFindToolsTool: () => createFindToolsTool,
   createLogger: () => createLogger,
   createPlan: () => createPlan,
+  createSkillTools: () => createSkillTools,
+  createSubagentTool: () => createSubagentTool,
+  createToolResultClearer: () => createToolResultClearer,
   createWebLLMModel: () => createWebLLMModel,
   decideReplan: () => decideReplan,
+  decideToolPermission: () => decideToolPermission,
   decryptJSON: () => decryptJSON,
   defaultPrompts: () => defaultPrompts,
+  defineSkill: () => defineSkill,
   defineTool: () => defineTool,
   directBrowserOk: () => directBrowserOk,
   dispatch: () => dispatch,
   encryptJSON: () => encryptJSON,
+  estimateMessagesTokens: () => messageTokens,
+  estimateTokens: () => estimateTokens,
   executeStep: () => executeStep,
   generate: () => generate,
   generateStructured: () => generateStructured,
   getOrCreateVaultKey: () => getOrCreateVaultKey,
+  isAttachmentRefusal: () => isAttachmentRefusal,
   isDirectModel: () => isDirectModel,
+  isImageRefusal: () => isImageRefusal,
   isProviderSpec: () => isProviderSpec,
+  isReadOnlyTool: () => isReadOnlyTool,
+  isTextMime: () => isTextMime,
   isWebGPUAvailable: () => isWebGPUAvailable,
+  limitModelOutput: () => limitModelOutput,
+  loadSkillFromUrl: () => loadSkillFromUrl,
   looksLikeJson: () => looksLikeJson,
+  markReadOnly: () => markReadOnly,
+  matchRule: () => matchRule,
+  mediaTypeOf: () => mediaTypeOf,
+  mergeProviderOptions: () => mergeProviderOptions,
+  mimeFromPath: () => mimeFromPath,
+  normalizePath: () => normalizePath,
   normalizeSteps: () => normalizeSteps,
   normalizeUsage: () => normalizeUsage,
   openAgentWebDB: () => openAgentWebDB,
@@ -116,49 +151,87 @@ __export(src_exports, {
   parsePlainText: () => parsePlainText,
   parsePlannerResponse: () => parsePlannerResponse,
   parseReplannerResponse: () => parseReplannerResponse,
+  parseSkillMarkdown: () => parseSkillMarkdown,
   preloadWebLLMModel: () => preloadWebLLMModel,
   promptHintOf: () => promptHintOf,
+  renderActiveSkills: () => renderActiveSkills,
   renderCatalog: () => renderCatalog,
+  renderSearchCatalog: () => renderSearchCatalog,
+  renderSkillIndex: () => renderSkillIndex,
   replanWanted: () => replanWanted,
+  resolveCaching: () => resolveCaching,
+  resolveCompaction: () => resolveCompaction,
   resolveConfig: () => resolveConfig,
   resolveModel: () => resolveModel,
   resolveStage: () => resolveStage,
+  resolveThinking: () => resolveThinking,
   runToolLoop: () => runToolLoop,
+  schemaHintOf: () => schemaHintOf,
+  searchTools: () => searchTools,
   selectToolMode: () => selectToolMode,
+  serveSubagentWorker: () => serveSubagentWorker,
   shouldReplan: () => shouldReplan,
   splitBlocker: () => splitBlocker,
   stream: () => stream,
+  supportsImages: () => supportsImages,
   supportsNativeTools: () => supportsNativeTools,
+  supportsPdf: () => supportsPdf,
   supportsStructuredOutput: () => supportsStructuredOutput,
   synthesizeAnswer: () => synthesizeAnswer,
+  thinkingFor: () => thinkingFor,
+  toFilePart: () => toFilePart,
+  toImagePart: () => toImagePart,
+  tokenize: () => tokenize,
+  toolCatalogOf: () => toolCatalogOf,
+  toolRunContextOf: () => toolRunContextOf,
   unloadWebLLMModel: () => unloadWebLLMModel,
+  withRollingBreakpoint: () => withRollingBreakpoint,
   withSystem: () => withSystem
 });
 module.exports = __toCommonJS(src_exports);
 
-// src/config.ts
-var resolveConfig = (c) => ({
-  clientName: c.clientName ?? "agent-web",
-  sessionId: c.sessionId ?? "default",
-  toolMode: c.toolMode ?? "auto",
-  toolSelectionStrategy: c.toolSelectionStrategy ?? "all",
-  maxIterations: c.maxIterations ?? 8,
-  maxStepsPerTask: c.maxStepsPerTask ?? 4,
-  maxRevisions: c.maxRevisions ?? 2,
-  chatTimeoutMs: c.chatTimeoutMs ?? 12e4,
-  budgets: {
-    planner: c.budgets?.planner ?? 800,
-    executor: c.budgets?.executor ?? 1200,
-    replanner: c.budgets?.replanner ?? 400,
-    synthesizer: c.budgets?.synthesizer ?? 400
-  },
-  temperature: c.temperature,
-  replan: c.replan ?? true,
-  replanAfter: c.replanAfter ?? "failure",
-  synthesize: c.synthesize ?? true,
-  compressAfterChars: c.compressAfterChars ?? 12e3,
-  logLevel: c.logLevel ?? "warn"
+// src/caching.ts
+var resolveCaching = (s) => {
+  if (s === false) return { enabled: false };
+  if (s === void 0 || s === true) return { enabled: true };
+  return { enabled: true, ttl: s.ttl, key: s.key };
+};
+var cachedInstructions = (system, caching) => caching.enabled ? {
+  role: "system",
+  content: system,
+  providerOptions: {
+    anthropic: {
+      cacheControl: { type: "ephemeral", ...caching.ttl ? { ttl: caching.ttl } : {} }
+    }
+  }
+} : system;
+var cachingProviderOptions = (caching, clientName, stage) => caching.enabled ? { openai: { promptCacheKey: caching.key ?? `${clientName}:${stage}` } } : void 0;
+var breakpoint = (ttl) => ({
+  anthropic: { cacheControl: { type: "ephemeral", ...ttl ? { ttl } : {} } }
 });
+var withoutBreakpoint = (m) => {
+  const own = m.providerOptions;
+  if (!own?.anthropic || !("cacheControl" in own.anthropic)) return m;
+  const { cacheControl: _drop, ...anthropic } = own.anthropic;
+  const { anthropic: _old, ...rest } = own;
+  const providerOptions = Object.keys(anthropic).length ? { ...rest, anthropic } : rest;
+  const { providerOptions: _po, ...base } = m;
+  return Object.keys(providerOptions).length ? { ...base, providerOptions } : base;
+};
+var withRollingBreakpoint = (messages, caching) => {
+  if (!caching.enabled || messages.length === 0) return messages;
+  const out = messages.map((m, i) => i < messages.length - 1 ? withoutBreakpoint(m) : m);
+  const last = out[out.length - 1];
+  const own = last.providerOptions ?? {};
+  out[out.length - 1] = {
+    ...last,
+    providerOptions: {
+      ...own,
+      anthropic: { ...own.anthropic, ...breakpoint(caching.ttl).anthropic }
+    }
+  };
+  return out;
+};
 
 // src/llm/generate.ts
 var import_ai = require("ai");
@@ -172,7 +245,10 @@ var normalizeUsage = (u) => {
   return {
     inputTokens,
     outputTokens,
-    totalTokens: u?.totalTokens ?? inputTokens + outputTokens
+    totalTokens: u?.totalTokens ?? inputTokens + outputTokens,
+    reasoningTokens: u?.outputTokenDetails?.reasoningTokens ?? u?.reasoningTokens ?? 0,
+    cachedInputTokens: u?.inputTokenDetails?.cacheReadTokens ?? u?.cachedInputTokens ?? 0,
+    cacheWriteTokens: u?.inputTokenDetails?.cacheWriteTokens ?? 0
   };
 };
 var timeoutSignal = (signal, ms) => {
@@ -183,53 +259,78 @@ var timeoutSignal = (signal, ms) => {
 };
 
 // src/llm/generate.ts
-var generate = (model, opts = {}) => (0, import_ai.generateText)({
-  model,
-  system: opts.system,
-  ...promptOf(opts),
-  tools: opts.tools,
+var callSettings = (opts) => ({
+  ...opts.system !== void 0 ? { instructions: opts.system } : {},
   maxOutputTokens: opts.maxOutputTokens,
   temperature: opts.temperature,
+  ...opts.reasoning ? { reasoning: opts.reasoning } : {},
+  ...opts.providerOptions ? { providerOptions: opts.providerOptions } : {},
   abortSignal: timeoutSignal(opts.abortSignal, opts.timeoutMs)
 });
+var generate = (model, opts = {}) => (0, import_ai.generateText)({
+  model,
+  ...callSettings(opts),
+  ...promptOf(opts),
+  tools: opts.tools
+});
 var stream = (model, opts = {}) => (0, import_ai.streamText)({
   model,
-  system: opts.system,
+  ...callSettings(opts),
   ...promptOf(opts),
-  tools: opts.tools,
-  maxOutputTokens: opts.maxOutputTokens,
-  temperature: opts.temperature,
-  abortSignal: timeoutSignal(opts.abortSignal, opts.timeoutMs)
+  tools: opts.tools
 });
 var generateStructured = (model, schema, opts = {}) => (0, import_ai.generateObject)({
   model,
   schema,
-  system: opts.system,
-  ...promptOf(opts),
-  maxOutputTokens: opts.maxOutputTokens,
-  temperature: opts.temperature,
-  abortSignal: timeoutSignal(opts.abortSignal, opts.timeoutMs)
+  ...callSettings(opts),
+  ...promptOf(opts)
 });
 
 // src/memory/compress.ts
-var totalChars = (msgs) => msgs.reduce((n, m) => n + m.content.length, 0);
+var resolveCompaction = (c) => {
+  const contextWindowTokens = c?.contextWindowTokens ?? 128e3;
+  return {
+    auto: c?.auto ?? true,
+    contextWindowTokens,
+    thresholdTokens: c?.thresholdTokens ?? Math.floor(contextWindowTokens / 2),
+    keepRecentTurns: c?.keepRecentTurns ?? 4,
+    keepRecentSteps: c?.keepRecentSteps ?? 3,
+    summaryMaxTokens: c?.summaryMaxTokens ?? 1024,
+    maxToolOutputChars: c?.maxToolOutputChars ?? 2e4,
+    clearToolResultsAfterTokens: c?.clearToolResultsAfterTokens ?? Math.floor(contextWindowTokens / 4),
+    keepToolResults: c?.keepToolResults ?? 3
+  };
+};
+var estimateTokens = (text) => Math.ceil((text ?? "").length / 4);
+var messageTokens = (msgs) => msgs.reduce((n, m) => n + estimateTokens(`${m.role}: ${m.content}
+`), 0);
+var SUMMARY_SYSTEM = "Summarize the following conversation into a compact set of durable facts, decisions, identifiers, open tasks and user preferences. Keep names, numbers and IDs verbatim. Output plain text only.";
 var compressHistory = async (messages, model, opts = {}) => {
-  const maxChars = opts.maxChars ?? 12e3;
   const keepRecent = opts.keepRecent ?? 6;
-  if (maxChars <= 0 || messages.length <= keepRecent + 1 || totalChars(messages) <= maxChars) {
-    return messages;
+  if (messages.length <= keepRecent + 1) return messages;
+  if (!opts.force) {
+    if (opts.thresholdTokens !== void 0) {
+      if (opts.thresholdTokens <= 0 || messageTokens(messages) <= opts.thresholdTokens) {
+        return messages;
+      }
+    } else {
+      const maxChars = opts.maxChars ?? 12e3;
+      const chars = messages.reduce((n, m) => n + m.content.length, 0);
+      if (maxChars <= 0 || chars <= maxChars) return messages;
+    }
   }
   const head = messages.slice(0, messages.length - keepRecent);
   const tail = messages.slice(messages.length - keepRecent);
-  const transcript = head.map((m) => `${m.role}: ${m.content}`).join("\n").slice(0, 8e3);
+  const transcript = head.map((m) => `${m.role}: ${m.content}`).join("\n").slice(-48e3);
   try {
     const result = await generate(model, {
-      system: "Summarize the following conversation into a compact set of durable facts and decisions. Output plain text only.",
+      system: SUMMARY_SYSTEM,
       prompt: transcript,
-      maxOutputTokens: 400,
+      maxOutputTokens: opts.summaryMaxTokens ?? 400,
       timeoutMs: opts.timeoutMs,
       abortSignal: opts.abortSignal
     });
+    opts.onUsage?.(normalizeUsage(result.usage));
     const clean = (result.text || "").trim();
     if (!clean) return messages;
     const summaryMsg = {
@@ -243,6 +344,93 @@ ${clean}`,
     return messages;
   }
 };
+var compactHistory = compressHistory;
+var TRACE_SYSTEM = "Summarize these completed agent steps into a compact progress note: what was done, what was found (keep names, numbers and IDs verbatim) and what failed. Plain text only.";
+var compactSteps = async (done, model, opts) => {
+  const keepRecent = opts.keepRecent ?? 3;
+  if (done.length <= keepRecent + 1) return done;
+  if (!opts.force && estimateTokens(done.join("\n")) <= opts.thresholdTokens) return done;
+  const head = done.slice(0, done.length - keepRecent);
+  try {
+    const result = await generate(model, {
+      system: TRACE_SYSTEM,
+      prompt: head.map((d, i) => `${i + 1}. ${d}`).join("\n"),
+      maxOutputTokens: opts.summaryMaxTokens ?? 600,
+      timeoutMs: opts.timeoutMs,
+      abortSignal: opts.abortSignal
+    });
+    opts.onUsage?.(normalizeUsage(result.usage));
+    const clean = (result.text || "").trim();
+    if (!clean) return done;
+    return [`Summary of ${head.length} earlier step(s): ${clean}`, ...done.slice(head.length)];
+  } catch {
+    return done;
+  }
+};
+
+// src/config.ts
+var resolveConfig = (c) => ({
+  clientName: c.clientName ?? "agent-web",
+  sessionId: c.sessionId ?? "default",
+  toolMode: c.toolMode ?? "auto",
+  toolSelectionStrategy: c.toolSelectionStrategy ?? "auto",
+  toolSearchThreshold: c.toolSearchThreshold ?? 40,
+  maxIterations: c.maxIterations ?? 8,
+  maxStepsPerTask: c.maxStepsPerTask ?? 4,
+  maxRevisions: c.maxRevisions ?? 2,
+  maxToolCalls: c.maxToolCalls ?? 0,
+  maxPlanSteps: c.maxPlanSteps ?? 8,
+  chatTimeoutMs: c.chatTimeoutMs ?? 12e4,
+  budgets: {
+    planner: c.limits?.perCall?.planner ?? c.budgets?.planner ?? 800,
+    executor: c.limits?.perCall?.executor ?? c.budgets?.executor ?? 1200,
+    replanner: c.limits?.perCall?.replanner ?? c.budgets?.replanner ?? 400,
+    synthesizer: c.limits?.perCall?.synthesizer ?? c.budgets?.synthesizer ?? 400,
+    compaction: c.limits?.perCall?.compaction ?? c.compaction?.summaryMaxTokens ?? 1024
+  },
+  limits: c.limits ?? {},
+  temperature: c.temperature,
+  replan: c.replan ?? true,
+  replanAfter: c.replanAfter ?? "failure",
+  synthesize: c.synthesize ?? true,
+  compressAfterChars: c.compressAfterChars ?? 12e3,
+  compaction: resolveCompaction(c.compaction),
+  logLevel: c.logLevel ?? "warn"
+});
+
+// src/limits.ts
+var over = (value, cap) => typeof cap === "number" && cap > 0 && (value ?? 0) >= cap;
+var checkLimits = (usage, limits) => {
+  if (!limits) return void 0;
+  if (over(usage.totalTokens, limits.maxTotalTokens)) {
+    return { kind: "total", tokens: usage.totalTokens, cap: limits.maxTotalTokens };
+  }
+  if (over(usage.inputTokens, limits.maxInputTokens)) {
+    return { kind: "input", tokens: usage.inputTokens, cap: limits.maxInputTokens };
+  }
+  if (over(usage.outputTokens, limits.maxOutputTokens)) {
+    return { kind: "output", tokens: usage.outputTokens, cap: limits.maxOutputTokens };
+  }
+  if (over(usage.reasoningTokens, limits.maxReasoningTokens)) {
+    return {
+      kind: "reasoning",
+      tokens: usage.reasoningTokens ?? 0,
+      cap: limits.maxReasoningTokens
+    };
+  }
+  return void 0;
+};
+var ToolBudgetError = class extends Error {
+  constructor(cap) {
+    super(
+      `Tool-call budget exhausted (${cap} per run). Do not call more tools; report what you have.`
+    );
+    this.name = "ToolBudgetError";
+  }
+  toJSON() {
+    return this.message;
+  }
+};
 
 // src/providers/types.ts
 var isDirectModel = (m) => typeof m === "string" || typeof m === "object" && m !== null && "specificationVersion" in m;
@@ -445,54 +633,77 @@ var historyBlock = (history) => {
 CONVERSATION SO FAR:
 ${lines.join("\n")}`;
 };
-var PLANNER_NATIVE = `You are the PLANNER of a tool-using agent that changes a workspace step by step.
-Produce a brief "thought" and an ordered "steps" list (1\u20136 DISTINCT, self-contained steps) grounded in the current STATE and the available TOOLS.
-If the user only greets, thanks, makes small talk, asks a question, or is unclear: return an EMPTY steps list and put a short, friendly answer in "thought".
-If a CONVERSATION SO FAR section is present, use it to resolve references to earlier turns.
-Never repeat or pad steps.`;
-var PLANNER_PROMPTED = `You are the PLANNER of a tool-using agent that changes a workspace step by step.
+var section = (title, body) => body && body.trim() ? `
 
-Reply with a single JSON object, nothing else:
-{ "reply": string, "plan": string[] }
-- Only produce a "plan" when the user CLEARLY asks to build, do, or change something. For a greeting, small talk, thanks, a question, or an unclear/empty request: set "plan": [] and put a short, friendly "reply".
-- For a real goal: "reply" is one short sentence; "plan" is 1\u20136 DISTINCT, self-contained steps. Never repeat or pad steps.
+${title}:
+${body.trim()}` : "";
+var PLANNER_RULES = `- Act autonomously: whenever the TOOLS can do the work or look up the answer, plan the steps \u2014 a question that needs data, a lookup or a check is a real goal too.
+- Never plan a step that asks the user something. If the request is ambiguous, pick the most reasonable interpretation and say which one you chose.
 - Plan realistic steps the available TOOLS can perform, grounded in the current STATE.
-- If a CONVERSATION SO FAR section is present, use it to resolve references to earlier turns.`;
-var EXECUTOR_NATIVE = `You are the EXECUTOR of a tool-using agent. Carry out ONLY the current step by calling the provided tools.
-Build on the current STATE \u2014 do not repeat work that is already there.
-When the step is done, reply with one short human sentence describing what you did (no JSON).
-If you CANNOT complete the step (a needed tool is missing or an input is unavailable), explain why in one sentence and include the token [BLOCKER].`;
-var EXECUTOR_PROMPTED = `You are the EXECUTOR of a tool-using agent. Carry out ONLY the current step by emitting tool calls.
+- If a CONVERSATION SO FAR section is present, use it to resolve references to earlier turns.
+- Never repeat or pad steps.`;
+var PLANNER_NATIVE = `You are the PLANNER of an autonomous tool-using agent that works step by step.
+Produce a brief "thought" and an ordered "steps" list (1\u20136 DISTINCT, self-contained steps).
+Return an EMPTY steps list ONLY for a pure greeting, thanks or small talk, or a question you can answer completely from the STATE and general knowledge without any tool \u2014 then put the answer itself in "thought".
+${PLANNER_RULES}`;
+var PLANNER_PROMPTED = `You are the PLANNER of an autonomous tool-using agent that works step by step.
+
+Reply with a single JSON object, nothing else:
+{ "reply": string, "plan": string[], "skills": string[] }
+- For a real goal: "reply" is one short sentence; "plan" is 1\u20136 DISTINCT, self-contained steps.
+- Set "plan": [] ONLY for a pure greeting, thanks or small talk, or a question you can answer completely from the STATE and general knowledge without any tool \u2014 then put the answer itself in "reply".
+${PLANNER_RULES}`;
+var PLANNER_SKILLS = `
+If a SKILLS list is present, list the names of the skills that apply to this goal in "skills" (or leave it empty).`;
+var PLANNER_SEARCH = `
+The TOOLS list may be abbreviated: the executor can search the full catalogue, so describe WHAT to do; name tools only when you see them listed.`;
+var EXECUTOR_RULES = `- Work autonomously: never ask the user questions or for confirmation. Look things up with the tools, choose sensible defaults, and state any assumption in your reply. Permission to run tools is handled by the system, not by you.
+- Build on the current STATE and on the results of earlier steps \u2014 do not repeat work that is already done.`;
+var EXECUTOR_NATIVE = `You are the EXECUTOR of an autonomous tool-using agent. Carry out ONLY the current step by calling the provided tools.
+${EXECUTOR_RULES}
+- When the step is done, reply with a short factual summary of what you did and found, including the concrete data (names, ids, numbers, values) later steps or the final answer need. No JSON.
+- If you truly CANNOT complete the step (a needed tool is missing or was denied, credentials or data are unavailable), explain why in one sentence and include the token [BLOCKER].`;
+var EXECUTOR_PROMPTED = `You are the EXECUTOR of an autonomous tool-using agent. Carry out ONLY the current step by emitting tool calls.
 
 Reply with a single JSON object, nothing else:
 { "reply": string, "actions": [ { "tool": string, "args": object } ] }
 - "actions" are the tool calls for THIS step ([] if none are needed). Use ONLY tools from the TOOLS list; "args" must match the tool's parameters.
-- Build on the current STATE \u2014 do not repeat work that is already there.
-- "reply" is one short human sentence (no JSON) describing what you did.
+${EXECUTOR_RULES}
+- "reply" is a short factual summary (no JSON) of what you did and found, with the concrete data later steps need.
 - After your actions run you will see their TOOL RESULTS and may continue the same step; finish with "actions": [] once it is done.
-- If you CANNOT complete the step, set "actions": [] and put the token [BLOCKER] in "reply" with a short reason.`;
-var REPLANNER_NATIVE = `You are the REPLANNER. After an executed step, decide whether to keep going, revise the remaining steps, or finish.
+- If you truly CANNOT complete the step, set "actions": [] and put the token [BLOCKER] in "reply" with a short reason.`;
+var EXECUTOR_SEARCH = `
+- If a tool you need is not in your current tool list, call find_tools with keywords; the tools it returns become callable right after.`;
+var EXECUTOR_SKILLS = `
+- If a skill from the SKILLS list covers this step, call load_skill to read it first (read_skill_file for its bundled files).`;
+var REPLANNER_RULES = `Judge from the current STATE and the progress vs the goal. Prefer "continue".
+After a failure, prefer revising around it (another tool, another approach) over giving up; never add a step that asks the user something.`;
+var REPLANNER_NATIVE = `You are the REPLANNER of an autonomous agent. After an executed step, decide whether to keep going, revise the remaining steps, or finish.
 "continue": the remaining steps still fit. "revise": provide a better "plan" for the REMAINING work (never repeat done work). "finish": the goal is already met.
-Judge from the current STATE vs the goal. Prefer "continue".`;
-var REPLANNER_PROMPTED = `You are the REPLANNER. After each executed step you decide whether to keep going, revise the remaining steps, or finish.
+${REPLANNER_RULES}`;
+var REPLANNER_PROMPTED = `You are the REPLANNER of an autonomous agent. After each executed step you decide whether to keep going, revise the remaining steps, or finish.
 
 Reply with a single JSON object, nothing else:
 { "decision": "continue" | "revise" | "finish", "reason": string, "plan": string[] }
 - "continue": remaining steps still fit \u2014 proceed (omit "plan").
 - "revise": replace the REMAINING steps with a better list in "plan"; never repeat done work.
 - "finish": the goal is already met \u2014 stop (omit "plan").
-Judge from the current STATE vs the goal. Prefer "continue".`;
-var SYNTHESIZER_SYSTEM = `You are the SYNTHESIZER. In 1\u20133 short, friendly sentences, tell the user what was done to meet their goal. Be concrete. Output plain text only \u2014 no JSON, no code.`;
+${REPLANNER_RULES}`;
+var SYNTHESIZER_SYSTEM = `You are the SYNTHESIZER. Answer the user's goal from what the agent did and found.
+- Lead with the result: the concrete data, from the FINDINGS verbatim when accuracy matters (names, numbers, ids), then \u2014 briefly \u2014 what was changed.
+- Mention any assumption the agent made. If something could not be done, say so plainly and why.
+- Do not ask follow-up questions unless the goal genuinely cannot be completed without the user.
+- Be concise and friendly. Plain text (light markdown is fine) \u2014 no JSON, no code.`;
 var defaultPrompts = {
   planner: (ctx) => ({
-    system: ctx.mode === "prompted" ? PLANNER_PROMPTED : PLANNER_NATIVE,
-    prompt: `GOAL: ${ctx.goal}${historyBlock(ctx.history)}${stateBlock(ctx.state)}
+    system: (ctx.mode === "prompted" ? PLANNER_PROMPTED : PLANNER_NATIVE) + (ctx.skills ? PLANNER_SKILLS : "") + (ctx.searchMode ? PLANNER_SEARCH : "") + section("SKILLS", ctx.skills) + `
 
 TOOLS:
-${ctx.toolCatalog}`
+${ctx.toolCatalog}`,
+    prompt: `GOAL: ${ctx.goal}${historyBlock(ctx.history)}${stateBlock(ctx.state)}`
   }),
   executor: (ctx) => ({
-    system: ctx.mode === "prompted" ? EXECUTOR_PROMPTED : EXECUTOR_NATIVE,
+    system: (ctx.mode === "prompted" ? EXECUTOR_PROMPTED : EXECUTOR_NATIVE) + (ctx.searchMode ? EXECUTOR_SEARCH : "") + (ctx.skills ? EXECUTOR_SKILLS : "") + section("SKILLS", ctx.skills) + section("ACTIVE SKILL INSTRUCTIONS", ctx.activeSkills),
     prompt: [
       `GOAL: ${ctx.goal}`,
       stateBlock(ctx.state).trimStart(),
@@ -504,7 +715,7 @@ ${numbered(ctx.done, "")}` : "",
     ].filter(Boolean).join("\n\n")
   }),
   replanner: (ctx) => ({
-    system: ctx.mode === "prompted" ? REPLANNER_PROMPTED : REPLANNER_NATIVE,
+    system: (ctx.mode === "prompted" ? REPLANNER_PROMPTED : REPLANNER_NATIVE) + section("ACTIVE SKILL INSTRUCTIONS", ctx.activeSkills),
     prompt: [
       `GOAL: ${ctx.goal}`,
       stateBlock(ctx.state).trimStart(),
@@ -516,13 +727,15 @@ ${numbered(ctx.remaining, "(none)")}`,
     ].filter(Boolean).join("\n\n")
   }),
   synthesizer: (ctx) => ({
-    system: SYNTHESIZER_SYSTEM,
+    system: SYNTHESIZER_SYSTEM + section("ACTIVE SKILL INSTRUCTIONS", ctx.activeSkills),
     prompt: [
       `GOAL: ${ctx.goal}`,
       stateBlock(ctx.state).trimStart(),
       `What was done:
 ${numbered(ctx.done, "(no changes)")}`,
-      "Write the final summary for the user."
+      ctx.findings?.length ? `FINDINGS (tool results):
+${ctx.findings.join("\n")}` : "",
+      "Write the final answer for the user."
     ].filter(Boolean).join("\n\n")
   })
 };
@@ -530,6 +743,294 @@ var withSystem = (base, extra) => extra && extra.trim() ? `${extra.trim()}
 
 ${base}` : base;
 
+// src/skills.ts
+var import_ai3 = require("ai");
+var SKILL_NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+var SKILL_TOOL_NAMES = ["load_skill", "read_skill_file"];
+var defineSkill = (skill) => {
+  if (!skill || typeof skill !== "object") throw new Error("skill must be an object");
+  if (typeof skill.name !== "string" || !SKILL_NAME_RE.test(skill.name)) {
+    throw new Error(
+      `skill name ${JSON.stringify(skill.name)} is invalid: use 1-64 lowercase letters, digits and dashes`
+    );
+  }
+  if (typeof skill.description !== "string" || !skill.description.trim()) {
+    throw new Error(`skill "${skill.name}" needs a description`);
+  }
+  if (typeof skill.content !== "string") {
+    throw new Error(`skill "${skill.name}" needs a content string`);
+  }
+  for (const f of skill.files ?? []) {
+    if (typeof f?.path !== "string" || !f.path || f.path.startsWith("/") || f.path.includes("..")) {
+      throw new Error(`skill "${skill.name}": invalid file path ${JSON.stringify(f?.path)}`);
+    }
+  }
+  return skill;
+};
+var unquote = (v) => {
+  const t = v.trim();
+  if (t.length >= 2 && t.startsWith('"') && t.endsWith('"')) {
+    try {
+      return JSON.parse(t);
+    } catch {
+      return t.slice(1, -1);
+    }
+  }
+  if (t.length >= 2 && t.startsWith("'") && t.endsWith("'")) {
+    return t.slice(1, -1).replace(/''/g, "'");
+  }
+  return t;
+};
+var parseFrontmatter = (block) => {
+  const out = {};
+  const lines = block.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i += 1) {
+    const m = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(lines[i]);
+    if (!m) continue;
+    const [, key, rest] = m;
+    if (rest === ">" || rest === "|" || rest === ">-" || rest === "|-") {
+      const body = [];
+      while (i + 1 < lines.length && (/^\s+\S/.test(lines[i + 1]) || lines[i + 1] === "")) {
+        body.push(lines[i + 1].trim());
+        i += 1;
+      }
+      out[key] = rest.startsWith(">") ? body.filter(Boolean).join(" ") : body.join("\n").trim();
+      continue;
+    }
+    out[key] = unquote(rest);
+  }
+  return out;
+};
+var parseSkillMarkdown = (markdown, files) => {
+  const text = (markdown ?? "").replace(/^/, "");
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
+  if (!m) throw new Error("SKILL.md must start with a --- frontmatter block (name, description)");
+  const meta = parseFrontmatter(m[1]);
+  return defineSkill({
+    name: meta.name ?? "",
+    description: meta.description ?? "",
+    content: m[2].trim(),
+    ...files?.length ? { files } : {}
+  });
+};
+var loadSkillFromUrl = async (url, opts = {}) => {
+  const fetchFn = opts.fetch ?? globalThis.fetch;
+  const res = await fetchFn(url);
+  if (!res.ok) throw new Error(`could not fetch ${url}: HTTP ${res.status}`);
+  const markdown = await res.text();
+  const files = [];
+  for (const path of opts.files ?? []) {
+    const r = await fetchFn(new URL(path, url).toString());
+    if (!r.ok) throw new Error(`could not fetch skill file ${path}: HTTP ${r.status}`);
+    files.push({ path, content: await r.text() });
+  }
+  return parseSkillMarkdown(markdown, files);
+};
+var renderSkillIndex = (skills) => skills.map((s) => `- ${s.name}: ${s.description.replace(/\s+/g, " ").trim()}`).join("\n");
+var ACTIVE_SKILLS_BUDGET = 24e3;
+var renderActiveSkills = (skills) => {
+  let budget = ACTIVE_SKILLS_BUDGET;
+  const parts = [];
+  for (const s of skills) {
+    if (budget <= 0) break;
+    const files = s.files?.length ? `
+(bundled files, read with read_skill_file: ${s.files.map((f) => f.path).join(", ")})` : "";
+    const block = clip(`### Skill: ${s.name}
+${s.content}${files}`, budget);
+    budget -= block.length;
+    parts.push(block);
+  }
+  return parts.join("\n\n");
+};
+var createSkillTools = (skills, onLoad) => {
+  const byName = new Map(skills.map((s) => [s.name, s]));
+  const known = skills.map((s) => s.name).join(", ");
+  const loadSkill = (0, import_ai3.tool)({
+    description: "Load the full instructions of a skill from the SKILLS list before doing work it covers.",
+    inputSchema: (0, import_ai3.jsonSchema)({
+      type: "object",
+      properties: { name: { type: "string", description: "The skill name" } },
+      required: ["name"],
+      additionalProperties: false
+    }),
+    execute: async ({ name }) => {
+      const skill = byName.get(name);
+      if (!skill) throw new Error(`unknown skill "${name}"; available: ${known}`);
+      onLoad?.(skill);
+      return {
+        name: skill.name,
+        content: skill.content,
+        files: (skill.files ?? []).map((f) => f.path)
+      };
+    }
+  });
+  const readFile = (0, import_ai3.tool)({
+    description: "Read one of a skill's bundled files (paths are listed by load_skill).",
+    inputSchema: (0, import_ai3.jsonSchema)({
+      type: "object",
+      properties: {
+        name: { type: "string", description: "The skill name" },
+        path: { type: "string", description: "The file path, relative to the skill" }
+      },
+      required: ["name", "path"],
+      additionalProperties: false
+    }),
+    execute: async ({ name, path }) => {
+      const skill = byName.get(name);
+      if (!skill) throw new Error(`unknown skill "${name}"; available: ${known}`);
+      const file = skill.files?.find((f) => f.path === path);
+      if (!file) {
+        const listed = (skill.files ?? []).map((f) => f.path).join(", ") || "none";
+        throw new Error(`skill "${name}" has no file "${path}"; files: ${listed}`);
+      }
+      return file.content;
+    }
+  });
+  for (const t of [loadSkill, readFile]) {
+    ;
+    t.readOnly = true;
+    t.promptHint = t === loadSkill ? "{ name: string }" : "{ name: string, path: string }";
+  }
+  return { load_skill: loadSkill, read_skill_file: readFile };
+};
+
+// src/tools/approval.ts
+var TOOL_APPROVAL_MODES = [
+  "autopilot",
+  "ask-writes",
+  "ask-all",
+  "read-only"
+];
+var ToolDeniedError = class extends Error {
+  constructor(reason) {
+    super(
+      `Tool call denied by the user${reason ? `: ${reason}` : ""}. Do not retry it; continue without it, or report what is blocked.`
+    );
+    this.name = "ToolDeniedError";
+  }
+  toJSON() {
+    return this.message;
+  }
+};
+var markReadOnly = (tool6, readOnly = true) => {
+  ;
+  tool6.readOnly = readOnly;
+  return tool6;
+};
+var isReadOnlyTool = (tool6) => tool6?.readOnly === true;
+var globToRegExp = (glob) => new RegExp(
+  `^${glob.split("*").map((s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*")}$`
+);
+var matchRule = (rules, toolName) => {
+  if (!rules) return void 0;
+  if (Object.hasOwn(rules, toolName)) return rules[toolName];
+  let best;
+  for (const [pattern, perm] of Object.entries(rules)) {
+    if (!pattern.includes("*")) continue;
+    if (!globToRegExp(pattern).test(toolName)) continue;
+    const len = pattern.replace(/\*/g, "").length;
+    if (!best || len > best.len) best = { len, perm };
+  }
+  return best?.perm;
+};
+var decideToolPermission = (opts) => {
+  if (opts.remembered?.has(opts.toolName)) return "allow";
+  const rule = matchRule(opts.rules, opts.toolName);
+  if (rule) return rule;
+  switch (opts.mode) {
+    case "autopilot":
+      return "allow";
+    case "read-only":
+      return opts.readOnly ? "allow" : "deny";
+    case "ask-writes":
+      return opts.readOnly ? "allow" : "ask";
+    case "ask-all":
+      return "ask";
+  }
+};
+var normalizeDecision = (d) => typeof d === "boolean" ? { approved: d } : { approved: Boolean(d?.approved), reason: d?.reason, remember: d?.remember };
+var createApprovalState = (config) => ({
+  mode: config?.mode ?? "autopilot",
+  config: config ?? {},
+  remembered: /* @__PURE__ */ new Set()
+});
+var seq = 0;
+var gateToolCall = async (state, call, events, signal) => {
+  const permission = decideToolPermission({
+    toolName: call.toolName,
+    readOnly: call.readOnly,
+    mode: state.mode,
+    rules: state.config.rules,
+    remembered: state.remembered
+  });
+  if (permission === "allow") return;
+  const id = `approval-${Date.now().toString(36)}-${seq += 1}`;
+  if (permission === "deny") {
+    const reason = state.mode === "read-only" && !matchRule(state.config.rules, call.toolName) ? "the agent is in read-only mode" : "blocked by policy";
+    events.resolved({ id, name: call.toolName, approved: false, reason, automatic: true });
+    throw new ToolDeniedError(reason);
+  }
+  const onRequest = state.config.onRequest;
+  if (!onRequest) {
+    const reason = "no approval handler configured";
+    events.resolved({ id, name: call.toolName, approved: false, reason, automatic: true });
+    throw new ToolDeniedError(reason);
+  }
+  const req = { id, ...call };
+  events.requested(req);
+  let decision;
+  try {
+    decision = normalizeDecision(
+      await withDeadline(Promise.resolve(onRequest(req)), state.config.timeoutMs, signal)
+    );
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    events.resolved({ id, name: call.toolName, approved: false, reason, automatic: true });
+    throw new ToolDeniedError(reason);
+  }
+  if (decision.approved && decision.remember) state.remembered.add(call.toolName);
+  events.resolved({
+    id,
+    name: call.toolName,
+    approved: decision.approved,
+    reason: decision.reason,
+    automatic: false
+  });
+  if (!decision.approved) throw new ToolDeniedError(decision.reason);
+};
+var withDeadline = (p, timeoutMs, signal) => {
+  if ((!timeoutMs || timeoutMs <= 0) && !signal) return p;
+  return new Promise((resolve, reject) => {
+    let timer;
+    const done = () => {
+      if (timer !== void 0) clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    };
+    const onAbort = () => {
+      done();
+      reject(new Error("the run was stopped while waiting for approval"));
+    };
+    if (signal?.aborted) return onAbort();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (timeoutMs && timeoutMs > 0) {
+      timer = setTimeout(() => {
+        done();
+        reject(new Error(`no approval decision within ${timeoutMs} ms`));
+      }, timeoutMs);
+    }
+    p.then(
+      (v) => {
+        done();
+        resolve(v);
+      },
+      (e) => {
+        done();
+        reject(e);
+      }
+    );
+  });
+};
+
 // src/tools/mode.ts
 var LOCAL_RE = /web-?llm|mlc|browser-ai|transformers|nano|built-?in/i;
 var selectToolMode = (model, mode = "auto") => {
@@ -540,15 +1041,15 @@ var selectToolMode = (model, mode = "auto") => {
 };
 
 // src/tools/types.ts
-var promptHintOf = (tool2) => typeof tool2.promptHint === "string" ? tool2.promptHint : void 0;
+var promptHintOf = (tool6) => typeof tool6.promptHint === "string" ? tool6.promptHint : void 0;
 
 // src/tools/prompted.ts
-var renderCatalog = (tools) => {
+var renderCatalog = (tools, hintOf) => {
   const names = Object.keys(tools);
   if (names.length === 0) return "(no tools)";
   return names.map((name) => {
     const t = tools[name];
-    const hint = promptHintOf(t) ?? "";
+    const hint = promptHintOf(t) ?? hintOf?.(name) ?? "";
     const desc = typeof t.description === "string" ? t.description : "";
     return `- ${name}(${hint}): ${desc}`;
   }).join("\n");
@@ -598,20 +1099,269 @@ var dispatch = async (action, tools, ctx = {}) => {
   }
 };
 
+// src/tools/search.ts
+var import_ai4 = require("ai");
+var FIND_TOOLS_NAME = "find_tools";
+var toolCatalogOf = (tools) => Object.entries(tools).map(([name, t]) => {
+  const sep = name.indexOf("__");
+  return {
+    name,
+    description: typeof t.description === "string" ? t.description : "",
+    ...sep > 0 ? { server: name.slice(0, sep) } : {},
+    readOnly: isReadOnlyTool(t)
+  };
+});
+var tokenize = (s) => (s ?? "").replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+var hits = (term, words) => words.some(
+  (w) => w === term || term.length >= 3 && (w.startsWith(term) || term.startsWith(w) && w.length >= 3)
+);
+var searchTools = (catalog, query, opts = {}) => {
+  const terms = [...new Set(tokenize(query))];
+  const limit = Math.min(Math.max(1, opts.limit ?? 8), 20);
+  const server = opts.server?.toLowerCase();
+  const scored = [];
+  catalog.forEach((entry, index) => {
+    if (opts.exclude?.has(entry.name)) return;
+    if (server && entry.server?.toLowerCase() !== server) return;
+    const nameWords = tokenize(
+      entry.server ? entry.name.slice(entry.server.length + 2) : entry.name
+    );
+    const serverWords = tokenize(entry.server ?? "");
+    const descWords = tokenize(entry.description);
+    let score = 0;
+    for (const term of terms) {
+      if (hits(term, nameWords)) score += 3;
+      if (hits(term, serverWords)) score += 2;
+      if (hits(term, descWords)) score += 1;
+    }
+    if (terms.length === 0 && server) score = 1;
+    if (score > 0) scored.push({ entry, score, index });
+  });
+  scored.sort((a, b) => b.score - a.score || a.index - b.index);
+  return scored.slice(0, limit).map((s) => s.entry);
+};
+var renderSearchCatalog = (catalog, budget = 12e3) => {
+  if (catalog.length === 0) return "(no tools)";
+  const groups = /* @__PURE__ */ new Map();
+  for (const e of catalog) {
+    const key = e.server ?? "(host)";
+    groups.set(key, [...groups.get(key) ?? [], e]);
+  }
+  const lines = [];
+  let used = 0;
+  let shown = 0;
+  for (const [server, entries] of groups) {
+    const head = `[${server}] ${entries.length} tool(s)`;
+    if (used + head.length > budget) break;
+    lines.push(head);
+    used += head.length + 1;
+    for (const e of entries) {
+      const desc = e.description.replace(/\s+/g, " ").trim().slice(0, 60);
+      const line = `- ${e.name}${desc ? `: ${desc}` : ""}`;
+      if (used + line.length > budget) break;
+      lines.push(line);
+      used += line.length + 1;
+      shown += 1;
+    }
+  }
+  const rest = catalog.length - shown;
+  if (rest > 0)
+    lines.push(`\u2026 ${rest} more tool(s) \u2014 the executor can find them with ${FIND_TOOLS_NAME}`);
+  return lines.join("\n");
+};
+var createFindToolsTool = (catalog, onFound, hintOf) => {
+  const t = (0, import_ai4.tool)({
+    description: "Search the full tool catalogue by keywords and make the matching tools callable from the next step on. Use it whenever the tool you need is not in your current tool list.",
+    inputSchema: (0, import_ai4.jsonSchema)({
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Keywords: what the tool should do" },
+        server: { type: "string", description: "Optional: only tools of this MCP server" },
+        limit: { type: "number", description: "Max results (default 8, max 20)" }
+      },
+      required: ["query"],
+      additionalProperties: false
+    }),
+    execute: async ({ query, server, limit }) => {
+      const found = searchTools(catalog(), query, { server, limit });
+      onFound(
+        query,
+        found.map((f) => f.name)
+      );
+      return {
+        tools: found.map((f) => ({
+          name: f.name,
+          description: f.description,
+          ...f.server ? { server: f.server } : {},
+          readOnly: Boolean(f.readOnly),
+          ...hintOf?.(f.name) ? { args: hintOf(f.name) } : {}
+        })),
+        note: found.length ? "These tools are now callable." : "No tool matched; try other keywords or a server name."
+      };
+    }
+  });
+  t.readOnly = true;
+  t.promptHint = "{ query: string, server?: string, limit?: number }";
+  return t;
+};
+
+// src/tools/wrap.ts
+var import_ai5 = require("ai");
+var toolRunContextOf = (options) => options?.agentRun;
+var truncated = (s, max) => s.length > max ? `${s.slice(0, max)}\u2026 [truncated ${s.length - max} chars]` : s;
+var toText = (v) => {
+  if (typeof v === "string") return v;
+  try {
+    return JSON.stringify(v) ?? String(v);
+  } catch {
+    return String(v);
+  }
+};
+var limitModelOutput = (original, maxChars) => (async (opts) => {
+  const base = original ? await original(opts) : typeof opts.output === "string" ? { type: "text", value: opts.output } : { type: "json", value: opts.output ?? null };
+  if (base.type === "text" || base.type === "error-text") {
+    return { ...base, value: truncated(base.value, maxChars) };
+  }
+  if (base.type === "json" || base.type === "error-json") {
+    const text = toText(base.value);
+    if (text.length <= maxChars) return base;
+    return {
+      type: base.type === "json" ? "text" : "error-text",
+      value: truncated(text, maxChars)
+    };
+  }
+  return base;
+});
+var wrapToolsForRun = (tools, o) => {
+  const out = {};
+  const gate = (toolName, input, readOnly, signal) => gateToolCall(
+    o.approval,
+    { toolName, input, readOnly, step: o.step() },
+    {
+      requested: (req) => o.emit({
+        type: "tool.approval-requested",
+        id: req.id,
+        name: req.toolName,
+        input: req.input,
+        readOnly: req.readOnly,
+        step: req.step
+      }),
+      resolved: (r) => o.emit({ type: "tool.approval-resolved", ...r })
+    },
+    signal ?? o.signal
+  );
+  for (const [name, t] of Object.entries(tools)) {
+    const execute = t.execute;
+    const builtin = o.builtins.has(name);
+    const readOnly = builtin || isReadOnlyTool(t);
+    const wrapped = { ...t };
+    if (o.maxToolOutputChars > 0) {
+      wrapped.toModelOutput = limitModelOutput(t.toModelOutput, o.maxToolOutputChars);
+    }
+    if (typeof execute === "function") {
+      wrapped.execute = (input, options) => {
+        const run = () => {
+          if (!builtin) o.countCall();
+          const agentRun = {
+            emit: o.emit,
+            step: o.step(),
+            signal: o.signal,
+            addUsage: o.addUsage,
+            approve: (toolName, toolInput, ro) => gate(toolName, toolInput, ro)
+          };
+          return execute.call(t, input, { ...options, agentRun });
+        };
+        if (builtin) return run();
+        const permission = decideToolPermission({
+          toolName: name,
+          readOnly,
+          mode: o.approval.mode,
+          rules: o.approval.config.rules,
+          remembered: o.approval.remembered
+        });
+        if (permission === "allow") return run();
+        return gate(
+          name,
+          input,
+          readOnly,
+          options?.abortSignal
+        ).then(run);
+      };
+    }
+    out[name] = wrapped;
+  }
+  return out;
+};
+var createCallCounter = (cap) => {
+  let calls = 0;
+  return {
+    count: () => {
+      if (cap && cap > 0 && calls >= cap) throw new ToolBudgetError(cap);
+      calls += 1;
+    },
+    get calls() {
+      return calls;
+    },
+    get exhausted() {
+      return Boolean(cap && cap > 0 && calls >= cap);
+    }
+  };
+};
+var typeHint = (s, depth) => {
+  if (!s) return "any";
+  if (Array.isArray(s.enum) && s.enum.length > 0 && s.enum.length <= 8) {
+    return s.enum.map((v) => JSON.stringify(v)).join(" | ");
+  }
+  const type = Array.isArray(s.type) ? s.type.find((x) => x !== "null") : s.type;
+  if (type === "array") return `${typeHint(s.items, depth)}[]`;
+  if (type === "object" || s.properties) {
+    if (depth > 1 || !s.properties) return "object";
+    return objectHint(s, depth + 1);
+  }
+  return type ?? "any";
+};
+var objectHint = (s, depth = 0) => {
+  const required = new Set(s.required ?? []);
+  const props = Object.entries(s.properties ?? {});
+  if (props.length === 0) return "{}";
+  return `{ ${props.slice(0, 12).map(([k, v]) => `${k}${required.has(k) ? "" : "?"}: ${typeHint(v, depth)}`).join(", ")}${props.length > 12 ? ", \u2026" : ""} }`;
+};
+var schemaHintOf = async (t) => {
+  const own = promptHintOf(t);
+  if (own) return own;
+  try {
+    const schema = await (0, import_ai5.asSchema)(t.inputSchema).jsonSchema;
+    return schema && typeof schema === "object" ? objectHint(schema) : void 0;
+  } catch {
+    return void 0;
+  }
+};
+
 // src/llm/tool-loop.ts
-var import_ai3 = require("ai");
+var import_ai6 = require("ai");
 
 // src/agent/loop-types.ts
 var BLOCKER = "[BLOCKER]";
-var emptyUsage = () => ({ inputTokens: 0, outputTokens: 0, totalTokens: 0 });
+var emptyUsage = () => ({
+  inputTokens: 0,
+  outputTokens: 0,
+  totalTokens: 0,
+  reasoningTokens: 0,
+  cachedInputTokens: 0,
+  cacheWriteTokens: 0
+});
 var addUsage = (a, b) => ({
   inputTokens: a.inputTokens + b.inputTokens,
   outputTokens: a.outputTokens + b.outputTokens,
-  totalTokens: a.totalTokens + b.totalTokens
+  totalTokens: a.totalTokens + b.totalTokens,
+  reasoningTokens: (a.reasoningTokens ?? 0) + (b.reasoningTokens ?? 0),
+  cachedInputTokens: (a.cachedInputTokens ?? 0) + (b.cachedInputTokens ?? 0),
+  cacheWriteTokens: (a.cacheWriteTokens ?? 0) + (b.cacheWriteTokens ?? 0)
 });
 
 // src/parse.ts
-var stripFences = (text) => (text || "").replace(/```(?:json)?/gi, "").trim();
+var stripThinking = (text) => text.replace(/<think>[\s\S]*?<\/think>/gi, "").replace(/^[\s\S]*?<\/think>/i, "");
+var stripFences = (text) => stripThinking(text || "").replace(/```(?:json)?/gi, "").trim();
 var extractBalanced = (text, open) => {
   const close = open === "{" ? "}" : "]";
   const start = text.indexOf(open);
@@ -701,15 +1451,16 @@ var parsePlannerResponse = (raw) => {
   const obj = asObject(text);
   if (obj) {
     const reply = typeof obj.reply === "string" ? obj.reply.trim() : "";
-    return { reply, plan: normalizeSteps(obj.plan) };
+    return { reply, plan: normalizeSteps(obj.plan), skills: normalizeSteps(obj.skills) };
   }
   if (/"plan"\s*:/.test(text)) {
     return {
       reply: salvageString(text, "reply"),
-      plan: normalizeSteps(salvageStringArray(text, "plan"))
+      plan: normalizeSteps(salvageStringArray(text, "plan")),
+      skills: normalizeSteps(salvageStringArray(text, "skills"))
     };
   }
-  return { reply: looksLikeJson(text) ? "" : text.trim(), plan: [] };
+  return { reply: looksLikeJson(text) ? "" : text.trim(), plan: [], skills: [] };
 };
 var toActions = (value) => {
   if (!Array.isArray(value)) return [];
@@ -752,20 +1503,99 @@ var parsePlainText = (raw) => {
   return looksLikeJson(text) ? "" : text.trim();
 };
 
+// src/llm/context-editing.ts
+var STUB = (name) => `[${name} result cleared to save context \u2014 call the tool again if you still need it]`;
+var estimate = (messages) => {
+  try {
+    return estimateTokens(JSON.stringify(messages));
+  } catch {
+    return 0;
+  }
+};
+var positionsOf = (messages) => messages.flatMap(
+  (m, i) => m.role === "tool" && Array.isArray(m.content) ? m.content.flatMap(
+    (p, j) => p.type === "tool-result" ? [`${i}:${j}`] : []
+  ) : []
+);
+var createToolResultClearer = (opts, onCleared) => {
+  const keep = Math.max(0, opts.keep ?? 3);
+  const cleared = /* @__PURE__ */ new Set();
+  const apply = (messages) => cleared.size === 0 ? messages : messages.map(
+    (m, i) => m.role === "tool" && Array.isArray(m.content) ? {
+      ...m,
+      content: m.content.map(
+        (p, j) => p.type === "tool-result" && cleared.has(`${i}:${j}`) ? { ...p, output: { type: "text", value: STUB(p.toolName) } } : p
+      )
+    } : m
+  );
+  return (messages) => {
+    let edited = apply(messages);
+    const before = estimate(edited);
+    if (before <= opts.triggerTokens) return edited;
+    const positions = positionsOf(messages);
+    let added = 0;
+    for (const pos of positions.slice(0, Math.max(0, positions.length - keep))) {
+      if (!cleared.has(pos)) {
+        cleared.add(pos);
+        added += 1;
+      }
+    }
+    if (added === 0) return edited;
+    edited = apply(messages);
+    onCleared?.({ cleared: added, beforeTokens: before, afterTokens: estimate(edited) });
+    return edited;
+  };
+};
+
 // src/llm/tool-loop.ts
 var runToolLoop = (model, opts) => opts.mode === "prompted" ? runPrompted(model, opts) : runNative(model, opts);
+var activeOf = (opts) => typeof opts.activeTools === "function" ? opts.activeTools() : opts.activeTools;
+var callExtras = (opts) => ({
+  ...opts.system !== void 0 ? { instructions: opts.system } : {},
+  maxOutputTokens: opts.maxOutputTokens,
+  temperature: opts.temperature,
+  ...opts.reasoning ? { reasoning: opts.reasoning } : {},
+  ...opts.providerOptions ? { providerOptions: opts.providerOptions } : {}
+});
 var runNative = async (model, opts) => {
   const toolCalls = [];
   const pending = /* @__PURE__ */ new Map();
-  const result = (0, import_ai3.streamText)({
+  let stoppedByBudget = false;
+  const stopWhen = [(0, import_ai6.stepCountIs)(opts.maxSteps ?? 4)];
+  if (opts.shouldStop) {
+    const shouldStop = opts.shouldStop;
+    stopWhen.push(({ steps }) => {
+      const used = steps.reduce((u, s) => addUsage(u, normalizeUsage(s.usage)), emptyUsage());
+      if (!shouldStop(used)) return false;
+      stoppedByBudget = true;
+      return true;
+    });
+  }
+  const initialActive = activeOf(opts);
+  const dynamic = typeof opts.activeTools === "function";
+  const caching = opts.caching?.enabled ? opts.caching : void 0;
+  const clear = opts.clearToolResults ? createToolResultClearer(opts.clearToolResults, opts.callbacks?.onToolResultsCleared) : void 0;
+  const editMessages = caching || clear;
+  const result = (0, import_ai6.streamText)({
     model,
     tools: opts.tools,
-    ...opts.activeTools ? { activeTools: opts.activeTools } : {},
-    stopWhen: (0, import_ai3.stepCountIs)(opts.maxSteps ?? 4),
-    system: opts.system,
+    ...initialActive ? { activeTools: initialActive } : {},
+    // Before every round: re-read the active set so tools activated mid-call
+    // (find_tools) become callable; clear stale tool results; move the cache
+    // breakpoint to the newest message.
+    ...dynamic || editMessages ? {
+      prepareStep: ({ messages }) => {
+        let next = clear ? clear(messages) : messages;
+        if (caching) next = withRollingBreakpoint(next, caching);
+        return {
+          ...dynamic ? { activeTools: activeOf(opts) } : {},
+          ...editMessages ? { messages: next } : {}
+        };
+      }
+    } : {},
+    stopWhen,
+    ...callExtras(opts),
     ...promptOf(opts),
-    maxOutputTokens: opts.maxOutputTokens,
-    temperature: opts.temperature,
     abortSignal: timeoutSignal(opts.abortSignal, opts.timeoutMs)
   });
   for await (const part of result.fullStream) {
@@ -773,6 +1603,9 @@ var runNative = async (model, opts) => {
       case "text-delta":
         if (part.text) opts.callbacks?.onTextDelta?.(part.text);
         break;
+      case "reasoning-delta":
+        if (part.text) opts.callbacks?.onReasoningDelta?.(part.text);
+        break;
       case "tool-call":
         pending.set(part.toolCallId, { name: part.toolName, input: part.input });
         opts.callbacks?.onToolCall?.(part.toolName, part.input);
@@ -806,7 +1639,7 @@ var runNative = async (model, opts) => {
     }
   }
   const [text, usage] = await Promise.all([result.text, result.usage]);
-  return { text: text.trim(), toolCalls, usage: normalizeUsage(usage) };
+  return { text: text.trim(), toolCalls, usage: normalizeUsage(usage), stoppedByBudget };
 };
 var asJson = (value) => {
   try {
@@ -815,13 +1648,16 @@ var asJson = (value) => {
     return String(value);
   }
 };
-var toolResultsPrompt = (results) => {
+var toolResultsPrompt = (results, newTools) => {
   const lines = results.map(
     (r) => `- ${r.name} ${clip(asJson(r.input), 160)} \u2192 ${r.ok ? "ok" : "FAILED"}: ${clip(asJson(r.output), 400)}`
   );
   return `TOOL RESULTS:
 ${lines.join("\n")}
-
+${newTools ? `
+TOOLS NOW AVAILABLE (call them by these exact names):
+${newTools}
+` : ""}
 Continue THIS step using the results above. Reply with a single JSON object, nothing else:
 { "reply": string, "actions": [ { "tool": string, "args": object } ] }
 - If the step is now complete: "actions": [] and a short outcome in "reply".
@@ -829,22 +1665,28 @@ Continue THIS step using the results above. Reply with a single JSON object, not
 };
 var runPrompted = async (model, opts) => {
   const maxRounds = Math.max(1, opts.maxSteps ?? 4);
-  const active = opts.activeTools;
-  const tools = active ? Object.fromEntries(Object.entries(opts.tools).filter(([name]) => active.includes(name))) : opts.tools;
+  const callable = () => {
+    const active = activeOf(opts);
+    return active ? Object.fromEntries(Object.entries(opts.tools).filter(([name]) => active.includes(name))) : opts.tools;
+  };
   const signal = timeoutSignal(opts.abortSignal, opts.timeoutMs);
   const messages = opts.messages ? [...opts.messages] : [{ role: "user", content: opts.prompt ?? "" }];
   const toolCalls = [];
   const seen = /* @__PURE__ */ new Set();
   let usage = emptyUsage();
   let text = "";
+  let stoppedByBudget = false;
   for (let round = 1; round <= maxRounds; round += 1) {
     if (signal?.aborted) break;
-    const result = await (0, import_ai3.generateText)({
+    if (opts.shouldStop?.(usage)) {
+      stoppedByBudget = true;
+      break;
+    }
+    const before = new Set(Object.keys(callable()));
+    const result = await (0, import_ai6.generateText)({
       model,
-      system: opts.system,
-      messages,
-      maxOutputTokens: opts.maxOutputTokens,
-      temperature: opts.temperature,
+      ...callExtras(opts),
+      messages: opts.caching ? withRollingBreakpoint(messages, opts.caching) : messages,
       abortSignal: signal
     });
     usage = addUsage(usage, normalizeUsage(result.usage));
@@ -859,42 +1701,226 @@ var runPrompted = async (model, opts) => {
     for (const action of parsed.actions) {
       if (signal?.aborted) break;
       opts.callbacks?.onToolCall?.(action.tool, action.args);
-      const rec = await dispatch(action, tools, { abortSignal: signal });
+      const rec = await dispatch(action, callable(), { abortSignal: signal });
       toolCalls.push(rec);
       results.push(rec);
       opts.callbacks?.onToolResult?.(rec.name, rec.output, rec.ok);
     }
     if (round === maxRounds || signal?.aborted) break;
+    const added = Object.keys(callable()).filter((n) => !before.has(n));
     messages.push({ role: "assistant", content: result.text });
-    messages.push({ role: "user", content: toolResultsPrompt(results) });
+    messages.push({
+      role: "user",
+      content: toolResultsPrompt(
+        results,
+        added.length && opts.describeTools ? opts.describeTools(added) : ""
+      )
+    });
   }
   if (text) opts.callbacks?.onTextDelta?.(text);
-  return { text, toolCalls, usage };
+  return { text, toolCalls, usage, stoppedByBudget };
 };
 
-// src/agent/internal.ts
-var systemFor = (ctx, base) => withSystem(base, ctx.raw.systemPrompt);
-
-// src/agent/executor.ts
-var splitBlocker = (raw) => {
-  if (!raw.includes(BLOCKER)) return { summary: raw.trim(), blocked: false };
-  return { summary: raw.split(BLOCKER).join("").trim(), blocked: true };
-};
-var activeToolNames = (ctx, step) => {
-  if (ctx.config.toolSelectionStrategy !== "plan-narrowed") return void 0;
-  const suggested = step.suggestedTools ?? [];
-  const known = suggested.filter((n) => ctx.tools[n]);
-  if (known.length === 0 && suggested.length > 0) return Object.keys(ctx.tools);
-  return known;
+// src/thinking.ts
+var normalize = (setting) => {
+  if (setting === void 0 || setting === false) return void 0;
+  if (setting === true) return { level: "medium" };
+  if (typeof setting === "string") return { level: setting };
+  return setting;
 };
-var summaryOf = (text, toolCallCount) => {
-  if (text.length > 0) return text;
-  return toolCallCount > 0 ? `Executed ${toolCallCount} tool call(s).` : "Step produced no output.";
+var resolveThinking = (setting) => {
+  const cfg = normalize(setting);
+  if (!cfg) return {};
+  const level = cfg.level ?? "medium";
+  if (level === "none") return { reasoning: "none" };
+  const includeThoughts = cfg.includeThoughts !== false;
+  const budget = cfg.budgetTokens;
+  if (typeof budget === "number" && budget > 0) {
+    return {
+      reasoning: level,
+      providerOptions: {
+        anthropic: { thinking: { type: "enabled", budgetTokens: budget } },
+        google: { thinkingConfig: { thinkingBudget: budget, includeThoughts } }
+      }
+    };
+  }
+  if (!includeThoughts) return { reasoning: level };
+  return {
+    reasoning: level,
+    providerOptions: {
+      google: { thinkingConfig: { includeThoughts: true } },
+      openai: { reasoningSummary: "auto" }
+    }
+  };
 };
+var thinkingFor = (stage, top, perStage) => perStage && stage in perStage ? perStage[stage] : top;
+var isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var deepMerge = (a, b) => {
+  const out = { ...a };
+  for (const [k, v] of Object.entries(b)) {
+    out[k] = isPlainObject(out[k]) && isPlainObject(v) ? deepMerge(out[k], v) : v;
+  }
+  return out;
+};
+var mergeProviderOptions = (...maps) => {
+  let out;
+  for (const m of maps) {
+    if (!m || Object.keys(m).length === 0) continue;
+    out = out ? deepMerge(out, m) : { ...m };
+  }
+  return out;
+};
+
+// src/images.ts
+var DATA_URL_RE = /^data:([^;,]+)?;base64,(.*)$/s;
+var HTTP_RE = /^https?:\/\//i;
+var mediaTypeOf = (f) => {
+  if (f.mediaType) return f.mediaType;
+  if (typeof f.data === "string") {
+    const m = DATA_URL_RE.exec(f.data);
+    if (m?.[1]) return m[1];
+  }
+  const url = f.data instanceof URL ? f.data.href : typeof f.data === "string" ? f.data : "";
+  if (HTTP_RE.test(url) || f.name) {
+    const ext = (f.name ?? new URL(url, "http://x").pathname).split(".").pop()?.toLowerCase();
+    if (ext === "pdf") return "application/pdf";
+    if (ext && ["png", "jpg", "jpeg", "gif", "webp"].includes(ext)) {
+      return `image/${ext === "jpg" ? "jpeg" : ext}`;
+    }
+  }
+  return void 0;
+};
+var attachmentKind = (f) => {
+  const mt = mediaTypeOf(f) ?? "";
+  if (mt.startsWith("image/")) return "image";
+  if (mt === "application/pdf") return "pdf";
+  return "file";
+};
+var KIND_LABEL = {
+  image: "images",
+  pdf: "PDF files",
+  file: "file attachments"
+};
+var KIND_HINT = {
+  image: "Remove the image, or switch to a vision-capable model such as Gemini, Claude or GPT-4o/GPT-5.",
+  pdf: "Convert the PDF to text first (e.g. PDF \u2192 Markdown), or switch to a model that reads PDFs such as Gemini, Claude or GPT-4o/GPT-5.",
+  file: "Paste its text instead, or switch to a model that accepts this file type."
+};
+var AttachmentsNotSupportedError = class extends Error {
+  kind;
+  constructor(model, kind, detail) {
+    super(
+      `The model "${model}" can't take ${KIND_LABEL[kind]}${detail ? ` (${detail})` : ""}. ${KIND_HINT[kind]}`
+    );
+    this.name = "AttachmentsNotSupportedError";
+    this.kind = kind;
+  }
+  toJSON() {
+    return this.message;
+  }
+};
+var ImagesNotSupportedError = class extends AttachmentsNotSupportedError {
+  constructor(model, detail) {
+    super(model, "image", detail);
+    this.name = "ImagesNotSupportedError";
+  }
+};
+var unsupportedAttachment = (model, kind, detail) => kind === "image" ? new ImagesNotSupportedError(model, detail) : new AttachmentsNotSupportedError(model, kind, detail);
+var dataOf = (f) => {
+  if (typeof f.data === "string") {
+    const m = DATA_URL_RE.exec(f.data);
+    if (m) return m[2];
+    if (HTTP_RE.test(f.data)) return new URL(f.data);
+  }
+  return f.data;
+};
+var toFilePart = (f) => {
+  const kind = attachmentKind(f);
+  const mediaType = mediaTypeOf(f) ?? (kind === "image" ? "image" : "application/octet-stream");
+  return {
+    type: "file",
+    data: dataOf(f),
+    mediaType,
+    ...f.name ? { filename: f.name } : {}
+  };
+};
+var toImagePart = toFilePart;
+var modelLabel = (model) => {
+  if (typeof model === "string") return model;
+  const m = model;
+  return m?.modelId ? `${m.modelId}${m.provider ? ` (${m.provider})` : ""}` : "this model";
+};
+var REFUSAL_RE = /image|vision|multimodal|multi-modal|media type|mediatype|pdf|document|unsupported (file|content|part|mime)|does not support (file|content)|invalid content type|image_url|inline_?data|file_?data/i;
+var isAttachmentRefusal = (err) => REFUSAL_RE.test(err instanceof Error ? `${err.name} ${err.message}` : String(err));
+var isImageRefusal = isAttachmentRefusal;
+
+// src/agent/internal.ts
+var promptFor = (ctx, prompt) => ctx.images?.length ? {
+  messages: [
+    {
+      role: "user",
+      content: [{ type: "text", text: prompt }, ...ctx.images.map(toFilePart)]
+    }
+  ]
+} : { prompt };
+var imageRefusal = (ctx, err, model) => {
+  if (!ctx.images?.length || err instanceof AttachmentsNotSupportedError || !isAttachmentRefusal(err)) {
+    return void 0;
+  }
+  const kinds = new Set(ctx.images.map(attachmentKind));
+  const kind = kinds.size === 1 ? [...kinds][0] : "file";
+  const detail = err instanceof Error ? err.message.slice(0, 160) : void 0;
+  return unsupportedAttachment(modelLabel(model), kind, detail && `the provider said: ${detail}`);
+};
+var systemFor = (ctx, base) => withSystem(base, ctx.raw.systemPrompt);
+var stageCall = (ctx, stage, baseSystem) => {
+  const system = systemFor(ctx, baseSystem);
+  const thinking = resolveThinking(thinkingFor(stage, ctx.raw.thinking, ctx.raw.stageThinking));
+  const caching = ctx.caching ?? { enabled: false };
+  const providerOptions = mergeProviderOptions(
+    cachingProviderOptions(caching, ctx.config.clientName, stage),
+    thinking.providerOptions
+  );
+  return {
+    system: cachedInstructions(system, caching),
+    ...thinking.reasoning ? { reasoning: thinking.reasoning } : {},
+    ...providerOptions ? { providerOptions } : {}
+  };
+};
+
+// src/agent/executor.ts
+var splitBlocker = (raw) => {
+  if (!raw.includes(BLOCKER)) return { summary: raw.trim(), blocked: false };
+  return { summary: raw.split(BLOCKER).join("").trim(), blocked: true };
+};
+var activeToolNames = (ctx, step) => {
+  const strategy = ctx.strategy ?? ctx.config.toolSelectionStrategy;
+  const builtins = [...ctx.builtinTools ?? []].filter((n) => ctx.tools[n]);
+  const suggested = step.suggestedTools ?? [];
+  const known = suggested.filter((n) => ctx.tools[n]);
+  if (strategy === "search") {
+    const discovered = (ctx.discovered?.() ?? []).slice(-16);
+    return [.../* @__PURE__ */ new Set([...builtins, ...known, ...discovered])];
+  }
+  if (strategy !== "plan-narrowed") return void 0;
+  if (known.length === 0 && suggested.length > 0) return Object.keys(ctx.tools);
+  return [.../* @__PURE__ */ new Set([...known, ...builtins])];
+};
+var summaryOf = (text, toolCallCount) => {
+  if (text.length > 0) return text;
+  return toolCallCount > 0 ? `Executed ${toolCallCount} tool call(s).` : "Step produced no output.";
+};
+var catalogFor = (ctx, names) => renderCatalog(
+  Object.fromEntries(names.filter((n) => ctx.tools[n]).map((n) => [n, ctx.tools[n]])),
+  ctx.toolHint
+);
 var executeStep = async (ctx, goal, step, index, total, done) => {
   const state = await ctx.state();
-  const active = activeToolNames(ctx, step);
-  const toolCatalog = active === void 0 ? ctx.toolCatalog : renderCatalog(Object.fromEntries(active.map((name) => [name, ctx.tools[name]])));
+  ctx.setCurrentStep?.(step);
+  const initial = activeToolNames(ctx, step);
+  const searchMode = (ctx.strategy ?? ctx.config.toolSelectionStrategy) === "search";
+  const toolCatalog = catalogFor(ctx, initial ?? Object.keys(ctx.tools));
+  const active = ctx.activeSkills?.() ?? [];
   const parts = ctx.prompts.executor({
     goal,
     state,
@@ -903,21 +1929,44 @@ var executeStep = async (ctx, goal, step, index, total, done) => {
     total,
     toolCatalog,
     done,
-    mode: ctx.executorMode
+    mode: ctx.executorMode,
+    skills: ctx.skills?.length ? renderSkillIndex(ctx.skills) : void 0,
+    activeSkills: active.length ? renderActiveSkills(active) : void 0,
+    searchMode: searchMode && Boolean(ctx.tools[FIND_TOOLS_NAME])
   });
   const loop = await runToolLoop(ctx.executorModel, {
     mode: ctx.executorMode,
-    system: systemFor(ctx, parts.system),
-    prompt: parts.prompt,
+    ...stageCall(ctx, "executor", parts.system),
+    ...promptFor(ctx, parts.prompt),
     tools: ctx.tools,
-    activeTools: active,
+    // In search mode the active set grows while the step runs.
+    activeTools: searchMode ? () => [.../* @__PURE__ */ new Set([...initial ?? [], ...ctx.discovered?.() ?? []])] : initial,
+    describeTools: (names) => catalogFor(ctx, names),
     maxSteps: ctx.config.maxStepsPerTask,
+    shouldStop: ctx.overBudget,
     maxOutputTokens: ctx.config.budgets.executor,
     temperature: ctx.config.temperature,
     abortSignal: ctx.signal,
     timeoutMs: ctx.config.chatTimeoutMs,
+    caching: ctx.caching,
+    ...ctx.config.compaction.clearToolResultsAfterTokens > 0 ? {
+      clearToolResults: {
+        triggerTokens: ctx.config.compaction.clearToolResultsAfterTokens,
+        keep: ctx.config.compaction.keepToolResults
+      }
+    } : {},
     callbacks: {
+      onToolResultsCleared: (info) => {
+        ctx.log.info(`cleared ${info.cleared} stale tool result(s) from the step's context`);
+        ctx.emit({
+          type: "context.compacted",
+          scope: "tool-results",
+          beforeTokens: info.beforeTokens,
+          afterTokens: info.afterTokens
+        });
+      },
       onTextDelta: (delta) => ctx.emit({ type: "step.text-delta", step, delta }),
+      onReasoningDelta: (delta) => ctx.emit({ type: "step.reasoning-delta", step, delta }),
       onToolCall: (name, input) => {
         ctx.log.info(`tool call: ${name}`, input);
         ctx.emit({ type: "step.tool-call", step, name, input });
@@ -927,6 +1976,8 @@ var executeStep = async (ctx, goal, step, index, total, done) => {
         ctx.emit({ type: "step.tool-result", step, name, output, ok });
       }
     }
+  }).catch((err) => {
+    throw imageRefusal(ctx, err, ctx.executorModel) ?? err;
   });
   ctx.log.debug("executor text:", loop.text);
   const { summary, blocked } = splitBlocker(loop.text);
@@ -937,7 +1988,8 @@ var executeStep = async (ctx, goal, step, index, total, done) => {
       toolCalls: loop.toolCalls,
       blocked
     },
-    usage: loop.usage
+    usage: loop.usage,
+    stoppedByBudget: loop.stoppedByBudget
   };
 };
 var shouldReplan = (result) => {
@@ -978,9 +2030,11 @@ var PlanStepSchema = import_zod.z.object({
   suggestedTools: import_zod.z.array(import_zod.z.string()).optional()
 });
 var PlanSchema = import_zod.z.object({
-  /** One short sentence. For a greeting/question/unclear request, holds the answer and steps is empty. */
+  /** One short sentence. For a greeting/small talk, holds the answer and steps is empty. */
   thought: import_zod.z.string(),
-  steps: import_zod.z.array(PlanStepSchema)
+  steps: import_zod.z.array(PlanStepSchema),
+  /** Names of the configured skills that apply to this goal. */
+  skills: import_zod.z.array(import_zod.z.string()).optional()
 });
 var ReplanSchema = import_zod.z.object({
   decision: import_zod.z.enum(["continue", "revise", "finish"]),
@@ -990,7 +2044,7 @@ var ReplanSchema = import_zod.z.object({
 });
 
 // src/agent/planner.ts
-var toSteps = (raw) => raw.filter((s) => s.description && s.description.trim()).map((s, i) => ({
+var toSteps = (raw, cap) => raw.filter((s) => s.description && s.description.trim()).slice(0, Math.max(1, cap)).map((s, i) => ({
   id: `s${i + 1}`,
   description: s.description.trim(),
   expectedOutcome: s.expectedOutcome,
@@ -1001,46 +2055,72 @@ var createPlan = async (ctx, goal, nudge) => {
   const effectiveGoal = nudge ? `${goal}
 
 ${nudge}` : goal;
+  const skillIndex = ctx.skills?.length ? renderSkillIndex(ctx.skills) : void 0;
+  const cap = ctx.config.maxPlanSteps;
   const commonFor = (mode) => {
     const parts = ctx.prompts.planner({
       goal: effectiveGoal,
       state,
       toolCatalog: ctx.toolCatalog,
       mode,
-      history: ctx.history
+      history: ctx.history,
+      skills: skillIndex,
+      searchMode: ctx.strategy === "search"
     });
     return {
-      system: systemFor(ctx, parts.system),
-      prompt: parts.prompt,
+      ...stageCall(ctx, "planner", parts.system),
+      ...promptFor(ctx, parts.prompt),
       maxOutputTokens: ctx.config.budgets.planner,
       temperature: ctx.config.temperature,
       abortSignal: ctx.signal,
       timeoutMs: ctx.config.chatTimeoutMs
     };
   };
+  const validSkills = (names) => {
+    const known = new Set((ctx.skills ?? []).map((s) => s.name));
+    const picked = [...new Set(names ?? [])];
+    const kept = picked.filter((n) => known.has(n));
+    if (kept.length < picked.length) {
+      ctx.log.warn(
+        "planner picked unknown skills, dropped:",
+        picked.filter((n) => !known.has(n))
+      );
+    }
+    return kept;
+  };
   if (ctx.plannerMode === "native") {
     try {
       const result2 = await generateStructured(ctx.plannerModel, PlanSchema, commonFor("native"));
       ctx.log.debug("planner (native):", result2.object);
       return {
-        plan: { thought: result2.object.thought, steps: toSteps(result2.object.steps) },
-        usage: normalizeUsage(result2.usage)
+        plan: { thought: result2.object.thought, steps: toSteps(result2.object.steps, cap) },
+        usage: normalizeUsage(result2.usage),
+        skills: validSkills(result2.object.skills)
       };
     } catch (err) {
+      if (ctx.signal?.aborted) throw err;
+      const refused = imageRefusal(ctx, err, ctx.plannerModel);
+      if (refused) throw refused;
       ctx.log.warn("planner: native structured output failed, salvaging:", asMessage(err));
       ctx.emit({ type: "retry", phase: "plan", attempt: 1, error: asMessage(err) });
     }
   }
-  const result = await generate(ctx.plannerModel, commonFor("prompted"));
+  const result = await generate(ctx.plannerModel, commonFor("prompted")).catch((err) => {
+    throw imageRefusal(ctx, err, ctx.plannerModel) ?? err;
+  });
   const parsed = parsePlannerResponse(result.text);
   ctx.log.debug("planner (prompted) raw:", result.text);
   ctx.log.debug("planner (prompted) parsed:", parsed);
   return {
     plan: {
       thought: parsed.reply,
-      steps: toSteps(parsed.plan.map((description) => ({ description })))
+      steps: toSteps(
+        parsed.plan.map((description) => ({ description })),
+        cap
+      )
     },
-    usage: normalizeUsage(result.usage)
+    usage: normalizeUsage(result.usage),
+    skills: validSkills(parsed.skills)
   };
 };
 var asMessage = (err) => err instanceof Error ? err.message : String(err);
@@ -1048,10 +2128,18 @@ var asMessage = (err) => err instanceof Error ? err.message : String(err);
 // src/agent/replanner.ts
 var decideReplan = async (ctx, goal, done, remaining) => {
   const state = await ctx.state();
+  const active = ctx.activeSkills?.() ?? [];
   const commonFor = (mode) => {
-    const parts = ctx.prompts.replanner({ goal, state, done, remaining, mode });
+    const parts = ctx.prompts.replanner({
+      goal,
+      state,
+      done,
+      remaining,
+      mode,
+      activeSkills: active.length ? renderActiveSkills(active) : void 0
+    });
     return {
-      system: systemFor(ctx, parts.system),
+      ...stageCall(ctx, "replanner", parts.system),
       prompt: parts.prompt,
       maxOutputTokens: ctx.config.budgets.replanner,
       temperature: ctx.config.temperature,
@@ -1086,12 +2174,19 @@ var decideReplan = async (ctx, goal, done, remaining) => {
 };
 
 // src/agent/synthesizer.ts
-var synthesizeAnswer = async (ctx, goal, done) => {
+var synthesizeAnswer = async (ctx, goal, done, findings = []) => {
   const state = await ctx.state();
-  const parts = ctx.prompts.synthesizer({ goal, state, done });
+  const active = ctx.activeSkills?.() ?? [];
+  const parts = ctx.prompts.synthesizer({
+    goal,
+    state,
+    done,
+    findings,
+    activeSkills: active.length ? renderActiveSkills(active) : void 0
+  });
   const result = stream(ctx.synthesizerModel, {
-    system: systemFor(ctx, parts.system),
-    prompt: parts.prompt,
+    ...stageCall(ctx, "synthesizer", parts.system),
+    ...promptFor(ctx, parts.prompt),
     maxOutputTokens: ctx.config.budgets.synthesizer,
     temperature: ctx.config.temperature,
     abortSignal: ctx.signal,
@@ -1099,13 +2194,27 @@ var synthesizeAnswer = async (ctx, goal, done) => {
   });
   let text = "";
   let verdict = "unknown";
-  for await (const delta of result.textStream) {
+  for await (const part of result.fullStream) {
+    if (part.type === "reasoning-delta") {
+      if (part.text) ctx.emit({ type: "final.reasoning-delta", delta: part.text });
+      continue;
+    }
+    if (part.type === "error") {
+      const err = part.error instanceof Error ? part.error : new Error(String(part.error));
+      throw imageRefusal(ctx, err, ctx.synthesizerModel) ?? err;
+    }
+    if (part.type !== "text-delta") continue;
+    const delta = part.text;
     text += delta;
     if (verdict === "unknown") {
       const lead = text.trimStart();
       if (!lead) continue;
+      if (lead.startsWith("<think>") && !text.includes("</think>")) continue;
       verdict = looksLikeJson(lead) ? "suppress" : "emit";
-      if (verdict === "emit") ctx.emit({ type: "final.text-delta", delta: text });
+      if (verdict === "emit") {
+        const visible = text.includes("</think>") ? text.slice(text.lastIndexOf("</think>") + "</think>".length).trimStart() : text;
+        if (visible) ctx.emit({ type: "final.text-delta", delta: visible });
+      }
     } else if (verdict === "emit") {
       ctx.emit({ type: "final.text-delta", delta });
     }
@@ -1138,6 +2247,43 @@ var createLogger = (level = "warn", sink = console) => {
   };
 };
 
+// src/providers/capabilities.ts
+var CLOUD = /* @__PURE__ */ new Set([
+  "openai",
+  "anthropic",
+  "google",
+  "openai-compatible",
+  "xai",
+  "deepseek",
+  "gateway"
+]);
+var supportsNativeTools = (p) => CLOUD.has(p);
+var supportsStructuredOutput = (p) => CLOUD.has(p);
+var directBrowserOk = (p) => p === "google" || p === "gateway" || p === "openai-compatible" || p === "anthropic";
+var LOCAL_RE2 = /web-?llm|mlc|browser-ai|transformers|built-?in/i;
+var TEXT_ONLY_MODEL_RE = /gpt-3\.5|o1-mini|o3-mini|deepseek|text-(davinci|embedding)|embedding|babbage|davinci|codestral/i;
+var VISION_PROVIDER_RE = /^(google|anthropic|openai|azure|xai|vertex|bedrock|gemini)/i;
+var PDF_PROVIDER_RE = /^(google|anthropic|openai|azure|vertex|bedrock|gemini)/i;
+var supportsImages = (model) => {
+  if (typeof model === "string") {
+    const [provider2 = "", id2 = model] = model.includes("/") ? model.split("/", 2) : ["", model];
+    if (TEXT_ONLY_MODEL_RE.test(id2) || /deepseek/i.test(provider2)) return false;
+    return VISION_PROVIDER_RE.test(provider2) ? true : void 0;
+  }
+  if (!model || typeof model !== "object") return void 0;
+  const provider = String(model.provider ?? "");
+  const id = String(model.modelId ?? "");
+  if (LOCAL_RE2.test(provider)) return false;
+  if (/deepseek/i.test(provider) || TEXT_ONLY_MODEL_RE.test(id)) return false;
+  return VISION_PROVIDER_RE.test(provider) ? true : void 0;
+};
+var supportsPdf = (model) => {
+  const vision = supportsImages(model);
+  if (vision === false) return false;
+  const provider = typeof model === "string" ? model.split("/")[0] ?? "" : String(model?.provider ?? "");
+  return PDF_PROVIDER_RE.test(provider) ? true : void 0;
+};
+
 // src/agent/runner.ts
 var errMessage = (err) => err instanceof Error ? err.message : String(err);
 var filterTools = (all, available, excluded) => {
@@ -1146,6 +2292,16 @@ var filterTools = (all, available, excluded) => {
   if (excluded && excluded.length > 0) entries = entries.filter(([n]) => !excluded.includes(n));
   return Object.fromEntries(entries);
 };
+var asJson2 = (v) => {
+  if (typeof v === "string") return v;
+  try {
+    return JSON.stringify(v) ?? String(v);
+  } catch {
+    return String(v);
+  }
+};
+var FINDING_CHARS = 600;
+var FINDINGS_BUDGET = 6e3;
 var createAgent = async (config) => {
   const cfg = resolveConfig(config);
   const buildStage = (override, stageName) => buildModelFromStage(
@@ -1161,16 +2317,52 @@ var createAgent = async (config) => {
   ]);
   const plannerMode = selectToolMode(plannerModel, cfg.toolMode);
   const executorMode = selectToolMode(executorModel, cfg.toolMode);
-  const tools = filterTools(
+  const baseTools = filterTools(
     config.tools ?? {},
     config.availableTools,
     config.excludedTools
   );
-  const toolCatalog = renderCatalog(tools);
+  const skills = (config.skills ?? []).map(defineSkill);
+  const skillNames = /* @__PURE__ */ new Set();
+  for (const s of skills) {
+    if (skillNames.has(s.name)) throw new Error(`duplicate skill name "${s.name}"`);
+    skillNames.add(s.name);
+  }
+  const catalog = toolCatalogOf(baseTools);
+  const strategy = cfg.toolSelectionStrategy === "auto" ? catalog.length > cfg.toolSearchThreshold ? "search" : "all" : cfg.toolSelectionStrategy;
+  const reserved = [
+    ...skills.length ? SKILL_TOOL_NAMES : [],
+    ...strategy === "search" ? [FIND_TOOLS_NAME] : []
+  ];
+  for (const name of reserved) {
+    if (Object.hasOwn(baseTools, name)) {
+      throw new Error(
+        `tool name "${name}" is reserved by the agent's built-in tools; rename your tool`
+      );
+    }
+  }
+  const builtinTools = new Set(reserved);
+  const hints = /* @__PURE__ */ new Map();
+  await Promise.all(
+    Object.entries(baseTools).map(async ([name, t]) => {
+      const hint = await schemaHintOf(t);
+      if (hint) hints.set(name, hint);
+    })
+  );
+  const toolHint = (name) => hints.get(name);
+  const plannerCatalog = strategy === "search" ? renderSearchCatalog(catalog) : renderCatalog(baseTools, toolHint);
   const prompts = { ...defaultPrompts, ...config.prompts };
+  const caching = resolveCaching(config.promptCaching);
+  const textOnly = executorMode === "prompted";
+  const accepts = {
+    image: config.inputs?.images ?? config.vision ?? (textOnly ? false : supportsImages(executorModel)),
+    pdf: config.inputs?.pdf ?? (textOnly ? false : supportsPdf(executorModel)),
+    file: config.inputs?.files ?? (textOnly ? false : void 0)
+  };
+  const approval = createApprovalState(config.toolApproval);
   const log = createLogger(cfg.logLevel, config.logger);
   log.info(
-    `agent ready \u2014 tools: [${Object.keys(tools).join(", ") || "none"}], planner mode: ${plannerMode}, executor mode: ${executorMode}`
+    `agent ready \u2014 ${catalog.length} tool(s) (${strategy}), skills: [${[...skillNames].join(", ") || "none"}], planner mode: ${plannerMode}, executor mode: ${executorMode}, approval: ${approval.mode}`
   );
   const run = async (goal, opts = {}) => {
     const emit = (event) => {
@@ -1190,7 +2382,8 @@ var createAgent = async (config) => {
       steps: 0,
       applied: 0,
       stopped: false,
-      usage
+      usage,
+      skills: []
     };
     if (!text) return result;
     const state = async () => config.describeState ? config.describeState() : void 0;
@@ -1207,7 +2400,72 @@ var createAgent = async (config) => {
       } catch {
       }
     };
+    const activeSkillNames = /* @__PURE__ */ new Set();
+    const activateSkill = (name, by) => {
+      if (activeSkillNames.has(name) || !skillNames.has(name)) return;
+      activeSkillNames.add(name);
+      result.skills = [...activeSkillNames];
+      emit({ type: "skill.activated", name, by });
+    };
+    const discovered = [];
+    let currentStep;
+    const counter = createCallCounter(cfg.maxToolCalls);
+    const builtins = {};
+    if (skills.length) {
+      Object.assign(
+        builtins,
+        createSkillTools(skills, (s) => activateSkill(s.name, "tool"))
+      );
+    }
+    if (strategy === "search") {
+      builtins[FIND_TOOLS_NAME] = createFindToolsTool(
+        () => catalog,
+        (query, names) => {
+          for (const n of names) {
+            const i = discovered.indexOf(n);
+            if (i >= 0) discovered.splice(i, 1);
+            discovered.push(n);
+          }
+          emit({ type: "tools.discovered", step: currentStep, query, names });
+        },
+        toolHint
+      );
+    }
+    const tools = wrapToolsForRun(
+      { ...baseTools, ...builtins },
+      {
+        approval,
+        builtins: builtinTools,
+        emit,
+        step: () => currentStep,
+        signal: opts.signal,
+        addUsage: (u) => bumpUsage(u, "subagent"),
+        countCall: counter.count,
+        maxToolOutputChars: cfg.compaction.maxToolOutputChars
+      }
+    );
+    let budgetExceeded;
+    const breach = (extra) => {
+      const b = checkLimits(extra ? addUsage(usage, extra) : usage, cfg.limits);
+      if (b) return b;
+      if (counter.exhausted)
+        return { kind: "tool-calls", tokens: counter.calls, cap: cfg.maxToolCalls };
+      return void 0;
+    };
     emit({ type: "run.start", goal: text });
+    const images = [...opts.images ?? [], ...opts.files ?? []];
+    const refused = images.map(attachmentKind).find((kind) => accepts[kind] === false);
+    if (refused) {
+      const err = unsupportedAttachment(
+        modelLabel(executorModel),
+        refused,
+        textOnly ? "it runs in the text-only prompted tool mode" : void 0
+      );
+      log.warn(err.message);
+      emit({ type: "error", phase: "run", error: err.message });
+      result.final = err.message;
+      return result;
+    }
     let history = [];
     if (config.memory) {
       try {
@@ -1215,6 +2473,30 @@ var createAgent = async (config) => {
       } catch {
       }
     }
+    if (config.memory && config.compaction && cfg.compaction.auto && history.length > 0) {
+      const before = messageTokens(history);
+      if (before > cfg.compaction.thresholdTokens) {
+        const compacted = await compressHistory(history, synthesizerModel, {
+          thresholdTokens: cfg.compaction.thresholdTokens,
+          keepRecent: cfg.compaction.keepRecentTurns,
+          summaryMaxTokens: cfg.budgets.compaction,
+          timeoutMs: cfg.chatTimeoutMs,
+          abortSignal: opts.signal,
+          onUsage: (u) => bumpUsage(u, "compact")
+        });
+        if (compacted !== history) {
+          history = compacted;
+          await config.memory.replace(sessionId, compacted).catch(() => {
+          });
+          emit({
+            type: "context.compacted",
+            scope: "history",
+            beforeTokens: before,
+            afterTokens: messageTokens(compacted)
+          });
+        }
+      }
+    }
     const ctx = {
       config: cfg,
       raw: config,
@@ -1224,24 +2506,42 @@ var createAgent = async (config) => {
       plannerMode,
       executorMode,
       tools,
-      toolCatalog,
+      toolCatalog: plannerCatalog,
       prompts,
       emit,
       log,
       signal: opts.signal,
       state,
-      history
+      history,
+      strategy,
+      caching,
+      skills,
+      activeSkills: () => skills.filter((s) => activeSkillNames.has(s.name)),
+      discovered: () => discovered,
+      builtinTools,
+      toolHint,
+      usageSoFar: () => usage,
+      overBudget: (extra) => breach(extra) !== void 0,
+      setCurrentStep: (step) => {
+        currentStep = step;
+      },
+      images: images.length ? images : void 0
+    };
+    await remember({
+      role: "user",
+      content: images.length ? `${text}
+[attached: ${images.map((f, i) => f.name ?? `${attachmentKind(f)} ${i + 1}`).join(", ")}]` : text
+    });
+    log.info("run:", text, images.length ? `(+${images.length} image(s))` : "");
+    const stop = () => {
+      emit({ type: "stopped" });
+      result.stopped = true;
+      return result;
     };
-    await remember({ role: "user", content: text });
-    log.info("run:", text);
     try {
       let planned = await createPlan(ctx, text);
       bumpUsage(planned.usage, "plan");
-      if (isAborted()) {
-        emit({ type: "stopped" });
-        result.stopped = true;
-        return result;
-      }
+      if (isAborted()) return stop();
       if (planned.plan.steps.length === 0 && text.split(/\s+/).length > 2) {
         log.warn(
           "planner returned no steps for a multi-word goal \u2014 retrying with a nudge. thought:",
@@ -1250,17 +2550,13 @@ var createAgent = async (config) => {
         const retried = await createPlan(
           ctx,
           text,
-          "NOTE: If the message above asks to build, add, change, clear or delete ANYTHING, you MUST output 1-6 concrete steps. Output an empty plan ONLY for a pure greeting or question."
+          "NOTE: If the message above asks to build, add, change, clear, delete, find, check or look up ANYTHING the tools can do, you MUST output 1-6 concrete steps. Output an empty plan ONLY for a pure greeting or small talk."
         );
         bumpUsage(retried.usage, "plan");
         if (retried.plan.steps.length > 0) planned = retried;
       }
       result.plan = planned.plan;
-      if (isAborted()) {
-        emit({ type: "stopped" });
-        result.stopped = true;
-        return result;
-      }
+      if (isAborted()) return stop();
       if (planned.plan.steps.length === 0) {
         log.info("no plan \u2014 answering directly (no tools will run)");
         const answer = planned.plan.thought.trim() || "Tell me what you'd like to do.";
@@ -1275,19 +2571,25 @@ var createAgent = async (config) => {
       );
       emit({ type: "plan.created", plan: planned.plan });
       planned.plan.steps.forEach((step, index) => emit({ type: "plan.step-added", step, index }));
-      const done = [];
+      for (const name of planned.skills) activateSkill(name, "plan");
+      let done = [];
+      const findings = [];
       let remaining = [...planned.plan.steps];
       let iter = 0;
       let revisions = 0;
       while (remaining.length > 0 && iter < cfg.maxIterations) {
-        if (isAborted()) {
-          emit({ type: "stopped" });
-          result.stopped = true;
-          return result;
+        if (isAborted()) return stop();
+        const hit = breach();
+        if (hit) {
+          budgetExceeded = hit;
+          result.budgetExceeded = hit;
+          log.warn(`${hit.kind} limit reached (${hit.tokens}/${hit.cap}) \u2014 writing the answer now`);
+          emit({ type: "budget.exceeded", ...hit });
+          break;
         }
         iter += 1;
         const step = remaining.shift();
-        const stepNo = done.length + 1;
+        const stepNo = result.trace.length + 1;
         const total = stepNo + remaining.length;
         emit({ type: "step.start", step, index: stepNo, total });
         let stepResult;
@@ -1296,13 +2598,12 @@ var createAgent = async (config) => {
           bumpUsage(out.usage, "execute");
           stepResult = out.result;
         } catch (err) {
-          if (isAborted()) {
-            emit({ type: "stopped" });
-            result.stopped = true;
-            return result;
-          }
+          if (isAborted()) return stop();
+          if (err instanceof AttachmentsNotSupportedError) throw err;
           emit({ type: "error", phase: "execute", error: errMessage(err) });
           stepResult = { step, summary: errMessage(err), toolCalls: [], blocked: true };
+        } finally {
+          currentStep = void 0;
         }
         result.trace.push(stepResult);
         const applied = stepResult.toolCalls.filter((c) => c.ok).length;
@@ -1318,10 +2619,38 @@ var createAgent = async (config) => {
         stepResult.toolCalls.filter((c) => !c.ok).forEach((c) => log.warn(`tool ${c.name} failed:`, c.output));
         log.debug(`step ${stepNo} detail:`, stepResult);
         emit({ type: "step.complete", step, result: stepResult });
+        const counts = stepResult.toolCalls.length ? ` [${applied} tool call(s) ok${failed ? `, ${failed} failed` : ""}]` : "";
         done.push(
-          `${step.description} \u2014 ${applied} applied${failed ? `, ${failed} failed` : ""}${stepResult.blocked ? ", blocked" : ""}`
+          `${step.description} \u2014 ${clip(stepResult.summary, FINDING_CHARS)}${counts}${stepResult.blocked ? " [blocked]" : ""}`
         );
-        const wantReplan = cfg.replan && iter < cfg.maxIterations && revisions < cfg.maxRevisions && !isAborted() && await replanWanted(cfg.replanAfter, stepResult, {
+        for (const c of stepResult.toolCalls) {
+          if (!c.ok || builtinTools.has(c.name)) continue;
+          findings.push(`- ${c.name}: ${clip(asJson2(c.output), FINDING_CHARS)}`);
+        }
+        while (findings.join("\n").length > FINDINGS_BUDGET && findings.length > 1) findings.shift();
+        if (cfg.compaction.auto) {
+          const before = estimateTokens(done.join("\n"));
+          if (before > cfg.compaction.thresholdTokens) {
+            const compacted = await compactSteps(done, synthesizerModel, {
+              thresholdTokens: cfg.compaction.thresholdTokens,
+              keepRecent: cfg.compaction.keepRecentSteps,
+              summaryMaxTokens: cfg.budgets.compaction,
+              timeoutMs: cfg.chatTimeoutMs,
+              abortSignal: opts.signal,
+              onUsage: (u) => bumpUsage(u, "compact")
+            });
+            if (compacted !== done) {
+              done = compacted;
+              emit({
+                type: "context.compacted",
+                scope: "trace",
+                beforeTokens: before,
+                afterTokens: estimateTokens(done.join("\n"))
+              });
+            }
+          }
+        }
+        const wantReplan = cfg.replan && iter < cfg.maxIterations && revisions < cfg.maxRevisions && !isAborted() && !breach() && await replanWanted(cfg.replanAfter, stepResult, {
           signal: ctx.signal,
           timeoutMs: cfg.chatTimeoutMs,
           onError: (err) => log.warn("replanAfter predicate threw \u2014 using the failure rule", err)
@@ -1338,7 +2667,7 @@ var createAgent = async (config) => {
           if (decision.decision === "finish") break;
           if (decision.decision === "revise" && decision.plan.length > 0) {
             revisions += 1;
-            remaining = decision.plan.slice(0, cfg.maxIterations - iter).map((description, i) => ({ id: `r${iter}-${i + 1}`, description }));
+            remaining = decision.plan.slice(0, Math.min(cfg.maxPlanSteps, cfg.maxIterations - iter)).map((description, i) => ({ id: `r${iter}-${i + 1}`, description }));
             emit({
               type: "plan.revised",
               plan: { thought: planned.plan.thought, steps: remaining },
@@ -1347,81 +2676,371 @@ var createAgent = async (config) => {
           }
         }
       }
-      if (isAborted()) {
-        emit({ type: "stopped" });
-        result.stopped = true;
-        return result;
+      if (!budgetExceeded && remaining.length > 0) {
+        const hit = breach();
+        if (hit) {
+          budgetExceeded = hit;
+          result.budgetExceeded = hit;
+          emit({ type: "budget.exceeded", ...hit });
+        }
       }
+      if (isAborted()) return stop();
       let summary = "Done \u2014 the changes have been applied.";
       if (cfg.synthesize) {
         try {
-          const synth = await synthesizeAnswer(ctx, text, done);
+          const synth = await synthesizeAnswer(ctx, text, done, findings);
           bumpUsage(synth.usage, "synthesize");
           if (synth.text) summary = synth.text;
-        } catch {
+        } catch (err) {
+          if (isAborted()) return stop();
+          if (err instanceof AttachmentsNotSupportedError) throw err;
         }
       }
       log.info(`done \u2014 ${result.applied} tool call(s) applied over ${result.steps} step(s)`);
       emit({ type: "final", text: summary });
       await remember({ role: "assistant", content: summary });
       result.final = summary;
-      if (config.memory && cfg.compressAfterChars > 0) {
+      if (config.memory && (config.compaction ? cfg.compaction.auto : cfg.compressAfterChars > 0)) {
         try {
           const transcript = await config.memory.load(sessionId);
+          const before = messageTokens(transcript);
           const compacted = await compressHistory(transcript, synthesizerModel, {
-            maxChars: cfg.compressAfterChars,
+            ...config.compaction ? {
+              thresholdTokens: cfg.compaction.thresholdTokens,
+              keepRecent: cfg.compaction.keepRecentTurns,
+              summaryMaxTokens: cfg.budgets.compaction
+            } : { maxChars: cfg.compressAfterChars },
             timeoutMs: cfg.chatTimeoutMs,
-            abortSignal: opts.signal
+            abortSignal: opts.signal,
+            onUsage: (u) => bumpUsage(u, "compact")
           });
-          if (compacted !== transcript) await config.memory.replace(sessionId, compacted);
+          if (compacted !== transcript) {
+            await config.memory.replace(sessionId, compacted);
+            emit({
+              type: "context.compacted",
+              scope: "history",
+              beforeTokens: before,
+              afterTokens: messageTokens(compacted)
+            });
+          }
         } catch {
         }
       }
       return result;
     } catch (err) {
+      if (isAborted()) return stop();
       emit({ type: "error", phase: "run", error: errMessage(err) });
       result.final = errMessage(err);
       return result;
     }
   };
+  const compact = async (o = {}) => {
+    const empty = {
+      compacted: false,
+      beforeTokens: 0,
+      afterTokens: 0,
+      usage: emptyUsage()
+    };
+    if (!config.memory) return empty;
+    const sessionId = o.sessionId ?? cfg.sessionId;
+    const transcript = await config.memory.load(sessionId);
+    const beforeTokens = messageTokens(transcript);
+    let usage = emptyUsage();
+    const compacted = await compressHistory(transcript, synthesizerModel, {
+      thresholdTokens: cfg.compaction.thresholdTokens,
+      keepRecent: cfg.compaction.keepRecentTurns,
+      summaryMaxTokens: cfg.budgets.compaction,
+      force: o.force ?? true,
+      timeoutMs: cfg.chatTimeoutMs,
+      abortSignal: o.signal,
+      onUsage: (u) => {
+        usage = addUsage(usage, u);
+      }
+    });
+    if (compacted === transcript)
+      return { ...empty, beforeTokens, afterTokens: beforeTokens, usage };
+    await config.memory.replace(sessionId, compacted);
+    return { compacted: true, beforeTokens, afterTokens: messageTokens(compacted), usage };
+  };
   return {
     run,
+    compact,
+    setToolApprovalMode: (mode) => {
+      if (!TOOL_APPROVAL_MODES.includes(mode)) {
+        throw new Error(`unknown tool approval mode "${mode}" (${TOOL_APPROVAL_MODES.join(" | ")})`);
+      }
+      approval.mode = mode;
+      log.info(`tool approval mode \u2192 ${mode}`);
+    },
+    get toolApprovalMode() {
+      return approval.mode;
+    },
+    listTools: () => catalog.map((e) => ({ ...e })),
+    toolStrategy: strategy,
+    skills: skills.map((s) => ({ name: s.name, description: s.description })),
+    capabilities: { images: accepts.image, pdf: accepts.pdf, files: accepts.file },
     models: { planner: plannerModel, executor: executorModel, synthesizer: synthesizerModel }
   };
 };
 
-// src/index.ts
-init_webllm();
+// src/subagent/tool.ts
+var import_ai7 = require("ai");
 
-// src/providers/capabilities.ts
-var CLOUD = /* @__PURE__ */ new Set([
-  "openai",
-  "anthropic",
-  "google",
-  "openai-compatible",
-  "xai",
-  "deepseek",
-  "gateway"
-]);
-var supportsNativeTools = (p) => CLOUD.has(p);
-var supportsStructuredOutput = (p) => CLOUD.has(p);
-var directBrowserOk = (p) => p === "google" || p === "gateway" || p === "openai-compatible" || p === "anthropic";
+// src/subagent/protocol.ts
+var toCloneable = (value) => {
+  try {
+    return JSON.parse(
+      JSON.stringify(value, (_k, v) => v instanceof Error ? v.message : v) ?? "null"
+    );
+  } catch {
+    return String(value);
+  }
+};
+var safePost = (target, message) => {
+  try {
+    target.postMessage(message);
+  } catch {
+    target.postMessage(toCloneable(message));
+  }
+};
+
+// src/subagent/tool.ts
+var abortError = () => {
+  const e = new Error("The subagent was aborted");
+  e.name = "AbortError";
+  return e;
+};
+var createSemaphore = (size) => {
+  let active = 0;
+  const queue = [];
+  return async (signal) => {
+    if (active >= size) {
+      await new Promise((resolve, reject) => {
+        const go = () => {
+          signal?.removeEventListener("abort", onAbort);
+          resolve();
+        };
+        const onAbort = () => {
+          const i = queue.indexOf(go);
+          if (i >= 0) queue.splice(i, 1);
+          reject(abortError());
+        };
+        queue.push(go);
+        signal?.addEventListener("abort", onAbort, { once: true });
+      });
+    }
+    active += 1;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      active -= 1;
+      queue.shift()?.();
+    };
+  };
+};
+var seq2 = 0;
+var createSubagentTool = (opts) => {
+  if (!opts.config === !opts.worker) {
+    throw new Error(
+      `subagent "${opts.name}": pass exactly one of \`config\` (in-process) or \`worker\``
+    );
+  }
+  if (opts.worker && !opts.workerConfig) {
+    throw new Error(`subagent "${opts.name}": a worker subagent needs \`workerConfig\``);
+  }
+  const acquire = createSemaphore(Math.max(1, opts.maxConcurrent ?? 4));
+  const outputMax = opts.outputMaxChars ?? 8e3;
+  const gatedHostTools = (approve) => Object.fromEntries(
+    Object.entries(opts.tools ?? {}).map(([name, t2]) => {
+      const execute = t2.execute;
+      if (typeof execute !== "function" || !approve) return [name, t2];
+      return [
+        name,
+        {
+          ...t2,
+          execute: async (input, o) => {
+            await approve(name, input, isReadOnlyTool(t2));
+            return execute.call(t2, input, o);
+          }
+        }
+      ];
+    })
+  );
+  const runInProcess = async (task, signal, forward, hostTools) => {
+    const config = opts.config;
+    const agent = await createAgent({ ...config, tools: { ...config.tools, ...hostTools } });
+    let runError;
+    const result = await agent.run(task, {
+      signal,
+      onEvent: (e) => {
+        if (e.type === "error" && e.phase === "run") runError = e.error;
+        forward(e);
+      }
+    });
+    if (result.stopped) throw abortError();
+    if (runError) throw new Error(runError);
+    return { text: result.final, usage: result.usage };
+  };
+  const proxiedSpecs = async () => Promise.all(
+    Object.entries(opts.tools ?? {}).map(async ([name, t2]) => ({
+      name,
+      description: typeof t2.description === "string" ? t2.description : "",
+      inputSchema: toCloneable(await (0, import_ai7.asSchema)(t2.inputSchema).jsonSchema),
+      readOnly: isReadOnlyTool(t2)
+    }))
+  );
+  const workerConfigFor = async () => {
+    const cfg = opts.workerConfig;
+    let model = { ...cfg.model };
+    if (model.credentialRef && !model.apiKey && opts.credentials) {
+      const apiKey = await opts.credentials.getApiKey(model.credentialRef);
+      if (!apiKey)
+        throw new Error(`no API key stored under "${model.credentialRef}" for the subagent`);
+      model = { ...model, apiKey };
+    }
+    return toCloneable({ ...cfg, model });
+  };
+  const runInWorker = async (task, signal, forward, hostTools) => {
+    if (signal?.aborted) throw abortError();
+    const [config, proxied] = await Promise.all([workerConfigFor(), proxiedSpecs()]);
+    const worker = opts.worker();
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const finish = (fn) => {
+        if (settled) return;
+        settled = true;
+        signal?.removeEventListener("abort", onAbort);
+        worker.removeEventListener?.("message", onMessage);
+        worker.removeEventListener?.("error", onError);
+        worker.terminate?.();
+        fn();
+      };
+      const onAbort = () => {
+        safePost(worker, { type: "abort" });
+        finish(() => reject(abortError()));
+      };
+      const onError = (ev) => finish(() => reject(new Error(`subagent worker failed: ${ev?.message ?? "unknown error"}`)));
+      const callHostTool = async (callId, name, input) => {
+        const t2 = hostTools[name];
+        try {
+          if (!t2 || typeof t2.execute !== "function") throw new Error(`unknown host tool "${name}"`);
+          const output = await t2.execute(input, {
+            toolCallId: callId,
+            messages: [],
+            abortSignal: signal
+          });
+          if (!settled) safePost(worker, { type: "tool-result", callId, ok: true, output });
+        } catch (err) {
+          const output = err instanceof Error ? err.message : String(err);
+          if (!settled) safePost(worker, { type: "tool-result", callId, ok: false, output });
+        }
+      };
+      const onMessage = (ev) => {
+        const msg = ev.data;
+        switch (msg?.type) {
+          case "event":
+            forward(msg.event);
+            break;
+          case "tool-call":
+            void callHostTool(msg.callId, msg.name, msg.input);
+            break;
+          case "done":
+            finish(() => resolve({ text: msg.text, usage: msg.usage }));
+            break;
+          case "error":
+            finish(() => reject(new Error(msg.error)));
+            break;
+        }
+      };
+      worker.addEventListener("message", onMessage);
+      worker.addEventListener("error", onError);
+      signal?.addEventListener("abort", onAbort, { once: true });
+      safePost(worker, { type: "run", task, config, proxied });
+    });
+  };
+  const t = (0, import_ai7.tool)({
+    description: opts.description,
+    inputSchema: (0, import_ai7.jsonSchema)({
+      type: "object",
+      properties: {
+        task: {
+          type: "string",
+          description: "A complete, self-contained task: the subagent sees nothing of your context except this text."
+        }
+      },
+      required: ["task"],
+      additionalProperties: false
+    }),
+    execute: async ({ task }, options) => {
+      const runCtx = toolRunContextOf(options);
+      const parentSignal = options?.abortSignal ?? runCtx?.signal;
+      const id = `${opts.name}-${seq2 += 1}`;
+      const release = await acquire(parentSignal);
+      const emit = (e) => runCtx?.emit(e);
+      const controller = new AbortController();
+      const onParentAbort = () => controller.abort();
+      parentSignal?.addEventListener("abort", onParentAbort, { once: true });
+      if (parentSignal?.aborted) controller.abort();
+      let timedOut = false;
+      const timer = opts.timeoutMs && opts.timeoutMs > 0 ? setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+      }, opts.timeoutMs) : void 0;
+      emit({ type: "subagent.start", id, name: opts.name, task });
+      try {
+        const forward = (event) => emit({ type: "subagent.event", id, name: opts.name, event });
+        const hostTools = gatedHostTools(runCtx?.approve);
+        const run = opts.worker ? runInWorker : runInProcess;
+        const out = await run(task, controller.signal, forward, hostTools).catch((err) => {
+          if (timedOut)
+            throw new Error(`subagent "${opts.name}" timed out after ${opts.timeoutMs} ms`);
+          throw err;
+        });
+        runCtx?.addUsage(out.usage);
+        emit({ type: "subagent.complete", id, name: opts.name, text: out.text, usage: out.usage });
+        return clip(out.text, outputMax);
+      } catch (err) {
+        emit({
+          type: "subagent.error",
+          id,
+          name: opts.name,
+          error: err instanceof Error ? err.message : String(err)
+        });
+        throw err;
+      } finally {
+        if (timer !== void 0) clearTimeout(timer);
+        parentSignal?.removeEventListener("abort", onParentAbort);
+        release();
+      }
+    }
+  });
+  t.promptHint = "{ task: string }";
+  if (opts.readOnly) t.readOnly = true;
+  return t;
+};
+
+// src/subagent/worker.ts
+var import_ai8 = require("ai");
 
 // src/storage/db.ts
 var import_idb = require("idb");
 var KEYS_STORE = "keys";
 var SECRETS_STORE = "secrets";
 var SESSIONS_STORE = "sessions";
+var FILES_STORE = "files";
+var DB_VERSION = 2;
 var cache = /* @__PURE__ */ new Map();
 var openAgentWebDB = (opts = {}) => {
   const name = opts.dbName ?? "agent-web";
   let p = cache.get(name);
   if (!p) {
-    p = (0, import_idb.openDB)(name, 1, {
+    p = (0, import_idb.openDB)(name, DB_VERSION, {
       upgrade(db) {
         if (!db.objectStoreNames.contains(KEYS_STORE)) db.createObjectStore(KEYS_STORE);
         if (!db.objectStoreNames.contains(SECRETS_STORE)) db.createObjectStore(SECRETS_STORE);
         if (!db.objectStoreNames.contains(SESSIONS_STORE)) db.createObjectStore(SESSIONS_STORE);
+        if (!db.objectStoreNames.contains(FILES_STORE)) db.createObjectStore(FILES_STORE);
       }
     });
     cache.set(name, p);
@@ -1553,12 +3172,336 @@ var MemoryCredentialStore = class {
   }
 };
 
+// src/subagent/worker.ts
+var SUBAGENT_REF = "__subagent__";
+var defaultResolveModel = (spec) => {
+  const { apiKey, ...rest } = spec;
+  const credentials = apiKey ? new MemoryCredentialStore({ [SUBAGENT_REF]: apiKey }) : void 0;
+  return buildModelFromStage(
+    resolveStage(apiKey ? { ...rest, credentialRef: SUBAGENT_REF } : rest, void 0, "subagent"),
+    credentials
+  );
+};
+var serveSubagentWorker = (opts = {}) => {
+  const scope = opts.scope ?? globalThis;
+  let controller;
+  const pending = /* @__PURE__ */ new Map();
+  let callSeq = 0;
+  const proxy = (spec) => {
+    const t = (0, import_ai8.dynamicTool)({
+      description: spec.description,
+      inputSchema: (0, import_ai8.jsonSchema)(spec.inputSchema),
+      execute: (input, options) => new Promise((resolve, reject) => {
+        const callId = `call-${callSeq += 1}`;
+        const signal = options?.abortSignal;
+        if (signal?.aborted) return reject(new Error("aborted"));
+        pending.set(callId, { resolve, reject });
+        signal?.addEventListener(
+          "abort",
+          () => {
+            if (pending.delete(callId)) reject(new Error("aborted"));
+          },
+          { once: true }
+        );
+        safePost(scope, { type: "tool-call", callId, name: spec.name, input });
+      })
+    });
+    return spec.readOnly ? markReadOnly(t) : t;
+  };
+  const run = async (msg) => {
+    controller = new AbortController();
+    let runError;
+    try {
+      const { model: spec, ...rest } = msg.config;
+      const model = await (opts.resolveModel ?? defaultResolveModel)(spec);
+      const proxied = Object.fromEntries(msg.proxied.map((p) => [p.name, proxy(p)]));
+      const agent = await createAgent({
+        ...rest,
+        model,
+        tools: { ...opts.tools, ...proxied }
+      });
+      const result = await agent.run(msg.task, {
+        signal: controller.signal,
+        onEvent: (event) => {
+          if (event.type === "error" && event.phase === "run") runError = event.error;
+          safePost(scope, { type: "event", event });
+        }
+      });
+      if (result.stopped) safePost(scope, { type: "error", error: "aborted" });
+      else if (runError) safePost(scope, { type: "error", error: runError });
+      else
+        safePost(scope, {
+          type: "done",
+          text: result.final,
+          usage: result.usage,
+          steps: result.steps
+        });
+    } catch (err) {
+      safePost(scope, { type: "error", error: err instanceof Error ? err.message : String(err) });
+    }
+  };
+  scope.addEventListener("message", (ev) => {
+    const msg = ev.data;
+    switch (msg?.type) {
+      case "run":
+        void run(msg);
+        break;
+      case "abort":
+        controller?.abort();
+        for (const [id, p] of pending) {
+          pending.delete(id);
+          p.reject(new Error("aborted"));
+        }
+        break;
+      case "tool-result": {
+        const p = pending.get(msg.callId);
+        if (!p) break;
+        pending.delete(msg.callId);
+        if (msg.ok) p.resolve(msg.output);
+        else
+          p.reject(
+            new Error(typeof msg.output === "string" ? msg.output : JSON.stringify(msg.output))
+          );
+        break;
+      }
+    }
+  });
+};
+
+// src/files/vfs.ts
+var MIME = {
+  txt: "text/plain",
+  md: "text/markdown",
+  json: "application/json",
+  csv: "text/csv",
+  html: "text/html",
+  css: "text/css",
+  js: "text/javascript",
+  ts: "text/typescript",
+  svg: "image/svg+xml",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  pdf: "application/pdf",
+  xml: "application/xml",
+  yaml: "text/yaml",
+  yml: "text/yaml"
+};
+var mimeFromPath = (path) => MIME[path.split(".").pop()?.toLowerCase() ?? ""] ?? "application/octet-stream";
+var isTextMime = (mime) => /^text\/|json|xml|yaml|javascript|typescript|svg/.test(mime);
+var normalizePath = (input) => {
+  const parts = [];
+  for (const seg of String(input ?? "").replace(/\\/g, "/").split("/")) {
+    if (!seg || seg === ".") continue;
+    if (seg === "..") {
+      if (parts.length === 0) throw new Error(`path "${input}" escapes the root`);
+      parts.pop();
+      continue;
+    }
+    parts.push(seg);
+  }
+  if (parts.length === 0) throw new Error("a file path is required");
+  return `/${parts.join("/")}`;
+};
+var byteLength = (content, encoding) => encoding === "base64" ? Math.floor(content.replace(/=+$/, "").length * 3 / 4) : new TextEncoder().encode(content).length;
+var bytesToBase64 = (bytes) => {
+  let bin = "";
+  for (let i = 0; i < bytes.length; i += 32768) {
+    bin += String.fromCharCode(...bytes.subarray(i, i + 32768));
+  }
+  return btoa(bin);
+};
+var VirtualFileSystem = class {
+  memory;
+  dbName;
+  ns;
+  maxFileBytes;
+  listeners = /* @__PURE__ */ new Set();
+  constructor(opts = {}) {
+    if (opts.memory) this.memory = /* @__PURE__ */ new Map();
+    this.dbName = opts.dbName;
+    this.ns = opts.namespace ?? "default";
+    this.maxFileBytes = opts.maxFileBytes ?? 10 * 1024 * 1024;
+  }
+  key(path) {
+    return `${this.ns}:${path}`;
+  }
+  /** Subscribe to writes and deletes (e.g. to refresh a file list). Returns an unsubscribe. */
+  onChange(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  notify(type, path) {
+    for (const l of this.listeners) {
+      try {
+        l({ type, path });
+      } catch {
+      }
+    }
+  }
+  async write(path, content, opts = {}) {
+    const p = normalizePath(path);
+    const binary = content instanceof Uint8Array;
+    const encoding = binary ? "base64" : opts.encoding ?? "utf8";
+    const text = binary ? bytesToBase64(content) : content;
+    const size = binary ? content.length : byteLength(text, encoding);
+    if (size > this.maxFileBytes) {
+      throw new Error(`"${p}" is ${size} bytes; the limit is ${this.maxFileBytes}`);
+    }
+    const file = {
+      path: p,
+      content: text,
+      encoding,
+      mimeType: opts.mimeType ?? mimeFromPath(p),
+      size,
+      updatedAt: Date.now()
+    };
+    if (this.memory) this.memory.set(p, file);
+    else {
+      const db = await openAgentWebDB({ dbName: this.dbName });
+      await db.put(FILES_STORE, file, this.key(p));
+    }
+    this.notify("write", p);
+    const { content: _drop, ...info } = file;
+    return info;
+  }
+  /** Store a data URL ("data:image/png;base64,…") as a file. */
+  async writeDataUrl(path, dataUrl) {
+    const m = /^data:([^;,]+)?(;base64)?,(.*)$/s.exec(dataUrl);
+    if (!m) throw new Error("not a data URL");
+    const mimeType = m[1] ?? "application/octet-stream";
+    return m[2] ? this.write(path, m[3], { mimeType, encoding: "base64" }) : this.write(path, decodeURIComponent(m[3]), { mimeType });
+  }
+  async read(path) {
+    const p = normalizePath(path);
+    if (this.memory) return this.memory.get(p);
+    const db = await openAgentWebDB({ dbName: this.dbName });
+    return await db.get(FILES_STORE, this.key(p));
+  }
+  /** The file as a data URL (for <img src>, downloads). */
+  async readDataUrl(path) {
+    const f = await this.read(path);
+    if (!f) return void 0;
+    return f.encoding === "base64" ? `data:${f.mimeType};base64,${f.content}` : `data:${f.mimeType};charset=utf-8,${encodeURIComponent(f.content)}`;
+  }
+  async delete(path) {
+    const p = normalizePath(path);
+    let existed;
+    if (this.memory) existed = this.memory.delete(p);
+    else {
+      const db = await openAgentWebDB({ dbName: this.dbName });
+      existed = await db.get(FILES_STORE, this.key(p)) !== void 0;
+      await db.delete(FILES_STORE, this.key(p));
+    }
+    if (existed) this.notify("delete", p);
+    return existed;
+  }
+  /** Files under a prefix ("/" = all), sorted by path. */
+  async list(prefix = "/") {
+    const dir = prefix === "/" ? "/" : `${normalizePath(prefix)}/`;
+    let files;
+    if (this.memory) files = [...this.memory.values()];
+    else {
+      const db = await openAgentWebDB({ dbName: this.dbName });
+      const range = IDBKeyRange.bound(`${this.ns}:`, `${this.ns}:\uFFFF`);
+      files = await db.getAll(FILES_STORE, range);
+    }
+    return files.filter((f) => dir === "/" || f.path.startsWith(dir)).map(({ content: _drop, ...info }) => info).sort((a, b) => a.path.localeCompare(b.path));
+  }
+  /** Remove every file (of this namespace). */
+  async clear() {
+    for (const f of await this.list()) await this.delete(f.path);
+  }
+};
+
+// src/files/tools.ts
+var import_ai9 = require("ai");
+var createFileTools = (vfs, opts = {}) => {
+  const p = opts.prefix ?? "fs_";
+  const maxRead = opts.maxReadChars ?? 5e4;
+  const tools = {
+    [`${p}list`]: markReadOnly(
+      (0, import_ai9.tool)({
+        description: "List the files in the workspace (attachments the user added, files you wrote). Optionally only under a directory prefix.",
+        inputSchema: (0, import_ai9.jsonSchema)({
+          type: "object",
+          properties: { prefix: { type: "string", description: 'Directory prefix, e.g. "/docs"' } },
+          additionalProperties: false
+        }),
+        execute: async ({ prefix }) => (await vfs.list(prefix || "/")).map((f) => ({
+          path: f.path,
+          mimeType: f.mimeType,
+          size: f.size
+        }))
+      })
+    ),
+    [`${p}read`]: markReadOnly(
+      (0, import_ai9.tool)({
+        description: "Read a text file from the workspace by its path.",
+        inputSchema: (0, import_ai9.jsonSchema)({
+          type: "object",
+          properties: { path: { type: "string", description: 'Absolute path, e.g. "/notes.md"' } },
+          required: ["path"],
+          additionalProperties: false
+        }),
+        execute: async ({ path }) => {
+          const f = await vfs.read(path);
+          if (!f) {
+            const known = (await vfs.list()).map((x) => x.path).slice(0, 30);
+            throw new Error(`no file "${path}"; files: ${known.join(", ") || "none"}`);
+          }
+          if (f.encoding === "base64" && !isTextMime(f.mimeType)) {
+            return `"${f.path}" is a binary file (${f.mimeType}, ${f.size} bytes) and cannot be read as text.`;
+          }
+          const text = f.encoding === "base64" ? atob(f.content) : f.content;
+          return text.length > maxRead ? `${text.slice(0, maxRead)}\u2026 [truncated ${text.length - maxRead} chars]` : text;
+        }
+      })
+    )
+  };
+  if (opts.readOnly) return tools;
+  tools[`${p}write`] = (0, import_ai9.tool)({
+    description: "Write a text file to the workspace (creates or replaces it). Use it for reports, drafts, data the user should be able to open.",
+    inputSchema: (0, import_ai9.jsonSchema)({
+      type: "object",
+      properties: {
+        path: { type: "string", description: 'Absolute path, e.g. "/reports/summary.md"' },
+        content: { type: "string", description: "The full file content" },
+        mimeType: { type: "string", description: "Optional MIME type (guessed from the name)" }
+      },
+      required: ["path", "content"],
+      additionalProperties: false
+    }),
+    execute: async ({ path, content, mimeType }) => {
+      const info = await vfs.write(path, content, mimeType ? { mimeType } : {});
+      return { written: info.path, size: info.size };
+    }
+  });
+  tools[`${p}delete`] = (0, import_ai9.tool)({
+    description: "Delete a file from the workspace.",
+    inputSchema: (0, import_ai9.jsonSchema)({
+      type: "object",
+      properties: { path: { type: "string" } },
+      required: ["path"],
+      additionalProperties: false
+    }),
+    execute: async ({ path }) => ({ deleted: await vfs.delete(path) })
+  });
+  return tools;
+};
+
+// src/index.ts
+init_webllm();
+
 // src/tools/define.ts
-var import_ai4 = require("ai");
+var import_ai10 = require("ai");
 var defineTool = (config) => {
-  const { promptHint, ...rest } = config;
-  const t = (0, import_ai4.tool)(rest);
+  const { promptHint, readOnly, ...rest } = config;
+  const t = (0, import_ai10.tool)(rest);
   if (promptHint) t.promptHint = promptHint;
+  if (readOnly) t.readOnly = true;
   return t;
 };
 
@@ -1613,6 +3556,10 @@ var IndexedDBStore = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AttachmentsNotSupportedError,
+  FILES_STORE,
+  FIND_TOOLS_NAME,
+  ImagesNotSupportedError,
   IndexedDBStore,
   IndexedDBVault,
   KEYS_STORE,
@@ -1623,28 +3570,59 @@ var IndexedDBStore = class {
   ReplanSchema,
   SECRETS_STORE,
   SESSIONS_STORE,
+  SKILL_TOOL_NAMES,
+  TOOL_APPROVAL_MODES,
+  ToolBudgetError,
+  ToolDeniedError,
   VaultCredentialStore,
+  VirtualFileSystem,
+  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,
+  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,
@@ -1652,22 +3630,41 @@ var IndexedDBStore = class {
   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
 });
 //# sourceMappingURL=index.cjs.map