argus-reviewer-e2e 0.1.2 → 0.2.0

package/dist/review/triage.js

@@ -0,0 +1,163 @@
+/**
+ * U7 PR triage lane — one batched `decide` call before chunk review
+ * produces a typed-probability triage record (the pace two-round
+ * pattern). Jev routes and annotates, never gates: every chunk is still
+ * reviewed by a code model and the deterministic verdict stays
+ * authoritative. `decide` failure degrades open — the record lands with
+ * `unadjudicated` and routing keeps the configured (strong) model.
+ *
+ * PR title/body in `state` are untrusted text — Jev is the only
+ * consumer; they never reach the verdict path.
+ */
+import { debug } from '../debug.js';
+import { describeDecisionError, isChoiceAnswer, isNoulAnswer, isScoreAnswer, JEV_DEFAULT_MODEL, } from '../vision/decisions.js';
+// The choice criteria own the vocabulary — TRIAGE_AREAS derives from
+// it so an offered option can never drift out of the record type.
+const RISK_AREA_CRITERIA = {
+    auth: 'authentication, authorization, tokens, sessions, permissions',
+    billing: 'payments, invoices, usage metering, cost accounting',
+    data: 'persistence, migrations, integrity, serialization, caching',
+    ops: 'CI, deploy, infra, configuration, tooling, observability',
+    none: 'no meaningful risk area in this diff',
+};
+export const TRIAGE_AREAS = Object.keys(RISK_AREA_CRITERIA);
+/** Diff excerpt bound — triage needs shape, not full fidelity. */
+const MAX_DIFF_STATE_CHARS = 12_000;
+/** Per-file bound — one huge patch must not starve every other file. */
+const MAX_FILE_EXCERPT = 4_000;
+const MAX_TITLE_CHARS = 300;
+const MAX_BODY_CHARS = 2_000;
+const MAX_FILE_LIST = 100;
+export function buildTriageState(opts) {
+    let budget = MAX_DIFF_STATE_CHARS;
+    const excerpts = [];
+    for (const f of opts.files) {
+        if (budget <= 0)
+            break;
+        if (f.patch === undefined)
+            continue;
+        const take = f.patch.slice(0, Math.min(budget, MAX_FILE_EXCERPT));
+        excerpts.push(take);
+        budget -= take.length;
+    }
+    return {
+        title: (opts.title ?? '').slice(0, MAX_TITLE_CHARS),
+        body: (opts.body ?? '').slice(0, MAX_BODY_CHARS),
+        files: opts.files.slice(0, MAX_FILE_LIST).map((f) => f.filename),
+        totalFiles: opts.files.length,
+        diffExcerpt: excerpts.join('\n\n'),
+    };
+}
+/** Question IDs — one spelling for builder and reader. */
+const Q = { deep: 'needs_deep_review', risk: 'risk', area: 'top_risk_area' };
+function buildTriageQuestions() {
+    return {
+        [Q.deep]: {
+            type: 'noul',
+            instructions: 'does this PR warrant careful review beyond a skim? yes for changes touching ' +
+                'auth, money, data integrity, concurrency, secrets handling, public APIs, or ' +
+                'irreversible ops; no for docs, comments, formatting, or metadata-only changes.',
+        },
+        [Q.risk]: {
+            type: 'score',
+            instructions: 'blast radius if this PR merges broken — pick the closest rubric level.',
+            criteria: [
+                'cosmetic only — docs, comments, formatting, metadata',
+                'minor — internal-only paths, limited blast radius',
+                'moderate — user-visible defects plausible',
+                'high — security-sensitive or data-handling paths touched',
+                'severe — auth, billing, or data-loss surface',
+            ],
+        },
+        [Q.area]: {
+            type: 'choice',
+            instructions: 'the single subsystem most likely to hide a defect in this diff.',
+            criteria: RISK_AREA_CRITERIA,
+        },
+    };
+}
+export async function triagePr(opts) {
+    try {
+        const { answers, model } = await opts.client.decide({
+            ...(opts.model !== undefined ? { model: opts.model } : {}),
+            state: opts.state,
+            questions: buildTriageQuestions(),
+        });
+        const deep = answers[Q.deep];
+        const risk = answers[Q.risk];
+        const area = answers[Q.area];
+        const rec = {
+            mode: opts.mode,
+            model,
+            diffExcerptChars: opts.state.diffExcerpt.length,
+        };
+        if (deep !== undefined && isNoulAnswer(deep))
+            rec.needsDeepReview = deep.noul;
+        if (risk !== undefined && isScoreAnswer(risk))
+            rec.risk = risk.score;
+        if (area !== undefined &&
+            isChoiceAnswer(area) &&
+            TRIAGE_AREAS.includes(area.choice)) {
+            rec.topRiskArea = area.choice;
+            if (area.confidence !== undefined)
+                rec.topRiskAreaConfidence = area.confidence;
+        }
+        // A call that answered none of the typed questions adjudicated nothing.
+        if (rec.needsDeepReview === undefined &&
+            rec.risk === undefined &&
+            rec.topRiskArea === undefined) {
+            rec.unadjudicated = true;
+        }
+        return rec;
+    }
+    catch (e) {
+        debug('triage', `adjudication failed — degrading to annotate: ${describeDecisionError(e)}`);
+        return { mode: opts.mode, model: opts.model ?? JEV_DEFAULT_MODEL, unadjudicated: true };
+    }
+}
+/**
+ * 'route' mode model selection — cheap tier only on a clear low-risk
+ * signal (risk ≤ 2 AND deep-review < 0.5) backed by actual diff
+ * evidence. Any ambiguity (missing fields, unadjudicated, unset
+ * lowRiskModel, or a title/body-only triage — fully attacker-steerable
+ * text) keeps the configured model: coverage stays constant and the
+ * expensive path is the default.
+ */
+export function routeModel(opts) {
+    const rec = opts.record;
+    if (rec === undefined ||
+        rec.mode !== 'route' ||
+        rec.unadjudicated === true ||
+        opts.lowRiskModel === undefined ||
+        rec.risk === undefined ||
+        rec.needsDeepReview === undefined ||
+        (rec.diffExcerptChars ?? 0) === 0) {
+        return { model: opts.configured, reason: 'no routing signal' };
+    }
+    if (rec.risk <= 2 && rec.needsDeepReview < 0.5) {
+        return {
+            model: opts.lowRiskModel,
+            reason: `low risk — risk=${rec.risk}, needsDeepReview=${rec.needsDeepReview.toFixed(2)}`,
+        };
+    }
+    return {
+        model: opts.configured,
+        reason: `risk=${rec.risk}, needsDeepReview=${rec.needsDeepReview.toFixed(2)}`,
+    };
+}
+/**
+ * U9 — the probe lane's advisory ordering signal. Present only when
+ * triage adjudicated a real area with its confidence attached; 'none'
+ * is the null-area sentinel, not an ordering signal, and the
+ * confidence floor itself is queue policy (MIN_AREA_CONFIDENCE).
+ */
+export function triageAreaSignal(rec) {
+    if (rec === undefined ||
+        rec.unadjudicated === true ||
+        rec.topRiskArea === undefined ||
+        rec.topRiskArea === 'none' ||
+        rec.topRiskAreaConfidence === undefined) {
+        return undefined;
+    }
+    return { area: rec.topRiskArea, confidence: rec.topRiskAreaConfidence };
+}

