acuvo-code 0.5.3 → 0.6.0

package/lib/input-box.mjs

@@ -66,7 +66,14 @@ export function visibleWidth(s) {
  *
  * @returns {{lines: string[], cursorColumn: number}} 1-based cursor column
  */
-export function renderBox({ value = '', cursor = 0, columns = 80, prompt = '› ' } = {}) {
+/**
+ * The names offered by the slash menu. Passed in rather than imported so this
+ * module keeps no opinion about what commands exist — `slash.mjs` owns that
+ * list, and a second copy here would drift the first time one is added.
+ */
+export const DEFAULT_COMMANDS = Object.freeze(['help', 'skills', 'mcp', 'cost', 'model', 'clear']);
+
+export function renderBox({ value = '', cursor = 0, columns = 80, prompt = '› ', commands = DEFAULT_COMMANDS } = {}) {
   /**
    * ── ⚠️ FULL WIDTH. THE 100-COLUMN CAP WAS WRONG AND IT LOOKED WRONG ────────
    *
@@ -113,13 +120,48 @@ export function renderBox({ value = '', cursor = 0, columns = 80, prompt = '›
    * ⚠️ Two rows, not three — so the reserved region shrinks with it and the
    * transcript gets a row back.
    */
+  /**
+   * ── ⭐⭐⭐ THE SLASH MENU — WHAT YOU CAN DO, AT THE MOMENT YOU ASK ───────────
+   *
+   * Roman: *"when users do a special Acuvo command it changes the colour and
+   * also shows you your options in a dropdown."*
+   *
+   * ⭐ THIS IS THE DISCOVERABILITY FIX, NOT DECORATION. 28 skills, 7 commands,
+   * MCP in both directions — all built, and nothing on screen ever mentioned
+   * any of it. A capability nobody is shown is worth zero, which is the same
+   * defect as the toolbox and the whiteboard. Typing one character is the
+   * cheapest possible moment to answer "what can this thing do".
+   *
+   * ⚠️ IT REPLACES THE RULE RATHER THAN ADDING A ROW. The input lives in a
+   * reserved region of fixed height; growing it would mean resizing the scroll
+   * region mid-keystroke, and a region that changes size while a transcript is
+   * scrolling through it is how the display gets corrupted. The rule is already
+   * a full-width line doing nothing — so it becomes the menu while a command is
+   * being typed, and goes back to being a rule the moment it is not.
+   */
+  const slash = /^\/(\S*)$/.exec(value);
+  let rule = '─'.repeat(width);
+  if (slash) {
+    const typed = slash[1].toLowerCase();
+    const matches = commands.filter((c) => c.startsWith(typed));
+    /**
+     * ⚠️ NO MATCHES IS ITS OWN ANSWER. Falling back to the full list would tell
+     * somebody who mistyped that everything is fine; saying so is what lets them
+     * fix it.
+     */
+    const shown = matches.length ? matches.map((c) => `/${c}`).join('  ') : 'no command starts with that';
+    const label = `  ${shown}  `;
+    rule = visibleWidth(label) >= width
+      ? label.slice(0, width)
+      : `${label}${'─'.repeat(width - visibleWidth(label))}`;
+  }
+
   return {
-    lines: [
-      '─'.repeat(width),
-      `${body}${pad}`,
-    ],
+    lines: [rule, `${body}${pad}`],
     // 1-based, and there is no left border to skip any more.
     cursorColumn: 1 + promptWidth + (cursor - start),
+    /** True while a slash command is being typed — the caller paints it. */
+    isCommand: Boolean(slash),
   };
 }
 
@@ -238,8 +280,23 @@ export function splitKeys(chunk) {
  * to the end of each border as it is written — which reads as a flicker and is
  * the difference between a rendered box and a drawn one.
  */
-export function paint(output, state, { first = false, atRow = 0 } = {}) {
-  const { lines, cursorColumn } = renderBox(state);
+export function paint(output, state, { first = false, atRow = 0, paintFn = null } = {}) {
+  const r = renderBox(state);
+  const { cursorColumn } = r;
+  /**
+   * ── ⭐ THE INPUT TURNS BRAND GREEN WHILE A COMMAND IS BEING TYPED ──────────
+   *
+   * Roman: *"it changes the colour and also shows you your options."* The colour
+   * is the faster half of that — it says "you are in a different mode" before
+   * anyone has read a single menu entry.
+   *
+   * ⚠️ THE PAINTER IS INJECTED and colour is applied AFTER layout, never before:
+   * escape codes have no width, so colouring a string and then padding it aligns
+   * the text against invisible bytes. `renderBox` stays pure and returns plain
+   * text; this is the only place that knows about colour.
+   */
+  const brand = (paintFn && r.isCommand) ? paintFn : null;
+  const lines = brand ? r.lines.map((l) => brand(l)) : r.lines;
 
   /**
    * ── ⭐⭐⭐ PINNED: DRAW AT AN ABSOLUTE ROW, NOT WHEREVER THE CURSOR IS ───────
@@ -311,7 +368,7 @@ export function paint(output, state, { first = false, atRow = 0 } = {}) {
  *
  * @returns {Promise<{value: string|null, reason: 'submit'|'cancel'|'eof'}>}
  */
-export function readBoxedLine({ input, output, history = [], onInterrupt = null, prompt = '› ', atRow = 0 }) {
+export function readBoxedLine({ input, output, history = [], onInterrupt = null, prompt = '› ', atRow = 0, commands = DEFAULT_COMMANDS, paintFn = null }) {
   return new Promise((resolve) => {
     let state = { value: '', cursor: 0, history, historyIndex: history.length, draft: '' };
     const columns = () => output.columns ?? process.stdout.columns ?? 80;
@@ -346,7 +403,7 @@ export function readBoxedLine({ input, output, history = [], onInterrupt = null,
          * instead of on top of it.
          */
         output.write(`${CSI}${atRow - 1};1H\n${prompt}${value ?? ''}\n`);
-        paint(output, { value: '', cursor: 0, columns: output.columns ?? 80 }, { atRow });
+        paint(output, { value: '', cursor: 0, columns: output.columns ?? 80, commands }, { atRow, paintFn });
         output.write(`${CSI}${atRow - 1};1H`);
       } else {
         /**
@@ -370,7 +427,7 @@ export function readBoxedLine({ input, output, history = [], onInterrupt = null,
         if (next.done === 'submit') {
           state = next;
           // Repaint once so the committed line is what stays on screen.
-          paint(output, { ...state, columns: columns() }, { atRow });
+          paint(output, { ...state, columns: columns(), commands }, { atRow, paintFn });
           return finish(state.value, 'submit');
         }
         if (next.done === 'cancel') {
@@ -392,18 +449,18 @@ export function readBoxedLine({ input, output, history = [], onInterrupt = null,
            */
           state = { ...state, value: '', cursor: 0, historyIndex: history.length, draft: '' };
           onInterrupt?.();
-          paint(output, { ...state, columns: columns() }, { atRow });
+          paint(output, { ...state, columns: columns(), commands }, { atRow, paintFn });
           continue;
         }
         if (next.done === 'eof') return finish(null, 'eof');
         state = next;
-        paint(output, { ...state, columns: columns() }, { atRow });
+        paint(output, { ...state, columns: columns(), commands }, { atRow, paintFn });
       }
     };
 
     try { input.setRawMode?.(true); } catch { /* not a TTY */ }
     input.resume?.();
-    paint(output, { ...state, columns: columns() }, { first: true, atRow });
+    paint(output, { ...state, columns: columns(), commands }, { first: true, atRow, paintFn });
     input.on('data', onData);
     input.once('end', onEnd);
   });

package/lib/tool-prefix.mjs

@@ -218,9 +218,45 @@ export function alwaysOfferedNames(maxRounds) {
  * @param {{ maxRounds?: number }} [opts]
  * @returns {Array<any>} the same schemas, constant ones first
  */
-export function orderForCachePrefix(schemas, { maxRounds = 8 } = {}) {
+export function orderForCachePrefix(schemas, { maxRounds = 8, shortlist = null } = {}) {
   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))];
+
+  /**
+   * ── 💰⭐⭐⭐ THE SHORTLIST GOES FIRST, OR A WIDEN BURNS THE WHOLE CACHE ──────
+   *
+   * MEASURED on a real brief, 2026-08-22: the narrow offer is 27 tools / 24,602
+   * bytes and the widened offer is 64 / 62,470 — and only **6,866 bytes were a
+   * shared prefix. 27.9%.** So widening rewrote 72% of the tools block, and
+   * `tool-prefix`'s own header measures that block at 94% of the shared head.
+   * One widen therefore threw away roughly **68% of everything cacheable.**
+   *
+   * ⚠️ AND THE ORDERING ABOVE DID NOT PREVENT IT. Sorting core-first is correct
+   * and insufficient: the SHORTLIST cuts across core-vs-conditional, so a
+   * shortlisted conditional tool sits after a non-shortlisted core one, and
+   * re-admitting the missing tools INTERLEAVES them into the middle of the
+   * block rather than appending.
+   *
+   * ⭐ THE FIX IS ORDER, NOT CONTENT. If the shortlisted tools are emitted FIRST
+   * in a stable order, the narrow block becomes a byte-prefix of the wide one —
+   * so widening APPENDS and everything already cached stays cached. The model
+   * gains capability and pays only for the tools it just gained.
+   *
+   * ⚠️ `shortlist` is optional and omitting it keeps the previous behaviour
+   * exactly, so nothing that does not know about this changes.
+   */
+  const inShortlist = shortlist ? new Set(shortlist) : null;
+  const rank = (t) => {
+    const name = t?.function?.name;
+    if (inShortlist) return inShortlist.has(name) ? (isCore(t) ? 0 : 1) : (isCore(t) ? 2 : 3);
+    return isCore(t) ? 0 : 1;
+  };
+  /**
+   * ⚠️ A STABLE SORT, AND NODE'S IS GUARANTEED STABLE since V8 7.0 — so tools of
+   * equal rank keep their registry order and the block is byte-identical run to
+   * run. An unstable sort here would change the prefix on every process for no
+   * reason at all, which is the same defect as the random sticky key.
+   */
+  return [...schemas].sort((a, b) => rank(a) - rank(b));
 }

package/lib/turn.mjs

@@ -2713,7 +2713,27 @@ export async function runSession({
    * definition — they are the one part of the block that CANNOT be shared — so
    * they belong behind everything that can be.
    */
-  const tools = [...orderForCachePrefix(toolSchemasFor(offered, { shell }), { maxRounds }), ...mcpSchemas];
+  /**
+   * ── 💰⭐⭐⭐ THE ORDERING KEY IS THE *NARROW* LIST, ALWAYS ────────────────────
+   *
+   * Computed with `widened: false` even after a widen, deliberately. It is not
+   * the set of tools to offer — it is the ORDER to emit them in, and it has to
+   * be the same before and after so the narrow block stays a byte-prefix of the
+   * wide one.
+   *
+   * MEASURED before this: a widen shared only **6,866 of 24,602 bytes — 27.9%**
+   * — with the rest of the tools block rewritten. `tool-prefix`'s own header
+   * puts that block at 94% of the shared head, so one widen threw away ~68% of
+   * everything cacheable. With the narrow list pinning the order: **100%.**
+   *
+   * ⚠️ Passing the WIDENED list here would silently undo it — the order would
+   * change the moment it widened, which is the exact failure being fixed.
+   */
+  const orderKey = shortlistEnabled ? shortlistTools(task ?? '', environmentOffer, { widened: false }) : null;
+  const tools = [
+    ...orderForCachePrefix(toolSchemasFor(offered, { shell }), { maxRounds, shortlist: orderKey }),
+    ...mcpSchemas,
+  ];
   /**
    * ⚠️ APPEND, NEVER REBUILD. The system prompt and the workspace context are the
    * cacheable prefix; a continuing turn adds one user message to the end and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acuvo-code",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Acuvo Code — the terminal client for the Acuvo capability registry. Zero dependencies, by design.",
   "type": "module",
   "bin": {