@chatpanel/events 0.66.0 → 0.67.0

package/find-tool.js

@@ -0,0 +1,59 @@
+// `find` — the user's own data and the web, behind ONE registered tool.
+//
+// The history and web-search schemas cost ~1,760 tokens on EVERY turn (1,081 of schema plus
+// a 678-token system block explaining them), paid whether or not the turn touched the user's
+// data. It was noticed on "hi": the model, handed 678 tokens of instructions about history
+// tools, opened the conversation by reciting them. It was doing what we asked.
+//
+// Relevance-narrowing could not help: local tools are exempt from culling on purpose, and
+// culling them by relevance would trade a constant cost for a guessing game in which a turn
+// that needed history silently lost it. A dispatcher has no such trade: everything stays
+// reachable, nothing is guessed, and the saving is identical on every turn.
+//
+// The NAME and the WORDING are the contract every client shares. The extension's `find`
+// and the desktop's `find` must be the same tool — a model that learned to call one on the
+// panel should find the identical tool in the app, and a recipe recorded on one must run on
+// the other. What goes BEHIND it (which search engine, which history store) is the host's.
+
+import { makeDispatchProvider } from './tool-dispatch.js';
+
+export const FIND_TOOL_NAME = 'find';
+
+export const FIND_DESCRIPTION =
+  'Search and read the user\'s own saved data (past chats, notes, meetings) and the web. '
+  + 'Pass an `action` and put that action\'s own arguments inside `args`, e.g. '
+  + '{"action":"history_search","args":{"query":"pricing"}}. Unsure of an action\'s '
+  + 'arguments? {"action":"describe","args":{"tool":"<action>"}} returns its full schema. '
+  + 'Use this when the answer plausibly depends on something the user already has; do not '
+  + 'call it for greetings or general knowledge.';
+
+// One line resident, not 678. The rest travels with `describe`.
+//
+// SAY THAT IT HAS THE DATA, not just that a tool exists. Asked "check my meetings with
+// <name>", a model answered "I do not have access to your personal calendar, emails, or
+// meeting history" — while `find` was sitting in its toolset. The old line named the tool
+// and left the capability to be inferred, and inference is what small models are worst at.
+export const FIND_RESIDENT =
+  "You HAVE access to the user's own ChatPanel data — their past chats, notes, and "
+  + 'meeting transcripts and summaries — through the `find` tool, plus the web. When the '
+  + 'question is about past meetings, notes, people, decisions, or anything the user '
+  + 'discussed or wrote, call `find` FIRST and answer from what it returns. Never tell '
+  + 'the user you cannot access their meetings, notes or history: you can.';
+
+/**
+ * Wrap the real search/read tools (history, web search, weather…) as the one `find` tool.
+ *
+ * `remote` is false: history is on-device and web search is proxied by the host under its
+ * own settings, so the harness hands these tools real values under "redact remote".
+ */
+export function findDispatchProvider(inner, { all = null, rank = undefined } = {}) {
+  return makeDispatchProvider({
+    name: FIND_TOOL_NAME,
+    description: FIND_DESCRIPTION,
+    resident: FIND_RESIDENT,
+    inner,
+    remote: false,
+    all,
+    rank,
+  });
+}

package/index.js

@@ -177,6 +177,15 @@ export {
   resultToolSpec, RESULT_TOOL_NAME, DEFAULT_SHIELD, DEFAULT_STORE,
 } from './tool-result.js';
 export { findTools, findToolsResult, findActionArgs, oneLiner, overlapRank, FIND_ACTION } from './tool-discovery.js';
