@chatpanel/events 0.102.0 → 0.104.0

package/tool-traits.js

@@ -1,182 +1 @@
-// What a tool DOES to the world — read from its annotations, guessed from its name, and
-// turned into the three decisions every host was making by hand.
-//
-// MCP tools carry `annotations` (readOnlyHint, destructiveHint, idempotentHint,
-// openWorldHint) and nothing in any ChatPanel client read them. Meanwhile each client
-// decided separately whether a call could run alongside another (never — every round ran
-// one call at a time), whether a repeat could be answered from the last result (a
-// hand-kept list of seven tool names), and whether an action deserved a confirmation
-// (per-action, per-site rules with no idea what the tool itself declared). Three
-// decisions, one fact underneath: is this a read, and could it destroy something.
-//
-// Annotations win when present. When absent, the NAME is read — `get_`, `list_`,
-// `search_` on one side, `delete_`, `purge_`, `revoke_` on the other — with the
-// conservative default in the middle: a tool nobody can classify is a write, not a read,
-// and "unknown" is never promoted to "safe".
-//
-// Class R: strings in, booleans out. No I/O, so the extension, desktop, gateway and bridge
-// give the same answer for the same spec.
-
-const READ_VERBS = new Set([
-  'get', 'list', 'search', 'read', 'find', 'fetch', 'query', 'describe', 'lookup', 'look', 'show',
-  'view', 'count', 'check', 'status', 'recall', 'inspect', 'screenshot', 'preview', 'browse', 'grep',
-  'glob', 'head', 'tail', 'cat', 'ls', 'stat', 'resolve', 'detect', 'validate', 'explain', 'summarize',
-  'summarise', 'summary', 'history', 'recent', 'latest', 'whoami', 'info', 'render', 'compare', 'diff',
-  'ping', 'health', 'select', 'retrieve', 'load', 'peek', 'watch', 'tools', 'schema', 'suggest', 'smart',
-]);
-
-// Anything that changes the world without necessarily destroying part of it. A name that
-// carries one of these is never a read, whatever else it carries: `search_and_replace`
-// searches, and replaces.
-const WRITE_VERBS = new Set([
-  'create', 'update', 'set', 'post', 'put', 'send', 'write', 'add', 'edit', 'move', 'rename',
-  'upload', 'run', 'execute', 'exec', 'click', 'type', 'submit', 'save', 'insert', 'patch', 'apply',
-  'merge', 'push', 'commit', 'start', 'stop', 'enable', 'disable', 'assign', 'close', 'reopen',
-  'login', 'logout', 'install', 'replace', 'transfer', 'pay', 'order', 'book', 'schedule',
-  'publish', 'deploy', 'restart', 'import', 'sync', 'remember', 'label', 'tag', 'mark', 'fill',
-  'press', 'scroll', 'navigate', 'open', 'goto', 'drag', 'invoke', 'call', 'trigger', 'act',
-]);
-
-const DESTRUCTIVE_VERBS = new Set([
-  'delete', 'remove', 'drop', 'purge', 'destroy', 'reset', 'clear', 'kill', 'wipe', 'revoke',
-  'truncate', 'erase', 'overwrite', 'rm', 'rmdir', 'uninstall', 'terminate', 'ban', 'force',
-  'unlink', 'discard', 'forget',
-]);
-
-// `mcp_<server>__<tool>` → `<tool>`; `jira:delete-issue` → `delete-issue`.
-export function bareToolName(name) {
-  const s = String(name || '');
-  const i = s.lastIndexOf('__');
-  return i >= 0 ? s.slice(i + 2) : s.replace(/^mcp[_-]/i, '');
-}
-
-const tokensOf = (name) => bareToolName(name).toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
-
-function hasHint(a) {
-  return !!a && typeof a === 'object' && ['readOnlyHint', 'destructiveHint', 'idempotentHint', 'openWorldHint'].some((k) => typeof a[k] === 'boolean');
-}
-
-/**
- * @returns {{ readOnly: boolean, destructive: boolean, idempotent: boolean, openWorld: boolean, source: 'annotations'|'heuristic' }}
- */
-export function toolTraits(spec) {
-  const name = typeof spec === 'string' ? spec : spec?.name;
-  const a = typeof spec === 'object' && spec ? spec.annotations : null;
-  const toks = tokensOf(name);
-  const namedDestructive = toks.some((t) => DESTRUCTIVE_VERBS.has(t));
-  const namedWrite = namedDestructive || toks.some((t) => WRITE_VERBS.has(t));
-  // A read verb anywhere (`web_search`, `issue_get`) — as long as nothing in the name writes.
-  const namedRead = !namedWrite && toks.some((t) => READ_VERBS.has(t));
-
-  if (hasHint(a)) {
-    const readOnly = a.readOnlyHint === true;
-    // The spec's default for an absent destructiveHint is TRUE, which would put every
-    // `create_issue` behind a confirmation. Explicit wins; absent falls back to the name.
-    const destructive = readOnly ? false : (typeof a.destructiveHint === 'boolean' ? a.destructiveHint : namedDestructive);
-    return {
-      readOnly,
-      destructive,
-      idempotent: readOnly || a.idempotentHint === true,
-      openWorld: typeof a.openWorldHint === 'boolean' ? a.openWorldHint : true,
-      source: 'annotations',
-    };
-  }
-  return { readOnly: namedRead, destructive: namedDestructive, idempotent: namedRead, openWorld: true, source: 'heuristic' };
-}
-
-/** Two reads never race each other for the world; a write is a barrier. */
-export const canRunConcurrently = (t) => !!t?.readOnly;
-
-/** A read asked twice has one answer, so the second can be served from the first. */
-export const isCacheable = (t) => !!t?.readOnly;
-
-/** Destroying is the one thing a person should be asked about, whatever the site rules say. */
-export const needsConfirmation = (t) => t?.destructive === true;
-
-/** Name → traits for a whole toolset, including the tools a dispatcher hides. */
-export function traitsIndex(specs = []) {
-  const index = new Map();
-  for (const s of specs) if (s?.name) index.set(s.name, toolTraits(s));
-  return index;
-}
-
-/**
- * Ask before a destructive call — the gate, as a toolset wrapper with the dialog injected.
- *
- * Page actions have had a confirmation card since the beginning; a tool on a connected
- * server that DECLARES itself destructive (`destructiveHint`, or a name like `delete_repo`)
- * had none: the model called it and it ran. This asks first, on the REAL tool name even
- * when a dispatcher hides it, and refuses when there is nobody to ask — a background turn
- * with no window cannot destroy anything a person did not approve.
- *
- * @param confirm  async ({ name, input, via }) => 'allow' | 'always' | 'deny'. `always`
- *                 allows this tool for the rest of the toolset's life (one session).
- *                 Omit it on a surface with no window: destructive calls are then refused
- *                 with a message the model can act on.
- * @param only     `(name) => boolean` — which top-level tools the gate covers (a host that
- *                 already confirms its page and note tools passes its remote set).
- * @param traitsOf `(name, input) => traits`; defaults to the toolset's index, then the name.
- */
-export function withDestructiveGate(toolset, { confirm = null, only = () => true, traitsOf = null, effectiveName = defaultEffectiveName } = {}) {
-  if (!toolset || typeof toolset.execute !== 'function') return toolset;
-  const base = toolset.execute.bind(toolset);
-  const byName = new Map((toolset.specs || []).filter((s) => s?.name).map((s) => [s.name, s]));
-  const allowed = new Set();
-  const traits = traitsOf || ((name, input) => {
-    const eff = effectiveName(name, input);
-    return toolset.traits?.get(eff) || toolset.traits?.get(name) || toolTraits(byName.get(eff) || byName.get(name) || { name: eff });
-  });
-  return {
-    ...toolset,
-    async execute(name, input, meta) {
-      if (!only(name)) return base(name, input, meta);
-      const t = traits(name, input);
-      if (!needsConfirmation(t)) return base(name, input, meta);
-      const eff = effectiveName(name, input);
-      if (allowed.has(eff)) return base(name, input, meta);
-      if (!confirm) {
-        return JSON.stringify({
-          error: `"${eff}" is a destructive action and needs the user's confirmation, which this surface cannot ask for. Do not retry it; tell the user what you would do and let them run it from the side panel.`,
-          blocked: true, needsConfirmation: true, tool: eff,
-        });
-      }
-      const decision = await confirm({ name: eff, input, via: name === eff ? null : name, traits: t });
-      if (decision === 'always') allowed.add(eff);
-      if (decision !== 'allow' && decision !== 'always') {
-        return JSON.stringify({ error: `The user DECLINED "${eff}". Do not retry it — stop and ask the user how to proceed.`, blocked: true, declined: true, tool: eff });
-      }
-      return base(name, input, meta);
-    },
-  };
-}
-
-// A dispatcher carries the real action in `input.action`; every name-based policy must
-// see through it or `mcp {action:"mcp_x__delete_repo"}` is judged by the name "mcp" — and
-// `page {action:'screenshot'}` taken four times looks like a stuck loop instead of a look.
-// One definition: the extension, the desktop and the gate each had their own copy.
-export function effectiveToolName(name, input) {
-  const action = input && typeof input === 'object' ? input.action : null;
-  return typeof action === 'string' && action ? action : name;
-}
-const defaultEffectiveName = effectiveToolName;
-
-// Local tools whose reads may overlap in one round: they touch the user's own data or the
-// network, never the one tab a page tool is driving. Everything not remote and not here
-// runs one at a time, whatever its name says — a wrong "parallel" races the world, a wrong
-// "serial" only costs latency. The `find` dispatcher is here as a whole: everything behind
-// it is a read of the user's data or the web (its writes are separate tools by design).
-//
-// ONE list. The extension and the desktop each kept their own and they drifted within
-// weeks — the desktop serialised `recall` and `skill_open` that the extension overlapped.
-export const PARALLEL_LOCAL_RE = /^(find$|history_|web_search$|weather$|get_result$|skill_open$|skill_file$|recall$|memory_recall$|meeting_live_transcript$)/;
-
-/**
- * May this call share a batch with its neighbours? Read-only by its traits, not pinned
- * serial by the toolset, and either remote (its own server) or on the local overlap list.
- */
-export function parallelEligible(tools, call, traits) {
-  if (!traits?.readOnly) return false;
-  if (tools?.serialTools?.has(call.name)) return false;
-  const eff = effectiveToolName(call.name, call.input);
-  return !!tools?.remoteTools?.has(call.name) || PARALLEL_LOCAL_RE.test(eff) || PARALLEL_LOCAL_RE.test(call.name);
-}
+const w=new Set(["get","list","search","read","find","fetch","query","describe","lookup","look","show","view","count","check","status","recall","inspect","screenshot","preview","browse","grep","glob","head","tail","cat","ls","stat","resolve","detect","validate","explain","summarize","summarise","summary","history","recent","latest","whoami","info","render","compare","diff","ping","health","select","retrieve","load","peek","watch","tools","schema","suggest","smart"]),b=new Set(["create","update","set","post","put","send","write","add","edit","move","rename","upload","run","execute","exec","click","type","submit","save","insert","patch","apply","merge","push","commit","start","stop","enable","disable","assign","close","reopen","login","logout","install","replace","transfer","pay","order","book","schedule","publish","deploy","restart","import","sync","remember","label","tag","mark","fill","press","scroll","navigate","open","goto","drag","invoke","call","trigger","act"]),v=new Set(["delete","remove","drop","purge","destroy","reset","clear","kill","wipe","revoke","truncate","erase","overwrite","rm","rmdir","uninstall","terminate","ban","force","unlink","discard","forget"]);function k(e){const t=String(e||""),r=t.lastIndexOf("__");return r>=0?t.slice(r+2):t.replace(/^mcp[_-]/i,"")}const x=e=>k(e).toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);function _(e){return!!e&&typeof e=="object"&&["readOnlyHint","destructiveHint","idempotentHint","openWorldHint"].some(t=>typeof e[t]=="boolean")}function h(e){const t=typeof e=="string"?e:e?.name,r=typeof e=="object"&&e?e.annotations:null,c=x(t),l=c.some(o=>v.has(o)),d=!(l||c.some(o=>b.has(o)))&&c.some(o=>w.has(o));if(_(r)){const o=r.readOnlyHint===!0,f=o?!1:typeof r.destructiveHint=="boolean"?r.destructiveHint:l;return{readOnly:o,destructive:f,idempotent:o||r.idempotentHint===!0,openWorld:typeof r.openWorldHint=="boolean"?r.openWorldHint:!0,source:"annotations"}}return{readOnly:d,destructive:l,idempotent:d,openWorld:!0,source:"heuristic"}}const H=e=>!!e?.readOnly,S=e=>!!e?.readOnly,E=e=>e?.destructive===!0;function $(e=[]){const t=new Map;for(const r of e)r?.name&&t.set(r.name,h(r));return t}function R(e,{confirm:t=null,only:r=()=>!0,traitsOf:c=null,effectiveName:l=O}={}){if(!e||typeof e.execute!="function")return e;const u=e.execute.bind(e),d=new Map((e.specs||[]).filter(n=>n?.name).map(n=>[n.name,n])),o=new Set,f=c||((n,s)=>{const i=l(n,s);return e.traits?.get(i)||e.traits?.get(n)||h(d.get(i)||d.get(n)||{name:i})});return{...e,async execute(n,s,i){if(!r(n))return u(n,s,i);const m=f(n,s);if(!E(m))return u(n,s,i);const a=l(n,s);if(o.has(a))return u(n,s,i);if(!t)return JSON.stringify({error:`"${a}" is a destructive action and needs the user's confirmation, which this surface cannot ask for. Do not retry it; tell the user what you would do and let them run it from the side panel.`,blocked:!0,needsConfirmation:!0,tool:a});const p=await t({name:a,input:s,via:n===a?null:n,traits:m});return p==="always"&&o.add(a),p!=="allow"&&p!=="always"?JSON.stringify({error:`The user DECLINED "${a}". Do not retry it — stop and ask the user how to proceed.`,blocked:!0,declined:!0,tool:a}):u(n,s,i)}}}function y(e,t){const r=t&&typeof t=="object"?t.action:null;return typeof r=="string"&&r?r:e}const O=y,g=/^(find$|history_|web_search$|weather$|get_result$|skill_open$|skill_file$|recall$|memory_recall$|meeting_live_transcript$)/;function T(e,t,r){if(!r?.readOnly||e?.serialTools?.has(t.name))return!1;const c=y(t.name,t.input);return!!e?.remoteTools?.has(t.name)||g.test(c)||g.test(t.name)}export{g as PARALLEL_LOCAL_RE,k as bareToolName,H as canRunConcurrently,y as effectiveToolName,S as isCacheable,E as needsConfirmation,T as parallelEligible,h as toolTraits,$ as traitsIndex,R as withDestructiveGate};

