argus-reviewer-e2e 0.1.2

package/dist/config.d.ts

@@ -0,0 +1,130 @@
+export interface ProviderRules {
+    only?: string[];
+    ignore?: string[];
+    order?: string[];
+    allow_fallbacks?: boolean;
+    require_parameters?: boolean;
+}
+export interface Target {
+    command: string;
+    url: string;
+    readyTimeoutMs: number;
+}
+export interface Config {
+    model: string;
+    escalation_model: string;
+    /**
+     * Optional specialist model for grounding-correction retries (e.g. a
+     * ui-tars-class model that returns bare coordinates). Used only when the
+     * primary model's proposed point resolves to the wrong element.
+     */
+    grounding_model: string | undefined;
+    /**
+     * Optional code review model. Used by `argus-reviewer code-review` to review
+     * PR diffs and post findings. Defaults to the primary `model` if not set.
+     */
+    code_model: string | undefined;
+    /**
+     * Hard budget for the `argus-reviewer code-review` lane. When set, the
+     * review stops early if the cumulative OpenRouter cost exceeds this cap.
+     */
+    codeReviewBudgetUsd: number | undefined;
+    provider: ProviderRules;
+    budgetUsd: number | undefined;
+    target: Target | undefined;
+    cacheDir: string | undefined;
+    /** Directory scanned by `argus-reviewer run` for *.test.* files. */
+    testsDir: string | undefined;
+    /** Directory for JUnit XML + JSON run report output. */
+    reportDir: string | undefined;
+    /**
+     * Named secrets for `td.type(name, { secret: true })`. The value is typed
+     * locally and never sent to the model — the model only resolves the field.
+     */
+    secrets: Record<string, string> | undefined;
+    /**
+     * Optional module path (resolved from cwd) whose default export is invoked
+     * with the Playwright `Page` after the driver launches and before any
+     * navigation — the seam for `page.route` mocks, tenant seeding, and other
+     * pre-navigation setup.
+     */
+    pageSetup: string | undefined;
+    /**
+     * OpenRouter request metadata. `trace` is sent in the request body and
+     * can be used to attribute spend by repo, PR, or run. `headers` are
+     * sent verbatim with every OpenRouter request (e.g. HTTP-Referer, X-Title).
+     */
+    openrouter: {
+        trace?: Record<string, string>;
+        headers?: Record<string, string>;
+    } | undefined;
+    /**
+     * Browser engine for Playwright: `chromium`, `firefox`, or `webkit`.
+     * Defaults to `chromium`.
+     */
+    browser: 'chromium' | 'firefox' | 'webkit' | undefined;
+    /**
+     * Hard limit in milliseconds for Playwright cleanup (context + browser close).
+     * Prevents a hung browser from keeping the runner or test suite alive.
+     * Defaults to 30 seconds.
+     */
+    browserTimeoutMs: number | undefined;
+    /**
+     * Severity levels that block a pre-merge status. Defaults to `['bug']` so
+     * `risk`/`nit`/`q` findings are surfaced but do not fail the status.
+     */
+    severity: string[] | undefined;
+    /**
+     * Log verbosity — 'debug'|'info'|'warn'|'error'. ARGUS_DEBUG=1 forces
+     * 'debug'. Default 'warn'.
+     */
+    logLevel: 'debug' | 'info' | 'warn' | 'error' | undefined;
+    /**
+     * Repo globs naming the app surface the tests exercise (e.g. 'ui/src/**').
+     * Diff-aware invalidation marks flow caches stale when the diff touches
+     * files in this surface's dependency cone.
+     */
+    sourceGlobs: string[] | undefined;
+    /** Path (repo-relative) for the generated repo index. Default 'argus.index.json'. */
+    indexPath: string | undefined;
+    /** Base ref for diff invalidation (e.g. 'origin/main'); unset = working tree. */
+    diffBase: string | undefined;
+    /**
+     * Max actions `argus-reviewer record` will take before giving up on `done`.
+     * Real multi-action flows need headroom — defaults to 40; `record
+     * --max-steps <n>` overrides.
+     */
+    recordStepCap: number | undefined;
+    /**
+     * Agent Zero instance for delegated tasks (`argus-reviewer delegate`,
+     * `heal: 'a0'`). `url` is the instance base URL — leave unset to let the
+     * `a0` CLI resolve it (saved host, AGENT_ZERO_HOST, Docker discovery).
+     * Least-privilege scoping (browser vs full desktop) is configured on the
+     * instance's gateway, not here.
+     */
+    a0: {
+        url: string | undefined;
+    } | undefined;
+    /**
+     * Failure escalation for `run`. 'local' (default) heals via the vision
+     * model only. 'a0' additionally sends each failed test to Agent Zero for an
+     * autonomous second opinion — it clicks through the app and reports whether
+     * the app or the expectation is wrong.
+     */
+    heal: 'local' | 'a0' | undefined;
+}
+export type ConfigInput = Partial<Omit<Config, 'provider'>> & {
+    provider?: Partial<ProviderRules>;
+};
+export declare const DEFAULT_RECORD_STEP_CAP = 40;
+export declare function defineConfig(input: ConfigInput): ConfigInput;
+export declare function resolveConfig(input?: ConfigInput): Config;
+export declare function loadConfig(cwd: string): Promise<Config>;
+/**
+ * Provider slugs the harness recognizes for `provider.only/ignore/order`
+ * (KTD4). Unknown slugs warn but do not fail — OpenRouter's catalog changes
+ * faster than this list, so validation is fail-open by design.
+ */
+export declare const KNOWN_PROVIDER_SLUGS: ReadonlySet<string>;
+/** Slugs in the provider rules that are not recognized; callers warn, not fail. */
+export declare function unknownProviderSlugs(provider: ProviderRules): string[];

