acuvo-code 0.2.0

package/lib/memory-workspace.mjs

@@ -0,0 +1,179 @@
+/**
+ * ── ⭐ THE SECOND EXECUTOR — ONE LOOP, TWO CLIENTS, FINALLY REAL ─────────────
+ *
+ * "One registry, two clients" has been the stated architecture for weeks. It was
+ * measured on 2026-08-09 and found to be fiction: the CLI has 13 verbs, the
+ * console has 153 tools, and the overlap is ZERO. Two forked registries sharing
+ * a doctrine paragraph.
+ *
+ * ⭐ AND IT EXPLAINS THE PEER GAP. We generate a PAGE where Manus/Replit/Base44
+ * generate an APPLICATION, and the cause is not the model — it is that the
+ * builder has no write→run→fix loop. It cannot run what it wrote, so it cannot
+ * fix what it wrote. The CLI has exactly that loop and it works: 7/7 on the
+ * bench, and it went 5/7 → 7/7 with NO MODEL CHANGE, purely on loop fixes.
+ *
+ * ⚠️ SO THE ANSWER IS NOT A SECOND LOOP. Forking `turn.mjs` for the browser is
+ * how we got here. This file is the other half of the seam: the SAME
+ * `runSession` gets an executor whose disk is a Map instead of a filesystem.
+ *
+ *   CLI      → createLocalExecutor(dir)      → real files, child_process
+ *   BUILDER  → createMemoryExecutor({...})   → a file MAP, Modal sandbox
+ *
+ * ── ⚠️ WHY THE BUILDER'S WORKSPACE IS A MAP AND NOT A TEMP DIRECTORY ────────
+ * A browser session has no disk of its own, and giving each one a server-side
+ * temp directory would mean per-tenant cleanup, disk quotas and a new class of
+ * path-escape bug on a multi-tenant box. The generated files already live in
+ * memory (see `generated-files.ts`), and `runInSandbox` takes exactly
+ * `Record<string, string>` — so the natural representation is the one both ends
+ * already speak. Nothing is written to the server's disk, ever.
+ *
+ * ── ⚠️ THE DEPENDENCY DIRECTION IS DELIBERATE ───────────────────────────────
+ * This module does NOT import the Modal sandbox, or anything from console/. It
+ * takes a `runCommand` function. `acuvo-code/` stays zero-dependency and
+ * runnable on its own; the console injects the sandbox when it constructs the
+ * executor. Importing upward would make the CLI depend on Next.js, which is how
+ * a shared core stops being shareable.
+ */
+
+import { normalizeRelativePath } from './workspace.mjs';
+
+/** Mirrors the local executor's ceiling so the two agree about what is too big. */
+export const MAX_MEMORY_FILE_BYTES = 512 * 1024;
+/**
+ * ⚠️ A TOTAL CAP, WHICH THE LOCAL EXECUTOR DOES NOT NEED. A real disk pushes
+ * back; a Map on a shared server does not, and an agent in a loop writing
+ * megabytes per round is a memory leak with a plausible explanation.
+ */
+export const MAX_MEMORY_TOTAL_BYTES = 8 * 1024 * 1024;
+export const MAX_MEMORY_FILES = 400;
+
+const bytes = (s) => Buffer.byteLength(s, 'utf8');
+
+/**
+ * An executor whose filesystem is a Map<string, string>.
+ *
+ * @param {{
+ *   files?: Record<string, string>,
+ *   dryRun?: boolean,
+ *   runCommand?: (command: string, files: Record<string, string>) => Promise<any>,
+ * }} [opts]
+ */
+export function createMemoryExecutor({ files = {}, dryRun = false, runCommand = null } = {}) {
+  /** @type {Map<string, string>} */
+  const disk = new Map();
+  for (const [path, content] of Object.entries(files)) {
+    const norm = normalizeRelativePath(path);
+    // A malformed seed path is dropped rather than thrown: the caller is often
+    // handing over model-generated filenames, and one bad name must not take
+    // down a session that could still do useful work with the rest.
+    if (norm.ok && typeof content === 'string') disk.set(norm.path, content);
+  }
+
+  const totalBytes = () => [...disk.values()].reduce((a, c) => a + bytes(c), 0);
+
+  return {
+    /**
+     * ⚠️ A LABEL, NOT A PATH. The local executor's `root` is a real directory
+     * and several call sites `join()` with it. Nothing may do that here, so it
+     * is deliberately not path-shaped — a silent `join('(memory)', x)` producing
+     * a relative path that half-works is worse than an obvious break.
+     */
+    root: '(memory)',
+    dryRun,
+    /** ⭐ How the caller gets the work back out — the whole point of the run. */
+    snapshot() { return Object.fromEntries(disk); },
+
+    readFile(path) {
+      const r = normalizeRelativePath(path);
+      if (!r.ok) return { ok: false, error: r.reason };
+      if (!disk.has(r.path)) return { ok: false, error: `no such file: ${r.path}` };
+      const content = disk.get(r.path);
+      return { ok: true, path: r.path, content, bytes: bytes(content) };
+    },
+
+    writeFile(path, content) {
+      const r = normalizeRelativePath(path);
+      if (!r.ok) return { ok: false, error: r.reason };
+      if (typeof content !== 'string') return { ok: false, error: 'content must be a string' };
+      const size = bytes(content);
+      if (size > MAX_MEMORY_FILE_BYTES) {
+        return { ok: false, error: `${r.path} would be ${size} bytes, over the ${MAX_MEMORY_FILE_BYTES}-byte limit` };
+      }
+      const existed = disk.has(r.path);
+      const previousBytes = existed ? bytes(disk.get(r.path)) : 0;
+      if (!existed && disk.size >= MAX_MEMORY_FILES) {
+        return { ok: false, error: `this workspace already holds ${disk.size} files, the maximum` };
+      }
+      if (totalBytes() - previousBytes + size > MAX_MEMORY_TOTAL_BYTES) {
+        return { ok: false, error: `that write would take the workspace over its ${MAX_MEMORY_TOTAL_BYTES}-byte total` };
+      }
+      // ⚠️ A dry run must not mutate, but must still report what WOULD happen —
+      // same contract as the local executor, or the two clients diverge in the
+      // one mode where a user is deliberately being careful.
+      if (!dryRun) disk.set(r.path, content);
+      return { ok: true, path: r.path, bytes: size, created: !existed, previousBytes, dryRun };
+    },
+
+    deleteFile(path) {
+      const r = normalizeRelativePath(path);
+      if (!r.ok) return { ok: false, error: r.reason };
+      if (!disk.has(r.path)) return { ok: false, error: `no such file: ${r.path} — nothing was deleted` };
+      const size = bytes(disk.get(r.path));
+      if (!dryRun) disk.delete(r.path);
+      return { ok: true, path: r.path, bytes: size, dryRun };
+    },
+
+    /**
+     * A Map has no directories, so they are DERIVED from the path segments.
+     * ⚠️ The shape must match the local executor's exactly — `{ name, type,
+     * bytes }` — because `gatherWorkspaceContext` walks it and would otherwise
+     * silently produce an empty tree for the builder while working for the CLI.
+     */
+    listDir(path = '.') {
+      let prefix = '';
+      if (path && path !== '.' && path !== './') {
+        const r = normalizeRelativePath(path);
+        if (!r.ok) return { ok: false, error: r.reason };
+        prefix = `${r.path}/`;
+      }
+      const seen = new Map();
+      for (const [p, content] of disk) {
+        if (prefix && !p.startsWith(prefix)) continue;
+        const rest = p.slice(prefix.length);
+        const slash = rest.indexOf('/');
+        if (slash === -1) seen.set(rest, { name: rest, type: 'file', bytes: bytes(content) });
+        else {
+          const dir = rest.slice(0, slash);
+          if (!seen.has(dir)) seen.set(dir, { name: dir, type: 'dir' });
+        }
+      }
+      if (prefix && seen.size === 0) return { ok: false, error: `no such directory: ${path}` };
+      return {
+        ok: true,
+        path: prefix ? prefix.slice(0, -1) : '.',
+        entries: [...seen.values()].sort((a, b) => a.name.localeCompare(b.name)),
+      };
+    },
+
+    /**
+     * ⭐ THE HALF THAT MAKES IT A BUILDER AND NOT A GENERATOR.
+     *
+     * Injected, never imported — see the header. The console passes a function
+     * that ships `snapshot()` to the Modal sandbox; a test passes a stub; the
+     * CLI never constructs this executor at all.
+     *
+     * ⚠️ AND WHEN IT IS ABSENT THE ANSWER IS AN HONEST REFUSAL, not a fake pass.
+     * A builder whose "run" silently succeeds without running is the exact
+     * dead-button failure this codebase keeps re-learning: the model believes
+     * its code is verified, says so, and ships something nobody executed.
+     */
+    async runCommand(command) {
+      if (typeof runCommand !== 'function') {
+        return { ok: false, error: 'no sandbox is configured for this workspace, so nothing can be run or verified here' };
+      }
+      return runCommand(command, Object.fromEntries(disk));
+    },
+
+    hasRunner: typeof runCommand === 'function',
+  };
+}

