amicus 4.9.2 → 4.9.4

package/src/utils/live-probes.js

@@ -0,0 +1,53 @@
+/**
+ * @module live-probes
+ * The single gate on outbound AUTHENTICATED network probes made by diagnostics
+ * (`amicus doctor` / `init` / the setup finale), which run with the user's real
+ * stored keys.
+ *
+ * OPT-IN, NOT OPT-OUT. `bin/amicus.js` — the one entry point every command
+ * routes through — calls enable() at startup. Nothing else does, so a module
+ * required directly (by a test, a script, another tool) can never probe.
+ *
+ * ⚠️ WHY IT IS SHAPED THIS WAY. The first version detected test RUNNERS
+ * instead: JEST_WORKER_ID, VITEST, NODE_TEST_CONTEXT. That is a blocklist
+ * heuristic, and a blocklist is only as good as its enumeration — a bespoke
+ * runner, a plain `node script.js`, or a harness nobody thought of walks
+ * straight past it and spends the developer's credentials. Council review of
+ * PR 222. Detecting "am I in a test?" is unbounded; asserting "I am the CLI"
+ * is a single known fact, so the burden moved to the side that can actually
+ * discharge it.
+ *
+ * ⚠️ AND WHY THAT IS SAFE. Inverting a default risks the opposite failure: miss
+ * an entry point and production silently stops probing. That is survivable
+ * ONLY because a skipped probe is never reported as healthy — callers must
+ * surface it as unverified (see doctor-key-auth-check.js and the
+ * `openrouter-credit` row). Worst case is a visible warn, never a false green.
+ * If you add an entry point that should probe, call enable() there; if you
+ * forget, `doctor` says so out loud.
+ */
+
+'use strict';
+
+let enabled = false;
+
+/** Allow live probes for the remainder of this process. Called by bin/amicus.js. */
+function enableLiveProbes() {
+  enabled = true;
+}
+
+/**
+ * Whether a live authenticated probe may run right now.
+ * `AMICUS_NO_NETWORK_PROBES=1` forces off even for the CLI — an escape hatch
+ * for air-gapped or rate-limited environments.
+ */
+function liveProbesAllowed() {
+  if (process.env.AMICUS_NO_NETWORK_PROBES === '1') { return false; }
+  return enabled;
+}
+
+/** Test-only: restore the default (disabled) state. */
+function _resetLiveProbes() {
+  enabled = false;
+}
+
+module.exports = { enableLiveProbes, liveProbesAllowed, _resetLiveProbes };

package/src/utils/model-catalog.js

@@ -20,6 +20,10 @@ const path = require('path');
 function _getConfigDir() { return require('./config').getConfigDir(); }
 function _readApiKeyValues() { return require('./api-key-store').readApiKeyValues(); }
 async function _fetchAllModels(keys) { return require('./model-fetcher').fetchAllModelsDetailed(keys); }
+async function _enrichCeilings(rows) { return require('./model-ceilings-modelsdev').enrichCeilings(rows); }
+function _emptyOutcome(failure) { return require('./model-ceilings-modelsdev').emptyOutcome(failure); }
+/** #218 P3 opt-out: `modelsDevCeilings: false` in config.json, and ONLY a literal false. */
+function _modelsDevEnabled() { return require('./config').loadConfig()?.modelsDevCeilings !== false; }
 
 const DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24h
 const CATALOG_SCHEMA_VERSION = 2;
@@ -68,8 +72,13 @@ function writeCacheDoc(doc) {
   }
 }
 
