amicus 4.9.3 → 4.9.5

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

@@ -17,11 +17,13 @@
  * 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 is ARITHMETICALLY INERT. kimi-k3's
- *      true ceiling is 943,718 and Math.min(943718, 32000) is still 32000. Only
- *      a value BELOW 32000 changes the outbound request. The issue's headline
- *      framing ("a 32,000 reservation against a 943,718 ceiling is arbitrary")
- *      reads as though feeding the real ceiling would help. It would not.
+ *   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
@@ -30,15 +32,21 @@
  *
  * 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 — that is what this module enables. Mode 2 (a leg spending its whole
- * allowance on reasoning and emitting 0-2 output tokens) would need it RAISED,
- * which the descriptor cannot do at all because of the Math.min; its real cause
- * is reasoning effort, a knob amicus already owns (`sidecar/fanout.js` →
- * `body.reasoning`). Lowering the budget makes those legs fail faster and
- * cheaper. It does not make them produce output. No claim is made that it does.
+ * 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 `{}` — byte-identical to pre-#218 behaviour.
+ * still registered as `{}` and no engine flag is set — byte-identical to
+ * pre-#218 behaviour.
  */
 
 'use strict';
@@ -121,4 +129,4 @@ function computeModelLimit(row, budget) {
   return { context, output: Math.max(1, Math.min(ceiling, want)) };
 }
 
-module.exports = { normalizeOutputBudget, buildLimitLookup, computeModelLimit };
+module.exports = { normalizeOutputBudget, buildLimitLookup, computeModelLimit, positiveCount };

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,