amicus 4.9.2 → 4.9.4

package/src/utils/openrouter-credit.js

@@ -0,0 +1,104 @@
+/**
+ * @module openrouter-credit
+ * The OpenRouter credit/limit probe, split out of api-key-validation.js to keep
+ * that module under the 300-line size gate — the same reason it was itself
+ * split out of api-key-store.js. Different concern, too: this asks what the
+ * ACCOUNT can afford, not whether the credential is accepted.
+ *
+ * Re-exported from api-key-validation.js so every existing call site keeps
+ * working unchanged.
+ */
+
+'use strict';
+
+const https = require('https');
+
+/** Warning string for a zero-credit OpenRouter key (paid models will 402). */
+const OPENROUTER_NO_CREDIT_WARNING =
+  'OpenRouter key has no remaining credit — paid models will fail (402). ' +
+  'Add credit at openrouter.ai/credits, or build a free council (amicus setup → option 2).';
+
+/** Warning string for a free-tier OpenRouter key. */
+const OPENROUTER_FREE_TIER_WARNING =
+  'OpenRouter key is free tier — only :free models will route; paid models will fail (402). ' +
+  'Add credit at openrouter.ai/credits to use paid models.';
+
+/**
+ * Non-blocking credit/limit check for an OpenRouter key.
+ *
+ * Hits GET https://openrouter.ai/api/v1/key (returns limit, usage,
+ * is_free_tier, limit_remaining) and produces a WARNING — never an error —
+ * when is_free_tier is true or limit_remaining <= 0. Any failure (non-200,
+ * network error, malformed body) resolves with warning:null so setup is
+ * never blocked. Free-tier councils against free models are legitimate.
+ *
+ * @param {string} key OpenRouter API key
+ * @returns {Promise<{checked: boolean, warning: string|null, isFreeTier: boolean,
+ *   limitRemaining: number|null, limit: number|null, usage: number|null}>}
+ *   `checked` is false whenever no answer was obtained. Never infer health
+ *   from `warning: null` alone — see the note on `none` below.
+ */
+function checkOpenRouterCredit(key) {
+  // ⚠️ `checked: false` is the whole point. Every failure path below resolves
+  // THIS object, and `warning: null` is also what a perfectly healthy account
+  // resolves — so a caller branching on `warning` alone cannot tell "the
+  // account is fine" from "the probe never got an answer", and renders the
+  // first for the second. That is the false green the fourth council pass
+  // found still alive on the network-failure path after it had been fixed only
+  // for the gate-disabled one. Intent-to-probe and result-of-probe are
+  // different facts and now have different fields.
+  const none = {
+    checked: false,
+    warning: null, isFreeTier: false, limitRemaining: null, limit: null, usage: null
+  };
+  if (!key || key.trim().length === 0) {
+    return Promise.resolve(none);
+  }
+
+  const headers = { 'Authorization': `Bearer ${key.trim()}` };
+
+  return new Promise((resolve) => {
+    const req = https.get('https://openrouter.ai/api/v1/key', { headers }, (res) => {
+      let body = '';
+      // Same response-stream gap as validateApiKey (#224). `none` carries
+      // checked:false, so a mid-flight death reports "could not be checked"
+      // rather than falling through to "credit ok".
+      res.on('error', () => { resolve(none); });
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => {
+        if (res.statusCode !== 200) { resolve(none); return; }
+        let data;
+        try {
+          data = (JSON.parse(body) || {}).data || {};
+        } catch (_e) {
+          resolve(none);
+          return;
+        }
+        const isFreeTier = data.is_free_tier === true;
+        const limitRemaining = (typeof data.limit_remaining === 'number')
+          ? data.limit_remaining : null;
+        const limit = (typeof data.limit === 'number') ? data.limit : null;
+        const usage = (typeof data.usage === 'number') ? data.usage : null;
+
+        let warning = null;
+        if (limitRemaining !== null && limitRemaining <= 0) {
+          warning = OPENROUTER_NO_CREDIT_WARNING;
+        } else if (isFreeTier) {
+          warning = OPENROUTER_FREE_TIER_WARNING;
+        }
+        resolve({ checked: true, warning, isFreeTier, limitRemaining, limit, usage });
+      });
+    });
+    req.setTimeout(10000, () => {
+      req.destroy();
+      resolve(none);
+    });
+    req.on('error', () => { resolve(none); });
+  });
+}
+
+module.exports = {
+  checkOpenRouterCredit,
+  OPENROUTER_NO_CREDIT_WARNING,
+  OPENROUTER_FREE_TIER_WARNING,
+};