package/toolset.js

@@ -1,89 +1,3 @@
-// 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 l=/^mcp[_-]/i;function S(g,{mcpSystem:i=""}={}){const s=(g||[]).filter(t=>t&&t.specs?.length);if(!s.length)return;const o=[],a=new Map,h=new Set,c=new Map,m=new Set,d=[],f=new Map;for(const t of s){const n=t.remote===!0;if(t.traits instanceof Map)for(const[e,r]of t.traits)c.has(e)||c.set(e,r);if(Array.isArray(t.reach)&&t.specs.length===1)for(const e of t.reach)e?.name&&!f.has(e.name)&&(f.set(e.name,t.specs[0].name),d.push(e));for(const e of t.specs)a.has(e.name)||(o.push(e),a.set(e.name,t.execute),(n||l.test(String(e.name||"")))&&h.add(e.name),t.serial===!0&&m.add(e.name))}if(!o.length)return;const p=o.some(t=>l.test(String(t?.name||"")))?String((typeof i=="function"?i():i)||""):"",M=[p,...s.map(t=>t.system)].map(t=>String(t||"").trim()).filter(Boolean).join(`
 
-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);
-    },
-  };
-}
+`)||void 0,u={};p.trim()&&(u.mcp=Math.round(p.length/4));for(const t of s){const n=Math.round(String(t.system||"").trim().length/4);n&&(u[t.id||t.specs[0]?.name||"group"]=n)}return{specs:o,system:M,systemParts:u,remoteTools:h,traits:c,serialTools:m,reach:d,hiddenVia:f,async execute(t,n,e={}){const r=a.get(t);return r?r(t,n,e):JSON.stringify({error:`Unknown tool: ${t}`})}}}export{S as buildToolset};