acuvo-code 0.2.0

package/lib/write-approval.mjs

@@ -0,0 +1,235 @@
+/**
+ * ── ⭐⭐ THE PER-RUN HALF OF WRITE APPROVAL ─────────────────────────────────
+ *
+ * `diff-preview.mjs` is complete and was reachable from nothing. Its own running
+ * list entry says exactly what was missing, and it is only this:
+ *
+ *   > `executeToolCall` "is a pure switch over a single call and has no memory of
+ *   > the round before it", and `approvalDecision` needs two facts that span
+ *   > rounds — `createdThisRun` (so the agent revising its own draft is never
+ *   > queried) and `sessionApproved` (the "all remaining" answer).
+ *
+ * So this file is the memory, and nothing else. All the judgement — what counts
+ * as risky, what a diff looks like, what the prompt says — already lives in
+ * `diff-preview.mjs` and is not duplicated here.
+ *
+ * ── ⚠️ THE GATE IS ON THE MODEL'S DOOR, NOT IN THE EXECUTOR ─────────────────
+ * `tools.mjs` states the rule for the credential guard and it applies verbatim:
+ * *"THE GUARD IS HERE, ON THE MODEL'S DOOR, NOT IN THE EXECUTOR … a model-facing
+ * refusal pushed down into shared plumbing broke seven tests of legitimate
+ * internal work."* Approval is a model-facing refusal. Hooking
+ * `workspace.writeFile` would gate `--doctor`, checkpoint restores and the
+ * acceptance harness too — none of which is a model asking to change your files.
+ *
+ * ── ⚠️⚠️ AND IT NEVER BLOCKS AN UNATTENDED RUN ─────────────────────────────
+ * `diff-preview.mjs`'s header settles this and the reasoning is inherited whole:
+ * a gate that breaks CI, `--parallel` and the fleet gets globally disabled with
+ * `ACUVO_APPROVE=never` in a shell profile, and then it protects nobody on the
+ * laptop either. With no terminal there is nobody to ask, so the write proceeds
+ * and the decision says so. **This is a review affordance, not a fifth lock** —
+ * the write is already confined by `resolveInWorkspace`, `WRITE_FORBIDDEN_ROOTS`,
+ * `MAX_WRITE_BYTES` and `policy.requireDryRun` before it ever reaches here.
+ */
+import {
+  approvalDecision, approvalMode, interpretAnswer,
+  diffUnified, renderApproval, approvalPrompt, previewLineCap,
+} from './diff-preview.mjs';
+
+/**
+ * Build the per-run approver. One per turn; the closure IS the memory.
+ *
+ * @param {object} opts
+ * @param {(question: string) => Promise<string>|string} [opts.ask] the existing
+ *   asker seam. Absent = unattended, and every write settles unreviewed.
+ * @param {boolean} [opts.isInteractive]
+ * @param {NodeJS.ProcessEnv} [opts.env]
+ * @param {string|null} [opts.flag] `--yes` / `--approve=<mode>` if given.
+ * @returns {{ approve: (write: object) => Promise<object>, noteCreated: (path: string) => void, state: object }}
+ */
+/**
+ * ── ⚠️⚠️⚠️ PEOPLE WERE APPROVING CHANGES THEY COULD NOT SEE ─────────────────
+ *
+ * Measured 2026-08-19: all 1,044 lines of `diff-preview.mjs`'s renderer —
+ * `renderDiff`, `renderApproval`, `approvalPrompt` — had **zero production
+ * callers**. The prompt a user actually got was the bare fallback
+ * `Apply changes to <path>?`, with no diff and no mention of `a` or `q`, even
+ * though `interpretAnswer` accepts all four.
+ *
+ * ⭐ THE DIFF IS THE PRODUCT HERE. Claude Code's primary output is the diff;
+ * "approve this" without showing what "this" is trains people to type `y`
+ * reflexively, which is the same as having no gate at all — worse, because it
+ * looks like one.
+ */
+export function createWriteApprover({
+  ask = null, isInteractive = false, env = process.env, flag = null,
+  /**
+   * Where the diff is printed. STDERR by default, deliberately: stdout is the
+   * `--json` contract, and a review that corrupted a machine-readable document
+   * would be a worse bug than the one this fixes.
+   */
+  show = (text) => process.stderr.write(`${text}
+`),
+  paint = null,
+} = {}) {
+  /**
+   * ⚠️ `approvalMode` RETURNS `{ ok, mode, from }`, NOT A STRING — and passing the
+   * object straight through silently disabled the feature: `approvalDecision`
+   * compares `mode === 'never'`, an object never matches, so `ACUVO_APPROVE=never`
+   * kept prompting. Caught by its own test, which is the only reason it is not
+   * still doing that.
+   */
+  const { mode } = approvalMode({ env, flag });
+  /** Files this run brought into existence. Revising your own draft is not a change to REVIEW. */
+  const createdThisRun = new Set();
+  const state = { sessionApproved: false, asked: 0, approved: 0, refused: 0 };
+
+  /**
+   * ⚠️ A PATH IS RECORDED AS "OURS" ONLY WHEN IT DID NOT EXIST BEFORE. Recording
+   * every written path would mean the second edit of a file the user wrote is
+   * treated as our own draft and never queried — which is precisely the review
+   * this exists to perform.
+   */
+  const noteCreated = (path) => {
+    const p = String(path ?? '').trim();
+    if (p) createdThisRun.add(p);
+  };
+
+  const approve = async (write) => {
+    const decision = approvalDecision(write, {
+      mode,
+      interactive: Boolean(isInteractive && ask),
+      createdThisRun,
+      sessionApproved: state.sessionApproved,
+    });
+
+    // Nothing to ask, or nobody to ask. `diff-preview` has already encoded which.
+    if (!decision.required || !decision.satisfiable || typeof ask !== 'function') {
+      return { ...decision, allowed: true };
+    }
+
+    state.asked += 1;
+
+    /**
+     * ⭐⭐ SHOW THE CHANGE BEFORE ASKING ABOUT IT. `diffUnified` refuses to
+     * render something enormous and says so rather than printing 40,000 lines
+     * into a terminal, so the cap is its problem, not ours.
+     *
+     * ⚠️ NEVER FAILS THE WRITE. A renderer that threw would turn "we could not
+     * draw this" into "your change was rejected", which is the worst possible
+     * trade for a display feature.
+     */
+    const kind = write?.kind
+      ?? (write?.after === null || write?.after === undefined ? 'deleted'
+        : (write?.before === null || write?.before === undefined ? 'created' : 'replaced'));
+    /**
+     * ⭐ `renderApproval` HANDS BACK BOTH HALVES — `{ body, prompt }` — so the
+     * diff and the question it belongs to cannot drift apart. Composing the
+     * prompt separately here is how a change ends up shown beside the wrong
+     * verb: "Delete" printed over a diff that creates.
+     */
+    let question = null;
+    try {
+      const diff = diffUnified(write?.before ?? '', write?.after ?? '', write?.path ?? '', {});
+      const rendered = renderApproval(diff, decision, {
+        cap: previewLineCap({ env }),
+        path: write?.path ?? '',
+        ...(paint ? { paint } : {}),
+      });
+      if (rendered?.body) show(rendered.body);
+      question = rendered?.prompt ?? null;
+    } catch { /* a diff we cannot draw is not a reason to refuse a write */ }
+
+    let answer;
+    try {
+      answer = await ask(decision.prompt ?? question ?? approvalPrompt(write?.path ?? '', kind));
+    } catch {
+      /**
+       * ⚠️ AN ASKER THAT THROWS MEANS NOBODY ANSWERED, NOT "NO". A closed pipe
+       * mid-run must not turn into a refusal that looks like the user vetoing
+       * the work — that is the least legible failure available, because the
+       * agent then reports being blocked by a person who was never there.
+       */
+      return { ...decision, allowed: true, reviewed: false, reason: 'nobody could be asked, so the write proceeded' };
+    }
+
+    /**
+     * ⚠️ FOUR OUTCOMES, NOT TWO, and `diff-preview.mjs` owns the vocabulary:
+     * `approve` · `approve-all` · `reject` · `abort`. Collapsing them to a
+     * boolean here would lose the two that matter most — `approve-all` is what
+     * stops the prompt firing forty times, and `abort` means STOP THE RUN rather
+     * than "skip this file", which the agent must not treat as a retryable no.
+     */
+    const verdict = interpretAnswer(answer);
+    if (verdict.decision === 'approve-all') state.sessionApproved = true;
+    const allowed = verdict.decision === 'approve' || verdict.decision === 'approve-all';
+    if (allowed) state.approved += 1;
+    else state.refused += 1;
+    return {
+      ...decision,
+      allowed,
+      reviewed: true,
+      aborted: verdict.decision === 'abort',
+      answer: verdict,
+      reason: verdict.reason,
+    };
+  };
+
+  /**
+   * ── ⭐ THE BULK CASE: ONE QUESTION FOR THE WHOLE BATCH ─────────────────────
+   *
+   * ⚠️ Asking per file turns one intent — "apply this refactor" — into forty
+   * prompts, and a prompt answered forty times is answered without reading by
+   * the third.
+   *
+   * ⚠️ AND IT ASKS IF **ANY** FILE NEEDS IT, not if all of them do. A batch of
+   * thirty-nine scratch files plus one rewrite of `server.js` is exactly the
+   * shape a review exists to catch, and an "all" rule would wave it through.
+   * The answer then governs the whole batch, which is what the person was shown.
+   */
+  const approveMany = async (writes) => {
+    const list = Array.isArray(writes) ? writes : [];
+    if (list.length === 0) return { allowed: true, required: false, reason: 'nothing to write' };
+
+    const decisions = list.map((w) => approvalDecision(w, {
+      mode,
+      interactive: Boolean(isInteractive && ask),
+      createdThisRun,
+      sessionApproved: state.sessionApproved,
+    }));
+    const riskiest = decisions.find((d) => d.required && d.satisfiable);
+    if (!riskiest || typeof ask !== 'function') {
+      return { allowed: true, required: false, reason: 'no file in this batch needed review' };
+    }
+
+    state.asked += 1;
+    let answer;
+    try {
+      answer = await ask(
+        `${riskiest.prompt ?? 'Apply these changes?'} (${list.length} file${list.length === 1 ? '' : 's'} in this batch)`,
+      );
+    } catch {
+      return { allowed: true, reviewed: false, reason: 'nobody could be asked, so the batch proceeded' };
+    }
+    const verdict = interpretAnswer(answer);
+    if (verdict.decision === 'approve-all') state.sessionApproved = true;
+    const allowed = verdict.decision === 'approve' || verdict.decision === 'approve-all';
+    if (allowed) state.approved += 1;
+    else state.refused += 1;
+    return { allowed, reviewed: true, aborted: verdict.decision === 'abort', reason: verdict.reason };
+  };
+
+  return { approve, approveMany, noteCreated, state };
+}
+
+/**
+ * ⭐ THE REFUSAL THE MODEL SEES. It has to read as a decision a person made, not
+ * as a tool failure — otherwise the agent's next move is to retry the write,
+ * which is the worst possible response to "no".
+ */
+export function refusedWriteResult(path) {
+  return {
+    ok: false,
+    refused: true,
+    error: `the change to ${path} was declined by the person running this. Do not retry the same write — ask what they want different, or move on to another part of the task.`,
+  };
+}