-/** Write a successful fetch: fresh models/fetchedAt, outcome fields cleared. @param {Array} models */
-function writeCache(models, providerFailures) {
+/**
+ * Write a successful fetch: fresh models/fetchedAt, outcome fields cleared.
+ * @param {Array} models
+ * @param {Array} [providerFailures]
+ * @param {object|null} [ceilingEnrichment] #218 P3 outcome for THESE rows (model-ceilings-modelsdev.js)
+ */
+function writeCache(models, providerFailures, ceilingEnrichment) {
   writeCacheDoc({
     schemaVersion: CATALOG_SCHEMA_VERSION,
     fetchedAt: Date.now(),
@@ -78,6 +87,7 @@ function writeCache(models, providerFailures) {
     // alongside the rows because it describes THESE rows -- a cache served later
     // is still a catalog whose deepseek namespace is empty for a reason.
     providerFailures: Array.isArray(providerFailures) ? providerFailures : [],
+    ceilingEnrichment: ceilingEnrichment || null,
   });
 }
 
@@ -124,7 +134,27 @@ async function refreshCatalog() {
     writeRefreshFailure(reason, providerFailures);
     return [];
   }
-  writeCache(models, providerFailures);
+  // #218 P3: fill direct-provider ceilings from models.dev AFTER the floor-only
+  // check (a failed refresh is never enriched, so "stale cache stands" holds)
+  // and IN PLACE on the fresh row objects, so `authoritative`/`local` ride
+  // through untouched. enrichCeilings never rejects; the belt-and-braces catch
+  // keeps a bug there from failing a refresh that already succeeded.
+  // Council #230 D1/C2: `modelsDevCeilings: false` means models.dev is never
+  // contacted. The persisted outcome still carries the full counter set, so
+  // `--json` readers and the `Ceilings:` line see "disabled", not a blank.
+  let ceilingEnrichment;
+  if (!_modelsDevEnabled()) {
+    ceilingEnrichment = { ..._emptyOutcome(null), skipped: 'disabled' };
+  } else {
+    try {
+      ceilingEnrichment = await _enrichCeilings(models);
+    } catch (err) {
+      // Same shape enrichCeilings' own failures use (council #230 C4/D5), so every
+      // reader of ceilingEnrichment sees the full counter set however it failed.
+      ceilingEnrichment = _emptyOutcome({ reason: 'exception', detail: err.message });
+    }
+  }
+  writeCache(models, providerFailures, ceilingEnrichment);
   return models;
 }
 
@@ -154,7 +184,7 @@ async function getCatalog(opts = {}) {
  * #13: also threads the last-refresh outcome so callers can tell "current"
  * apart from "stale because refreshing keeps failing" — null/null when the
  * last attempt on record succeeded (or none has happened yet).
- * @returns {Promise<{models: Array, fetchedAt: number|null, lastRefreshAttempt: number|null, lastRefreshError: string|null}>}
+ * @returns {Promise<{models: Array, fetchedAt: number|null, lastRefreshAttempt: number|null, lastRefreshError: string|null, providerFailures: Array, ceilingEnrichment: object|null}>}
  */
 async function getCatalogInfo(opts = {}) {
   const models = await getCatalog(opts);
@@ -167,6 +197,8 @@ async function getCatalogInfo(opts = {}) {
     lastRefreshError: (doc && doc.lastRefreshError) || null,
     // #209: namespace-level fetch outcomes for the CACHED rows above.
     providerFailures: (doc && Array.isArray(doc.providerFailures)) ? doc.providerFailures : [],
+    // #218 P3: where the direct-provider ceilings came from, or why they did not.
+    ceilingEnrichment: (doc && doc.ceilingEnrichment) || null,
   };
 }
 

package/src/utils/model-ceilings-modelsdev.js

@@ -0,0 +1,230 @@
+/**
+ * @module model-ceilings-modelsdev
+ * #218 P3 — output ceilings for the direct-provider catalog rows.
+ *
+ * WHY: computeModelLimit (model-output-limit.js) refuses to emit a `limit`
+ * descriptor unless the catalog knows BOTH a model's context and its output
+ * ceiling — a blanket budget against an unknown ceiling would send an
+ * over-ceiling max_tokens. OpenRouter publishes its ceiling on /models; the
+ * direct openai/anthropic/deepseek lists do not (google's does, lifted
+ * first-party in model-fetcher.js). models.dev publishes all of them, keyless.
+ *
+ * WHAT THIS DOES NOT CHANGE: the engine already resolves every `{}` descriptor's
+ * limit from its own models.dev copy. This gives AMICUS the same numbers so it
+ * can clamp an outputBudget on the direct anthropic/deepseek routes through the
+ * descriptor (a route it cannot clamp still gets the budget through the engine
+ * flag — engine-output-flag.js) and name a reservation in a dead-leg note. The
+ * direct openai route is the exception: the engine drives that provider through
+ * the Responses API, whose request carries no output-limit field at all, so the
+ * ceiling filled here shows in `amicus models` but neither the descriptor nor
+ * the flag reaches the wire there — a direct openai row sends no output
+ * reservation at all (#218 PR 4, probe M5/M13/M22). It reads models.dev
+ * directly, not the engine's cache file, because that file's path and refresh
+ * flags are engine-private.
+ *
+ * RULES (measured 2026-09-04 against live data, see the plan):
+ *   - the provider's own value WINS: models.dev fills a field only when the
+ *     provider gave no usable positive integer — null, 0, negative or malformed
+ *     — and a usable provider value is never overwritten (OpenRouter and
+ *     models.dev disagree on 24 of 344 openrouter ceilings);
+ *   - a zero/absent models.dev limit is never written (openai image rows);
+ *   - `openrouter/openrouter/*` meta-routers are skipped (models.dev says
+ *     2,000,000 for `auto`, a number no underlying model honours);
+ *   - local rows are skipped; the fill is IN PLACE so `authoritative`/`local`
+ *     flags on the row objects ride through untouched;
+ *   - the FETCH ITSELF is skipped when no candidate row is missing a ceiling,
+ *     and `model-catalog.js` skips this module entirely when the config key
+ *     `modelsDevCeilings` is `false` (council #230 D1/C2): a refresh that has
+ *     nothing to fill must not spend up to 10 s asking.
+ */
+'use strict';
+
+const { positiveCount } = require('./model-output-limit');
+
+const MODELS_DEV_URL = 'https://models.dev/api.json';
+const MODELS_DEV_TIMEOUT_MS = 10000;
+/** The vendors amicus catalogs under these exact id prefixes (model-fetcher.js normalizers). */
+const VENDORS = ['anthropic', 'openai', 'google', 'deepseek', 'openrouter'];
+
+/**
+ * Index a models.dev api.json document by amicus catalog id. A positive
+ * finite integer count, or null — reuses `positiveCount` from
+ * model-output-limit.js so this module holds the same discipline as that one.
+ * @param {*} api parsed https://models.dev/api.json
+ * @returns {Map<string, {context: number|null, output: number|null}>}
+ */
+function limitsFromModelsDev(api) {
+  const out = new Map();
+  if (!api || typeof api !== 'object') { return out; }
+  for (const vendor of VENDORS) {
+    const models = api[vendor] && api[vendor].models;
+    if (!models || typeof models !== 'object') { continue; }
+    for (const [modelId, m] of Object.entries(models)) {
+      const limit = (m && typeof m === 'object' && m.limit) || {};
+      const context = positiveCount(limit.context);
+      const output = positiveCount(limit.output);
+      if (context === null && output === null) { continue; }
+      out.set(`${vendor}/${modelId}`, { context, output });
+    }
+  }
+  return out;
+}
+
+/**
+ * Why this row is not a fill candidate, or null when it is one. THE single
+ * definition: `fillCeilings` counts each class and `needsFillCount` collapses
+ * them to a boolean, so the pass and the nothing-to-fill check cannot disagree
+ * about which rows the fetch could serve.
+ * @param {*} row a catalog row
+ * @returns {null|'malformed'|'local'|'router'}
+ */
+function skipClass(row) {
+  if (!row || typeof row !== 'object' || typeof row.id !== 'string') { return 'malformed'; }
+  if (row.local === true) { return 'local'; }
+  if (row.id.startsWith('openrouter/openrouter/')) { return 'router'; }
+  return null;
+}
+
+/**
+ * Does this row still lack a number outputBudget needs? computeModelLimit
+ * refuses to emit a descriptor unless BOTH ceilings are known, so one usable
+ * field is not "known" for any purpose the fill exists to serve.
+ * @param {object} row a catalog row
+ * @returns {boolean}
+ */
+function missingACeiling(row) {
+  return positiveCount(row.contextLength) === null || positiveCount(row.maxOutputTokens) === null;
+}
+
+/**
+ * Fill contextLength / maxOutputTokens in place. A field is filled ONLY when the
+ * provider gave no usable positive integer for it — `positiveCount(...) === null`,
+ * i.e. null, 0, negative, below 1 or non-numeric. (`positiveCount` FLOORS, so
+ * 1.5 is a usable 1; only a fraction below 1 falls through.) A usable provider
+ * value is never overwritten. A filled row is stamped `limitSource: 'models.dev'`,
+ * which marks a row where AT LEAST ONE field was filled from models.dev — not a
+ * claim that both numbers came from there (council #230 D2).
+ *
+ * COUNTERS. `filled` / `alreadyKnown` / `unknown` describe what the pass did;
+ * `stillMissing` describes the STATE it left behind and deliberately overlaps
+ * them. `alreadyKnown` means both fields were usable BEFORE the pass, and is
+ * decided BEFORE the models.dev lookup (council #230 A2) — a complete row
+ * models.dev does not list is `alreadyKnown`, not `unknown`. A row with one
+ * field known and the other unfillable is `stillMissing`, never "already known"
+ * (council #230 C1/D5): outputBudget cannot clamp it.
+ * @param {Array<object>} rows catalog rows (mutated)
+ * @param {Map<string, {context: number|null, output: number|null}>} limits
+ * @returns {{filled: number, alreadyKnown: number, unknown: number, stillMissing: number,
+ *   skippedRouters: number, skippedLocal: number}}
+ */
+function fillCeilings(rows, limits) {
+  const counts = { filled: 0, alreadyKnown: 0, unknown: 0, stillMissing: 0, skippedRouters: 0, skippedLocal: 0 };
+  for (const row of Array.isArray(rows) ? rows : []) {
+    const skip = skipClass(row);
+    if (skip === 'malformed') { continue; }
+    if (skip === 'local') { counts.skippedLocal++; continue; }
+    if (skip === 'router') { counts.skippedRouters++; continue; }
+    // BEFORE the lookup (council #230 A2): a row that already carries both
+    // usable numbers has nothing for models.dev to fill, so whether models.dev
+    // happens to list it is irrelevant. Looking first counted such a row
+    // `unknown` when models.dev did not have it — reporting a row outputBudget
+    // CAN clamp as one it knows nothing about.
+    if (!missingACeiling(row)) { counts.alreadyKnown++; continue; }
+    const lim = limits.get(row.id);
+    if (!lim) {
+      counts.unknown++;
+    } else {
+      let touched = false;
+      if (positiveCount(row.contextLength) === null && lim.context !== null) { row.contextLength = lim.context; touched = true; }
+      if (positiveCount(row.maxOutputTokens) === null && lim.output !== null) { row.maxOutputTokens = lim.output; touched = true; }
+      if (touched) { row.limitSource = 'models.dev'; counts.filled++; }
+    }
+    if (missingACeiling(row)) { counts.stillMissing++; }
+  }
+  return counts;
+}
+
+/**
+ * How many candidate rows the fetch could possibly help. Zero means the network
+ * call has nothing to do and is skipped entirely (council #230 D1/C2).
+ * @param {Array<object>} rows catalog rows
+ * @returns {number}
+ */
+function needsFillCount(rows) {
+  let n = 0;
+  for (const row of Array.isArray(rows) ? rows : []) {
+    if (skipClass(row) === null && missingACeiling(row)) { n++; }
+  }
+  return n;
+}
+
+/**
+ * The outcome a FAILED — or SKIPPED — enrichment persists: the failure plus
+ * every counter at zero. One shape, so this module's own failure returns and
+ * `model-catalog.js :: refreshCatalog`'s belt-and-braces catch cannot drift
+ * apart and `models-ceiling-line.js :: fmtCeilingLine` always has the counters
+ * it prints. `skipped` defaults to null and a caller that skipped the fetch
+ * spreads its own reason over it.
+ * @param {null|{reason: string, status?: number, detail?: string}} failure
+ * @returns {{source: 'models.dev', failure: object|null, skipped: null, filled: number,
+ *   alreadyKnown: number, unknown: number, stillMissing: number, skippedRouters: number,
+ *   skippedLocal: number}}
+ */
+function emptyOutcome(failure) {
+  return {
+    source: 'models.dev', failure, skipped: null,
+    filled: 0, alreadyKnown: 0, unknown: 0, stillMissing: 0, skippedRouters: 0, skippedLocal: 0,
+  };
+}
+
+/**
+ * Fetch models.dev and fill `rows`. ALWAYS resolves; the outcome travels with
+ * the rows it describes (model-catalog.js persists it as ceilingEnrichment).
+ * Failure reasons are http-get's (`timeout`, `network-error`, `http-status`,
+ * `too-large`, `parse-error`) plus `bad-shape` and `exception`.
+ *
+ * NO CALL IS MADE when no candidate row is missing a ceiling: the outcome is
+ * `skipped: 'nothing-to-fill'` and models.dev is never contacted (council #230
+ * D1/C2 — a refresh on a fully-known catalog paid up to 10 s for nothing).
+ * @param {Array<object>} rows catalog rows (mutated in place)
+ * @param {{getJson?: Function}} [deps] test seam
+ * @returns {Promise<{source: 'models.dev', failure: null|{reason: string, status?: number, detail?: string},
+ *   skipped: null|'nothing-to-fill', filled: number, alreadyKnown: number, unknown: number,
+ *   stillMissing: number, skippedRouters: number, skippedLocal: number}>}
+ */
+async function enrichCeilings(rows, deps = {}) {
+  const getJson = deps.getJson || require('./http-get').getJson;
+  if (needsFillCount(rows) === 0) {
+    return { ...emptyOutcome(null), skipped: 'nothing-to-fill' };
+  }
+  let res;
+  try {
+    res = await getJson(MODELS_DEV_URL, {
+      timeoutMs: MODELS_DEV_TIMEOUT_MS,
+      followRedirects: true,
+      headers: { 'User-Agent': `amicus/${require('../../package.json').version}` },
+    });
+  } catch (err) {
+    return emptyOutcome({ reason: 'exception', detail: err.message });
+  }
+  if (!res || !res.ok) {
+    return emptyOutcome((res && res.failure) || { reason: 'exception', detail: 'no result' });
+  }
+  const limits = limitsFromModelsDev(res.json);
+  // A 200 that parses but carries no recognised vendor limits — `{}`, an error
+  // object, a reshaped api.json — would otherwise persist as a SUCCESSFUL
+  // enrichment with every candidate row `unknown`, silently leaving direct-provider
+  // ceilings unfilled and outputBudget unable to clamp them (council #230 C1).
+  // It is a failure, and the rows are not touched.
+  if (limits.size === 0) {
+    return emptyOutcome({ reason: 'bad-shape', detail: 'no recognised vendor limits in api.json' });
+  }
+  return { source: 'models.dev', failure: null, skipped: null, ...fillCeilings(rows, limits) };
+}
+
+// `enrichCeilings` — the entry point — is first so the generated architecture
+// map, which lists a module's first five exports, actually names it.
+module.exports = {
+  enrichCeilings, fillCeilings, needsFillCount, limitsFromModelsDev, emptyOutcome,
+  MODELS_DEV_URL, MODELS_DEV_TIMEOUT_MS,
+};

package/src/utils/model-fetcher.js

@@ -5,7 +5,7 @@
  * Uses the same HTTPS pattern as api-key-store.js validateApiKey().
  */
 
-const https = require('https');
+const { httpGetText } = require('./http-get');
 
 /**
  * Hardcoded Anthropic floor: the anthropic/ rows a KEYLESS user (or a
@@ -45,6 +45,8 @@ const PROVIDER_FETCH_CONFIG = {
         id: `openrouter/${m.id}`,
         name: m.name || m.id,
         contextLength: m.context_length ?? null,
+        // #218: real output ceiling (411/417 rows); clamps outputBudget -- see utils/model-output-limit.js.
+        maxOutputTokens: (m.top_provider && m.top_provider.max_completion_tokens) ?? null,
         pricing: m.pricing
           ? { prompt: m.pricing.prompt ?? null,
               completion: m.pricing.completion ?? null }
@@ -62,6 +64,9 @@ const PROVIDER_FETCH_CONFIG = {
         id: `google/${m.name.replace('models/', '')}`,
         name: m.displayName || m.name.replace('models/', ''),
         contextLength: m.inputTokenLimit ?? null,
+        // #218 P3: Google's ListModels publishes the ceiling first-party; models.dev fills only
+        // what the provider left empty or unusable.
+        maxOutputTokens: m.outputTokenLimit ?? null,
         pricing: null
       }));
     }
@@ -146,43 +151,16 @@ function fetchModelsFromProvider(provider, key) {
  * @param {string} key - API key
  * @returns {Promise<{rows: Array, failure: {reason: string, status?: number, detail?: string}|null}>}
  */
-function fetchViaConfigDetailed(provider, key) {
+async function fetchViaConfigDetailed(provider, key) {
   const config = PROVIDER_FETCH_CONFIG[provider];
   const url = config.buildUrl ? config.buildUrl(key) : config.url;
-  const headers = config.authHeader(key);
-
-  return new Promise((resolve) => {
-    let chunks = '';
-    const ok = (rows) => resolve({ rows, failure: null });
-    const fail = (failure) => resolve({ rows: [], failure });
-
-    const timer = setTimeout(() => {
-      req.destroy();
-      fail({ reason: 'timeout', detail: `no response within ${FETCH_TIMEOUT_MS}ms` });
-    }, FETCH_TIMEOUT_MS);
-
-    const req = https.get(url, { headers }, (res) => {
-      if (res.statusCode !== 200) {
-        clearTimeout(timer);
-        res.on('data', () => {});
-        res.on('end', () => fail({ reason: 'http-status', status: res.statusCode }));
-        return;
-      }
-      res.on('data', (chunk) => { chunks += chunk; });
-      res.on('end', () => {
-        clearTimeout(timer);
-        try {
-          ok(config.normalize(chunks));
-        } catch (err) {
-          fail({ reason: 'parse-error', detail: err.message });
-        }
-      });
-    });
-    req.on('error', (err) => {
-      clearTimeout(timer);
-      fail({ reason: 'network-error', detail: err.message });
-    });
-  });
+  const res = await httpGetText(url, { headers: config.authHeader(key), timeoutMs: FETCH_TIMEOUT_MS });
+  if (!res.ok) { return { rows: [], failure: res.failure }; }
+  try {
+    return { rows: config.normalize(res.body), failure: null };
+  } catch (err) {
+    return { rows: [], failure: { reason: 'parse-error', detail: err.message } };
+  }
 }
 
 /**

package/src/utils/model-output-limit.js

@@ -0,0 +1,132 @@
+/**
+ * @module model-output-limit
+ * Issue #218 — the per-model `limit` descriptor amicus hands opencode.
+ *
+ * THE PROBLEM: every council leg reserved `max_tokens: 32000` regardless of the
+ * model's real ceiling. OpenRouter validates that RESERVATION against remaining
+ * credit BEFORE serving, so legs died in 2.2s with zero tokens and a literal
+ * "You requested up to 32000 tokens, but can only afford 354". amicus never set
+ * the value — `buildProviderModels` registered every model as `{}`, leaving
+ * opencode's own default to govern.
+ *
+ * WHERE 32000 COMES FROM (measured, in the pinned 1.18.15 binary, not inferred):
+ *
+ *     var MY=32000
+ *     function Hy($,Z=MY){return Math.min($.limit.output,Z)||Z}
+ *
+ * i.e. `ProviderTransform.maxOutputTokens(model) = Math.min(model.limit.output,
+ * OUTPUT_TOKEN_MAX)`. Three consequences, each a trap:
+ *
+ *   1. Supplying the model's REAL ceiling through THIS DESCRIPTOR ALONE is
+ *      ARITHMETICALLY INERT. kimi-k3's true ceiling is 943,718 and
+ *      Math.min(943718, 32000) is still 32000. Through the descriptor only a
+ *      value BELOW OUTPUT_TOKEN_MAX changes the outbound request. Raising
+ *      OUTPUT_TOKEN_MAX itself is engine-output-flag.js's job (PR 2): with the
+ *      flag set to the same budget the two levers agree on min(budget, ceiling)
+ *      — measured, probe rows C2 and K6.
+ *   2. `limit.context` is MANDATORY whenever `limit` is present. A `limit` with
+ *      only `output` is a hard ConfigInvalidError — and it poisons the ENTIRE
+ *      config for the server's lifetime, not just that model. Measured against
+ *      a live `opencode serve` + GET /config/providers.
+ *   3. `output: 0` is swallowed by the `|| Z` and falls back to 32000.
+ *
+ * WHAT THIS DOES NOT FIX. #218 conflates two modes that pull in OPPOSITE
+ * directions on this one knob. Mode 1 (credit rejection) needs the reservation
+ * LOWERED — this descriptor does that. Mode 2 (a leg spending its whole
+ * allowance on reasoning and emitting 0-2 output tokens) needs it RAISED, which
+ * this descriptor cannot do (the Math.min) and the engine flag can
+ * (engine-output-flag.js) — but its real cause is reasoning effort, which #218
+ * PR 4 now delivers: `--thinking` reaches the engine as its `variant` field, not
+ * the `reasoning` object the prompt API never read (F1), and is checked against
+ * the model's own declaration first — so on the one route where a variant moves
+ * the reservation the leg is refused, not silently overshot (M2: 24000 + 16000 =
+ * 40000; the fit that lands the sum on the budget is M17). Lowering the budget
+ * makes such a leg fail faster and cheaper; raising it gives the reasoning more
+ * room. Neither makes it produce output, and no claim is made that either does.
+ *
+ * POLICY: opt-in, no default change. With no configured budget every model is
+ * still registered as `{}` and no engine flag is set — byte-identical to
+ * pre-#218 behaviour.
+ */
+
+'use strict';
+
+/**
+ * A usable positive, finite INTEGER count. Rejects strings, booleans, NaN,
+ * Infinity, and anything that floors to zero.
+ *
+ * ⚠️ Order matters, and getting it wrong was council finding C2 on PR #221.
+ * Testing `v > 0` BEFORE flooring let 0.5 through and returned `Math.floor(0.5)`
+ * === 0 — breaking this function's own "positive integer, or null" contract.
+ * Downstream that was worse than a bad number: computeModelLimit's
+ * `Math.max(1, ...)` guard, which exists to stop `output: 0` reaching opencode,
+ * laundered the bogus 0 into a bogus `output: 1` — a ONE-TOKEN reservation on
+ * every leg. A hardening masking the very input it was meant to reject. Floor
+ * first, then test positivity, so a sub-1 value is rejected outright.
+ */
+function positiveCount(v) {
+  if (typeof v !== 'number' || !Number.isFinite(v) || v <= 0) { return null; }
+  const n = Math.floor(v);
+  return n > 0 ? n : null;
+}
+
+/**
+ * Coerce a configured output budget to a usable integer, or null.
+ * null means "emit no limit" — the opt-in default, and today's behaviour.
+ * @param {*} v raw `config.outputBudget`
+ * @returns {number|null}
+ */
+function normalizeOutputBudget(v) {
+  // `typeof true === 'boolean'` and `'8000'` is a string: both rejected. A
+  // config knob is only honoured when it is unambiguously a number.
+  return positiveCount(v);
+}
+
+/**
+ * Index catalog rows by full route id for O(1) lookup during route walking.
+ * A Map (not an object) so a model id colliding with an Object.prototype member
+ * — 'constructor', 'toString' — cannot resolve to an inherited function. Same
+ * discipline as the `__proto__: null` alias table in config.js.
+ * @param {Array<{id:string, contextLength:?number, maxOutputTokens:?number}>} models
+ * @returns {Map<string, {contextLength:?number, maxOutputTokens:?number}>}
+ */
+function buildLimitLookup(models) {
+  const out = new Map();
+  if (!Array.isArray(models)) { return out; }
+  for (const m of models) {
+    if (!m || typeof m !== 'object' || typeof m.id !== 'string') { continue; }
+    out.set(m.id, {
+      contextLength: m.contextLength ?? null,
+      maxOutputTokens: m.maxOutputTokens ?? null,
+    });
+  }
+  return out;
+}
+
+/**
+ * The `limit` descriptor for one model, or null when it must not be emitted.
+ *
+ * Returns null — meaning "register as `{}`, exactly as before" — whenever any
+ * input is missing or unusable. That is deliberate: a partial descriptor is not
+ * a partial improvement here, it is a fatal config error (rule 2 above).
+ *
+ * @param {?{contextLength:?number, maxOutputTokens:?number}} row catalog row
+ * @param {?number} budget normalized output budget
+ * @returns {?{context:number, output:number}}
+ */
+function computeModelLimit(row, budget) {
+  const want = positiveCount(budget);
+  if (want === null || !row || typeof row !== 'object') { return null; }
+
+  const context = positiveCount(row.contextLength);
+  const ceiling = positiveCount(row.maxOutputTokens);
+  // Both or neither. Without a known ceiling a blanket budget would REGRESS a
+  // small model: an 8000 budget against a real 4096 ceiling sends an
+  // over-ceiling max_tokens, where today opencode's own Math.min keeps it
+  // correct. The ceiling is a hard requirement for clamping, not a nicety.
+  if (context === null || ceiling === null) { return null; }
+
+  return { context, output: Math.max(1, Math.min(ceiling, want)) };
+}
+
+module.exports = { normalizeOutputBudget, buildLimitLookup, computeModelLimit, positiveCount };