@chatpanel/events 0.101.0 → 0.103.1

package/tool-discovery.js

@@ -1,87 +1 @@
-// `find` — the way back to a tool the menu left out.
-//
-// Narrowing keeps a turn's tool list short by ranking the connected tools against the
-// message and showing the top few. It keeps the EXECUTE map whole on purpose — a tool the
-// model knows the name of still runs — but nothing told the model the names it was not
-// shown. So a tool that ranked low was, for that turn, gone: the model could not ask for
-// it because it did not know to.
-//
-// This is the missing half. A `find` action searches the FULL set — every tool the group
-// owns, narrowed or not — and answers with names and one-liners, cheap enough to sit on
-// every dispatcher and cheap enough to call on a hunch. The model discovers, then calls;
-// the menu stays short; the capability decision the cap used to make silently is now a
-// call away. `describe` already gives the full schema for one action, so the two together
-// are the pay-as-you-go ladder: names → one line → full schema, each on demand.
-//
-// Ranking is injected. The lexical, IDF-weighted ranker the extension and gateway share
-// lives in @chatpanel/pii; this package must stay dependency-free, so it takes `rank` and
-// falls back to a plain token overlap when a host has none.
-
-export const FIND_ACTION = 'find';
-
-const STOP = new Set(['the', 'and', 'for', 'with', 'that', 'this', 'use', 'can', 'you', 'your', 'from', 'what', 'how', 'are', 'get', 'find', 'tool', 'tools']);
-
-const tokens = (s) => String(s || '').toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 2 && !STOP.has(w));
-
-/** Token overlap — a fallback, not a ranker anyone should prefer. */
-export function overlapRank(specs, query) {
-  const q = new Set(tokens(query));
-  if (!q.size) return [...specs];
-  return specs
-    .map((s, i) => {
-      const hay = `${s.name} ${s.description || ''}`.toLowerCase();
-      let n = 0;
-      for (const w of q) if (hay.includes(w)) n += 1;
-      return { s, i, n };
-    })
-    .sort((a, b) => (b.n - a.n) || (a.i - b.i))
-    .map((x) => x.s);
-}
-
-/** First sentence, whitespace collapsed, capped — the "one line" of the ladder. */
-export function oneLiner(description, max = 110) {
-  const s = String(description || '').replace(/\s+/g, ' ').trim();
-  const cut = s.search(/[.!?]\s|\n/);
-  const first = cut > 20 ? s.slice(0, cut + 1) : s;
-  return first.length > max ? `${first.slice(0, max - 1).trimEnd()}…` : first;
-}
-
-const requiredOf = (spec) => {
-  const p = spec?.parameters || spec?.inputSchema;
-  return Array.isArray(p?.required) ? p.required.map(String) : [];
-};
-
-/**
- * @param specs  the FULL set — not the narrowed menu
- * @param rank   `(specs, query) => specs` most-relevant first
- * @returns `[{ name, summary, required }]`
- */
-export function findTools(specs, query, { limit = 8, rank = overlapRank } = {}) {
-  const list = (specs || []).filter((s) => s && s.name);
-  const q = String(query || '').trim();
-  const ranked = q ? rank(list, q) : list;
-  const cap = Math.max(1, Math.min(50, Number(limit) || 8));
-  return ranked.slice(0, cap).map((s) => ({ name: s.name, summary: oneLiner(s.description), required: requiredOf(s) }));
-}
-
-/** The JSON text a `find` action returns, with the next step spelled out. */
-export function findToolsResult(specs, query, { limit, rank, describeAction = 'describe', menu = [] } = {}) {
-  const found = findTools(specs, query, { limit, rank });
-  const total = (specs || []).length;
-  const hidden = new Set(menu.map((m) => (typeof m === 'string' ? m : m?.name)));
-  return JSON.stringify({
-    query: String(query || ''),
-    matches: found.map((f) => ({ ...f, listed: hidden.size ? hidden.has(f.name) : undefined })),
-    total,
-    hint: found.length
-      ? `Call one as {"action":"<name>","args":{…}}. Unsure of its arguments? {"action":"${describeAction}","args":{"tool":"<name>"}}.`
-      : `No tool matched "${query}" among ${total}. Try other words, or describe the task differently.`,
-  });
-}
-
-/** The parameter schema fragment a dispatcher advertises for `find`. */
-export function findActionArgs() {
-  return {
-    query: { type: 'string', description: `With action="${FIND_ACTION}": words describing the task; returns matching tool names.` },
-  };
-}
+const d="find",l=new Set(["the","and","for","with","that","this","use","can","you","your","from","what","how","are","get","find","tool","tools"]),m=e=>String(e||"").toLowerCase().split(/[^a-z0-9]+/).filter(t=>t.length>2&&!l.has(t));function f(e,t){const o=new Set(m(t));return o.size?e.map((n,r)=>{const a=`${n.name} ${n.description||""}`.toLowerCase();let s=0;for(const c of o)a.includes(c)&&(s+=1);return{s:n,i:r,n:s}}).sort((n,r)=>r.n-n.n||n.i-r.i).map(n=>n.s):[...e]}function h(e,t=110){const o=String(e||"").replace(/\s+/g," ").trim(),n=o.search(/[.!?]\s|\n/),r=n>20?o.slice(0,n+1):o;return r.length>t?`${r.slice(0,t-1).trimEnd()}…`:r}const g=e=>{const t=e?.parameters||e?.inputSchema;return Array.isArray(t?.required)?t.required.map(String):[]};function p(e,t,{limit:o=8,rank:n=f}={}){const r=(e||[]).filter(i=>i&&i.name),a=String(t||"").trim(),s=a?n(r,a):r,c=Math.max(1,Math.min(50,Number(o)||8));return s.slice(0,c).map(i=>({name:i.name,summary:h(i.description),required:g(i)}))}function y(e,t,{limit:o,rank:n,describeAction:r="describe",menu:a=[]}={}){const s=p(e,t,{limit:o,rank:n}),c=(e||[]).length,i=new Set(a.map(u=>typeof u=="string"?u:u?.name));return JSON.stringify({query:String(t||""),matches:s.map(u=>({...u,listed:i.size?i.has(u.name):void 0})),total:c,hint:s.length?`Call one as {"action":"<name>","args":{…}}. Unsure of its arguments? {"action":"${r}","args":{"tool":"<name>"}}.`:`No tool matched "${t}" among ${c}. Try other words, or describe the task differently.`})}function S(){return{query:{type:"string",description:`With action="${d}": words describing the task; returns matching tool names.`}}}export{d as FIND_ACTION,S as findActionArgs,p as findTools,y as findToolsResult,h as oneLiner,f as overlapRank};

