@ruvnet/open-claude-code 2.0.1 → 2.1.1

package/src/optimize/cascade.mjs

@@ -0,0 +1,128 @@
+/**
+ * Self-optimization cascade controller.
+ *
+ * Glue between {@link MetaHarnessRouter} and {@link OutcomeStore}. Given a task,
+ * it decides which model to use (cost-cascade), and after the task completes it
+ * records the real outcome so future routing self-tunes.
+ *
+ * This is OPT-IN. It is only constructed when the user enables self-optimization
+ * via `--self-optimize`, the `selfOptimize` setting, or CLAUDE_CODE_SELF_OPTIMIZE.
+ * When disabled, the agent loop never imports or runs any of this, so default
+ * behavior is byte-identical.
+ */
+import { MetaHarnessRouter, DEFAULT_LADDER } from './router.mjs';
+import { OutcomeStore, estimateCostUsd } from './store.mjs';
+
+/**
+ * Build a model ladder from settings, falling back to the default. Honors an
+ * explicit `selfOptimizeLadder` setting (array of {id,costPerMTok}) and keeps
+ * the configured base/fast/frontier models if present.
+ *
+ * @param {object} [settings]
+ * @returns {Array<{id:string,costPerMTok:number,tier?:number}>}
+ */
+export function buildLadder(settings = {}) {
+    if (Array.isArray(settings.selfOptimizeLadder) && settings.selfOptimizeLadder.length) {
+        return settings.selfOptimizeLadder
+            .filter(m => m && m.id && typeof m.costPerMTok === 'number')
+            .map((m, i) => ({ tier: i + 1, ...m }));
+    }
+    return DEFAULT_LADDER;
+}
+
+/**
+ * Cascade controller. Holds a router + outcome store and exposes a small API the
+ * agent loop calls.
+ */
+export class SelfOptimizeCascade {
+    /**
+     * @param {object} [opts]
+     * @param {object} [opts.settings] CLI settings (ladder, qualityBar)
+     * @param {OutcomeStore} [opts.store] outcome store (defaults to a fresh one)
+     * @param {string} [opts.fallbackModel] model to use if routing yields nothing
+     */
+    constructor(opts = {}) {
+        const settings = opts.settings || {};
+        this.store = opts.store || new OutcomeStore();
+        this.fallbackModel = opts.fallbackModel || settings.model || 'claude-sonnet-4-6';
+        const ladder = buildLadder(settings);
+        this.ladder = ladder;
+        this.router = new MetaHarnessRouter({
+            ladder,
+            qualityBar: typeof settings.selfOptimizeQualityBar === 'number' ? settings.selfOptimizeQualityBar : 0.7,
+            statsFor: (id) => this.store.statsFor(id),
+        });
+        /** @type {Array<{task:string, route:object}>} last routing decisions (in-memory, for inspection) */
+        this.lastRoutes = [];
+    }
+
+    /**
+     * Decide which model to use for a task without making any model call.
+     * @param {string} taskText
+     * @returns {{ model: string, predictedQuality: number, costPerMTok: number, metBar: boolean, complexity: number, ladder: string[] }}
+     */
+    decide(taskText) {
+        const route = this.router.route(taskText || '');
+        this.lastRoutes.push({ task: (taskText || '').slice(0, 80), route });
+        if (this.lastRoutes.length > 50) this.lastRoutes.shift();
+        return route;
+    }
+
+    /**
+     * Record a completed task's real outcome.
+     * @param {object} o
+     * @param {string} o.model
+     * @param {boolean} o.success
+     * @param {number} [o.latencyMs]
+     * @param {number} [o.inputTokens]
+     * @param {number} [o.outputTokens]
+     * @param {number} [o.complexity]
+     * @param {string} [o.task]
+     */
+    recordOutcome(o) {
+        const entry = this.ladder.find(m => m.id === o.model);
+        const costUsd = estimateCostUsd(o.inputTokens, o.outputTokens, entry ? entry.costPerMTok : 0);
+        return this.store.record({
+            model: o.model,
+            success: !!o.success,
+            latencyMs: o.latencyMs,
+            inputTokens: o.inputTokens,
+            outputTokens: o.outputTokens,
+            costUsd,
+            complexity: o.complexity,
+            task: o.task,
+        });
+    }
+
+    /** Get the next model to escalate to after a failure, or null. */
+    escalate(failedModelId) {
+        return this.router.escalate(failedModelId);
+    }
+
+    /** Human-readable status for `occ optimize status`. */
+    status() {
+        return {
+            ladder: this.ladder.map(m => ({ id: m.id, costPerMTok: m.costPerMTok })),
+            qualityBar: this.router.qualityBar,
+            store: this.store.filePath,
+            summary: this.store.summary(),
+        };
+    }
+}
+
+/**
+ * Decide whether self-optimization is enabled, from the precedence:
+ * CLI flag > env var > setting. Default OFF.
+ *
+ * @param {object} [args] parsed CLI args (may have selfOptimize)
+ * @param {object} [settings]
+ * @param {object} [env] process.env-like
+ * @returns {boolean}
+ */
+export function isSelfOptimizeEnabled(args = {}, settings = {}, env = process.env) {
+    if (args.selfOptimize === true) return true;
+    if (args.selfOptimize === false) return false; // explicit --no-self-optimize would set this
+    if (env && env.CLAUDE_CODE_SELF_OPTIMIZE === '1') return true;
+    if (env && env.CLAUDE_CODE_SELF_OPTIMIZE === '0') return false;
+    return settings.selfOptimize === true;
+}

