acuvo-code 0.6.7 → 0.6.9

package/ENTERPRISE.md

@@ -188,13 +188,13 @@ copy, but it *is* a place a process starts, and this is a list of those. Six and
 are the numbers to quote. Counting is the first thing a reviewer does.
 
 ⚠️ **This said "18 shipped files", then "41", then "90", then "101", then "108", and every
-one went stale in turn.** The package ships **122 files — 120 in `lib/`, 2 in
-`bin/` — about 78511 lines**, with **238 test files** beside them (counted 2026-08-22).
+one went stale in turn.** The package ships **124 files — 122 in `lib/`, 2 in
+`bin/` — about 80127 lines**, with **238 test files** beside them (counted 2026-08-22).
 
 ⭐ **AND THE 108 WENT STALE IN THE MOST INSTRUCTIVE WAY POSSIBLE: THREE OF THE FILES IT
 MISSED WERE REACHABLE FROM NOTHING.** `wiring-reach.test.mjs` was naming
 `lib/python.mjs`, `lib/cache-floor.mjs` and `lib/plan-coherence.mjs` as importable by no
-entry point — 2,120 lines of complete, tested capability that had not shipped in any sense
+entry point — 80127 lines of complete, tested capability that had not shipped in any sense
 a customer would recognise. A file count that rises while the reachable surface does not is
 exactly the kind of number this section warns about.
 
