acuvo-code 0.2.0

package/lib/terminal-graphics.mjs

@@ -0,0 +1,171 @@
+/**
+ * ── ⭐⭐ THE TERMINAL IS A CANVAS, NOT A LOG ─────────────────────────────────
+ *
+ * Every coding CLI treats the terminal as append-only text. It is not. It is a
+ * grid of cells with 24-bit colour, and several modern terminals accept ACTUAL
+ * PIXELS through documented escape sequences — no dependency, no framework, no
+ * permission. Just bytes on stdout.
+ *
+ * ⭐ WHY THIS IS OURS AND NOT ANYONE ELSE'S. A coding agent has nothing to show
+ * you: it writes text, so it prints text. This one renders pages, generates
+ * images and draws faces, and until now it has been describing them in prose
+ * like a radio announcer calling a painting. `see_page` already produces a real
+ * screenshot and then tells you a FILE PATH. Printing the picture instead is a
+ * capability the competition structurally cannot copy, because they have no
+ * picture to print.
+ *
+ * ── ⚠️ WHAT THIS DELIBERATELY DOES NOT DO ───────────────────────────────────
+ * **No sixel.** Sixel would cover Windows Terminal and xterm, and it is the one
+ * I most wanted. It needs the image as RAW PIXELS, which means decoding PNG —
+ * inflate, defilter, palette quantisation — and that is a decoder we would own,
+ * test and be wrong in, in a package whose whole promise is zero dependencies.
+ * Kitty and iTerm2 both accept a PNG byte-for-byte, so they cost nothing.
+ *
+ * ⚠️ SO ON WINDOWS TERMINAL THIS PRINTS A PATH, exactly as before. That is
+ * stated here rather than discovered by a user, because a feature that silently
+ * does nothing on the author's own machine is how "it works" becomes a lie.
+ *
+ * ⚠️ AND IT MUST NEVER CORRUPT A TERMINAL THAT CANNOT READ IT. An unrecognised
+ * escape sequence does not render as nothing — it renders as garbage, and a few
+ * kilobytes of base64 vomited into a pipe is worse than any missing feature. So
+ * detection is ALLOWLIST-ONLY: a terminal we do not positively recognise gets
+ * text, forever. Guessing costs more than abstaining.
+ */
+
+import { readFileSync } from 'node:fs';
+
+/** Terminals whose support we have positively identified, and by which protocol. */
+const KITTY_PROTOCOL = 'kitty';
+const ITERM_PROTOCOL = 'iterm';
+
+/**
+ * Which inline-image protocol this terminal speaks, or null.
+ *
+ * ⚠️ ENV IS READ AT CALL TIME, never captured at import — the same rule the
+ * media config follows, and for the same reason: a test must be able to hand in
+ * a different environment without reloading the module.
+ */
+export function detectImageProtocol(env = process.env, { isTTY = process.stdout.isTTY } = {}) {
+  /**
+   * ⚠️ THE OVERRIDE IS CHECKED FIRST AND IN BOTH DIRECTIONS. Someone on a
+   * terminal we have not heard of should be able to turn this on, and someone
+   * piping our output somewhere should be able to turn it off — and `0` must
+   * win over every piece of cleverness below it.
+   */
+  const forced = env.ACUVO_INLINE_IMAGES?.trim();
+  if (forced === '0' || forced === 'false' || forced === 'off') return null;
+
+  /**
+   * ⚠️ NOT A TTY MEANS SOMETHING IS READING THIS, not someone. `acuvo --json |
+   * jq` must never receive image bytes; it would not just look wrong, it would
+   * break the parse. This check sits above the allowlist deliberately: being
+   * ON kitty is irrelevant when stdout is a file.
+   */
+  if (!isTTY && forced !== '1') return null;
+
+  const program = (env.TERM_PROGRAM ?? '').toLowerCase();
+  const term = (env.TERM ?? '').toLowerCase();
+
+  // Kitty itself, and the terminals that implement its protocol.
+  if (env.KITTY_WINDOW_ID) return KITTY_PROTOCOL;
+  if (term.includes('kitty')) return KITTY_PROTOCOL;
+  if (program === 'ghostty' || env.GHOSTTY_RESOURCES_DIR) return KITTY_PROTOCOL;
+  if (program === 'wezterm' || env.WEZTERM_PANE !== undefined) return KITTY_PROTOCOL;
+  if (env.KONSOLE_VERSION) return KITTY_PROTOCOL;
+
+  if (program === 'iterm.app' || env.ITERM_SESSION_ID) return ITERM_PROTOCOL;
+
+  // ⚠️ Everything else — Windows Terminal, VS Code, plain xterm, tmux, CI —
+  // gets text. See the sixel note at the top for why Windows Terminal is on
+  // this side of the line.
+  if (forced === '1') return KITTY_PROTOCOL;
+  return null;
+}
+
+/**
+ * Kitty graphics protocol: transmit-and-display a PNG.
+ *
+ * ⚠️ CHUNKED AT 4096 BASE64 CHARACTERS, WHICH IS THE SPEC AND NOT A PREFERENCE.
+ * Terminals drop escape sequences longer than their input buffer, and the
+ * failure is silent — no image, no error, nothing to debug. `m=1` means another
+ * chunk follows; the final chunk carries `m=0`.
+ */
+export function kittySequence(pngBytes) {
+  const b64 = Buffer.from(pngBytes).toString('base64');
+  const CHUNK = 4096;
+  if (b64.length <= CHUNK) return `\x1b_Ga=T,f=100;${b64}\x1b\\`;
+
+  const parts = [];
+  for (let i = 0; i < b64.length; i += CHUNK) {
+    const slice = b64.slice(i, i + CHUNK);
+    const more = i + CHUNK < b64.length ? 1 : 0;
+    // Control keys go on the FIRST chunk only; later chunks carry just `m`.
+    parts.push(i === 0
+      ? `\x1b_Ga=T,f=100,m=${more};${slice}\x1b\\`
+      : `\x1b_Gm=${more};${slice}\x1b\\`);
+  }
+  return parts.join('');
+}
+
+/**
+ * iTerm2 inline image protocol.
+ *
+ * `size` is the byte length of the DECODED image — iTerm uses it for a progress
+ * indicator, and getting it wrong shows a stalled bar on a picture that already
+ * arrived. `inline=1` displays rather than downloads.
+ */
+export function itermSequence(pngBytes, { name = 'acuvo.png' } = {}) {
+  const buf = Buffer.from(pngBytes);
+  const args = [
+    'inline=1',
+    `size=${buf.length}`,
+    `name=${Buffer.from(name, 'utf8').toString('base64')}`,
+    'width=60', // cells, not pixels — a full-width screenshot swamps the scrollback
+    'preserveAspectRatio=1',
+  ].join(';');
+  return `\x1b]1337;File=${args}:${buf.toString('base64')}\x07`;
+}
+
+/**
+ * ⚠️ THE CEILING EXISTS BECAUSE THE TERMINAL IS NOT A GALLERY. A 4K screenshot
+ * is megabytes of base64 travelling through a pty one byte at a time; it stalls
+ * the session and scrolls everything useful off the screen. Beyond this we say
+ * so and print the path.
+ */
+const MAX_INLINE_BYTES = 1_500_000;
+
+/**
+ * Render an image file into the terminal if we can, and say what we did.
+ *
+ * Returns `{ shown, text }` — `text` is always safe to print, so the caller
+ * never needs to know which branch it took. Never throws: a picture failing to
+ * display must not end a coding session.
+ */
+export function renderImage(absolutePath, { env = process.env, isTTY = process.stdout.isTTY, readImpl = readFileSync } = {}) {
+  const protocol = detectImageProtocol(env, { isTTY });
+  if (!protocol) return { shown: false, text: null };
+
+  let bytes;
+  try {
+    bytes = readImpl(absolutePath);
+  } catch {
+    // The path is printed by the caller regardless; a missing file here is not
+    // this function's problem to report.
+    return { shown: false, text: null };
+  }
+
+  if (bytes.length > MAX_INLINE_BYTES) {
+    return {
+      shown: false,
+      text: `  (${Math.round(bytes.length / 1024)}KB — too large to show inline; open the file)`,
+    };
+  }
+
+  const seq = protocol === KITTY_PROTOCOL
+    ? kittySequence(bytes)
+    : itermSequence(bytes, { name: absolutePath.split(/[\\/]/).pop() });
+
+  // A newline after the sequence, or the next line of output lands on top of
+  // the image — which looks exactly like a rendering bug and is not one.
+  return { shown: true, text: `${seq}\n` };
+}

