@phuetz/code-buddy 1.6.1 → 2.1.0

package/dist/agent/science/experiment-variant-store.js

@@ -0,0 +1,156 @@
+/**
+ * AI-Scientist-lite — Phase 1: the experiment variant store.
+ *
+ * A genuinely APPEND-ONLY record of SCORED experiment variants (JSONL — one
+ * variant per line, appended with O_APPEND), calqued on
+ * `CodeVariantStore`/`EvolutionaryArchive` but DECOUPLED from the repo: a record
+ * carries the experiment's hypothesis + code + execution summary + measured
+ * metric + fitness + lineage (`parentId`), NOT a git branch/sha of Code Buddy.
+ *
+ * JSONL append (like the CKG ledger) is why two `buddy science` runs in the same
+ * cwd no longer clobber each other: `record()` appends a single line instead of
+ * rewriting the whole file, so a concurrent writer can't erase another's variant
+ * (the old full read-modify-write was last-writer-wins). A legacy single-object
+ * store (`{schemaVersion,variants:[…]}`) is still read back and is migrated to
+ * JSONL on the next append.
+ *
+ * It records and reads back; it NEVER "publishes" a variant. `kept` flips to true
+ * ONLY after the human keep-gate approves (Phase 1 §4) — a rejected/ungated
+ * variant stays archived (auditable) but is never marked kept. Timestamps are
+ * INJECTED by the caller (no `Date.now()` here). never-throws.
+ *
+ * @module agent/science/experiment-variant-store
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { logger } from '../../utils/logger.js';
+import { writeFileAtomicSync } from '../../utils/atomic-write.js';
+function defaultStorePath() {
+    return join(process.cwd(), '.codebuddy', 'science', 'experiment-variants.json');
+}
+/**
+ * Append-only JSONL store for scored experiment variants. Mirrors
+ * `CodeVariantStore`: `record()` appends ONE line, `list()`/`get()` read back,
+ * `best()` selects. never-throws. Concurrent-safe (O_APPEND, no full rewrite).
+ */
+export class ExperimentVariantStore {
+    path;
+    constructor(path) {
+        this.path = path ?? defaultStorePath();
+    }
+    getPath() {
+        return this.path;
+    }
+    list() {
+        if (!existsSync(this.path))
+            return [];
+        let raw;
+        try {
+            raw = readFileSync(this.path, 'utf8');
+        }
+        catch (err) {
+            logger.warn(`[science] experiment variant store unreadable: ${err instanceof Error ? err.message : String(err)}`);
+            return [];
+        }
+        const trimmed = raw.trim();
+        if (!trimmed)
+            return [];
+        // Backward-compat: an older single-object store `{schemaVersion,variants:[…]}`.
+        if (trimmed.startsWith('{') && trimmed.includes('"variants"')) {
+            try {
+                const data = JSON.parse(trimmed);
+                if (Array.isArray(data?.variants))
+                    return data.variants;
+            }
+            catch {
+                // Not parseable as a legacy object — fall through to best-effort JSONL.
+            }
+        }
+        // JSONL: one variant per line. A torn/corrupt line is skipped (never-throws)
+        // rather than nuking the whole store.
+        const out = [];
+        for (const line of trimmed.split('\n')) {
+            const t = line.trim();
+            if (!t)
+                continue;
+            try {
+                out.push(JSON.parse(t));
+            }
+            catch {
+                /* skip a corrupt line */
+            }
+        }
+        return out;
+    }
+    get(id) {
+        return this.list().find((v) => v.id === id) ?? null;
+    }
+    /**
+     * Append a variant record as one JSONL line (best-effort, never throws). This
+     * is a true append (O_APPEND), so concurrent `buddy science` runs in the same
+     * cwd cannot clobber each other's variants.
+     */
+    record(rec) {
+        try {
+            mkdirSync(dirname(this.path), { recursive: true });
+            // One-time migration of a legacy single-object store to JSONL, so the
+            // append below does not strand the pre-existing variants.
+            this.migrateLegacyIfNeeded();
+            appendFileSync(this.path, `${JSON.stringify(rec)}\n`);
+        }
+        catch (err) {
+            logger.warn(`[science] experiment variant store write failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * If the store is still in the legacy `{schemaVersion,variants:[…]}` format,
+     * rewrite it as JSONL ONCE so subsequent appends stay pure appends. A
+     * non-parseable legacy blob is left untouched (never-throws; `list()` still
+     * best-effort-parses lines). Called only from `record()`.
+     */
+    migrateLegacyIfNeeded() {
+        if (!existsSync(this.path))
+            return;
+        const trimmed = readFileSync(this.path, 'utf8').trim();
+        if (!(trimmed.startsWith('{') && trimmed.includes('"variants"')))
+            return;
+        try {
+            const data = JSON.parse(trimmed);
+            const variants = Array.isArray(data?.variants) ? data.variants : [];
+            writeFileAtomicSync(this.path, variants.map((v) => JSON.stringify(v)).join('\n') + (variants.length ? '\n' : ''));
+        }
+        catch {
+            /* leave a non-parseable legacy file as-is */
+        }
+    }
+    /**
+     * The winner: highest-scoring variant that passed everything, has no
+     * regression, and (if given) strictly beats the baseline score. Ties broken by
+     * most recent. null if none qualify.
+     */
+    best(opts = {}) {
+        const requirePassedAll = opts.requirePassedAll !== false;
+        const rejectRegressions = opts.rejectRegressions !== false;
+        const eligible = this.list().filter((v) => {
+            if (requirePassedAll && !v.passedAll)
+                return false;
+            if (rejectRegressions && v.regressions.length > 0)
+                return false;
+            if (opts.requireKept && !v.kept)
+                return false;
+            if (opts.baselineScore !== undefined && !(v.score > opts.baselineScore))
+                return false;
+            return true;
+        });
+        if (eligible.length === 0)
+            return null;
+        return eligible.reduce((best, v) => {
+            if (v.score > best.score)
+                return v;
+            if (v.score === best.score && v.createdAt > best.createdAt)
+                return v;
+            return best;
+        });
+    }
+}
+//# sourceMappingURL=experiment-variant-store.js.map

package/dist/agent/science/human-gate.d.ts

@@ -0,0 +1,31 @@
+/**
+ * AI-Scientist-lite — the fail-closed human gate primitive.
+ *
+ * Shared by the Phase 0 orchestrator (plan + publish gates) and the Phase 1
+ * empirical keep-gate. Extracted into its own module so both can REUSE the exact
+ * same fail-closed resolution (no reinvention, no import cycle). Only an explicit
+ * `approved === true` proceeds; a decline, timeout, throw, or any other shape is
+ * treated as a refusal.
+ *
+ * @module agent/science/human-gate
+ */
+/** A human gate decision. Only `approved === true` proceeds (fail closed). */
+export interface GateDecision {
+    approved: boolean;
+    /** Optional human-supplied reason / note. */
+    reason?: string;
+}
+/** What a gate presents to the human before they decide. */
+export interface HumanGatePrompt {
+    gate: 'plan' | 'publish' | 'keep';
+    title: string;
+    body: string;
+}
+/** A human-gate boundary. MAY throw / time out — the resolver fails closed. */
+export type HumanGateFn = (prompt: HumanGatePrompt) => Promise<GateDecision>;
+/**
+ * Resolve a human gate, defaulting to REFUSED. Only an explicit
+ * `approved === true` proceeds; a thrown error, timeout, or any other shape is
+ * treated as a decline (fail closed).
+ */
+export declare function resolveGate(fn: HumanGateFn, prompt: HumanGatePrompt): Promise<GateDecision>;

package/dist/agent/science/human-gate.js

@@ -0,0 +1,32 @@
+/**
+ * AI-Scientist-lite — the fail-closed human gate primitive.
+ *
+ * Shared by the Phase 0 orchestrator (plan + publish gates) and the Phase 1
+ * empirical keep-gate. Extracted into its own module so both can REUSE the exact
+ * same fail-closed resolution (no reinvention, no import cycle). Only an explicit
+ * `approved === true` proceeds; a decline, timeout, throw, or any other shape is
+ * treated as a refusal.
+ *
+ * @module agent/science/human-gate
+ */
+/**
+ * Resolve a human gate, defaulting to REFUSED. Only an explicit
+ * `approved === true` proceeds; a thrown error, timeout, or any other shape is
+ * treated as a decline (fail closed).
+ */
+export async function resolveGate(fn, prompt) {
+    try {
+        const decision = await fn(prompt);
+        if (decision && decision.approved === true) {
+            return { approved: true, ...(decision.reason ? { reason: decision.reason } : {}) };
+        }
+        return {
+            approved: false,
+            ...(decision && decision.reason ? { reason: decision.reason } : {}),
+        };
+    }
+    catch (err) {
+        return { approved: false, reason: `gate error (fail-closed): ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+//# sourceMappingURL=human-gate.js.map

package/dist/agent/self-improvement/authored-artifact-gate.js

@@ -11,8 +11,22 @@ import { matchAllDangerousPatterns } from '../../security/dangerous-patterns.js'
 const OMISSION_RE = /\/\/\s*\.\.\.\s*(rest|remaining|other|more|implementation|code)\b|#\s*\.\.\.\s*(rest|remaining)\b/i;
 /** Obvious secret shapes — never let an authored artifact embed these. */
 const SECRET_RE = /(sk-[a-z0-9]{16,}|api[_-]?key\s*[:=]\s*['"]?\S{12,}|-----BEGIN [A-Z ]*PRIVATE KEY-----|ghp_[a-zA-Z0-9]{20,}|AKIA[0-9A-Z]{16})/i;
-/** Writing under src/ is the hard self-modification invariant — refuse it. */
-const SRC_WRITE_RE = /(writeFile|writeFileSync|appendFile\w*|fs\.\w*write|open\s*\([^)]*['"]w|>>?\s*['"]?\.{0,2}\/?src\/)/i;
+/**
+ * Any filesystem-WRITE API. An authored tool's contract is "read input from
+ * env, print result to stdout" — it has no reason to write files. Flagging
+ * every write API (not just literal `src/` targets) closes the audited
+ * bypasses: string-split targets (`'sr'+'c'`), dynamic paths, and
+ * catastrophic non-src targets (`.git/hooks/pre-commit`, `~/.ssh/…`, the
+ * AuthoredToolStore JSON, a poisoned SKILL.md).
+ */
+const FS_WRITE_RE = /\b(writeFile|writeFileSync|appendFile\w*|createWriteStream|mkdir\w*|rename\w*|copyFile\w*|truncate\w*|chmod\w*|symlink\w*)\s*\(|\bfs\.\w*(write|append|open)\w*|\bopen\s*\([^)]*['"][wa]/i;
+/**
+ * Network egress. Env isolation already denies inherited secrets, but an
+ * authored compute tool has no reason to open the network — belt and braces
+ * against exfiltration. (This subsystem is authored tools only; the general
+ * execute_code tool does NOT pass through this gate.)
+ */
+const NETWORK_RE = /\bfetch\s*\(\s*['"`]https?:|\brequire\s*\(\s*['"`](?:https?|net|dgram|dns|tls)['"`]\)|\bimport\s*\(\s*['"`](?:node:)?(?:https?|net|dgram|dns|tls)['"`]\)|\bnew\s+WebSocket\b|\bXMLHttpRequest\b|\bnavigator\.sendBeacon\b/i;
 const MAX_CODE_BYTES = 64 * 1024;
 /**
  * Statically inspect authored code. Returns ok=false with one or more reasons on
@@ -34,7 +48,18 @@ export function inspectAuthoredCode(code, subsystem = 'code') {
         reasons.push('looks like it embeds a secret');
     if (OMISSION_RE.test(text))
         reasons.push('contains an omission placeholder (not self-contained)');
-    if (/src\//.test(text) && SRC_WRITE_RE.test(text)) {
+    // Authored tools (subsystem 'code') read input + print to stdout — no writes,
+    // no network. Skills use a different scanner (scanSkillFirewall) so keep the
+    // legacy src/-only write check for them to avoid changing that path.
+    if (subsystem === 'code') {
+        if (FS_WRITE_RE.test(text)) {
+            reasons.push('performs a filesystem write (authored tools must only read input + print to stdout)');
+        }
+        if (NETWORK_RE.test(text)) {
+            reasons.push('opens the network (authored tools must not make outbound requests)');
+        }
+    }
+    else if (/src\//.test(text) && /(writeFile|writeFileSync|appendFile\w*|fs\.\w*write)/i.test(text)) {
         reasons.push('writes under src/ (forbidden self-modification invariant)');
     }
     return { ok: reasons.length === 0, reasons };

package/dist/agent/self-improvement/authored-tool-runtime.d.ts

@@ -4,8 +4,10 @@
  * authored tool runs" so the thing we GATE is exactly the thing we REGISTER.
  *
  * An authored tool runs its `code` SANDBOXED: a throwaway cwd, RPC off (no
- * callback into the tool system), and its call arguments arrive as JSON in the
- * CODEBUDDY_TOOL_INPUT env var; the script prints its result to stdout.
+ * callback into the tool system), an ISOLATED environment (no inherited
+ * secrets, HOME redirected away from `~/.codebuddy`), and its call arguments
+ * arrive as JSON in the CODEBUDDY_TOOL_INPUT env var; the script prints its
+ * result to stdout.
  *
  * @module agent/self-improvement/authored-tool-runtime
  */

package/dist/agent/self-improvement/authored-tool-runtime.js

@@ -4,14 +4,17 @@
  * authored tool runs" so the thing we GATE is exactly the thing we REGISTER.
  *
  * An authored tool runs its `code` SANDBOXED: a throwaway cwd, RPC off (no
- * callback into the tool system), and its call arguments arrive as JSON in the
- * CODEBUDDY_TOOL_INPUT env var; the script prints its result to stdout.
+ * callback into the tool system), an ISOLATED environment (no inherited
+ * secrets, HOME redirected away from `~/.codebuddy`), and its call arguments
+ * arrive as JSON in the CODEBUDDY_TOOL_INPUT env var; the script prints its
+ * result to stdout.
  *
  * @module agent/self-improvement/authored-tool-runtime
  */
 import * as os from 'os';
 import * as path from 'path';
 import { randomUUID } from 'crypto';
+import fs from 'node:fs/promises';
 import { executeCode } from '../../tools/execute-code-runner.js';
 export const AUTHORED_PREFIX = 'authored__';
 export const AUTHORED_LANGUAGES = ['javascript', 'typescript', 'python'];
@@ -33,7 +36,14 @@ export function buildAuthoredTool(spec) {
         async execute(input) {
             const rootDir = path.join(os.tmpdir(), `cb-authored-${randomUUID()}`);
             try {
-                const res = await executeCode({ code, language, env: { CODEBUDDY_TOOL_INPUT: JSON.stringify(input ?? {}) } }, { rootDir, rpcEnabled: false });
+                await fs.mkdir(rootDir, { recursive: true, mode: 0o700 });
+                const source = language === 'typescript'
+                    ? (await import('typescript')).transpileModule(code, { compilerOptions: { module: 99, target: 9 } }).outputText
+                    : code;
+                const res = await executeCode({ code: source, language: language === 'typescript' ? 'javascript' : language, env: { CODEBUDDY_TOOL_INPUT: JSON.stringify(input ?? {}) } }, 
+                // envMode 'isolate' → the sandbox (used for BOTH pre-accept scoring
+                // and live calls) never inherits the host's secrets.
+                { rootDir, rpcEnabled: false, envMode: 'isolate', confinement: 'compute' });
                 if (!res.ok) {
                     return {
                         success: false,
@@ -48,6 +58,9 @@ export function buildAuthoredTool(spec) {
                     error: `authored tool "${name}" error: ${err instanceof Error ? err.message : String(err)}`,
                 };
             }
+            finally {
+                await fs.rm(rootDir, { recursive: true, force: true });
+            }
         },
         getSchema() {
             return { name, description, parameters: parameters };

package/dist/agent/self-improvement/authored-tool-store.js

@@ -8,6 +8,7 @@
  */
 import fs from 'fs';
 import path from 'path';
+import { readJsonAtomicSync, writeJsonAtomicSync } from '../../utils/atomic-write.js';
 export const AUTHORED_TOOL_STORE_SCHEMA_VERSION = 1;
 export class AuthoredToolStore {
     filePath;
@@ -20,7 +21,7 @@ export class AuthoredToolStore {
     }
     read() {
         try {
-            const parsed = JSON.parse(fs.readFileSync(this.filePath, 'utf-8'));
+            const parsed = readJsonAtomicSync(this.filePath, {}, { mode: 0o600 });
             if (Array.isArray(parsed.tools)) {
                 return { schemaVersion: AUTHORED_TOOL_STORE_SCHEMA_VERSION, tools: parsed.tools };
             }
@@ -32,7 +33,7 @@ export class AuthoredToolStore {
     }
     write(file) {
         fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
-        fs.writeFileSync(this.filePath, JSON.stringify(file, null, 2), 'utf-8');
+        writeJsonAtomicSync(this.filePath, file, { mode: 0o600 });
     }
     list() {
         return this.read().tools;

package/dist/agent/self-improvement/capability-benchmark.js

@@ -62,20 +62,107 @@ export const SEED_BENCHMARK_SCENARIOS = [
     {
         id: 'npm-test-path-filter',
         query: 'npm test',
-        expectIncludes: ['path filter', 'path/to', '--'],
+        expectIncludes: ['path filter', 'path/to'],
         description: 'Running the full test suite is slow; guidance should prefer a path filter.',
+        source: 'CLAUDE.md:27',
     },
     {
         id: 'esm-js-extension-imports',
         query: 'import',
-        expectIncludes: ['.js extension', 'esm', 'extension'],
+        expectIncludes: ['.js extension', 'esm'],
         description: 'ESM project needs .js extensions on relative imports even from .ts sources.',
+        source: 'CLAUDE.md:40',
     },
     {
         id: 'logger-not-console',
         query: 'console.log',
         expectIncludes: ['logger', 'not console'],
         description: 'Production code should use logger, not console.*, because tests spy on logger.',
+        source: 'CLAUDE.md:41',
+    },
+    {
+        id: 'atomic-write-state',
+        query: 'atomic-write',
+        expectIncludes: ['o_append', 'state write'],
+        description: 'State JSON and markdown files must use atomic-write.ts to prevent corrupt reads.',
+        source: 'CLAUDE.md:39',
+    },
+    {
+        id: 'git-add-named-files',
+        query: 'git add',
+        expectIncludes: ['nommément', 'jamais -a'],
+        description: 'Always stage files by specific name, never using git add -A or git commit -a.',
+        source: 'CLAUDE.md:11',
+    },
+    {
+        id: 'subproc-bounded-timeout',
+        query: 'wait_agent',
+        expectIncludes: ['with timeout', 'completion'],
+        description: 'Sub-agent processes and orchestrations must be bounded with an explicit timeout.',
+        source: 'docs/agents.md:11',
+    },
+    {
+        id: 'no-secrets-in-repo',
+        query: 'jwt_secret',
+        expectIncludes: ['secret in clair', 'secretref'],
+        description: 'Never store plaintext secrets or tokens in tracked repository files.',
+        source: 'CLAUDE.md:12',
+    },
+    {
+        id: 'isolated-home-tests',
+        query: '_qa/',
+        expectIncludes: ['home isolé', 'gitignoré'],
+        description: 'Integration and CLI tests must run with an isolated QA home directory.',
+        source: 'CLAUDE.md:13',
+    },
+    {
+        id: 'str-replace-omission-block',
+        query: 'str_replace',
+        expectIncludes: ['omission placeholder', 'rest of code'],
+        description: 'Use str_replace with exact matching and never leave omission placeholders like rest of code.',
+        source: 'CLAUDE.md:210',
+    },
+    {
+        id: 'verify-before-finishing',
+        query: 'verificationenforcement',
+        expectIncludes: ['verify before finishing', 'file changes'],
+        description: 'Always verify changes with targeted test runs before considering a task finished.',
+        source: 'CLAUDE.md:99',
+    },
+    {
+        id: 'report-before-inspection',
+        query: 'docs/reports',
+        expectIncludes: ['rapport créé avant', 'avant toute inspection'],
+        description: 'Create the mission repair report before starting code inspection.',
+        source: 'CLAUDE.md:10',
+    },
+    {
+        id: 'tests-live-in-tests-only',
+        query: 'vitest.config',
+        expectIncludes: ['tests/ only', 'in-source'],
+        description: 'All test files must reside under tests/ directory, never in-source inside src/.',
+        source: 'CLAUDE.md:35',
+    },
+    {
+        id: 'self-improvement-never-touch-src',
+        query: 'self-improvement',
+        expectIncludes: ['reversible learnable', 'never edits src'],
+        description: 'Self-improvement engine operates strictly on reversible layers, never modifying src/ directly.',
+        source: 'CLAUDE.md:119',
+    },
+    {
+        id: 'peer-tool-fails-closed',
+        query: 'peer.tool.invoke',
+        expectIncludes: ['peer_workspace_not_configured', 'fails closed'],
+        description: 'Peer tool invocation fails closed if peer tool workspace root is not configured.',
+        source: 'CLAUDE.md:139',
+    },
+    {
+        id: 'batch-anti-tautology-guard',
+        query: '/batch',
+        expectIncludes: ['anti-tautology', 'no files changed'],
+        description: 'Batch execution enforces an anti-tautology guard rejecting write units that change no files.',
+        source: 'docs/agents.md:119',
     },
 ];
 //# sourceMappingURL=capability-benchmark.js.map

package/dist/agent/self-improvement/continuous-benchmark.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Opt-in continuous capability benchmark for active LLM models.
+ *
+ * This module deliberately reuses the curated scenarios and scoring primitive
+ * from `capability-benchmark.ts`. It has no scheduler: P0 is invoked only by
+ * `buddy improve bench` (or an explicit programmatic call with the opt-in env).
+ *
+ * @module agent/self-improvement/continuous-benchmark
+ */
+import { type OutcomeRecord } from '../../fleet/model-scoreboard.js';
+import { type ActiveLlmModelPoolEntry } from '../../providers/active-llm-model-pool.js';
+import type { BenchmarkScenario } from './types.js';
+export declare const CONTINUOUS_BENCHMARK_VERSION = "1";
+export declare const DEFAULT_SELF_BENCH_TIMEOUT_MS = 60000;
+export declare const DEFAULT_SELF_BENCH_DROP = 0.15;
+export declare const SELF_BENCH_MOVING_WINDOW = 5;
+export interface BenchmarkHistoryEntry {
+    /** Added by this runner; optional so older/minimal spec-shaped ledgers remain readable. */
+    runId?: string;
+    model: string;
+    provider?: string;
+    scenario: string;
+    score: number;
+    latencyMs: number;
+    ts: string;
+    benchVersion: string;
+    status?: 'ok' | 'timeout' | 'error';
+}
+export interface BenchmarkRegression {
+    model: string;
+    before: number;
+    after: number;
+    /** Relative decrease: `(before - after) / before`. */
+    drop: number;
+}
+export interface BenchmarkRunSummary {
+    runId: string;
+    model: string;
+    provider: string;
+    ts: string;
+    score: number;
+    latencyMs: number;
+    scenarios: number;
+}
+export interface BenchmarkLlmRequest {
+    candidate: ActiveLlmModelPoolEntry;
+    scenario: BenchmarkScenario;
+    prompt: string;
+    signal: AbortSignal;
+}
+/** Minimal injectable seam: tests never need to construct a real provider client. */
+export interface BenchmarkLlmClient {
+    chat(request: BenchmarkLlmRequest): Promise<unknown>;
+}
+export type BenchmarkLlmClientFactory = (candidate: ActiveLlmModelPoolEntry) => BenchmarkLlmClient | Promise<BenchmarkLlmClient>;
+export interface BenchmarkScoreboardPort {
+    recordOutcome(record: OutcomeRecord): void;
+}
+export interface RunBenchmarkOptions {
+    models?: string | string[];
+    provider?: string;
+    scenarios?: number;
+    env?: Record<string, string | undefined>;
+    /** One injected client can dispatch on `request.candidate`. */
+    client?: BenchmarkLlmClient;
+    /** Or create a dedicated client per active provider/model. */
+    clientFactory?: BenchmarkLlmClientFactory;
+    /** Hermetic pool seam for tests; production always uses the active pool. */
+    modelPool?: ActiveLlmModelPoolEntry[];
+    scoreboard?: BenchmarkScoreboardPort;
+    now?: () => Date;
+    monotonicNow?: () => number;
+    runId?: string;
+}
+export interface BenchmarkModelResult extends BenchmarkRunSummary {
+    entries: BenchmarkHistoryEntry[];
+}
+export interface ContinuousBenchmarkResult {
+    runId: string;
+    historyPath: string;
+    models: BenchmarkModelResult[];
+    regressions: BenchmarkRegression[];
+}
+export interface BenchmarkReport {
+    latest: BenchmarkRunSummary[];
+    regressions: BenchmarkRegression[];
+    recommendation: string;
+}
+/** Resolve the append-only history path without reading or creating it. */
+export declare function resolveBenchmarkHistoryPath(env?: Record<string, string | undefined>): string;
+/** Read the append-only history, ignoring a torn/corrupt final line. */
+export declare function readBenchmarkHistory(env?: Record<string, string | undefined>): Promise<BenchmarkHistoryEntry[]>;
+/** Aggregate the per-scenario JSONL records into model runs. */
+export declare function aggregateBenchmarkRuns(history: readonly BenchmarkHistoryEntry[]): BenchmarkRunSummary[];
+/**
+ * Pure regression detector. For each model, compare its latest aggregate run
+ * with the mean of up to five immediately preceding runs.
+ */
+export declare function detectRegressions(history: readonly BenchmarkHistoryEntry[], threshold?: number): BenchmarkRegression[];
+/** Build the latest state and a routing recommendation from history. */
+export declare function createBenchmarkReport(history: readonly BenchmarkHistoryEntry[], threshold?: number): BenchmarkReport;
+/** Render one simple ASCII bar per model/run, suitable for `--history`. */
+export declare function renderBenchmarkHistory(history: readonly BenchmarkHistoryEntry[], model?: string): string;
+/** Execute the curated capability scenarios against every selected active model. */
+export declare function runBenchmark(options?: RunBenchmarkOptions): Promise<ContinuousBenchmarkResult>;