package/lib/write-many.mjs

@@ -0,0 +1,162 @@
+/**
+ * ── ⭐⭐ THE BULK EDIT WAS ALREADY HAPPENING — JUST NOT WHERE ANYTHING COULD SEE IT ─
+ *
+ * Measured 2026-08-13. Given "add a parameter to every one of these 45 modules",
+ * the agent did not call `write_file` 45 times across 45 rounds. It wrote a
+ * loop inside `evaluate` and did all 45 in ONE call, correctly, in six rounds.
+ * That is the right instinct and it is how a person would do it.
+ *
+ * ⚠️ But `evaluate` starts a process, so every accounting mechanism this package
+ * has was blind to it:
+ *
+ *   · no `mutated` flag  → the run reported "No files changed" after 45 writes
+ *   · no lease claim     → another terminal's file could be overwritten silently
+ *   · no `mutatedPath`   → `parallel.mjs`'s collision detection saw nothing
+ *   · no credential gate → the write path's refusals never ran
+ *
+ * ⭐ THE ANSWER IS NOT TO FORBID `evaluate`. It is to make the operation the
+ * model actually wants a FIRST-CLASS one, so the effective technique and the
+ * governed technique are the same technique. Every write here goes through
+ * `executor.writeFile`, which means leases, refusals, dry-run and the change
+ * count all work exactly as they do for a single file — because it IS the
+ * single-file path, called in a loop.
+ *
+ * ── ⚠️ PARTIAL SUCCESS IS REPORTED, NOT ROLLED BACK ─────────────────────────
+ *
+ * The obvious instinct is all-or-nothing. It is wrong here, for a reason worth
+ * writing down: a rollback needs to restore the previous contents of files this
+ * tool may have just created, in a workspace another terminal may be writing to
+ * concurrently — a second, more dangerous write path, invented to tidy the
+ * failure of the first. Reporting exactly which files landed and which were
+ * refused is honest, is what the model needs in order to retry the remainder,
+ * and cannot itself corrupt anything.
+ */
+
+/** More than this in one call is a migration, and a migration wants review. */
+export const MAX_FILES = 60;
+/** The sum of all contents. `write_file`'s own per-file ceiling still applies. */
+export const MAX_TOTAL_BYTES = 2_000_000;
+
+export function writeManyToolSchemas() {
+  return [
+    {
+      type: 'function',
+      function: {
+        name: 'write_files',
+        description: [
+          'Write SEVERAL files in one call. Use this instead of many separate write_file calls',
+          'when a change touches more than two or three files — a rename across a package, adding',
+          'a parameter to every module, generating a set of tests.',
+          'DO NOT reach for a script inside `evaluate` to do bulk edits: writes made that way are',
+          'invisible to the file leases that stop two terminals colliding, and to the "files changed"',
+          'count the person reads at the end.',
+          `At most ${MAX_FILES} files per call. Each file replaces its whole contents, exactly like write_file.`,
+          'If some are refused, the rest still land and you are told which did what.',
+        ].join(' '),
+        parameters: {
+          type: 'object',
+          properties: {
+            files: {
+              type: 'array',
+              description: 'The files to write. Each replaces the whole file.',
+              items: {
+                type: 'object',
+                properties: {
+                  path: { type: 'string', description: 'Workspace-relative path.' },
+                  content: { type: 'string', description: 'The complete new contents.' },
+                },
+                required: ['path', 'content'],
+              },
+            },
+          },
+          required: ['files'],
+        },
+      },
+    },
+  ];
+}
+
+/**
+ * @param {{ writeFile: (path: string, content: string) => any }} executor
+ * @param {{ files?: unknown }} args
+ */
+export function writeMany(executor, { files } = {}) {
+  if (!Array.isArray(files) || files.length === 0) {
+    return { ok: false, error: 'write_files needs a non-empty `files` array — each entry is { path, content }' };
+  }
+  if (files.length > MAX_FILES) {
+    return {
+      ok: false,
+      error: `${files.length} files in one call is over the ${MAX_FILES} limit. Split it — a change that large is one somebody will want to read in pieces.`,
+    };
+  }
+
+  /**
+   * ⚠️ VALIDATED BEFORE ANYTHING IS WRITTEN. A malformed entry halfway down the
+   * list would otherwise leave the first half applied and the call refused,
+   * which is the worst of both answers: work done, and an error saying it was
+   * not.
+   */
+  let total = 0;
+  const seen = new Set();
+  for (const [i, f] of files.entries()) {
+    if (!f || typeof f !== 'object') return { ok: false, error: `files[${i}] is not an object — each entry is { path, content }` };
+    if (typeof f.path !== 'string' || !f.path.trim()) return { ok: false, error: `files[${i}] has no path` };
+    if (typeof f.content !== 'string') return { ok: false, error: `files[${i}] (${f.path}) has no content string` };
+    /**
+     * ⚠️ THE SAME PATH TWICE IS A MISTAKE, NOT AN INSTRUCTION. One of the two
+     * contents would silently win, and which one is an implementation detail of
+     * iteration order — exactly the kind of thing that looks fine in testing
+     * and loses somebody's work once.
+     */
+    const key = f.path.trim();
+    if (seen.has(key)) return { ok: false, error: `${key} appears twice in one call — one of the two would silently win` };
+    seen.add(key);
+    total += Buffer.byteLength(f.content, 'utf8');
+  }
+  if (total > MAX_TOTAL_BYTES) {
+    return { ok: false, error: `refusing to write ${total} bytes in one call (limit ${MAX_TOTAL_BYTES})` };
+  }
+
+  const written = [];
+  const refused = [];
+  for (const f of files) {
+    // ⭐ THE SINGLE-FILE PATH, in a loop. Every guard it has — leases,
+    // credential refusals, `.acuvo/` protection, dry-run — applies unchanged,
+    // because this is not a second way to write a file.
+    const r = executor.writeFile(f.path, f.content);
+    if (r?.ok) written.push({ path: r.path ?? f.path, bytes: r.bytes ?? Buffer.byteLength(f.content, 'utf8'), created: r.created === true, dryRun: r.dryRun === true });
+    else refused.push({ path: f.path, error: r?.error ?? 'the write was refused' });
+  }
+
+  return {
+    /**
+     * ⚠️ `ok` IS FALSE WHEN NOTHING LANDED, and true when some did. A call that
+     * wrote 44 of 45 files did real work the model must not repeat blindly, and
+     * one that wrote none is a failure it should react to. Collapsing the two
+     * into "partial" would leave the model guessing which it had.
+     */
+    ok: written.length > 0,
+    written,
+    refused,
+    error: written.length === 0
+      ? `no file was written. ${refused.length === 1 ? refused[0].error : `${refused.length} paths were refused — the first was: ${refused[0]?.error ?? 'unknown'}`}`
+      : undefined,
+  };
+}
+
+/** What the model reads back. Names every refusal, because it has to retry them. */
+export function formatWriteMany(result) {
+  if (!result) return 'write_files returned nothing';
+  if (result.ok !== true && (result.written?.length ?? 0) === 0) return `write_files: ${result.error}`;
+  const lines = [];
+  const w = result.written ?? [];
+  const dry = w.some((f) => f.dryRun);
+  lines.push(`${w.length} file${w.length === 1 ? '' : 's'} ${dry ? 'WOULD be written (dry run — nothing was)' : 'written'}:`);
+  for (const f of w.slice(0, 60)) lines.push(`  ${f.created ? 'created ' : 'replaced'} ${f.path} (${f.bytes} bytes)`);
+  if ((result.refused?.length ?? 0) > 0) {
+    lines.push(`${result.refused.length} refused — these still need doing:`);
+    for (const f of result.refused.slice(0, 20)) lines.push(`  ${f.path}: ${f.error}`);
+  }
+  return lines.join('\n');
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "acuvo-code",
+  "version": "0.2.0",
+  "description": "Acuvo Code — the terminal client for the Acuvo capability registry. Zero dependencies, by design.",
+  "type": "module",
+  "bin": {
+    "acuvo": "bin/acuvo.mjs",
+    "acuvo-mcp": "bin/acuvo-mcp.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": "./lib/turn.mjs",
+    "./turn": "./lib/turn.mjs",
+    "./tools": "./lib/tools.mjs",
+    "./workspace": "./lib/workspace.mjs",
+    "./memory-workspace": "./lib/memory-workspace.mjs",
+    "./budget": "./lib/budget.mjs",
+    "./policy": "./lib/policy.mjs",
+    "./lib/*": "./lib/*.mjs",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "node scripts/test.mjs",
+    "test:raw": "node --test --test-timeout=180000 test/",
+    "bundle": "node scripts/bundle.mjs --out dist/acuvo.mjs",
+    "bundle:mcp": "node scripts/bundle.mjs --entry bin/acuvo-mcp.mjs --out dist/acuvo-mcp.mjs",
+    "machine": "node scripts/machine.mjs status",
+    "machine:stop": "node scripts/machine.mjs stop"
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "license": "FSL-1.1-ALv2",
+  "files": [
+    "bin/",
+    "lib/",
+    "skills/",
+    "scripts/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "ENTERPRISE.md",
+    "ROADMAP.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xxiautomate-star/acuvo-code.git"
+  },
+  "homepage": "https://acuvo.xxiautomate.com",
+  "bugs": {
+    "email": "roman@xxiautomate.com"
+  },
+  "author": "XXIautomate (Roman Puglielli)",
+  "keywords": [
+    "ai",
+    "cli",
+    "coding-agent",
+    "agent",
+    "terminal"
+  ]
+}