package/lib/tool-prefix.mjs

@@ -0,0 +1,226 @@
+/**
+ * ── ⭐⭐ THE TOOLS BLOCK IS BYTE 0 OF EVERY REQUEST, SO ITS ORDER IS MONEY ───
+ *
+ * `PRICING.md` sizes the ladder on a cache floor, and a floor is
+ * `sharedHead ÷ typicalPrompt`. MEASURED on this repo, 2026-08-16, through the
+ * real `runSession` against three different repositories: the shared head
+ * between two tenants is **22,889 bytes, of which 21,466 — 94% — is the tool
+ * schema block**. It is the first thing on the wire and it is almost the whole
+ * of what any two requests have in common.
+ *
+ * ── ⚠️⚠️ AND HALF OF IT IS CONDITIONAL, SITTING IN THE MIDDLE ───────────────
+ *
+ * `toolNamesForRounds` decides what to OFFER from the machine's configuration —
+ * `--no-run`, `ACUVO_ALLOW_PUSH`, the `MODAL_*` endpoints, whether stdin is a
+ * TTY, whether this is a subagent. `toolSchemasFor` then filters the registry,
+ * which preserves REGISTRY order — and the optional tools are registered in the
+ * middle of it (`run_command` at index 3, `git_push` at 15, `generate_image` at
+ * 16, `speak` at 18).
+ *
+ * ⚠️ SO ONE ABSENT TOOL DOES NOT COST ITS OWN 400 BYTES. It costs everything
+ * behind it: the rest of the tools block, the system message, the repo map and
+ * the task. Measured, same day, against a bare-machine reference of 31,354
+ * bytes:
+ *
+ *     configuration difference        shared prefix     of the tools block
+ *     --no-run                            1,199 B                    3.8%
+ *     ACUVO_ALLOW_PUSH=1                 10,693 B                   32.9%
+ *     MODAL_TTS_URL set                  11,766 B                   37.1%
+ *     stdin is a TTY (ask_user)          17,386 B                   53.6%
+ *     running as a subagent              15,500 B                   49.4%
+ *
+ * ⚠️⚠️ READ THE TTY ROW AGAIN. Same user, same machine, same repository, same
+ * task — `acuvo "…"` typed at a terminal and the same command in CI share
+ * **half** their prompt prefix, because one of them is offered `ask_user` and
+ * the schema for it is registered at index 37 instead of last.
+ *
+ * ── ⭐ THE FIX IS AN ORDERING CHANGE AND NOTHING ELSE ───────────────────────
+ *
+ * Constant first, conditional last. The model is offered exactly the same tools
+ * with exactly the same descriptions; only their position in the array moves,
+ * and a `tools` array is a SET of available functions, not a ranking. Measured
+ * gain, same variants:
+ *
+ *     configuration difference        before        after
+ *     --no-run                        1,199 B     19,191 B     (16.0x)
+ *     ACUVO_ALLOW_PUSH=1             10,693 B     21,893 B      (2.0x)
+ *     MODAL_TTS_URL set              11,766 B     22,966 B      (2.0x)
+ *     stdin is a TTY                 17,386 B     24,206 B      (1.4x)
+ *     running as a subagent          15,500 B     22,968 B      (1.5x)
+ *
+ * ⭐ AND IT COSTS NO CONTEXT QUALITY, WHICH IS THE RULE THAT OUTRANKS THE CACHE.
+ * Nothing is dropped, summarised, withheld or reworded. Not compacting to
+ * protect a prefix causes context drift and drift is far more expensive than a
+ * miss — this is the opposite trade: the same context, in a cheaper order.
+ *
+ * ⚠️ `run_command` moves from index 3 to the tail, which is the one visible
+ * consequence worth naming. It is still offered, still described identically,
+ * and the verbs a model reaches for first — `read_file`, `write_file`,
+ * `edit_file`, `list_dir`, `search_text` — are unmoved at the head.
+ */
+
+import { toolNamesForRounds } from './tools.mjs';
+
+/**
+ * ── ⚠️⚠️ THE CORE IS DERIVED, NEVER HAND-LISTED ─────────────────────────────
+ *
+ * A written-down list of "the tools that are always offered" is a SECOND COPY of
+ * a fact that lives in `toolNamesForRounds`'s control flow, and the second copy
+ * is the one that goes stale. The failure would be silent and expensive: add a
+ * new conditional tool, forget the list, and it lands in the middle of the head
+ * again — voiding every prompt on every machine that does not have it, with
+ * nothing going red.
+ *
+ * So the core is computed by ASKING the offer function, across the configuration
+ * space, and intersecting the answers.
+ *
+ * ── ⭐⭐ AND THE DERIVATION IS MACHINE-INDEPENDENT BY CONSTRUCTION ──────────
+ *
+ * ⚠️ THIS IS THE TRAP THAT NEARLY SHIPPED. The obvious version derives the core
+ * from the offers available on THIS machine — and then a machine with a
+ * language server present puts `check_types` in the core, a machine without it
+ * does not, the two produce different ORDERS, and the ordering meant to protect
+ * the prefix becomes the thing that destroys it. That is `localeCompare` in
+ * `lib/prefix-order.mjs` wearing a different hat: a sort whose result depends on
+ * the environment is not a sort, it is a per-machine cache pool.
+ *
+ * ⭐ So every probe runs against a root that CANNOT EXIST. Skills and the LSP
+ * verbs are gated on files under the workspace, so a non-existent root offers
+ * neither, on every machine, for ever. The derived core is therefore a pure
+ * function of this package's own code — identical in CI, on Roman's laptop and
+ * on the box the gateway runs on, which is the only way two tenants can share a
+ * byte-identical head at all.
+ *
+ * ⚠️ AND THE ERROR DIRECTION IS SAFE. An intersection can only ever SHRINK the
+ * core, so an unsampled configuration can push a tool OUT of the head (costing a
+ * little ordering) and can never sneak one IN (which would cost the prefix). A
+ * tool this misses is a tool in the tail, and the tail is always correct.
+ */
+
+/**
+ * A path no workspace uses, so `existsSync` is false everywhere. ⚠️ It is never
+ * created, read or written — only NAMED, so that the root-gated verbs answer
+ * "absent" identically on every machine.
+ *
+ * ⚠️ ORDINARY CHARACTERS ONLY. The first draft of this constant separated its
+ * words with literal NUL bytes, which render as NOTHING in every viewer — so the
+ * source read as a normal path, the test asserting the path does not exist was
+ * checking a DIFFERENT string, and both passed. `cache-prefix-stability.test.mjs`
+ * records the same trap in its own separators: a control character in source is
+ * a value nobody can review.
+ */
+const NOWHERE = '/acuvo-cache-core-probe-no-such-workspace';
+
+/**
+ * Which environment variables does the offer even consult? Recorded rather than
+ * guessed, so a new gate on a new variable is sampled the day it is written.
+ *
+ * ⚠️ `has` AND `ownKeys` ARE TRAPPED TOO, not just `get`. A gate written as
+ * `'MODAL_TTS_URL' in env` reads through a different trap, and a spy that only
+ * watched `get` would report the variable as unread and leave its tool in the
+ * head.
+ *
+ * ⚠️ AND THOSE TWO TRAPS ARE NOT COVERED BY A TEST, because no gate in the
+ * package reaches them today — deleting them leaves the suite green. That is
+ * stated rather than papered over: they are insurance against the next gate, and
+ * the thing that WOULD catch a miss is the brute-force re-derivation in
+ * `test/tool-prefix-order.test.mjs`, which samples the variables directly.
+ */
+function envKeysConsulted(maxRounds) {
+  const seen = new Set();
+  const spy = new Proxy({}, {
+    get(_t, key) { if (typeof key === 'string') seen.add(key); return undefined; },
+    has(_t, key) { if (typeof key === 'string') seen.add(key); return false; },
+    ownKeys() { return []; },
+    getOwnPropertyDescriptor() { return undefined; },
+  });
+  try {
+    toolNamesForRounds(maxRounds, { allowRun: true, root: NOWHERE, env: spy });
+  } catch {
+    /* a spy that upsets a future gate must not take the ordering down with it */
+  }
+  return [...seen].sort();
+}
+
+/**
+ * ⚠️ FOUR ENVIRONMENT POINTS, AND THE EMPTY STRING IS NOT REDUNDANT. Gates in
+ * this package are deliberately not all the same shape: `PERCHANCE_IMAGE_URL`
+ * UNSET means "use the public endpoint, offer the tool", and set-but-EMPTY means
+ * "this machine has switched it off". Sampling only unset would leave
+ * `generate_image` looking unconditional.
+ */
+const ENV_SAMPLES = ['', '1', 'https://example.invalid'];
+
+/** Memoised per rounds-bucket: the derivation is pure, so it is computed once. */
+const cache = new Map();
+
+/**
+ * The tools offered under EVERY configuration — the ones whose bytes may sit in
+ * the shared head.
+ *
+ * ⚠️ BUCKETED ON `maxRounds <= 1`, because that is the only threshold
+ * `toolNamesForRounds` has: a single-shot turn returns `SINGLE_SHOT_TOOL_NAMES`
+ * and shares almost nothing with a multi-round offer. They are different cache
+ * pools by nature and pretending otherwise would put a multi-round tool in a
+ * single-shot head.
+ *
+ * @param {number} maxRounds
+ * @returns {Set<string>}
+ */
+export function alwaysOfferedNames(maxRounds) {
+  const bucket = Number(maxRounds) <= 1 ? 'single' : 'multi';
+  const memo = cache.get(bucket);
+  if (memo) return memo;
+
+  const rounds = bucket === 'single' ? 1 : 8;
+  const keys = envKeysConsulted(rounds);
+  const envs = [{}, ...ENV_SAMPLES.map((v) => Object.fromEntries(keys.map((k) => [k, v])))];
+
+  /** @type {Set<string> | null} */
+  let core = null;
+  for (const allowRun of [true, false]) {
+    for (const subagent of [true, false]) {
+      for (const interactive of [true, false]) {
+        for (const env of envs) {
+          let offered;
+          try {
+            offered = toolNamesForRounds(rounds, { allowRun, subagent, interactive, root: NOWHERE, env });
+          } catch {
+            /* a configuration the offer refuses contributes nothing to the intersection */
+            continue;
+          }
+          const names = new Set(offered);
+          core = core === null ? names : new Set([...core].filter((n) => names.has(n)));
+        }
+      }
+    }
+  }
+
+  const result = core ?? new Set();
+  cache.set(bucket, result);
+  return result;
+}
+
+/**
+ * ── ⭐ CONSTANT FIRST, CONDITIONAL LAST, EACH HALF IN ITS ORIGINAL ORDER ────
+ *
+ * ⚠️ A STABLE PARTITION, NOT A SORT. Both halves keep the order they arrived in
+ * — registry order, which is already deterministic — so this adds no second
+ * ordering rule that could disagree with the first. Two machines offering the
+ * same tools produce byte-identical output; two machines differing by one tool
+ * differ only in the tail.
+ *
+ * ⚠️ IT NEVER ADDS, REMOVES OR EDITS A SCHEMA. The output is a permutation of
+ * the input and nothing else — that property is what makes this safe to apply on
+ * the model's door, and it is asserted directly rather than reviewed.
+ *
+ * @param {Array<{ function?: { name?: string } }>} schemas as `toolSchemasFor` returned them
+ * @param {{ maxRounds?: number }} [opts]
+ * @returns {Array<any>} the same schemas, constant ones first
+ */
+export function orderForCachePrefix(schemas, { maxRounds = 8 } = {}) {
+  if (!Array.isArray(schemas) || schemas.length === 0) return Array.isArray(schemas) ? [...schemas] : [];
+  const core = alwaysOfferedNames(maxRounds);
+  const isCore = (t) => core.has(t?.function?.name);
+  return [...schemas.filter(isCore), ...schemas.filter((t) => !isCore(t))];
+}