package/src/utils/output-length.js

@@ -0,0 +1,90 @@
+/**
+ * @module utils/output-length
+ * #218 PR 3: name the "Mode 2" death.
+ *
+ * THE PROBLEM. A council leg whose provider stopped for length before any
+ * answer text -- the whole max_tokens reservation went to reasoning (the #218
+ * ledger rows: 32000 reasoning, 0-2 output, $0.63 billed for nothing) -- came
+ * back `complete` with an empty summary and was announced as "the leg ended
+ * 'complete' with no usable output"; with VISIBLE reasoning it came back
+ * `complete` with its thinking promoted to the review and was adjudicated as one.
+ *
+ * WHAT THE ENGINE RECORDS (scripts/probe-max-tokens.js rows A/H1/L1-L4, engine
+ * 1.18.15): `finish: 'length'` on the assistant message on both provider
+ * families; a reasoning/output token split on OpenAI-compatible routes
+ * (L3: output = completion - reasoning) but NOT on the direct Anthropic route
+ * (L4: everything is `output`, reasoning 0); and, with visible reasoning, a
+ * `reasoning` part and no `text` part (L2/L4), which
+ * sidecar/conversation-mirror.js :: mirrorMessages promotes to `output` -- so
+ * `output` cannot be the test; the mirror records the last message's own facts
+ * and this module reads only those. No row carries an engine error for the stop.
+ *
+ * So the death is keyed on `finish` plus "no answer text arrived", never on a
+ * token count; the counts are reported, not decided on. Pure: no I/O, no clock.
+ * headless.js :: runHeadless calls both functions once, post-loop.
+ */
+'use strict';
+
+const {
+  outputTokenFlagValue, ENGINE_DEFAULT_OUTPUT_TOKENS, OUTPUT_TOKEN_FLAG, PLAIN_OUTPUT_TOKEN_FLAG,
+} = require('./engine-output-flag');
+
+/** The prefix a consumer can classify on, like `NO_OUTPUT_BACKSTOP:`. */
+const OUTPUT_LENGTH_PREFIX = 'OUTPUT_LENGTH:';
+
+/**
+ * Is this leg the Mode 2 death? The provider stopped for length AND the LAST
+ * assistant message carries no answer text: nothing at all (L1), or only
+ * reasoning (L2/L4). Decided per message, never on the session's accumulated
+ * output (council #232 r1 B2/D1). Named mutants (tests/utils/output-length.test.js):
+ * "NOTLENGTH" drops the finish check, "TEXTIGNORED" drops the text check.
+ * @param {{finish?: string|null, hasText?: boolean}} last the last assistant message's facts
+ * @returns {boolean}
+ */
+function isOutputLengthDeath({ finish, hasText }) {
+  return finish === 'length' && hasText !== true;
+}
+
+/**
+ * The reason string. Every clause is an observation: `finish` and the two
+ * counts are the engine's own record of the message; the budget clause is what
+ * the engine serving the leg was spawned with: the budget (`null` = unset,
+ * `undefined` = unknown — no handle value and config unreadable) or, when no
+ * budget was set, the ambient flag. The remedy names the one
+ * lever that exists today; PR 4 adds the effort lever. Named mutant
+ * "BUDGETUNSET": always print the unset clause.
+ * @param {{tokens?: {reasoning?: number, output?: number}|null,
+ *   budget?: number|null, reasoningOnly?: boolean,
+ *   ambientFlag?: string|null}} args `reasoningOnly` = the
+ *   message carried reasoning parts and no text -- L2/L4; `ambientFlag` = the
+ *   ambient `OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX` the engine was started with
+ *   when no budget was set (`null` when none, or when a budget overrode it);
+ *   named mutant "AMBIENTIGNORED".
+ * @returns {string}
+ */
+function formatOutputLengthReason({ tokens, budget, reasoningOnly, ambientFlag }) {
+  const t = tokens || {};
+  const count = (n) => (Number.isFinite(n) ? n : 0);
+  const streamed = reasoningOnly
+    ? 'only reasoning was streamed, no answer text'
+    : 'no answer text arrived';
+  // PLAIN_OUTPUT_TOKEN_FLAG is the one form measured to be honoured (C1, K5,
+  // K12); 64000abc and 0 fell back to 32000 (D1/D2); every other form is
+  // unmeasured, and the clause below says so -- shared with the doctor row
+  // (doctor-output-budget-check.js :: evaluateOutputBudget) so the gates agree.
+  const ambient = typeof ambientFlag === 'string' ? ambientFlag : null;
+  const knob = budget === undefined
+    ? 'outputBudget could not be read'
+    : budget !== null
+      ? `outputBudget is ${outputTokenFlagValue(budget)}`
+      : ambient === null
+        ? `outputBudget is unset — the engine's ${ENGINE_DEFAULT_OUTPUT_TOKENS} default reservation governs`
+        : PLAIN_OUTPUT_TOKEN_FLAG.test(ambient)
+          ? `outputBudget is unset — the ambient ${OUTPUT_TOKEN_FLAG}=${ambient} the engine was started with governs (each leg reserves min(${ambient}, the ceiling the engine's catalog knows for it))`
+          : `outputBudget is unset and the ambient ${OUTPUT_TOKEN_FLAG}=${ambient} the engine was started with is not a plain positive integer — the only form measured to be honoured (probe D1/D2: 64000abc and 0 fell back to ${ENGINE_DEFAULT_OUTPUT_TOKENS} silently); any other form is unmeasured`;
+  return `${OUTPUT_LENGTH_PREFIX} the provider stopped at the max_tokens reservation (finish 'length') and ${streamed} — `
+    + `${count(t.reasoning)} reasoning / ${count(t.output)} output tokens; ${knob} — `
+    + 'raise outputBudget in config.json (docs/configuration.md, Output budget)';
+}
+
+module.exports = { OUTPUT_LENGTH_PREFIX, isOutputLengthDeath, formatOutputLengthReason };

