amicus 4.2.1 → 4.3.0

package/src/spend-query.js

@@ -0,0 +1,104 @@
+// src/spend-query.js
+'use strict';
+
+/**
+ * @module spend-query
+ * Pure query/rollup helpers for `amicus spend` (spec §7.3 filters/group-by,
+ * §6.3/resolved Q6 `wasted`). Split out of src/cli-handlers-spend.js (which
+ * re-exports these) to stay under the 300-line size gate — see that file's
+ * module docblock. No I/O, no CLI concerns: everything here is rows-in,
+ * rows/rollup-out and independently testable.
+ */
+
+/**
+ * Valid `--group-by`/`groupBy` dimensions — the SINGLE source of truth shared
+ * by the CLI's validity check (cli-handlers-spend.js), the MCP `amicus_spend`
+ * tool's `groupBy` Zod enum (mcp-tools.js), and rowKey()'s switch below. Do
+ * NOT hand-copy this array elsewhere: a 7th dimension added here must reach
+ * both surfaces automatically, not just the one someone remembered to edit.
+ */
+const GROUP_DIMS = ['model', 'wave', 'council', 'project', 'op', 'day'];
+
+/** Cap on rows returned when a caller opts into raw rows (CLI --rows / MCP rows:true). */
+const ROWS_CAP = 1000;
+
+function emptyTokens() {
+  return { input: 0, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0 };
+}
+
+function addTokens(into, tokens) {
+  if (!tokens) { return; }
+  for (const k of Object.keys(into)) { into[k] += tokens[k] || 0; }
+}
+
+/** Pure row filter over the additive attribution fields (spec 7.3). */
+function filterRows(rows, f = {}) {
+  const cutoff = (f.since !== undefined && f.since !== null && f.now !== undefined) ? f.now - f.since * 86400000 : null;
+  return rows.filter((r) => {
+    if (f.wave && r.waveId !== f.wave) { return false; }
+    if (f.council && r.councilRunId !== f.council && r.councilName !== f.council) { return false; }
+    if (f.project && r.project !== f.project) { return false; }
+    if (f.model && !String(r.model || '').startsWith(f.model)) { return false; }
+    if (f.op && r.op !== f.op) { return false; }
+    if (f.failed && (r.status === 'complete' || !r.status)) { return false; }
+    if (cutoff !== null) { const t = Date.parse(r.ts); if (!Number.isFinite(t) || t < cutoff) { return false; } }
+    return true;
+  });
+}
+
+/** dimension -> row key. null/absent -> '(unattributed)'. `day` = the ISO date. */
+function rowKey(row, dimension) {
+  switch (dimension) {
+    case 'model': return row.model || '(unattributed)';
+    case 'wave': return row.waveId || '(unattributed)';
+    case 'council': return row.councilRunId || row.councilName || '(unattributed)';
+    case 'project': return row.project || '(unattributed)';
+    case 'op': return row.op || '(unattributed)';
+    case 'day': return typeof row.ts === 'string' ? row.ts.slice(0, 10) : '(unattributed)';
+    default: return '(unattributed)';
+  }
+}
+
+/** Group rows into {key, amount, tokens, runs, sourceMix}, most-expensive first. */
+function groupRows(rows, dimension) {
+  const map = new Map();
+  for (const r of rows) {
+    const key = rowKey(r, dimension);
+    if (!map.has(key)) { map.set(key, { key, amount: 0, tokens: emptyTokens(), runs: 0, sourceMix: { reported: 0, estimated: 0, unknown: 0 } }); }
+    const b = map.get(key);
+    b.runs += 1;
+    addTokens(b.tokens, r.tokens);
+    const cost = r.cost || {};
+    if (typeof cost.amount === 'number') { b.amount += cost.amount; }
+    const src = (cost.source === 'reported' || cost.source === 'estimated') ? cost.source : 'unknown';
+    b.sourceMix[src] += 1;
+  }
+  return [...map.values()].sort((a, b) => b.amount - a.amount);
+}
+
+/**
+ * Wasted spend = every row with an EXPLICIT non-complete status, bucketed by
+ * status (spec 6.3, resolved Q6). A row with status null/absent (pre-v4.3,
+ * or any row that never reached a terminal status write) is deliberately
+ * EXCLUDED here — not "complete" and not "wasted" — because we cannot know
+ * whether that historical run actually failed; counting it would fabricate
+ * a failure that was never recorded. Contrast with groupRows(), where a null
+ * dimension is a first-class '(unattributed)' bucket (grouping never drops
+ * a row); computeWasted intentionally drops it instead.
+ */
+function computeWasted(rows) {
+  const out = { amount: 0, tokens: emptyTokens(), runs: 0, byStatus: {} };
+  for (const r of rows) {
+    if (r.status === 'complete' || !r.status) { continue; }
+    out.runs += 1;
+    addTokens(out.tokens, r.tokens);
+    const amt = (r.cost && typeof r.cost.amount === 'number') ? r.cost.amount : 0;
+    out.amount += amt;
+    if (!out.byStatus[r.status]) { out.byStatus[r.status] = { amount: 0, runs: 0 }; }
+    out.byStatus[r.status].amount += amt;
+    out.byStatus[r.status].runs += 1;
+  }
+  return out;
+}
+
+module.exports = { filterRows, groupRows, computeWasted, emptyTokens, addTokens, GROUP_DIMS, ROWS_CAP };

