@open-cr-agent/cli 0.2.0 → 0.3.0

package/dist/memory.js

@@ -2,8 +2,8 @@ import { constants, existsSync } from "node:fs";
 import { lstat, mkdir, open, readdir, readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { parseArgs } from "node:util";
-import { MEMORY_PATH, parseMemory, serializeMemory, } from "@open-cr-agent/core";
-import { findRepositoryRoot } from "@open-cr-agent/vcs-local";
+import { MEMORY_PATH, parseMemory, serializeMemory } from "@open-cr-agent/core/internal";
+import { findRepositoryRoot } from "@open-cr-agent/vcs-local/internal";
 import { UsageError } from "./review/args.js";
 import { SESSIONS_DIR } from "./review/command.js";
 import { forTerminal } from "./review/terminal.js";

package/dist/metrics.d.ts

@@ -0,0 +1,47 @@
+import { type Severity, type Verification } from "@open-cr-agent/core";
+import type { Output } from "./review/progress.js";
+export declare const METRICS_VERSION = 1;
+export declare const METRICS_USAGE = "Usage: ocra metrics [options]\n\nCounts over the finished reviews in .ocra/sessions: runs, cost, findings,\nwhat reviewers later fixed or dismissed, per reviewer. Reads each session's\nreport.json (report version 1); nothing calls a model.\n\nOptions:\n  --sessions <dir>     Sessions directory (default: .ocra/sessions of this repository)\n  --since <date>       Only runs started at or after this ISO 8601 date\n  --format <text|json> Output format (default: text); the JSON carries \"version\": 1\n  -h, --help           Show help\n";
+export interface ReviewerMetrics {
+    tasks: number;
+    failedTasks: number;
+    findings: number;
+    costUsd: number;
+    fixed: number;
+    dismissed: number;
+    acceptanceRate: number | null;
+}
+export interface Metrics {
+    version: typeof METRICS_VERSION;
+    sessionsDir: string;
+    since?: string;
+    runs: {
+        total: number;
+        byVerdict: Record<string, number>;
+        incomplete: number;
+        unreadable: number;
+    };
+    cost: {
+        usd: number;
+        inputTokens: number;
+        outputTokens: number;
+        usdPerRun: number | null;
+    };
+    findings: {
+        reported: number;
+        unique: number;
+        bySeverity: Record<Severity, number>;
+        byVerification: Record<Verification, number>;
+    };
+    outcomes: {
+        fixed: number;
+        dismissed: number;
+        acceptanceRate: number | null;
+    };
+    reviewers: Record<string, ReviewerMetrics>;
+}
+export declare function metricsCommand(argv: string[], out: Output, cwd: string): Promise<number>;
+export declare function sessionStart(id: string): Date | undefined;
+export declare function collectMetrics(sessionsDir: string, since?: Date): Promise<Metrics>;
+export declare function renderMetrics(m: Metrics): string;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.js

@@ -0,0 +1,227 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { reportOutputSchema, } from "@open-cr-agent/core";
+import { findRepositoryRoot } from "@open-cr-agent/vcs-local/internal";
+import { UsageError } from "./review/args.js";
+import { SESSIONS_DIR } from "./review/command.js";
+import { forTerminal } from "./review/terminal.js";
+export const METRICS_VERSION = 1;
+export const METRICS_USAGE = `Usage: ocra metrics [options]
+
+Counts over the finished reviews in ${SESSIONS_DIR}: runs, cost, findings,
+what reviewers later fixed or dismissed, per reviewer. Reads each session's
+report.json (report version 1); nothing calls a model.
+
+Options:
+  --sessions <dir>     Sessions directory (default: ${SESSIONS_DIR} of this repository)
+  --since <date>       Only runs started at or after this ISO 8601 date
+  --format <text|json> Output format (default: text); the JSON carries "version": ${METRICS_VERSION}
+  -h, --help           Show help
+`;
+export async function metricsCommand(argv, out, cwd) {
+    const { values } = parseArgs({
+        args: argv,
+        allowPositionals: false,
+        strict: true,
+        options: {
+            sessions: { type: "string" },
+            since: { type: "string" },
+            format: { type: "string" },
+            help: { type: "boolean", short: "h" },
+        },
+    });
+    if (values.help) {
+        out.write(METRICS_USAGE);
+        return 0;
+    }
+    const format = values.format ?? "text";
+    if (format !== "text" && format !== "json")
+        throw new UsageError("--format must be text or json");
+    const since = values.since === undefined ? undefined : parseSince(values.since);
+    const sessionsDir = values.sessions
+        ? resolve(cwd, values.sessions)
+        : join(await findRepositoryRoot(cwd), SESSIONS_DIR);
+    const metrics = await collectMetrics(sessionsDir, since);
+    out.write(format === "json" ? `${JSON.stringify(metrics, null, 2)}\n` : renderMetrics(metrics));
+    return 0;
+}
+function parseSince(text) {
+    const date = new Date(text);
+    if (Number.isNaN(date.getTime()))
+        throw new UsageError(`--since needs an ISO 8601 date, not "${text}"`);
+    return date;
+}
+// A session directory is named by its run id, whose first part is the start
+// time (newRunId in core); that is what --since compares against.
+export function sessionStart(id) {
+    const m = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z/.exec(id);
+    if (!m)
+        return undefined;
+    const [, y, mo, d, h, mi, s] = m;
+    return new Date(`${y}-${mo}-${d}T${h}:${mi}:${s}Z`);
+}
+export async function collectMetrics(sessionsDir, since) {
+    const names = (await readdir(sessionsDir).catch(() => []))
+        .filter((n) => !n.startsWith("."))
+        .filter((n) => {
+        const start = sessionStart(n);
+        return since === undefined || (start !== undefined && start >= since);
+    })
+        .sort();
+    const reports = [];
+    let unreadable = 0;
+    for (const name of names) {
+        const report = await readReport(join(sessionsDir, name, "report.json"));
+        if (report)
+            reports.push(report);
+        else
+            unreadable += 1;
+    }
+    return aggregate(reports, {
+        sessionsDir,
+        unreadable,
+        ...(since ? { since: since.toISOString() } : {}),
+    });
+}
+async function readReport(path) {
+    let data;
+    try {
+        data = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    const parsed = reportOutputSchema.safeParse(data);
+    return parsed.success ? parsed.data : undefined;
+}
+function aggregate(reports, meta) {
+    const byVerdict = {};
+    const bySeverity = { critical: 0, warning: 0, suggestion: 0 };
+    const byVerification = { confirmed: 0, uncertain: 0, unchecked: 0 };
+    const reviewers = new Map();
+    const reviewerOf = new Map();
+    const unique = new Set();
+    const fixed = new Set();
+    const dismissed = new Set();
+    let incomplete = 0;
+    let reported = 0;
+    let usd = 0;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    const forReviewer = (id) => {
+        let r = reviewers.get(id);
+        if (!r) {
+            r = {
+                tasks: 0,
+                failedTasks: 0,
+                findings: 0,
+                costUsd: 0,
+                fixed: 0,
+                dismissed: 0,
+                acceptanceRate: null,
+            };
+            reviewers.set(id, r);
+        }
+        return r;
+    };
+    for (const report of reports) {
+        byVerdict[report.verdict] = (byVerdict[report.verdict] ?? 0) + 1;
+        if (report.coverage.some((c) => c.status === "failed" || c.status === "unreviewed"))
+            incomplete += 1;
+        usd += report.usage.costUsd;
+        inputTokens += report.usage.inputTokens;
+        outputTokens += report.usage.outputTokens;
+        for (const task of report.tasks) {
+            const r = forReviewer(task.reviewer);
+            r.tasks += 1;
+            if (task.status === "failed" || task.status === "timed_out")
+                r.failedTasks += 1;
+            r.costUsd += task.usage.costUsd;
+        }
+        for (const finding of report.findings) {
+            reported += 1;
+            unique.add(finding.fingerprint);
+            bySeverity[finding.severity] += 1;
+            byVerification[finding.verification] += 1;
+            forReviewer(finding.reviewer).findings += 1;
+            if (!reviewerOf.has(finding.fingerprint))
+                reviewerOf.set(finding.fingerprint, finding.reviewer);
+        }
+        for (const f of report.rereview?.fixed ?? [])
+            fixed.add(f.fingerprint);
+        for (const f of report.rereview?.dismissed ?? [])
+            dismissed.add(f.fingerprint);
+    }
+    // A fingerprint can be dismissed in one review and gone in a later one:
+    // the reviewer's decision stands.
+    for (const fp of dismissed)
+        fixed.delete(fp);
+    for (const fp of fixed) {
+        const reviewer = reviewerOf.get(fp);
+        if (reviewer)
+            forReviewer(reviewer).fixed += 1;
+    }
+    for (const fp of dismissed) {
+        const reviewer = reviewerOf.get(fp);
+        if (reviewer)
+            forReviewer(reviewer).dismissed += 1;
+    }
+    for (const r of reviewers.values())
+        r.acceptanceRate = rate(r.fixed, r.dismissed);
+    return {
+        version: METRICS_VERSION,
+        sessionsDir: meta.sessionsDir,
+        ...(meta.since ? { since: meta.since } : {}),
+        runs: { total: reports.length, byVerdict, incomplete, unreadable: meta.unreadable },
+        cost: {
+            usd,
+            inputTokens,
+            outputTokens,
+            usdPerRun: reports.length > 0 ? usd / reports.length : null,
+        },
+        findings: { reported, unique: unique.size, bySeverity, byVerification },
+        outcomes: {
+            fixed: fixed.size,
+            dismissed: dismissed.size,
+            acceptanceRate: rate(fixed.size, dismissed.size),
+        },
+        reviewers: Object.fromEntries([...reviewers].sort(([a], [b]) => a.localeCompare(b))),
+    };
+}
+function rate(fixed, dismissed) {
+    return fixed + dismissed > 0 ? fixed / (fixed + dismissed) : null;
+}
+const percent = (value) => (value === null ? "n/a" : `${Math.round(value * 100)}%`);
+const dollars = (value) => (value === null ? "n/a" : `$${value.toFixed(2)}`);
+export function renderMetrics(m) {
+    const lines = [
+        `Runs: ${m.runs.total}${m.since ? ` since ${m.since}` : ""} (${m.runs.incomplete} incomplete, ${m.runs.unreadable} unreadable)`,
+        `  by verdict: ${entries(m.runs.byVerdict)}`,
+        `Cost: ${dollars(m.cost.usd)} total, ${dollars(m.cost.usdPerRun)} per run · ${m.cost.inputTokens} in / ${m.cost.outputTokens} out tokens`,
+        `Findings: ${m.findings.reported} reported, ${m.findings.unique} unique`,
+        `  by severity: ${entries(m.findings.bySeverity)}`,
+        `  by verification: ${entries(m.findings.byVerification)}`,
+        `Outcomes: ${m.outcomes.fixed} fixed, ${m.outcomes.dismissed} dismissed, acceptance ${percent(m.outcomes.acceptanceRate)}`,
+        "",
+        "Reviewer           Tasks  Failed  Findings  Cost      Fixed  Dismissed  Acceptance",
+    ];
+    for (const [id, r] of Object.entries(m.reviewers)) {
+        lines.push([
+            id.padEnd(18),
+            String(r.tasks).padStart(5),
+            String(r.failedTasks).padStart(7),
+            String(r.findings).padStart(9),
+            dollars(r.costUsd).padStart(9),
+            String(r.fixed).padStart(6),
+            String(r.dismissed).padStart(10),
+            percent(r.acceptanceRate).padStart(11),
+        ].join(" "));
+    }
+    return `${forTerminal(lines.join("\n"))}\n`;
+}
+function entries(record) {
+    const parts = Object.entries(record).filter(([, n]) => n > 0);
+    return parts.length === 0 ? "none" : parts.map(([k, n]) => `${k} ${n}`).join(", ");
+}
+//# sourceMappingURL=metrics.js.map

package/dist/review/args.d.ts

@@ -1,3 +1,4 @@
+import { OcraError } from "@open-cr-agent/core";
 import type { LocalTarget } from "@open-cr-agent/vcs-local";
 export type OutputFormat = "text" | "json" | "sarif";
 export interface PullRequestTarget {
@@ -22,9 +23,14 @@ export interface ReviewArgs {
     ultra?: true;
     full?: true;
     plan?: true;
+    importSarif?: string[];
+    configFile?: string;
+    temperature?: number;
+    seed?: number;
 }
-export declare class UsageError extends Error {
+export declare class UsageError extends OcraError {
+    constructor(message: string);
 }
-export declare const REVIEW_USAGE = "Usage: ocra review [options]\n\nReviews uncommitted changes by default.\n\nOptions:\n  --from <ref>       Review changes on --to since it diverged from <ref>\n  --to <ref>         End of the range (default: HEAD)\n  --commit <sha>     Review a single commit\n  --pr <number>      Review a GitHub pull request (needs GITHUB_TOKEN)\n  --repo <owner/name>  Repository of --pr (default: GITHUB_REPOSITORY or origin)\n  --mr <iid>         Review a GitLab merge request (needs GITLAB_TOKEN)\n  --project <id|path>  Project of --mr (default: CI_PROJECT_ID or origin)\n  --publish          With --pr or --mr: post the review to it\n  --full             With --pr or --mr: review every file, not only what\n                     changed since the previous review\n  --format <format>  text (default), json, or sarif (SARIF 2.1.0; not with --plan)\n  --output <file>    Write the result to a file instead of stdout\n  --reviewers <ids>  Run only these reviewers (comma-separated)\n  --max-cost-usd <n> Spend limit: reviews use 80%, verification and judging the rest\n  --plan             Show files, bundles, review tasks and prompt sizes; call no model\n  --ultra            Favor recall: all reviewers at every tier, two samples each (about 2x cost)\n  --no-repo-config   Ignore .ocra/config.json and its plugins (for untrusted\n                     code); models come from OCRA_MODEL_* variables\n  -h, --help         Show help\n";
+export declare const REVIEW_USAGE = "Usage: ocra review [options]\n\nReviews uncommitted changes by default.\n\nOptions:\n  --from <ref>       Review changes on --to since it diverged from <ref>\n  --to <ref>         End of the range (default: HEAD)\n  --commit <sha>     Review a single commit\n  --pr <number>      Review a GitHub pull request (needs GITHUB_TOKEN)\n  --repo <owner/name>  Repository of --pr (default: GITHUB_REPOSITORY or origin)\n  --mr <iid>         Review a GitLab merge request (needs GITLAB_TOKEN)\n  --project <id|path>  Project of --mr (default: CI_PROJECT_ID or origin)\n  --publish          With --pr or --mr: post the review to it\n  --full             With --pr or --mr: review every file, not only what\n                     changed since the previous review\n  --format <format>  text (default), json, or sarif (SARIF 2.1.0; not with --plan)\n  --output <file>    Write the result to a file instead of stdout\n  --reviewers <ids>  Run only these reviewers (comma-separated)\n  --max-cost-usd <n> Spend limit: reviews use 80%, verification and judging the rest\n  --import-sarif <file>  Add the results of a SARIF 2.1.0 log (Semgrep, CodeQL, \u2026)\n                     that fall on the change; repeatable; not with --plan\n  --plan             Show files, bundles, review tasks and prompt sizes; call no model\n  --ultra            Favor recall: all reviewers at every tier, two samples each (about 2x cost)\n  --temperature <n>  Sampling temperature, 0 to 2 (default: the provider's, or sampling in config)\n  --seed <n>         Sampling seed, where the runtime and provider support one\n  --config <file>    Read this configuration file instead of the repository's\n                     .ocra/config.json; it applies with --no-repo-config too\n  --no-repo-config   Ignore .ocra/config.json and its plugins (for untrusted\n                     code); models come from OCRA_MODEL_* variables or --config\n  -h, --help         Show help\n";
 export declare function parseReviewArgs(argv: string[]): ReviewArgs | "help";
 //# sourceMappingURL=args.d.ts.map

package/dist/review/args.js

@@ -1,5 +1,10 @@
 import { parseArgs } from "node:util";
-export class UsageError extends Error {
+import { OcraError } from "@open-cr-agent/core";
+export class UsageError extends OcraError {
+    constructor(message) {
+        super("INPUT_USAGE", message);
+        this.name = "UsageError";
+    }
 }
 export const REVIEW_USAGE = `Usage: ocra review [options]
 
@@ -20,10 +25,16 @@ Options:
   --output <file>    Write the result to a file instead of stdout
   --reviewers <ids>  Run only these reviewers (comma-separated)
   --max-cost-usd <n> Spend limit: reviews use 80%, verification and judging the rest
+  --import-sarif <file>  Add the results of a SARIF 2.1.0 log (Semgrep, CodeQL, …)
+                     that fall on the change; repeatable; not with --plan
   --plan             Show files, bundles, review tasks and prompt sizes; call no model
   --ultra            Favor recall: all reviewers at every tier, two samples each (about 2x cost)
+  --temperature <n>  Sampling temperature, 0 to 2 (default: the provider's, or sampling in config)
+  --seed <n>         Sampling seed, where the runtime and provider support one
+  --config <file>    Read this configuration file instead of the repository's
+                     .ocra/config.json; it applies with --no-repo-config too
   --no-repo-config   Ignore .ocra/config.json and its plugins (for untrusted
-                     code); models come from OCRA_MODEL_* variables
+                     code); models come from OCRA_MODEL_* variables or --config
   -h, --help         Show help
 `;
 export function parseReviewArgs(argv) {
@@ -79,6 +90,30 @@ export function parseReviewArgs(argv) {
             throw new UsageError(`--max-cost-usd must be a positive number, got ${values["max-cost-usd"]}`);
         args.maxCostUsd = max;
     }
+    if (values.temperature !== undefined) {
+        const temperature = Number(values.temperature);
+        if (values.temperature.trim() === "" || !(temperature >= 0 && temperature <= 2)) {
+            throw new UsageError(`--temperature must be a number from 0 to 2, got ${values.temperature}`);
+        }
+        args.temperature = temperature;
+    }
+    if (values.seed !== undefined) {
+        const seed = Number(values.seed);
+        if (!/^\d+$/.test(values.seed) || seed > 2 ** 31 - 1) {
+            throw new UsageError(`--seed must be a whole number from 0 to 2147483647, got ${values.seed}`);
+        }
+        args.seed = seed;
+    }
+    if (values.config !== undefined) {
+        if (values.config === "")
+            throw new UsageError("--config needs a file");
+        args.configFile = values.config;
+    }
+    if (values["import-sarif"] !== undefined && values["import-sarif"].length > 0) {
+        if (values.plan)
+            throw new UsageError("--import-sarif is not used by --plan");
+        args.importSarif = values["import-sarif"];
+    }
     if (values.reviewers !== undefined) {
         const ids = values.reviewers
             .split(",")
@@ -102,9 +137,13 @@ function parse(argv) {
             format: { type: "string" },
             output: { type: "string" },
             "no-repo-config": { type: "boolean" },
+            config: { type: "string" },
             reviewers: { type: "string" },
             "max-cost-usd": { type: "string" },
+            "import-sarif": { type: "string", multiple: true },
             ultra: { type: "boolean" },
+            temperature: { type: "string" },
+            seed: { type: "string" },
             full: { type: "boolean" },
             plan: { type: "boolean" },
             pr: { type: "string" },

package/dist/review/command.d.ts

@@ -1,6 +1,7 @@
 import { type OcraPlugin } from "@open-cr-agent/core";
 import type { ReviewArgs } from "./args.js";
 import { type Output } from "./progress.js";
+import type { RuntimeLoaders } from "./runtimes.js";
 export declare const SESSIONS_DIR = ".ocra/sessions";
 export declare const EXIT: {
     readonly ok: 0;
@@ -14,6 +15,7 @@ export interface ReviewDeps {
     cwd: string;
     env: Readonly<Record<string, string | undefined>>;
     builtinPlugins: readonly OcraPlugin[];
+    runtimes: RuntimeLoaders;
     writeFile(path: string, content: string): Promise<void>;
     now(): number;
     heartbeatMs: number;

package/dist/review/command.js

@@ -1,15 +1,18 @@
 import { join, relative, resolve } from "node:path";
-import { agentsMdReviewerPlugin, correctnessReviewerPlugin, coverageGaps, defaultSelectionPolicy, docsReviewerPlugin, newSessionId, performanceReviewerPlugin, previewReview, runReview, securityReviewerPlugin, sessionJsonlPlugin, startPlugins, toPlanOutput, } from "@open-cr-agent/core";
-import { opencodeRuntimePlugin } from "@open-cr-agent/runtime-opencode";
+import { agentsMdReviewerPlugin, correctnessReviewerPlugin, coverageGaps, docsReviewerPlugin, performanceReviewerPlugin, review, securityReviewerPlugin, sessionJsonlPlugin, startPlugins, } from "@open-cr-agent/core";
+import { defaultSelectionPolicy, newRunId, previewReview, toPlanOutput, } from "@open-cr-agent/core/internal";
 import { githubPlugin } from "@open-cr-agent/vcs-github";
 import { gitlabPlugin } from "@open-cr-agent/vcs-gitlab";
-import { findRepositoryRoot, localGitPlugin } from "@open-cr-agent/vcs-local";
+import { localGitPlugin } from "@open-cr-agent/vcs-local";
+import { findRepositoryRoot } from "@open-cr-agent/vcs-local/internal";
 import { VERSION } from "../version.js";
 import { ConfigError } from "./config.js";
 import { renderPlan } from "./plan-render.js";
 import { ProgressPrinter } from "./progress.js";
+import { configHash, requestedSampling } from "./provenance.js";
 import { renderJson, renderText, safeJson } from "./render.js";
 import { renderSarif } from "./sarif.js";
+import { loadSarifLogs } from "./sarif-input.js";
 import { localTarget, mergeRequestTarget, pullRequestTarget } from "./target.js";
 import { forTerminal } from "./terminal.js";
 export const SESSIONS_DIR = ".ocra/sessions";
@@ -18,7 +21,6 @@ export const BUILTIN_PLUGINS = [
     localGitPlugin,
     githubPlugin,
     gitlabPlugin,
-    opencodeRuntimePlugin,
     correctnessReviewerPlugin,
     securityReviewerPlugin,
     performanceReviewerPlugin,
@@ -30,17 +32,20 @@ export async function reviewCommand(args, io, deps) {
     const root = await findRepositoryRoot(deps.cwd);
     const warn = (message) => io.err.write(`[ocra] Warning: ${forTerminal(message)}\n`);
     const ignoreRepoConfig = args.ignoreRepoConfig === true;
+    const configFile = args.configFile ? resolve(deps.cwd, args.configFile) : undefined;
+    const localArgs = configFile ? { ...args, configFile } : args;
     const target = args.pullRequest
-        ? await pullRequestTarget(args.pullRequest, deps.cwd, root, deps.env, warn, deps.fetch, ignoreRepoConfig)
+        ? await pullRequestTarget(args.pullRequest, deps.cwd, root, deps.env, warn, deps.fetch, ignoreRepoConfig, configFile)
         : args.mergeRequest
-            ? await mergeRequestTarget(args.mergeRequest, deps.cwd, root, deps.env, warn, deps.fetch, ignoreRepoConfig)
-            : await localTarget(args, deps.cwd, root, deps.env, warn, deps.fetch);
+            ? await mergeRequestTarget(args.mergeRequest, deps.cwd, root, deps.env, warn, deps.fetch, ignoreRepoConfig, configFile)
+            : await localTarget(localArgs, deps.cwd, root, deps.env, warn, deps.fetch);
     const { config } = target;
-    const session = { dir: join(root, SESSIONS_DIR), id: newSessionId() };
-    // A plan calls no model and writes no session log.
+    const session = { dir: join(root, SESSIONS_DIR), id: newRunId() };
+    // A plan calls no model, writes no session log and imports no runtime: it
+    // works without the optional runtime-opencode.
     const builtins = args.plan
         ? deps.builtinPlugins.filter((p) => p.name !== sessionJsonlPlugin.name)
-        : deps.builtinPlugins;
+        : [...deps.builtinPlugins, ...(await builtinRuntime(deps.runtimes, config.runtime))];
     const registry = await startPlugins([...builtins, ...target.plugins], {
         settings: args.plan
             ? config.pluginSettings
@@ -68,10 +73,13 @@ export async function reviewCommand(args, io, deps) {
             await deps.writeFile(resolve(deps.cwd, args.output), rendered);
         return EXIT.ok;
     }
+    const sarif = await loadSarifLogs(args.importSarif ?? [], deps.cwd);
+    const sampling = requestedSampling(config, args);
     const runtime = registry.createRuntime(config.runtime, {
         models: config.models,
         env: deps.env,
         providers: config.providers,
+        ...(Object.keys(sampling).length > 0 ? { sampling } : {}),
     });
     const progress = new ProgressPrinter(io.err, { heartbeatMs: deps.heartbeatMs, now: deps.now });
     const interrupt = new AbortController();
@@ -81,13 +89,16 @@ export async function reviewCommand(args, io, deps) {
     });
     let report;
     try {
-        report = await runReview({
+        report = await review({
+            runId: session.id,
             signal: interrupt.signal,
             ...runOptions(config),
             reviewerOverrides: overrides,
+            provenance: { ocraVersion: VERSION, configHash: configHash(config, args), sampling },
             ...(args.maxCostUsd !== undefined ? { maxCostUsd: args.maxCostUsd } : {}),
             ...(args.ultra ? { ultra: true } : {}),
             ...(args.full ? { fullReview: true } : {}),
+            ...(sarif.length > 0 ? { sarif } : {}),
             ...(target.readTrusted ? { readTrusted: target.readTrusted } : {}),
             vcs,
             runtime,
@@ -137,6 +148,11 @@ export async function reviewCommand(args, io, deps) {
     }
     return exitCode(report, io.err);
 }
+// A runtime not built in comes from a plugin of the configuration.
+async function builtinRuntime(runtimes, name) {
+    const load = Object.hasOwn(runtimes, name) ? runtimes[name] : undefined;
+    return load ? [await load()] : [];
+}
 function runOptions(config) {
     const options = {
         selection: { ...defaultSelectionPolicy, include: config.include, exclude: config.exclude },

package/dist/review/config.d.ts

@@ -1,7 +1,8 @@
-import { type CustomProvider, type ModelChains, type RepoRule } from "@open-cr-agent/core";
+import { type CustomProvider, type ModelChains, OcraError, type RepoRule } from "@open-cr-agent/core";
 import { z } from "zod";
 export declare const CONFIG_PATH = ".ocra/config.json";
 declare const configSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
     models: z.ZodDefault<z.ZodObject<{
         top: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<string[], string | string[]>>>;
         standard: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<string[], string | string[]>>>;
@@ -14,13 +15,20 @@ declare const configSchema: z.ZodObject<{
     judge: z.ZodOptional<z.ZodBoolean>;
     maxCostUsd: z.ZodOptional<z.ZodNumber>;
     maxTasks: z.ZodOptional<z.ZodNumber>;
+    sampling: z.ZodOptional<z.ZodObject<{
+        temperature: z.ZodOptional<z.ZodNumber>;
+        seed: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
     github: z.ZodDefault<z.ZodObject<{
         requestChanges: z.ZodOptional<z.ZodBoolean>;
         botLogin: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     include: z.ZodDefault<z.ZodArray<z.ZodString>>;
     exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
-    runtime: z.ZodDefault<z.ZodString>;
+    runtime: z.ZodDefault<z.ZodUnion<[z.ZodEnum<{
+        direct: "direct";
+        opencode: "opencode";
+    }>, z.ZodString]>>;
     plugins: z.ZodDefault<z.ZodArray<z.ZodString>>;
     reviewers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
@@ -43,6 +51,8 @@ declare const configSchema: z.ZodObject<{
     }, z.core.$strict>>>;
     extends: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
+export declare const CONFIG_SCHEMA_ID = "https://ocra.majincheng.com/schema/config.v1.json";
+export declare function configJsonSchema(): Record<string, unknown>;
 export type CliConfig = Omit<z.infer<typeof configSchema>, "models" | "providers"> & {
     models: ModelChains;
     providers: Record<string, CustomProvider>;
@@ -51,10 +61,14 @@ export type CliConfig = Omit<z.infer<typeof configSchema>, "models" | "providers
 export interface LoadOptions {
     repository: boolean;
     read?: (path: string) => Promise<string | undefined>;
+    file?: string;
     fetch?: typeof fetch;
     warn?: (message: string) => void;
 }
-export declare class ConfigError extends Error {
+export declare class ConfigError extends OcraError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
 }
 export declare function loadConfig(root: string, env: Readonly<Record<string, string | undefined>>, options?: LoadOptions): Promise<CliConfig>;
 export {};

package/dist/review/config.js

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { RISK_TIERS, } from "@open-cr-agent/core";
+import { OcraError, } from "@open-cr-agent/core";
+import { RISK_TIERS } from "@open-cr-agent/core/internal";
 import { z } from "zod";
 import { fetchRemoteConfig, mergeConfig } from "./remote-config.js";
 export const CONFIG_PATH = ".ocra/config.json";
@@ -41,8 +42,12 @@ const providerSchema = z
         .refine((models) => Object.keys(models).length > 0, "must list at least one model"),
 })
     .strict();
+// The runtimes ocra ships; a plugin may register another name, so the
+// schema lists these for editors and still accepts any other string.
+const BUILTIN_RUNTIMES = ["opencode", "direct"];
 const configSchema = z
     .object({
+    $schema: z.string().optional(),
     models: z
         .object({ top: modelChain, standard: modelChain, light: modelChain })
         .partial()
@@ -55,6 +60,20 @@ const configSchema = z
     judge: z.boolean().optional(),
     maxCostUsd: z.number().positive().optional(),
     maxTasks: z.number().int().min(1).max(1_000).optional(),
+    // Unset: each provider's default. A seed makes sampling repeatable only
+    // where the provider supports it.
+    sampling: z
+        .object({
+        temperature: z.number().min(0).max(2),
+        seed: z
+            .number()
+            .int()
+            .min(0)
+            .max(2 ** 31 - 1),
+    })
+        .partial()
+        .strict()
+        .optional(),
     github: z
         .object({ requestChanges: z.boolean(), botLogin: z.string().min(1) })
         .partial()
@@ -62,7 +81,7 @@ const configSchema = z
         .default({}),
     include: z.array(z.string().min(1)).default([]),
     exclude: z.array(z.string().min(1)).default([]),
-    runtime: z.string().min(1).default("opencode"),
+    runtime: z.enum(BUILTIN_RUNTIMES).or(z.string().min(1)).default("opencode"),
     plugins: z.array(z.string().min(1)).default([]),
     reviewers: z
         .record(z.string(), z
@@ -78,20 +97,40 @@ const configSchema = z
     extends: z.string().min(1).optional(),
 })
     .strict();
+export const CONFIG_SCHEMA_ID = "https://ocra.majincheng.com/schema/config.v1.json";
+// JSON Schema (draft 2020-12) of .ocra/config.json, for editors: what a
+// file may say, so defaults are optional and model chains take either form.
+export function configJsonSchema() {
+    const generated = z.toJSONSchema(configSchema, { target: "draft-2020-12", io: "input" });
+    const { $schema, ...rest } = generated;
+    return {
+        $schema,
+        $id: CONFIG_SCHEMA_ID,
+        title: "ocra configuration",
+        description: "The .ocra/config.json file of a repository, or a file passed with --config. Unknown keys are rejected.",
+        ...rest,
+    };
+}
 const MODEL_ENV = {
     top: "OCRA_MODEL_TOP",
     standard: "OCRA_MODEL_STANDARD",
     light: "OCRA_MODEL_LIGHT",
 };
-export class ConfigError extends Error {
+export class ConfigError extends OcraError {
+    constructor(message, options) {
+        super("CONFIG_INVALID", message, options);
+        this.name = "ConfigError";
+    }
 }
 // Without the repository's file, only defaults and environment variables
 // apply: that file can name plugins, and plugins run code.
 export async function loadConfig(root, env, options = { repository: true }) {
     const read = options.read ?? ((path) => readConfigFromDisk(root, path));
-    const { config: parsed, rules } = options.repository
-        ? await readConfigFile(read, options)
-        : { config: configSchema.parse({}), rules: [] };
+    const { config: parsed, rules } = options.file
+        ? await readConfigFile(ownFile(options.file), options, options.file)
+        : options.repository
+            ? await readConfigFile(read, options, CONFIG_PATH)
+            : { config: configSchema.parse({}), rules: [] };
     const models = {};
     for (const [tier, chain] of Object.entries(parsed.models)) {
         if (chain)
@@ -139,6 +178,16 @@ function unpriced(providers, models) {
 // The user's own checkout, read like any local file (links followed): unlike
 // the review's reads, which never follow links (vcs-local), this is trusted
 // configuration, and --no-repo-config skips it for code that is not.
+function ownFile(file) {
+    return async () => {
+        try {
+            return await readFile(file, "utf8");
+        }
+        catch (error) {
+            throw new ConfigError(`cannot read ${file}: ${error.message}`, { cause: error });
+        }
+    };
+}
 async function readConfigFromDisk(root, path) {
     try {
         return await readFile(join(root, path), "utf8");
@@ -149,7 +198,7 @@ async function readConfigFromDisk(root, path) {
         throw error;
     }
 }
-async function readConfigFile(read, options) {
+async function readConfigFile(read, options, label) {
     const text = await read(CONFIG_PATH);
     if (text === undefined)
         return { config: configSchema.parse({}), rules: [] };
@@ -158,11 +207,13 @@ async function readConfigFile(read, options) {
         data = JSON.parse(text);
     }
     catch (error) {
-        throw new ConfigError(`${CONFIG_PATH} is not valid JSON: ${error.message}`);
+        throw new ConfigError(`${label} is not valid JSON: ${error.message}`, {
+            cause: error,
+        });
     }
     const local = configSchema.safeParse(data);
     if (!local.success)
-        throw new ConfigError(`${CONFIG_PATH} is invalid: ${z.prettifyError(local.error)}`);
+        throw new ConfigError(`${label} is invalid: ${z.prettifyError(local.error)}`);
     if (!local.data.extends)
         return { config: local.data, rules: [] };
     // A shared configuration that cannot be loaded costs its defaults, not the

package/dist/review/plan-render.d.ts

@@ -1,3 +1,3 @@
-import type { ReviewPreview } from "@open-cr-agent/core";
+import type { ReviewPreview } from "@open-cr-agent/core/internal";
 export declare function renderPlan(preview: ReviewPreview): string;
 //# sourceMappingURL=plan-render.d.ts.map

package/dist/review/progress.js

@@ -33,7 +33,7 @@ export class ProgressPrinter {
 function describe(event) {
     switch (event.type) {
         case "run_started":
-            return `Reviewing: ${event.changeRequest.title}`;
+            return `Reviewing: ${event.changeRequest.title} · run ${event.runId}`;
         case "files_selected":
             return `${event.selected} file(s) selected, ${event.excluded} excluded · risk tier: ${event.tier}`;
         case "files_bundled":

package/dist/review/provenance.d.ts

@@ -0,0 +1,6 @@
+import type { Sampling } from "@open-cr-agent/core";
+import type { ReviewArgs } from "./args.js";
+import type { CliConfig } from "./config.js";
+export declare function requestedSampling(config: CliConfig, args: ReviewArgs): Sampling;
+export declare function configHash(config: CliConfig, args: ReviewArgs): string;
+//# sourceMappingURL=provenance.d.ts.map

package/dist/review/provenance.js

@@ -0,0 +1,38 @@
+import { stableHash } from "@open-cr-agent/core/internal";
+// The sampling a review asks for: the configuration's, with --temperature
+// and --seed on top.
+export function requestedSampling(config, args) {
+    const temperature = args.temperature ?? config.sampling?.temperature;
+    const seed = args.seed ?? config.sampling?.seed;
+    return {
+        ...(temperature === undefined ? {} : { temperature }),
+        ...(seed === undefined ? {} : { seed }),
+    };
+}
+// The effective configuration and the flags that change what is reviewed
+// and how, so two runs can tell they were set up alike. Keys are names of
+// environment variables, never their values; a password written into a
+// URL is dropped. Sampling is recorded on its own.
+export function configHash(config, args) {
+    const { sampling: _, providers, extends: shared, ...rest } = config;
+    return stableHash({
+        ...rest,
+        ...(shared === undefined ? {} : { extends: withoutCredentials(shared) }),
+        providers: Object.fromEntries(Object.entries(providers).map(([id, p]) => [
+            id,
+            { ...p, baseUrl: withoutCredentials(p.baseUrl) },
+        ])),
+        flags: { reviewers: args.reviewers, ultra: args.ultra, maxCostUsd: args.maxCostUsd },
+    });
+}
+function withoutCredentials(value) {
+    if (!URL.canParse(value))
+        return value;
+    const url = new URL(value);
+    if (url.username === "" && url.password === "")
+        return value;
+    url.username = "";
+    url.password = "";
+    return url.toString();
+}
+//# sourceMappingURL=provenance.js.map

package/dist/review/remote-config.d.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 export declare const remoteConfigSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
     models: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
         light: "light";
         standard: "standard";

package/dist/review/remote-config.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import { repoRuleSchema } from "@open-cr-agent/core";
+import { OcraError } from "@open-cr-agent/core";
+import { repoRuleSchema } from "@open-cr-agent/core/internal";
 import { z } from "zod";
 const MAX_BYTES = 256 * 1024;
 const TIMEOUT_MS = 10_000;
@@ -8,6 +9,7 @@ const TIMEOUT_MS = 10_000;
 // is fetched from outside the repository.
 export const remoteConfigSchema = z
     .object({
+    $schema: z.string().optional(),
     models: z.record(z.enum(["top", "standard", "light"]), z.unknown()).optional(),
     concurrency: z.unknown().optional(),
     taskTimeoutMinutes: z.unknown().optional(),
@@ -29,7 +31,7 @@ export async function fetchRemoteConfig(spec, fetchImpl = fetch) {
     const [address = "", fragment] = spec.split("#", 2);
     const url = new URL(address);
     if (url.protocol !== "https:")
-        throw new Error(`extends must be an https URL, got ${url.protocol}`);
+        throw new OcraError("CONFIG_INVALID", `extends must be an https URL, got ${url.protocol}`);
     const pinned = fragment?.startsWith("sha256=")
         ? fragment.slice("sha256=".length).toLowerCase()
         : undefined;
@@ -39,21 +41,21 @@ export async function fetchRemoteConfig(spec, fetchImpl = fetch) {
         redirect: "error",
     });
     if (!response.ok)
-        throw new Error(`${url.href} answered ${response.status}`);
+        throw new OcraError("CONFIG_INVALID", `${url.href} answered ${response.status}`);
     const body = await readLimited(response, MAX_BYTES, url.href);
     if (pinned !== undefined) {
         const actual = createHash("sha256").update(body).digest("hex");
         if (actual !== pinned)
-            throw new Error(`${url.href} does not match its pinned sha256`);
+            throw new OcraError("CONFIG_INVALID", `${url.href} does not match its pinned sha256`);
     }
     const parsed = remoteConfigSchema.safeParse(JSON.parse(body));
     if (!parsed.success)
-        throw new Error(`${url.href} is invalid: ${z.prettifyError(parsed.error)}`);
+        throw new OcraError("CONFIG_INVALID", `${url.href} is invalid: ${z.prettifyError(parsed.error)}`);
     // A provider decides where the code under review goes: unpinned, whoever
     // serves the file could send it to an endpoint of their choosing.
     if (pinned === undefined && Object.keys(parsed.data.providers ?? {}).length > 0) {
         const digest = createHash("sha256").update(body).digest("hex");
-        throw new Error(`${url.href} declares providers, which a shared configuration may do only when pinned; check its content, then extend "${address}#sha256=${digest}"`);
+        throw new OcraError("CONFIG_INVALID", `${url.href} declares providers, which a shared configuration may do only when pinned; check its content, then extend "${address}#sha256=${digest}"`);
     }
     return parsed.data;
 }
@@ -71,7 +73,7 @@ async function readLimited(response, limit, name) {
         size += value.byteLength;
         if (size > limit) {
             await reader.cancel();
-            throw new Error(`${name} is larger than 256 KB`);
+            throw new OcraError("CONFIG_INVALID", `${name} is larger than 256 KB`);
         }
         chunks.push(value);
     }

package/dist/review/render.d.ts

@@ -1,4 +1,5 @@
-import { type ReviewReport, serializeOutput } from "@open-cr-agent/core";
+import { type ReviewReport } from "@open-cr-agent/core";
+import { serializeOutput } from "@open-cr-agent/core/internal";
 export declare function renderJson(report: ReviewReport): string;
 export declare const safeJson: typeof serializeOutput;
 export declare function renderText(report: ReviewReport, sessionDir?: string): string;

package/dist/review/render.js

@@ -1,4 +1,5 @@
-import { coverageGaps, serializeOutput, toReportOutput, } from "@open-cr-agent/core";
+import { coverageGaps, toReportOutput, } from "@open-cr-agent/core";
+import { serializeOutput } from "@open-cr-agent/core/internal";
 import { forTerminal } from "./terminal.js";
 const SEVERITIES = ["critical", "warning", "suggestion"];
 const VERIFICATION = {
@@ -86,8 +87,7 @@ export function renderText(report, sessionDir) {
     }
     for (const warning of report.warnings)
         lines.push(`Warning: ${warning}`);
-    if (sessionDir)
-        lines.push(`Session: ${sessionDir}`);
+    lines.push(`Run: ${report.runId}${sessionDir ? ` (${sessionDir})` : ""}`);
     return forTerminal(`${lines.join("\n")}\n`);
 }
 function emptyMessage(report, nothingReviewed, notReviewed) {

package/dist/review/runtimes.d.ts

@@ -0,0 +1,5 @@
+import { type OcraPlugin } from "@open-cr-agent/core";
+export type RuntimeLoaders = Readonly<Record<string, () => Promise<OcraPlugin>>>;
+export declare const BUILTIN_RUNTIMES: RuntimeLoaders;
+export declare function loadRuntime(runtime: string, packageName: string, load: () => Promise<OcraPlugin>): Promise<OcraPlugin>;
+//# sourceMappingURL=runtimes.d.ts.map

package/dist/review/runtimes.js

@@ -0,0 +1,29 @@
+import { OcraError } from "@open-cr-agent/core";
+import { VERSION } from "../version.js";
+export const BUILTIN_RUNTIMES = {
+    opencode: () => loadRuntime("opencode", "@open-cr-agent/runtime-opencode", async () => (await import("@open-cr-agent/runtime-opencode")).opencodeRuntimePlugin),
+    direct: () => loadRuntime("direct", "@open-cr-agent/runtime-direct", async () => (await import("@open-cr-agent/runtime-direct")).directRuntimePlugin),
+};
+export async function loadRuntime(runtime, packageName, load) {
+    try {
+        return await load();
+    }
+    catch (error) {
+        if (!isMissingPackage(error, packageName))
+            throw error;
+        const other = runtime === "direct" ? "opencode" : "direct";
+        throw new OcraError("RUNTIME_START_FAILED", `The ${runtime} runtime needs ${packageName}, which is not installed ` +
+            "(an optional dependency of @open-cr-agent/cli, left out by --omit=optional). " +
+            `Install it next to ocra with npm install ${packageName}@${VERSION} (-g for a global ocra), ` +
+            `or set "runtime": "${other}" in the configuration.`, { cause: error });
+    }
+}
+// Node reports a bare specifier it cannot resolve as ERR_MODULE_NOT_FOUND,
+// naming the package; a module missing inside the package names another.
+function isMissingPackage(error, packageName) {
+    if (!(error instanceof Error))
+        return false;
+    const code = error.code;
+    return code === "ERR_MODULE_NOT_FOUND" && error.message.includes(`'${packageName}'`);
+}
+//# sourceMappingURL=runtimes.js.map

package/dist/review/sarif-input.d.ts

@@ -0,0 +1,4 @@
+import { type SarifLog } from "@open-cr-agent/core";
+export declare const MAX_SARIF_BYTES: number;
+export declare function loadSarifLogs(paths: readonly string[], cwd: string): Promise<SarifLog[]>;
+//# sourceMappingURL=sarif-input.d.ts.map

package/dist/review/sarif-input.js

@@ -0,0 +1,34 @@
+import { readFile, stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parseSarifLog } from "@open-cr-agent/core";
+import { ConfigError } from "./config.js";
+// A log is untrusted input like everything else that reaches the review; it
+// is bounded before it is parsed.
+export const MAX_SARIF_BYTES = 20 * 1024 * 1024;
+export async function loadSarifLogs(paths, cwd) {
+    const logs = [];
+    for (const path of paths) {
+        const file = resolve(cwd, path);
+        let text;
+        try {
+            const { size } = await stat(file);
+            if (size > MAX_SARIF_BYTES) {
+                throw new ConfigError(`--import-sarif ${path}: larger than ${MAX_SARIF_BYTES} bytes`);
+            }
+            text = await readFile(file, "utf8");
+        }
+        catch (error) {
+            if (error instanceof ConfigError)
+                throw error;
+            throw new ConfigError(`--import-sarif ${path}: ${error.message}`);
+        }
+        try {
+            logs.push(parseSarifLog(text));
+        }
+        catch (error) {
+            throw new ConfigError(`--import-sarif ${path}: ${error.message}`);
+        }
+    }
+    return logs;
+}
+//# sourceMappingURL=sarif-input.js.map

package/dist/review/sarif.js

@@ -1,4 +1,5 @@
-import { coverageGaps, serializeOutput, } from "@open-cr-agent/core";
+import { coverageGaps, } from "@open-cr-agent/core";
+import { serializeOutput } from "@open-cr-agent/core/internal";
 // `--format sarif`: the review as a SARIF 2.1.0 log, for code scanning and
 // security dashboards. One rule per reviewer category, one result per
 // finding. Findings an earlier review reported in files this run did not
@@ -26,6 +27,7 @@ export function renderSarif(report, version) {
         version: "2.1.0",
         runs: [
             {
+                automationDetails: { id: `ocra/${report.runId}` },
                 tool: {
                     driver: {
                         name: "ocra",
@@ -36,7 +38,9 @@ export function renderSarif(report, version) {
                             id,
                             name: id,
                             shortDescription: {
-                                text: id === CARRIED ? CARRIED_DESCRIPTION : `Findings of ocra's ${id} reviewer`,
+                                text: id === CARRIED
+                                    ? CARRIED_DESCRIPTION
+                                    : `Findings of the ${id} reviewer or analyzer`,
                             },
                             properties: { tags: [id] },
                         })),
@@ -100,6 +104,8 @@ function fromFinding(f, index) {
             verification: f.verification ?? "unchecked",
             status: f.status === "unfixed" ? "unfixed" : "new",
             ...(f.lowConfidence ? { lowConfidence: true } : {}),
+            task: f.provenance.task,
+            ...(f.provenance.model === undefined ? {} : { model: f.provenance.model }),
         },
     };
 }

package/dist/review/target.d.ts

@@ -1,4 +1,4 @@
-import type { OcraPlugin, PluginRegistry, VcsAdapter } from "@open-cr-agent/core";
+import { type OcraPlugin, type PluginRegistry, type VcsAdapter } from "@open-cr-agent/core";
 import type { MergeRequestTarget, PullRequestTarget, ReviewArgs } from "./args.js";
 import { type CliConfig } from "./config.js";
 export interface ReviewTarget {
@@ -11,7 +11,7 @@ export interface ReviewTarget {
 }
 type Env = Readonly<Record<string, string | undefined>>;
 export declare function localTarget(args: ReviewArgs, cwd: string, root: string, env: Env, warn: (message: string) => void, fetchImpl?: typeof fetch): Promise<ReviewTarget>;
-export declare function pullRequestTarget(pr: PullRequestTarget, cwd: string, root: string, env: Env, warn: (message: string) => void, fetchImpl?: typeof fetch, ignoreRepoConfig?: boolean): Promise<ReviewTarget>;
-export declare function mergeRequestTarget(mr: MergeRequestTarget, cwd: string, root: string, env: Env, warn: (message: string) => void, fetchImpl?: typeof fetch, ignoreRepoConfig?: boolean): Promise<ReviewTarget>;
+export declare function pullRequestTarget(pr: PullRequestTarget, cwd: string, root: string, env: Env, warn: (message: string) => void, fetchImpl?: typeof fetch, ignoreRepoConfig?: boolean, configFile?: string): Promise<ReviewTarget>;
+export declare function mergeRequestTarget(mr: MergeRequestTarget, cwd: string, root: string, env: Env, warn: (message: string) => void, fetchImpl?: typeof fetch, ignoreRepoConfig?: boolean, configFile?: string): Promise<ReviewTarget>;
 export {};
 //# sourceMappingURL=target.d.ts.map

package/dist/review/target.js

@@ -1,17 +1,21 @@
-import { DEFAULT_BOT_LOGIN, GitHubApi } from "@open-cr-agent/vcs-github";
-import { GitLabApi } from "@open-cr-agent/vcs-gitlab";
-import { ensureCommits, filesChangedSince, LocalGitAdapter } from "@open-cr-agent/vcs-local";
+import { dirname } from "node:path";
+import { OcraError, } from "@open-cr-agent/core";
+import { DEFAULT_BOT_LOGIN, GitHubApi } from "@open-cr-agent/vcs-github/internal";
+import { GitLabApi } from "@open-cr-agent/vcs-gitlab/internal";
+import { ensureCommits, filesChangedSince, LocalGitAdapter, } from "@open-cr-agent/vcs-local/internal";
 import { ConfigError, loadConfig } from "./config.js";
 import { loadExternalPlugins } from "./plugins.js";
 export async function localTarget(args, cwd, root, env, warn, fetchImpl) {
     const config = await loadConfig(root, env, {
         repository: !args.ignoreRepoConfig,
+        ...(args.configFile ? { file: args.configFile } : {}),
         warn,
         ...(fetchImpl ? { fetch: fetchImpl } : {}),
     });
     return {
         config,
-        plugins: await loadExternalPlugins(config.plugins, root),
+        // Plugins named by the user's own file are resolved from where it is.
+        plugins: await loadExternalPlugins(config.plugins, args.configFile ? dirname(args.configFile) : root),
         createVcs: (registry) => registry.createVcs("local", { cwd, target: args.target }),
         ...(args.ignoreRepoConfig ? { readTrusted: untrustedTreeReader(args, cwd) } : {}),
         publish: false,
@@ -29,10 +33,11 @@ function untrustedTreeReader(args, cwd) {
 }
 // The pull request's own files are untrusted: configuration, guidelines and
 // rules come from its base commit, and repository plugins never load.
-export async function pullRequestTarget(pr, cwd, root, env, warn, fetchImpl, ignoreRepoConfig = false) {
+export async function pullRequestTarget(pr, cwd, root, env, warn, fetchImpl, ignoreRepoConfig = false, configFile) {
     const token = env.GITHUB_TOKEN ?? env.GH_TOKEN;
-    if (!token)
-        throw new ConfigError("--pr needs a GitHub token in GITHUB_TOKEN or GH_TOKEN");
+    if (!token) {
+        throw new OcraError("CONFIG_CREDENTIALS_MISSING", "--pr needs a GitHub token in GITHUB_TOKEN or GH_TOKEN");
+    }
     const [owner = "", repo = ""] = (pr.repo ?? (await repositoryName(root, env))).split("/");
     const apiOptions = { token, ...(env.GITHUB_API_URL ? { baseUrl: env.GITHUB_API_URL } : {}) };
     const api = new GitHubApi({ owner, repo }, fetchImpl ? { ...apiOptions, fetch: fetchImpl } : apiOptions);
@@ -43,11 +48,12 @@ export async function pullRequestTarget(pr, cwd, root, env, warn, fetchImpl, ign
     const config = await loadConfig(root, env, {
         repository: !ignoreRepoConfig,
         read: readTrusted,
+        ...(configFile ? { file: configFile } : {}),
         warn,
         ...(fetchImpl ? { fetch: fetchImpl } : {}),
     });
     if (config.plugins.length > 0) {
-        warn("plugins in .ocra/config.json are not loaded for pull requests");
+        warn("plugins in the configuration are not loaded for pull requests");
     }
     const code = new LocalGitAdapter({
         cwd,
@@ -81,10 +87,10 @@ const GITLAB_API = "https://gitlab.com/api/v4";
 // target branch the merge request was based on, and repository plugins never
 // load. GitLab CI sets CI_API_V4_URL and CI_PROJECT_ID; GITLAB_TOKEN must be
 // a token that may write notes, which CI_JOB_TOKEN may not.
-export async function mergeRequestTarget(mr, cwd, root, env, warn, fetchImpl, ignoreRepoConfig = false) {
+export async function mergeRequestTarget(mr, cwd, root, env, warn, fetchImpl, ignoreRepoConfig = false, configFile) {
     const token = env.GITLAB_TOKEN;
     if (!token) {
-        throw new ConfigError("--mr needs a GitLab token in GITLAB_TOKEN: a project access token with the api scope and the Developer role (CI_JOB_TOKEN cannot post comments)");
+        throw new OcraError("CONFIG_CREDENTIALS_MISSING", "--mr needs a GitLab token in GITLAB_TOKEN: a project access token with the api scope and the Developer role (CI_JOB_TOKEN cannot post comments)");
     }
     const origin = await originUrl(root);
     const project = mr.project ?? env.CI_PROJECT_ID ?? gitlabProject(origin);
@@ -96,19 +102,21 @@ export async function mergeRequestTarget(mr, cwd, root, env, warn, fetchImpl, ig
     });
     const merge = await api.getMergeRequest(mr.iid);
     const refs = merge.diff_refs;
-    if (!refs)
-        throw new ConfigError(`merge request !${mr.iid} has no diff yet; try again shortly`);
+    if (!refs) {
+        throw new OcraError("VCS_NOT_READY", `merge request !${mr.iid} has no diff yet; try again shortly`);
+    }
     await ensureCommits(root, [refs.start_sha, refs.head_sha], [`refs/merge-requests/${mr.iid}/head`]);
     const base = new LocalGitAdapter({ cwd, target: { mode: "commit", commit: refs.start_sha } });
     const readTrusted = (path) => base.readFile(path);
     const config = await loadConfig(root, env, {
         repository: !ignoreRepoConfig,
         read: readTrusted,
+        ...(configFile ? { file: configFile } : {}),
         warn,
         ...(fetchImpl ? { fetch: fetchImpl } : {}),
     });
     if (config.plugins.length > 0) {
-        warn("plugins in .ocra/config.json are not loaded for merge requests");
+        warn("plugins in the configuration are not loaded for merge requests");
     }
     const code = new LocalGitAdapter({
         cwd,

package/dist/review/terminal.js

@@ -1,4 +1,4 @@
-import { isUnsafeCodePoint } from "@open-cr-agent/core";
+import { isUnsafeCodePoint } from "@open-cr-agent/core/internal";
 // Findings, commit messages and errors can carry text a diff planted; none of
 // it may drive the user's terminal. C0 and C1 controls (ANSI and OSC escapes
 // start with ESC or a C1 code) except tab and newline, carriage returns, and

package/dist/run.js

@@ -1,9 +1,12 @@
 import { writeFile } from "node:fs/promises";
 import { parseArgs } from "node:util";
-import { errorMessage } from "@open-cr-agent/core";
+import { isOcraError } from "@open-cr-agent/core";
+import { errorMessage } from "@open-cr-agent/core/internal";
 import { memoryCommand } from "./memory.js";
+import { metricsCommand } from "./metrics.js";
 import { parseReviewArgs, REVIEW_USAGE, UsageError } from "./review/args.js";
 import { BUILTIN_PLUGINS, EXIT, reviewCommand } from "./review/command.js";
+import { BUILTIN_RUNTIMES } from "./review/runtimes.js";
 import { forTerminal } from "./review/terminal.js";
 import { VERSION } from "./version.js";
 const USAGE = `Usage: ocra <command> [options]
@@ -11,6 +14,7 @@ const USAGE = `Usage: ocra <command> [options]
 Commands:
   review      Review code changes (run "ocra review --help" for options)
   memory      Remember findings the team accepts (run "ocra memory --help")
+  metrics     Counts over past reviews: runs, cost, findings, per reviewer (run "ocra metrics --help")
 
 Options:
   -h, --help     Show help
@@ -21,6 +25,7 @@ export function defaultDeps() {
         cwd: process.cwd(),
         env: process.env,
         builtinPlugins: BUILTIN_PLUGINS,
+        runtimes: BUILTIN_RUNTIMES,
         writeFile: (path, content) => writeFile(path, content, "utf8"),
         now: Date.now,
         heartbeatMs: 30_000,
@@ -45,12 +50,14 @@ export async function run(argv, out, err, deps = defaultDeps()) {
     const [command, ...rest] = argv;
     if (command === "review")
         return review(rest, out, err, deps);
-    if (command === "memory") {
+    if (command === "memory" || command === "metrics") {
         try {
-            return await memoryCommand(rest, out, deps.cwd);
+            return command === "memory"
+                ? await memoryCommand(rest, out, deps.cwd)
+                : await metricsCommand(rest, out, deps.cwd);
         }
         catch (error) {
-            err.write(`ocra: ${forTerminal(errorMessage(error))}\n`);
+            err.write(failure(error));
             return EXIT.error;
         }
     }
@@ -91,9 +98,14 @@ async function review(argv, out, err, deps) {
             err.write(`${error.message}\n\n${REVIEW_USAGE}`);
         }
         else {
-            err.write(`ocra: ${forTerminal(errorMessage(error))}\n`);
+            err.write(failure(error));
         }
         return EXIT.error;
     }
 }
+// The code is what a script may match on; the message is for people.
+function failure(error) {
+    const code = isOcraError(error) ? ` [${error.code}]` : "";
+    return `ocra${code}: ${forTerminal(errorMessage(error))}\n`;
+}
 //# sourceMappingURL=run.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-cr-agent/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "ocra: open-source multi-agent code review for local changes and GitHub pull requests",
   "keywords": [
     "code-review",
@@ -23,9 +23,11 @@
   "type": "module",
   "exports": {
     ".": {
+      "@open-cr-agent/source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "bin": {
     "ocra": "./dist/main.js"
@@ -35,13 +37,16 @@
     "!dist/**/*.map"
   ],
   "dependencies": {
-    "@open-cr-agent/core": "0.2.0",
-    "@open-cr-agent/runtime-opencode": "0.2.0",
-    "@open-cr-agent/vcs-github": "0.2.0",
-    "@open-cr-agent/vcs-gitlab": "0.2.0",
-    "@open-cr-agent/vcs-local": "0.2.0",
+    "@open-cr-agent/core": "0.3.0",
+    "@open-cr-agent/runtime-direct": "0.3.0",
+    "@open-cr-agent/vcs-github": "0.3.0",
+    "@open-cr-agent/vcs-gitlab": "0.3.0",
+    "@open-cr-agent/vcs-local": "0.3.0",
     "zod": "^4.6.5"
   },
+  "optionalDependencies": {
+    "@open-cr-agent/runtime-opencode": "0.3.0"
+  },
   "publishConfig": {
     "access": "public"
   }