+// One registered tool per group, the registry that merges providers, and the two tools every
+// client with a loop offers — the SAME `find` and `web_search` on the panel and in the app.
+export { buildToolset } from './toolset.js';
+export {
+  DESCRIBE_ACTION, actionMenu, buildGroupDispatchSpec, validateAction, makeGroupDispatchExecutor,
+  withGuidance, makeDispatchProvider, estimateTokens,
+} from './tool-dispatch.js';
+export { FIND_TOOL_NAME, FIND_DESCRIPTION, FIND_RESIDENT, findDispatchProvider } from './find-tool.js';
+export { WEB_SEARCH_TOOL_NAME, WEB_SEARCH_TOOL_SYSTEM, WEB_SEARCH_SPEC, searchResultsToText, webSearchToolProvider } from './web-search-tool.js';
 export { compressToolSpec, compressToolSpecs, compressionStats, trimDescription, COMPRESSION_MODES, DEFAULT_COMPRESSION } from './tool-schema.js';
 export { validateRecipe, expandRecipe, recipeParams, mapInput, dryRunRecipe, runPlan, runRecipe, RecipeError, RECIPE_MODES } from './recipe.js';
 export { createManifest, ManifestError, SOURCES } from './manifest.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/events",
-  "version": "0.66.0",
+  "version": "0.67.0",
   "description": "The canonical ChatPanel event-log and capability contracts \u2014 typed durable facts, clock-free deterministic linearization, schema upcasting, and the invariants the replay harness asserts. Pure, dependency-free ESM shared by the ChatPanel extension, gateway and bridge.",
   "type": "module",
   "main": "index.js",
@@ -94,7 +94,11 @@
     "./voice-speaker.js": "./voice-speaker.js",
     "./weather.js": "./weather.js",
     "./web-search.js": "./web-search.js",
-    "./widget.js": "./widget.js"
+    "./widget.js": "./widget.js",
+    "./toolset.js": "./toolset.js",
+    "./tool-dispatch.js": "./tool-dispatch.js",
+    "./find-tool.js": "./find-tool.js",
+    "./web-search-tool.js": "./web-search-tool.js"
   },
   "files": [
     "LICENSE",
@@ -111,6 +115,7 @@
     "entity.js",
     "event.js",
     "extraction.js",
+    "find-tool.js",
     "flowchart.js",
     "harness.js",
     "index.js",
@@ -171,18 +176,21 @@
     "theme.js",
     "titles.js",
     "tool-discovery.js",
+    "tool-dispatch.js",
     "tool-groups.js",
     "tool-need.js",
     "tool-result.js",
     "tool-round.js",
     "tool-schema.js",
     "tool-traits.js",
+    "toolset.js",
     "trajectory.js",
     "upcast.js",
     "vault.js",
     "view.js",
     "voice-intents.js",
     "weather.js",
+    "web-search-tool.js",
     "web-search.js",
     "widget.js"
   ],

package/tool-dispatch.js