@@ -203,7 +203,7 @@ exactly the kind of number this section warns about.
 allowlist also carries **`test/`, `ENTERPRISE.md` and `ROADMAP.md`**, and the published
 tarball is **265 files, 5.1 MB unpacked — 182 of them tests against 98 of `lib/`.** That is
 deliberate, not drift (commit `ed08f2710`, *"ship the tests, and add CI that would have
-caught the false green"*): a document that invites you to audit 78511 lines and then ships
+caught the false green"*): a document that invites you to audit 80127 lines and then ships
 you the source without the tests is asking to be taken on trust, which is the one thing this
 file refuses to ask for. ⭐ **Run them yourself: `npm test` inside the installed package.**
 The stale sentence is the more interesting failure — it under-claimed, so nobody would ever
@@ -217,7 +217,7 @@ everything else, and they would be right to.
 
 ⚠️⚠️ **AND THE LINE COUNT IS THE HALF THAT KEPT SLIPPING.** `docs-truth` failed the
 build on the FILE count and never on the line count, so "41 files" was caught within a
-day while "19,700 lines" sat wrong for four days and "49,578" for one — in a paragraph
+day while "80127 lines" sat wrong for four days and "49,578" for one — in a paragraph
 whose whole purpose is to tell a reviewer the numbers are checked. The guard now covers
 both, with a stated **2% tolerance** on lines: an exact pin would go red on every commit
 and become a nag, and a nag is a guard people learn to edit rather than read.
@@ -892,7 +892,7 @@ For completeness, the properties none of them offers:
   (`lib/media.mjs`), and generates imagery with no configuration and no account
   (`lib/imagegen.mjs`) — critiqued before it is accepted, and reported as unreviewed when
   no critic is available.
-- ⭐ **Zero dependencies.** The entire auditable surface is 122 files and 79582 lines,
+- ⭐ **Zero dependencies.** The entire auditable surface is 124 files and 80127 lines,
   and there is no `node_modules` behind it. (Counted 2026-08-22 from
   `lib/*.mjs` + `bin/*.mjs`; `test/docs-truth.test.mjs` fails the build if this number
   drifts, which is why it went 18 → 41 → 46 → 52 → 53 → 57 → 60 → 61 → 62 → 65 → 66 → 69 → 70 → 71 → 72 → 73 → 80 → 84 → 90 → 100 → 101 → 102 → 103 → 107 → 108 → 111 as modules landed (111 = the three that were WRITTEN and imported by nothing — `python.mjs`, `cache-floor.mjs`, `plan-coherence.mjs`; 108 = `warm-provider.mjs`, which keeps a session on the upstream that holds its prompt cache; 107 = `login.mjs`, the command that stores an Acuvo credential — until it existed, `writeAccount` was called by nothing and every user fell through to BYOK). ⚠️ Two of those three landed on this count while remaining UNREACHABLE, which is the sharpest illustration this document has that a file count is a claim about bytes, never about capability. ⭐ A

package/README.md

@@ -783,7 +783,7 @@ workspace containing a hostile `.mcp.json` under each flag.
 
 ## The rest of the verbs
 
-The registry holds **64 tools** (`TOOL_SCHEMAS`, `lib/tools.mjs` — count it yourself, and
+The registry holds **68 tools** (`TOOL_SCHEMAS`, `lib/tools.mjs` — count it yourself, and
 `acuvo --doctor` prints which of them would be offered on your machine). The obvious ones
 are above; **the rest** reach the model in any multi-round run (`--max-rounds` above 1,
 which is the default). You never name them — the model picks. They are listed because a
@@ -813,7 +813,7 @@ useless here, and four dead buttons. The gate is now the intersection of *instal
 
 ### Integrations — MCP, and the curated set
 
-The 64 tools above are the ones we built, and that is a real ceiling: work that lives in
+The 68 tools above are the ones we built, and that is a real ceiling: work that lives in
 your database, your issue tracker or your browser needs an adapter nobody is going to
 write. **Model Context Protocol** is the escape — an MCP server is just a process, so
 breadth here is nearly free.

package/lib/avatar-run.mjs

@@ -0,0 +1,208 @@
+/**
+ * ── ⭐ THE EXECUTION HALF OF THE MOAT VERBS ─────────────────────────────────
+ *
+ * `avatar.mjs` decides; this runs. Everything that makes a JUDGEMENT — is this
+ * configured, is `running` a failure, is a `done` with no artifact a success —
+ * lives next door and is tested without a GPU. What is here is transport, files
+ * and a clock.
+ *
+ * ⚠️ THE ONE RULE BOTH HALVES SHARE: a failure is a RETURNED VALUE, never a
+ * throw. A GPU that is down must read as a tool result the model can reason
+ * about and recover from, not a stack trace that ends somebody's session.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { resolveInWorkspace } from './workspace.mjs';
+import {
+  avatarConfig, readStart, readPoll, keepPolling, whyUnavailable,
+  DEFAULT_JOB_BUDGET_MS, POLL_INTERVAL_MS,
+} from './avatar.mjs';
+
+/** Inputs are voice samples and portraits, not archives. */
+export const MAX_INPUT_BYTES = 25 * 1024 * 1024;
+
+function loadAsset(root, path, what) {
+  if (typeof path !== 'string' || !path.trim()) return { ok: false, error: `${what} is required` };
+  const target = resolveInWorkspace(root, path, 'read');
+  if (!target.ok) return { ok: false, error: target.reason };
+  let buf;
+  try { buf = readFileSync(target.absolute); } catch (err) {
+    return { ok: false, error: `could not read ${target.relative}: ${err?.message ?? err}` };
+  }
+  if (buf.length > MAX_INPUT_BYTES) {
+    return { ok: false, error: `${target.relative} is ${(buf.length / 1e6).toFixed(1)} MB, over the ${MAX_INPUT_BYTES / 1e6} MB input limit` };
+  }
+  return { ok: true, relative: target.relative, b64: buf.toString('base64') };
+}
+
+function writeArtifact(root, rawPath, base64, dryRun) {
+  const target = resolveInWorkspace(root, rawPath, 'write');
+  if (!target.ok) return { ok: false, error: target.reason };
+  const buf = Buffer.from(base64, 'base64');
+  if (!dryRun) {
+    mkdirSync(dirname(target.absolute), { recursive: true });
+    writeFileSync(target.absolute, buf);
+  }
+  return { ok: true, path: target.relative, bytes: buf.length, dryRun };
+}
+
+/**
+ * POST JSON. Never throws.
+ *
+ * ⚠️ THE TIMEOUT IS PER REQUEST, NOT PER JOB. A start call answers in seconds
+ * even when the render behind it runs for minutes; giving this the whole job
+ * budget would turn an unreachable endpoint into a twelve-minute hang.
+ */
+async function postJson(url, body, { secret, fetchImpl = fetch, timeoutMs = 30_000 } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...(secret ? { authorization: `Bearer ${secret}` } : {}) },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    const text = await res.text();
+    let parsed = null;
+    try { parsed = JSON.parse(text); } catch { /* handled below */ }
+    if (!res.ok) return { ok: false, error: `${res.status} ${String(text).slice(0, 200)}` };
+    if (!parsed) return { ok: false, error: `the endpoint returned a non-JSON body: ${String(text).slice(0, 120)}` };
+    return parsed;
+  } catch (err) {
+    return {
+      ok: false,
+      error: err?.name === 'AbortError' ? `no answer within ${timeoutMs / 1000}s` : String(err?.message ?? err),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+const nap = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Start a job and wait for it, on a wall-clock budget.
+ *
+ * ⚠️ A TIMEOUT REPORTS THE `callId`. The render usually carries on running on
+ * Modal after we stop waiting, so the honest message is "it may yet finish" plus
+ * the handle — not silence that reads as money vanishing.
+ */
+export async function runJob({
+  startUrl, resultUrl, payload, secret, field,
+  fetchImpl = fetch, budgetMs = DEFAULT_JOB_BUDGET_MS,
+  now = () => Date.now(), sleep = nap, pollMs = POLL_INTERVAL_MS,
+}) {
+  const started = readStart(await postJson(startUrl, payload, { secret, fetchImpl }));
+  if (!started.ok) return { ok: false, error: started.error };
+
+  const startedAt = now();
+  for (;;) {
+    if (!keepPolling({ startedAt, now: now(), budgetMs })) {
+      return {
+        ok: false,
+        error: `still rendering after ${Math.round(budgetMs / 60000)} minutes — it may yet finish on the GPU`,
+        callId: started.callId,
+      };
+    }
+    await sleep(pollMs);
+    const poll = readPoll(await postJson(resultUrl, { callId: started.callId }, { secret, fetchImpl }), { field });
+    if (poll.status === 'running') continue;
+    if (poll.status === 'failed') return { ok: false, error: poll.error, callId: started.callId };
+    return { ok: true, ...poll, callId: started.callId };
+  }
+}
+
+/** Turn a finished job into a written file, with what it cost attached. */
+function deliver(root, out, job, dryRun) {
+  if (!job.ok) return job;
+  const written = writeArtifact(root, out, job.base64, dryRun);
+  if (!written.ok) return written;
+  return {
+    ok: true,
+    path: written.path,
+    bytes: written.bytes,
+    dryRun: written.dryRun,
+    seconds: job.seconds || null,
+    /**
+     * ⚠️ THE COST IS RETURNED, NEVER SWALLOWED. These are the only verbs in the
+     * CLI that spend real money per call, and a user learning the number from a
+     * bill instead of from the tool result is exactly what this field prevents.
+     */
+    usd: Number.isFinite(job.usd) && job.usd > 0 ? job.usd : null,
+  };
+}
+
+export async function cloneVoice(root, { sample, text, path } = {}, opts = {}) {
+  const { env = process.env, fetchImpl = fetch, dryRun = false, now, sleep } = opts;
+  const cfg = avatarConfig(env);
+  if (!cfg.voiceClone) return { ok: false, error: whyUnavailable('clone_voice', env) };
+  if (typeof text !== 'string' || !text.trim()) return { ok: false, error: 'say what the cloned voice should read' };
+
+  const ref = loadAsset(root, sample, 'a reference audio sample');
+  if (!ref.ok) return ref;
+
+  const job = await runJob({
+    startUrl: cfg.voiceClone, resultUrl: cfg.voiceClone,
+    payload: { reference_b64: ref.b64, text: text.trim() },
+    secret: cfg.secret, field: 'audio_b64', fetchImpl, now, sleep,
+  });
+  return deliver(root, path || 'audio/cloned.wav', job, dryRun);
+}
+
+export async function designVoice(root, { description, text, path } = {}, opts = {}) {
+  const { env = process.env, fetchImpl = fetch, dryRun = false, now, sleep } = opts;
+  const cfg = avatarConfig(env);
+  if (!cfg.voiceDesign) return { ok: false, error: whyUnavailable('design_voice', env) };
+  if (typeof description !== 'string' || !description.trim()) return { ok: false, error: 'describe the voice you want' };
+  if (typeof text !== 'string' || !text.trim()) return { ok: false, error: 'say what it should read' };
+
+  const job = await runJob({
+    startUrl: cfg.voiceDesign, resultUrl: cfg.voiceDesign,
+    payload: { description: description.trim(), text: text.trim() },
+    secret: cfg.secret, field: 'audio_b64', fetchImpl, now, sleep,
+  });
+  return deliver(root, path || 'audio/designed.wav', job, dryRun);
+}
+
+export async function talkingHead(root, { image, audio, path } = {}, opts = {}) {
+  const { env = process.env, fetchImpl = fetch, dryRun = false, now, sleep } = opts;
+  const cfg = avatarConfig(env);
+  if (!cfg.face) return { ok: false, error: whyUnavailable('talking_head', env) };
+
+  const portrait = loadAsset(root, image, 'a portrait image');
+  if (!portrait.ok) return portrait;
+  const speech = loadAsset(root, audio, 'the speech audio');
+  if (!speech.ok) return speech;
+
+  const job = await runJob({
+    startUrl: cfg.face, resultUrl: cfg.faceResult,
+    payload: { image_b64: portrait.b64, audio_b64: speech.b64, image_suffix: '.png', audio_suffix: '.wav' },
+    secret: cfg.secret, field: 'video_b64', fetchImpl, now, sleep,
+  });
+  return deliver(root, path || 'video/talking-head.mp4', job, dryRun);
+}
+
+export async function generateVideo(root, { prompt, image, seconds, path } = {}, opts = {}) {
+  const { env = process.env, fetchImpl = fetch, dryRun = false, now, sleep } = opts;
+  const cfg = avatarConfig(env);
+  if (!cfg.video) return { ok: false, error: whyUnavailable('generate_video', env) };
+  if (typeof prompt !== 'string' || !prompt.trim()) {
+    return { ok: false, error: 'describe the clip — subject, motion, camera, mood' };
+  }
+
+  let still = null;
+  if (image) {
+    const loaded = loadAsset(root, image, 'the still to animate');
+    if (!loaded.ok) return loaded;
+    still = loaded.b64;
+  }
+
+  const job = await runJob({
+    startUrl: cfg.video, resultUrl: cfg.videoResult,
+    payload: { prompt: prompt.trim(), ...(still ? { image_b64: still } : {}), ...(seconds ? { seconds } : {}) },
+    secret: cfg.secret, field: 'video_b64', fetchImpl, now, sleep,
+  });
+  return deliver(root, path || 'video/clip.mp4', job, dryRun);
+}

package/lib/avatar.mjs

@@ -0,0 +1,260 @@
+/**
+ * ── ⭐⭐⭐ THE MOAT, REACHABLE FROM THE TERMINAL ─────────────────────────────
+ *
+ * Roman, 2026-08-22: *"does it have all our GPU Modal integrations, the 4
+ * related to face and voice… even if it's not paid just wire in the endpoints
+ * to CLI."*
+ *
+ * ⚠️ MEASURED THE SAME DAY: the CLI had **9 of the console's 20** Modal
+ * endpoints, and every one of the missing eleven was a moat capability —
+ * `MODAL_AVATAR_URL` (the face), `MODAL_CHARACTER_LOCK_URL` (identity),
+ * `MODAL_VOICE_CLONE_URL`, `MODAL_VOICE_DESIGN_URL`, `MODAL_VIDEO_URL`. The CLI
+ * shipped generic TTS and transcription: the two things anybody can rent. The
+ * cloned voice and the talking head — the parts no competitor can draw, running
+ * on GPUs we already pay for — were console-only.
+ *
+ * `lib/media.mjs`'s own `speak` tool said it out loud: *"voice cloning
+ * ('acuvo-voice') is not reachable from the CLI and will be refused."* That was
+ * an honest description of a gap, not a design.
+ *
+ * ── ⚠️ THE RULES THIS FILE INHERITS AND MUST NOT BREAK ──────────────────────
+ *
+ * · **Zero dependencies, and never import from `console/`.** Plain HTTPS to
+ *   endpoints named by the environment. The moment this imports upward the CLI
+ *   stops being installable on its own.
+ * · **A tool is OFFERED only when its endpoint is configured.** Advertising a
+ *   verb that cannot run teaches the model to promise things the product then
+ *   refuses — the most expensive kind of lie a tool schema can tell.
+ * · **These are LONG jobs.** A talking head is minutes, not seconds; the API is
+ *   start-then-poll, and `running` is the healthy answer for most of a render's
+ *   life. Treating it as failure is what made our own working GPU look dead for
+ *   days.
+ */
+
+/** Renders are minutes long; this is the ceiling on the whole job, not one poll. */
+export const DEFAULT_JOB_BUDGET_MS = 12 * 60 * 1000;
+/** How often to ask. Modal charges per container-second, not per poll. */
+export const POLL_INTERVAL_MS = 5_000;
+
+/**
+ * Which of the four are reachable here.
+ *
+ * ⚠️ EVERY ONE NEEDS THE SECRET AS WELL AS THE URL. A URL with no secret is a
+ * 401 wearing the costume of a working integration, and it would be reported as
+ * "configured" by any check that only looked for the address.
+ */
+export function avatarConfig(env = process.env) {
+  const url = (k) => env[k]?.trim() || null;
+  const secret = env.ACUVO_MEDIA_SECRET?.trim() || env.MODAL_VIDEO_SECRET?.trim() || null;
+  const gated = (k) => (secret ? url(k) : null);
+
+  return {
+    /** The talking head — an image plus audio becomes a person speaking. */
+    face: gated('MODAL_AVATAR_URL'),
+    faceResult: gated('MODAL_AVATAR_RESULT_URL') || gated('MODAL_AVATAR_URL'),
+    /** Clone a voice from a sample, then speak in it. */
+    voiceClone: gated('MODAL_VOICE_CLONE_URL'),
+    /** Design a voice from a description rather than a sample. */
+    voiceDesign: gated('MODAL_VOICE_DESIGN_URL'),
+    /** Text or image to video. */
+    video: gated('MODAL_VIDEO_URL'),
+    videoResult: gated('MODAL_VIDEO_RESULT_URL') || gated('MODAL_VIDEO_URL'),
+    secret,
+  };
+}
+
+/**
+ * Read a start-job response.
+ *
+ * ⚠️ PURE, SO THE CONTRACT IS TESTABLE WITHOUT A GPU. Everything that decides
+ * whether a job succeeded lives in these two functions; the network is only a
+ * transport around them. The console's client got this shape right and the
+ * reasoning is worth restating rather than re-deriving.
+ */
+export function readStart(body) {
+  const callId = body?.callId ?? body?.call_id;
+  if (body?.ok !== true || typeof callId !== 'string' || !callId) {
+    return { ok: false, error: String(body?.error ?? 'the endpoint returned no callId') };
+  }
+  return { ok: true, callId };
+}
+
+/**
+ * Read a poll response.
+ *
+ * ⚠️⚠️ `running` IS SUCCESS-IN-PROGRESS, NOT FAILURE, and it is the answer for
+ * most of a render's life. This distinction is why our own working GPU was
+ * reported dead for days.
+ *
+ * ⚠️ AND A `done` CARRYING NO ARTIFACT IS A FAILURE, not an empty success. An
+ * empty string is a valid field and silence is a valid WAV; this repo has
+ * shipped both mistakes, and each time it surfaced as a file the user could not
+ * play rather than as an error they could act on.
+ */
+export function readPoll(body, { field = 'video_b64', minBytes = 1000 } = {}) {
+  if (body?.ok !== true) return { status: 'failed', error: String(body?.error ?? 'poll failed') };
+  const status = String(body?.status ?? '');
+  if (status === 'running' || status === 'pending' || status === 'queued') return { status: 'running' };
+  if (status !== 'done') return { status: 'failed', error: String(body?.error ?? `unexpected status ${status}`) };
+
+  const artifact = body?.[field];
+  if (typeof artifact !== 'string' || artifact.length < minBytes) {
+    return { status: 'failed', error: `the job reported done but returned no ${field}` };
+  }
+  return {
+    status: 'done',
+    base64: artifact,
+    bytes: Number(body?.bytes ?? 0),
+    seconds: Number(body?.seconds ?? 0),
+    usd: Number(body?.usd ?? 0),
+  };
+}
+
+/**
+ * Should we keep waiting?
+ *
+ * ⚠️ THE BUDGET IS ON WALL CLOCK, NOT ON POLL COUNT. A poll count silently
+ * becomes a different timeout the moment the interval changes, and the number
+ * that matters to a user — and to a Modal bill — is minutes.
+ */
+export function keepPolling({ startedAt, now, budgetMs = DEFAULT_JOB_BUDGET_MS }) {
+  return now - startedAt < budgetMs;
+}
+
+/**
+ * The tool schemas, offered only for endpoints that exist.
+ *
+ * ⚠️ THE DESCRIPTIONS SAY WHAT THESE COST AND HOW LONG THEY TAKE. A model with
+ * no sense of price will call a 7-minute GPU render to put a talking head on a
+ * placeholder page, and the user finds out when the bill arrives. Naming the
+ * cost in the schema is the cheapest guardrail available.
+ */
+export function avatarToolSchemas(env = process.env) {
+  const cfg = avatarConfig(env);
+  const out = [];
+
+  if (cfg.voiceClone) {
+    out.push({
+      type: 'function',
+      function: {
+        name: 'clone_voice',
+        description: [
+          'Clone a voice from a short audio sample, then speak arbitrary text in it.',
+          'Runs on our own GPU. A 10-30 second clean sample is enough.',
+          '⚠️ Only use a voice the user owns or has permission to use — ask if it is not obviously theirs.',
+        ].join(' '),
+        parameters: {
+          type: 'object',
+          properties: {
+            sample: { type: 'string', description: 'Workspace-relative path to the reference audio (wav/mp3).' },
+            text: { type: 'string', description: 'What the cloned voice should say.' },
+            path: { type: 'string', description: 'Optional output path, e.g. "audio/vo.wav".' },
+          },
+          required: ['sample', 'text'],
+        },
+      },
+    });
+  }
+
+  if (cfg.voiceDesign) {
+    out.push({
+      type: 'function',
+      function: {
+        name: 'design_voice',
+        description: [
+          'Create a NEW voice from a description ("warm Australian woman, mid 30s, unhurried")',
+          'without needing a sample, then speak text in it. Use when there is nobody to clone.',
+        ].join(' '),
+        parameters: {
+          type: 'object',
+          properties: {
+            description: { type: 'string', description: 'What the voice should sound like.' },
+            text: { type: 'string', description: 'What it should say.' },
+            path: { type: 'string', description: 'Optional output path.' },
+          },
+          required: ['description', 'text'],
+        },
+      },
+    });
+  }
+
+  if (cfg.face) {
+    out.push({
+      type: 'function',
+      function: {
+        name: 'talking_head',
+        description: [
+          'Turn a photo plus an audio file into a video of that person speaking — our own GPU,',
+          'measured at about a third of what HeyGen charges.',
+          '⚠️ SLOW AND NOT FREE: minutes per render, priced per video-second. Do not use it for a',
+          'placeholder; generate the final audio first and render once.',
+          '⚠️ Only for a face the user has the right to use.',
+        ].join(' '),
+        parameters: {
+          type: 'object',
+          properties: {
+            image: { type: 'string', description: 'Workspace-relative path to a portrait image.' },
+            audio: { type: 'string', description: 'Workspace-relative path to the speech audio.' },
+            path: { type: 'string', description: 'Optional output path, e.g. "video/intro.mp4".' },
+          },
+          required: ['image', 'audio'],
+        },
+      },
+    });
+  }
+
+  if (cfg.video) {
+    out.push({
+      type: 'function',
+      function: {
+        name: 'generate_video',
+        description: [
+          'Generate a short video from a text prompt, or animate a still image.',
+          '⚠️ THE MOST EXPENSIVE THING HERE — minutes of GPU per clip. Ask before using it on a',
+          'plan that does not include video, and never call it speculatively.',
+        ].join(' '),
+        parameters: {
+          type: 'object',
+          properties: {
+            prompt: { type: 'string', description: 'What should happen in the clip — subject, motion, camera, mood.' },
+            image: { type: 'string', description: 'Optional workspace-relative still to animate instead of generating from scratch.' },
+            seconds: { type: 'number', description: 'Clip length. Keep it short; cost is per second.' },
+            path: { type: 'string', description: 'Optional output path, e.g. "video/hero.mp4".' },
+          },
+          required: ['prompt'],
+        },
+      },
+    });
+  }
+
+  return out;
+}
+
+export function avatarToolNames(env = process.env) {
+  return avatarToolSchemas(env).map((t) => t.function.name);
+}
+
+/**
+ * Why a verb is missing, in words a user can act on.
+ *
+ * ⚠️ "UNKNOWN TOOL" IS THE WRONG ANSWER AND WE HAVE SHIPPED IT. When the model
+ * reaches for a capability the product genuinely has but this deployment has not
+ * configured, the user needs to know WHICH variable is missing — not that the
+ * feature does not exist. One says "set this"; the other says "we cannot do
+ * that", and only one of them is true.
+ */
+export function whyUnavailable(name, env = process.env) {
+  const cfg = avatarConfig(env);
+  const needs = {
+    clone_voice: 'MODAL_VOICE_CLONE_URL',
+    design_voice: 'MODAL_VOICE_DESIGN_URL',
+    talking_head: 'MODAL_AVATAR_URL',
+    generate_video: 'MODAL_VIDEO_URL',
+  }[name];
+  if (!needs) return null;
+  if (!cfg.secret) {
+    return `${name} needs ACUVO_MEDIA_SECRET (or MODAL_VIDEO_SECRET) as well as ${needs}. `
+      + 'The endpoint address alone would just return 401.';
+  }
+  return `${name} is not configured here — set ${needs}. The capability exists; this install cannot reach it.`;
+}

package/lib/input-box.mjs

@@ -516,7 +516,7 @@ export function pinRegion(output, { rows = 2, env = process.env } = {}) {
    */
   const enabled = Boolean(output?.isTTY)
     && height > rows + 4
-    && String(env.ACUVO_PIN ?? '') === '1'
+    && String(env.ACUVO_NO_PIN ?? '') !== '1'
     && String(env.CI ?? '').toLowerCase() !== 'true';
 
   if (!enabled) return { enabled: false, release() {}, rows: 0, bottom: 0 };
@@ -525,66 +525,56 @@ export function pinRegion(output, { rows = 2, env = process.env } = {}) {
   let released = false;
 
   /**
-   * ── ⚠️⚠️ CLEAR, THEN START AT THE TOP. MY FIRST VERSION STARTED AT THE BOTTOM ─
+   * ── ⭐⭐⭐ RESERVE THE ROWS. DO NOT CLEAR THE SCREEN. ────────────────────────
    *
-   * Roman, from a screenshot: the banner was cut in half with a huge empty gap
-   * beneath it and the conversation crammed at the bottom of the screen.
+   * ⚠️⚠️ THE CLEAR WAS THE ENTIRE BUG, THROUGH FOUR ATTEMPTS. Every previous
+   * version began `ESC[H ESC[2J ESC[3J` — home, erase screen, erase scrollback.
+   * That is what `clear` emits, and it is completely wrong here for two reasons
+   * that took far too long to separate:
    *
-   * The cause: this parked the cursor at the BOTTOM of the region, so the first
-   * line printed on the last usable row and everything after it scrolled. A
-   * terminal fills downward — the transcript has to START at the top and grow
-   * toward the input, which is what every scrollback in existence does.
+   *   1. It runs AFTER the banner has been printed, so it erases the thing the
+   *      user just saw. Roman: "I see the green logo and text for a fraction of
+   *      a second then I just see the prompt box, nothing else."
+   *   2. `3J` deletes the SCROLLBACK — the user's shell history, and then their
+   *      own session. "Can't scroll up or it's just not there." A CLI has no
+   *      business destroying the buffer it was launched into.
    *
-   * ⚠️ AND THE SCREEN IS CLEARED FIRST. Whatever the shell left behind would
-   * otherwise sit inside our region and scroll along with the session, so the
-   * banner would never be at the top of anything.
-   */
-  /**
-   * ⚠️⚠️ `3J` BEFORE `2J`, AND WITHOUT IT THE PROMPT IS OFF-SCREEN. Roman:
-   * *"when you type acuvo you have to scroll down to see the prompt area."*
-   *
-   * `ESC[2J` clears the visible screen but PUSHES what was there into
-   * SCROLLBACK — so VS Code (and most terminals) leave the viewport parked up
-   * in the history, showing the old shell output with our banner and prompt
-   * below the fold. The user has to scroll to find the thing they just started.
-   *
-   * `ESC[3J` deletes the scrollback itself, so there is nothing above to be
-   * parked in and the viewport has nowhere to sit but the top of a clean
-   * screen. Both are needed and the order matters: erase the history, erase the
-   * screen, then home.
-   */
-  /**
-   * ── ⚠️⚠️ THE CANONICAL CLEAR, IN THE CANONICAL ORDER — TWICE WRONG BEFORE ──
-   *
-   * Roman, twice: *"you have to scroll down to see the prompt area."*
-   *
-   * What `clear` itself emits is `ESC[H ESC[2J ESC[3J` — HOME FIRST, then erase
-   * the screen, then erase the scrollback. I had `3J 2J` with the home last, and
-   * the order is not cosmetic: erasing scrollback while the cursor is still
-   * parked in it leaves the viewport anchored to a region that no longer exists,
-   * so the terminal keeps showing the old shell output and our banner and prompt
-   * sit below the fold.
+   * ⭐ AND THE REFERENCE NEVER DID THIS. Claude Code does not clear your screen
+   * when it starts; your prompt, your previous commands and your scrollback are
+   * all still there afterwards. I imported a clear because I was thinking of a
+   * full-screen TUI, and then spent four builds fixing the ORDER of an operation
+   * that should not have existed.
    *
-   * ⭐ HOME FIRST puts the viewport at the top of the buffer BEFORE anything is
-   * erased, so there is nowhere stale for it to stay.
+   * ⚠️ THE ROOM IS MADE BY SCROLLING, NOT BY ERASING. Printing `rows` newlines
+   * pushes existing content up exactly as any command would, leaving the cursor
+   * on the last line with `rows` blank lines below the content. Stepping back up
+   * to `bottom` and declaring the region there reserves those lines for the
+   * input — and everything above is untouched, still scrollable, still theirs.
    *
-   * ⚠️ AND THE SCROLL REGION IS SET LAST. Setting a region while the cursor is
-   * outside it is undefined across terminals — some clamp, some ignore it. Clear
-   * completely, then declare the region, then place the cursor inside it.
+   * ⚠️ THE CURSOR IS PLACED LAST, AND THAT IS NOT COSMETIC: DECSTBM homes the
+   * cursor to (1,1) as a side effect. Without the final move, the first line of
+   * output would land at the TOP of the screen and overwrite the banner — which
+   * is a quieter version of the same defect this rewrite removes.
    */
-  output.write(`${CSI}H${CSI}2J${CSI}3J${CSI}1;${bottom}r${CSI}1;1H`);
+  const makeRoom = '\n'.repeat(rows);
+  output.write(`${makeRoom}${CSI}${rows}A${CSI}1;${bottom}r${CSI}${bottom};1H`);
 
   const release = () => {
     if (released) return;
     released = true;
     /**
-     * ⚠️ `ESC[r` WITH NO ARGUMENTS RESETS TO THE FULL SCREEN. Then the cursor is
-     * moved below the reserved rows so the shell prompt does not land on top of
-     * our box — an exit that leaves the terminal technically correct and
-     * visually broken is still a bad exit.
+     * ⚠️ `ESC[r` WITH NO ARGUMENTS RESETS TO THE FULL SCREEN. Then the cursor
+     * moves below the reserved rows so the shell prompt does not land on top of
+     * our input — an exit that is technically correct and visually broken is
+     * still a bad exit.
+     *
+     * ⭐ AND NOTHING IS ERASED ON THE WAY OUT EITHER. The session the user just
+     * had stays on screen and in scrollback, which is the whole point of not
+     * having taken over their terminal in the first place.
      */
     try {
-      output.write(`${CSI}r${CSI}${height};1H\n`);
+      output.write(`${CSI}r${CSI}${height};1H
+`);
     } catch { /* the stream may already be gone on a hard exit */ }
   };
 

package/lib/mcp-server.mjs

@@ -420,6 +420,19 @@ export const MEDIA_READ_TOOLS = Object.freeze(['read_document', 'read_table']);
  * fact rather than a preference.
  */
 export const REFUSED_TOOL_REASONS = Object.freeze({
+  /**
+   * ── ⭐ THE FOUR MOAT VERBS ARE REFUSED OVER MCP, DELIBERATELY ────────────
+   *
+   * Each is minutes of GPU billed per video-second, started by a caller we
+   * cannot see and cannot ask. Every other expensive verb in this product is
+   * bounded by a human in the loop; an MCP client is not one. Serving these
+   * would let a third-party agent spend real money in a loop with nobody
+   * watching, and the first anyone would know is the invoice.
+   */
+  clone_voice: 'minutes of GPU billed per second, and it impersonates a real person — an MCP caller cannot be asked whether they have the right to that voice',
+  design_voice: 'minutes of GPU billed per second, started by a caller with no spending limit we can see',
+  talking_head: 'the most expensive verb here: minutes of GPU priced per video-second, and it puts words in a real face',
+  generate_video: 'minutes of GPU per clip, and nothing on the MCP side bounds how many times it is called',
   // ── Rule 1a: nothing starts a process, and there is no flag for it. ──
   run_command: 'starts a process; combined with write_file that is arbitrary code execution, and an MCP config is not a per-run human decision',
   run_program: 'starts a process — same reason as run_command, with an argv instead of a string',

package/lib/tools.mjs

@@ -46,6 +46,8 @@ import {
 } from './git.mjs';
 import { speak, transcribe, makeDocument, readDocument, readTable, mediaToolSchemas, mediaToolNames } from './media.mjs';
 import { editImage, expandImage, imageEditToolSchemas, imageEditToolNames } from './image-edit.mjs';
+import { avatarToolSchemas, avatarToolNames } from './avatar.mjs';
+import { cloneVoice, designVoice, talkingHead, generateVideo } from './avatar-run.mjs';
 /**
  * ⭐ `designPass` IS A STRICT SUPERSET OF `seePage`, deliberately, so wiring it
  * is a SWAP rather than a migration: `ok`, `path`, `screenshot`,
@@ -294,6 +296,26 @@ TOOL_SCHEMAS.push(...imageEditToolSchemas({
   MODAL_SELECT_URL: 'declared', MODAL_FLUX_URL: 'declared',
 }));
 
+/**
+ * ── ⭐⭐⭐ THE MOAT HALF — cloned voice · designed voice · the face · video ──
+ *
+ * ⚠️ MEASURED 2026-08-22: the CLI carried 9 of the console's 20 Modal
+ * endpoints, and every missing one was a moat capability. It shipped generic
+ * TTS and transcription — the two things anybody can rent — while the cloned
+ * voice and the talking head, running on GPUs we already pay for, were
+ * reachable only from the web builder. `media.mjs` said so in its own schema:
+ * "voice cloning is not reachable from the CLI and will be refused."
+ *
+ * Declared unconditionally like the rest, for the same reason: the drift guard
+ * must not see a different tool list on a machine with different env. The
+ * per-turn OFFER below is what gates on real configuration.
+ */
+TOOL_SCHEMAS.push(...avatarToolSchemas({
+  MODAL_VIDEO_SECRET: 'declared',
+  MODAL_AVATAR_URL: 'declared', MODAL_VOICE_CLONE_URL: 'declared',
+  MODAL_VOICE_DESIGN_URL: 'declared', MODAL_VIDEO_URL: 'declared',
+}));
+
 /**
  * ── ⭐ THE MODULES THAT WERE BUILT FOR THIS SEAM AND NEVER PLUGGED INTO IT ──
  *
@@ -818,6 +840,14 @@ export function toolNamesForRounds(maxRounds, { allowRun = true, env = process.e
   // the model then LOOKS at the result. Offering it on a single-shot turn buys
   // the render and throws away the check.
   names.push(...imageEditToolNames(env));
+  /**
+   * ⚠️ MULTI-ROUND ONLY, AND THE STRONGEST CASE OF THE THREE. A talking head
+   * is MINUTES of GPU and is priced per video-second. On a single-shot turn
+   * the model would buy the render and then have no round left to look at it,
+   * which is paying for the expensive half of a loop and skipping the half
+   * that makes it correct.
+   */
+  names.push(...avatarToolNames(env));
   names.push('git_status', 'git_diff', 'git_log');
   if (allowRun) names.push('git_commit');
   /**
@@ -1516,6 +1546,34 @@ export async function executeToolCall(call, executor, {
       });
       return { id, name, args, result, mutated: result.ok === true, mutatedPath: result.path ?? null };
     }
+    /**
+     * ── ⭐⭐⭐ THE FOUR MOAT VERBS ────────────────────────────────────────
+     *
+     * ⚠️ ALL FOUR ARE `mutated: true`. Each writes a real file into the
+     * workspace, so the run summary must count it — otherwise a user ends up
+     * with a video on disk that the session never mentioned, which is how a
+     * generated asset becomes a mystery file nobody trusts.
+     *
+     * ⚠️ AND THE EXECUTOR RETURNS `usd`. These are the only verbs here that
+     * spend money per call; the cost travels back with the result rather than
+     * arriving later on a bill.
+     */
+    case 'clone_voice': {
+      const result = await cloneVoice(executor.root, args, { dryRun: executor.dryRun });
+      return { id, name, args, result, mutated: result.ok === true, mutatedPath: result.path ?? null };
+    }
+    case 'design_voice': {
+      const result = await designVoice(executor.root, args, { dryRun: executor.dryRun });
+      return { id, name, args, result, mutated: result.ok === true, mutatedPath: result.path ?? null };
+    }
+    case 'talking_head': {
+      const result = await talkingHead(executor.root, args, { dryRun: executor.dryRun });
+      return { id, name, args, result, mutated: result.ok === true, mutatedPath: result.path ?? null };
+    }
+    case 'generate_video': {
+      const result = await generateVideo(executor.root, args, { dryRun: executor.dryRun });
+      return { id, name, args, result, mutated: result.ok === true, mutatedPath: result.path ?? null };
+    }
     case 'generate_image': {
       /**
        * ⚠️ `mutated: true` — this DOES write a file into the workspace, unlike

package/package.json

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