amicus 1.0.0 → 1.2.0

package/src/utils/pricing.js

@@ -0,0 +1,93 @@
+// src/utils/pricing.js
+'use strict';
+
+/**
+ * @module pricing
+ * Token aggregation + cached-pricing lookup + layered cost resolution (WS-2 #2).
+ * Cost is resolved in layers and ALWAYS tagged with its source so it can never
+ * be mistaken for an authoritative figure it isn't:
+ *   reported  — OpenCode billed cost (msg.info.cost > 0)
+ *   estimated — tokens × cached catalog pricing
+ *   unknown   — neither available (e.g. a direct provider with pricing:null)
+ */
+
+function emptyUsageTotals() {
+  return { tokens: { input: 0, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0 }, costReported: 0 };
+}
+
+/**
+ * Sum per-message usage. The poll loop re-reads ALL messages each poll, so the
+ * caller stores the latest snapshot per message id in a Map; summing the Map's
+ * values avoids double-counting streamed growth.
+ * @param {Map<string,{tokens?:object, cost?:number}>} map
+ */
+function sumPerMessageUsage(map) {
+  const totals = emptyUsageTotals();
+  for (const v of map.values()) {
+    const t = v && v.tokens ? v.tokens : {};
+    totals.tokens.input += t.input || 0;
+    totals.tokens.output += t.output || 0;
+    totals.tokens.reasoning += t.reasoning || 0;
+    totals.tokens.cacheRead += (t.cache && t.cache.read) || 0;
+    totals.tokens.cacheWrite += (t.cache && t.cache.write) || 0;
+    if (typeof v.cost === 'number') { totals.costReported += v.cost; }
+  }
+  return totals;
+}
+
+/** Sync, non-refreshing cached-pricing lookup by full route id. @returns {{prompt,completion}|null} */
+function lookupPricing(modelId) {
+  if (!modelId) { return null; }
+  let cache;
+  try { cache = require('./model-catalog').readCache(); } catch { return null; }
+  if (!cache || !Array.isArray(cache.models)) { return null; }
+  const row = cache.models.find(m => m && m.id === modelId);
+  if (!row || !row.pricing) { return null; }
+  const prompt = Number(row.pricing.prompt);
+  const completion = Number(row.pricing.completion);
+  if (!Number.isFinite(prompt) || !Number.isFinite(completion) || prompt < 0 || completion < 0) { return null; }
+  return { prompt, completion };
+}
+
+/** @returns {{amount:number|null, currency:'USD', source:'reported'|'estimated'|'unknown'}} */
+function resolveLegCost({ reportedCost, tokens, pricing }) {
+  if (typeof reportedCost === 'number' && reportedCost > 0) {
+    return { amount: reportedCost, currency: 'USD', source: 'reported' };
+  }
+  if (pricing && tokens) {
+    const est = (tokens.input || 0) * pricing.prompt + (tokens.output || 0) * pricing.completion;
+    if (est > 0) { return { amount: est, currency: 'USD', source: 'estimated' }; }
+  }
+  return { amount: null, currency: 'USD', source: 'unknown' };
+}
+
+/** Resolve a single run/leg's final usage block from raw totals + the model id. */
+function resolveUsage({ model, usageTotals }) {
+  const totals = usageTotals || emptyUsageTotals();
+  const cost = resolveLegCost({ reportedCost: totals.costReported, tokens: totals.tokens, pricing: lookupPricing(model) });
+  return { tokens: totals.tokens, cost };
+}
+
+/** Aggregate leg usage into a wave-level usage block. Legs without usage count as unpriced. */
+function sumWaveUsage(legs) {
+  const tokens = { input: 0, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0 };
+  let amount = 0; let anyAmount = false;
+  let reportedLegs = 0, estimatedLegs = 0, unpricedLegs = 0;
+  for (const leg of legs) {
+    const u = leg && leg.usage;
+    if (!u || !u.cost) { unpricedLegs++; continue; }
+    for (const k of Object.keys(tokens)) { tokens[k] += (u.tokens && u.tokens[k]) || 0; }
+    if (typeof u.cost.amount === 'number') { amount += u.cost.amount; anyAmount = true; }
+    if (u.cost.source === 'reported') { reportedLegs++; }
+    else if (u.cost.source === 'estimated') { estimatedLegs++; }
+    else { unpricedLegs++; }
+  }
+  let source;
+  if (reportedLegs > 0 && estimatedLegs === 0 && unpricedLegs === 0) { source = 'reported'; }
+  else if (estimatedLegs > 0 && reportedLegs === 0 && unpricedLegs === 0) { source = 'estimated'; }
+  else if (reportedLegs === 0 && estimatedLegs === 0) { source = 'unknown'; }
+  else { source = 'mixed'; }
+  return { tokens, cost: { amount: anyAmount ? amount : null, currency: 'USD', source, reportedLegs, estimatedLegs, unpricedLegs } };
+}
+
+module.exports = { emptyUsageTotals, sumPerMessageUsage, lookupPricing, resolveLegCost, resolveUsage, sumWaveUsage };

