@open-cr-agent/core 0.2.0 → 0.4.0

package/dist/pipeline/agents.js

@@ -0,0 +1,55 @@
+export const EFFORT_LEVELS = [
+    "none",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+];
+export const AGENT_ROLES = ["verifier", "judge", "helper"];
+export const ROLE_TIERS = {
+    verifier: "standard",
+    judge: "top",
+    helper: "light",
+};
+// A reviewer's effort covers every call made on its behalf: its review
+// tasks and its plan call.
+export function reviewerEffort(reviewer, settings) {
+    return settings.reviewerOverrides?.[reviewer.id]?.effort ?? settings.effort?.[reviewer.modelTier];
+}
+export function roleEffort(role, settings) {
+    return settings.roles?.[role]?.effort ?? settings.effort?.[ROLE_TIERS[role]];
+}
+// The enabled reviewers and the roles, each with its tier and effort.
+export function resolveAgents(reviewers, settings) {
+    const agent = (id, tier, effort) => effort === undefined ? { id, tier } : { id, tier, effort };
+    return [
+        ...reviewers
+            .filter((r) => settings.reviewerOverrides?.[r.id]?.enabled !== false)
+            .map((r) => agent(r.id, r.modelTier, reviewerEffort(r, settings))),
+        ...AGENT_ROLES.map((role) => agent(role, ROLE_TIERS[role], roleEffort(role, settings))),
+    ];
+}
+// The request fields that name an agent and its effort.
+export function agentCall(agent, effort) {
+    return effort === undefined ? { agent } : { agent, effort };
+}
+// Said once per run, so a configured effort that never reached a model is
+// not mistaken for one that did.
+export function effortWarnings(agents, runtime) {
+    const asked = agents.filter((a) => a.effort !== undefined);
+    if (asked.length === 0)
+        return [];
+    const { appliedTo } = runtime;
+    if (!appliedTo) {
+        return [
+            `the ${runtime.name} runtime does not apply reasoning effort yet; the effort configured for ${asked.map((a) => a.id).join(", ")} was not sent`,
+        ];
+    }
+    const refused = asked.filter((a) => appliedTo.call(runtime, a.id)?.effort === false);
+    return refused.length === 0
+        ? []
+        : [
+            `the endpoint refused the reasoning effort for ${refused.map((a) => a.id).join(", ")}; those calls were sent again without it`,
+        ];
+}
+//# sourceMappingURL=agents.js.map

package/dist/pipeline/budget.d.ts

@@ -1,6 +1,7 @@
 import type { Usage } from "../contracts.js";
+import { OcraError } from "../errors.js";
 export declare const REVIEW_BUDGET_SHARE = 0.8;
