@chatpanel/events 0.64.0 → 0.65.0

package/index.js

@@ -167,7 +167,18 @@ export {
   unfence, findJson, rewriteJson, repairJson, isNothing,
   coerce, parseStructured, createStructuredStream,
 } from './structured.js';
-export { explainMcpError, packageFromArgs } from './mcp-errors.js';
+export { explainMcpError, packageFromArgs, isStaleMcpSession } from './mcp-errors.js';
+// The tool round — what a tool does, how a round runs, what a result costs, how a tool is
+// found, and a workflow written down once (see docs/ROADMAP "the tool round" in chatpanel).
+export { toolTraits, bareToolName, canRunConcurrently, isCacheable, needsConfirmation, traitsIndex } from './tool-traits.js';
+export { planToolRound, runToolRound } from './tool-round.js';
+export {
+  createResultStore, shieldToolResult, runResultQuery, withResultShield, describeShape, compactValue,
+  resultToolSpec, RESULT_TOOL_NAME, DEFAULT_SHIELD, DEFAULT_STORE,
+} from './tool-result.js';
+export { findTools, findToolsResult, findActionArgs, oneLiner, overlapRank, FIND_ACTION } from './tool-discovery.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';
 export { createKernel, meetDecisions, KernelError, REQUIRED_PLUGINS, ALLOW_ALL } from './kernel.js';
 export { replay, formatReport, parseJsonl, toJsonl } from './harness.js';

package/mcp-errors.js

@@ -85,3 +85,22 @@ export function packageFromArgs(args = []) {
   }
   return '';
 }