package/src/utils/quick-picks.js

@@ -0,0 +1,81 @@
+/**
+ * Quick-pick resolution (wizard Step 2) — resolves each curated family to
+ * the current catalog flagship. Setup-time only; runtime alias resolution
+ * stays on the static DEFAULT_ALIASES (see curated-models.js).
+ *
+ * Ranking: numeric-descending over ids; a marker-suffixed variant
+ * (-preview/-exp/-beta/-latest/:free) loses ONLY to its own unmarked base,
+ * so gemini-3.1-pro-preview still beats the older stable gemini-2.5-pro.
+ */
+
+'use strict';
+
+const { getFamilies, toDefaultAliases } = require('./curated-models');
+
+const MARKER_RE = /(-preview|-exp|-beta|-latest|:free)+$/;
+
+/** Numeric-desc comparator; same-base marker variant sorts after its base. */
+function compareIdsDesc(a, b) {
+  const aBase = a.replace(MARKER_RE, '');
+  const bBase = b.replace(MARKER_RE, '');
+  if (aBase === bBase && a !== b) {
+    if (a === aBase) { return -1; }
+    if (b === bBase) { return 1; }
+    return a.localeCompare(b, 'en', { numeric: true });
+  }
+  return b.localeCompare(a, 'en', { numeric: true });
+}
+
+/**
+ * Newest catalog id under `<nsPrefix><vendorPath>/` whose model segment
+ * matches idPattern. nsPrefix is 'openrouter/' or '' (direct rows).
+ * @param {string} vendorPath - vendor segment in the OpenRouter namespace,
+ *   or the provider name when matching direct-namespace rows (nsPrefix '').
+ * @returns {string|null} full catalog id
+ */
+function pickCurrent(catalog, nsPrefix, vendorPath, idPattern) {
+  const prefix = `${nsPrefix}${vendorPath}/`;
+  const ids = (Array.isArray(catalog) ? catalog : [])
+    .map(m => m && m.id)
+    .filter(id => typeof id === 'string' && id.startsWith(prefix))
+    .filter(id => idPattern.test(id.slice(prefix.length)));
+  if (ids.length === 0) { return null; }
+  return ids.sort(compareIdsDesc)[0];
+}
+
+/**
+ * @param {Array<{id:string}>} catalog
+ * @returns {Array<{alias,label,blurb,source:'live'|'fallback',routes:Object<string,string>}>}
+ * `routes` may be empty if a family defines no fallback and the catalog has no match.
+ */
+function resolveQuickPicks(catalog) {
+  return getFamilies().map(f => {
+    const routes = {};
+    let live = false;
+    const orPick = pickCurrent(catalog, 'openrouter/', f.vendorPath, f.idPattern);
+    if (orPick) { routes.openrouter = orPick; live = true; }
+    else if (f.fallback.openrouter) { routes.openrouter = f.fallback.openrouter; }
+    for (const p of f.directProviders) {
+      const direct = pickCurrent(catalog, '', p, f.idPattern);
+      if (direct) { routes[p] = direct; live = true; }
+      else if (f.fallback[p]) { routes[p] = f.fallback[p]; }
+    }
+    return { alias: f.alias, label: f.label, blurb: f.blurb, routes,
+             source: live ? 'live' : 'fallback' };
+  });
+}
+
+/**
+ * Seed map for fresh configs: static defaults overlaid with live family
+ * openrouter routes (cardless aliases stay pinned).
+ * @returns {Object<string,string>}
+ */
+function toLiveSeedAliases(catalog) {
+  const seeds = toDefaultAliases();
+  for (const r of resolveQuickPicks(catalog || [])) {
+    if (r.source === 'live' && r.routes.openrouter) { seeds[r.alias] = r.routes.openrouter; }
+  }
+  return seeds;
+}
+
+module.exports = { compareIdsDesc, pickCurrent, resolveQuickPicks, toLiveSeedAliases };

package/src/utils/result-schema.js

@@ -9,7 +9,7 @@
  * any rename/removal bumps SCHEMA_VERSION.
  */
 
-const SCHEMA_VERSION = 1;
+const SCHEMA_VERSION = 2;
 
 /** Leg/run statuses that count as terminal for wave aggregation. */
 const TERMINAL_STATUSES = ['complete', 'error', 'timeout', 'aborted', 'crashed', 'idle-timeout'];