package/lib/model-json.mjs

@@ -0,0 +1,132 @@
+/**
+ * ── ⚠️⚠️ CLAMPED JSON IS UNPARSEABLE JSON ───────────────────────────────────
+ *
+ * `toolResultText` formats 24 of the 63 dispatched tools. The other 39 fall to
+ * `default: clampOutput(JSON.stringify(result))` — and so does **every MCP
+ * result**, whose names are `mcp__<server>__<tool>` and can never match a case.
+ *
+ * `clampOutput` is well built for what it was written for: it keeps 35% head and
+ * 65% tail and splices `… N characters omitted …` between them, so nothing is
+ * lost silently and trailing fields survive. On PROSE that degrades gracefully.
+ *
+ * ⚠️ On a serialised object it does not degrade — it breaks. The splice lands
+ * mid-object and the result is no longer JSON at all. Measured on `git_diff`
+ * against an ordinary 400-line refactor: an 8,030-character reply that
+ * `JSON.parse` rejects. The model is then reading a broken object and inferring
+ * its fields, which is the failure mode an earlier audit recorded as *"search
+ * results were arriving 19% complete, as broken JSON"*.
+ *
+ * ⭐ THE FIX IS TO SHRINK THE PAYLOAD, NOT THE SYNTAX. Cut the big string
+ * FIELDS inside the object until the whole thing fits, and the reply stays
+ * valid JSON with every flag, every count and every pagination cursor intact.
+ * A `diff` or a `stdout` is what is actually large; `ok`, `truncated` and
+ * `nextPage` are bytes that must never be the ones sacrificed.
+ *
+ * ⚠️ It shrinks the LARGEST field first and re-measures each time, rather than
+ * dividing a budget evenly. A result carrying one 9KB `diff` beside a 40-char
+ * `path` should lose only diff — an even split would mangle both.
+ */
+
+/** Mirrors `clampOutput`'s split so truncation reads the same everywhere. */
+function spliceMiddle(text, budget) {
+  const head = Math.floor(budget * 0.35);
+  const tail = budget - head;
+  const omitted = text.length - budget;
+  return `${text.slice(0, head)}\n\n… ${omitted} characters omitted …\n\n${text.slice(-tail)}`;
+}
+
+/**
+ * ⚠️ A floor, so a field is never cut to uselessness. Below this there is no
+ * point keeping the field's content at all — a 20-character window of a diff
+ * tells the model nothing and still costs it a read.
+ */
+const MIN_FIELD_CHARS = 200;
+
+/** Every string field big enough to be worth cutting, deepest-first by size. */
+function largeStrings(value, path = [], out = []) {
+  if (typeof value === 'string') {
+    if (value.length > MIN_FIELD_CHARS) out.push({ path, length: value.length });
+    return out;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((v, i) => largeStrings(v, [...path, i], out));
+    return out;
+  }
+  if (value && typeof value === 'object') {
+    for (const [k, v] of Object.entries(value)) largeStrings(v, [...path, k], out);
+  }
+  return out;
+}
+
+function getAt(root, path) {
+  return path.reduce((acc, key) => acc?.[key], root);
+}
+
+function setAt(root, path, next) {
+  const parent = path.slice(0, -1).reduce((acc, key) => acc[key], root);
+  parent[path[path.length - 1]] = next;
+}
+
+/**
+ * Serialise a tool result for the model, keeping it VALID JSON at any size.
+ *
+ * @param {unknown} result   the tool's return value
+ * @param {number}  maxChars the same ceiling the formatted branches use
+ * @returns {string} JSON that parses, whose large string fields may be spliced
+ */
+export function stringifyForModel(result, maxChars) {
+  let json = JSON.stringify(result);
+  if (typeof json !== 'string') return '';
+  if (json.length <= maxChars) return json;
+
+  /**
+   * ⚠️ Deep-cloned, because this renders a LIVE result object that callers keep
+   * using — the transcript writer and the usage recorder both read it after we
+   * are done. Truncating in place would corrupt the record of what the tool
+   * actually returned, which is the one copy that has to stay true.
+   */
+  const clone = structuredClone(result);
+  const fields = largeStrings(clone).sort((a, b) => b.length - a.length);
+
+  for (const field of fields) {
+    if (json.length <= maxChars) break;
+    const current = getAt(clone, field.path);
+    if (typeof current !== 'string') continue;
+
+    /**
+     * How much this one field must give up for the whole reply to fit, with a
+     * little slack for the `… N characters omitted …` marker we splice in.
+     */
+    const excess = json.length - maxChars;
+    const budget = Math.max(MIN_FIELD_CHARS, current.length - excess - 80);
+    if (budget >= current.length) continue;
+
+    setAt(clone, field.path, spliceMiddle(current, budget));
+    json = JSON.stringify(clone);
+  }
+
+  /**
+   * ⚠️ THE HONEST FLOOR. If the size lives in structure rather than in strings —
+   * ten thousand tiny array entries — no amount of field-cutting reaches it, and
+   * cutting the JSON string would put us back where we started. Say so in a way
+   * that still parses, and keep the fields that describe the result over the
+   * ones that are the result.
+   */
+  if (json.length > maxChars) {
+    const note = {
+      ok: result?.ok,
+      error: result?.error,
+      _truncated: true,
+      _note: `this result was ${json.length} characters and could not be reduced to ${maxChars} `
+        + 'by trimming its text fields — its size is in structure, not prose. '
+        + 'Request a narrower slice (a smaller range, an offset, or a single path).',
+    };
+    for (const [k, v] of Object.entries(result ?? {})) {
+      if (typeof v === 'number' || typeof v === 'boolean') note[k] = v;
+    }
+    const fallback = JSON.stringify(note);
+    return fallback.length <= maxChars ? fallback : JSON.stringify({ ok: false, _truncated: true });
+  }
+
+  return json;
+}