@@ -0,0 +1,231 @@
+// PROGRESSIVE TOOL DISCLOSURE — a group of tools registered as ONE tool.
+//
+// Twenty page-action schemas cost ~3,300 tokens on EVERY turn; six data tools cost ~1,760.
+// Paid whether or not the turn touched any of them, and on a small local model that can eat
+// half the context before the user has typed anything. So a group is registered as one
+// compact tool carrying an action enum and a one-line gist each; the full schema for any
+// action is REACHABLE via `{action:'describe', tool:'<name>'}`, and arguments are validated
+// at execution with a structured error the model can act on.
+//
+// WHY A DISPATCHER RATHER THAN AN INDEX. Over MCP a model may only call tools that are
+// REGISTERED; returning a schema from an index tool would not make the described tool
+// callable. A dispatcher is one registered tool that can reach all of them, so the same
+// mechanism works for a relayed CLI agent and for an in-client loop.
+//
+// The page dispatcher proved the shape and earned three bugs doing it (the stripped `args`
+// envelope, the blinded loop guard, the unreadable activity rows). Every later group — the
+// user's own data, MCP servers, and now the desktop's turn — goes through this instead of
+// re-earning them. What a group supplies is only what is genuinely its own: a name, a
+// sentence about when to reach for it, and whether its tools are remote.
+
+import { FIND_ACTION, findToolsResult, findActionArgs } from './tool-discovery.js';
+import { traitsIndex } from './tool-traits.js';
+
+export const DESCRIBE_ACTION = 'describe';
+
+/** First sentence of a description — enough to choose an action, not to call it blind. */
+function gistOf(spec) {
+  const text = String(spec.description || '').replace(/\s+/g, ' ').trim();
+  const stop = text.search(/(?<=[.!?])\s/);
+  const first = stop > 0 ? text.slice(0, stop) : text;
+  return first.length > 90 ? `${first.slice(0, 87).trimEnd()}...` : first;
+}
+
+function requiredOf(spec) {
+  const req = spec?.parameters?.required;
+  return Array.isArray(req) ? req : [];
+}
+
+/** The action menu — one line per action, enough to choose but not to call blind. */
+export function actionMenu(specs) {
+  return specs.map((s) => {
+    const req = requiredOf(s);
+    return `- ${s.name}${req.length ? `(${req.join(', ')})` : '()'}: ${gistOf(s)}`;
+  }).join('\n');
+}
+
+/**
+ * Build a dispatcher spec for ANY group of tools.
+ *
+ * @param hidden how many more actions the group can reach than the menu lists (a relevance
+ *               cap trimmed it). When > 0 the spec says so and names the way back: `find`
+ *               searches every tool the group owns, listed or not. Without that line a tool
+ *               the cap dropped was, for that turn, gone.
+ */
+export function buildGroupDispatchSpec({ name, description, specs, hidden = 0 }) {
+  const more = hidden > 0
+    ? `\n${hidden} more action${hidden === 1 ? '' : 's'} not listed — {"action":"${FIND_ACTION}","args":{"query":"<task words>"}} finds them by name.`
+    : '';
+  return {
+    name,
+    description: `${description}\n\nActions:\n${actionMenu(specs)}${more}`,
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: [DESCRIBE_ACTION, ...(hidden > 0 ? [FIND_ACTION] : []), ...specs.map((s) => s.name)],
+          description: 'Which action to run.',
+        },
+        // A DECLARED envelope, not `additionalProperties`. Providers and MCP validators
+        // routinely strip properties that are not in `properties`, so undeclared top-level
+        // arguments silently vanish before they reach the executor — which is exactly how
+        // `structured_insert` lost its `elements` array. Anything declared survives.
+        args: {
+          type: 'object',
+          description: 'The chosen action\'s own arguments, verbatim. Use {} when it takes none.',
+          additionalProperties: true,
+        },
+        tool: { type: 'string', description: `With action="${DESCRIBE_ACTION}": the action to describe.` },
+        ...(hidden > 0 ? findActionArgs() : {}),
+      },
+      required: ['action'],
+      additionalProperties: true, // tolerated, but never relied upon — see `args`
+    },
+  };
+}
+
+/**
+ * Validate arguments against the REAL spec. Returns null when fine, else a structured error
+ * naming exactly what is missing — a bounded repair path instead of a dead turn.
+ */
+export function validateAction(spec, args) {
+  const missing = requiredOf(spec).filter((k) => args[k] === undefined || args[k] === null);
+  if (!missing.length) return null;
+  return {
+    error: `Missing required argument(s) for "${spec.name}": ${missing.join(', ')}.`,
+    required: requiredOf(spec),
+    hint: `Put them inside \`args\`: {"action":"${spec.name}","args":{...}}. `
+      + `Call {"action":"${DESCRIBE_ACTION}","args":{"tool":"${spec.name}"}} for the full schema.`,
+  };
+}
+
+/**
+ * Route one dispatch call to the real per-action executor.
+ *
+ * `runAction(name, args, meta)` is the EXISTING guarded executor, so every confirmation gate,
+ * budget and site grant keeps firing on the real action name — the dispatcher must never
+ * become a way around them.
+ *
+ * @param specs  the MENU — what the dispatcher lists
+ * @param all    everything the group can reach; defaults to the menu. When larger, `find`
+ *               searches it and any action in it runs, listed or not.
+ * @param rank   `(specs, query) => specs` for `find`; the shared IDF ranker when given
+ */
+export function makeGroupDispatchExecutor({ name: dispatchName, specs, all = specs, runAction, rank }) {
+  const byName = new Map(all.map((s) => [s.name, s]));
+  for (const s of specs) byName.set(s.name, s); // the menu's copy wins a duplicate name
+  const menuNames = specs.map((s) => s.name);
+  return async (name, input, meta) => {
+    if (name !== dispatchName) return runAction(name, input, meta); // direct calls still work
+    // Accept BOTH shapes. `args` is the declared envelope and the one the description
+    // teaches; top-level arguments are merged too, so a model that ignores the envelope — or
+    // a provider that happens to pass extras through — still works rather than failing in a
+    // way that looks like the tool is broken.
+    const raw = input || {};
+    const { action: rawAction, args: envelope, tool: rawTool, ...rest } = raw;
+    const args = { ...rest, ...(envelope && typeof envelope === 'object' ? envelope : {}) };
+    const action = String(rawAction || '');
+
+    if (action === FIND_ACTION) {
+      return findToolsResult(all, String(args.query ?? rawTool ?? ''), { rank, describeAction: DESCRIBE_ACTION, menu: menuNames });
+    }
+
+    if (action === DESCRIBE_ACTION) {
+      const spec = byName.get(String(args.tool || rawTool || ''));
+      return JSON.stringify(
+        spec
+          ? {
+            name: spec.name,
+            // The full contract when the menu carried a compressed one (tool-schema.js).
+            description: spec.full?.description || spec.description,
+            parameters: spec.full?.parameters || spec.parameters,
+            ...(spec.annotations ? { annotations: spec.annotations } : {}),
+            callAs: { action: spec.name, args: '<the properties above, verbatim>' },
+          }
+          : { error: `Unknown action "${args.tool || rawTool}".`, actions: [...byName.keys()] },
+      );
+    }
+
+    const spec = byName.get(action);
+    if (!spec) {
+      return JSON.stringify({
+        error: `Unknown action "${action}".`,
+        actions: menuNames,
+        ...(all.length > specs.length ? { hint: `${all.length - specs.length} more are reachable: {"action":"${FIND_ACTION}","args":{"query":"…"}} finds them.` } : {}),
+      });
+    }
+    const bad = validateAction(spec, args);
+    if (bad) return JSON.stringify(bad);
+    return runAction(action, args, meta);
+  };
+}
+
+/**
+ * Attach a group's detailed guidance to `describe` instead of the prompt. The model reads it
+ * at the moment it is about to act on it — which is when it is most likely to follow it —
+ * and a turn that never reaches for the group never pays for it.
+ */
+export function withGuidance(execute, guidance) {
+  if (!guidance) return execute;
+  return async (name, input, meta) => {
+    const out = await execute(name, input, meta);
+    if (String(input?.action || '') !== DESCRIBE_ACTION) return out;
+    try {
+      const parsed = JSON.parse(out);
+      if (!parsed || !parsed.name) return out;
+      return JSON.stringify({ ...parsed, guidance });
+    } catch {
+      return out;
+    }
+  };
+}
+
+/**
+ * Turn a toolset into ONE provider — the reusable half of progressive disclosure.
+ *
+ * @param inner    a toolset ({ specs, execute, system }) — the real tools, kept whole.
+ * @param resident the ONE line that stays in the prompt. Everything else the group wants to
+ *                 say travels with `describe`.
+ * @param remote   true when these tools call a third party. This is load-bearing for
+ *                 PRIVACY, not bookkeeping: the harness uses it to keep PII off remote tools
+ *                 under "redact remote". A dispatcher that lost the flag would quietly turn
+ *                 redacted tools into unredacted ones.
+ * @param all      every spec the group can reach when the menu (`inner.specs`) is a
+ *                 relevance-capped subset. `find` searches it; any action in it runs.
+ * @param rank     the ranker `find` uses — the shared IDF one, so discovery agrees with the
+ *                 narrowing that hid the tool in the first place.
+ */
+export function makeDispatchProvider({ name, description, resident, inner, remote = false, all = null, rank = undefined }) {
+  if (!inner || !inner.specs?.length) return null;
+  const specs = inner.specs;
+  const reach = all && all.length > specs.length ? all : specs;
+  return {
+    specs: [buildGroupDispatchSpec({ name, specs, description, hidden: reach.length - specs.length })],
+    system: resident,
+    remote,
+    // What each REAL tool does to the world (annotations, else its name) — read by the round
+    // runner through the dispatcher, which otherwise hides every inner spec.
+    traits: traitsIndex(reach),
+    // …and WHICH tools are behind this name, so a recipe step can name the real tool and be
+    // routed through the dispatcher (buildToolset builds `hiddenVia` from it).
+    reach,
+    execute: withGuidance(
+      makeGroupDispatchExecutor({
+        name,
+        specs,
+        all: reach,
+        rank,
+        // Routes on the REAL tool name so every guard, budget and gate downstream keeps
+        // firing on the name it was written against.
+        runAction: (toolName, args, meta) => inner.execute(toolName, args, meta),
+      }),
+      inner.system,
+    ),
+  };
+}
+
+/** Rough token estimate — used by budget tests, not at runtime. */
+export function estimateTokens(value) {
+  return Math.round(JSON.stringify(value).length / 4);
+}