@@ -48,7 +48,7 @@ function durationBetween(createdAt, completedAt) {
  * @param {string|null} [opts.waveId] - Explicit wave id (falls back to metadata.parentWave)
  * @returns {object} run document
  */
-function buildRunResult({ taskId, metadata = {}, result = null, summary = null, modelInput = null, sessionDir = null, waveId = null }) {
+function buildRunResult({ taskId, metadata = {}, result = null, summary = null, modelInput = null, sessionDir = null, waveId = null, usage = null }) {
   const status = result ? statusFromResult(result) : (metadata.status || 'unknown');
   const createdAt = metadata.createdAt || null;
   const completedAt = metadata.completedAt || metadata.abortedAt || null;
@@ -69,6 +69,7 @@ function buildRunResult({ taskId, metadata = {}, result = null, summary = null,
     durationMs,
     sessionDir,
     opencodeSessionId: metadata.opencodeSessionId || null,
+    usage: usage !== null ? usage : (metadata.usage || null),
   };
 }
 
@@ -115,6 +116,7 @@ function waveExitCode(waveStatus) {
  * @returns {object} wave document
  */
 function buildWaveResult({ waveId, legs = [], promptMeta = null, createdAt = null, completedAt = null, status = null }) {
+  const { sumWaveUsage } = require('./pricing');
   const counts = {
     total: legs.length,
     complete: legs.filter(l => l.status === 'complete').length,
@@ -135,6 +137,7 @@ function buildWaveResult({ waveId, legs = [], promptMeta = null, createdAt = nul
     createdAt,
     completedAt,
     durationMs,
+    usage: sumWaveUsage(legs),
   };
 }
 
@@ -246,6 +249,21 @@ function buildAuditDoc({ stale, catalogAvailable }) {
   };
 }
 
+/**
+ * Build a doctor health-check document (`doctor --json`).
+ * @param {{version: string, timestamp: string, checks: Array<{id,name,status,message,hint}>}} opts
+ */
+function buildDoctorDoc({ version, timestamp, checks }) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    type: 'doctor',
+    ok: checks.every(c => c.status !== 'error'),
+    version,
+    timestamp,
+    checks,
+  };
+}
+
 module.exports = {
   SCHEMA_VERSION,
   TERMINAL_STATUSES,
@@ -258,4 +276,5 @@ module.exports = {
   buildWaveResultFromSession,
   buildCatalogDoc,
   buildAuditDoc,
+  buildDoctorDoc,
 };

package/src/utils/session-abort.js

@@ -1,29 +1,33 @@
 /**
- * Session abort on process signals (F3 #20).
+ * Session abort utilities: signal handler installation and terminal metadata writes.
  *
- * When the parent process is killed (SIGTERM/SIGINT/SIGBREAK), the running
- * headless session must be aborted so no orphaned OpenCode session keeps
- * burning API credits. `markAborted` is the synchronous metadata write that
- * guarantees `amicus list` won't show an orphan afterward.
+ * Handles two related responsibilities: (1) installing process signal handlers
+ * (SIGINT, SIGTERM, SIGBREAK) that trigger abort callbacks, and (2) synchronously
+ * writing terminal status to session metadata (markTerminal and markAborted).
+ * These work together to ensure that when a session process is signaled, the
+ * session is marked as aborted immediately, preventing orphaned sessions from
+ * consuming API credits and ensuring `amicus list` reflects the true state.
  */
 
 const fs = require('fs');
 const path = require('path');
 
 /**
- * Synchronously mark a session's metadata as aborted. Best-effort: never throws.
+ * Synchronously write a terminal status to a session's metadata. Best-effort: never throws.
+ * `aborted` uses `abortedAt`; every other status uses `completedAt`.
  * @param {string} sessionDir
- * @param {string} reason - e.g. a signal name
- * @returns {boolean} true if the session was marked aborted
+ * @param {'aborted'|'timed-out'|'error'|'complete'} status
+ * @param {string} reason
+ * @returns {boolean} true if written
  */
-function markAborted(sessionDir, reason) {
+function markTerminal(sessionDir, status, reason) {
   try {
     const metaPath = path.join(sessionDir, 'metadata.json');
     if (!fs.existsSync(metaPath)) { return false; }
     const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
-    meta.status = 'aborted';
-    meta.reason = `Aborted (${reason})`;
-    meta.abortedAt = new Date().toISOString();
+    meta.status = status;
+    meta.reason = reason;
+    meta[status === 'aborted' ? 'abortedAt' : 'completedAt'] = new Date().toISOString();
     fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
     return true;
   } catch {
@@ -31,6 +35,11 @@ function markAborted(sessionDir, reason) {
   }
 }
 
+/** Mark a session aborted (preserves prior behavior). */
+function markAborted(sessionDir, reason) {
+  return markTerminal(sessionDir, 'aborted', `Aborted (${reason})`);
+}
+
 /**
  * Register signal handlers that call onAbort(signal). Returns an uninstall fn.
  * @param {{onAbort: (signal: string) => void, signals?: string[]}} opts
@@ -50,4 +59,22 @@ function installSignalAbort({ onAbort, signals = ['SIGINT', 'SIGTERM', 'SIGBREAK
   };
 }
 
-module.exports = { markAborted, installSignalAbort };
+/**
+ * Idle-backstop teardown: mark timed-out, write a stub summary, close the owned server.
+ * Returns the exit code (always 2).
+ * @param {string} sessionDir
+ * @param {{close: () => void}|null} server
+ * @param {boolean} externalServer - when true, the server is not ours to close
+ * @returns {2}
+ */
+function idleBackstopTeardown(sessionDir, server, externalServer) {
+  try {
+    markTerminal(sessionDir, 'timed-out', 'Idle backstop timeout');
+    fs.writeFileSync(path.join(sessionDir, 'summary.md'),
+      'Session timed out — idle backstop fired before completion.\n', { mode: 0o600 });
+  } catch { /* best-effort */ }
+  if (!externalServer && server) { try { server.close(); } catch { /* best-effort */ } }
+  return 2;
+}
+
+module.exports = { markTerminal, markAborted, installSignalAbort, idleBackstopTeardown };

package/src/utils/validators.js

@@ -168,7 +168,7 @@ function validateExplicitSession(session, _projectPath) {
   if (!found) {
     return {
       valid: false,
-      error: `Error: --session '${session}' not found. Use 'sidecar list' to see available sessions or omit --session for most recent.`
+      error: `Error: --session '${session}' not found. Use 'amicus list' to see available sessions or omit --session for most recent.`
     };
   }
 
@@ -176,12 +176,7 @@ function validateExplicitSession(session, _projectPath) {
 }
 
 /**
- * Validate agent mode
- *
- * Accepts:
- * - OpenCode native agents: Build, Plan, General, Explore
- * - Custom agents: any non-empty string (for user-defined OpenCode agents)
- *
+ * Validate agent mode (native OpenCode agents or any non-empty custom agent string).
  * @param {string} agent
  * @returns {{valid: boolean, error?: string}}
  */
@@ -239,11 +234,8 @@ const { MODEL_THINKING_SUPPORT, getSupportedThinkingLevels, validateThinkingLeve
 
 /**
  * Validate API key is present for the given model's provider.
- *
- * Assumes loadCredentials() has already run, projecting all credential
- * sources (sidecar .env, auth.json) into process.env.
- *
- * @param {string} model - The model string (e.g., 'openrouter/google/gemini-2.5-flash')
+ * Assumes loadCredentials() has already run (projects .env + auth.json → process.env).
+ * @param {string} model - e.g. 'openrouter/google/gemini-2.5-flash'
  * @returns {{valid: boolean, error?: string}}
  */
 function validateApiKey(model) {
@@ -259,14 +251,22 @@ function validateApiKey(model) {
   }
 
   if (!process.env[providerInfo.key]) {
+    const keyName = providerInfo.key;
+    const isWin = process.platform === 'win32';
+    const persist = isWin
+      ? `  - Persist it for new shells: setx ${keyName} <your-key>\n` +
+        `    (or add $env:${keyName} to your PowerShell $PROFILE)\n`
+      : `  - Persist it across shells: add 'export ${keyName}=<your-key>' to ~/.zshenv\n` +
+        '    (non-interactive shells like Claude Code and CI do not source ~/.zshrc)\n';
     return {
       valid: false,
-      error: `Error: ${providerInfo.key} not found.\n\n` +
-        'In non-interactive shells (Claude Code, CI), ~/.zshrc is not sourced.\n' +
+      code: 'MISSING_KEY',
+      error:
+        `Error: ${keyName} not found for ${providerInfo.name}.\n\n` +
         'Fix with one of:\n' +
-        '  - Run `sidecar setup` to store keys in sidecar\'s config\n' +
-        '  - Move your export to ~/.zshenv (sourced by all zsh shells)\n' +
-        '  - Add key to ~/.local/share/opencode/auth.json'
+        `  - Store it in Amicus (recommended): amicus key ${provider} <apikey>\n` +
+        persist +
+        '  - Or add it to ~/.local/share/opencode/auth.json\n',
     };
   }