-export declare class SpendLimitReached extends Error {
+export declare class SpendLimitReached extends OcraError {
     constructor(maxCostUsd: number);
 }
 export interface SpendTracker {

package/dist/pipeline/budget.js

@@ -1,3 +1,4 @@
+import { OcraError } from "../errors.js";
 // Review tasks may spend this share of the limit; the rest is kept for Verify
 // and Judge, so the run that hits the limit still gets its findings checked.
 // Those stages are one short call per file with findings plus one top-tier
@@ -7,9 +8,9 @@
 // and whatever the runtime had not reported yet) comes out of the reserve.
 export const REVIEW_BUDGET_SHARE = 0.8;
 // Why running review tasks were stopped.
-export class SpendLimitReached extends Error {
+export class SpendLimitReached extends OcraError {
     constructor(maxCostUsd) {
-        super(`stopped at the spend limit of $${maxCostUsd}`);
+        super("BUDGET_EXHAUSTED", `stopped at the spend limit of $${maxCostUsd}`);
         this.name = "SpendLimitReached";
     }
 }

package/dist/pipeline/context.d.ts

@@ -1,6 +1,8 @@
 import type { ReviewContext, VcsAdapter } from "../contracts.js";
 import type { FileDiff } from "../domain.js";
-export declare class AccessDeniedError extends Error {
+import { OcraError } from "../errors.js";
+export declare class AccessDeniedError extends OcraError {
+    constructor(message: string);
 }
 export declare function reviewContext(vcs: VcsAdapter, diffs: readonly FileDiff[]): ReviewContext;
 //# sourceMappingURL=context.d.ts.map

package/dist/pipeline/context.js

@@ -1,6 +1,11 @@
 import { posix } from "node:path";
+import { OcraError } from "../errors.js";
 import { isSecretPath } from "../select/select.js";
-export class AccessDeniedError extends Error {
+export class AccessDeniedError extends OcraError {
+    constructor(message) {
+        super("ACCESS_DENIED", message);
+        this.name = "AccessDeniedError";
+    }
 }
 const WINDOWS = process.platform === "win32";
 // Agents read the repository through this context only, so the policy lives

package/dist/pipeline/coverage.d.ts

@@ -0,0 +1,6 @@
+import type { FileDecision } from "../select/select.js";
+import type { JobResult } from "./execute.js";
+import type { MatrixCell } from "./matrix.js";
+import type { CoverageEntry } from "./report.js";
+export declare function coverageOf(decisions: readonly FileDecision[], results: readonly JobResult[], unchanged: ReadonlySet<string>, limited: readonly MatrixCell[], notStarted: ReadonlySet<string>): CoverageEntry[];
+//# sourceMappingURL=coverage.d.ts.map

package/dist/pipeline/coverage.js

@@ -0,0 +1,44 @@
+export function coverageOf(decisions, results, unchanged, limited, notStarted) {
+    // A file is reviewed when every reviewer assigned to it finished at least
+    // one of its tasks: under --ultra one completed sample is enough. A
+    // reviewer whose task failed makes the file "failed"; one whose task never
+    // started (the task or spend limit, a cancelled run) makes it "unreviewed".
+    const done = new Map();
+    const ran = new Set();
+    const key = (reviewer, file) => `${reviewer}\0${file}`;
+    for (const { outcome } of results) {
+        const started = !notStarted.has(outcome.taskId);
+        for (const file of outcome.files) {
+            const k = key(outcome.reviewer, file);
+            if (started)
+                ran.add(k);
+            done.set(k, done.get(k) === true || outcome.status === "completed");
+        }
+    }
+    for (const cell of limited) {
+        for (const f of cell.bundle.files) {
+            const k = key(cell.reviewer.id, f.newPath);
+            if (!done.has(k))
+                done.set(k, false);
+        }
+    }
+    const status = new Map();
+    for (const [k, completed] of done) {
+        const file = k.split("\0")[1];
+        const now = completed ? "reviewed" : ran.has(k) ? "failed" : "unreviewed";
+        const before = status.get(file);
+        // failed outranks unreviewed, which outranks reviewed.
+        if (!before || now === "failed" || (now === "unreviewed" && before === "reviewed")) {
+            status.set(file, now);
+        }
+    }
+    return decisions.map((d) => {
+        const path = d.diff.newPath;
+        if (!d.selected)
+            return { path, status: "excluded", reason: d.reason };
+        if (unchanged.has(path))
+            return { path, status: "unchanged" };
+        return { path, status: status.get(path) ?? "unreviewed" };
+    });
+}
+//# sourceMappingURL=coverage.js.map

package/dist/pipeline/execute.d.ts

@@ -2,6 +2,7 @@ import { type AnchorContext } from "../anchor/anchor.js";
 import type { AgentRuntime, Usage } from "../contracts.js";
 import type { Finding } from "../domain.js";
 import { planBundle } from "../review/plan-phase.js";
+import { type AgentSettings } from "./agents.js";
 import type { MatrixCell } from "./matrix.js";
 import type { ReviewPlan } from "./plan.js";
 import type { ReviewEvent, TaskOutcome } from "./report.js";
@@ -21,6 +22,7 @@ export interface ExecuteOptions {
     emit: (event: ReviewEvent) => void;
     onUsage?: ((usage: Usage) => void) | undefined;
     signal: AbortSignal;
+    agents?: AgentSettings;
 }
 type PlannedBundle = Awaited<ReturnType<typeof planBundle>>;
 export declare const PLAN_MIN_FILES = 5;

package/dist/pipeline/execute.js

@@ -4,6 +4,7 @@ import { findCallers } from "../review/impact.js";
 import { planBundle } from "../review/plan-phase.js";
 import { buildReviewPrompt } from "../review/prompt.js";
 import { resolveRules } from "../rules/resolve.js";
+import { reviewerEffort } from "./agents.js";
 import { toFinding } from "./findings.js";
 import { executeTask } from "./task.js";
 import { addUsage } from "./usage.js";
@@ -28,6 +29,7 @@ export async function runJob(job, plan, options) {
         guidelines: plan.guidelines,
         accepted: memoryFor(files, plan.memory),
     };
+    const effort = reviewerEffort(job.reviewer, options.agents ?? {});
     const extraUsage = [];
     const extraWarnings = [];
     let prompt = buildReviewPrompt(input);
@@ -36,7 +38,7 @@ export async function runJob(job, plan, options) {
         const key = `${job.reviewer.id}\0${job.bundle.label}`;
         const shared = options.plans?.get(key);
         const planning = shared ??
-            planBundle(options.runtime, job.reviewer, buildReviewPrompt({ ...input, forPlanning: true }), options.signal);
+            planBundle(options.runtime, job.reviewer, buildReviewPrompt({ ...input, forPlanning: true }), options.signal, effort);
         if (!shared)
             options.plans?.set(key, planning);
         const planned = await planning;
@@ -62,6 +64,7 @@ export async function runJob(job, plan, options) {
         taskId: job.taskId,
         reviewer: job.reviewer.id,
         modelTier: job.reviewer.modelTier,
+        ...(effort === undefined ? {} : { effort }),
         systemPrompt: prompt.system,
         userPrompt: prompt.user,
         context: plan.context,
@@ -85,7 +88,7 @@ export async function runJob(job, plan, options) {
     // happened to read the file.
     const bundleFiles = new Set(files);
     let outside = 0;
-    for (const reported of result.findings) {
+    for (const { reported, model } of result.findings) {
         // Relocating a quote on a file outside the bundle would pay for an
         // answer the next check throws away.
         const context = bundleFiles.has(reported.file)
@@ -101,13 +104,15 @@ export async function runJob(job, plan, options) {
         const content = anchor.lineRange
             ? await plan.context.readFile(anchor.file).catch(() => undefined)
             : undefined;
-        const finding = toFinding(reported, job.reviewer.id, anchor, content);
+        const provenance = model === undefined ? { task: job.taskId } : { task: job.taskId, model };
+        const finding = toFinding(reported, job.reviewer.id, provenance, anchor, content);
         findings.push(finding);
         emit({ type: "finding", taskId: job.taskId, finding });
     }
     if (outside > 0) {
         warnings.push(`${job.taskId}: dropped ${outside} finding(s) on files outside its bundle`);
     }
+    const usage = extraUsage.reduce(addUsage, result.usage);
     const outcome = {
         taskId: job.taskId,
         reviewer: job.reviewer.id,
@@ -116,10 +121,11 @@ export async function runJob(job, plan, options) {
         status: result.status,
         findings: findings.length,
         durationMs: Date.now() - started,
+        usage,
     };
     if (result.error !== undefined)
         outcome.error = result.error;
     emit({ type: "task_finished", outcome });
-    return { outcome, findings, usage: extraUsage.reduce(addUsage, result.usage), warnings };
+    return { outcome, findings, usage, warnings };
 }
 //# sourceMappingURL=execute.js.map

package/dist/pipeline/findings.d.ts

@@ -1,6 +1,6 @@
 import type { Anchor } from "../anchor/anchor.js";
-import type { Finding, ReportedFinding } from "../domain.js";
+import type { Finding, FindingProvenance, ReportedFinding } from "../domain.js";
 export declare function fingerprint(category: string, file: string, existingCode: string): string;
-export declare function toFinding(reported: ReportedFinding, reviewer: string, anchor: Anchor, content?: string): Finding;
+export declare function toFinding(reported: ReportedFinding, reviewer: string, provenance: FindingProvenance, anchor: Anchor, content?: string): Finding;
 export declare function dedupeFindings(findings: readonly Finding[]): Finding[];
 //# sourceMappingURL=findings.d.ts.map

package/dist/pipeline/findings.js

@@ -7,13 +7,14 @@ export function fingerprint(category, file, existingCode) {
     return createHash("sha256").update(key).digest("hex").slice(0, 16);
 }
 // content is the anchored file at head, when the anchor found lines in it.
-export function toFinding(reported, reviewer, anchor, content) {
+export function toFinding(reported, reviewer, provenance, anchor, content) {
     const finding = {
         ...reported,
         file: anchor.file,
         id: randomUUID(),
         fingerprint: fingerprint(reported.category, anchor.file, reported.existingCode),
         reviewer,
+        provenance,
         anchor: {
             method: anchor.method,
             inDiff: anchor.inDiff,

package/dist/pipeline/helpers.d.ts

@@ -1,6 +1,6 @@
 import type { FileGrouper } from "../bundle/grouping.js";
-import type { AgentRuntime, Usage } from "../contracts.js";
+import type { AgentRuntime, Effort, Usage } from "../contracts.js";
 export declare const HELPER_TIMEOUT_MS = 60000;
-export declare function runtimeGrouper(runtime: AgentRuntime, signal: AbortSignal, onUsage: (usage: Usage) => void): FileGrouper | undefined;
+export declare function runtimeGrouper(runtime: AgentRuntime, signal: AbortSignal, onUsage: (usage: Usage) => void, effort?: Effort): FileGrouper | undefined;
 export declare function parseJsonAnswer(text: string): unknown;
 //# sourceMappingURL=helpers.d.ts.map

package/dist/pipeline/helpers.js

@@ -1,14 +1,21 @@
-import { usageSpent } from "../errors.js";
+import { OcraError, usageSpent } from "../errors.js";
+import { agentCall } from "./agents.js";
 export const HELPER_TIMEOUT_MS = 60_000;
 // Grouping runs on the runtime's cheapest tier when the runtime supports plain
 // completions; otherwise bundling falls back to per-file review.
-export function runtimeGrouper(runtime, signal, onUsage) {
+export function runtimeGrouper(runtime, signal, onUsage, effort) {
     const complete = runtime.complete?.bind(runtime);
     if (!complete)
         return undefined;
     return {
         async group(prompt) {
-            const result = await complete({ tier: "light", system: prompt.system, user: prompt.user, timeoutMs: HELPER_TIMEOUT_MS }, AbortSignal.any([signal, AbortSignal.timeout(HELPER_TIMEOUT_MS)])).catch((error) => {
+            const result = await complete({
+                tier: "light",
+                ...agentCall("helper", effort),
+                system: prompt.system,
+                user: prompt.user,
+                timeoutMs: HELPER_TIMEOUT_MS,
+            }, AbortSignal.any([signal, AbortSignal.timeout(HELPER_TIMEOUT_MS)])).catch((error) => {
                 const spent = usageSpent(error);
                 if (spent)
                     onUsage(spent);
@@ -25,7 +32,7 @@ export function parseJsonAnswer(text) {
     const candidate = (fenced ?? text).trim();
     const start = candidate.search(/[[{]/);
     if (start < 0)
-        throw new Error("the model answered without JSON");
+        throw new OcraError("RUNTIME_INVALID_OUTPUT", "the model answered without JSON");
     const end = Math.max(candidate.lastIndexOf("]"), candidate.lastIndexOf("}"));
     return JSON.parse(candidate.slice(start, end + 1));
 }

package/dist/pipeline/imports.d.ts

@@ -0,0 +1,12 @@
+import type { Finding } from "../domain.js";
+import type { SarifLog } from "../sarif/schema.js";
+import type { ReviewPlan } from "./plan.js";
+import type { ReviewEvent, TaskOutcome } from "./report.js";
+export interface SarifImport {
+    findings: Finding[];
+    outcomes: TaskOutcome[];
+    warnings: string[];
+}
+export declare const MAX_IMPORTED_PER_RUN = 200;
+export declare function importSarif(logs: readonly SarifLog[], plan: Pick<ReviewPlan, "selected" | "context">, emit: (event: ReviewEvent) => void): Promise<SarifImport>;
+//# sourceMappingURL=imports.d.ts.map

package/dist/pipeline/imports.js

@@ -0,0 +1,126 @@
+import { anchorFinding } from "../anchor/anchor.js";
+import { sarifCandidates } from "../sarif/candidates.js";
+import { toFinding } from "./findings.js";
+import { boundFinding } from "./task.js";
+import { emptyUsage } from "./usage.js";
+// A hostile log could carry thousands of results on the change.
+export const MAX_IMPORTED_PER_RUN = 200;
+export async function importSarif(logs, plan, emit) {
+    const windows = changedLines(plan.selected);
+    const imported = { findings: [], outcomes: [], warnings: [] };
+    const counts = new Map();
+    for (const log of logs) {
+        for (const run of log.runs) {
+            const { tool, candidates, skipped } = sarifCandidates(run);
+            const n = (counts.get(tool.slug) ?? 0) + 1;
+            counts.set(tool.slug, n);
+            const taskId = `sarif-${tool.slug}-${n}`;
+            const started = Date.now();
+            const onChange = candidates.filter((c) => touches(windows, c));
+            const kept = onChange.slice(0, MAX_IMPORTED_PER_RUN);
+            const files = [...new Set(kept.map((c) => c.file))];
+            emit({ type: "task_started", taskId, reviewer: tool.slug, bundle: "sarif", files });
+            let noCode = 0;
+            const findings = [];
+            for (const candidate of kept) {
+                const finding = await toImportedFinding(candidate, tool.slug, taskId, plan);
+                if (!finding) {
+                    noCode += 1;
+                    continue;
+                }
+                findings.push(finding);
+                emit({ type: "finding", taskId, finding });
+            }
+            const outcome = {
+                taskId,
+                reviewer: tool.slug,
+                bundle: "sarif",
+                files,
+                status: "completed",
+                findings: findings.length,
+                durationMs: Date.now() - started,
+                usage: emptyUsage(),
+            };
+            emit({ type: "task_finished", outcome });
+            imported.findings.push(...findings);
+            imported.outcomes.push(outcome);
+            imported.warnings.push(...importWarnings(tool.name, {
+                imported: findings.length,
+                outside: candidates.length - onChange.length,
+                overLimit: onChange.length - kept.length,
+                noCode,
+                ...skipped,
+            }));
+        }
+    }
+    return imported;
+}
+async function toImportedFinding(candidate, reviewer, taskId, plan) {
+    const content = await plan.context.readFile(candidate.file).catch(() => undefined);
+    const existingCode = candidate.snippet ?? quoteFrom(content, candidate.lines);
+    if (!existingCode)
+        return undefined;
+    const reported = boundFinding({
+        category: reviewer,
+        severity: candidate.severity,
+        file: candidate.file,
+        existingCode,
+        title: candidate.title,
+        body: candidate.body,
+        evidence: [],
+    });
+    // The tool's lines are not trusted over the quote: the same anchoring as
+    // for a model's finding decides where the comment lands.
+    const anchor = await anchorFinding(reported, {
+        diffs: plan.selected,
+        readNewFile: plan.context.readFile,
+    });
+    return toFinding(reported, reviewer, { task: taskId }, anchor, content);
+}
+function quoteFrom(content, lines) {
+    if (content === undefined)
+        return undefined;
+    const quote = content
+        .split("\n")
+        .slice(lines.start - 1, lines.end)
+        .join("\n")
+        .trim();
+    return quote || undefined;
+}
+// The new-side lines each hunk covers, context included.
+function changedLines(diffs) {
+    const windows = new Map();
+    for (const diff of diffs) {
+        const ranges = diff.hunks
+            .filter((h) => h.newLines > 0)
+            .map((h) => ({ start: h.newStart, end: h.newStart + h.newLines - 1 }));
+        if (ranges.length > 0)
+            windows.set(diff.newPath, ranges);
+    }
+    return windows;
+}
+function touches(windows, candidate) {
+    const ranges = windows.get(candidate.file);
+    if (!ranges)
+        return false;
+    return ranges.some((r) => candidate.lines.start <= r.end && candidate.lines.end >= r.start);
+}
+function importWarnings(tool, c) {
+    const left = [];
+    if (c.outside > 0)
+        left.push(`${c.outside} outside the change`);
+    if (c.overLimit > 0)
+        left.push(`${c.overLimit} over the limit of ${MAX_IMPORTED_PER_RUN} per run`);
+    if (c.noCode > 0)
+        left.push(`${c.noCode} on lines that could not be read`);
+    if (c.noLocation > 0)
+        left.push(`${c.noLocation} without a file and lines`);
+    if (c.unsupportedUri > 0)
+        left.push(`${c.unsupportedUri} on paths outside the repository`);
+    if (c.noMessage > 0)
+        left.push(`${c.noMessage} without a message`);
+    if (left.length === 0)
+        return [];
+    return [`${tool}: imported ${c.imported} result(s); left out ${left.join(", ")}`];
+}
+//# sourceMappingURL=imports.js.map

package/dist/pipeline/matrix.d.ts

@@ -1,10 +1,13 @@
+import { z } from "zod";
 import type { Bundle } from "../bundle/bundle.js";
+import type { Effort } from "../contracts.js";
 import type { RiskTier } from "../domain.js";
 import type { ReviewerDefinition } from "../review/reviewer.js";
 export declare const RISK_TIERS: readonly RiskTier[];
 export interface ReviewerOverride {
     enabled?: boolean | undefined;
     minTier?: RiskTier | undefined;
+    effort?: Effort | undefined;
 }
 export type ReviewerOverrides = Readonly<Record<string, ReviewerOverride>>;
 export interface MatrixCell {
@@ -12,7 +15,14 @@ export interface MatrixCell {
     reviewer: ReviewerDefinition;
     bundle: Bundle;
 }
-export type SkipReason = "disabled" | "below_tier" | "no_matching_files" | "no_guidelines" | "task_limit";
+export declare const skipReasonSchema: z.ZodEnum<{
+    below_tier: "below_tier";
+    disabled: "disabled";
+    no_guidelines: "no_guidelines";
+    no_matching_files: "no_matching_files";
+    task_limit: "task_limit";
+}>;
+export type SkipReason = z.infer<typeof skipReasonSchema>;
 export interface SkippedCell {
     reviewer: string;
     bundle: string;

package/dist/pipeline/matrix.js

@@ -1,5 +1,13 @@
 import picomatch from "picomatch";
+import { z } from "zod";
 export const RISK_TIERS = ["trivial", "lite", "full"];
+export const skipReasonSchema = z.enum([
+    "disabled",
+    "below_tier",
+    "no_matching_files",
+    "no_guidelines",
+    "task_limit",
+]);
 // Deterministic: which reviewer runs on which bundle, so cost grows with the
 // risk of the change instead of bundles × reviewers.
 export function planMatrix(bundles, reviewers, tier, overrides = {}, options = {}) {