package/lib/model-tier.mjs

@@ -0,0 +1,171 @@
+/**
+ * ── ⭐ THE LADDER RETRIED WITH THE SAME MODEL, WHICH IS THE WEAK VERSION ────
+ *
+ * `escalate.mjs` climbs solo → fresh context → best-of N, and every rung asked
+ * **the same model** the failing one used. That is the cheapest kind of "try
+ * harder": a fresh context helps because the old one was poisoned, and parallel
+ * attempts help because sampling varies — but neither adds capability the model
+ * did not have on the first try.
+ *
+ * ⭐ Model tiers add the missing axis. A rung can be given a STRONGER model, so
+ * "spend more on the hard ones" becomes true of the thing doing the work and not
+ * only of how many times it is asked.
+ *
+ * ── ⚠️⚠️ OFF BY DEFAULT, AND THE REASON IS ARITHMETIC, NOT CAUTION ─────────
+ *
+ * `escalate.projectTierCost` prices the next rung from **what the last attempt
+ * measurably cost**. That is the honest way to project when the model is
+ * constant, and it is WRONG the moment it is not: a rung on a model that costs
+ * 20x per token would be projected at 3x the price of a cheap attempt, the
+ * budget would wave it through, and the ceiling the user typed would be crossed
+ * by an order of magnitude — by the one code path whose entire job is not to do
+ * that.
+ *
+ * We cannot fix that by guessing prices: this package has no price table, and a
+ * wrong one is worse than none. So:
+ *
+ *   · with no configuration, every tier is the SAME model and nothing changes;
+ *   · configuring tiers is an explicit act (`ACUVO_MODEL_TIERS`), which is the
+ *     user saying "I know what these cost";
+ *   · and when a rung's model differs from the previous rung's, the caller is
+ *     TOLD (`changed: true`) so the projection can be widened rather than
+ *     quietly trusted.
+ *
+ * ⭐ The default therefore costs nothing and changes nothing, which is the only
+ * safe shape for a feature that can multiply a bill.
+ */
+
+/** The variable that turns this on. Cheapest first, strongest last. */
+export const TIERS_ENV = 'ACUVO_MODEL_TIERS';
+
+/**
+ * ⚠️ A CEILING ON HOW FAR A SINGLE RUN CAN ESCALATE. Someone will paste a list
+ * of ten models; the ladder has three rungs and the rest would be dead config
+ * that reads as if it were doing something.
+ */
+export const MAX_TIERS = 4;
+
+/**
+ * Parse the configured ladder.
+ *
+ * ⚠️ AN EMPTY OR ABSENT VARIABLE IS NOT AN ERROR — it is the normal case, and
+ * it means "one tier: whatever the run is already using".
+ *
+ * @param {string} baseModel
+ * @param {object} env
+ * @returns {string[]} cheapest first, always at least one entry
+ */
+/**
+ * ── ⭐⭐ THE ESCALATION MODEL, ON BY DEFAULT ────────────────────────────────
+ *
+ * This ladder climbs solo → fresh context → best-of-N, and until now every rung
+ * ran the SAME cheap model. So the loop got more determined and never got
+ * smarter, and every benchmark number this package holds is a FLOOR taken with
+ * one hand tied: 19 of 19 runs measured on flash, with the stronger rungs
+ * switched off and nobody having tried them.
+ *
+ * ⭐ THE ARITHMETIC THAT MAKES IT AFFORDABLE, and it is not what you would
+ * guess. Pro is 3.1x flash on a cache MISS and 3.1x on OUTPUT — but only
+ * **1.29x on a cache HIT** ($0.0036/M against $0.0028/M direct). At the cache
+ * rates this package now sustains, pro's INPUT is nearly flash's price and the
+ * entire gap is output.
+ *
+ * ⭐ AND ESCALATION IS ALREADY FRESH-CONTEXT, WHICH IS WHAT MAKES THE SWITCH
+ * CHEAP. `escalate.mjs` passes the TASK to each rung, never the transcript, so
+ * moving to a different model does not re-send a 41,000-token conversation at
+ * the dearer model's miss price. A prompt cache is per-model — switching MID-
+ * CONVERSATION would cost a full cold prompt every time, and nothing about this
+ * default does that.
+ *
+ * ⚠️ MODELLED, NOT MEASURED: at ~8% of tasks escalating (our bench passes 12 of
+ * 13 on flash alone), the blended cost is about $4.13 per user-month against
+ * $3.28 for flash-only — 78% margin instead of 83%. Five points of margin to
+ * put a materially better model on the tasks that already failed once. How much
+ * pro actually BUYS is still unmeasured; that is a bench run, not an opinion.
+ *
+ * ⚠️ THE DATED SNAPSHOT IS DELIBERATE. `deepseek-v4-pro-0813` is $0.435/M;
+ * the undated `deepseek-v4-pro` pointer is $1.168/M — 2.7x dearer for what is
+ * meant to be the same family. Pinning the snapshot is both cheaper and
+ * reproducible, and a moving pointer under a benchmark is how a "regression"
+ * appears that nobody changed.
+ *
+ * ⚠️ Set `ACUVO_MODEL_TIERS` to override, or to a single id to switch this off.
+ */
+export const DEFAULT_ESCALATION_MODEL = 'deepseek/deepseek-v4-pro-0813';
+
+export function parseTiers(baseModel, env = process.env) {
+  const raw = String(env?.[TIERS_ENV] ?? '').trim();
+  /**
+   * ⚠️ THE BASE MODEL STAYS RUNG ZERO, WHATEVER THE USER CONFIGURED. This adds a
+   * rung above it; it never replaces the model somebody chose. And when the base
+   * IS the escalation model — somebody set `OPENROUTER_CODEGEN_MODEL` to pro —
+   * the ladder collapses to one entry rather than listing pro twice, because
+   * `modelForRung` reuses the last tier and a duplicate would read as a switch
+   * that is not happening.
+   */
+  if (raw === '') {
+    return baseModel === DEFAULT_ESCALATION_MODEL
+      ? [baseModel]
+      : [baseModel, DEFAULT_ESCALATION_MODEL];
+  }
+
+  const seen = new Set();
+  const tiers = [];
+  for (const part of raw.split(',')) {
+    const id = part.trim();
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    tiers.push(id);
+    if (tiers.length >= MAX_TIERS) break;
+  }
+  return tiers.length > 0 ? tiers : [baseModel];
+}
+
+/**
+ * Which model a given rung should use.
+ *
+ * ⚠️ THE LAST TIER IS REUSED, NEVER WRAPPED. With two tiers configured and three
+ * rungs, the third rung gets the strongest configured model — not tier[0] again.
+ * Wrapping would send the hardest attempt to the weakest model, which is the
+ * exact inverse of the feature.
+ *
+ * @param {number} rungIndex  0-based position in the ladder
+ * @param {string[]} tiers
+ * @returns {string}
+ */
+export function modelForRung(rungIndex, tiers) {
+  const list = Array.isArray(tiers) && tiers.length > 0 ? tiers : [null];
+  const i = Math.max(0, Math.min(list.length - 1, Number.isInteger(rungIndex) ? rungIndex : 0));
+  return list[i];
+}
+
+/**
+ * What model does this rung use, and is it a different one from last time?
+ *
+ * `changed` is the load-bearing field: it is the signal that a cost projection
+ * derived from the previous rung no longer applies.
+ *
+ * @returns {{model: string, changed: boolean, tier: number, of: number}}
+ */
+export function planRung(rungIndex, { baseModel, env = process.env, previousModel = null } = {}) {
+  const tiers = parseTiers(baseModel, env);
+  const model = modelForRung(rungIndex, tiers);
+  return {
+    model,
+    changed: previousModel !== null && previousModel !== model,
+    tier: Math.min(rungIndex, tiers.length - 1),
+    of: tiers.length,
+  };
+}
+
+/**
+ * One line for a human when the ladder changes model mid-run.
+ *
+ * ⚠️ SAID OUT LOUD, ALWAYS. A run that silently switches to a pricier model has
+ * changed what it costs without telling the person paying, and "why was this
+ * bill different" must never be unanswerable.
+ */
+export function describeSwitch(from, to) {
+  if (!from || !to || from === to) return null;
+  return `escalating the model as well: ${from} → ${to} (its price is not projected from the previous rung — see --budget)`;
+}