@chatpanel/events 0.102.0 → 0.104.0

package/tool-result.js

@@ -1,438 +1,2 @@
-// 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 } };
-}
+const k="get_result",j=Object.freeze({maxChars:48e3,maxArrayItems:50,maxStringChars:4e3,maxKeys:60,maxDepth:8}),I=Object.freeze({maxEntries:100,maxBytes:64*1024*1024}),A=50,N=200,C=8e3,T=32e3,_=20,E=160,D=()=>`r_${Math.random().toString(36).slice(2,8)}${Date.now().toString(36).slice(-3)}`,S=t=>t!==null&&typeof t=="object"&&!Array.isArray(t);function J(t){const e=typeof t=="string"?t:JSON.stringify(t);return e==null?0:e.length}function K(t){const e=String(t||"").trim();if(!(!e||e[0]!=="{"&&e[0]!=="["))try{const o=JSON.parse(e);return o&&typeof o=="object"?o:void 0}catch{return}}function G({maxEntries:t=I.maxEntries,maxBytes:e=I.maxBytes,now:o=()=>Date.now(),newId:n=D}={}){const i=new Map;let l=0;const r=f=>{const c=i.get(f);return c?(i.delete(f),l-=c.bytes,!0):!1},s=()=>{for(;i.size&&(i.size>t||l>e);)r(i.keys().next().value)};return{put({tool:f="",value:c,owner:a}={}){let h=n();for(;i.has(h);)h=n();const u={ref:h,tool:String(f||""),owner:a,createdAt:o(),bytes:J(c),value:c};return i.set(h,u),l+=u.bytes,s(),h},get(f,c){const a=i.get(String(f||""));return!a||a.owner!==void 0&&a.owner!==c?null:a},drop:r,clear(){i.clear(),l=0},get size(){return i.size},get bytes(){return l}}}function L(t,{maxKeys:e=20,maxPaths:o=8}={}){if(typeof t=="string")return{kind:"text",chars:t.length};if(Array.isArray(t)){const n=new Set;let i=0;for(const r of t.slice(0,50))if(S(r)){i+=1;for(const s of Object.keys(r))n.add(s)}const l=i===Math.min(t.length,50)&&t.length?"object":t.length?typeof t[0]:"empty";return{kind:"array",items:t.length,itemKind:l,keys:[...n].slice(0,e),moreKeys:Math.max(0,n.size-e)}}if(S(t)){const n=Object.keys(t),i=[],l=(r,s,f)=>{if(!(i.length>=o||f>3)){if(Array.isArray(r)){i.push({path:s,items:r.length});return}if(S(r))for(const c of Object.keys(r))l(r[c],s?`${s}.${c}`:c,f+1)}};return l(t,"",0),{kind:"object",keys:n.slice(0,e),moreKeys:Math.max(0,n.length-e),arrays:i}}return{kind:typeof t}}function R(t){if(!t)return"";if(t.kind==="text")return`${t.chars.toLocaleString("en-US")} characters of text`;if(t.kind==="array"){const e=t.keys?.length?` with keys ${t.keys.join(", ")}${t.moreKeys?` (+${t.moreKeys} more)`:""}`:"";return`an array of ${t.items} ${t.itemKind==="object"?"objects":"items"}${e}`}if(t.kind==="object"){const e=t.keys?.length?`keys ${t.keys.join(", ")}${t.moreKeys?` (+${t.moreKeys} more)`:""}`:"no keys",o=t.arrays?.length?`; arrays at ${t.arrays.map(n=>`${n.path} (${n.items})`).join(", ")}`:"";return`an object with ${e}${o}`}return`a ${t.kind}`}function w(t,e={}){const o={...j,...e};let n=!1;const i=(r,s)=>{if(typeof r=="string")return r.length<=o.maxStringChars?r:(n=!0,`${r.slice(0,o.maxStringChars)}…[+${r.length-o.maxStringChars} chars]`);if(Array.isArray(r)){if(s>=o.maxDepth)return n=!0,`[array of ${r.length}]`;const f=r.slice(0,o.maxArrayItems).map(c=>i(c,s+1));return r.length>o.maxArrayItems&&(n=!0,f.push(`…[+${r.length-o.maxArrayItems} more items]`)),f}if(S(r)){if(s>=o.maxDepth)return n=!0,"{…}";const f=Object.keys(r),c={};for(const a of f.slice(0,o.maxKeys))c[a]=i(r[a],s+1);return f.length>o.maxKeys&&(n=!0,c["…"]=`+${f.length-o.maxKeys} more keys`),c}return r};return{value:i(t,0),truncated:n}}function U({ref:t,shape:e,totalChars:o,shownChars:n,preview:i}){const l=s=>Number(s||0).toLocaleString("en-US"),r=[`[ChatPanel result shield: this result is ${l(o)} characters; showing a ${l(n)}-character preview.`];if(r.push(`Full result: ${R(e)}.`),!t)return r.push("It was not stored, so what is above is all that is available.]"),r.join(" ");if(r.push(`It is stored as ref "${t}" — read more with the ${k} tool:`),e.kind==="array"){const s=i?.items??0;r.push(`{"ref":"${t}","offset":${s},"limit":${A}} pages items; add "search":"<text>" to filter, "fields":["a","b"] to keep only those keys.`)}else if(e.kind==="object"){const s=e.arrays?.[0];r.push(s?`{"ref":"${t}","path":"${s.path}","offset":0,"limit":${A}} pages that array; "search" filters, "fields" projects.`:`{"ref":"${t}","path":"<key>"} reads one key; "search":"<text>" finds where it occurs.`)}else r.push(`{"ref":"${t}","offset":${n},"limit":${C}} continues the text; {"ref":"${t}","search":"<text>"} finds where a phrase occurs.`);return r.push("Do not ask the user for the rest; fetch what you need.]"),r.join(" ")}function F(t,{tool:e="",store:o=null,owner:n,envelope:i=null,...l}={}){const r={...j,...l},s=typeof t=="string"?t:String(t??""),f=i?i.open(s):null,c=f?f.body:s;if(c.length<=r.maxChars)return{text:s,truncated:!1};const a=K(c);let h,u,g=null;if(a!==void 0){h=a;let p={...r},$=w(a,p),b=JSON.stringify($.value);for(let M=0;b.length>r.maxChars&&M<8;M+=1)p={...p,maxArrayItems:Math.max(1,p.maxArrayItems>>1),maxStringChars:Math.max(80,p.maxStringChars>>1),maxKeys:Math.max(5,p.maxKeys>>1)},$=w(a,p),b=JSON.stringify($.value);b.length>r.maxChars&&(b=`${b.slice(0,r.maxChars)}…`),u=b,Array.isArray(a)&&(g={items:Math.min(a.length,p.maxArrayItems)})}else h=c,u=c.slice(0,r.maxChars);const d=o?o.put({tool:e,value:h,owner:n}):null,m=L(h),x=f?f.close(u):u,y=U({ref:d,shape:m,totalChars:c.length,shownChars:u.length,preview:g});return{text:`${x}
+${y}`,truncated:!0,ref:d,shape:m,totalChars:c.length}}function z(){return{name:k,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 ${A}, max ${N}) or characters (default ${C}, max ${T}).`},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:!0,idempotentHint:!0,openWorldHint:!1}}}function H(t,e){const o=String(e||"").split(".").map(l=>l.trim()).filter(Boolean);let n=t;const i=[];for(const l of o){if(Array.isArray(n)&&/^\d+$/.test(l))n=n[Number(l)];else if(S(n)&&Object.prototype.hasOwnProperty.call(n,l))n=n[l];else return{error:`No "${l}" at "${i.join(".")||"(root)"}"`,available:S(n)?Object.keys(n).slice(0,40):Array.isArray(n)?`array of ${n.length}`:typeof n};i.push(l)}return{value:n}}const O=(t,e,o,n)=>{const i=Number.parseInt(t,10);return Number.isFinite(i)?Math.min(n,Math.max(o,i)):e};function P(t,e={},{owner:o,maxChars:n=j.maxChars}={}){const i=String(e?.ref||""),l=t?t.get(i,o):null;if(!l)return JSON.stringify({error:`Unknown or expired ref "${i}".`,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 r=e.path?H(l.value,e.path):{value:l.value};if(r.error)return JSON.stringify({error:r.error,available:r.available,ref:i});const s=r.value,f=e.search!=null&&String(e.search).trim()?String(e.search).toLowerCase():"",c={ref:i,...e.path?{path:e.path}:{}};if(Array.isArray(s)){let a=s;f&&(a=a.filter(y=>JSON.stringify(y).toLowerCase().includes(f)));const h=Array.isArray(e.fields)?e.fields.map(String).filter(Boolean):[],u=y=>{if(!h.length||!S(y))return y;const p={};for(const $ of h)Object.prototype.hasOwnProperty.call(y,$)&&(p[$]=y[$]);return p},g=O(e.offset,0,0,Number.MAX_SAFE_INTEGER);let d=O(e.limit,A,1,N),m,x;for(let y=0;y<8;y+=1){m=a.slice(g,g+d).map($=>w(u($),{maxArrayItems:20,maxStringChars:2e3}).value);const p=g+d<a.length?{offset:g+d,limit:d}:null;if(x=JSON.stringify({...c,total:s.length,...f?{matched:a.length,search:e.search}:{},offset:g,limit:d,count:m.length,items:m,next:p}),x.length<=n||d===1)break;d=Math.max(1,d>>1)}return x}if(typeof s=="string"){if(f){const d=s.toLowerCase(),m=[];let x=0;for(;m.length<_;){const y=d.indexOf(f,x);if(y<0)break;const p=Math.max(0,y-E),$=Math.min(s.length,y+f.length+E);m.push({offset:y,excerpt:s.slice(p,$)}),x=y+f.length}return JSON.stringify({...c,chars:s.length,search:e.search,matches:m,more:m.length>=_})}const a=O(e.offset,0,0,s.length),h=Math.min(O(e.limit,C,1,T),Math.max(1,n-200)),u=s.slice(a,a+h),g=a+h<s.length?{offset:a+h,limit:h}:null;return JSON.stringify({...c,chars:s.length,offset:a,limit:h,text:u,next:g})}if(S(s)){const a=L(s),h=w(s,{maxArrayItems:10,maxStringChars:1e3,maxKeys:40});let u=JSON.stringify({...c,shape:a,value:h.value,hint:a.arrays?.length?`Use "path" to page an array, e.g. "${a.arrays[0].path}".`:'Use "path" to read one key.'});return u.length>n&&(u=JSON.stringify({...c,shape:a,hint:'Too large to show whole; use "path" to descend.'})),u}return JSON.stringify({...c,value:s})}function W(t,{store:e,owner:o,envelope:n=null,exempt:i=()=>!1,limits:l={},textOf:r=X,setText:s=B}={}){if(!t||typeof t.execute!="function")return t;const f=z(),c=[...(t.specs||[]).filter(u=>u?.name!==k),f],a=t.execute.bind(t),h=new Map;return{...t,specs:c,shieldStore:e,async execute(u,g,d){if(u===k)return P(e,g||{},{owner:o,maxChars:l.maxChars});const m=await a(u,g,d);if(i(u,g))return m;const x=r(m);if(typeof x!="string")return m;const y=F(x,{tool:u,store:e,owner:o,envelope:n,...l});return y.truncated?(y.ref&&h.set(y.ref,u),s(m,y.text,y)):m}}}function X(t){if(typeof t=="string")return t;if(t&&typeof t=="object"&&typeof t.text=="string")return t.text}function B(t,e,o){return typeof t=="string"?e:{...t,text:e,shielded:{ref:o.ref,totalChars:o.totalChars}}}export{j as DEFAULT_SHIELD,I as DEFAULT_STORE,k as RESULT_TOOL_NAME,w as compactValue,G as createResultStore,L as describeShape,z as resultToolSpec,P as runResultQuery,F as shieldToolResult,W as withResultShield};

package/tool-schema.js

@@ -1,155 +1 @@
-// 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 };
-}
+const y=Object.freeze(["off","balanced","aggressive"]),d=Object.freeze({mode:"balanced",maxDescriptionChars:200,maxParamDescriptionChars:100}),u=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"]),O=new Set(["$schema","$comment","title","examples","example","deprecated","readOnly","writeOnly","$id","contentMediaType","contentEncoding"]),m=t=>String(t||"").replace(/\s+/g," ").trim();function l(t,r){const s=m(t);if(!r||s.length<=r)return s;const o=s.slice(0,r),n=Math.max(o.lastIndexOf(". "),o.lastIndexOf("! "),o.lastIndexOf("? "));if(n>=r*.4)return o.slice(0,n+1);const e=o.lastIndexOf(" ");return`${(e>r*.6?o.slice(0,e):o).trimEnd()}…`}const h=t=>new Set(m(t).toLowerCase().split(/[^a-z0-9]+/).filter(r=>r.length>2)),b=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 w(t,r,s){const o=h(r),n=[...h(t.replace(/([a-z])([A-Z])/g,"$1 $2"))];for(const e of[...o]){if(b.has(e)){o.delete(e);continue}n.some(i=>i.length>=3&&(e.startsWith(i)||i.startsWith(e)))&&o.delete(e)}return s&&typeof s.type=="string"&&o.delete(s.type),o.size>=2}function p(t,r,{name:s="",depth:o=0}={}){if(!t||typeof t!="object")return t;if(Array.isArray(t))return t.map(e=>p(e,r,{depth:o+1}));const n={};for(const[e,i]of Object.entries(t))if(!O.has(e)){if(e==="description"){if(o===0){n[e]=l(i,r.maxDescriptionChars);continue}if(r.mode==="aggressive"?u.has(s.toLowerCase()):u.has(s.toLowerCase())||w(s,i,t)){const c=l(i,r.maxParamDescriptionChars);c&&(n[e]=c)}continue}if(e==="properties"&&i&&typeof i=="object"){const a={};for(const[c,f]of Object.entries(i))a[c]=p(f,r,{name:c,depth:o+1});n[e]=a;continue}if((e==="items"||e==="additionalProperties"||e==="not")&&i&&typeof i=="object"){n[e]=p(i,r,{name:s,depth:o+1});continue}if((e==="anyOf"||e==="oneOf"||e==="allOf")&&Array.isArray(i)){n[e]=i.map(a=>p(a,r,{name:s,depth:o+1}));continue}if(e==="$defs"||e==="definitions"){const a={};for(const[c,f]of Object.entries(i||{}))a[c]=p(f,r,{name:c,depth:o+1});n[e]=a;continue}n[e]=i}return n}function g(t,r={}){const s={...d,...r};if(!t||s.mode==="off"||!y.includes(s.mode))return t;const o={...t};if(typeof t.description=="string"){const n=l(t.description,s.maxDescriptionChars);n?o.description=n:delete o.description}for(const n of["parameters","inputSchema"])t[n]&&typeof t[n]=="object"&&(o[n]=p(t[n],s,{depth:1}));return o}function S(t,r){return(t||[]).map(s=>g(s,r))}function x(t,r={}){const s=t||[],o=a=>JSON.stringify(a??null).length;let n=0,e=0;const i=[];for(const a of s){const c=o(a),f=o(g(a,r));n+=c,e+=f,i.push({name:a?.name,before:c,after:f})}return{mode:r.mode||d.mode,tools:s.length,before:n,after:e,saved:n-e,savedPercent:n?Math.round((n-e)/n*100):0,perTool:i}}export{y as COMPRESSION_MODES,d as DEFAULT_COMPRESSION,g as compressToolSpec,S as compressToolSpecs,x as compressionStats,l as trimDescription};