package/tool-dispatch.js

@@ -1,231 +1,6 @@
-// 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 as g,findToolsResult as A,findActionArgs as N}from"./tool-discovery.js";import{traitsIndex as q}from"./tool-traits.js";const m="describe";function O(e){const t=String(e.description||"").replace(/\s+/g," ").trim(),r=t.search(/(?<=[.!?])\s/),n=r>0?t.slice(0,r):t;return n.length>90?`${n.slice(0,87).trimEnd()}...`:n}function b(e){const t=e?.parameters?.required;return Array.isArray(t)?t:[]}function k(e){return e.map(t=>{const r=b(t);return`- ${t.name}${r.length?`(${r.join(", ")})`:"()"}: ${O(t)}`}).join(`
+`)}function j({name:e,description:t,specs:r,hidden:n=0}){const c=n>0?`
+${n} more action${n===1?"":"s"} not listed — {"action":"${g}","args":{"query":"<task words>"}} finds them by name.`:"";return{name:e,description:`${t}
 
-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);
-}
+Actions:
+${k(r)}${c}`,parameters:{type:"object",properties:{action:{type:"string",enum:[m,...n>0?[g]:[],...r.map(i=>i.name)],description:"Which action to run."},args:{type:"object",description:"The chosen action's own arguments, verbatim. Use {} when it takes none.",additionalProperties:!0},tool:{type:"string",description:`With action="${m}": the action to describe.`},...n>0?N():{}},required:["action"],additionalProperties:!0}}}function v(e,t){const r=b(e).filter(n=>t[n]===void 0||t[n]===null);return r.length?{error:`Missing required argument(s) for "${e.name}": ${r.join(", ")}.`,required:b(e),hint:`Put them inside \`args\`: {"action":"${e.name}","args":{...}}. Call {"action":"${m}","args":{"tool":"${e.name}"}} for the full schema.`}:null}function J({name:e,specs:t,all:r=t,runAction:n,rank:c}){const i=new Map(r.map(o=>[o.name,o]));for(const o of t)i.set(o.name,o);const a=t.map(o=>o.name);return async(o,u,l)=>{if(o!==e)return n(o,u,l);const h=u||{},{action:d,args:y,tool:$,...w}=h,f={...w,...y&&typeof y=="object"?y:{}},p=String(d||"");if(p===g)return A(r,String(f.query??$??""),{rank:c,describeAction:m,menu:a});if(p===m){const s=i.get(String(f.tool||$||""));return JSON.stringify(s?{name:s.name,description:s.full?.description||s.description,parameters:s.full?.parameters||s.parameters,...s.annotations?{annotations:s.annotations}:{},callAs:{action:s.name,args:"<the properties above, verbatim>"}}:{error:`Unknown action "${f.tool||$}".`,actions:[...i.keys()]})}const S=i.get(p);if(!S)return JSON.stringify({error:`Unknown action "${p}".`,actions:a,...r.length>t.length?{hint:`${r.length-t.length} more are reachable: {"action":"${g}","args":{"query":"…"}} finds them.`}:{}});const x=v(S,f);return x?JSON.stringify(x):n(p,f,l)}}function T(e,t){return t?async(r,n,c)=>{const i=await e(r,n,c);if(String(n?.action||"")!==m)return i;try{const a=JSON.parse(i);return!a||!a.name?i:JSON.stringify({...a,guidance:t})}catch{return i}}:e}function C({name:e,description:t,resident:r,inner:n,remote:c=!1,all:i=null,rank:a=void 0}){if(!n||!n.specs?.length)return null;const o=n.specs,u=i&&i.length>o.length?i:o;return{specs:[j({name:e,specs:o,description:t,hidden:u.length-o.length})],system:r,remote:c,traits:q(u),reach:u,execute:T(J({name:e,specs:o,all:u,rank:a,runAction:(l,h,d)=>n.execute(l,h,d)}),n.system)}}function E(e){return Math.round(JSON.stringify(e).length/4)}export{m as DESCRIBE_ACTION,k as actionMenu,j as buildGroupDispatchSpec,E as estimateTokens,C as makeDispatchProvider,J as makeGroupDispatchExecutor,v as validateAction,T as withGuidance};

