@open-cr-agent/core 0.1.1 → 0.2.0

package/dist/pipeline/budget.d.ts

@@ -1,5 +1,8 @@
 import type { Usage } from "../contracts.js";
 export declare const REVIEW_BUDGET_SHARE = 0.8;
+export declare class SpendLimitReached extends Error {
+    constructor(maxCostUsd: number);
+}
 export interface SpendTracker {
     reviewExhausted(): boolean;
     exhausted(): boolean;

package/dist/pipeline/budget.js

@@ -2,9 +2,17 @@
 // 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
 // call, while every agent step resends a task's whole conversation, so a fifth
-// covers them in typical runs. The reserve also absorbs review tasks that were
-// already running when their share ran out.
+// covers them in typical runs. Review tasks still running when their share
+// runs out are stopped; what they spend while stopping (the step in flight,
+// 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 {
+    constructor(maxCostUsd) {
+        super(`stopped at the spend limit of $${maxCostUsd}`);
+        this.name = "SpendLimitReached";
+    }
+}
 export function spendTracker(maxCostUsd, initial) {
     let spent = initial.reduce((sum, u) => sum + u.costUsd, 0);
     const over = (limit) => maxCostUsd !== undefined && spent >= limit;

package/dist/pipeline/execute.d.ts

@@ -19,6 +19,7 @@ export interface ExecuteOptions {
     relocate?: AnchorContext["relocate"] | undefined;
     plans?: Map<string, Promise<PlannedBundle>>;
     emit: (event: ReviewEvent) => void;
+    onUsage?: ((usage: Usage) => void) | undefined;
     signal: AbortSignal;
 }
 type PlannedBundle = Awaited<ReturnType<typeof planBundle>>;

package/dist/pipeline/execute.js

@@ -43,6 +43,8 @@ export async function runJob(job, plan, options) {
         // The sample that made the call pays for it and reports its warning.
         if (!shared) {
             extraUsage.push(...planned.usage);
+            for (const usage of planned.usage)
+                options.onUsage?.(usage);
             if (planned.warning)
                 extraWarnings.push(planned.warning);
         }
@@ -66,6 +68,7 @@ export async function runJob(job, plan, options) {
         timeoutMs: options.taskTimeoutMs,
     }, options.signal, {
         onProgress: (message) => emit({ type: "task_progress", taskId: job.taskId, message }),
+        onUsage: options.onUsage,
         category: job.reviewer.category,
         abortGraceMs: options.abortGraceMs,
     });

package/dist/pipeline/output.d.ts

@@ -55,6 +55,7 @@ export interface ReportOutput {
         files: string[];
     }[];
     anchoring?: AnchoringSummary;
+    spendLimit?: ReviewReport["spendLimit"];
     usage: Usage;
     warnings: string[];
 }

package/dist/pipeline/output.js

