acuvo-code 0.2.0

package/lib/builtin-skills.mjs

@@ -0,0 +1,135 @@
+/**
+ * ── ⭐⭐⭐ THE SKILLS THAT SHIP WITH ACUVO ───────────────────────────────────
+ *
+ * Roman, 2026-08-17: *"all the Modal integrations, all free opensource tools,
+ * design elements and capabilities, skills, frameworks — it all needs to be in
+ * Acuvo dude. Make it real."*
+ *
+ * ⚠️⚠️ MEASURED THE SAME DAY, AND HE WAS RIGHT: `skills.mjs` is 28,968 bytes of
+ * complete infrastructure — a catalogue, frontmatter parsing, size caps, a
+ * prompt block, tool schemas, tests — and **ZERO SKILLS SHIPPED**. There was no
+ * `.acuvo/skills` directory anywhere in the repo and nothing seeded one. A user
+ * installing the CLI got the loader and an empty shelf.
+ *
+ * That is the house defect at its most expensive: the extensibility system that
+ * makes the product feel deep was finished, and there was nothing in it.
+ *
+ * ── ⭐ BUNDLED, NOT SEEDED ──────────────────────────────────────────────────
+ *
+ * The obvious fix — copy skill files into the user's project on first run — is
+ * the wrong one. It writes into a repo we do not own, it goes stale the moment
+ * we improve a skill, and it turns `git status` noisy in someone else's project.
+ *
+ * Instead these live INSIDE the package and are discovered as a second root.
+ * Upgrading the CLI upgrades the skills, and the user's project stays clean.
+ *
+ * ⚠️ THE PROJECT ALWAYS WINS ON A NAME COLLISION. A user who writes their own
+ * `nextjs-app-router` skill means it — ours is a default, not a policy. Losing
+ * that argument silently would make the product feel like it is fighting them.
+ */
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { discoverSkills, MAX_BUILTIN_SKILLS, loadSkill, SKILLS_DIR } from './skills.mjs';
+
+/** Where the bundled skills live, relative to the package root. */
+export const BUILTIN_SKILLS_DIR = 'skills';
+
+/**
+ * The package root — the directory containing `lib/` and `skills/`.
+ *
+ * ⚠️ DERIVED FROM `import.meta.url`, NOT `process.cwd()`. The CLI runs inside
+ * whatever project the user is in, so cwd is THEIR repo; resolving the bundle
+ * against it would look for our skills inside their tree and silently find
+ * nothing — the exact failure this file exists to end.
+ */
+export function builtinSkillsRoot() {
+  return join(dirname(fileURLToPath(import.meta.url)), '..');
+}
+
+/**
+ * Every skill available this run: the ones we ship, plus the ones the project
+ * defines, with the project taking precedence by name.
+ *
+ * ⚠️ SHAPE-COMPATIBLE WITH `discoverSkills` ON PURPOSE, so `skillsPromptBlock`
+ * and every existing test keep working against it unchanged.
+ *
+ * ⚠️ NEVER THROWS — the same rule `discoverSkills` follows. Assembling the
+ * prompt may never be the thing that kills a run, so a broken bundle degrades
+ * to "the project's skills only" rather than taking the session with it.
+ */
+export function discoverAllSkills(projectRoot, opts = {}) {
+  let builtin = { ok: true, skills: [] };
+  try {
+    // ⚠️ `maxSkills` LAST, so a caller's project-shelf limit cannot silently
+    // truncate the builtin shelf — which is exactly how three shipped skills
+    // vanished. See MAX_BUILTIN_SKILLS in skills.mjs.
+    builtin = discoverSkills(builtinSkillsRoot(), { ...opts, dir: BUILTIN_SKILLS_DIR, maxSkills: MAX_BUILTIN_SKILLS });
+  } catch {
+    builtin = { ok: true, skills: [] };
+  }
+
+  let project = { ok: true, skills: [] };
+  try {
+    project = discoverSkills(projectRoot, opts);
+  } catch {
+    project = { ok: true, skills: [] };
+  }
+
+  const builtinList = Array.isArray(builtin?.skills) ? builtin.skills : [];
+  const projectList = Array.isArray(project?.skills) ? project.skills : [];
+
+  const overridden = new Set(projectList.map((s) => s?.name).filter(Boolean));
+  const merged = [
+    ...projectList,
+    ...builtinList.filter((s) => s?.name && !overridden.has(s.name)),
+  ];
+
+  return {
+    /**
+     * ⚠️⚠️ `ok` IS TRUE WHENEVER WE HAVE SKILLS TO OFFER, and my first version
+     * got this wrong in a way only a test caught. I set it to the PROJECT's
+     * `ok`, reasoning that a user's malformed `.acuvo/skills` should be heard
+     * about. But `skillsPromptBlock` returns NULL on `ok === false` — so any
+     * project without a readable skills directory (which is every project, by
+     * default) suppressed the entire BUNDLED catalogue too. The skills shipped,
+     * were discovered, and never reached the model.
+     *
+     * ⭐ The project's problem is still reported — it rides in `error` — but it
+     * no longer takes our shelf down with it.
+     */
+    ok: merged.length > 0 || project?.ok !== false,
+    dir: project?.dir ?? SKILLS_DIR,
+    skills: merged,
+    skipped: [...(project?.skipped ?? []), ...(builtin?.skipped ?? [])],
+    found: merged.length,
+    capped: (project?.capped ?? 0) + (builtin?.capped ?? 0),
+    scanTruncated: Boolean(project?.scanTruncated || builtin?.scanTruncated),
+    error: project?.error,
+    builtinCount: builtinList.length,
+    overrodeBuiltin: [...overridden].filter((n) => builtinList.some((b) => b.name === n)),
+  };
+}
+
+/**
+ * Load one skill by name, project first then bundled.
+ *
+ * ⚠️ THE ORDER MATCHES DISCOVERY. If the catalogue advertised the project's
+ * version and the loader returned ours, the model would be shown one thing and
+ * handed another — a drift that is invisible in every log.
+ */
+export function loadAnySkill(projectRoot, rawName, opts = {}) {
+  let fromProject = null;
+  try {
+    fromProject = loadSkill(projectRoot, rawName, opts);
+  } catch {
+    fromProject = null;
+  }
+  if (fromProject && fromProject.ok) return fromProject;
+
+  try {
+    return loadSkill(builtinSkillsRoot(), rawName, { ...opts, dir: BUILTIN_SKILLS_DIR });
+  } catch {
+    // Fall back to the project's own refusal so the caller still gets a reason.
+    return fromProject ?? { ok: false, error: 'skill not found' };
+  }
+}