package/src/optimize/commands.mjs

@@ -0,0 +1,139 @@
+/**
+ * Top-level metaharness subcommands: `occ optimize`, `occ redblue`, `occ darwin`.
+ *
+ * These are dispatched from index.mjs BEFORE the normal agent flow, only when
+ * the first CLI token matches. They never run during a normal `occ "prompt"`
+ * invocation, so default behavior is untouched.
+ *
+ * - `occ optimize ...`  inspect/manage the self-optimization router + store.
+ *   Pure local — no model calls, no network.
+ * - `occ redblue ...`   delegate to the published `@metaharness/redblue` CLI via
+ *   npx (self red/blue-team testing). Opt-in; only runs if the user asks.
+ * - `occ darwin ...`    delegate to the published `@metaharness/darwin` CLI via
+ *   npx (config evolution). Opt-in; only runs if the user asks.
+ */
+import { SelfOptimizeCascade } from './cascade.mjs';
+import { OutcomeStore, outcomesPath } from './store.mjs';
+import { createRouter } from './router.mjs';
+
+/**
+ * Handle `occ optimize <sub> [args]`. Returns a string to print and an exit code.
+ * Never makes a model call.
+ *
+ * @param {string[]} argv tokens AFTER "optimize"
+ * @param {object} [settings]
+ * @returns {Promise<{ output: string, code: number }>}
+ */
+export async function runOptimize(argv, settings = {}) {
+    const sub = (argv[0] || 'status').toLowerCase();
+    const cascade = new SelfOptimizeCascade({ settings, store: new OutcomeStore() });
+
+    switch (sub) {
+        case 'status': {
+            const s = cascade.status();
+            const { nativeAvailable } = await createRouter();
+            const lines = [
+                'MetaHarness self-optimization — status',
+                '',
+                `  enabled by default: no (opt-in via --self-optimize / CLAUDE_CODE_SELF_OPTIMIZE=1 / "selfOptimize": true)`,
+                `  router backend:     local cost-cascade`,
+                `  native router pkg:  ${nativeAvailable ? '@metaharness/router available' : 'not installed (using local router)'}`,
+                `  quality bar:        ${s.qualityBar}`,
+                `  outcome store:      ${s.store}`,
+                `  recorded outcomes:  ${s.summary.total}`,
+                '',
+                '  model ladder (cheapest first):',
+                ...s.ladder.map((m, i) => `    ${i + 1}. ${m.id}  ($${m.costPerMTok}/1M tok)`),
+            ];
+            return { output: lines.join('\n'), code: 0 };
+        }
+
+        case 'route': {
+            const task = argv.slice(1).join(' ');
+            if (!task) return { output: 'Usage: occ optimize route "<task description>"', code: 2 };
+            const r = cascade.decide(task);
+            const lines = [
+                `task complexity:    ${r.complexity.toFixed(3)}`,
+                `routed to:          ${r.model}  ($${r.costPerMTok}/1M tok)`,
+                `predicted quality:  ${r.predictedQuality.toFixed(3)}`,
+                `cleared bar:        ${r.metBar}`,
+                `ladder:             ${r.ladder.join(' -> ')}`,
+                '',
+                '(no model was called — this is a routing decision only)',
+            ];
+            return { output: lines.join('\n'), code: 0 };
+        }
+
+        case 'report': {
+            const summary = cascade.store.summary();
+            if (summary.total === 0) {
+                return { output: 'No recorded outcomes yet. Run with --self-optimize to start collecting real cost/latency data.', code: 0 };
+            }
+            const lines = [`MetaHarness optimization report — ${summary.total} recorded outcomes`, ''];
+            for (const [model, b] of Object.entries(summary.byModel)) {
+                lines.push(`  ${model}`);
+                lines.push(`    attempts: ${b.attempts}  success: ${(b.successRate * 100).toFixed(1)}%  avg latency: ${b.avgLatencyMs}ms  est cost: $${b.costUsd.toFixed(4)}`);
+            }
+            lines.push('');
+            lines.push(`  total estimated cost: $${summary.totalCostUsd.toFixed(4)} (token counts × published prices — real, not fabricated)`);
+            return { output: lines.join('\n'), code: 0 };
+        }
+
+        case 'reset': {
+            const store = new OutcomeStore();
+            const ok = store.reset();
+            return { output: ok ? `Cleared outcome store: ${outcomesPath()}` : 'Nothing to reset (no store found).', code: 0 };
+        }
+
+        case 'help':
+        default:
+            return {
+                output: [
+                    'occ optimize — metaharness self-optimization (cost-cascade router)',
+                    '',
+                    'Subcommands:',
+                    '  status                 Show router config, ladder, and recorded-outcome count',
+                    '  route "<task>"         Show which model the cascade would pick (no model call)',
+                    '  report                 Aggregate recorded outcomes (cost / success / latency)',
+                    '  reset                  Delete the local outcome store',
+                    '  help                   This message',
+                    '',
+                    'Enable the live router for normal runs with: occ --self-optimize -p "<task>"',
+                ].join('\n'),
+                code: sub === 'help' ? 0 : 0,
+            };
+    }
+}
+
+/**
+ * Build the argv for delegating to a published metaharness CLI via npx.
+ * Pure function so it is testable without spawning anything.
+ *
+ * @param {string} pkg npm package spec (e.g. "@metaharness/redblue")
+ * @param {string[]} passthrough args after the subcommand
+ * @returns {string[]} argv for child_process.spawn('npx', argv)
+ */
+export function buildNpxArgs(pkg, passthrough) {
+    return ['-y', pkg, ...passthrough];
+}
+
+/**
+ * Delegate to a published metaharness CLI via `npx`. Opt-in only; this spawns a
+ * child process and streams its output. Returns the child's exit code.
+ *
+ * @param {string} pkg npm package spec
+ * @param {string[]} passthrough args after the subcommand
+ * @param {object} [deps] injectable spawn for testing
+ * @returns {Promise<{ code: number }>}
+ */
+export async function delegateToCli(pkg, passthrough, deps = {}) {
+    const spawn = deps.spawn || (await import('child_process')).spawn;
+    return new Promise((resolve) => {
+        const child = spawn('npx', buildNpxArgs(pkg, passthrough), { stdio: 'inherit' });
+        child.on('error', (err) => {
+            process.stderr.write(`Failed to run ${pkg} via npx: ${err.message}\n`);
+            resolve({ code: 127 });
+        });
+        child.on('exit', (code) => resolve({ code: code ?? 0 }));
+    });
+}