package/tool-groups.js

@@ -1,81 +1 @@
-// Tool groups as plugins — "here is a set of capabilities, and when to offer them".
-//
-// The extension assembles a turn's toolset from three hardcoded blocks: the user's own
-// data, their MCP servers, and the page. Each block is the same shape — decide whether it
-// applies, build a provider, collapse it behind a dispatcher — written out three times, so
-// a fourth means editing a shared function and no other client can contribute one at all.
-//
-// The failure this prevents is not hypothetical. A duplicated search-engine list in two
-// files produced a retired engine that kept reappearing in settings; two implementations of
-// one decision disagree eventually. A registry makes that unrepresentable: there is one
-// list, and it is the registrations.
-//
-// A group DECIDES and BUILDS; it does not know about the others. Ordering is explicit
-// priority rather than call order, because "which tools does the model see first" should be
-// a stated decision and not an accident of where someone added a line.
-
-export class ToolGroupError extends Error {
-  constructor(code, message) { super(message); this.name = 'ToolGroupError'; this.code = code; }
-}
-
-/**
- * @param applies (ctx) => boolean — cheap, synchronous, no side effects. Kept separate from
- *        `build` so "should this be offered" can be answered without paying to construct
- *        it: MCP construction connects to servers, and asking that question should not.
- * @param build   async (ctx) => provider | null. Returning null is normal (nothing
- *        configured), not an error.
- */
-export function defineToolGroup({ id, label, applies, build, priority = 0 }) {
-  if (!id) throw new ToolGroupError('BAD_GROUP', 'group.id required');
-  if (typeof build !== 'function') throw new ToolGroupError('BAD_GROUP', `group '${id}': build required`);
-  return Object.freeze({
-    id,
-    label: label || id,
-    priority,
-    applies: typeof applies === 'function' ? applies : () => true,
-    build,
-  });
-}
-
-export function createToolGroupRegistry() {
-  const groups = [];
-  return {
-    add(group) {
-      groups.push(group);
-      return () => { const i = groups.indexOf(group); if (i >= 0) groups.splice(i, 1); };
-    },
-
-    list: () => [...groups].sort((a, b) => b.priority - a.priority),
-
-    /**
-     * Build every group that applies, in priority order.
-     *
-     * Groups are built CONCURRENTLY because one of them connects to remote servers and
-     * serialising would add its latency to every turn — but the RESULT is re-sorted by
-     * priority, so the order the model sees never depends on which finished first.
-     *
-     * A group that throws is dropped with a report, not propagated: a broken MCP server
-     * must not cost the user their history tools. Same isolation rule as the source
-     * registry and the adapter registry, for the same reason.
-     */
-    async build(ctx, { onError = () => {}, admit = null } = {}) {
-      const eligible = this.list().filter((g) => {
-        // Admission is checked BEFORE `applies`, and both before `build`. A group the user
-        // switched off must not do its work and be discarded afterwards — for MCP that work
-        // is connecting to servers, which is what once made a first turn wait 45 seconds.
-        if (admit && !admit(g)) return false;
-        try { return !!g.applies(ctx); } catch (e) { onError(g.id, e); return false; }
-      });
-      const built = await Promise.all(eligible.map(async (g) => {
-        try { return { id: g.id, priority: g.priority, provider: await g.build(ctx) }; } catch (e) {
-          onError(g.id, e);
-          return null;
-        }
-      }));
-      return built
-        .filter((b) => b && b.provider)
-        .sort((a, b) => b.priority - a.priority)
-        .map((b) => ({ id: b.id, provider: b.provider }));
-    },
-  };
-}
+class p extends Error{constructor(t,e){super(e),this.name="ToolGroupError",this.code=t}}function s({id:i,label:t,applies:e,build:o,priority:u=0}){if(!i)throw new p("BAD_GROUP","group.id required");if(typeof o!="function")throw new p("BAD_GROUP",`group '${i}': build required`);return Object.freeze({id:i,label:t||i,priority:u,applies:typeof e=="function"?e:()=>!0,build:o})}function c(){const i=[];return{add(t){return i.push(t),()=>{const e=i.indexOf(t);e>=0&&i.splice(e,1)}},list:()=>[...i].sort((t,e)=>e.priority-t.priority),async build(t,{onError:e=()=>{},admit:o=null}={}){const u=this.list().filter(r=>{if(o&&!o(r))return!1;try{return!!r.applies(t)}catch(n){return e(r.id,n),!1}});return(await Promise.all(u.map(async r=>{try{return{id:r.id,priority:r.priority,provider:await r.build(t)}}catch(n){return e(r.id,n),null}}))).filter(r=>r&&r.provider).sort((r,n)=>n.priority-r.priority).map(r=>({id:r.id,provider:r.provider}))}}}export{p as ToolGroupError,c as createToolGroupRegistry,s as defineToolGroup};