package/lib/cache-floor.mjs

@@ -0,0 +1,204 @@
+/**
+ * ── ⭐⭐ THE INSTRUMENT. THE CACHE RATE IS THE MARGIN, SO IT GETS MEASURED ───
+ *
+ * `lib/plan.mjs` sizes every tier on holding a cache floor, and
+ * `acuvo-gateway/PRICING.md` §5 states the arithmetic behind it:
+ *
+ *     cache floor = sharedHead ÷ typicalPrompt
+ *
+ * ⚠️⚠️ AND UNTIL THIS FILE EXISTED, NEITHER TERM HAD EVER BEEN MEASURED.
+ * PRICING.md tabulates 25k/40k and 40k/60k as illustrations and closes with the
+ * open item *"measure the achieved cache floor"*. A margin that leans on a
+ * number nobody has read off the wire is a margin nobody has.
+ *
+ * ── ⚠️⚠️ SHARED BYTES ARE NOT A SHARED PREFIX, AND THE GAP IS THE WHOLE TRAP ─
+ *
+ * A prompt cache reuses everything up to the FIRST DIFFERING BYTE and pays full
+ * price for everything after it. So "these two requests are 98.9% identical" is
+ * not a cache claim at all — two requests can share 98.9% of their bytes and
+ * cache at exactly 0% if the 1.1% that differs sits at the front.
+ *
+ * ⭐ THAT IS WHY THIS FILE REPORTS BOTH. A probe that reports only the shared
+ * fraction cannot tell "our prefix is perfect and the provider is routing us
+ * somewhere cold" apart from "our prefix moved at byte 200" — and those two have
+ * completely different fixes. `describeDivergence` names the byte, so the
+ * question stops being a guess.
+ *
+ * ⚠️ EVERYTHING HERE IS PURE. It takes strings and returns numbers: no fetch, no
+ * provider, no key. That is deliberate — the half of the cache contract we
+ * control is the bytes we send, and it is the half that can be tested for $0.00
+ * on every commit. What a provider then does with those bytes is measured with
+ * `acuvo --json`'s `.cache` block against a real key, and this file's numbers are
+ * what make that reading interpretable.
+ *
+ * ⚠️ BYTES, NOT TOKENS, AND THE DIFFERENCE IS STATED RATHER THAN HIDDEN. A
+ * tokeniser is provider-specific and we do not ship one; bytes are exact, ours,
+ * and monotone in the thing we care about. A floor computed in bytes is an
+ * ESTIMATE of the floor in tokens — close, because the shared head and the tail
+ * are the same kind of text, and never presented as anything else.
+ */
+
+/**
+ * Length of the byte-identical run the two strings begin with.
+ *
+ * ⚠️ THIS IS THE ONLY QUANTITY A PREFIX CACHE PAYS FOR. Anything shared further
+ * in is shared bytes, not cache.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+export function sharedPrefixBytes(a, b) {
+  const x = String(a ?? '');
+  const y = String(b ?? '');
+  const n = Math.min(x.length, y.length);
+  let i = 0;
+  while (i < n && x[i] === y[i]) i += 1;
+  return i;
+}
+
+/**
+ * Length of the byte-identical run the two strings END with.
+ *
+ * ⭐ WORTH NOTHING TO THE CACHE AND EVERYTHING TO THE DIAGNOSIS. A large shared
+ * suffix beside a small shared prefix is the signature of one varying field near
+ * the front — which is a fix we own. A small shared suffix beside a large shared
+ * prefix is the ordinary, healthy shape: the task text differs and nothing else.
+ *
+ * ⚠️ Clamped so the two runs cannot overlap and double-count on near-identical
+ * inputs — without the clamp two equal strings report `2 × length` shared.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+export function sharedSuffixBytes(a, b) {
+  const x = String(a ?? '');
+  const y = String(b ?? '');
+  const limit = Math.min(x.length, y.length) - sharedPrefixBytes(x, y);
+  if (limit <= 0) return 0;
+  let i = 0;
+  while (i < limit && x[x.length - 1 - i] === y[y.length - 1 - i]) i += 1;
+  return i;
+}
+
+/**
+ * ── ⭐ THE FLOOR, AND WHY IT IS DIVIDED BY THE LARGER PROMPT ────────────────
+ *
+ * `sharedHead ÷ typicalPrompt`. When two prompts differ in length the honest
+ * denominator is the LARGER of the two: the cache pays for the head once and we
+ * are billed for every uncached byte of whichever request is bigger, so dividing
+ * by the smaller would quote a floor no request actually achieves.
+ *
+ * ⚠️ null, never 0 and never NaN, when there is no prompt behind it. A rate with
+ * an empty denominator is not a measurement — the same rule `aggregateCache` in
+ * `turn.mjs` already follows for a session with no reported rounds.
+ *
+ * @param {{ sharedHead: number, typicalPrompt: number }} sizes
+ * @returns {number | null} 0..1
+ */
+export function cacheFloor({ sharedHead, typicalPrompt } = {}) {
+  const head = Number(sharedHead);
+  const prompt = Number(typicalPrompt);
+  if (!Number.isFinite(head) || !Number.isFinite(prompt) || prompt <= 0) return null;
+  if (head <= 0) return 0;
+  // ⚠️ A head longer than the prompt is a caller error, not a floor above 100%.
+  return Math.min(1, head / prompt);
+}
+
+/**
+ * ── ⭐⭐ THE ONE READING THAT ANSWERS "WHY DID THIS NOT CACHE" ──────────────
+ *
+ * Given two wire payloads, returns the shared prefix, the shared suffix, the
+ * floor, and — the part that turns a number into an action — the byte where they
+ * part company with a window of context from each side.
+ *
+ * ⚠️ THE WINDOW IS WHAT MAKES IT USABLE. "diverged at byte 10,693" is a fact
+ * nobody can act on; "diverged at byte 10,693, where A has `git_push` and B does
+ * not" is a fix. `context` bytes either side, clamped to the strings.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @param {{ context?: number }} [opts]
+ */
+export function describeDivergence(a, b, { context = 120 } = {}) {
+  const x = String(a ?? '');
+  const y = String(b ?? '');
+  const prefix = sharedPrefixBytes(x, y);
+  const suffix = sharedSuffixBytes(x, y);
+  const larger = Math.max(x.length, y.length);
+  const identical = x === y;
+  const span = Math.max(0, Math.trunc(context));
+  return {
+    identical,
+    bytesA: x.length,
+    bytesB: y.length,
+    sharedPrefix: prefix,
+    sharedSuffix: suffix,
+    /**
+     * ⚠️ THE FIGURE THAT LOOKS LIKE A CACHE RATE AND IS NOT ONE. Reported so a
+     * reader who has been handed "98.9% shared" can see it beside the number
+     * that actually bills, rather than mistaking one for the other.
+     */
+    sharedFraction: larger > 0 ? (prefix + suffix) / larger : null,
+    floor: cacheFloor({ sharedHead: prefix, typicalPrompt: larger }),
+    /** null when the strings are identical — there is no divergence to point at. */
+    at: identical ? null : prefix,
+    aroundA: identical ? null : x.slice(Math.max(0, prefix - span), prefix + span),
+    aroundB: identical ? null : y.slice(Math.max(0, prefix - span), prefix + span),
+  };
+}
+
+/**
+ * ── ⭐ WHAT A PROVIDER ACTUALLY HASHES, IN THE ORDER IT SEES IT ─────────────
+ *
+ * The tool schemas are a TOP-LEVEL field on the request and are rendered into
+ * the prompt ahead of the messages, so a probe that serialises only
+ * `opts.messages` is measuring the second half of the prefix and calling it the
+ * whole thing. Measured on this repo 2026-08-16: the tools block is **21,466 of
+ * the 22,889 shared bytes** between two tenants — 94% of the entire shared head.
+ * A prefix probe that cannot see it is blind to the part that matters most.
+ *
+ * ⚠️ THIS IS A STABLE SERIALISATION FOR MEASUREMENT, NOT THE WIRE FORMAT.
+ * `callModel` builds the real body with more fields on it; every one of those is
+ * either constant across requests or irrelevant to the prefix. What matters is
+ * that this function is deterministic and puts the same things in the same
+ * order every time it is called, which is exactly what makes two readings
+ * comparable.
+ *
+ * @param {{ tools?: any, messages?: any }} request
+ * @returns {string}
+ */
+/**
+ * ── ⭐⭐ THE SAME BYTES, SERIALISED SO THAT APPENDING EXTENDS THE STRING ─────
+ *
+ * `wireBytes` wraps everything in one JSON object, which is right for comparing
+ * two DIFFERENT requests — the envelope is shared, so it cancels out.
+ *
+ * ⚠️ IT IS WRONG FOR COMPARING ROUND N TO ROUND N+1, and the error looks exactly
+ * like a defect. A conversation is append-only, but `{"messages":[a,b]}` is NOT
+ * a prefix of `{"messages":[a,b,c]}` — the closing `]}` sits between them. So a
+ * perfectly stable loop measures 99.99% and reports drift on every single round.
+ *
+ * ⭐ MEASURED WHEN EXACTLY THAT HAPPENED: 32,272 of 32,274 bytes shared, and the
+ * two missing ones were `]}`. A naive reading of that says "we void our own
+ * cache every round", which is false, and would have sent somebody hunting a
+ * bug that does not exist. **The instrument has to be right before its readings
+ * mean anything.**
+ *
+ * Here each part is serialised separately and joined with a delimiter that
+ * cannot occur in JSON text, so appending a message strictly EXTENDS the string
+ * and an append-only round measures exactly 1.
+ *
+ * ⚠️ This is for round-over-round comparison ONLY. Across two different requests
+ * use `wireBytes` — this one's delimiter is not what any provider receives.
+ */
+export function appendOnlyWireBytes({ tools = null, messages = [] } = {}) {
+  const parts = [JSON.stringify(tools ?? null)];
+  for (const m of messages) parts.push(JSON.stringify(m));
+  return parts.join('');
+}
+
+export function wireBytes({ tools = null, messages = [] } = {}) {
+  return JSON.stringify({ tools, messages });
+}