package/dist/config.js

@@ -0,0 +1,163 @@
+import { pathToFileURL } from 'node:url';
+export const DEFAULT_RECORD_STEP_CAP = 40;
+const defaults = {
+    model: 'google/gemini-2.5-flash-lite',
+    escalation_model: 'moonshotai/kimi-k2.5',
+    grounding_model: undefined,
+    code_model: 'deepseek/deepseek-v4.1-flash',
+    codeReviewBudgetUsd: undefined,
+    provider: {
+        ignore: ['siliconflow', 'novitaai', 'atlascloud', 'streamlake', 'chutes'],
+    },
+    budgetUsd: undefined,
+    target: undefined,
+    cacheDir: undefined,
+    testsDir: undefined,
+    reportDir: undefined,
+    secrets: undefined,
+    pageSetup: undefined,
+    openrouter: undefined,
+    browser: 'chromium',
+    browserTimeoutMs: 30_000,
+    severity: ['bug'],
+    logLevel: undefined,
+    sourceGlobs: undefined,
+    indexPath: undefined,
+    diffBase: undefined,
+    recordStepCap: DEFAULT_RECORD_STEP_CAP,
+    a0: undefined,
+    heal: 'local',
+};
+export function defineConfig(input) {
+    return input;
+}
+export function resolveConfig(input = {}) {
+    const provider = { ...defaults.provider, ...(input.provider ?? {}) };
+    const resolved = { ...defaults, ...input, provider };
+    const cap = resolved.recordStepCap;
+    resolved.recordStepCap =
+        cap !== undefined && Number.isFinite(cap) && cap >= 1
+            ? Math.floor(cap)
+            : DEFAULT_RECORD_STEP_CAP;
+    if (resolved.heal !== 'a0')
+        resolved.heal = 'local';
+    return resolved;
+}
+export async function loadConfig(cwd) {
+    const fs = await import('node:fs/promises');
+    const path = await import('node:path');
+    const names = ['argus-reviewer.config', 'vision-e2e.config'];
+    for (const name of names) {
+        for (const ext of ['.ts', '.json']) {
+            const file = path.join(cwd, `${name}${ext}`);
+            try {
+                const stat = await fs.stat(file);
+                if (!stat.isFile())
+                    continue;
+                if (ext === '.json') {
+                    const raw = await fs.readFile(file, 'utf8');
+                    return resolveConfig(JSON.parse(raw));
+                }
+                // Always transpile .ts to a temp .mjs rather than importing natively:
+                // Node's built-in type stripping resolves the module type from the
+                // *consumer's* package.json, so a CommonJS consumer makes ESM config
+                // fail with 'Cannot use import statement'. The transpiled file is
+                // written next to the config (removed after import) so relative
+                // imports and node_modules resolution behave like the original file;
+                // the package self-import is rewritten to this module's own index so
+                // global/npx installs resolve it too.
+                const ts = await import('typescript');
+                const { readFile, writeFile, rm } = await import('node:fs/promises');
+                const { join, dirname } = await import('node:path');
+                const source = await readFile(file, 'utf8');
+                const js = ts
+                    .transpileModule(source, {
+                    compilerOptions: { module: ts.ModuleKind.ESNext, target: ts.ScriptTarget.ES2022 },
+                })
+                    .outputText.replace(/(['"])argus-reviewer-e2e\1/g, 
+                // package.json exports '.' → dist/api.js (sibling of this file)
+                JSON.stringify(new URL('./api.js', import.meta.url).href));
+                const out = join(dirname(file), `.argus-config-${process.pid}-${Date.now()}.mjs`);
+                let mod;
+                try {
+                    await writeFile(out, js, 'utf8');
+                    mod = (await import(pathToFileURL(out).href));
+                }
+                finally {
+                    await rm(out, { force: true }).catch(() => undefined);
+                }
+                const exported = mod.default ?? mod;
+                return resolveConfig(exported);
+            }
+            catch (e) {
+                const code = e.code;
+                if (code === 'ENOENT')
+                    continue;
+                throw e;
+            }
+        }
+    }
+    return resolveConfig();
+}
+/**
+ * Provider slugs the harness recognizes for `provider.only/ignore/order`
+ * (KTD4). Unknown slugs warn but do not fail — OpenRouter's catalog changes
+ * faster than this list, so validation is fail-open by design.
+ */
+export const KNOWN_PROVIDER_SLUGS = new Set([
+    'ai21',
+    'aion-labs',
+    'alibaba',
+    'amazon-bedrock',
+    'anthropic',
+    'atlascloud',
+    'azure',
+    'bedrock',
+    'cerebras',
+    'chutes',
+    'cloudflare',
+    'cohere',
+    'coreweave',
+    'crusoe',
+    'deepinfra',
+    'deepseek',
+    'featherless',
+    'fireworks',
+    'friendli',
+    'gmicloud',
+    'google',
+    'google-ai-studio',
+    'groq',
+    'hyperbolic',
+    'inception',
+    'inference-net',
+    'lambda',
+    'mistral',
+    'moonshotai',
+    'ncompass',
+    'nebius',
+    'nineteen',
+    'novitaai',
+    'open-inference',
+    'openai',
+    'openrouter',
+    'parasail',
+    'perplexity',
+    'phala',
+    'relace',
+    'sambanova',
+    'siliconflow',
+    'streamlake',
+    'targon',
+    'together',
+    'ubicloud',
+    'venice',
+    'wandb',
+    'xai',
+    'zai',
+]);
+/** Slugs in the provider rules that are not recognized; callers warn, not fail. */
+export function unknownProviderSlugs(provider) {
+    const slugs = [...(provider.only ?? []), ...(provider.ignore ?? []), ...(provider.order ?? [])];
+    return slugs.filter((slug) => !KNOWN_PROVIDER_SLUGS.has(slug.toLowerCase()));
+}

package/dist/debug.d.ts

@@ -0,0 +1 @@
+export declare function debug(kind: string, ...args: unknown[]): void;

package/dist/debug.js

@@ -0,0 +1,30 @@
+import { join } from 'node:path';
+import { liveLog } from './live.js';
+const DEBUG = process.env.ARGUS_DEBUG === '1' || process.env.ARGUS_DEBUG === 'true';
+// debug() has no config access — it lives under the default cache dir.
+const LIVE_DIR = join(process.cwd(), '.argus-reviewer-cache');
+function toMsg(arg) {
+    if (typeof arg === 'string')
+        return arg;
+    try {
+        const s = JSON.stringify(arg);
+        return s === undefined ? String(arg) : s; // JSON.stringify(undefined) -> undefined
+    }
+    catch {
+        return String(arg); // BigInt, cyclic refs — never throw from a debug call
+    }
+}
+export function debug(kind, ...args) {
+    if (!DEBUG)
+        return; // keep debug() free of fs work on the hot path
+    for (const arg of args) {
+        liveLog(LIVE_DIR, kind, 'debug', toMsg(arg));
+        const prefix = `[argus-reviewer:${kind}]`;
+        if (typeof arg === 'string') {
+            console.error(`${prefix} ${arg}`);
+        }
+        else {
+            console.error(prefix, arg);
+        }
+    }
+}

package/dist/detect.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Environment detection for `init` readiness reporting and Agent Zero
+ * resolution. Everything here is best-effort — a missing tool degrades a
+ * feature flag, it never breaks the command.
+ */
+export interface ExecResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export type ExecFn = (cmd: string, args: string[], timeoutMs: number) => Promise<ExecResult>;
+export declare const defaultExec: ExecFn;
+export type ProbeFn = (url: string, timeoutMs: number) => Promise<boolean>;
+/**
+ * Any HTTP response — including a login redirect — means *something* is up,
+ * but port 5080 could be an unrelated service. Require an Agent Zero marker
+ * in the served HTML before trusting the probe result.
+ */
+export declare const defaultProbe: ProbeFn;
+export interface A0Info {
+    /** `a0` CLI version string when the binary is on PATH. */
+    version: string | undefined;
+    /** Resolved instance base URL, if one could be found. */
+    host: string | undefined;
+    hostSource: 'env' | 'dotfile' | 'probe' | undefined;
+}
+export interface EnvironmentReport {
+    /** OPENROUTER_API_KEY is set and non-empty. */
+    openrouterKey: boolean;
+    /** gh CLI authenticated; undefined when gh is not installed at all. */
+    ghAuth: boolean | undefined;
+    /** Playwright engines with a downloaded executable (e.g. 'chromium'). */
+    playwrightBrowsers: string[];
+    a0: A0Info;
+}
+export interface DetectOptions {
+    exec?: ExecFn;
+    home?: string;
+    probe?: ProbeFn;
+}
+/**
+ * Resolve the Agent Zero instance URL the same way the `a0` CLI does:
+ * explicit env var, the launcher-managed ~/.agent-zero/.env, then a probe of
+ * the default local port (http://localhost:5080).
+ */
+export declare function resolveA0Host(env: NodeJS.ProcessEnv, opts?: DetectOptions): Promise<{
+    host: string | undefined;
+    source: A0Info['hostSource'];
+}>;
+export declare function detectEnvironment(env: NodeJS.ProcessEnv, opts?: DetectOptions): Promise<EnvironmentReport>;

package/dist/detect.js

@@ -0,0 +1,105 @@
+import { execFile } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { readdir, readFile } from 'node:fs/promises';
+export const defaultExec = (cmd, args, timeoutMs) => new Promise((resolve) => {
+    execFile(cmd, args, { timeout: timeoutMs }, (err, stdout, stderr) => {
+        if (err) {
+            // stderr is '' (not undefined) on spawn ENOENT — fall back to the
+            // error message so callers can distinguish "missing" from "failed".
+            resolve({ code: 1, stdout: String(stdout), stderr: String(stderr) || err.message });
+        }
+        else {
+            resolve({ code: 0, stdout: String(stdout), stderr: String(stderr) });
+        }
+    });
+});
+/**
+ * Any HTTP response — including a login redirect — means *something* is up,
+ * but port 5080 could be an unrelated service. Require an Agent Zero marker
+ * in the served HTML before trusting the probe result.
+ */
+export const defaultProbe = async (url, timeoutMs) => {
+    try {
+        const res = await fetch(url, {
+            signal: AbortSignal.timeout(timeoutMs),
+            redirect: 'manual',
+        });
+        if (res.status >= 500)
+            return false;
+        const body = (await res.text()).slice(0, 65_536);
+        return /agent.?zero/i.test(body);
+    }
+    catch {
+        return false;
+    }
+};
+/** Read `AGENT_ZERO_HOST` (and friends) out of ~/.agent-zero/.env. */
+async function a0EnvFileHost(home) {
+    try {
+        const raw = await readFile(join(home, '.agent-zero', '.env'), 'utf8');
+        for (const line of raw.split('\n')) {
+            const m = /^AGENT_ZERO_HOST=(\S+)\s*$/.exec(line.trim());
+            if (m?.[1] !== undefined && m[1] !== '')
+                return m[1];
+        }
+    }
+    catch {
+        // no dotfile — fall through
+    }
+    return undefined;
+}
+/**
+ * Resolve the Agent Zero instance URL the same way the `a0` CLI does:
+ * explicit env var, the launcher-managed ~/.agent-zero/.env, then a probe of
+ * the default local port (http://localhost:5080).
+ */
+export async function resolveA0Host(env, opts = {}) {
+    const home = opts.home ?? homedir();
+    const probe = opts.probe ?? defaultProbe;
+    const fromEnv = env.AGENT_ZERO_HOST;
+    if (fromEnv !== undefined && fromEnv !== '')
+        return { host: fromEnv, source: 'env' };
+    const fromFile = await a0EnvFileHost(home);
+    if (fromFile !== undefined)
+        return { host: fromFile, source: 'dotfile' };
+    const local = 'http://localhost:5080';
+    if (await probe(local, 2_000))
+        return { host: local, source: 'probe' };
+    return { host: undefined, source: undefined };
+}
+/** Playwright engines with a downloaded browser under ~/.cache/ms-playwright. */
+async function playwrightBrowsers(home) {
+    try {
+        const entries = await readdir(join(home, '.cache', 'ms-playwright'));
+        const found = new Set();
+        for (const entry of entries) {
+            for (const engine of ['chromium', 'firefox', 'webkit']) {
+                if (entry.startsWith(engine))
+                    found.add(engine);
+            }
+        }
+        return [...found];
+    }
+    catch {
+        return [];
+    }
+}
+export async function detectEnvironment(env, opts = {}) {
+    const exec = opts.exec ?? defaultExec;
+    const home = opts.home ?? homedir();
+    const [a0Version, gh, browsers, a0Host] = await Promise.all([
+        exec('a0', ['--version'], 5_000),
+        exec('gh', ['auth', 'status'], 5_000),
+        playwrightBrowsers(home),
+        resolveA0Host(env, opts),
+    ]);
+    const version = a0Version.code === 0 ? a0Version.stdout.trim() : undefined;
+    const ghMissing = gh.code !== 0 && /ENOENT|not found|no such file/i.test(gh.stderr);
+    return {
+        openrouterKey: env.OPENROUTER_API_KEY !== undefined && env.OPENROUTER_API_KEY !== '',
+        ghAuth: gh.code === 0 ? true : ghMissing ? undefined : false,
+        playwrightBrowsers: browsers,
+        a0: { version, host: a0Host.host, hostSource: a0Host.source },
+    };
+}

package/dist/driver/browser.d.ts

@@ -0,0 +1,64 @@
+import { type Page } from 'playwright';
+export interface Viewport {
+    width: number;
+    height: number;
+}
+export interface BrowserDriverOptions {
+    /** Pinned viewport in CSS pixels. Model coordinates map 1:1 onto this. */
+    viewport?: Viewport;
+    /** Directory for the per-run webm recording. Defaults to a fresh temp dir. */
+    videoDir?: string;
+    /** JPEG quality 0-100 for observation screenshots. */
+    screenshotQuality?: number;
+    /** Optional scale factor for the observation screenshot (<=1 downscales). */
+    screenshotScale?: number;
+    /** Playwright browser engine: `chromium` (default), `firefox`, or `webkit`. */
+    browser?: 'chromium' | 'firefox' | 'webkit' | undefined;
+    /** Hard limit in ms for Playwright cleanup. */
+    browserTimeoutMs?: number | undefined;
+}
+export interface Observation {
+    screenshotJpeg: Buffer;
+    a11yYaml: string;
+    /** Viewport (CSS pixels) the screenshot was taken at — model coords map 1:1. */
+    width: number;
+    height: number;
+}
+/**
+ * One Playwright context per run. Viewport and deviceScaleFactor are pinned so
+ * vision-model pixel coordinates map 1:1 to viewport pixels (KTD2).
+ */
+export declare class BrowserDriver {
+    private readonly browser;
+    private readonly context;
+    private readonly page;
+    private readonly quality;
+    private readonly videoDir;
+    private readonly viewport;
+    private readonly browserTimeoutMs;
+    private video;
+    private closed;
+    private constructor();
+    static launch(options?: BrowserDriverOptions): Promise<BrowserDriver>;
+    get rawPage(): Page;
+    get recordingDir(): string;
+    goto(url: string): Promise<void>;
+    /**
+     * Capture the current observation: a bounded JPEG screenshot plus the page's
+     * a11y tree as YAML via ariaSnapshot (not the deprecated accessibility API).
+     *
+     * `grid: true` paints a temporary coordinate overlay (lines + axis labels
+     * every 100px) before the screenshot and removes it immediately after — the
+     * set-of-marks trick that measurably improves vision-model pixel grounding.
+     */
+    observe(options?: {
+        grid?: boolean;
+    }): Promise<Observation>;
+    private _paintGrid;
+    private _removeGrid;
+    /** Path of the recorded webm, available after close(). */
+    videoPath(): string | undefined;
+    /** Close the context and browser; resolves the video artifact path. Idempotent. */
+    close(): Promise<string | undefined>;
+    private _withTimeout;
+}