amicus 4.9.3 → 4.9.5

package/src/utils/http-get.js

@@ -0,0 +1,284 @@
+/**
+ * @module http-get
+ * One HTTPS GET, always resolved, never rejected — the timer/destroy/failure
+ * core that model-fetcher.js :: fetchViaConfigDetailed carried inline (#209)
+ * and that the models.dev ceiling fetch (#218 P3) needs too. Extracted rather
+ * than copied so a second caller cannot drift from the first: the same failure
+ * reasons and the same {reason, status?, detail?} shape the catalog persists
+ * as providerFailures.
+ *
+ * The call shape is deliberately `https.get(url, { headers }, cb)` — the one
+ * tests/model-fetcher.test.js mocks — so that suite keeps intercepting after
+ * the extraction.
+ *
+ * REDIRECTS ARE OPT-IN, AND THEN FOLLOWED AT MOST TWICE (council #230 A2, made
+ * opt-in by #230 D4). Without `followRedirects: true` a 3xx is the terminal
+ * `http-status` failure it has always been — the keyed provider fetches in
+ * `model-fetcher.js` never hop, so a provider's redirect stays a visible
+ * failure rather than a silent behavioural change. With the option on, a
+ * 301/302/303/307/308 carrying a `Location` is resolved against the URL that
+ * produced it and re-issued under the SAME deadline — one timeout covers the
+ * whole chain, so a hop never buys the server more time. The target must be
+ * `https:`. A plain-http Location, a missing Location and a third redirect are
+ * each an `http-status` failure carrying the status plus a `detail` naming
+ * which, so a domain move that loops or downgrades stays visible on the
+ * caller's failure line (for the models.dev ceiling fetch, the `Ceilings:` line
+ * of `amicus models --refresh`) instead of being chased silently.
+ *
+ * ONLY AN ALLOWLIST OF HEADERS CROSSES AN ORIGIN (council #230 C3). `model-fetcher.js`
+ * hands this module `Authorization: Bearer <key>` (openrouter/openai/deepseek)
+ * or `x-api-key` (anthropic), so a 302 — or an open redirect — on a provider
+ * host would otherwise forward a live key to whatever host the `Location`
+ * named. A same-origin hop keeps every header; a CROSS-ORIGIN hop keeps ONLY
+ * `user-agent`, `accept` and `accept-language` (matched
+ * case-insensitively) and drops everything else. An allowlist rather than a
+ * deny-list because the deny-list has to be extended for every new vendor
+ * header — `x-goog-api-key` was not on it — and the one that is forgotten is
+ * the one that leaks. Once dropped, stay dropped: the stripped set is what the
+ * next hop carries, so a same-origin third hop cannot resurrect a credential.
+ * `accept-encoding` is NOT on the allowlist (council #230 C3): nothing here
+ * decodes a content-encoded body, so forwarding it would invite compressed
+ * bytes to be concatenated into the body as text.
+ *
+ * A REFUSED 3xx RELEASES THE CONNECTION (council #230 C1). Each refusal branch
+ * settles the promise first and then retires the response and destroys the live
+ * request: the chain's single deadline is cleared the moment the promise
+ * settles, so a refused redirect whose body never ends would otherwise hold the
+ * socket open with nothing left to close it.
+ *
+ * The body is capped at `maxBytes` (council #230 B3): a response that keeps
+ * coming is destroyed and reported as `too-large` rather than accumulated in a
+ * string until the process dies.
+ */
+
+'use strict';
+
+const https = require('https');
+
+const DEFAULT_TIMEOUT_MS = 5000;
+/** 16 MiB. models.dev's api.json is ~4.5 MB, so this is headroom, not a budget. */
+const DEFAULT_MAX_BYTES = 16 * 1024 * 1024;
+/** Two hops, then `redirect limit reached`. */
+const MAX_REDIRECTS = 2;
+const REDIRECT_STATUS = new Set([301, 302, 303, 307, 308]);
+/**
+ * The ONLY headers a cross-origin hop keeps. Lower-case: callers spell headers
+ * freely. `accept-encoding` is deliberately NOT here (council #230 C3): this
+ * module never decodes a content-encoded body, so forwarding it would invite a
+ * compressed response to be concatenated into a string as text.
+ */
+const CROSS_ORIGIN_HEADERS = new Set(['user-agent', 'accept', 'accept-language']);
+
+/**
+ * The headers the NEXT hop may carry. A same-origin hop keeps the caller's
+ * object untouched; a cross-origin hop gets a copy holding ONLY the allowlisted
+ * names. A current URL that will not parse counts as cross-origin — the safe
+ * direction, since the comparison cannot be made.
+ * @param {object} headers the headers this hop was issued with
+ * @param {string} from the URL that produced the redirect
+ * @param {URL} to the resolved target
+ * @returns {object} `headers` itself, or an allowlisted copy
+ */
+function hopHeaders(headers, from, to) {
+  let fromOrigin = null;
+  try { fromOrigin = new URL(from).origin; } catch (err) { fromOrigin = null; }
+  if (fromOrigin !== null && fromOrigin === to.origin) { return headers; }
+  const kept = {};
+  for (const name of Object.keys(headers)) {
+    if (CROSS_ORIGIN_HEADERS.has(name.toLowerCase())) { kept[name] = headers[name]; }
+  }
+  return kept;
+}
+
+/**
+ * Retire a response the chain has finished with — either before the next hop starts, or on a
+ * refused redirect (`refuseRedirect`). Its `data`/`end`
+ * listeners and — the point of this — the chain's `error` listener are detached
+ * first, so an abrupt close on the abandoned socket can no longer settle a
+ * promise the live hop now owns. `error` is REPLACED by a swallow rather than
+ * simply removed: a destroyed stream still emits, and an 'error' with no
+ * listener at all throws as an uncaught exception.
+ * @param {object} res the http.IncomingMessage the chain has moved on from
+ */
+function retire(res) {
+  res.removeAllListeners('data');
+  res.removeAllListeners('end');
+  res.removeAllListeners('error');
+  res.on('error', () => {});
+  if (typeof res.destroy === 'function') { res.destroy(); }
+}
+
+/**
+ * A REFUSED 3xx: settle with the failure, then release the connection it came
+ * on. Draining alone was not enough (council #230 C1) — settling clears the
+ * chain's only deadline, so after the refusal nothing would ever close a socket
+ * whose body never ends. The failure is raised FIRST and the teardown second,
+ * because destroying the request can emit `error` on it and `ctx.onError` is
+ * still attached; single-settle then makes that late event a no-op instead of
+ * rewriting the reason as `network-error`.
+ * @param {object} res the http.IncomingMessage
+ * @param {{fail: Function, destroy: Function}} ctx
+ * @param {{reason: string, status: number, detail: string}} failure
+ */
+function refuseRedirect(res, ctx, failure) {
+  ctx.fail(failure);
+  retire(res);
+  ctx.destroy();
+}
+
+/**
+ * One hop's 3xx: resolve `Location` against the URL that produced it, retire
+ * this response, and hand the target plus its (possibly stripped) headers to
+ * `ctx.hop` — or fail with the status and a `detail` naming why the hop was
+ * refused. Every refusal goes through `refuseRedirect`, which releases the
+ * connection as well as failing.
+ * @param {object} res the http.IncomingMessage
+ * @param {{url: string, left: number, headers: object}} hop the hop it answered
+ * @param {{hop: Function, fail: Function, destroy: Function, retireRequest: Function}} ctx
+ */
+function followRedirect(res, hop, ctx) {
+  const status = res.statusCode;
+  const loc = (res.headers && res.headers.location) || null;
+  if (loc === null) { refuseRedirect(res, ctx, { reason: 'http-status', status, detail: 'redirect without Location' }); return; }
+  if (hop.left <= 0) { refuseRedirect(res, ctx, { reason: 'http-status', status, detail: 'redirect limit reached' }); return; }
+  let next;
+  try {
+    next = new URL(loc, hop.url);
+  } catch (err) {
+    refuseRedirect(res, ctx, { reason: 'http-status', status, detail: `redirect to an unparseable Location: ${err.message}` });
+    return;
+  }
+  // https ONLY: a downgrade would re-send the caller's headers in clear text.
+  if (next.protocol !== 'https:') { refuseRedirect(res, ctx, { reason: 'http-status', status, detail: 'redirect to non-https location' }); return; }
+  const headers = hopHeaders(hop.headers, hop.url, next);
+  retire(res);  // BEFORE the next hop exists, so the two can never race
+  ctx.retireRequest();  // and its REQUEST's 'error' listener with it
+  ctx.hop({ url: next.toString(), left: hop.left - 1, headers });
+}
+
+/**
+ * One hop's response: a 3xx goes to followRedirect WHEN the caller opted in,
+ * any other non-200 — an un-opted-in 3xx included — is an `http-status` failure
+ * once the body drains, a 200 accumulates under the byte cap.
+ * @param {object} res the http.IncomingMessage
+ * @param {{url: string, left: number, headers: object}} hop the hop it answered
+ * @param {{hop: Function, fail: Function, done: Function, onError: Function, destroy: Function,
+ *   retireRequest: Function, maxBytes: number, followRedirects: boolean}} ctx
+ */
+function readResponse(res, hop, ctx) {
+  // Decode once, at the stream: `chunks += chunk` decodes each Buffer on its
+  // own and mangles any multi-byte character split across a chunk boundary.
+  res.setEncoding('utf8');
+  // A mid-body stream error is emitted on `res`, NOT on `req`. With no listener
+  // here node rethrows it as an uncaught exception and the promise never
+  // settles — so it is attached once, ahead of the status check, and covers the
+  // redirect and non-200 drain branches too.
+  res.on('error', ctx.onError);
+  if (ctx.followRedirects && REDIRECT_STATUS.has(res.statusCode)) { followRedirect(res, hop, ctx); return; }
+  if (res.statusCode !== 200) {
+    // The deadline stays armed until `end`: a non-200 whose body never ends
+    // must still time out rather than leave the promise pending for ever.
+    res.on('data', () => {});
+    res.on('end', () => { ctx.fail({ reason: 'http-status', status: res.statusCode }); });
+    return;
+  }
+  let body = '';
+  let bytes = 0;
+  res.on('data', (chunk) => {
+    // Bytes, not `body.length`: the cap is named in bytes and the stream is
+    // already decoded, so a multi-byte body would otherwise pass an over-budget
+    // payload through under the character count.
+    bytes += Buffer.byteLength(chunk, 'utf8');
+    if (bytes > ctx.maxBytes) {
+      ctx.destroy();
+      ctx.fail({ reason: 'too-large', detail: `body exceeded ${ctx.maxBytes} bytes` });
+      return;
+    }
+    body += chunk;
+  });
+  res.on('end', () => { ctx.done({ ok: true, body }); });
+}
+
+/**
+ * GET `url`; resolve with the raw body on a 200. Caps the body at `maxBytes`.
+ * With `followRedirects: true` it follows at most two https redirects under a
+ * single deadline, keeping only the allowlisted headers on a cross-origin hop;
+ * without it a 3xx is a terminal `http-status` failure.
+ * @param {string} url
+ * @param {{headers?: object, timeoutMs?: number, maxBytes?: number, followRedirects?: boolean}} [opts]
+ * @returns {Promise<{ok: true, body: string}|{ok: false, failure: {reason: string, status?: number, detail?: string}}>}
+ */
+function httpGetText(url, opts = {}) {
+  const headers = opts.headers || {};
+  const timeoutMs = opts.timeoutMs === undefined ? DEFAULT_TIMEOUT_MS : opts.timeoutMs;
+  const maxBytes = opts.maxBytes === undefined ? DEFAULT_MAX_BYTES : opts.maxBytes;
+  const followRedirects = opts.followRedirects === true;
+  return new Promise((resolve) => {
+    // CHAIN-SCOPED. The deadline and the size trip must destroy the LIVE hop, so
+    // every hop assigns this from inside itself BEFORE dispatching its response.
+    // An outer `req = https.get(...)` cannot: https.get may call back
+    // synchronously, and the next hop's assignment would then be undone by the
+    // outer one completing afterwards.
+    let current = null;
+    let timer = null;
+    let settled = false;
+    // Single-settle: a timeout, a stream error, a size trip and an `end` can all
+    // race, and across a redirect chain the losing hops are still live.
+    const done = (v) => { if (settled) { return; } settled = true; clearTimeout(timer); resolve(v); };
+    const fail = (failure) => { done({ ok: false, failure }); };
+    const onError = (err) => { fail({ reason: 'network-error', detail: err.message }); };
+    const destroy = () => { if (current) { current.destroy(); } };
+    // A superseded hop's REQUEST keeps `onError` attached, so a late socket
+    // error on the abandoned connection would settle a chain the live hop now
+    // owns. Swapped for a swallow rather than merely removed: 'error' with no
+    // listener at all throws as an uncaught exception. Not destroyed — the
+    // response side already is, and destroying the request would fire this.
+    const retireRequest = () => {
+      if (!current) { return; }
+      current.removeAllListeners('error');
+      current.on('error', () => {});
+    };
+    // ONE deadline for the WHOLE chain — armed before the first hop, never rearmed.
+    timer = setTimeout(() => { destroy(); fail({ reason: 'timeout', detail: `no response within ${timeoutMs}ms` }); }, timeoutMs);
+    const ctx = { fail, done, onError, maxBytes, destroy, retireRequest, followRedirects, hop: null };
+    ctx.hop = (hop) => {
+      let res = null;
+      let armed = false;
+      let request;
+      try {
+        request = https.get(hop.url, { headers: hop.headers }, (r) => { res = r; if (armed) { readResponse(r, hop, ctx); } });
+      } catch (err) {
+        // `https.get` throws SYNCHRONOUSLY on a malformed URL (and on a bad
+        // option object). "Always resolves, never rejects" has to hold for that.
+        onError(err);
+        return;
+      }
+      current = request;
+      request.on('error', onError);
+      armed = true;
+      // A callback that already fired SYNCHRONOUSLY is replayed here, now that
+      // `current` is this hop's request rather than the previous one's.
+      if (res) { readResponse(res, hop, ctx); }
+    };
+    ctx.hop({ url, left: MAX_REDIRECTS, headers });
+  });
+}
+
+/**
+ * GET + JSON.parse. A body that is not JSON is a 'parse-error' failure, so a
+ * caller sees the transport reasons plus exactly this one more.
+ * @param {string} url
+ * @param {{headers?: object, timeoutMs?: number, maxBytes?: number, followRedirects?: boolean}} [opts]
+ * @returns {Promise<{ok: true, json: any}|{ok: false, failure: {reason: string, status?: number, detail?: string}}>}
+ */
+async function getJson(url, opts) {
+  const res = await httpGetText(url, opts);
+  if (!res.ok) { return res; }
+  try {
+    return { ok: true, json: JSON.parse(res.body) };
+  } catch (err) {
+    return { ok: false, failure: { reason: 'parse-error', detail: err.message } };
+  }
+}
+
+module.exports = { httpGetText, getJson, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_BYTES, MAX_REDIRECTS };

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
@@ -64,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
       }));
     }
@@ -148,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 } };
+  }
 }
 
 /**