package/dist/trust.d.ts

@@ -0,0 +1,50 @@
+import type { PrMeta } from './evidence/ci.js';
+/**
+ * Checkout trust — decided BEFORE `loadConfig` runs, because loading a
+ * PR-controlled `argus-reviewer.config.ts` executes arbitrary code beside
+ * `OPENROUTER_API_KEY`/`GITHUB_TOKEN` (#58).
+ *
+ * Trust keys on fork status of the checked-out tree, never on
+ * `author_association` — a MEMBER can author a hostile fork PR.
+ */
+export type Trust = 'trusted' | 'untrusted';
+export interface TrustResult {
+    trust: Trust;
+    reason: string;
+    /**
+     * PR number derived from the event payload on `issue_comment` events
+     * (`issue.number` when the issue is a PR). Undefined otherwise — the
+     * caller's own repo/pr derivation still applies.
+     */
+    pr: string | undefined;
+}
+export interface ResolveTrustOpts {
+    env: Record<string, string | undefined>;
+    /**
+     * Fetches PR metadata — required only on `issue_comment` (the payload has
+     * no `head.repo.fork`) and as a fallback when a `pull_request*` payload
+     * is unreadable. Injectable for tests.
+     */
+    fetchMeta?: (repo: string, pr: string, token: string) => Promise<PrMeta | undefined>;
+    /** Injectable event-payload reader for tests. Defaults to node fs. */
+    readEventFile?: (path: string) => Promise<string>;
+    /** Human-readable note on the resolved decision (e.g. ctx.err). */
+    note?: (line: string) => void;
+}
+/**
+ * Resolves whether the checked-out tree may execute config code.
+ *
+ * - `pull_request*` events: fork status from the event payload — no token
+ *   needed (`head.repo.fork`). Payload absent/unreadable → `fetchMeta`
+ *   fallback → still unknown → untrusted.
+ * - `issue_comment`: `fetchMeta` on `issue.number`; unavailable → untrusted.
+ * - Any other present `GITHUB_EVENT_NAME` (`workflow_run`, `push`,
+ *   `workflow_dispatch`, …): untrusted — unlisted CI events fail closed
+ *   because privileged-CI-over-fork-checkout patterns (workflow_run over a
+ *   fork SHA) land exactly there. Maintainers opt out explicitly with
+ *   `ARGUS_TRUSTED=1`.
+ * - No event env at all (local run): trusted unless `ARGUS_UNTRUSTED=1`.
+ * - `ARGUS_UNTRUSTED=1` always wins; `ARGUS_TRUSTED=1` overrides event
+ *   resolution but never `ARGUS_UNTRUSTED`.
+ */
+export declare function resolveTrust(opts: ResolveTrustOpts): Promise<TrustResult>;

