acuvo-code 0.5.3 → 0.5.4

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.5.4",
   "description": "Acuvo Code — the terminal client for the Acuvo capability registry. Zero dependencies, by design.",
   "type": "module",
   "bin": {