@@ -29,6 +29,8 @@ export function toReportOutput(report) {
         output.judgement = report.judgement;
     if (report.anchoring)
         output.anchoring = report.anchoring;
+    if (report.spendLimit)
+        output.spendLimit = report.spendLimit;
     if (report.rereview) {
         const r = report.rereview;
         output.rereview = {

package/dist/pipeline/report.d.ts

@@ -13,7 +13,10 @@ export type CoverageEntry = {
     status: "excluded";
     reason: ExclusionReason;
 };
-export declare function coverageGaps(coverage: readonly CoverageEntry[]): {
+export declare function coverageGaps(run: {
+    coverage: readonly CoverageEntry[];
+    tasks: readonly Pick<TaskOutcome, "status">[];
+}): {
     notReviewed: number;
     nothingReviewed: boolean;
 };
@@ -60,6 +63,10 @@ export interface ReviewReport {
         dismissed: PriorFinding[];
     };
     anchoring?: AnchoringSummary;
+    spendLimit?: {
+        usd: number;
+        reached?: "review" | "total";
+    };
     usage: Usage;
     warnings: string[];
 }

package/dist/pipeline/report.js

@@ -1,11 +1,14 @@
 // How much of the selection this run actually reviewed. Every surface (exit
 // code, terminal, pull request summary) reads it from here, so none of them
 // can call a run that reviewed nothing "approved".
-export function coverageGaps(coverage) {
-    const notReviewed = coverage.filter((c) => c.status === "failed" || c.status === "unreviewed").length;
+export function coverageGaps(run) {
+    const notReviewed = run.coverage.filter((c) => c.status === "failed" || c.status === "unreviewed").length;
     // Unchanged files were reviewed by an earlier run, and their findings and
     // verdict carry over: a re-review whose new files all failed still has them.
-    const reviewed = coverage.some((c) => c.status === "reviewed" || c.status === "unchanged");
+    // A file stays failed while any of its reviewers failed, so a reviewer that
+    // finished its tasks has still reviewed something (#263).
+    const reviewed = run.coverage.some((c) => c.status === "reviewed" || c.status === "unchanged") ||
+        run.tasks.some((t) => t.status === "completed");
     return { notReviewed, nothingReviewed: notReviewed > 0 && !reviewed };
 }
 export function summarizeAnchoring(findings, relocationCalls) {

package/dist/pipeline/run.js

@@ -6,14 +6,14 @@ import { priorCodePresence } from "../rereview/presence.js";
 import { reconcile, stillOpen } from "../rereview/reconcile.js";
 import { correctnessReviewer } from "../review/reviewers/correctness.js";
 import { markUnchecked, verifyFindings } from "../verify/verify.js";
-import { spendTracker } from "./budget.js";
+import { SpendLimitReached, spendTracker } from "./budget.js";
 import { runJob } from "./execute.js";
 import { dedupeFindings } from "./findings.js";
 import { DEFAULT_MAX_TASKS, planTasks } from "./matrix.js";
 import { planReview } from "./plan.js";
 import { mapWithConcurrency } from "./pool.js";
 import { coverageGaps, summarizeAnchoring, } from "./report.js";
-import { addUsage, emptyUsage } from "./usage.js";
+import { addUsage, emptyUsage, unpricedCalls } from "./usage.js";
 export { GUIDELINES_PATH } from "./plan.js";
 const DEFAULTS = { concurrency: 4, taskTimeoutMs: 10 * 60_000, runTimeoutMs: 25 * 60_000 };
 // Plan (deterministic stages) → execute (one agent task per cell) → report.
@@ -52,6 +52,15 @@ export async function runReview(options) {
                 relocationUsage.push(u);
                 budget.add(u);
             }));
+    // Tasks report spend while they run, so the one that uses up the review
+    // share stops every task still running, not only the ones not yet started.
+    const spendLimit = new AbortController();
+    const spend = (usage) => {
+        budget.add(usage);
+        if (budget.reviewExhausted() && !spendLimit.signal.aborted) {
+            spendLimit.abort(new SpendLimitReached(options.maxCostUsd ?? 0));
+        }
+    };
     const execute = {
         runtime: options.runtime,
         taskTimeoutMs: options.taskTimeoutMs ?? DEFAULTS.taskTimeoutMs,
@@ -62,25 +71,34 @@ export async function runReview(options) {
         ultra: options.ultra === true,
         plans: new Map(),
         emit,
-        signal,
+        onUsage: spend,
+        signal: AbortSignal.any([signal, spendLimit.signal]),
     };
+    // Tasks that never started leave their files unreviewed, not failed.
+    const notStarted = new Set();
+    let unaffordable = 0;
     const results = await mapWithConcurrency(matrix.cells, options.concurrency ?? DEFAULTS.concurrency, async (cell) => {
         // Once the run is cancelled or timed out, remaining cells are not started.
-        if (signal.aborted)
+        if (signal.aborted) {
+            notStarted.add(cell.taskId);
             return skipCell(cell, "run cancelled before this task started", emit);
+        }
         if (budget.reviewExhausted()) {
+            notStarted.add(cell.taskId);
+            unaffordable += 1;
             return skipCell(cell, `spend limit of $${options.maxCostUsd} reached`, emit);
         }
-        const result = await runJob(cell, plan, execute);
-        budget.add(result.usage);
-        return result;
+        return runJob(cell, plan, execute);
     });
+    if (unaffordable > 0) {
+        plan.warnings.push(`spend limit of $${options.maxCostUsd} reached: ${unaffordable} review task(s) did not start; their files are reported as not reviewed`);
+    }
     // Memory and the previous review filter first, so Verify and Judge are not
     // paid for findings that will not be reported, and a person's dismissal
     // keeps a finding out of the verdict whatever the models say.
     const concurrency = options.concurrency ?? DEFAULTS.concurrency;
     const found = dedupeFindings(results.flatMap((r) => r.findings));
-    const fileCoverage = coverage(plan.decisions, results, plan.unchanged, matrix.limited ?? []);
+    const fileCoverage = coverage(plan.decisions, results, plan.unchanged, matrix.limited ?? [], notStarted);
     const remembered = applyMemory(found, plan.memory);
     const reported = new Set(found.map((f) => f.fingerprint));
     const priorReview = withoutRemembered(prior.review, plan.memory);
@@ -129,12 +147,22 @@ export async function runReview(options) {
     if (judgeWanted && !judgeAffordable) {
         judged.warnings.push(`spend limit of $${options.maxCostUsd} reached: findings were not judged`);
     }
-    const { nothingReviewed } = coverageGaps(fileCoverage);
+    const { nothingReviewed } = coverageGaps({
+        coverage: fileCoverage,
+        tasks: results.map((r) => r.outcome),
+    });
     if (!nothingReviewed) {
         emit(judged.decisions
             ? { type: "judge_finished", verdict: judged.verdict, judgement: judged.decisions }
             : { type: "judge_finished", verdict: judged.verdict });
     }
+    const calls = [
+        ...plan.usage,
+        ...results.map((r) => r.usage),
+        ...relocationUsage,
+        ...verification.usage,
+        ...judged.usage,
+    ];
     const report = {
         changeRequest: plan.changeRequest,
         tier: plan.tier,
@@ -152,14 +180,9 @@ export async function runReview(options) {
         unverifiedCriticals: countMissedCriticals(verification.kept, verification.missed),
         refuted: verification.refuted,
         remembered: remembered.remembered,
-        usage: sumUsage([
-            ...plan.usage,
-            ...results.map((r) => r.usage),
-            ...relocationUsage,
-            ...verification.usage,
-            ...judged.usage,
-        ]),
+        usage: sumUsage(calls),
         warnings: [
+            ...unpricedWarning(calls),
             ...plan.warnings,
             ...results.flatMap((r) => r.warnings),
             ...verification.warnings,
@@ -168,6 +191,14 @@ export async function runReview(options) {
     };
     if (judged.decisions)
         report.judgement = judged.decisions;
+    if (options.maxCostUsd !== undefined) {
+        const reached = budget.exhausted()
+            ? "total"
+            : spendLimit.signal.aborted || unaffordable > 0
+                ? "review"
+                : undefined;
+        report.spendLimit = { usd: options.maxCostUsd, ...(reached ? { reached } : {}) };
+    }
     report.anchoring = summarizeAnchoring(report.findings, relocationUsage.length);
     if (prior.review) {
         report.rereview = {
@@ -239,18 +270,20 @@ async function loadPriorReview(vcs) {
         return { warning: `could not load the previous review: ${errorMessage(error)}` };
     }
 }
-function coverage(decisions, results, unchanged, limited) {
+function coverage(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 the task limit
-    // never started makes it "unreviewed".
+    // 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);
-            ran.add(k);
+            if (started)
+                ran.add(k);
             done.set(k, done.get(k) === true || outcome.status === "completed");
         }
     }
@@ -286,6 +319,14 @@ function sortFindings(findings) {
         a.file.localeCompare(b.file) ||
         (a.lineRange?.start ?? 0) - (b.lineRange?.start ?? 0));
 }
+function unpricedWarning(calls) {
+    const unpriced = unpricedCalls(calls);
+    return unpriced > 0
+        ? [
+            `${unpriced} model call(s) used tokens but reported no cost: their model has no price, so the reported cost and the spend limit do not count them`,
+        ]
+        : [];
+}
 function sumUsage(usages) {
     return usages.reduce(addUsage, emptyUsage());
 }

package/dist/pipeline/task.d.ts

@@ -10,6 +10,7 @@ export interface TaskResult {
 }
 export interface TaskCallbacks {
     onProgress(message: string): void;
+    onUsage?: ((usage: Usage) => void) | undefined;
     category: string;
     abortGraceMs?: number | undefined;
 }

package/dist/pipeline/task.js

@@ -1,5 +1,6 @@
 import { reportedFindingSchema } from "../domain.js";
 import { errorMessage } from "../errors.js";
+import { SpendLimitReached } from "./budget.js";
 import { addUsage, emptyUsage } from "./usage.js";
 export async function executeTask(runtime, spec, runSignal, callbacks) {
     const timeout = AbortSignal.timeout(spec.timeoutMs);
@@ -30,9 +31,20 @@ export async function executeTask(runtime, spec, runSignal, callbacks) {
         if (signal.aborted) {
             const timedOut = timeout.aborted && !runSignal.aborted;
             result.status = timedOut ? "timed_out" : "cancelled";
-            result.error = timedOut ? `timed out after ${spec.timeoutMs}ms` : "run cancelled";
-            if (iterator)
-                await collectAfterAbort(iterator, pending, result, callbacks);
+            result.error = timedOut
+                ? `timed out after ${spec.timeoutMs}ms`
+                : runSignal.reason instanceof SpendLimitReached
+                    ? runSignal.reason.message
+                    : "run cancelled";
+            const ending = iterator
+                ? await collectAfterAbort(iterator, pending, result, callbacks)
+                : undefined;
+            // The task's last usage report crossed the limit, and it finished
+            // anyway: its review is complete.
+            if (ending === "done" && runSignal.reason instanceof SpendLimitReached) {
+                result.status = "completed";
+                delete result.error;
+            }
             void iterator?.return?.();
         }
         else {
@@ -54,18 +66,19 @@ async function collectAfterAbort(iterator, pending, result, callbacks) {
         for (;;) {
             const event = await untilAborted(next, grace);
             if (event.done)
-                return;
+                return undefined;
             const { value } = event;
             if (value.type === "usage" || value.type === "finding")
                 handle(value, result, callbacks);
             if (value.type === "done" || value.type === "error")
-                return;
+                return value.type;
             next = iterator.next();
         }
     }
     catch {
         // The runtime did not finish within the grace period, or failed: keep
         // what arrived.
+        return undefined;
     }
 }
 function handle(event, result, callbacks) {
@@ -88,9 +101,12 @@ function handle(event, result, callbacks) {
             }
             return false;
         }
-        case "usage":
-            result.usage = addUsage(result.usage, event);
+        case "usage": {
+            const { type: _type, taskId: _taskId, ...usage } = event;
+            result.usage = addUsage(result.usage, usage);
+            callbacks.onUsage?.(usage);
             return false;
+        }
         case "done":
             return true;
         case "error":

package/dist/pipeline/usage.d.ts

@@ -1,4 +1,5 @@
 import type { Usage } from "../contracts.js";
 export declare function emptyUsage(): Usage;
 export declare function addUsage(total: Usage, next: Usage): Usage;
+export declare function unpricedCalls(usages: readonly Usage[]): number;
 //# sourceMappingURL=usage.d.ts.map

package/dist/pipeline/usage.js

@@ -10,4 +10,10 @@ export function addUsage(total, next) {
         costUsd: total.costUsd + next.costUsd,
     };
 }
+// Calls that used tokens but cost nothing: their model has no price (a
+// declared model priced at 0, or one missing from the pricing catalog), so
+// reported cost and the spend limit cannot count them.
+export function unpricedCalls(usages) {
+    return usages.filter((u) => u.inputTokens + u.outputTokens > 0 && u.costUsd === 0).length;
+}
 //# sourceMappingURL=usage.js.map

package/dist/plugin/types.d.ts

@@ -11,6 +11,17 @@ export interface RuntimeOptions {
     models: ModelChains;
     tools: readonly ToolDefinition[];
     env: Env;
+    providers?: Readonly<Record<string, CustomProvider>>;
+}
+export interface CustomProvider {
+    baseUrl: string;
+    apiKeyEnv?: string;
+    models: Readonly<Record<string, ModelPrice>>;
+}
+export interface ModelPrice {
+    input: number;
+    output: number;
+    cachedInput?: number;
 }
 export type VcsFactory = (options: unknown) => VcsAdapter;
 export type RuntimeFactory = (options: RuntimeOptions) => AgentRuntime;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-cr-agent/core",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Domain types, review pipeline stages and plugin contracts for Open-CR-Agent",
   "keywords": [
     "code-review",