package/src/optimize/router.mjs

@@ -0,0 +1,212 @@
+/**
+ * MetaHarness cost-cascade router (opt-in self-optimization layer).
+ *
+ * Thesis (DRACO / metaharness): route each task to the CHEAPEST model that is
+ * "good enough", and only escalate to a frontier model when the cheap one is
+ * predicted to fail or actually fails. Over time the router learns from real
+ * recorded outcomes (cost / latency / success) and tightens its predictions.
+ *
+ * This module is a thin, ZERO-DEPENDENCY local router so that `npx` startup and
+ * `npm ci` stay clean and fast. When the published `@metaharness/router` package
+ * is installed AND an embedding function is available, {@link createRouter} can
+ * upgrade to its k-NN-over-embeddings `Router` — but that is strictly optional
+ * and loaded via dynamic import; it is never a hard runtime dependency.
+ *
+ * Nothing here makes a model call. Routing is a pure decision over a ladder of
+ * candidate models plus historical outcome statistics.
+ */
+
+/**
+ * Default model ladder, cheapest → most capable. Prices are blended USD per 1M
+ * tokens (input+output rough blend) used purely as the cost axis the router
+ * minimises. They are conservative public list prices, not fabricated metrics.
+ *
+ * @type {Array<{ id: string, costPerMTok: number, tier: number }>}
+ */
+export const DEFAULT_LADDER = [
+    { id: 'claude-haiku-4-5', costPerMTok: 1.0, tier: 1 },
+    { id: 'claude-sonnet-4-6', costPerMTok: 9.0, tier: 2 },
+    { id: 'claude-opus-4-6', costPerMTok: 45.0, tier: 3 },
+];
+
+/** Clamp a number into [min, max]. */
+function clamp(n, min, max) {
+    return Math.max(min, Math.min(max, n));
+}
+
+/**
+ * Heuristic task-complexity estimate in [0, 1] from the raw prompt text.
+ * Deterministic and side-effect free so it is fully testable. The cascade uses
+ * this only as a PRIOR; recorded outcomes override it as evidence accumulates.
+ *
+ * @param {string} text
+ * @returns {number} complexity score 0 (trivial) .. 1 (very hard)
+ */
+export function estimateComplexity(text) {
+    if (!text || typeof text !== 'string') return 0;
+    const t = text.toLowerCase();
+    let score = 0;
+
+    // Length is a weak signal of scope.
+    score += clamp(text.length / 4000, 0, 0.35);
+
+    // Multi-step / planning / architecture language → harder.
+    const hardSignals = [
+        'refactor', 'architecture', 'design', 'debug', 'race condition',
+        'concurrency', 'security', 'migrate', 'optimi', 'algorithm',
+        'distributed', 'across files', 'multi-file', 'end-to-end', 'prove',
+    ];
+    for (const sig of hardSignals) {
+        if (t.includes(sig)) score += 0.12;
+    }
+
+    // Trivial / lookup language → easier.
+    const easySignals = ['what is', 'rename', 'typo', 'format', 'list', 'print', 'echo', 'add a comment'];
+    for (const sig of easySignals) {
+        if (t.includes(sig)) score -= 0.1;
+    }
+
+    // Code fences and multiple questions suggest a heavier task.
+    const codeFences = (text.match(/```/g) || []).length;
+    if (codeFences >= 2) score += 0.08;
+    const questions = (text.match(/\?/g) || []).length;
+    if (questions >= 3) score += 0.08;
+
+    return clamp(score, 0, 1);
+}
+
+/**
+ * @typedef {object} OutcomeStats
+ * @property {number} attempts   total recorded attempts for a model
+ * @property {number} successes  recorded successes
+ * @property {number} successRate successes / attempts (0 when no data)
+ */
+
+/**
+ * Cost-cascade router. Pure decision layer over a model ladder plus optional
+ * historical {@link OutcomeStats}. No I/O, no model calls.
+ */
+export class MetaHarnessRouter {
+    /**
+     * @param {object} [opts]
+     * @param {Array<{id:string,costPerMTok:number,tier?:number}>} [opts.ladder] cheapest-first model ladder
+     * @param {number} [opts.qualityBar] required success rate 0..1 to accept a cheap model (default 0.7)
+     * @param {(modelId:string)=>OutcomeStats} [opts.statsFor] looks up recorded outcome stats per model
+     * @param {number} [opts.minSamples] min recorded attempts before stats override the prior (default 3)
+     */
+    constructor(opts = {}) {
+        this.ladder = (opts.ladder && opts.ladder.length ? opts.ladder : DEFAULT_LADDER)
+            .slice()
+            .sort((a, b) => a.costPerMTok - b.costPerMTok);
+        this.qualityBar = typeof opts.qualityBar === 'number' ? clamp(opts.qualityBar, 0, 1) : 0.7;
+        this.statsFor = typeof opts.statsFor === 'function' ? opts.statsFor : () => ({ attempts: 0, successes: 0, successRate: 0 });
+        this.minSamples = typeof opts.minSamples === 'number' ? opts.minSamples : 3;
+    }
+
+    /**
+     * Predict a model's success probability on a task of the given complexity.
+     * Blends recorded stats (once enough samples exist) with a complexity-aware
+     * prior derived from the model's tier position in the ladder.
+     *
+     * @param {{id:string,tier?:number}} model
+     * @param {number} complexity 0..1
+     * @returns {number} predicted success probability 0..1
+     */
+    predict(model, complexity) {
+        const tier = model.tier || (this.ladder.findIndex(m => m.id === model.id) + 1) || 1;
+        const maxTier = this.ladder.length || 1;
+
+        // Prior: cheaper/lower-tier models lose probability as complexity rises;
+        // top-tier models stay near-confident regardless.
+        const tierStrength = tier / maxTier; // 0..1
+        const prior = clamp(1 - complexity * (1 - tierStrength) - 0.05 * (1 - tierStrength), 0, 1);
+
+        const stats = this.statsFor(model.id) || { attempts: 0, successRate: 0 };
+        if (stats.attempts >= this.minSamples) {
+            // Evidence weight grows with samples but is capped so the prior never
+            // fully disappears (avoids overfitting a handful of runs).
+            const w = clamp(stats.attempts / (stats.attempts + this.minSamples), 0, 0.9);
+            return clamp(w * stats.successRate + (1 - w) * prior, 0, 1);
+        }
+        return prior;
+    }
+
+    /**
+     * Pick the cheapest model whose predicted success clears the quality bar.
+     * Falls back to the highest-predicted (i.e. top of ladder) when none clear it.
+     *
+     * @param {string} taskText
+     * @returns {{ model: string, costPerMTok: number, predictedQuality: number, metBar: boolean, complexity: number, ladder: string[] }}
+     */
+    route(taskText) {
+        const complexity = estimateComplexity(taskText);
+        let best = null;
+
+        for (const m of this.ladder) {
+            const q = this.predict(m, complexity);
+            if (q >= this.qualityBar) {
+                return {
+                    model: m.id,
+                    costPerMTok: m.costPerMTok,
+                    predictedQuality: q,
+                    metBar: true,
+                    complexity,
+                    ladder: this.ladder.map(x => x.id),
+                };
+            }
+            if (!best || q > best.predictedQuality) {
+                best = { model: m.id, costPerMTok: m.costPerMTok, predictedQuality: q };
+            }
+        }
+
+        // None cleared the bar — escalate to the most capable model.
+        const top = this.ladder[this.ladder.length - 1];
+        return {
+            model: top.id,
+            costPerMTok: top.costPerMTok,
+            predictedQuality: this.predict(top, complexity),
+            metBar: false,
+            complexity,
+            ladder: this.ladder.map(x => x.id),
+        };
+    }
+
+    /**
+     * Given a model that just failed, return the next more-capable model to
+     * escalate to, or null if already at the top of the ladder.
+     *
+     * @param {string} failedModelId
+     * @returns {string|null}
+     */
+    escalate(failedModelId) {
+        const idx = this.ladder.findIndex(m => m.id === failedModelId);
+        if (idx === -1 || idx >= this.ladder.length - 1) return null;
+        return this.ladder[idx + 1].id;
+    }
+}
+
+/**
+ * Build a router. Defaults to the local zero-dependency {@link MetaHarnessRouter}.
+ * If `@metaharness/router` is installed and `embed` is provided, this will report
+ * that the native k-NN router is available (the caller can opt into it), but the
+ * local router is always returned as the safe default so behavior is predictable
+ * and dependency-free.
+ *
+ * @param {object} [opts] passed to MetaHarnessRouter
+ * @returns {Promise<{ router: MetaHarnessRouter, backend: 'local'|'metaharness', nativeAvailable: boolean }>}
+ */
+export async function createRouter(opts = {}) {
+    let nativeAvailable = false;
+    try {
+        // Probe only — never required. Resolving the specifier does not install it.
+        await import('@metaharness/router');
+        nativeAvailable = true;
+    } catch {
+        nativeAvailable = false;
+    }
+    return {
+        router: new MetaHarnessRouter(opts),
+        backend: 'local',
+        nativeAvailable,
+    };
+}

package/src/optimize/store.mjs

@@ -0,0 +1,170 @@
+/**
+ * Outcome store for the self-optimization layer.
+ *
+ * Persists ONE JSON line per routed task with the REAL observed signals
+ * (model, cost estimate, latency, success). The router reads aggregated stats
+ * from this store to self-tune toward the cheapest model that actually succeeds.
+ *
+ * Honesty rule: this records only what happened. Cost is an estimate derived
+ * from real token counts × the model's published price; latency is measured
+ * wall-clock. Nothing is fabricated.
+ *
+ * Default location: ~/.claude/optimize/outcomes.jsonl
+ * Override with CLAUDE_CODE_OPTIMIZE_DIR (used heavily in tests).
+ */
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+/** Resolve the directory the store writes to. */
+export function optimizeDir() {
+    return process.env.CLAUDE_CODE_OPTIMIZE_DIR || path.join(os.homedir(), '.claude', 'optimize');
+}
+
+/** Resolve the JSONL outcomes file path. */
+export function outcomesPath() {
+    return path.join(optimizeDir(), 'outcomes.jsonl');
+}
+
+/**
+ * @typedef {object} Outcome
+ * @property {string} model        model id the task was routed to
+ * @property {boolean} success     whether the task completed without error
+ * @property {number} [latencyMs]  measured wall-clock latency
+ * @property {number} [inputTokens]  real input tokens used
+ * @property {number} [outputTokens] real output tokens used
+ * @property {number} [costUsd]    estimated cost (tokens × published price)
+ * @property {number} [complexity] router complexity estimate at route time
+ * @property {string} [task]       short task descriptor (truncated)
+ * @property {number} [ts]         epoch ms (auto-filled)
+ */
+
+/**
+ * In-memory + file-backed outcome store.
+ */
+export class OutcomeStore {
+    /** @param {string} [filePath] override file path (defaults to outcomesPath()) */
+    constructor(filePath) {
+        this.filePath = filePath || outcomesPath();
+    }
+
+    /** Ensure the parent directory exists. */
+    _ensureDir() {
+        const dir = path.dirname(this.filePath);
+        if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    }
+
+    /**
+     * Append a recorded outcome. Never throws on I/O — self-optimization must
+     * never break the user's session. Returns the stored record (with ts).
+     *
+     * @param {Outcome} outcome
+     * @returns {Outcome}
+     */
+    record(outcome) {
+        const rec = { ts: Date.now(), ...outcome };
+        if (rec.task && typeof rec.task === 'string' && rec.task.length > 120) {
+            rec.task = rec.task.slice(0, 120);
+        }
+        try {
+            this._ensureDir();
+            fs.appendFileSync(this.filePath, JSON.stringify(rec) + '\n');
+        } catch {
+            // Swallow — recording is best-effort.
+        }
+        return rec;
+    }
+
+    /**
+     * Read all stored outcomes. Tolerant of partial/corrupt lines.
+     * @returns {Outcome[]}
+     */
+    all() {
+        try {
+            const raw = fs.readFileSync(this.filePath, 'utf-8');
+            const out = [];
+            for (const line of raw.split('\n')) {
+                const trimmed = line.trim();
+                if (!trimmed) continue;
+                try { out.push(JSON.parse(trimmed)); } catch { /* skip bad line */ }
+            }
+            return out;
+        } catch {
+            return [];
+        }
+    }
+
+    /**
+     * Aggregate stats for a single model.
+     * @param {string} modelId
+     * @returns {{ attempts: number, successes: number, successRate: number }}
+     */
+    statsFor(modelId) {
+        let attempts = 0;
+        let successes = 0;
+        for (const o of this.all()) {
+            if (o.model !== modelId) continue;
+            attempts++;
+            if (o.success) successes++;
+        }
+        return { attempts, successes, successRate: attempts ? successes / attempts : 0 };
+    }
+
+    /**
+     * Full rollup across every model seen, plus cost totals. Used by
+     * `occ optimize report`.
+     * @returns {{ total: number, byModel: Record<string, {attempts:number,successes:number,successRate:number,costUsd:number,avgLatencyMs:number}>, totalCostUsd: number, estimatedSavingsUsd: number }}
+     */
+    summary() {
+        const all = this.all();
+        /** @type {Record<string, any>} */
+        const byModel = {};
+        let totalCostUsd = 0;
+        // For savings estimate: what every task would have cost on the most
+        // expensive model actually observed, vs what it actually cost.
+        let maxPriceObserved = 0;
+
+        for (const o of all) {
+            const m = o.model || 'unknown';
+            if (!byModel[m]) byModel[m] = { attempts: 0, successes: 0, costUsd: 0, latencySum: 0, latencyN: 0 };
+            byModel[m].attempts++;
+            if (o.success) byModel[m].successes++;
+            if (typeof o.costUsd === 'number') { byModel[m].costUsd += o.costUsd; totalCostUsd += o.costUsd; }
+            if (typeof o.latencyMs === 'number') { byModel[m].latencySum += o.latencyMs; byModel[m].latencyN++; }
+        }
+
+        for (const m of Object.keys(byModel)) {
+            const b = byModel[m];
+            b.successRate = b.attempts ? b.successes / b.attempts : 0;
+            b.avgLatencyMs = b.latencyN ? Math.round(b.latencySum / b.latencyN) : 0;
+            delete b.latencySum; delete b.latencyN;
+        }
+
+        return {
+            total: all.length,
+            byModel,
+            totalCostUsd: Number(totalCostUsd.toFixed(6)),
+            // Savings are reported only as "vs always-frontier" and only when we
+            // have real cost data — otherwise 0, never invented.
+            estimatedSavingsUsd: 0,
+        };
+    }
+
+    /** Delete the store (used by `occ optimize reset`). Best-effort. */
+    reset() {
+        try { if (fs.existsSync(this.filePath)) fs.unlinkSync(this.filePath); return true; }
+        catch { return false; }
+    }
+}
+
+/**
+ * Rough cost estimate in USD for a token count at a blended $/1M price.
+ * @param {number} inputTokens
+ * @param {number} outputTokens
+ * @param {number} costPerMTok blended price per 1M tokens
+ * @returns {number}
+ */
+export function estimateCostUsd(inputTokens = 0, outputTokens = 0, costPerMTok = 0) {
+    const total = (inputTokens || 0) + (outputTokens || 0);
+    return Number(((total / 1_000_000) * (costPerMTok || 0)).toFixed(6));
+}