package/src/utils/result-schema.js

@@ -50,6 +50,7 @@ function durationBetween(createdAt, completedAt) {
  *   metadata.pack was recorded (solo session launched via --pack), sourced straight off
  *   `metadata` like `usage`/`opencodeSessionId` already are (no new function parameter needed).
  *   `tag` (v4.7 F8/D13) is additive the same way — present only when metadata.tag was recorded.
+ *   `finish` (#218 PR 3) likewise — the engine's finish reason for the leg's last assistant message. `variant` / `variantUnverified` (#218 PR 4) likewise — the effort level SENT, and whether the engine's catalogue knew the model when it was sent.
  */
 function buildRunResult({ taskId, metadata = {}, result = null, summary = null, modelInput = null, sessionDir = null, waveId = null, usage = null }) {
   const status = result ? statusFromResult(result) : (metadata.status || 'unknown');
@@ -80,6 +81,8 @@ function buildRunResult({ taskId, metadata = {}, result = null, summary = null,
     // (B3): emit-when-VALID via the shared predicate — `metadata` is read off
     // disk, so NaN/±Infinity/negatives/fractions all reach here. See ./ttft.js.
     ...(isMeasuredTtft(metadata.ttftMs) ? { ttftMs: metadata.ttftMs } : {}),
+    ...(typeof metadata.finish === 'string' ? { finish: metadata.finish } : {}), // #218 PR 3: emit-when-set (named mutant FINISHCOERCED)
+    ...(typeof metadata.variant === 'string' ? { variant: metadata.variant } : {}), ...(metadata.variantUnverified === true ? { variantUnverified: true } : {}), // #218 PR 4: emit-when-sent (named mutants VARIANTCOERCED / UNVERIFIEDCOERCED)
     usage: usage !== null ? usage : (metadata.usage || null),
     ...(metadata.pack ? { pack: metadata.pack } : {}),
     ...(metadata.tag ? { tag: metadata.tag } : {}),
@@ -184,10 +187,11 @@ const { buildRunResultFromSession, buildWaveResultFromSession } = require('./res
  * #13: lastRefreshAttempt/lastRefreshError are additive — null/null when the
  * last refresh attempt on record succeeded (or none has happened yet).
  * @param {{models: Array, fetchedAt: number|null, refreshed?: boolean, search?: string|null,
- *   lastRefreshAttempt?: number|null, lastRefreshError?: string|null}} opts
+ *   lastRefreshAttempt?: number|null, lastRefreshError?: string|null,
+ *   ceilingEnrichment?: object|null}} opts
  */
 function buildCatalogDoc({ models, fetchedAt, refreshed = false, search = null,
-  lastRefreshAttempt = null, lastRefreshError = null }) {
+  lastRefreshAttempt = null, lastRefreshError = null, ceilingEnrichment = null }) {
   return {
     schemaVersion: SCHEMA_VERSION,
     type: 'model-catalog',
@@ -198,6 +202,7 @@ function buildCatalogDoc({ models, fetchedAt, refreshed = false, search = null,
     models,
     lastRefreshAttempt: lastRefreshAttempt || null,
     lastRefreshError: lastRefreshError || null,
+    ceilingEnrichment: ceilingEnrichment || null, // #218 P3: additive within SCHEMA_VERSION
   };
 }
 

package/src/utils/spend-ledger.js

@@ -62,11 +62,13 @@ const SPEND_LEDGER_FILE = 'spend-ledger.jsonl';
  * @param {number} [opts.attempt] fallback attempt count (omitted if absent)
  * @param {string} [opts.substitutedFor] substituted model (omitted if absent)
  * @param {string} [opts.retryOfWaveId] wave id being retried (omitted if absent)
+ * @param {string} [opts.finish] the leg's finish reason (omitted if absent) — #218 PR 3: 'length' on a row is the Mode 2 receipt
+ * @param {string} [opts.variant] the effort level sent (omitted if absent) — #218 PR 4
  * @param {{dir?:string}} [ctx] test seam — dir overrides getConfigDir()
  */
 function appendSpend({ taskId, waveId, model, mode, usage,
   op, status, councilRunId, councilName, project, gateway, tag,
-  attempt, substitutedFor, retryOfWaveId }, ctx = {}) {
+  attempt, substitutedFor, retryOfWaveId, finish, variant }, ctx = {}) {
   if (!usage) { return; }
   try {
     const dir = ctx.dir || getConfigDir();
@@ -96,6 +98,8 @@ function appendSpend({ taskId, waveId, model, mode, usage,
     if (attempt !== undefined) { row.attempt = attempt; }
     if (substitutedFor !== undefined) { row.substitutedFor = substitutedFor; }
     if (retryOfWaveId !== undefined) { row.retryOfWaveId = retryOfWaveId; }
+    if (typeof finish === 'string') { row.finish = finish; }
+    if (typeof variant === 'string') { row.variant = variant; } // #218 PR 4: emit-when-sent (named mutant "VARIANTNULLED")
     // v4.4.1 CA-2: a leg whose OWN cost is known but which spawned a child
     // session the walk could not price writes a PRICED row — so `unpricedRows`
     // never catches it and `amicus spend` reads as a complete measurement while

package/src/utils/thinking-validators.js

@@ -1,92 +1,39 @@
 /**
  * Thinking Level Validators
  *
- * Model-specific thinking level validation.
- * Extracted from validators.js to keep modules under 300 lines.
+ * #218 PR 4: the CLI's `--thinking` check is a VOCABULARY check only — the seven
+ * levels the curated routes declare between them (engine-variants.js ::
+ * VARIANT_LEVELS, measured on the engine's /config/providers dump, probe M0).
+ * Whether a given MODEL declares the level is the engine's call, read from that
+ * same dump at send time (opencode-client.js :: sendPrompt), where a level the
+ * model does not declare is refused before anything is sent. The per-model table
+ * this file carried until PR 4 (gpt-5 "without minimal", gemini "with everything")
+ * was a static guess the dump CONFIRMS on one row and contradicts on the other
+ * (M0: both exclude `minimal` for gpt-5 — gpt-5.6-terra declares none, low, medium,
+ * high, xhigh, max — while the table gave gemini `none` and `xhigh` and
+ * gemini-3.6-flash declares neither, only minimal, low, medium, high), and its "use
+ * medium instead" adjustment sent a level the user never asked for. Both are gone;
+ * nothing is adjusted here — guessing right on one row does not make a guess a
+ * declaration (council #235 r1 wave 2: this docblock had cited the CONFIRMING row
+ * as the contradiction, the same inversion the CHANGELOG carried).
  */
 
-/**
- * Model-specific thinking level support (static fallback)
- * Maps model patterns to their supported thinking levels.
- *
- * NOTE: For dynamic, up-to-date capabilities, use model-capabilities.js
- * which fetches from OpenRouter API and caches the results.
- * This static map is used as a fast fallback for CLI validation.
- */
-const MODEL_THINKING_SUPPORT = {
-  // OpenAI GPT-5.x does NOT support 'minimal'
-  'gpt-5': ['none', 'low', 'medium', 'high', 'xhigh'],
-  // o3/o3-mini supports all levels
-  'o3': ['none', 'minimal', 'low', 'medium', 'high', 'xhigh'],
-  // Gemini supports all levels
-  'gemini': ['none', 'minimal', 'low', 'medium', 'high', 'xhigh'],
-  // Default: all levels supported
-  'default': ['none', 'minimal', 'low', 'medium', 'high', 'xhigh']
-};
-
-/**
- * Get supported thinking levels for a model (synchronous, static fallback)
- *
- * For dynamic lookup from OpenRouter API cache, use:
- *   const { getSupportedThinkingLevels } = require('./model-capabilities');
- *
- * @param {string} model - Model identifier
- * @returns {string[]} Array of supported thinking levels
- */
-function getSupportedThinkingLevels(model) {
-  if (!model) {return MODEL_THINKING_SUPPORT.default;}
-
-  const modelLower = model.toLowerCase();
-
-  // Check each known model pattern
-  for (const [pattern, levels] of Object.entries(MODEL_THINKING_SUPPORT)) {
-    if (pattern !== 'default' && modelLower.includes(pattern)) {
-      return levels;
-    }
-  }
-
-  return MODEL_THINKING_SUPPORT.default;
-}
+const { VARIANT_LEVELS } = require('./engine-variants');
 
 /**
- * Validate thinking level for a specific model (synchronous)
- *
- * For async validation with dynamic API cache, use:
- *   const { validateThinkingForModel } = require('./model-capabilities');
- *
- * @param {string} thinking - Thinking level ('minimal', 'low', 'medium', 'high', 'xhigh', 'none')
- * @param {string} model - Model identifier
- * @returns {{valid: boolean, error?: string, warning?: string, adjustedLevel?: string}}
+ * @param {string} [thinking] the requested level; omitted (undefined/null) is valid (nothing is sent then)
+ * @returns {{valid: boolean, error?: string}}
  */
-function validateThinkingLevel(thinking, model) {
-  if (!thinking) {
-    return { valid: true };
+function validateThinkingLevel(thinking) {
+  // council #235 r2 (A2): presence, not truthiness. `--thinking=` parses to '' (cli.js's
+  // inline-value branch) and a truthiness test accepted it as "flag omitted", so the level
+  // was silently dropped. An omitted flag is undefined/null; anything else the user typed
+  // must face the vocabulary check. Named mutant "FALSYLEVELACCEPTED": restore `if (!thinking)`.
+  if (thinking === undefined || thinking === null) { return { valid: true }; }
+  if (!VARIANT_LEVELS.includes(thinking)) {
+    return { valid: false, error: `Error: --thinking must be one of: ${VARIANT_LEVELS.join(', ')}` };
   }
-
-  const allLevels = MODEL_THINKING_SUPPORT.default;
-  if (!allLevels.includes(thinking)) {
-    return {
-      valid: false,
-      error: `Error: --thinking must be one of: ${allLevels.join(', ')}`
-    };
-  }
-
-  const supportedLevels = getSupportedThinkingLevels(model);
-  if (!supportedLevels.includes(thinking)) {
-    // Map to nearest supported level
-    const fallback = thinking === 'minimal' ? 'low' : 'medium';
-    return {
-      valid: true,
-      warning: `Warning: Model '${model}' does not support thinking level '${thinking}'. Using '${fallback}' instead.`,
-      adjustedLevel: fallback
-    };
-  }
-
   return { valid: true };
 }
 
-module.exports = {
-  MODEL_THINKING_SUPPORT,
-  getSupportedThinkingLevels,
-  validateThinkingLevel
-};
+module.exports = { VARIANT_LEVELS, validateThinkingLevel };

package/src/utils/validators.js

@@ -214,7 +214,7 @@ function validateHeadlessAgent(agent) {
 }
 
 const { validateMcpSpec, validateMcpConfigFile } = require('./mcp-validators');
-const { MODEL_THINKING_SUPPORT, getSupportedThinkingLevels, validateThinkingLevel } = require('./thinking-validators');
+const { VARIANT_LEVELS, validateThinkingLevel } = require('./thinking-validators');
 
 /**
  * Validate API key is present for the given model's provider.
@@ -260,7 +260,7 @@ function validateApiKey(model) {
 module.exports = {
   VALID_AGENT_MODES,
   PROVIDER_KEY_MAP,
-  MODEL_THINKING_SUPPORT,
+  VARIANT_LEVELS,
   TASK_ID_PATTERN,
   validateTaskId,
   TAG_PATTERN,
@@ -278,7 +278,6 @@ module.exports = {
   validateMcpConfigFile,
   validateApiKey,
   validateThinkingLevel,
-  getSupportedThinkingLevels,
   findSessionInProjectDirs,
   // Re-exported from input-validators.js
   validateStartInputs: require('./input-validators').validateStartInputs,