package/lib/tool-shortlist.mjs

@@ -0,0 +1,162 @@
+/**
+ * ── ⭐⭐⭐ STOP NEEDING TO SEND 63 SCHEMAS ────────────────────────────────────
+ *
+ * Roman, 2026-08-20, on our own 100% cache number: *"a high-90s hit rate usually
+ * means your software is sending the exact same large prompt over and over."*
+ *
+ * ⚠️ HALF WRONG AND HALF EXACTLY RIGHT, and the right half is this file. The
+ * tool block MUST be re-sent every round — that is how chat-completions work,
+ * not redundancy anyone chose — so caching it is the correct fix. But caching
+ * makes 14,213 tokens *cheap*, not *free*: a cached read is still billed at
+ * roughly a tenth, and it still occupies the context window, which is the
+ * resource no cache refunds.
+ *
+ * MEASURED TODAY: `toolNamesForRounds` varies the offer by ROUND BUDGET and
+ * nothing else — 47 tools at every budget above one. So "fix this typo" carries
+ * the identical ~12k-token surface as "refactor the auth system".
+ *
+ * ⭐ THE EVIDENCE THIS IS WORTH DOING: adaptive shortlisting measured **93.1% vs
+ * 87.1%** overall and **76.8% vs 60.9%** on medium-difficulty queries against a
+ * fixed offer. Fewer, better-chosen tools beat more tools.
+ *
+ * ⚠️⚠️ AND THE FAILURE MODE THAT MAKES NAIVE SHORTLISTING WORSE THAN NOTHING:
+ * withholding a tool the task actually needed. This repo has already measured
+ * that **tool search fails on PARAPHRASE, not ranking** — a user who says
+ * "commit this" and one who says "save my work to version control" are the same
+ * intent and only one matches a keyword. So the design here is deliberately not
+ * a classifier:
+ *
+ *   1. a CORE set is ALWAYS offered — the spine of any coding task;
+ *   2. optional groups are ADDED on signal, never subtracted;
+ *   3. ⭐ and the moment the model reaches for something it was not given, the
+ *      next round gets EVERYTHING. Widening is automatic and permanent for the
+ *      session, so the worst case is one wasted round rather than a task the
+ *      agent cannot finish.
+ *
+ * That third rule is what makes this safe to ship. A shortlist you cannot escape
+ * is a capability ceiling; a shortlist that opens the moment it is wrong is an
+ * optimisation.
+ */
+
+/**
+ * The spine. Every one of these is reachable from almost any coding task, and
+ * the cost of withholding one is a failed run.
+ *
+ * ⚠️ GENEROUS ON PURPOSE. The saving comes from the groups below, which are
+ * large and specialised; shaving the core would buy little and risk much.
+ */
+export const CORE_TOOLS = Object.freeze([
+  'read_file', 'read_lines', 'read_around', 'list_dir', 'find_files', 'search_text',
+  'write_file', 'write_files', 'edit_file', 'move_file', 'delete_file',
+  'run_command', 'evaluate',
+  'plan_start', 'plan_step', 'plan_status',
+  'check_acceptance', 'declare_acceptance',
+  'read_skill', 'remember', 'forget', 'ask_user', 'delegate',
+]);
+
+/**
+ * Specialised groups, each with the words that mean "this task is about that".
+ *
+ * ⚠️ THE WORDS ARE A HINT, NOT A GATE. Missing one costs a single round because
+ * of the widening rule; there is no need for them to be exhaustive, and pretending
+ * they could be is how a keyword list becomes a capability ceiling.
+ */
+export const TOOL_GROUPS = Object.freeze({
+  vcs: {
+    tools: ['git_status', 'git_diff', 'git_log', 'git_commit', 'git_branch', 'git_push', 'gh_issue', 'gh_pr', 'gh_run'],
+    words: ['git', 'commit', 'branch', 'merge', 'rebase', 'pr', 'pull request', 'push', 'issue', 'github', 'review', 'diff', 'changelog', 'version control', 'ci', 'workflow', 'release'],
+  },
+  process: {
+    tools: ['start_process', 'stop_process', 'check_process', 'read_log', 'wait_for_output', 'summarize_log', 'call_endpoint'],
+    words: ['server', 'dev server', 'run it', 'serve', 'port', 'localhost', 'api', 'endpoint', 'daemon', 'watch', 'log', 'logs', 'background', 'start', 'boot', 'listen'],
+  },
+  intel: {
+    tools: ['check_types', 'find_definition', 'find_references', 'list_symbols', 'review_code'],
+    words: ['type', 'types', 'typescript', 'tsc', 'refactor', 'rename', 'definition', 'reference', 'symbol', 'interface', 'signature', 'review', 'audit', 'lint'],
+  },
+  db: {
+    tools: ['inspect_db', 'sample_db_rows'],
+    words: ['database', 'db', 'sql', 'table', 'schema', 'query', 'postgres', 'sqlite', 'migration', 'row', 'rows'],
+  },
+  web: {
+    tools: ['web_search', 'fetch_url', 'see_page'],
+    words: ['search', 'docs', 'documentation', 'look up', 'website', 'url', 'http', 'scrape', 'fetch', 'browse', 'page', 'screenshot', 'render'],
+  },
+  media: {
+    tools: ['generate_image', 'edit_image', 'expand_image', 'read_image', 'speak', 'transcribe', 'list_engines'],
+    words: ['image', 'picture', 'photo', 'logo', 'icon', 'illustration', 'voice', 'speak', 'audio', 'speech', 'transcribe', 'video', 'render', 'design', 'visual'],
+  },
+  docs: {
+    tools: ['make_document', 'read_document', 'read_table'],
+    words: ['document', 'pdf', 'docx', 'spreadsheet', 'csv', 'excel', 'report', 'table', 'export'],
+  },
+  repl: {
+    tools: ['repl', 'repl_reset', 'run_program'],
+    words: ['repl', 'interactive', 'experiment', 'try', 'explore', 'inspect', 'debug', 'session', 'python', 'node script'],
+  },
+  session: {
+    tools: ['list_sessions'],
+    words: ['session', 'resume', 'earlier', 'previous run', 'last time', 'history'],
+  },
+});
+
+const norm = (s) => String(s ?? '').toLowerCase();
+
+/** Which groups a task's own words point at. */
+export function groupsForTask(task) {
+  const text = norm(task);
+  if (!text.trim()) return Object.keys(TOOL_GROUPS);
+  const hit = [];
+  for (const [name, g] of Object.entries(TOOL_GROUPS)) {
+    if (g.words.some((w) => text.includes(w))) hit.push(name);
+  }
+  return hit;
+}
+
+/**
+ * The tools to offer for this task.
+ *
+ * @param {string} task the user's brief, verbatim
+ * @param {readonly string[]} available what the environment actually allows —
+ *   the shortlist may only ever be a SUBSET of this. Withdrawal (no shell, no
+ *   browser, no key) has already been decided upstream and must not be undone
+ *   here; a shortlist that re-offers a withdrawn tool is worse than no shortlist.
+ * @param {{ widened?: boolean }} [opts] `widened` is set once the model has
+ *   reached for something it was not given, and never unset for the session.
+ */
+export function shortlistTools(task, available, { widened = false } = {}) {
+  const allowed = new Set(available ?? []);
+  /**
+   * ⚠️ WIDENED IS ABSOLUTE. Once the model has demonstrated the shortlist was
+   * wrong, guessing again is how a run oscillates between two wrong offers.
+   */
+  if (widened) return [...allowed];
+
+  /**
+   * ⚠️ AN EMPTY OR VERY SHORT BRIEF OFFERS EVERYTHING. "fix it" carries no
+   * signal, and a shortlist built from no evidence is a guess with consequences.
+   */
+  const text = norm(task);
+  if (text.trim().length < 12) return [...allowed];
+
+  const keep = new Set(CORE_TOOLS.filter((t) => allowed.has(t)));
+  for (const name of groupsForTask(task)) {
+    for (const t of TOOL_GROUPS[name].tools) if (allowed.has(t)) keep.add(t);
+  }
+  // `finish` and anything else the environment offers that we do not classify
+  // stays IN — an unclassified tool is one we do not understand, and dropping
+  // what you do not understand is how capability disappears quietly.
+  for (const t of allowed) {
+    if (!Object.values(TOOL_GROUPS).some((g) => g.tools.includes(t))) keep.add(t);
+  }
+  return [...allowed].filter((t) => keep.has(t));
+}
+
+/**
+ * Did the model just reach for a tool it was not given? That is the signal to
+ * widen — and it is a FACT, not a heuristic.
+ */
+export function shouldWiden(calledNames, offered) {
+  const have = new Set(offered ?? []);
+  return (calledNames ?? []).some((n) => typeof n === 'string' && n && !have.has(n));
+}