package/toolset.js

@@ -0,0 +1,89 @@
+// A generic tool registry — ANY number of tool providers merged into the one shape a model
+// loop consumes: `{ specs, execute, system }`.
+//
+// A provider is `{ specs: ToolSpec[], execute(name, input, meta) => string | {text, note,
+// image}, system?: string, remote?: boolean, serial?: boolean, traits?: Map, reach?: [] }`.
+// ToolSpec is `{ name, description, parameters (JSON schema), annotations? }`.
+//
+// This lived in the extension for as long as the extension was the only client with a tool
+// loop. The desktop grew one, and the second copy of "first provider to claim a name wins"
+// would have been the second place that rule could quietly differ. Everything here is
+// input → output; the one platform-flavoured thing — the shared MCP guidance a client
+// prepends when any `mcp_*` tool is present — is INJECTED, so this file carries no prompt
+// text of its own and stays off the extension's first-paint budget by exactly the bytes
+// the old copy cost.
+
+const REMOTE_NAME_RE = /^mcp[_-]/i;
+
+/**
+ * @param providers  the tool providers, in the order the model should read them
+ * @param mcpSystem  the shared MCP rules — a string, or a function returning one, consulted
+ *                   only when an `mcp_*` tool is present so a turn without MCP pays nothing
+ * @returns the merged toolset, or `undefined` when no provider brought a tool
+ */
+export function buildToolset(providers, { mcpSystem = '' } = {}) {
+  const list = (providers || []).filter((p) => p && p.specs?.length);
+  if (!list.length) return undefined;
+
+  const specs = [];
+  const route = new Map(); // tool name -> the provider.execute that owns it
+  // Tools that call a REMOTE server — from a provider flagged remote, or (fallback) whose
+  // name matches the mcp_ convention. The PII harness uses this exact set to keep private
+  // data off remote tools under "redact remote".
+  const remoteTools = new Set();
+  // What each HIDDEN tool does — a dispatcher's own index of the tools behind it
+  // (tool-traits.js). Top-level specs carry `annotations` and are classified at run time.
+  const traits = new Map();
+  // Tools that must run one at a time even when read-only: page tools share ONE tab.
+  const serialTools = new Set();
+  // The tools a dispatcher hides, and which dispatcher: a recipe step names the real tool.
+  const reach = [];
+  const hiddenVia = new Map();
+  for (const p of list) {
+    const providerRemote = p.remote === true;
+    if (p.traits instanceof Map) for (const [k, v] of p.traits) if (!traits.has(k)) traits.set(k, v);
+    if (Array.isArray(p.reach) && p.specs.length === 1) {
+      for (const h of p.reach) if (h?.name && !hiddenVia.has(h.name)) { hiddenVia.set(h.name, p.specs[0].name); reach.push(h); }
+    }
+    for (const s of p.specs) {
+      if (route.has(s.name)) continue; // first provider to claim a name wins
+      specs.push(s);
+      route.set(s.name, p.execute);
+      if (providerRemote || REMOTE_NAME_RE.test(String(s.name || ''))) remoteTools.add(s.name);
+      if (p.serial === true) serialTools.add(s.name);
+    }
+  }
+  if (!specs.length) return undefined;
+
+  // Generic MCP rules ONCE (not repeated per server), then each provider's own inventory.
+  const hasMcp = specs.some((s) => REMOTE_NAME_RE.test(String(s?.name || '')));
+  const shared = hasMcp ? String((typeof mcpSystem === 'function' ? mcpSystem() : mcpSystem) || '') : '';
+  const parts = [shared, ...list.map((p) => p.system)];
+  const system = parts.map((x) => String(x || '').trim()).filter(Boolean).join('\n\n') || undefined;
+  // WHICH blurb costs what — one total for the whole preamble is visible but unattributable,
+  // and a number nobody can attribute is a number nobody can reduce.
+  const systemParts = {};
+  if (shared.trim()) systemParts.mcp = Math.round(shared.length / 4);
+  for (const p of list) {
+    const t = Math.round(String(p.system || '').trim().length / 4);
+    // Named by the dispatcher tool it owns — 'page', 'find', 'mcp' — which is what the
+    // reader sees in the tools list and can act on.
+    if (t) systemParts[p.id || p.specs[0]?.name || 'group'] = t;
+  }
+
+  return {
+    specs,
+    system,
+    systemParts,
+    remoteTools,
+    traits,
+    serialTools,
+    reach,
+    hiddenVia,
+    async execute(name, input, meta = {}) {
+      const fn = route.get(name);
+      if (!fn) return JSON.stringify({ error: `Unknown tool: ${name}` });
+      return fn(name, input, meta);
+    },
+  };
+}