package/dist/trust.js

@@ -0,0 +1,103 @@
+import { readFile } from 'node:fs/promises';
+async function readEventPayload(env, readEventFile) {
+    const eventPath = env.GITHUB_EVENT_PATH;
+    if (eventPath === undefined || eventPath === '')
+        return undefined;
+    try {
+        const parsed = JSON.parse(await readEventFile(eventPath));
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return undefined;
+        }
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+function tracePr(env) {
+    const raw = env.ARGUS_REVIEWER_TRACE;
+    if (raw === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        return typeof parsed.pr === 'string' && parsed.pr !== '' ? parsed.pr : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function fetchMetaFor(opts, prOverride) {
+    const { env, fetchMeta } = opts;
+    if (fetchMeta === undefined)
+        return undefined;
+    const repo = env.GITHUB_REPOSITORY;
+    const token = env.GITHUB_TOKEN ?? env.GH_TOKEN;
+    const pr = prOverride ?? tracePr(env);
+    if (repo === undefined || token === undefined || pr === undefined)
+        return undefined;
+    return fetchMeta(repo, pr, token);
+}
+/**
+ * Resolves whether the checked-out tree may execute config code.
+ *
+ * - `pull_request*` events: fork status from the event payload — no token
+ *   needed (`head.repo.fork`). Payload absent/unreadable → `fetchMeta`
+ *   fallback → still unknown → untrusted.
+ * - `issue_comment`: `fetchMeta` on `issue.number`; unavailable → untrusted.
+ * - Any other present `GITHUB_EVENT_NAME` (`workflow_run`, `push`,
+ *   `workflow_dispatch`, …): untrusted — unlisted CI events fail closed
+ *   because privileged-CI-over-fork-checkout patterns (workflow_run over a
+ *   fork SHA) land exactly there. Maintainers opt out explicitly with
+ *   `ARGUS_TRUSTED=1`.
+ * - No event env at all (local run): trusted unless `ARGUS_UNTRUSTED=1`.
+ * - `ARGUS_UNTRUSTED=1` always wins; `ARGUS_TRUSTED=1` overrides event
+ *   resolution but never `ARGUS_UNTRUSTED`.
+ */
+export async function resolveTrust(opts) {
+    const { env, note } = opts;
+    const readEventFile = opts.readEventFile ?? ((p) => readFile(p, 'utf8'));
+    const done = (trust, reason, pr) => {
+        note?.(`trust: ${trust} — ${reason}`);
+        return { trust, reason, pr };
+    };
+    if (env.ARGUS_UNTRUSTED === '1') {
+        return done('untrusted', 'ARGUS_UNTRUSTED=1');
+    }
+    if (env.ARGUS_TRUSTED === '1') {
+        return done('trusted', 'ARGUS_TRUSTED=1 override');
+    }
+    const eventName = env.GITHUB_EVENT_NAME;
+    if (eventName === undefined || eventName === '') {
+        return done('trusted', 'local run — no CI event context');
+    }
+    const payload = await readEventPayload(env, readEventFile);
+    if (eventName === 'pull_request' || eventName === 'pull_request_target') {
+        const fork = payload?.pull_request?.head?.repo?.fork;
+        if (fork === true)
+            return done('untrusted', 'fork PR head checkout');
+        if (fork === false)
+            return done('trusted', 'same-repo PR checkout');
+        // Payload absent/unreadable (or head.repo null — a deleted source fork
+        // fails closed the same way evidence/ci.ts's isFork does): try the API.
+        const meta = await fetchMetaFor(opts);
+        if (meta !== undefined) {
+            return meta.isFork
+                ? done('untrusted', 'fork PR (metadata)')
+                : done('trusted', 'same-repo PR (metadata)');
+        }
+        return done('untrusted', 'PR fork status unavailable — failing closed');
+    }
+    if (eventName === 'issue_comment') {
+        const pr = payload?.issue?.pull_request !== undefined && typeof payload.issue?.number === 'number'
+            ? String(payload.issue.number)
+            : undefined;
+        const meta = await fetchMetaFor(opts, pr);
+        if (meta !== undefined) {
+            return meta.isFork
+                ? done('untrusted', 'issue_comment on fork PR', pr)
+                : done('trusted', 'issue_comment on same-repo PR', pr);
+        }
+        return done('untrusted', 'issue_comment PR metadata unavailable — failing closed', pr);
+    }
+    return done('untrusted', `unlisted CI event "${eventName}" — failing closed`);
+}

package/dist/vision/cost.d.ts

@@ -1,4 +1,4 @@
-export type CallKind = 'ground' | 'heal' | 'assert' | 'code';
+export type CallKind = 'ground' | 'heal' | 'assert' | 'code' | 'decide';
 export interface CallCost {
     model: string;
     provider: string;
@@ -30,6 +30,19 @@ export interface OpenRouterResponse {
     usage: Usage;
 }
 export declare function makeCallCost(response: OpenRouterResponse, kind: CallKind): CallCost;
+/** Decisions API (`/api/alpha/decisions`) usage shape — no `cost_details`. */
+export interface DecisionsResponse {
+    id?: string;
+    model?: string;
+    provider?: ProviderValue;
+    answers?: Record<string, unknown>;
+    usage?: {
+        input_tokens?: number;
+        output_tokens?: number;
+        cost?: number;
+    };
+}
+export declare function makeDecisionsCallCost(response: DecisionsResponse, kind: CallKind): CallCost;
 export declare function extractUsageCost(response: OpenRouterResponse): {
     costUsd: number;
     upstreamCostUsd: number;

package/dist/vision/cost.js

@@ -8,6 +8,19 @@ export function makeCallCost(response, kind) {
         kind,
     };
 }
+export function makeDecisionsCallCost(response, kind) {
+    const providerName = typeof response.provider === 'string' ? response.provider : response.provider?.name ?? 'unknown';
+    const usage = response.usage ?? {};
+    // Coerce — a string cost would throw downstream at toFixed and discard
+    // a valid decision; a string token count would concatenate.
+    return {
+        model: response.model ?? 'unknown',
+        provider: providerName,
+        tokens: (Number(usage.input_tokens) || 0) + (Number(usage.output_tokens) || 0),
+        costUsd: Number(usage.cost) || 0,
+        kind,
+    };
+}
 export function extractUsageCost(response) {
     return {
         costUsd: response.usage.cost,

package/dist/vision/decisions.d.ts

@@ -0,0 +1,95 @@
+import type { CallCost, ProviderValue } from './cost.js';
+/**
+ * Pinned Jev slug — the alias `~typesafe/jev-latest` drifts silently and
+ * adjudication thresholds are calibrated to a version. The alias stays
+ * usable via `config.decisionModel` for experimentation.
+ */
+export declare const JEV_DEFAULT_MODEL = "typesafe/jev-1.13-20260917";
+export type DecisionErrorKind = 'auth' | 'validation' | 'rate_limited' | 'overloaded' | 'server_error' | 'timeout' | 'unexpected';
+export declare class DecisionError extends Error {
+    readonly kind: DecisionErrorKind;
+    readonly retryable: boolean;
+    constructor(kind: DecisionErrorKind, message: string, retryable: boolean);
+}
+export interface NoulQuestion {
+    type: 'noul';
+    instructions: string;
+    /** Optional yes/no clarifications, sent verbatim. */
+    true?: string;
+    false?: string;
+}
+export interface ChoiceQuestion {
+    type: 'choice';
+    instructions: string;
+    /** Option ID -> description. Up to 255 options. */
+    criteria: Record<string, string>;
+}
+export interface ScoreQuestion {
+    type: 'score';
+    instructions: string;
+    /** 2-10 ordered rubric levels, low to high. */
+    criteria: string[];
+}
+export type DecisionQuestion = NoulQuestion | ChoiceQuestion | ScoreQuestion;
+export interface NoulAnswer {
+    noul: number;
+}
+export interface ChoiceAnswer {
+    choice: string;
+    probabilities?: Record<string, number>;
+    confidence?: number;
+}
+export interface ScoreAnswer {
+    score: number;
+    legend?: string[];
+    probabilities?: number[];
+    confidence?: number;
+}
+export type DecisionAnswer = NoulAnswer | ChoiceAnswer | ScoreAnswer;
+/** Type guards over the answer union — one `in` check per lane otherwise. */
+export declare const isNoulAnswer: (a: DecisionAnswer) => a is NoulAnswer;
+export declare const isChoiceAnswer: (a: DecisionAnswer) => a is ChoiceAnswer;
+export declare const isScoreAnswer: (a: DecisionAnswer) => a is ScoreAnswer;
+/** Short error label for lane debug lines: DecisionError kind, else message. */
+export declare function describeDecisionError(e: unknown): string;
+/** Shared per-call batch cap for the Jev lanes (secrets, findings, triage). */
+export declare const MAX_CANDIDATES = 50;
+export interface DecisionClientOptions {
+    apiKey: string;
+    fetch?: typeof fetch;
+    trace?: Record<string, string>;
+    /** Request timeout in ms. Default 15_000. */
+    timeoutMs?: number;
+    onCall?: (call: {
+        id: string;
+        model: string;
+        provider: string;
+        kind: 'decide';
+        costUsd: number;
+        tokens: number;
+        trace?: Record<string, string>;
+    }) => void;
+}
+export declare class DecisionClient {
+    private _apiKey;
+    private _fetch;
+    private _trace;
+    private _timeoutMs;
+    private _onCall;
+    constructor(opts: DecisionClientOptions);
+    /**
+     * Ask typed questions about `state`. Throws a typed `DecisionError` on
+     * any failure — callers catch and degrade to unadjudicated; a decision
+     * failure must never suppress findings (KTD6).
+     */
+    decide(opts: {
+        model?: string;
+        state: unknown;
+        questions: Record<string, DecisionQuestion>;
+    }): Promise<{
+        answers: Record<string, DecisionAnswer>;
+        cost: CallCost;
+        model: string;
+    }>;
+}
+export type { ProviderValue };