package/lib/chain.mjs

@@ -0,0 +1,303 @@
+/**
+ * ── ⭐⭐ NEVER SINGLE — THE PROVIDER CHAIN ───────────────────────────────────
+ *
+ * Acuvo Code called OpenRouter and only OpenRouter. If OpenRouter rate-limits or
+ * has a bad ten minutes, **every user of this CLI is dead at once** — not
+ * degraded, dead, mid-task, with whatever they were doing abandoned.
+ *
+ * The console has carried a "never single" doctrine for months and the CLI never
+ * inherited it. An independent review of the product flagged the same thing as
+ * "API redundancy" and it is the most legitimate technical point in it: a
+ * one-provider agent is a one-provider outage.
+ *
+ * ── ⚠️ WHAT IS RETRYABLE, AND WHY THE DISTINCTION IS THE WHOLE FILE ─────────
+ * Retrying the wrong failure is worse than not retrying at all. A 401 retried
+ * three times is three times the wait before the user learns their key is bad,
+ * and a 400 retried is us hammering a provider with a request we malformed.
+ *
+ *   RETRY  429 (rate limit) · 5xx (their fault) · timeout · connection error
+ *   STOP   400 401 403 404 · and anything else 4xx
+ *
+ * ⭐ 402 IS DELIBERATELY NOT RETRYABLE ACROSS MODELS BUT IS ACROSS PROVIDERS.
+ * "This account cannot pay" is permanent for that account this minute; trying a
+ * cheaper model on the same exhausted balance just fails again more slowly.
+ *
+ * ── ⚠️⚠️ AN EMPTY 200 IS A FAILURE, AND IT IS THE ONE THAT ALMOST SHIPPED ───
+ * `qwen3.7-flash`, `deepseek-v4-flash-0731` and `deepseek-v4-pro` all have a
+ * native reasoning budget ON BY DEFAULT that can consume the entire output and
+ * return `content: null` with HTTP 200. Measured earlier in this project: a
+ * bake-off where BOTH v4 models returned 0 bytes and looked like a silent
+ * success. A chain that treats 200 as success would fall through to nothing and
+ * report "the model returned an empty reply" instead of trying the next one.
+ *
+ * ── ⚠️ THE PREFIX MUST NOT MOVE ─────────────────────────────────────────────
+ * Every attempt sends the SAME messages, byte for byte. An identical prompt
+ * prefix caches at a measured 97.2% and cuts call cost 4.3x; reordering,
+ * re-summarising or "trimming for the fallback" would throw that away silently
+ * and nobody would notice except the bill.
+ */
+
+import { callModel } from './model.mjs';
+
+/** Total attempts across the whole chain. Bounded because a loop that retries
+ *  forever is an outage that also costs money. */
+export const MAX_ATTEMPTS = 4;
+
+/**
+ * The order is deliberate: the configured model first (it is what the user
+ * asked for and what the cache is warm on), then progressively more available
+ * fallbacks.
+ *
+ * ⚠️ FREE MODELS LAST, NOT FIRST. They are the most rate-limited things on
+ * OpenRouter, so leading with one would make the common case slower and the
+ * failure case no better. They are here as a floor — something that answers
+ * when nothing else will — not as a cost optimisation.
+ */
+export function buildChain(primary, env = process.env) {
+  const extra = (env.ACUVO_FALLBACK_MODELS ?? '')
+    .split(',').map((s) => s.trim()).filter(Boolean);
+  const defaults = [
+    'deepseek/deepseek-chat',
+    'z-ai/glm-4.6',
+    'qwen/qwen3.7-flash',
+  ];
+  const seen = new Set();
+  return [primary, ...extra, ...defaults].filter((m) => {
+    if (!m || seen.has(m)) return false;
+    seen.add(m);
+    return true;
+  });
+}
+
+/**
+ * Decide what to do with a failed attempt.
+ *
+ * Pure, and separately tested — this is the function that decides whether a
+ * user waits four times as long for a key error.
+ */
+/**
+ * @param {any} error the message, for the cases that still have to be read
+ * @param {'timeout' | 'network' | null} [kind] the structured fact from
+ *   `transportErrorKind`, when the caller has it. ⭐ WHEN PRESENT IT DECIDES,
+ *   because a fact beats a regex over English — see model.mjs's
+ *   `transportErrorKind` for the timeout that never failed over.
+ */
+export function isRetryable(error, kind = null) {
+  /**
+   * ⚠️ ONLY EVER ADDS RETRYABILITY. A 401 or a malformed body fails identically
+   * on every provider, so no kind may turn one of those into four attempts —
+   * and none can, because this returns only `true` and the prose rules below
+   * still get their say when the kind is absent.
+   */
+  if (kind === 'timeout' || kind === 'network') return true;
+
+  const e = String(error ?? '');
+  // Transport: no HTTP status ever arrived.
+  if (/timed out|could not reach|network|ECONNRESET|ECONNREFUSED|ENOTFOUND|fetch failed/i.test(e)) return true;
+  // Their fault.
+  if (/HTTP 5\d\d/.test(e)) return true;
+  if (/HTTP 429|rate.?limit/i.test(e)) return true;
+  /**
+   * ⚠️ The empty-200 case arrives as a normal-looking error string from
+   * extractReply, NOT as an HTTP failure. It must be caught by text, and it is
+   * the single most important line here — see the header.
+   */
+  if (/empty reply|no content|returned nothing/i.test(e)) return true;
+  return false;
+}
+
+/**
+ * ── ⭐ IS THIS FAILURE ABOUT THE REQUEST, OR ABOUT THIS ONE MODEL? ───────────
+ *
+ * `callChain` stops the moment a failure is not retryable, and the reasoning is
+ * right for the case it was written against: a bad key or a malformed body
+ * "will fail identically on every provider", so burning three more attempts
+ * turns a two-second error into an eight-second one.
+ *
+ * ⚠️ THAT ARGUMENT DOES NOT HOLD FOR A FAILURE ABOUT THE MODEL ITSELF. Every
+ * candidate in the chain sends a DIFFERENT model id, so "model not found",
+ * a retired id, or "no endpoints found that support tool use" is a fact about
+ * ONE candidate and says nothing about the next three.
+ *
+ * ⭐ WE PAID FOR THIS ONE ALREADY. The OpenCode integration sat broken because
+ * its configured model was an IMAGE model with no tool support, and every
+ * request returned `404 "No endpoints found that support tool use"`. Three
+ * healthy fallbacks were sitting right there, each of which would have sent a
+ * different id, and the chain refused to try a single one of them.
+ *
+ * ⚠️ DELIBERATELY NARROW. This must match only failures that name the MODEL. A
+ * pattern loose enough to catch a bad key would restore the eight-second error
+ * this whole branch exists to prevent, so 401/403 and body-shape 400s are
+ * excluded explicitly and `test/chain-failover-policy.test.mjs` pins that.
+ */
+/**
+ * ── ⚠️⚠️ A PROVIDER PIN MAKES "NO ENDPOINTS FOUND" MEAN SOMETHING ELSE ───────
+ *
+ * The whole point of this function is that every candidate sends a DIFFERENT
+ * model id, so a failure naming the model says nothing about the next three.
+ * **A provider pin breaks that reasoning, because the pin is the SAME on all
+ * four.** `provider: { order: ['NotAProvider'] }` narrows the endpoint set to
+ * nothing and OpenRouter answers "No endpoints found for <model>" — the model
+ * id is merely what the sentence happens to name.
+ *
+ * ⭐ MEASURED 2026-08-14. With the pin invisible, the chain burned all four
+ * candidates re-sending the identical bad pin, and the error a human finally
+ * read led with "check OPENROUTER_CODEGEN_MODEL against the model catalogue"
+ * about a model that was never wrong. Four round trips to misdiagnose one
+ * environment variable.
+ *
+ * ⚠️ `pinned` DEFAULTS TO FALSE, so every existing caller behaves exactly as
+ * before. This can only ever REMOVE retryability, and only for the one cause
+ * that provably repeats — which keeps the OpenCode case intact: a genuinely
+ * dead model id with no pin still advances through the chain, and that is the
+ * failure this branch was written for in the first place.
+ *
+ * @param {any} error
+ * @param {{ pinned?: boolean }} [opts] `pinned` — a provider pin was sent with
+ *   this request, so an endpoint-shaped failure is at least as likely to be
+ *   about the pin as about the model.
+ */
+export function isModelSpecific(error, { pinned = false } = {}) {
+  const e = String(error ?? '');
+  if (/HTTP 40[13]|invalid api key|unauthoris|unauthoriz|forbidden/i.test(e)) return false;
+  /**
+   * ⚠️ ONLY the endpoint-shaped failure is disclaimed, not the whole family. A
+   * retired or misspelled model id still fails per-candidate under a pin, and
+   * those messages ("model not found", "deprecated model") are unambiguous —
+   * they cannot be produced by narrowing the provider set.
+   */
+  if (pinned && /no endpoints found/i.test(e)) return false;
+  return /no endpoints found|model not found|does not exist|unknown model|no such model|not a valid model|unsupported model|decommission|deprecated model/i.test(e);
+}
+
+/**
+ * Call the chain until something answers.
+ *
+ * Returns the same shape as `callModel`, plus `attempts` and `usedFallback`.
+ *
+ * ⚠️ THE RESULT SAYS WHICH MODEL ANSWERED. A silent downgrade that returns a
+ * weaker model's output without saying so is the dishonest version of this
+ * feature: the user compares two sessions, one is worse, and nothing on screen
+ * explains why.
+ */
+export async function callChain({
+  apiKey, model, messages, tools, timeoutMs, maxTokens, onText = null,
+  env = process.env, callImpl = callModel, onAttempt = null,
+  /**
+   * ⭐ THE STICKY KEY, THREADED. OpenRouter uses it to route every request in a
+   * conversation to the SAME upstream server, which is the half of the caching
+   * story no amount of prefix discipline could reach — see `sessionId` in
+   * model.mjs. It travels with the call rather than being derived here, because
+   * a conversation outlives any one chain attempt.
+   *
+   * ⚠️ IT DELIBERATELY SURVIVES A MODEL DOWNGRADE. Stickiness is tracked per
+   * account PER MODEL, so reusing the id on the fallback model costs nothing
+   * and keeps the ladder's later rounds warm if it stays there.
+   */
+  sessionId = null,
+  /** The observed-warm route, threaded straight through — see warm-provider.mjs. */
+  routeOverride = null,
+  /**
+   * ⭐ INJECTED SO THE BACKOFF IS TESTABLE. A test that really sleeps is a test
+   * nobody runs, and a backoff nobody tests is a backoff that quietly becomes
+   * zero. Production passes the real timer; the suite passes a recorder.
+   */
+  sleepImpl = (ms) => new Promise((r) => setTimeout(r, ms)),
+}) {
+  const chain = buildChain(model, env);
+  const tried = [];
+  let last = null;
+  /**
+   * ⚠️ THE CHAIN HAD NO BACKOFF AT ALL. Every attempt fired immediately and
+   * `Retry-After` was never read, so all four candidates were spent in
+   * milliseconds against a rate limiter that would have served us a second
+   * later — a chain that burns itself out faster than the limiter's window is a
+   * chain only on paper. Waits grow, and an explicit Retry-After always wins
+   * over our guess.
+   */
+  let waitBeforeNext = 0;
+
+  for (const candidate of chain) {
+    if (tried.length >= MAX_ATTEMPTS) break;
+    if (waitBeforeNext > 0) await sleepImpl(waitBeforeNext);
+    tried.push(candidate);
+    if (onAttempt) onAttempt({ model: candidate, attempt: tried.length, of: Math.min(chain.length, MAX_ATTEMPTS) });
+
+    /**
+     * ⚠️ `env` IS FORWARDED, and it was not. It is destructured above precisely
+     * so a library caller can configure a call without touching `process.env`
+     * — the design comment next to the provider-pin code says exactly that —
+     * but it reached only `buildChain`. So a caller that passed
+     * `ACUVO_PROVIDER_ORDER` through `env` had its pin silently ignored while
+     * `callModel` read the ambient environment instead. Production was
+     * unaffected only because `callModel` defaults to `process.env` and the CLI
+     * never passes anything else, which is what kept it invisible.
+     */
+    /**
+     * ⚠️ THE OVERRIDE APPLIES ONLY TO THE MODEL IT WAS LEARNED FOR. A chain
+     * falls back to a DIFFERENT model, whose cache lives somewhere else
+     * entirely, so carrying the pin across would force a cold provider AND
+     * remove its fallback — the exact failure this exists to prevent.
+     */
+    const route = candidate === model ? routeOverride : null;
+    const res = await callImpl({ apiKey, model: candidate, messages, tools, timeoutMs, maxTokens, onText, env, routeOverride: route, sessionId });
+    if (res.ok) {
+      return {
+        ...res,
+        attempts: tried.length,
+        // ⭐ True whenever the answer did NOT come from what was asked for.
+        usedFallback: candidate !== model,
+        chainTried: tried,
+      };
+    }
+
+    last = res;
+
+    /**
+     * ⭐ HOW LONG BEFORE THE NEXT CANDIDATE. An explicit `Retry-After` from the
+     * provider always wins — guessing over an instruction is how a client gets
+     * itself throttled harder. Otherwise 500ms, doubling, capped, so four
+     * attempts span about three seconds rather than forty milliseconds.
+     */
+    waitBeforeNext = Number.isFinite(res.retryAfterMs) && res.retryAfterMs > 0
+      ? Math.min(res.retryAfterMs, 30_000)
+      : Math.min((waitBeforeNext || 250) * 2, 4_000);
+
+    /**
+     * ⭐ A FAILURE ABOUT THIS ONE MODEL IS NOT A FAILURE ABOUT THE CHAIN. The
+     * next candidate sends a DIFFERENT model id, so a 404 here proves nothing
+     * about it — see `isModelSpecific`. Advancing costs one more attempt;
+     * stopping costs the whole capability, which is precisely what happened to
+     * the OpenCode integration.
+     */
+    if (isModelSpecific(res.error, { pinned: Array.isArray(res.providerPin) && res.providerPin.length > 0 })) continue;
+
+    /**
+     * ⭐ `res.kind` is the structured transport fact when `callModel` had one
+     * (model.mjs `transportErrorKind`). It is absent for HTTP failures, where
+     * the message still decides — so this reads the fact first and the prose
+     * second, which is the only ordering that stops the two drifting apart.
+     */
+    if (!isRetryable(res.error, res.kind ?? null)) {
+      /**
+       * ⚠️ STOP IMMEDIATELY, AND SAY THE CHAIN STOPPED EARLY. A bad key or a
+       * malformed request will fail identically on every provider; burning the
+       * remaining attempts turns a two-second error into an eight-second one and
+       * teaches the user that the tool is slow rather than that their key is
+       * wrong.
+       */
+      return { ...res, attempts: tried.length, usedFallback: false, chainTried: tried, stoppedEarly: true };
+    }
+  }
+
+  return {
+    ok: false,
+    error: [
+      `every provider in the chain failed after ${tried.length} attempt${tried.length === 1 ? '' : 's'}.`,
+      `tried: ${tried.join(' → ')}`,
+      `last error: ${last?.error ?? 'unknown'}`,
+    ].join('\n'),
+    attempts: tried.length,
+    chainTried: tried,
+  };
+}