package/web-search-tool.js

@@ -0,0 +1,107 @@
+// `web_search` as a TOOL — the spec, the guidance, and how results are put in front of a
+// model, without the search itself.
+//
+// Running a search is platform work: the extension fetches SERPs from a service worker
+// with DOMParser, the desktop's main process reads anchors with a tokenizer, a gateway that
+// grew one would use its own fetch. What is identical everywhere is what the model is told
+// the tool does, what it is told about citing, and how a result list becomes text it can
+// cite from — so that is what lives here, and `search` is injected.
+//
+// The citation rules are in the RESULT, not only in the system prompt, on purpose: the
+// model reads them at the moment it has sources in hand, which is when it is most likely to
+// follow them, and a turn that never searches never pays for them.
+
+export const WEB_SEARCH_TOOL_NAME = 'web_search';
+
+export const WEB_SEARCH_TOOL_SYSTEM =
+  'You can call web_search to look up current information from the web — prices, news, recent '
+  + 'events, documentation, or anything time-sensitive or that may have changed since your training. '
+  + 'Call it whenever the user asks about such things instead of guessing or saying you are unsure. '
+  + 'Cite results inline as markdown links — e.g. ([1](https://…)) — never HTML, <sup>, or bare '
+  + 'numbers, and finish with a "Sources" list of the links you used.';
+
+export const WEB_SEARCH_SPEC = Object.freeze({
+  name: WEB_SEARCH_TOOL_NAME,
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+  description:
+    'Search the web and return ranked result snippets with their source URLs. Use this for '
+    + 'current events, live prices/quotes, news, product/library docs, or any fact you are unsure '
+    + 'about or that may have changed since training — prefer it over guessing.',
+  parameters: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'The search query — a few keywords work best.' },
+    },
+    required: ['query'],
+    additionalProperties: false,
+  },
+});
+
+/**
+ * Flatten a search result into one readable blob the model can cite from.
+ *
+ * `res` is `{ query, engines: [ids], results: [{ rank, title, url, text }] }`. A citation
+ * index of markdown links sits at the TOP so it survives truncation.
+ */
+export function searchResultsToText(res) {
+  if (!res?.results?.length) {
+    // Name the engines HERE especially. The success path already lists them; the failure
+    // path did not, so "no web results" looked like "the web has nothing" when it usually
+    // means "the one engine we were allowed to ask returned nothing" — a search engine
+    // blocking us and a query with no answer are completely different problems, and the
+    // model cannot tell them apart without this.
+    const tried = (res?.engines || []).join(', ');
+    return `No web results for "${res?.query || ''}"`
+      + (tried ? ` (searched: ${tried}).` : '.')
+      + ' This may mean the engine blocked the request rather than that nothing exists —'
+      + ' do NOT conclude the information is unavailable. Try a shorter, more general query'
+      + ' (drop dates and qualifiers), and tell the user they can enable another search'
+      + ' engine in ChatPanel settings if it keeps failing.';
+  }
+  const engines = Array.isArray(res.engines) ? res.engines : [];
+  const sources = res.results.map((r) => `[${r.rank}] [${r.title}](${r.url})`).join('\n');
+  const example = res.results[0].url;
+  const head =
+    `Web search results for "${res.query}" (engines: ${engines.join(', ')}).\n\n`
+    + 'Citation rules: when a claim draws on a result below, cite it inline as a markdown '
+    + `link to that result's URL — e.g. ([1](${example})). Cite multiple sources as separate `
+    + 'links: ([1](url)) ([3](url)). Do NOT output HTML, <sup>, or bare bracket numbers like '
+    + '[1] — every citation must be a clickable markdown link. Finish with a "Sources" section '
+    + 'that repeats, as markdown links, each source you cited.\n\n'
+    + `Sources:\n${sources}`;
+  const body = res.results
+    .map((r) => `### [${r.rank}] ${r.title}\n<${r.url}>\n\n${r.text}`)
+    .join('\n\n---\n\n');
+  return `${head}\n\n---\nResult details:\n\n${body}`;
+}
+
+/**
+ * The tool provider — `{ specs, system, execute }` for `buildToolset`.
+ *
+ * @param search `(query) => Promise<{ query, engines, results }>` — the host's search. It
+ *               may throw; the model gets the message rather than a dead turn.
+ */
+export function webSearchToolProvider({ search } = {}) {
+  if (typeof search !== 'function') throw new Error('webSearchToolProvider: search required');
+  return {
+    specs: [WEB_SEARCH_SPEC],
+    system: WEB_SEARCH_TOOL_SYSTEM,
+    async execute(name, input) {
+      if (name !== WEB_SEARCH_TOOL_NAME) return JSON.stringify({ error: `Unknown tool: ${name}` });
+      const q = String(input?.query || '').trim();
+      if (!q) return 'No query provided to web_search.';
+      try {
+        const res = await search(q);
+        // Return an OBJECT so the step can name the ENGINE that actually served the results.
+        // "web_search" alone doesn't tell the user whether Startpage or DuckDuckGo answered —
+        // which matters, because engines differ in coverage, and because a CLI agent may have
+        // run its OWN search instead of this one. `note` becomes the step's badge; `text` is
+        // what the model reads, unchanged.
+        const engines = (res?.engines || []).join(', ');
+        return { text: searchResultsToText(res), note: engines ? `ChatPanel · ${engines}` : 'ChatPanel' };
+      } catch (e) {
+        return `web_search failed: ${e?.message || e}`;
+      }
+    },
+  };
+}