package/src/utils/error-classify.js

@@ -0,0 +1,31 @@
+'use strict';
+
+/**
+ * @module error-classify
+ * Conservative classification of an OpenCode leg-error string into a trigger
+ * class (spec 6.2). Fallback substitution fires ONLY on capacity signals
+ * (rate-limit|overload). timeout is excluded (resolved Q3: a slow model on a
+ * heavy task is not a capacity signal — --retry-failed covers it); auth /
+ * validation never substitute. Misclassification cost is bounded either way:
+ * one extra cheaper attempt, or status quo.
+ */
+
+const RATE_LIMIT = /429|rate ?limit|too many requests|quota|resource exhausted/i;
+const OVERLOAD = /529|503|overload|capacity|server busy|service unavailable/i;
+const AUTH = /401|403|unauthorized|forbidden|invalid api key|authentication/i;
+const TIMEOUT = /timed? ?out|timeout|deadline exceeded/i;
+
+/** @param {string} message @returns {'rate-limit'|'overload'|'auth'|'timeout'|'other'} */
+function classifyLegError(message) {
+  const m = String(message || '');
+  if (RATE_LIMIT.test(m)) { return 'rate-limit'; }
+  if (OVERLOAD.test(m)) { return 'overload'; }
+  if (AUTH.test(m)) { return 'auth'; }
+  if (TIMEOUT.test(m)) { return 'timeout'; }
+  return 'other';
+}
+
+/** Only capacity signals trigger a cheaper-model substitution. */
+function isRetryable(cls) { return cls === 'rate-limit' || cls === 'overload'; }
+
+module.exports = { classifyLegError, isRetryable };

package/src/utils/model-tiers.js

@@ -117,4 +117,4 @@ function resolveTier(vendor, tier, catalog) {
   return null;
 }
 
-module.exports = { TIERS, resolveTier };
+module.exports = { TIERS, TIER_ORDER, resolveTier };

package/src/utils/spend-ledger.js

@@ -46,9 +46,20 @@ const SPEND_LEDGER_FILE = 'spend-ledger.jsonl';
  * @param {string} opts.model resolved model id (or alias, if that's all the caller has)
  * @param {'headless'|'interactive'|'leg'} opts.mode
  * @param {{tokens:object, cost:{amount:number|null,currency:string,source:string}}|null} opts.usage
+ * @param {string} [opts.op] 'leg' | 'start' | 'continue' | 'resume'
+ * @param {string} [opts.status] terminal status
+ * @param {string} [opts.councilRunId] council run id (additive attribution)
+ * @param {string} [opts.councilName] council name (additive attribution)
+ * @param {string} [opts.project] project directory (additive attribution)
+ * @param {string} [opts.gateway] resolved gateway ('direct'|'openrouter'|'local', additive attribution)
+ * @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 {{dir?:string}} [ctx] test seam — dir overrides getConfigDir()
  */
-function appendSpend({ taskId, waveId, model, mode, usage }, ctx = {}) {
+function appendSpend({ taskId, waveId, model, mode, usage,
+  op, status, councilRunId, councilName, project, gateway,
+  attempt, substitutedFor, retryOfWaveId }, ctx = {}) {
   if (!usage) { return; }
   try {
     const dir = ctx.dir || getConfigDir();
@@ -62,7 +73,19 @@ function appendSpend({ taskId, waveId, model, mode, usage }, ctx = {}) {
       mode: mode || null,
       tokens: usage.tokens || null,
       cost: usage.cost || null,
+      // v4.3 additive attribution (spec 7.1). Nullable dimensions default to
+      // null (so a row is always groupable); linkage fields are OMITTED unless
+      // present (they only exist on fallback/retry rows).
+      op: op || null,
+      status: status || null,
+      councilRunId: councilRunId || null,
+      councilName: councilName || null,
+      project: project || null,
+      gateway: gateway || null,
     };
+    if (attempt !== undefined) { row.attempt = attempt; }
+    if (substitutedFor !== undefined) { row.substitutedFor = substitutedFor; }
+    if (retryOfWaveId !== undefined) { row.retryOfWaveId = retryOfWaveId; }
     fs.appendFileSync(path.join(dir, SPEND_LEDGER_FILE), JSON.stringify(row) + '\n');
   } catch (e) {
     logger.debug('spend-ledger append failed (best-effort, run unaffected)', { taskId, error: e.message });