+
+// A session the server no longer recognises — the OTHER half of the respawn story.
+//
+// The bridge replays `initialize` for a stdio server it respawned, but an HTTP server that
+// restarted has forgotten the `Mcp-Session-Id` the client still presents (the spec says
+// 404), and a stdio server the bridge did NOT restart — a crash between two bridge
+// restarts, say — answers "not initialized". Both mean the same thing to a client holding a
+// connection it believes is live: handshake again, then retry once. Recognised here so the
+// extension, the gateway and the bridge agree on what counts as stale, and no client
+// treats "session not found" as "the tool is broken".
+const STALE_SESSION_RE = /\b(session (not found|expired|invalid|unknown)|invalid session|no (valid )?session|not initialized|before initialization|initialization was (not )?complete|-32002)\b/i;
+
+export function isStaleMcpSession(text, { status } = {}) {
+  if (status === 404) return true;
+  const t = String(text || '');
+  if (!t) return false;
+  if (/\bHTTP 404\b/.test(t)) return true;
+  return STALE_SESSION_RE.test(t);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/events",
-  "version": "0.64.0",
+  "version": "0.65.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",
@@ -51,6 +51,7 @@
     "./promotion.js": "./promotion.js",
     "./queue.js": "./queue.js",
     "./reach.js": "./reach.js",
+    "./recipe.js": "./recipe.js",
     "./redaction-tokens.js": "./redaction-tokens.js",
     "./ref.js": "./ref.js",
     "./registry.js": "./registry.js",
@@ -78,8 +79,13 @@
     "./text-search.js": "./text-search.js",
     "./theme.js": "./theme.js",
     "./titles.js": "./titles.js",
+    "./tool-discovery.js": "./tool-discovery.js",
     "./tool-groups.js": "./tool-groups.js",
     "./tool-need.js": "./tool-need.js",
+    "./tool-result.js": "./tool-result.js",
+    "./tool-round.js": "./tool-round.js",
+    "./tool-schema.js": "./tool-schema.js",
+    "./tool-traits.js": "./tool-traits.js",
     "./trajectory.js": "./trajectory.js",
     "./upcast.js": "./upcast.js",
     "./vault.js": "./vault.js",
@@ -137,6 +143,7 @@
     "promotion.js",
     "queue.js",
     "reach.js",
+    "recipe.js",
     "redaction-tokens.js",
     "ref.js",
     "registry.js",
@@ -163,8 +170,13 @@
     "text-search.js",
     "theme.js",
     "titles.js",
+    "tool-discovery.js",
     "tool-groups.js",
     "tool-need.js",
+    "tool-result.js",
+    "tool-round.js",
+    "tool-schema.js",
+    "tool-traits.js",
     "trajectory.js",
     "upcast.js",
     "vault.js",

package/recipe.js

@@ -0,0 +1,264 @@
+// Recipes — a multi-step tool workflow written down once and run by name, with no model
+// in the loop.
+//
+// Skills are prompts: they tell a model what to do and the model decides which tools to
+// call. A recipe is the other thing — the DECISION already made, as data: "open_bug" is
+// `create_issue` with `labels: ["bug"]` baked in and `title`/`body` filled from the
+// caller; "triage_pair" fetches two issues at once; "search_then_read" searches, then
+// reads the first hit. It runs identically every time, from any client, with no tokens
+// spent deciding, and it is the shape the harness spine calls class R: declarative,
+// permissioned, never agent-written code. Amendment A2 asked for automations to be
+// authored conversationally and approved before they run; this is what gets approved.
+//
+// Four modes, matching the primitives a round already has: `call` (one tool),
+// `parallel` (independent calls, run through tool-round.js so reads overlap), `batch` (one
+// tool, many argument sets) and `pipeline` (each step may map values out of the previous
+// step's result with `inputMapping`: "$text" for its text, "$json" for it parsed,
+// "$json.items.0.key" for a path inside).
+//
+// Two properties are load-bearing:
+//   • DRY RUN before side effects — `dryRunRecipe` resolves every parameter and names
+//     every unknown tool, missing required field and destructive call without executing
+//     anything. It is the propose step of propose → approve → activate.
+//   • PARTIAL FAILURE IS RECOVERABLE — a parallel/batch run returns every sibling's result
+//     plus `failedIndexes`; a pipeline stops at the failing step and returns the outputs
+//     of the steps before it, plus which mappings resolved and which did not. Nothing is
+//     retried blindly, and nothing that succeeded is lost.
+//
+// Pure. Execution, tool specs and traits are injected; nothing here knows a model, a
+// window, or where recipes are stored.
+
+import { runToolRound } from './tool-round.js';
+import { toolTraits, needsConfirmation } from './tool-traits.js';
+
+export const RECIPE_MODES = Object.freeze(['call', 'parallel', 'batch', 'pipeline']);
+
+export class RecipeError extends Error {
+  constructor(code, message) { super(message); this.name = 'RecipeError'; this.code = code; }
+}
+
+const isRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const isParamRef = (v) => isRecord(v) && typeof v.$param === 'string' && Object.keys(v).every((k) => k === '$param' || k === 'default');
+
+/** Every `{ "$param": name }` a recipe reads, in first-seen order. */
+export function recipeParams(recipe) {
+  const names = [];
+  const seen = new Set();
+  const walk = (v) => {
+    if (isParamRef(v)) { if (!seen.has(v.$param)) { seen.add(v.$param); names.push({ name: v.$param, required: !('default' in v), default: v.default }); } return; }
+    if (Array.isArray(v)) v.forEach(walk);
+    else if (isRecord(v)) Object.values(v).forEach(walk);
+  };
+  walk(recipe);
+  return names;
+}
+
+/** Structural validity — the errors a person authoring one needs to see. */
+export function validateRecipe(recipe) {
+  const errors = [];
+  if (!isRecord(recipe)) return { ok: false, errors: ['recipe must be an object'] };
+  if (!recipe.name || typeof recipe.name !== 'string' || !/^[a-z][a-z0-9_-]{0,63}$/i.test(recipe.name)) errors.push('name: a short identifier (letters, digits, _ -) is required');
+  if (!RECIPE_MODES.includes(recipe.mode)) errors.push(`mode: one of ${RECIPE_MODES.join(', ')}`);
+  const call = (c, where) => {
+    if (!isRecord(c)) { errors.push(`${where}: must be an object`); return; }
+    if (!c.tool || typeof c.tool !== 'string') errors.push(`${where}.tool: required`);
+    if (c.arguments !== undefined && !isRecord(c.arguments)) errors.push(`${where}.arguments: must be an object`);
+    if (c.inputMapping !== undefined && (!isRecord(c.inputMapping) || Object.values(c.inputMapping).some((m) => typeof m !== 'string' || !/^\$(text|json)(\.[^.\s]+)*$/.test(m)))) {
+      errors.push(`${where}.inputMapping: values must be "$text", "$json" or "$json.<path>"`);
+    }
+    if (c.onMappingMissing !== undefined && !['continue', 'fail'].includes(c.onMappingMissing)) errors.push(`${where}.onMappingMissing: "continue" or "fail"`);
+  };
+  switch (recipe.mode) {
+    case 'call': call(recipe, 'recipe'); break;
+    case 'parallel':
+      if (!Array.isArray(recipe.calls) || !recipe.calls.length) errors.push('calls: a non-empty array');
+      else recipe.calls.forEach((c, i) => call(c, `calls[${i}]`));
+      break;
+    case 'batch':
+      if (!recipe.tool || typeof recipe.tool !== 'string') errors.push('tool: required');
+      if (!Array.isArray(recipe.items) || !recipe.items.length) errors.push('items: a non-empty array');
+      else recipe.items.forEach((it, i) => { if (!isRecord(it) || !isRecord(it.arguments)) errors.push(`items[${i}].arguments: must be an object`); });
+      break;
+    case 'pipeline':
+      if (!Array.isArray(recipe.steps) || !recipe.steps.length) errors.push('steps: a non-empty array');
+      else {
+        recipe.steps.forEach((s, i) => call(s, `steps[${i}]`));
+        if (isRecord(recipe.steps[0]) && recipe.steps[0].inputMapping) errors.push('steps[0].inputMapping: the first step has no previous result');
+      }
+      break;
+    default: break;
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Substitute parameters. Returns the plan — a list of concrete calls in the recipe's mode
+ * — and the names of any parameters missing without a default. A missing parameter is
+ * reported, not thrown: the caller decides whether to ask for it or fail.
+ */
+export function expandRecipe(recipe, params = {}) {
+  const v = validateRecipe(recipe);
+  if (!v.ok) return { ok: false, errors: v.errors, missing: [], plan: null };
+  const missing = new Set();
+  const fill = (x) => {
+    if (isParamRef(x)) {
+      if (Object.prototype.hasOwnProperty.call(params, x.$param) && params[x.$param] !== undefined) return params[x.$param];
+      if ('default' in x) return x.default;
+      missing.add(x.$param);
+      return undefined;
+    }
+    if (Array.isArray(x)) return x.map(fill);
+    if (isRecord(x)) {
+      const out = {};
+      for (const [k, val] of Object.entries(x)) { const f = fill(val); if (f !== undefined) out[k] = f; }
+      return out;
+    }
+    return x;
+  };
+  const one = (c) => ({ tool: c.tool, arguments: fill(c.arguments || {}), ...(c.inputMapping ? { inputMapping: { ...c.inputMapping } } : {}), ...(c.onMappingMissing ? { onMappingMissing: c.onMappingMissing } : {}) });
+  let calls;
+  switch (recipe.mode) {
+    case 'call': calls = [one(recipe)]; break;
+    case 'parallel': calls = recipe.calls.map(one); break;
+    case 'batch': calls = recipe.items.map((it) => ({ tool: recipe.tool, arguments: fill(it.arguments) })); break;
+    case 'pipeline': calls = recipe.steps.map(one); break;
+    default: calls = [];
+  }
+  return { ok: missing.size === 0, errors: [], missing: [...missing], plan: { name: recipe.name, mode: recipe.mode, calls } };
+}
+
+// ── mapping ──────────────────────────────────────────────────────────────────────────
+
+const textOf = (r) => (typeof r === 'string' ? r : r && typeof r === 'object' && typeof r.text === 'string' ? r.text : r == null ? '' : JSON.stringify(r));
+
+function parseJson(text) {
+  try { return { ok: true, value: JSON.parse(text) }; } catch { return { ok: false }; }
+}
+
+/**
+ * Resolve one step's `inputMapping` against the previous result.
+ * @returns `{ arguments, mapped: { [arg]: value }, skipped: [{ arg, expr, reason }] }`
+ */
+export function mapInput(previous, mapping = {}, base = {}) {
+  const args = { ...base };
+  const mapped = {};
+  const skipped = [];
+  const text = textOf(previous);
+  let json;
+  for (const [arg, expr] of Object.entries(mapping || {})) {
+    if (expr === '$text') { args[arg] = text; mapped[arg] = text; continue; }
+    if (!expr.startsWith('$json')) { skipped.push({ arg, expr, reason: 'unknown expression' }); continue; }
+    if (json === undefined) json = parseJson(text);
+    if (!json.ok) { skipped.push({ arg, expr, reason: 'previous result is not JSON' }); continue; }
+    let cur = json.value;
+    const path = expr.slice(5).split('.').filter(Boolean);
+    let found = true;
+    for (const seg of path) {
+      if (Array.isArray(cur) && /^\d+$/.test(seg)) cur = cur[Number(seg)];
+      else if (isRecord(cur) && Object.prototype.hasOwnProperty.call(cur, seg)) cur = cur[seg];
+      else { found = false; break; }
+    }
+    if (!found || cur === undefined) { skipped.push({ arg, expr, reason: 'path not found in previous result' }); continue; }
+    args[arg] = cur;
+    mapped[arg] = cur;
+  }
+  return { arguments: args, mapped, skipped };
+}
+
+// ── dry run ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Everything a person should know before approving: unknown tools, missing required
+ * fields, destructive calls, and which arguments a pipeline will only learn at run time.
+ *
+ * @param specs    the tool specs the runtime will execute against (for existence and
+ *                 required fields); omit to skip those checks
+ * @param traitsOf `(tool) => traits`; defaults to toolTraits on the spec or name
+ */
+export function dryRunRecipe(recipe, params = {}, { specs = null, traitsOf = null } = {}) {
+  const ex = expandRecipe(recipe, params);
+  if (!ex.plan) return { ok: false, errors: ex.errors, missing: ex.missing, calls: [], warnings: [], destructive: [] };
+  const byName = specs ? new Map(specs.filter((s) => s?.name).map((s) => [s.name, s])) : null;
+  const traits = traitsOf || ((tool) => toolTraits(byName?.get(tool) || tool));
+  const warnings = [];
+  const destructive = [];
+  const calls = ex.plan.calls.map((c, i) => {
+    const spec = byName?.get(c.tool);
+    const known = byName ? !!spec : null;
+    const t = traits(c.tool);
+    const mappedLater = new Set(Object.keys(c.inputMapping || {}));
+    const required = Array.isArray(spec?.parameters?.required) ? spec.parameters.required : Array.isArray(spec?.inputSchema?.required) ? spec.inputSchema.required : [];
+    const missingRequired = required.filter((k) => c.arguments[k] === undefined && !mappedLater.has(k));
+    const row = { index: i, tool: c.tool, arguments: c.arguments, known, traits: t, missingRequired, mappedLater: [...mappedLater] };
+    if (known === false) warnings.push({ index: i, code: 'unknown_tool', message: `No tool named "${c.tool}" is available.` });
+    if (missingRequired.length) warnings.push({ index: i, code: 'missing_required', message: `"${c.tool}" needs ${missingRequired.join(', ')}.` });
+    if (needsConfirmation(t)) { destructive.push(i); warnings.push({ index: i, code: 'destructive', message: `"${c.tool}" is destructive.` }); }
+    if (ex.plan.mode === 'pipeline' && i > 0 && !mappedLater.size) warnings.push({ index: i, code: 'no_mapping', message: `steps[${i}] uses nothing from the previous step; was that intended?` });
+    return row;
+  });
+  const blocking = ex.missing.length > 0 || warnings.some((w) => w.code === 'unknown_tool' || w.code === 'missing_required');
+  return { ok: !blocking, errors: [], missing: ex.missing, plan: ex.plan, calls, warnings, destructive };
+}
+
+// ── run ──────────────────────────────────────────────────────────────────────────────
+
+const defaultIsError = (r) => {
+  if (r == null) return false;
+  if (typeof r === 'string') return /^error:/i.test(r) || /^\{\s*"error"/.test(r);
+  return typeof r === 'object' && (r.error != null || r.isError === true);
+};
+
+/**
+ * Run an expanded plan. `execute(tool, arguments, meta)` is the host's toolset executor —
+ * every guard, redaction and confirmation it wraps applies unchanged, because a recipe is
+ * a way of composing calls, never a way around them.
+ */
+export async function runPlan(plan, { execute, traitsOf, concurrent, isError = defaultIsError, onStart, onDone } = {}) {
+  if (typeof execute !== 'function') throw new RecipeError('BAD_RUN', 'execute required');
+  if (!plan || !Array.isArray(plan.calls)) throw new RecipeError('BAD_PLAN', 'plan.calls required');
+  const meta = { recipe: plan.name, mode: plan.mode };
+
+  if (plan.mode === 'pipeline') {
+    const steps = [];
+    let previous;
+    for (let i = 0; i < plan.calls.length; i += 1) {
+      const c = plan.calls[i];
+      let args = c.arguments;
+      let mapped = {};
+      let skipped = [];
+      if (i > 0 && c.inputMapping) {
+        const m = mapInput(previous, c.inputMapping, c.arguments);
+        args = m.arguments; mapped = m.mapped; skipped = m.skipped;
+        if (skipped.length && c.onMappingMissing === 'fail') {
+          steps.push({ index: i, tool: c.tool, arguments: args, mappedArguments: mapped, skippedMappings: skipped, result: null, status: 'skipped' });
+          return { status: 'failed', failedStep: i, reason: 'mapping_missing', steps, finalResult: null };
+        }
+      }
+      onStart?.({ name: c.tool, input: args }, i);
+      let result;
+      try { result = await execute(c.tool, args, { ...meta, step: i }); } catch (e) { result = { error: `Tool ${c.tool} failed: ${e?.message || e}` }; }
+      onDone?.({ name: c.tool, input: args }, i, result);
+      const failed = isError(result);
+      steps.push({ index: i, tool: c.tool, arguments: args, mappedArguments: mapped, skippedMappings: skipped, result, status: failed ? 'failed' : 'ok' });
+      if (failed) return { status: 'failed', failedStep: i, reason: 'tool_error', steps, finalResult: null };
+      previous = result;
+    }
+    return { status: 'completed', steps, finalResult: previous };
+  }
+
+  const calls = plan.calls.map((c) => ({ name: c.tool, input: c.arguments }));
+  const round = await runToolRound(calls, {
+    execute: (call, i) => execute(call.name, call.input, { ...meta, index: i }),
+    traitsOf: traitsOf ? (c) => traitsOf(c.name) : undefined,
+    concurrent, isError, onStart, onDone,
+  });
+  return { status: round.status, succeeded: round.succeeded, failed: round.failed, failedIndexes: round.failedIndexes, results: round.results, coalesced: round.coalesced };
+}
+
+/** Expand, then run. Missing parameters fail before anything executes. */
+export async function runRecipe(recipe, params, options) {
+  const ex = expandRecipe(recipe, params);
+  if (!ex.plan) throw new RecipeError('INVALID', ex.errors.join('; '));
+  if (!ex.ok) throw new RecipeError('MISSING_PARAMS', `missing: ${ex.missing.join(', ')}`);
+  return runPlan(ex.plan, options);
+}

package/tool-discovery.js

@@ -0,0 +1,87 @@
+// `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.` },
+  };
+}

package/tool-result.js

@@ -0,0 +1,438 @@
+// The response shield — a tool result too big to read is stored, previewed and paged,
+// instead of being poured into the model's context whole.
+//
+// Every tool result used to go to the model in full. The only cap anywhere was the
+// 4,000-character slice the ACTIVITY LOG shows a person — the model got everything. One
+// `search_issues` returning three hundred kilobytes of JSON therefore cost the whole turn:
+// the request blew the context window, or it fit and every later turn re-read it.
+//
+// What is borrowed here is not truncation, which is easy, but the shape of the truncated
+// reply: it TEACHES the model how to get the rest. A preview goes back, plus what the
+// full result looks like (an array of 240 objects with these keys; 128,400 characters of
+// text) and a ready-to-send `get_result` call that pages, filters or projects the stored
+// copy. A cut with nothing after it is a result the model cannot recover from; a cut with
+// a retrieval note is one more tool call away from whatever it needed.
+//
+// Shared because the extension, the desktop and the gateway each feed tool results to a
+// model, and three limits would be three different answers to "what did the model see".
+// Pure: no storage binding, no clock, no id generator of its own — the host injects
+// `now`/`newId` (matching loop.js) and keeps the store wherever it keeps its turn state.
+
+export const RESULT_TOOL_NAME = 'get_result';
+
+export const DEFAULT_SHIELD = Object.freeze({
+  // Characters of result text a model receives before the shield engages. Above the
+  // page-read default (40,000) on purpose: a page the user asked to summarise must arrive
+  // whole, and the shield is for the results nobody asked to be that large.
+  maxChars: 48_000,
+  maxArrayItems: 50,
+  maxStringChars: 4_000,
+  maxKeys: 60,
+  maxDepth: 8,
+});
+
+export const DEFAULT_STORE = Object.freeze({
+  maxEntries: 100,
+  // Bytes across all stored results; oldest evicted first. A handful of very large
+  // results must not grow memory without bound.
+  maxBytes: 64 * 1024 * 1024,
+});
+
+const PAGE_LIMIT_DEFAULT = 50;
+const PAGE_LIMIT_MAX = 200;
+const TEXT_LIMIT_DEFAULT = 8_000;
+const TEXT_LIMIT_MAX = 32_000;
+const SEARCH_MATCHES_MAX = 20;
+const SEARCH_WINDOW = 160;
+
+const defaultId = () => `r_${Math.random().toString(36).slice(2, 8)}${Date.now().toString(36).slice(-3)}`;
+
+const isRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+function byteLength(value) {
+  const s = typeof value === 'string' ? value : JSON.stringify(value);
+  return s == null ? 0 : s.length;
+}
+
+/** Strict JSON, but only a container counts — a bare number or string is not "structured". */
+function parseStructured(text) {
+  const t = String(text || '').trim();
+  if (!t || (t[0] !== '{' && t[0] !== '[')) return undefined;
+  try {
+    const v = JSON.parse(t);
+    return v && typeof v === 'object' ? v : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The store: full results, keyed by ref, owned by whoever produced them.
+ *
+ * `owner` scopes retrieval — a gateway serving several sessions must not let one page
+ * another's results. `undefined` means unowned (a single-user client) and is readable
+ * by anyone; a store that receives owners must be asked with owners.
+ */
+export function createResultStore({ maxEntries = DEFAULT_STORE.maxEntries, maxBytes = DEFAULT_STORE.maxBytes, now = () => Date.now(), newId = defaultId } = {}) {
+  const entries = new Map(); // ref -> { ref, tool, owner, createdAt, bytes, value }
+  let bytes = 0;
+
+  const drop = (ref) => {
+    const e = entries.get(ref);
+    if (!e) return false;
+    entries.delete(ref);
+    bytes -= e.bytes;
+    return true;
+  };
+  const evict = () => {
+    while (entries.size && (entries.size > maxEntries || bytes > maxBytes)) {
+      drop(entries.keys().next().value);
+    }
+  };
+
+  return {
+    put({ tool = '', value, owner } = {}) {
+      let ref = newId();
+      while (entries.has(ref)) ref = newId();
+      const e = { ref, tool: String(tool || ''), owner, createdAt: now(), bytes: byteLength(value), value };
+      entries.set(ref, e);
+      bytes += e.bytes;
+      evict();
+      return ref;
+    },
+    get(ref, owner) {
+      const e = entries.get(String(ref || ''));
+      if (!e) return null;
+      if (e.owner !== undefined && e.owner !== owner) return null;
+      return e;
+    },
+    drop,
+    clear() { entries.clear(); bytes = 0; },
+    get size() { return entries.size; },
+    get bytes() { return bytes; },
+  };
+}
+
+// ── shape ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * What a stored value LOOKS like, in a sentence's worth of facts — enough for the model to
+ * choose between paging, searching, projecting and descending without seeing it all.
+ */
+export function describeShape(value, { maxKeys = 20, maxPaths = 8 } = {}) {
+  if (typeof value === 'string') return { kind: 'text', chars: value.length };
+  if (Array.isArray(value)) {
+    const keys = new Set();
+    let objects = 0;
+    for (const item of value.slice(0, 50)) {
+      if (!isRecord(item)) continue;
+      objects += 1;
+      for (const k of Object.keys(item)) keys.add(k);
+    }
+    const itemKind = objects === Math.min(value.length, 50) && value.length ? 'object' : value.length ? typeof value[0] : 'empty';
+    return { kind: 'array', items: value.length, itemKind, keys: [...keys].slice(0, maxKeys), moreKeys: Math.max(0, keys.size - maxKeys) };
+  }
+  if (isRecord(value)) {
+    const keys = Object.keys(value);
+    const arrays = [];
+    const walk = (v, path, depth) => {
+      if (arrays.length >= maxPaths || depth > 3) return;
+      if (Array.isArray(v)) { arrays.push({ path, items: v.length }); return; }
+      if (!isRecord(v)) return;
+      for (const k of Object.keys(v)) walk(v[k], path ? `${path}.${k}` : k, depth + 1);
+    };
+    walk(value, '', 0);
+    return { kind: 'object', keys: keys.slice(0, maxKeys), moreKeys: Math.max(0, keys.length - maxKeys), arrays };
+  }
+  return { kind: typeof value };
+}
+
+function shapeSentence(shape) {
+  if (!shape) return '';
+  if (shape.kind === 'text') return `${shape.chars.toLocaleString('en-US')} characters of text`;
+  if (shape.kind === 'array') {
+    const keys = shape.keys?.length ? ` with keys ${shape.keys.join(', ')}${shape.moreKeys ? ` (+${shape.moreKeys} more)` : ''}` : '';
+    return `an array of ${shape.items} ${shape.itemKind === 'object' ? 'objects' : 'items'}${keys}`;
+  }
+  if (shape.kind === 'object') {
+    const keys = shape.keys?.length ? `keys ${shape.keys.join(', ')}${shape.moreKeys ? ` (+${shape.moreKeys} more)` : ''}` : 'no keys';
+    const arrays = shape.arrays?.length ? `; arrays at ${shape.arrays.map((a) => `${a.path} (${a.items})`).join(', ')}` : '';
+    return `an object with ${keys}${arrays}`;
+  }
+  return `a ${shape.kind}`;
+}
+
+// ── compaction ───────────────────────────────────────────────────────────────────────
+
+/** A structurally-faithful preview: same nesting, fewer items, shorter strings. */
+export function compactValue(value, opts = {}) {
+  const o = { ...DEFAULT_SHIELD, ...opts };
+  let truncated = false;
+  const walk = (v, depth) => {
+    if (typeof v === 'string') {
+      if (v.length <= o.maxStringChars) return v;
+      truncated = true;
+      return `${v.slice(0, o.maxStringChars)}…[+${v.length - o.maxStringChars} chars]`;
+    }
+    if (Array.isArray(v)) {
+      if (depth >= o.maxDepth) { truncated = true; return `[array of ${v.length}]`; }
+      const head = v.slice(0, o.maxArrayItems).map((x) => walk(x, depth + 1));
+      if (v.length > o.maxArrayItems) { truncated = true; head.push(`…[+${v.length - o.maxArrayItems} more items]`); }
+      return head;
+    }
+    if (isRecord(v)) {
+      if (depth >= o.maxDepth) { truncated = true; return '{…}'; }
+      const keys = Object.keys(v);
+      const out = {};
+      for (const k of keys.slice(0, o.maxKeys)) out[k] = walk(v[k], depth + 1);
+      if (keys.length > o.maxKeys) { truncated = true; out['…'] = `+${keys.length - o.maxKeys} more keys`; }
+      return out;
+    }
+    return v;
+  };
+  const out = walk(value, 0);
+  return { value: out, truncated };
+}
+
+// ── the shield ───────────────────────────────────────────────────────────────────────
+
+function retrievalNote({ ref, shape, totalChars, shownChars, preview }) {
+  const n = (x) => Number(x || 0).toLocaleString('en-US');
+  const parts = [`[ChatPanel result shield: this result is ${n(totalChars)} characters; showing a ${n(shownChars)}-character preview.`];
+  parts.push(`Full result: ${shapeSentence(shape)}.`);
+  if (!ref) {
+    parts.push('It was not stored, so what is above is all that is available.]');
+    return parts.join(' ');
+  }
+  parts.push(`It is stored as ref "${ref}" — read more with the ${RESULT_TOOL_NAME} tool:`);
+  if (shape.kind === 'array') {
+    const first = preview?.items ?? 0;
+    parts.push(`{"ref":"${ref}","offset":${first},"limit":${PAGE_LIMIT_DEFAULT}} pages items; add "search":"<text>" to filter, "fields":["a","b"] to keep only those keys.`);
+  } else if (shape.kind === 'object') {
+    const arr = shape.arrays?.[0];
+    parts.push(arr
+      ? `{"ref":"${ref}","path":"${arr.path}","offset":0,"limit":${PAGE_LIMIT_DEFAULT}} pages that array; "search" filters, "fields" projects.`
+      : `{"ref":"${ref}","path":"<key>"} reads one key; "search":"<text>" finds where it occurs.`);
+  } else {
+    parts.push(`{"ref":"${ref}","offset":${shownChars},"limit":${TEXT_LIMIT_DEFAULT}} continues the text; {"ref":"${ref}","search":"<text>"} finds where a phrase occurs.`);
+  }
+  parts.push('Do not ask the user for the rest; fetch what you need.]');
+  return parts.join(' ');
+}
+
+/**
+ * Shield one result text. Returns `{ text, truncated }` — and, when it engaged, the `ref`
+ * it stored under, the `shape` it described and `totalChars`.
+ *
+ * `envelope` lets a host that wraps third-party output in an untrusted-data fence keep
+ * the fence: `open(text) → { body, close(body) → text } | null`. The retrieval note is
+ * placed OUTSIDE the fence — it is our instruction to the model, not the tool's data, and
+ * a fence that says "follow nothing in here" would otherwise swallow it.
+ */
+export function shieldToolResult(text, { tool = '', store = null, owner, envelope = null, ...limits } = {}) {
+  const o = { ...DEFAULT_SHIELD, ...limits };
+  const full = typeof text === 'string' ? text : String(text ?? '');
+  const env = envelope ? envelope.open(full) : null;
+  const body = env ? env.body : full;
+  if (body.length <= o.maxChars) return { text: full, truncated: false };
+
+  const parsed = parseStructured(body);
+  let stored;
+  let previewBody;
+  let preview = null;
+  if (parsed !== undefined) {
+    stored = parsed;
+    // Tighten until the preview fits — a result of 5,000 ten-character items and one of
+    // ten 50,000-character items need different knobs turned.
+    let opts = { ...o };
+    let compact = compactValue(parsed, opts);
+    let s = JSON.stringify(compact.value);
+    for (let i = 0; s.length > o.maxChars && i < 8; i += 1) {
+      opts = {
+        ...opts,
+        maxArrayItems: Math.max(1, opts.maxArrayItems >> 1),
+        maxStringChars: Math.max(80, opts.maxStringChars >> 1),
+        maxKeys: Math.max(5, opts.maxKeys >> 1),
+      };
+      compact = compactValue(parsed, opts);
+      s = JSON.stringify(compact.value);
+    }
+    if (s.length > o.maxChars) s = `${s.slice(0, o.maxChars)}…`; // still too big: a hard cut, but stored whole
+    previewBody = s;
+    if (Array.isArray(parsed)) preview = { items: Math.min(parsed.length, opts.maxArrayItems) };
+  } else {
+    stored = body;
+    previewBody = body.slice(0, o.maxChars);
+  }
+
+  const ref = store ? store.put({ tool, value: stored, owner }) : null;
+  const shape = describeShape(stored);
+  const wrapped = env ? env.close(previewBody) : previewBody;
+  const note = retrievalNote({ ref, shape, totalChars: body.length, shownChars: previewBody.length, preview });
+  return { text: `${wrapped}\n${note}`, truncated: true, ref, shape, totalChars: body.length };
+}
+
+// ── get_result ───────────────────────────────────────────────────────────────────────
+
+export function resultToolSpec() {
+  return {
+    name: RESULT_TOOL_NAME,
+    description:
+      'Read more of a tool result that was shielded (truncated) — the result named this tool and '
+      + 'gave a ref. Pages arrays by item and text by character; `search` filters, `fields` keeps '
+      + 'only those keys, `path` descends into a nested value (dot path, e.g. "data.items").',
+    parameters: {
+      type: 'object',
+      properties: {
+        ref: { type: 'string', description: 'The ref from the shielded result.' },
+        path: { type: 'string', description: 'Dot path inside the stored result.' },
+        offset: { type: 'integer', minimum: 0, description: 'First item (arrays) or character (text). Default 0.' },
+        limit: { type: 'integer', minimum: 1, description: `Items (default ${PAGE_LIMIT_DEFAULT}, max ${PAGE_LIMIT_MAX}) or characters (default ${TEXT_LIMIT_DEFAULT}, max ${TEXT_LIMIT_MAX}).` },
+        fields: { type: 'array', items: { type: 'string' }, description: 'Keep only these keys of each object.' },
+        search: { type: 'string', description: 'Case-insensitive text to filter items by, or to locate in text.' },
+      },
+      required: ['ref'],
+    },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+  };
+}
+
+function descend(value, path) {
+  const segs = String(path || '').split('.').map((s) => s.trim()).filter(Boolean);
+  let cur = value;
+  const walked = [];
+  for (const seg of segs) {
+    if (Array.isArray(cur) && /^\d+$/.test(seg)) cur = cur[Number(seg)];
+    else if (isRecord(cur) && Object.prototype.hasOwnProperty.call(cur, seg)) cur = cur[seg];
+    else return { error: `No "${seg}" at "${walked.join('.') || '(root)'}"`, available: isRecord(cur) ? Object.keys(cur).slice(0, 40) : Array.isArray(cur) ? `array of ${cur.length}` : typeof cur };
+    walked.push(seg);
+  }
+  return { value: cur };
+}
+
+const clampInt = (v, def, min, max) => {
+  const n = Number.parseInt(v, 10);
+  if (!Number.isFinite(n)) return def;
+  return Math.min(max, Math.max(min, n));
+};
+
+/**
+ * Answer one `get_result` call. Returns the JSON text the model receives — including
+ * errors, which name what exists so the model can correct itself without another call.
+ */
+export function runResultQuery(store, args = {}, { owner, maxChars = DEFAULT_SHIELD.maxChars } = {}) {
+  const ref = String(args?.ref || '');
+  const entry = store ? store.get(ref, owner) : null;
+  if (!entry) {
+    return JSON.stringify({ error: `Unknown or expired ref "${ref}".`, hint: 'Refs come from a shielded result in this conversation and expire when newer results replace them; re-run the original tool if needed.' });
+  }
+  const located = args.path ? descend(entry.value, args.path) : { value: entry.value };
+  if (located.error) return JSON.stringify({ error: located.error, available: located.available, ref });
+  const target = located.value;
+  const search = args.search != null && String(args.search).trim() ? String(args.search).toLowerCase() : '';
+  const base = { ref, ...(args.path ? { path: args.path } : {}) };
+
+  if (Array.isArray(target)) {
+    let items = target;
+    if (search) items = items.filter((it) => JSON.stringify(it).toLowerCase().includes(search));
+    const fields = Array.isArray(args.fields) ? args.fields.map(String).filter(Boolean) : [];
+    const project = (it) => {
+      if (!fields.length || !isRecord(it)) return it;
+      const out = {};
+      for (const f of fields) if (Object.prototype.hasOwnProperty.call(it, f)) out[f] = it[f];
+      return out;
+    };
+    const offset = clampInt(args.offset, 0, 0, Number.MAX_SAFE_INTEGER);
+    let limit = clampInt(args.limit, PAGE_LIMIT_DEFAULT, 1, PAGE_LIMIT_MAX);
+    let page;
+    let text;
+    // A page that itself exceeds the budget shrinks until it fits — the shield's guarantee
+    // holds for its own pages too.
+    for (let i = 0; i < 8; i += 1) {
+      page = items.slice(offset, offset + limit).map((it) => compactValue(project(it), { maxArrayItems: 20, maxStringChars: 2000 }).value);
+      const next = offset + limit < items.length ? { offset: offset + limit, limit } : null;
+      text = JSON.stringify({ ...base, total: target.length, ...(search ? { matched: items.length, search: args.search } : {}), offset, limit, count: page.length, items: page, next });
+      if (text.length <= maxChars || limit === 1) break;
+      limit = Math.max(1, limit >> 1);
+    }
+    return text;
+  }
+
+  if (typeof target === 'string') {
+    if (search) {
+      const hay = target.toLowerCase();
+      const matches = [];
+      let from = 0;
+      while (matches.length < SEARCH_MATCHES_MAX) {
+        const at = hay.indexOf(search, from);
+        if (at < 0) break;
+        const start = Math.max(0, at - SEARCH_WINDOW);
+        const end = Math.min(target.length, at + search.length + SEARCH_WINDOW);
+        matches.push({ offset: at, excerpt: target.slice(start, end) });
+        from = at + search.length;
+      }
+      return JSON.stringify({ ...base, chars: target.length, search: args.search, matches, more: matches.length >= SEARCH_MATCHES_MAX });
+    }
+    const offset = clampInt(args.offset, 0, 0, target.length);
+    const limit = Math.min(clampInt(args.limit, TEXT_LIMIT_DEFAULT, 1, TEXT_LIMIT_MAX), Math.max(1, maxChars - 200));
+    const slice = target.slice(offset, offset + limit);
+    const next = offset + limit < target.length ? { offset: offset + limit, limit } : null;
+    return JSON.stringify({ ...base, chars: target.length, offset, limit, text: slice, next });
+  }
+
+  if (isRecord(target)) {
+    const shape = describeShape(target);
+    const compact = compactValue(target, { maxArrayItems: 10, maxStringChars: 1000, maxKeys: 40 });
+    let text = JSON.stringify({ ...base, shape, value: compact.value, hint: shape.arrays?.length ? `Use "path" to page an array, e.g. "${shape.arrays[0].path}".` : 'Use "path" to read one key.' });
+    if (text.length > maxChars) text = JSON.stringify({ ...base, shape, hint: 'Too large to show whole; use "path" to descend.' });
+    return text;
+  }
+
+  return JSON.stringify({ ...base, value: target });
+}
+
+// ── the wrapper ──────────────────────────────────────────────────────────────────────
+
+/**
+ * Wrap a toolset `{ specs, execute, … }` so every result passes the shield and `get_result`
+ * exists to page what it stored. Everything else on the toolset is kept as-is.
+ *
+ * @param exempt   `(name) => boolean` — tools whose results are never shielded (a host
+ *                 that already sizes a result itself).
+ * @param textOf   how to read a result's text; `setText` how to write it back. Defaults fit
+ *                 the `string | { text, … }` executor contract.
+ */
+export function withResultShield(toolset, { store, owner, envelope = null, exempt = () => false, limits = {}, textOf = defaultTextOf, setText = defaultSetText } = {}) {
+  if (!toolset || typeof toolset.execute !== 'function') return toolset;
+  const spec = resultToolSpec();
+  const specs = [...(toolset.specs || []).filter((s) => s?.name !== RESULT_TOOL_NAME), spec];
+  const base = toolset.execute.bind(toolset);
+  const shielded = new Map(); // ref -> tool, for the host's activity log
+  return {
+    ...toolset,
+    specs,
+    shieldStore: store,
+    async execute(name, input, meta) {
+      if (name === RESULT_TOOL_NAME) return runResultQuery(store, input || {}, { owner, maxChars: limits.maxChars });
+      const raw = await base(name, input, meta);
+      if (exempt(name, input)) return raw;
+      const text = textOf(raw);
+      if (typeof text !== 'string') return raw;
+      const out = shieldToolResult(text, { tool: name, store, owner, envelope, ...limits });
+      if (!out.truncated) return raw;
+      if (out.ref) shielded.set(out.ref, name);
+      return setText(raw, out.text, out);
+    },
+  };
+}
+
+function defaultTextOf(result) {
+  if (typeof result === 'string') return result;
+  if (result && typeof result === 'object' && typeof result.text === 'string') return result.text;
+  return undefined;
+}
+
+function defaultSetText(result, text, shield) {
+  if (typeof result === 'string') return text;
+  return { ...result, text, shielded: { ref: shield.ref, totalChars: shield.totalChars } };
+}

package/tool-schema.js

@@ -0,0 +1,155 @@
+// Schema compression — a tool's contract, with the prose it does not need for the model to
+// call it correctly taken out.
+//
+// A connected server's tools arrive as full JSON schemas: a paragraph of description per
+// tool, a sentence per parameter, `title`s, `examples`, `$schema` and `$comment`. All of
+// it is re-sent on every turn the tool is armed, whether it is called or not. What the
+// model actually needs to make a correct call is small and structural — the names, the
+// types, which fields are required, the enum values, the bounds and defaults — plus enough
+// description to choose the tool and to disambiguate a parameter whose name does not say
+// what it holds.
+//
+// So `balanced` (the default) keeps everything structural, caps the tool description at a
+// sentence or two, and keeps a parameter's description only when it adds something the
+// name and type do not already say — `cursor: "opaque token from the previous page"` stays;
+// `issue_number: "The number of the issue"` goes. `aggressive` keeps parameter descriptions
+// only for the handful of names that are ambiguous everywhere (`ref`, `mode`, `sort`).
+// `off` is the schema as the server sent it.
+//
+// Pure and shared: the extension applies it as tools arrive from a server, the gateway
+// as tools pass through its relay, and the stats function makes the saving a number a
+// person can see rather than a claim.
+
+export const COMPRESSION_MODES = Object.freeze(['off', 'balanced', 'aggressive']);
+
+export const DEFAULT_COMPRESSION = Object.freeze({
+  mode: 'balanced',
+  maxDescriptionChars: 200,
+  maxParamDescriptionChars: 100,
+});
+
+// Names that mean something different on every server, so their description always earns
+// its place — a `ref` is a git ref here and a result ref there.
+const AMBIGUOUS = new Set([
+  'ref', 'mode', 'sort', 'order', 'direction', 'format', 'type', 'kind', 'state', 'status',
+  'cursor', 'after', 'before', 'anchor', 'sha', 'q', 'query', 'filter', 'scope', 'target',
+  'id', 'key', 'path', 'name', 'value', 'data', 'body', 'input', 'output', 'options',
+]);
+
+// Dropped outright: nothing a model needs to form a call.
+const DROP_KEYS = new Set(['$schema', '$comment', 'title', 'examples', 'example', 'deprecated', 'readOnly', 'writeOnly', '$id', 'contentMediaType', 'contentEncoding']);
+
+const collapse = (s) => String(s || '').replace(/\s+/g, ' ').trim();
+
+/** Cut at a sentence end when one falls comfortably inside the budget; else at a word. */
+export function trimDescription(text, max) {
+  const s = collapse(text);
+  if (!max || s.length <= max) return s;
+  const head = s.slice(0, max);
+  const sentence = Math.max(head.lastIndexOf('. '), head.lastIndexOf('! '), head.lastIndexOf('? '));
+  if (sentence >= max * 0.4) return head.slice(0, sentence + 1);
+  const word = head.lastIndexOf(' ');
+  return `${(word > max * 0.6 ? head.slice(0, word) : head).trimEnd()}…`;
+}
+
+const words = (s) => new Set(collapse(s).toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 2));
+
+/** Does a parameter description say anything its name and type do not? */
+const FILLER = new Set([
+  'the', 'this', 'that', 'for', 'and', 'with', 'optional', 'required', 'string', 'number', 'integer',
+  'boolean', 'array', 'object', 'value', 'values', 'field', 'parameter', 'param', 'name', 'identifier',
+  'text', 'list', 'given', 'specified', 'target', 'item', 'items', 'new', 'existing', 'which', 'whose',
+  'will', 'should', 'must', 'can', 'may', 'used', 'use', 'set', 'get', 'input', 'output',
+]);
+
+function informative(name, desc, node) {
+  const d = words(desc);
+  const own = [...words(name.replace(/([a-z])([A-Z])/g, '$1 $2'))];
+  for (const w of [...d]) {
+    if (FILLER.has(w)) { d.delete(w); continue; }
+    // `repo` covers "repository", `issue_number` covers "issues": a shared stem is the name.
+    if (own.some((n) => n.length >= 3 && (w.startsWith(n) || n.startsWith(w)))) d.delete(w);
+  }
+  if (node && typeof node.type === 'string') d.delete(node.type);
+  return d.size >= 2;
+}
+
+function compressNode(node, o, { name = '', depth = 0 } = {}) {
+  if (!node || typeof node !== 'object') return node;
+  if (Array.isArray(node)) return node.map((n) => compressNode(n, o, { depth: depth + 1 }));
+  const out = {};
+  for (const [k, v] of Object.entries(node)) {
+    if (DROP_KEYS.has(k)) continue;
+    if (k === 'description') {
+      if (depth === 0) { out[k] = trimDescription(v, o.maxDescriptionChars); continue; }
+      const keep = o.mode === 'aggressive'
+        ? AMBIGUOUS.has(name.toLowerCase())
+        : (AMBIGUOUS.has(name.toLowerCase()) || informative(name, v, node));
+      if (keep) {
+        const t = trimDescription(v, o.maxParamDescriptionChars);
+        if (t) out[k] = t;
+      }
+      continue;
+    }
+    if (k === 'properties' && v && typeof v === 'object') {
+      const props = {};
+      for (const [pn, pv] of Object.entries(v)) props[pn] = compressNode(pv, o, { name: pn, depth: depth + 1 });
+      out[k] = props;
+      continue;
+    }
+    if ((k === 'items' || k === 'additionalProperties' || k === 'not') && v && typeof v === 'object') {
+      out[k] = compressNode(v, o, { name, depth: depth + 1 });
+      continue;
+    }
+    if ((k === 'anyOf' || k === 'oneOf' || k === 'allOf') && Array.isArray(v)) {
+      out[k] = v.map((n) => compressNode(n, o, { name, depth: depth + 1 }));
+      continue;
+    }
+    if (k === '$defs' || k === 'definitions') {
+      const defs = {};
+      for (const [dn, dv] of Object.entries(v || {})) defs[dn] = compressNode(dv, o, { name: dn, depth: depth + 1 });
+      out[k] = defs;
+      continue;
+    }
+    out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Compress one spec. Works on the extension shape (`parameters`) and the MCP shape
+ * (`inputSchema`); everything else on the spec (name, annotations, …) is kept as-is.
+ */
+export function compressToolSpec(spec, opts = {}) {
+  const o = { ...DEFAULT_COMPRESSION, ...opts };
+  if (!spec || o.mode === 'off' || !COMPRESSION_MODES.includes(o.mode)) return spec;
+  const out = { ...spec };
+  if (typeof spec.description === 'string') {
+    const d = trimDescription(spec.description, o.maxDescriptionChars);
+    if (d) out.description = d; else delete out.description;
+  }
+  for (const k of ['parameters', 'inputSchema']) {
+    if (spec[k] && typeof spec[k] === 'object') out[k] = compressNode(spec[k], o, { depth: 1 });
+  }
+  return out;
+}
+
+export function compressToolSpecs(specs, opts) {
+  return (specs || []).map((s) => compressToolSpec(s, opts));
+}
+
+/** The saving, as a number: bytes of JSON before and after, per tool and in total. */
+export function compressionStats(specs, opts = {}) {
+  const list = specs || [];
+  const size = (v) => JSON.stringify(v ?? null).length;
+  let before = 0;
+  let after = 0;
+  const tools = [];
+  for (const s of list) {
+    const b = size(s);
+    const a = size(compressToolSpec(s, opts));
+    before += b; after += a;
+    tools.push({ name: s?.name, before: b, after: a });
+  }
+  return { mode: opts.mode || DEFAULT_COMPRESSION.mode, tools: list.length, before, after, saved: before - after, savedPercent: before ? Math.round(((before - after) / before) * 100) : 0, perTool: tools };
+}

package/tool-traits.js

@@ -0,0 +1,101 @@
+// 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;
+}