@chatpanel/events 0.101.0 → 0.103.1

package/tool-loop-guard.js

@@ -1,184 +1,6 @@
-// The loop guard — what stops a model that keeps asking the same thing.
-//
-// Lived inside the extension's providers.js for a year, which meant the desktop could not
-// use it and wrote a smaller one (a `seen` map and a repeat count) that answered the same
-// model behaviour differently: the extension blocked a repeated write BEFORE running it,
-// the desktop ran it once and replayed it; the extension noticed a whole round repeating,
-// the desktop only a single call. Same tools, same model, two outcomes. Now one guard,
-// with everything either client had learned:
-//
-//   • a call repeated past `maxIdenticalCalls` is not executed — a READ is answered from
-//     its first result (a pure read asked twice has one answer, and refusing it is how a
-//     small model concludes the tool is broken and invents an answer); a WRITE is refused
-//     with a result that says why, because replaying a click would be a lie about
-//     something that changed the world;
-//   • observation tools never count — read → act → read again with the same empty input
-//     is correct, not a loop;
-//   • a discrete-input tool that SUCCEEDED (a keystroke, a click) is progress and clears
-//     its own count — pressing Enter twice is normal; failing to press it twice is not;
-//   • a ROUND that repeats the previous round byte for byte, or in which every call was
-//     blocked, counts toward `stalled` — and a stalled turn is offered no more tools, so
-//     the model has to answer with what it has;
-//   • `repeats` counts every replay and refusal across the turn, so a loop can tell when
-//     the model has been told enough times (the desktop's rule: three, then a closing
-//     request with no tools).
-//
-// Class R: no I/O, no clock. Names are read through `effectiveToolName` so a dispatched
-// action is judged on what it is, not on the dispatcher's name.
+import{effectiveToolName as f}from"./tool-traits.js";import{resultText as h}from"./adaptive-tool-policy.js";const x=3,A=2,T=3,S=new Set(["inspect_page","read_canvas","screenshot","marked_screenshot"]),k=new Set(["press_key","type_text","click_at","move_mouse","click_mark","draw_path","input_sequence","click_element","click_by_text"]);function m(e){return!S.has(e)&&!k.has(e)&&e!=="scroll"}function d(e){return e==null||typeof e!="object"?JSON.stringify(e):Array.isArray(e)?`[${e.map(d).join(",")}]`:`{${Object.keys(e).sort().map(t=>`${JSON.stringify(t)}:${d(e[t])}`).join(",")}}`}function g(e,t){return`${String(e||"")}
+${d(t??{})}`}function w(e){return(Array.isArray(e)?e:[]).filter(t=>m(f(t?.name,t?.input))).map(t=>g(t.name,t.input)).sort().join("|")}function O(e,t,i={}){return JSON.stringify({ok:!1,blocked:!0,error:"tool_loop_blocked",tool:e||"tool",message:t,retry_hint:"Answer using the already available conversation context and tool results. Do not call more tools unless the user asks you to continue.",...i})}function N(e,t,i=null){const l=f(e,i);if(l==="scroll")try{return JSON.parse(h(t))?.atBottom===!1}catch{return!1}if(k.has(l))try{return JSON.parse(h(t))?.ok===!0}catch{return!1}return!1}function R({maxIdenticalCalls:e=x,maxStalledRounds:t=A,maxRepeats:i=T}={}){const l=new Map,p=new Map;let c=0,y=null,u=0;return{get disabled(){return!1},get stalled(){return c>=t},get repeats(){return u},get looping(){return u>=i},noteRound(o,a,n=""){const r=a>0&&o>=a,s=!!n&&n===y;y=n,s?c+=2:r?c+=1:c=0},reset(o){o&&l.delete(o)},remember(o,a,n,r,{readOnly:s=!1}={}){!o||!r||!s||p.set(o,r)},check(o,a){if(S.has(f(o,a)))return{blocked:!1};const n=g(o,a),r=(l.get(n)||0)+1;if(l.set(n,r),r>e&&p.has(n)){u+=1;const s=p.get(n),_="[This exact call was already made this turn; the result is unchanged. Answer from what you have.]",b=typeof s=="string"?`${s}
 
-import { effectiveToolName } from './tool-traits.js';
-import { resultText } from './adaptive-tool-policy.js';
+${_}`:s&&typeof s=="object"&&typeof s.text=="string"?{...s,text:`${s.text}
 
-export const DEFAULT_MAX_IDENTICAL_CALLS = 3;
-export const DEFAULT_MAX_STALLED_ROUNDS = 2;
-export const DEFAULT_MAX_REPEATS = 3;
-
-// Observation/read tools are MEANT to be repeated with the SAME (empty) input.
-export const OBSERVATION_TOOLS = new Set(['inspect_page', 'read_canvas', 'screenshot', 'marked_screenshot']);
-
-// Tools whose whole job is ONE discrete physical input. A SUCCESSFUL application counts as
-// progress and clears the repeat count; a failing one (unknown key, nothing at point) does
-// not, so a genuinely stuck call still trips the guard.
-export const INPUT_PROGRESS_TOOLS = new Set([
-  'press_key', 'type_text', 'click_at', 'move_mouse', 'click_mark', 'draw_path', 'input_sequence',
-  'click_element', 'click_by_text',
-]);
-
-/** A tool whose repetition signals a LOOP (search/query/fetch), not one meant to repeat. */
-export function isLoopableTool(name) {
-  return !OBSERVATION_TOOLS.has(name) && !INPUT_PROGRESS_TOOLS.has(name) && name !== 'scroll';
-}
-
-function stableStringify(value) {
-  if (value == null || typeof value !== 'object') return JSON.stringify(value);
-  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
-  return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(',')}}`;
-}
-
-/** The identity of a call: its name and its arguments with keys in a stable order. */
-export function stableToolCallKey(name, input) {
-  return `${String(name || '')}\n${stableStringify(input ?? {})}`;
-}
-
-/** The identity of a ROUND: its loopable calls, sorted — so a re-read or a scroll never makes two rounds look alike. */
-export function roundSignature(calls) {
-  return (Array.isArray(calls) ? calls : [])
-    .filter((c) => isLoopableTool(effectiveToolName(c?.name, c?.input)))
-    .map((c) => stableToolCallKey(c.name, c.input))
-    .sort()
-    .join('|');
-}
-
-/** The result a refused repeat receives — machine-readable, with the way out spelled out. */
-export function blockedToolResult(name, message, extra = {}) {
-  return JSON.stringify({
-    ok: false,
-    blocked: true,
-    error: 'tool_loop_blocked',
-    tool: name || 'tool',
-    message,
-    retry_hint: 'Answer using the already available conversation context and tool results. Do not call more tools unless the user asks you to continue.',
-    ...extra,
-  });
-}
-
-/**
- * Did a repeatable tool actually do something? For `scroll`, "more page below"; for a
- * discrete input, `ok: true`. Anything else is not progress — the step cap is the backstop.
- */
-export function toolMadeProgress(name, result, input = null) {
-  // Through the dispatcher too: `page {action:'scroll'}` is a scroll. Judged by the bare
-  // name, four scrolls through `page` looked like a stuck loop and were blocked.
-  const eff = effectiveToolName(name, input);
-  if (eff === 'scroll') {
-    try { return JSON.parse(resultText(result))?.atBottom === false; } catch { return false; }
-  }
-  if (INPUT_PROGRESS_TOOLS.has(eff)) {
-    try { return JSON.parse(resultText(result))?.ok === true; } catch { return false; }
-  }
-  return false;
-}
-
-/**
- * @param maxIdenticalCalls  how many times the SAME call runs before it is replayed or refused
- * @param maxStalledRounds   how many no-progress rounds in a row before `stalled`
- * @param maxRepeats         how many replays/refusals in a turn before `looping`
- */
-export function createToolLoopGuard({
-  maxIdenticalCalls = DEFAULT_MAX_IDENTICAL_CALLS,
-  maxStalledRounds = DEFAULT_MAX_STALLED_ROUNDS,
-  maxRepeats = DEFAULT_MAX_REPEATS,
-} = {}) {
-  const counts = new Map();
-  const lastResult = new Map(); // key → what that identical call returned the first time
-  let stalledRounds = 0;
-  let lastSignature = null;
-  let repeats = 0;
-
-  return {
-    // No nuclear per-turn kill switch — one looping tool must not disable the rest. The
-    // round cap is the overall backstop.
-    get disabled() { return false; },
-    get stalled() { return stalledRounds >= maxStalledRounds; },
-    /** Replays and refusals so far this turn. */
-    get repeats() { return repeats; },
-    /** The model has been answered "you already asked that" enough times to stop asking. */
-    get looping() { return repeats >= maxRepeats; },
-
-    /**
-     * After each round, note progress. No progress = every call was blocked, OR the round's
-     * loopable call-set is byte-identical to the previous round's (a loop even before the
-     * per-tool threshold trips). An exact-repeat round is definitive — two strikes at once.
-     */
-    noteRound(blockedCount, total, signature = '') {
-      const allBlocked = total > 0 && blockedCount >= total;
-      const repeatRound = !!signature && signature === lastSignature;
-      lastSignature = signature;
-      if (repeatRound) stalledRounds += 2;
-      else if (allBlocked) stalledRounds += 1;
-      else stalledRounds = 0;
-    },
-
-    /** Clear a call's repeat count when it actually made progress. */
-    reset(key) { if (key) counts.delete(key); },
-
-    /** Remember what a READ returned, so a repeat can be answered instead of refused. */
-    remember(key, name, input, result, { readOnly = false } = {}) {
-      if (!key || !result || !readOnly) return;
-      lastResult.set(key, result);
-    },
-
-    /**
-     * Should this call run? `{ blocked, replayed, count, key, result }` — `result` is what to
-     * answer with when it should not.
-     */
-    check(name, input) {
-      if (OBSERVATION_TOOLS.has(effectiveToolName(name, input))) return { blocked: false };
-      const key = stableToolCallKey(name, input);
-      const count = (counts.get(key) || 0) + 1;
-      counts.set(key, count);
-      if (count > maxIdenticalCalls && lastResult.has(key)) {
-        // Serve the answer it already earned — and say so, because a model that repeats
-        // itself is usually waiting for a value that will not change. Still counted, so a
-        // genuinely stuck loop stays visible in the log.
-        repeats += 1;
-        const prior = lastResult.get(key);
-        const note = '[This exact call was already made this turn; the result is unchanged. Answer from what you have.]';
-        const result = typeof prior === 'string' ? `${prior}\n\n${note}` : (prior && typeof prior === 'object' && typeof prior.text === 'string' ? { ...prior, text: `${prior.text}\n\n${note}` } : prior);
-        return { blocked: false, replayed: true, count, key, result };
-      }
-      if (count > maxIdenticalCalls) {
-        repeats += 1;
-        return {
-          blocked: true, count, key,
-          result: blockedToolResult(
-            name,
-            `Skipped a repeated identical ${name || 'tool'} call (${count}× with the same input). Vary the input or try a different action — your other tools still work.`,
-            { repeated: true, identicalCallCount: count, maxIdenticalCalls },
-          ),
-        };
-      }
-      return { blocked: false, count, key };
-    },
-  };
-}
+${_}`}:s;return{blocked:!1,replayed:!0,count:r,key:n,result:b}}return r>e?(u+=1,{blocked:!0,count:r,key:n,result:O(o,`Skipped a repeated identical ${o||"tool"} call (${r}× with the same input). Vary the input or try a different action — your other tools still work.`,{repeated:!0,identicalCallCount:r,maxIdenticalCalls:e})}):{blocked:!1,count:r,key:n}}}}export{x as DEFAULT_MAX_IDENTICAL_CALLS,T as DEFAULT_MAX_REPEATS,A as DEFAULT_MAX_STALLED_ROUNDS,k as INPUT_PROGRESS_TOOLS,S as OBSERVATION_TOOLS,O as blockedToolResult,R as createToolLoopGuard,m as isLoopableTool,w as roundSignature,g as stableToolCallKey,N as toolMadeProgress};

package/tool-need.js

@@ -1,124 +1,2 @@
-// Does this turn need tools AT ALL — asked before any of them are built.
-//
-// Every turn was armed with the same equipment regardless of what was said. "hi" arrived at
-// the model carrying a history dispatcher, an MCP dispatcher and ~1,200 tokens of rulebook
-// explaining how to use them, and that cost more than the prompt itself. That is not only
-// waste, it CHANGES THE ANSWER: a turn that carries tools requires a model that can call
-// them (see requirementsFor), so a greeting eliminated every model without the tools
-// capability and then paid a CLI agent two seconds to spawn a process in order to wave back.
-//
-// Equipment is not demand. The question "what does this turn need" has to be asked of the
-// MESSAGE, before the toolset exists — which is what the router already does for model
-// choice, from the same signals, for free.
-//
-// THE ERROR BIAS IS THE OPPOSITE OF THE ROUTER'S, which is why this is not simply
-// `signals.smalltalk`. Mis-routing a turn produces a worse answer; withholding the history
-// tools from "what did we decide in the standup" produces "I cannot access your meetings" —
-// wrong, and the exact thing the tool system prompt exists to prevent. So this does not try
-// to detect which turns need tools. It recognises the narrow class of turns that provably
-// cannot — pleasantries, and nothing else — and arms everything otherwise.
-//
-// Recognised by VOCABULARY rather than by absence: every word must be a conversational
-// move. An unknown word, a typo, a name, a question — anything at all — falls through to
-// "arm the tools", which is the safe direction. `smalltalk` still has to agree, so the two
-// definitions of trivial cannot drift apart.
-//
-// Class R: no model call, no network, no I/O. Reading a string.
-
-import { signalsFrom } from './router.js';
-
-// Greetings, thanks, acknowledgements, farewells — and the filler that attaches to them
-// ("hey there", "ok got it", "thanks so much"). Deliberately small: every addition widens
-// the set of turns that get no tools, so a word earns its place by being unable to appear
-// in a request.
-const PLEASANTRY = new Set([
-  'hi', 'hii', 'hiya', 'hey', 'heya', 'hello', 'helo', 'yo', 'sup', 'howdy', 'greetings',
-  'good', 'morning', 'afternoon', 'evening', 'night', 'day',
-  'thanks', 'thank', 'thankyou', 'thx', 'tnx', 'ty', 'cheers', 'appreciated',
-  'ok', 'okay', 'k', 'kk', 'got', 'sounds', 'perfect', 'great', 'cool', 'nice', 'awesome',
-  'lol', 'haha', 'hah', 'hehe', 'nvm', 'yep', 'yeah', 'yes', 'no', 'nope', 'sure',
-  'bye', 'goodbye', 'later', 'ya', 'cya', 'ciao', 'welcome', 'worries', 'problem', 'np',
-  'please', 'there', 'again', 'all', 'everyone', 'team', 'friend', 'mate', 'buddy',
-  'you', 'u', 'so', 'much', 'very', 'well', 'and', 'a', 'the',
-]);
-
-// At most a short phrase. A long message built entirely from these words is not a greeting,
-// it is something this rule does not understand — and not understanding means arm the tools.
-const MAX_PLEASANTRY_WORDS = 6;
-
-function isPleasantry(text) {
-  // Strip emoji, punctuation and digits: "hi!! 👋" is "hi". Anything left must be a word in
-  // the vocabulary.
-  const words = String(text || '')
-    .toLowerCase()
-    .replace(/[^\p{L}\s']/gu, ' ')
-    .split(/\s+/)
-    .filter(Boolean);
-  if (!words.length || words.length > MAX_PLEASANTRY_WORDS) return false;
-  return words.every((w) => PLEASANTRY.has(w));
-}
-
-/**
- * @param request     { text } | { messages } — the turn, as the router already reads it.
- * @param signals     precomputed signalsFrom(request), when the caller already has them.
- * @param attachments anything the user attached; presence alone means there is material.
- * @param explicit    the user or a skill ASKED for tools this turn (MCP mode 'on', the
- *                    /history hint, a running skill). Never second-guessed.
- * @returns { tools, why } — `tools: false` means build nothing at all this turn.
- */
-export function toolNeedFor({ request = null, signals = null, attachments = [], explicit = false } = {}) {
-  if (explicit) return { tools: true, why: 'the turn asked for tools' };
-  // MATERIAL THE USER HANDED OVER — not the tab that happens to be open.
-  //
-  // The side panel auto-attaches the current page to every send, so "hi" on a search results
-  // page arrived carrying an attachment and armed the full toolset: three tools, ~2,300
-  // tokens and a page read, to say hello back. The open tab is METADATA about where the user
-  // is, not content they asked about; treating the two the same made the ambient page defeat
-  // this rule on every turn where it mattered.
-  //
-  // `auto` marks it. A page the user genuinely attached has no such mark and still counts —
-  // and a message that ASKS about the page ("summarise this") is not a pleasantry anyway, so
-  // it arms tools by the ordinary path rather than by what happens to be attached.
-  if ((attachments || []).some((a) => a && !a.auto)) {
-    return { tools: true, why: 'the turn carries an attachment' };
-  }
-
-  const text = String(request?.text ?? (request?.messages || []).map((m) => m?.content || '').join('\n'));
-  if (!isPleasantry(text)) return { tools: true, why: 'the request may need something fetched' };
-
-  // And the router has to agree it is trivial. Two definitions of "asks for nothing" that
-  // can disagree is the duplication this codebase keeps removing; requiring both means the
-  // stricter one always wins.
-  const sig = signals || signalsFrom(request || {});
-  if (!sig.smalltalk) return { tools: true, why: 'the request may need something fetched' };
-
-  return { tools: false, why: 'a greeting — nothing to look up' };
-}
-
-// ── Which GRANTS a task's wording calls for (F8 §15.2) ──────────────────────────────────
-//
-// A team member holding `web` that answers a "latest price" question from memory has not
-// done the task. This is the deterministic half of the tool-choice guard: read the task's
-// text for the vocabulary that names a source — the web, the person's own history, attached
-// material — and return the grants that vocabulary fits. The runner nudges a member ONCE
-// when it ends with zero calls while holding one of these. Conservative by construction:
-// nothing here fires on a task that could plausibly be answered from what the model knows.
-const NEEDS = Object.freeze([
-  ['web', /\b(search|google|look ?up|latest|current|recent|today|this (week|month|year)|news|price|prices|pricing|cost of|quote|stock|market|website|url|online|web|docs?umentation|release notes|changelog|versions?)\b/i],
-  ['history', /\b(our (meeting|call|notes?|chats?|conversation)|what (did|was) (we|i)|we (decided|agreed|discussed|said)|in (my|our) (notes?|meetings?|history|chats?)|past (chats?|meetings?|notes?)|earlier (meeting|conversation|chat|note)|transcript|standup|retro)\b/i],
-  ['data', /\b(attached|attachment|this (page|document|file|pdf|spreadsheet|sheet)|the (document|file|pdf|spreadsheet) (above|provided|attached))\b/i],
-]);
-
-/**
- * The grants a task's text calls for, in the order they fit: `['web']`, `['history', 'web']`,
- * `[]`. `held` narrows to what the role actually has, so the caller gets what is BOTH needed
- * and available — an empty list means no nudge.
- */
-export function grantsNeededFor(text, { held = null } = {}) {
-  const t = String(text || '');
-  if (!t.trim()) return [];
-  const out = NEEDS.filter(([, re]) => re.test(t)).map(([g]) => g);
-  if (!held) return out;
-  const have = new Set((Array.isArray(held) ? held : []).map((g) => String(g).toLowerCase()));
-  return out.filter((g) => have.has(g) || (g === 'history' && have.has('data')));
-}
+import{signalsFrom as i}from"./router.js";const h=new Set(["hi","hii","hiya","hey","heya","hello","helo","yo","sup","howdy","greetings","good","morning","afternoon","evening","night","day","thanks","thank","thankyou","thx","tnx","ty","cheers","appreciated","ok","okay","k","kk","got","sounds","perfect","great","cool","nice","awesome","lol","haha","hah","hehe","nvm","yep","yeah","yes","no","nope","sure","bye","goodbye","later","ya","cya","ciao","welcome","worries","problem","np","please","there","again","all","everyone","team","friend","mate","buddy","you","u","so","much","very","well","and","a","the"]),l=6;function c(o){const e=String(o||"").toLowerCase().replace(/[^\p{L}\s']/gu," ").split(/\s+/).filter(Boolean);return!e.length||e.length>l?!1:e.every(n=>h.has(n))}function g({request:o=null,signals:e=null,attachments:n=[],explicit:r=!1}={}){if(r)return{tools:!0,why:"the turn asked for tools"};if((n||[]).some(a=>a&&!a.auto))return{tools:!0,why:"the turn carries an attachment"};const s=String(o?.text??(o?.messages||[]).map(a=>a?.content||"").join(`
+`));return c(s)?(e||i(o||{})).smalltalk?{tools:!1,why:"a greeting — nothing to look up"}:{tools:!0,why:"the request may need something fetched"}:{tools:!0,why:"the request may need something fetched"}}const u=Object.freeze([["web",/\b(search|google|look ?up|latest|current|recent|today|this (week|month|year)|news|price|prices|pricing|cost of|quote|stock|market|website|url|online|web|docs?umentation|release notes|changelog|versions?)\b/i],["history",/\b(our (meeting|call|notes?|chats?|conversation)|what (did|was) (we|i)|we (decided|agreed|discussed|said)|in (my|our) (notes?|meetings?|history|chats?)|past (chats?|meetings?|notes?)|earlier (meeting|conversation|chat|note)|transcript|standup|retro)\b/i],["data",/\b(attached|attachment|this (page|document|file|pdf|spreadsheet|sheet)|the (document|file|pdf|spreadsheet) (above|provided|attached))\b/i]]);function y(o,{held:e=null}={}){const n=String(o||"");if(!n.trim())return[];const r=u.filter(([,t])=>t.test(n)).map(([t])=>t);if(!e)return r;const s=new Set((Array.isArray(e)?e:[]).map(t=>String(t).toLowerCase()));return r.filter(t=>s.has(t)||t==="history"&&s.has("data"))}export{y as grantsNeededFor,g as toolNeedFor};