package/tool-hints.js

@@ -1,185 +1,10 @@
-// The prompt text every client hands a model about its tools. Shared, so it reads the same everywhere.
-export function combineSystemPrompt(...parts) {
-  return parts
-    .map((p) => String(p || '').trim())
-    .filter(Boolean)
-    .join('\n\n');
-}
-
-export function sourceCitationSystem({ compact = false } = {}) {
-  if (compact) {
-    return 'Cite these sources inline with <sup>[1]</sup> and add a bottom "Sources" list with labels and links: reuse any "Open in ChatPanel" link, derive a canonical URL from a returned ID (e.g. Wikipedia page ID → https://en.wikipedia.org/?curid=<id>), else give the ID/label. Never guess a URL you cannot derive.';
-  }
-  return [
-    'Source citation policy:',
-    'When your answer uses any attached, retrieved, searched, or tool-provided source, including MCP tools and history/search tools, cite the relevant claim inline with superscript markers like <sup>[1]</sup>.',
-    'Finish with a "Sources" section listing each cited source once. Match the numbering used in the answer.',
-    'For each source, include the best available title/name and URL/link. A ChatPanel history/note/meeting/chat result already carries an "Open in ChatPanel" chrome-extension:// link — reuse that exact link so the user can jump straight to the item.',
-    'If a tool returns a stable identifier for a known public source instead of a URL (e.g. a Wikipedia page ID, DOI, arXiv/PubMed ID, or a slug), build the canonical URL from it — for a Wikipedia page ID use https://en.wikipedia.org/?curid=<id> — and cite that. Deterministically constructing a URL from an ID the tool returned is derivation, not fabrication.',
-    'Only when no URL is present AND none can be derived, fall back to the source ID, page ID, tool name, search result label, or file/meeting/chat label so the user can still find it.',
-    'Do not invent sources, page IDs, or titles, and never guess a URL you cannot derive from a returned identifier.',
-    'If you did not use sources beyond general reasoning, omit the Sources section.',
-  ].join('\n');
-}
-
-export function toolStatus(result) {
-  const o = resultObject(result);
-  if (!o) {
-    // A plain-text result (a search's prose, a relayed agent's line): an error when it says
-    // so the way the shared tools do — `error: …`, `web_search failed: …` — else fine.
-    const s = typeof result === 'string' ? result : (result && typeof result === 'object' && typeof result.text === 'string' ? result.text : '');
-    if (!s.trim()) return '';
-    return /^(error:|\w+ failed\b)/i.test(s) ? `error: ${s.slice(0, 80)}` : 'ok';
-  }
-  if (o.error) {
-    const detail = errorDetail(o);
-    if (o.blocked) return `blocked: ${detail}`.slice(0, 90);
-    return `error: ${detail}`.slice(0, 90);
-  }
-  if (typeof o.mode === 'string') return o.mode;
-  if (o.ok === false) return `fail${o.error ? ': ' + String(o.error).slice(0, 70) : ''}`;
-  if (o.note) return String(o.note).slice(0, 80);
-  return 'ok';
-}
-
-// The GENERIC MCP guidance + citation policy — identical for every server, so emit
-// it ONCE per turn (see buildToolset), not once per connected server. Previously
-// this rode inside every mcpInventorySystem() block, so N servers repeated it N
-// times and bloated the prompt by thousands of tokens.
-export function mcpSharedSystem() {
-  return [
-    'One or more MCP servers are connected in ChatPanel for this conversation (each listed below with its callable tools).',
-    'Use their MCP tools directly when the user asks for matching data or actions. Do not ask the user to configure or discover these tools if they are listed.',
-    'Do not call MCP tools when the attached page or provided context is enough to answer; summarize or analyze that context directly.',
-    'Prefer relevant MCP tools over web search for their domain. If an MCP tool fails, state the exact tool error first, then say whether you are falling back to another source.',
-    "Match the user's request domain to the tool's domain: Hacker News requests should use Hacker News tools, Confluence requests should use Confluence tools, and Jira requests should use Jira tools.",
-    'Form arguments precisely: pass ONLY the specific entity, identifier, or minimal distinctive keywords the tool needs — not the full sentence, greetings, pleasantries, or unrelated personal details from the conversation. For lookup-by-title/ID tools pass the exact canonical name or ID (e.g. title "Seattle", not "which state is Seattle in"); for search tools pass the fewest keywords that uniquely identify the target. Fill every required argument and follow each argument\'s schema description.',
-    "If you don't know the exact title or ID a lookup tool requires, first call the matching search/list tool to resolve it, then call the lookup — never guess identifiers.",
-    'Do not retry the exact same failed tool call. Re-check the listed inputs, choose a better matching tool, or answer with the tool error.',
-    'When MCP or search results inform the answer, include inline citations and a bottom Sources section; do not wait for the user to ask for links.',
-    sourceCitationSystem(),
-  ].join('\n');
-}
-
-// Per-server block: ONLY the server-specific inventory (name + callable tool names
-// + a short guide). The generic rules/citation live once in mcpSharedSystem().
-export function mcpInventorySystem(serverName, specs = []) {
-  if (!specs.length) return '';
-  const title = String(serverName || 'MCP').trim() || 'MCP';
-  const names = specs.map((s) => s.name).filter(Boolean);
-  const shownNames = names.slice(0, 80).join(', ');
-  const moreNames = names.length > 80 ? `, and ${names.length - 80} more` : '';
-  const useful = specs.slice(0, 18).map(toolLine).filter(Boolean).join('\n');
-  return [
-    `MCP server "${title}" — callable tools: ${shownNames}${moreNames}.`,
-    useful ? `Tool guide:\n${useful}` : '',
-  ].filter(Boolean).join('\n');
-}
-
-function resultObject(result) {
-  if (typeof result === 'string') return parseJson(result);
-  if (!result || typeof result !== 'object') return null;
-  if (typeof result.text === 'string') return parseJson(result.text) || result;
-  return result;
-}
-
-function parseJson(s) {
-  try {
-    return JSON.parse(s);
-  } catch {
-    return null;
-  }
-}
-
-function errorDetail(o) {
-  const detail =
-    o.message ||
-    o.detail ||
-    o.error_description ||
-    o.refusal_reason ||
-    o.retry_hint ||
-    o.error;
-  if (typeof detail === 'string') return detail;
-  try {
-    return JSON.stringify(detail);
-  } catch {
-    return String(detail);
-  }
-}
-
-function toolLine(spec) {
-  const desc = cleanDescription(spec.description || spec.name || '');
-  const inputs = inputNames(spec.parameters);
-  const inputText = inputs.length ? ` inputs: ${inputs.join(', ')}` : '';
-  return `- ${spec.name}${inputText}: ${desc}`.slice(0, 260);
-}
-
-function cleanDescription(desc) {
-  return String(desc)
-    .replace(/^\[[^\]]+\]\s*/, '')
-    .replace(/\s+/g, ' ')
-    .trim()
-    .slice(0, 180);
-}
-
-function inputNames(schema = {}) {
-  const props = schema?.properties || {};
-  const required = new Set(schema?.required || []);
-  return Object.keys(props)
-    .slice(0, 6)
-    .map((name) => required.has(name) ? `${name}*` : name);
-}
-
-/**
- * How to build something the user can KEEP.
- *
- * Nobody should have to know an API to ask for a timer. The user says "make me a pomodoro
- * timer"; the model is the one that should know ChatPanel renders a single HTML file in a
- * sandbox and offers to keep it, and that a widget which remembers anything must save it
- * through `chatpanel.setState` — because nothing else in the sandbox persists.
- *
- * Kept short on purpose: it rides on every turn that could produce HTML, so it earns its
- * tokens by being the difference between a widget that forgets on close and one that doesn't.
- */
-export function widgetAuthoringSystem() {
-  return [
-    'Building small apps (widgets):',
-    'When the user asks for a small self-contained tool — a timer, calculator, converter, sticky note, tracker, checklist, dice, scoreboard — answer with ONE ```html block containing a complete, self-contained file (inline CSS/JS, no external requests). ChatPanel runs it in a sandbox and offers a "＋ Keep" button that saves it as a permanent widget in the user\'s panel.',
-    'If the widget should remember anything between visits — elapsed time, notes, a tally, settings — persist it with the ChatPanel widget API, which is injected automatically:',
-    '  await chatpanel.getState()      // returns what was saved, or null the first time',
-    '  await chatpanel.setState(value) // save any JSON value',
-    'Load state on start and save it whenever it changes. It works in the chat preview too, not only once kept. localStorage is backed by the same store, but indexedDB and cookies THROW in the sandbox — never use them.',
-    'The sandbox has NO network access and no access to the user\'s data, so build the widget to work entirely offline unless the user has granted it a capability.',
-    'Keep it compact and readable at ~320px wide (the panel is narrow), and give it sensible defaults so it is useful the moment it appears.',
-    'Give the file a <title> — it becomes the widget\'s name, and its icon is chosen from that name (a "Pomodoro Timer" gets a timer, "Standup Notes" a notepad).',
-  ].join('\n');
-}
-
-/**
- * How to keep a secret, told ONLY when the turn is about one.
- *
- * The widget guidance above rides on every turn that could produce HTML and is already at
- * its budget, and this is three times the size of the line it would replace. It is also
- * irrelevant to a pomodoro timer. So it is gated on the user actually asking for something
- * that holds credentials — which is cheap, deterministic, and wrong only in the direction
- * that costs nothing (a missed hint means a widget that stores a password in plain state,
- * and the vault is still there for the next attempt).
- */
-const SECRETY = /\b(password|passphrase|secret|vault|credential|api[- ]?key|token|pin code|private note|login|2fa|seed phrase)/i;
-
-export function wantsVaultGuidance(userText) {
-  return SECRETY.test(String(userText || ''));
-}
-
-export function vaultWidgetSystem() {
-  return [
-    'Secrets in a widget (passwords, keys, private notes) must NOT go in state — state is plain JSON on disk. Use the encrypted vault, which is keyed by a passphrase ChatPanel never stores:',
-    '  <meta name="chatpanel-requests" content="vault.status, vault.unlock, vault.list, vault.add, vault.reveal">',
-    '  await chatpanel.invoke("vault.status")                        // { exists, locked, entries }',
-    '  await chatpanel.invoke("vault.unlock")                        // ChatPanel asks for the passphrase itself',
-    '  await chatpanel.invoke("vault.add", { title, note, secret })',
-    '  await chatpanel.invoke("vault.list", { query })               // titles only, never secrets',
-    '  await chatpanel.invoke("vault.reveal", { id })                // ChatPanel asks the user each time',
-    'Never build your own passphrase box and never keep the secret in a variable longer than you need it. The user approves these once, when they keep the widget, so any call can throw — catch it and say so in the UI. Build the locked state first: a vault UI that assumes it is unlocked is wrong most of the time.',
-  ].join('\n');
-}
+function g(...e){return e.map(t=>String(t||"").trim()).filter(Boolean).join(`
+
+`)}function c({compact:e=!1}={}){return e?'Cite these sources inline with <sup>[1]</sup> and add a bottom "Sources" list with labels and links: reuse any "Open in ChatPanel" link, derive a canonical URL from a returned ID (e.g. Wikipedia page ID → https://en.wikipedia.org/?curid=<id>), else give the ID/label. Never guess a URL you cannot derive.':["Source citation policy:","When your answer uses any attached, retrieved, searched, or tool-provided source, including MCP tools and history/search tools, cite the relevant claim inline with superscript markers like <sup>[1]</sup>.",'Finish with a "Sources" section listing each cited source once. Match the numbering used in the answer.','For each source, include the best available title/name and URL/link. A ChatPanel history/note/meeting/chat result already carries an "Open in ChatPanel" chrome-extension:// link — reuse that exact link so the user can jump straight to the item.',"If a tool returns a stable identifier for a known public source instead of a URL (e.g. a Wikipedia page ID, DOI, arXiv/PubMed ID, or a slug), build the canonical URL from it — for a Wikipedia page ID use https://en.wikipedia.org/?curid=<id> — and cite that. Deterministically constructing a URL from an ID the tool returned is derivation, not fabrication.","Only when no URL is present AND none can be derived, fall back to the source ID, page ID, tool name, search result label, or file/meeting/chat label so the user can still find it.","Do not invent sources, page IDs, or titles, and never guess a URL you cannot derive from a returned identifier.","If you did not use sources beyond general reasoning, omit the Sources section."].join(`
+`)}function w(e){const t=u(e);if(!t){const n=typeof e=="string"?e:e&&typeof e=="object"&&typeof e.text=="string"?e.text:"";return n.trim()?/^(error:|\w+ failed\b)/i.test(n)?`error: ${n.slice(0,80)}`:"ok":""}if(t.error){const n=h(t);return t.blocked?`blocked: ${n}`.slice(0,90):`error: ${n}`.slice(0,90)}return typeof t.mode=="string"?t.mode:t.ok===!1?`fail${t.error?": "+String(t.error).slice(0,70):""}`:t.note?String(t.note).slice(0,80):"ok"}function y(){return["One or more MCP servers are connected in ChatPanel for this conversation (each listed below with its callable tools).","Use their MCP tools directly when the user asks for matching data or actions. Do not ask the user to configure or discover these tools if they are listed.","Do not call MCP tools when the attached page or provided context is enough to answer; summarize or analyze that context directly.","Prefer relevant MCP tools over web search for their domain. If an MCP tool fails, state the exact tool error first, then say whether you are falling back to another source.","Match the user's request domain to the tool's domain: Hacker News requests should use Hacker News tools, Confluence requests should use Confluence tools, and Jira requests should use Jira tools.",`Form arguments precisely: pass ONLY the specific entity, identifier, or minimal distinctive keywords the tool needs — not the full sentence, greetings, pleasantries, or unrelated personal details from the conversation. For lookup-by-title/ID tools pass the exact canonical name or ID (e.g. title "Seattle", not "which state is Seattle in"); for search tools pass the fewest keywords that uniquely identify the target. Fill every required argument and follow each argument's schema description.`,"If you don't know the exact title or ID a lookup tool requires, first call the matching search/list tool to resolve it, then call the lookup — never guess identifiers.","Do not retry the exact same failed tool call. Re-check the listed inputs, choose a better matching tool, or answer with the tool error.","When MCP or search results inform the answer, include inline citations and a bottom Sources section; do not wait for the user to ask for links.",c()].join(`
+`)}function v(e,t=[]){if(!t.length)return"";const n=String(e||"MCP").trim()||"MCP",a=t.map(l=>l.name).filter(Boolean),r=a.slice(0,80).join(", "),s=a.length>80?`, and ${a.length-80} more`:"",i=t.slice(0,18).map(d).filter(Boolean).join(`
+`);return[`MCP server "${n}" — callable tools: ${r}${s}.`,i?`Tool guide:
+${i}`:""].filter(Boolean).join(`
+`)}function u(e){return typeof e=="string"?o(e):!e||typeof e!="object"?null:typeof e.text=="string"&&o(e.text)||e}function o(e){try{return JSON.parse(e)}catch{return null}}function h(e){const t=e.message||e.detail||e.error_description||e.refusal_reason||e.retry_hint||e.error;if(typeof t=="string")return t;try{return JSON.stringify(t)}catch{return String(t)}}function d(e){const t=p(e.description||e.name||""),n=f(e.parameters),a=n.length?` inputs: ${n.join(", ")}`:"";return`- ${e.name}${a}: ${t}`.slice(0,260)}function p(e){return String(e).replace(/^\[[^\]]+\]\s*/,"").replace(/\s+/g," ").trim().slice(0,180)}function f(e={}){const t=e?.properties||{},n=new Set(e?.required||[]);return Object.keys(t).slice(0,6).map(a=>n.has(a)?`${a}*`:a)}function k(){return["Building small apps (widgets):",'When the user asks for a small self-contained tool — a timer, calculator, converter, sticky note, tracker, checklist, dice, scoreboard — answer with ONE ```html block containing a complete, self-contained file (inline CSS/JS, no external requests). ChatPanel runs it in a sandbox and offers a "＋ Keep" button that saves it as a permanent widget in the user\'s panel.',"If the widget should remember anything between visits — elapsed time, notes, a tally, settings — persist it with the ChatPanel widget API, which is injected automatically:","  await chatpanel.getState()      // returns what was saved, or null the first time","  await chatpanel.setState(value) // save any JSON value","Load state on start and save it whenever it changes. It works in the chat preview too, not only once kept. localStorage is backed by the same store, but indexedDB and cookies THROW in the sandbox — never use them.","The sandbox has NO network access and no access to the user's data, so build the widget to work entirely offline unless the user has granted it a capability.","Keep it compact and readable at ~320px wide (the panel is narrow), and give it sensible defaults so it is useful the moment it appears.",`Give the file a <title> — it becomes the widget's name, and its icon is chosen from that name (a "Pomodoro Timer" gets a timer, "Standup Notes" a notepad).`].join(`
+`)}const m=/\b(password|passphrase|secret|vault|credential|api[- ]?key|token|pin code|private note|login|2fa|seed phrase)/i;function b(e){return m.test(String(e||""))}function S(){return["Secrets in a widget (passwords, keys, private notes) must NOT go in state — state is plain JSON on disk. Use the encrypted vault, which is keyed by a passphrase ChatPanel never stores:",'  <meta name="chatpanel-requests" content="vault.status, vault.unlock, vault.list, vault.add, vault.reveal">','  await chatpanel.invoke("vault.status")                        // { exists, locked, entries }','  await chatpanel.invoke("vault.unlock")                        // ChatPanel asks for the passphrase itself','  await chatpanel.invoke("vault.add", { title, note, secret })','  await chatpanel.invoke("vault.list", { query })               // titles only, never secrets','  await chatpanel.invoke("vault.reveal", { id })                // ChatPanel asks the user each time',"Never build your own passphrase box and never keep the secret in a variable longer than you need it. The user approves these once, when they keep the widget, so any call can throw — catch it and say so in the UI. Build the locked state first: a vault UI that assumes it is unlocked is wrong most of the time."].join(`
+`)}export{g as combineSystemPrompt,v as mcpInventorySystem,y as mcpSharedSystem,c as sourceCitationSystem,w as toolStatus,S as vaultWidgetSystem,b as wantsVaultGuidance,k as widgetAuthoringSystem};