argus-reviewer-e2e 0.1.2

package/dist/driver/browser.js

@@ -0,0 +1,200 @@
+import { mkdtemp, mkdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { debug } from '../debug.js';
+import { chromium, firefox, webkit } from 'playwright';
+const DEFAULT_VIEWPORT = { width: 1280, height: 720 };
+const DEFAULT_QUALITY = 70;
+/**
+ * One Playwright context per run. Viewport and deviceScaleFactor are pinned so
+ * vision-model pixel coordinates map 1:1 to viewport pixels (KTD2).
+ */
+export class BrowserDriver {
+    browser;
+    context;
+    page;
+    quality;
+    videoDir;
+    viewport;
+    browserTimeoutMs;
+    video;
+    closed;
+    constructor(browser, context, page, quality, videoDir, viewport, browserTimeoutMs, video, closed = false) {
+        this.browser = browser;
+        this.context = context;
+        this.page = page;
+        this.quality = quality;
+        this.videoDir = videoDir;
+        this.viewport = viewport;
+        this.browserTimeoutMs = browserTimeoutMs;
+        this.video = video;
+        this.closed = closed;
+    }
+    static async launch(options = {}) {
+        const viewport = options.viewport ?? DEFAULT_VIEWPORT;
+        const browserName = options.browser ?? 'chromium';
+        const browserType = { chromium, firefox, webkit }[browserName];
+        if (browserType === undefined) {
+            throw new Error(`unknown browser: ${browserName}`);
+        }
+        const ownsVideoDir = options.videoDir === undefined;
+        const videoDir = options.videoDir ?? (await mkdtemp(join(tmpdir(), 'argus-video-')));
+        await mkdir(videoDir, { recursive: true });
+        const cleanupVideoDir = () => ownsVideoDir ? rm(videoDir, { recursive: true, force: true }).catch(() => undefined) : Promise.resolve();
+        let browser;
+        try {
+            browser = await browserType.launch({ headless: true });
+        }
+        catch (e) {
+            await cleanupVideoDir();
+            const msg = e.message;
+            if (/executable doesn't exist|browser has not been installed/i.test(msg)) {
+                throw new Error(`${msg}\nHint: install it with \`npx playwright install ${browserName}\``, {
+                    cause: e,
+                });
+            }
+            throw e;
+        }
+        try {
+            const context = await browser.newContext({
+                viewport,
+                deviceScaleFactor: 1,
+                recordVideo: { dir: videoDir, size: viewport },
+            });
+            const page = await context.newPage();
+            return new BrowserDriver(browser, context, page, options.screenshotQuality ?? DEFAULT_QUALITY, videoDir, viewport, options.browserTimeoutMs ?? 30_000, undefined);
+        }
+        catch (e) {
+            await browser.close().catch(() => undefined);
+            await cleanupVideoDir();
+            throw e;
+        }
+    }
+    get rawPage() {
+        return this.page;
+    }
+    get recordingDir() {
+        return this.videoDir;
+    }
+    async goto(url) {
+        await this.page.goto(url, { waitUntil: 'load' });
+    }
+    /**
+     * 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.
+     */
+    async observe(options = {}) {
+        const grid = options.grid === true;
+        let painted = false;
+        if (grid) {
+            try {
+                await this._removeGrid(); // stale overlay from a failed prior paint
+                await this._paintGrid();
+                painted = true;
+            }
+            catch {
+                // Navigation race (execution context destroyed) or no document body —
+                // degrade to an ungridded observation rather than aborting the step.
+            }
+        }
+        try {
+            const screenshotJpeg = await this.page.screenshot({
+                type: 'jpeg',
+                quality: this.quality,
+                scale: 'css',
+            });
+            const a11yYaml = await this.page.locator('body').ariaSnapshot();
+            return { screenshotJpeg, a11yYaml, width: this.viewport.width, height: this.viewport.height };
+        }
+        finally {
+            if (painted)
+                await this._removeGrid();
+        }
+    }
+    async _paintGrid() {
+        await this.page.evaluate(() => {
+            const doc = globalThis.document;
+            const overlay = doc.createElement('div');
+            overlay.id = '__argus_grid';
+            overlay.setAttribute('aria-hidden', 'true');
+            overlay.style.cssText =
+                'position:fixed;inset:0;z-index:2147483647;pointer-events:none;' +
+                    'background-image:' +
+                    'linear-gradient(to right, rgba(255,0,0,.35) 1px, transparent 1px),' +
+                    'linear-gradient(to bottom, rgba(255,0,0,.35) 1px, transparent 1px);' +
+                    'background-size:100px 100px;';
+            doc.body.appendChild(overlay);
+            const labels = doc.createElement('div');
+            labels.id = '__argus_grid_labels';
+            labels.setAttribute('aria-hidden', 'true');
+            labels.style.cssText =
+                'position:fixed;inset:0;z-index:2147483647;pointer-events:none;' +
+                    'font:9px monospace;color:rgba(200,0,0,.9);';
+            const win = globalThis;
+            for (let x = 100; x < win.innerWidth; x += 100) {
+                for (let y = 100; y < win.innerHeight; y += 100) {
+                    const tag = win.document.createElement('span');
+                    tag.style.cssText = `position:absolute;left:${x + 1}px;top:${y + 1}px;`;
+                    tag.textContent = `${x},${y}`;
+                    labels.appendChild(tag);
+                }
+            }
+            doc.body.appendChild(labels);
+        });
+    }
+    async _removeGrid() {
+        await this.page
+            .evaluate(() => {
+            const doc = globalThis.document;
+            for (const id of ['__argus_grid', '__argus_grid_labels']) {
+                doc.getElementById(id)?.remove();
+            }
+        })
+            .catch(() => undefined);
+    }
+    /** Path of the recorded webm, available after close(). */
+    videoPath() {
+        return this.video;
+    }
+    /** Close the context and browser; resolves the video artifact path. Idempotent. */
+    async close() {
+        if (this.closed)
+            return this.video;
+        this.closed = true;
+        const video = this.page.video();
+        try {
+            await this._withTimeout(this.context.close());
+        }
+        catch (e) {
+            debug('browser', `context close failed: ${e.message}`);
+        }
+        if (video) {
+            try {
+                this.video = await this._withTimeout(video.path());
+            }
+            catch {
+                this.video = undefined;
+            }
+        }
+        try {
+            await this._withTimeout(this.browser.close());
+        }
+        catch (e) {
+            debug('browser', `browser close failed: ${e.message}`);
+        }
+        return this.video;
+    }
+    _withTimeout(promise) {
+        return Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                const t = setTimeout(() => reject(new Error('browser cleanup timed out')), this.browserTimeoutMs);
+                t.unref?.();
+            }),
+        ]);
+    }
+}

package/dist/driver/target.d.ts

@@ -0,0 +1,23 @@
+import type { Target } from '../config.js';
+/**
+ * Poll `url` until it answers with HTTP 2xx/3xx or the timeout elapses.
+ * Non-http(s) schemes (e.g. file://) cannot be fetched, so they are treated
+ * as immediately ready — Playwright navigates them directly.
+ */
+export declare function waitForReady(url: string, timeoutMs: number): Promise<void>;
+/**
+ * Boot adapter for the run target (R11): spawn a shell command, poll the URL
+ * until it answers with HTTP 2xx/3xx or the ready timeout elapses, then let
+ * the run proceed. stop() kills the whole spawned process tree.
+ */
+export declare class TargetProcess {
+    private readonly child;
+    private readonly spec;
+    private stopped;
+    private constructor();
+    get url(): string;
+    get pid(): number | undefined;
+    static start(spec: Target): Promise<TargetProcess>;
+    /** Kill the spawned process tree (process group). Idempotent. */
+    stop(): Promise<void>;
+}

package/dist/driver/target.js

@@ -0,0 +1,97 @@
+import { spawn } from 'node:child_process';
+const POLL_INTERVAL_MS = 250;
+const STOP_GRACE_MS = 3_000;
+/**
+ * Poll `url` until it answers with HTTP 2xx/3xx or the timeout elapses.
+ * Non-http(s) schemes (e.g. file://) cannot be fetched, so they are treated
+ * as immediately ready — Playwright navigates them directly.
+ */
+export async function waitForReady(url, timeoutMs) {
+    if (!/^https?:/i.test(url))
+        return;
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            const res = await fetch(url, { redirect: 'manual' });
+            if (res.status >= 200 && res.status < 400)
+                return;
+        }
+        catch {
+            // connection refused / not up yet — keep polling
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`Target did not become ready: ${url} did not respond ` +
+                `with HTTP 2xx/3xx within ${timeoutMs}ms`);
+        }
+        await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+    }
+}
+/**
+ * Boot adapter for the run target (R11): spawn a shell command, poll the URL
+ * until it answers with HTTP 2xx/3xx or the ready timeout elapses, then let
+ * the run proceed. stop() kills the whole spawned process tree.
+ */
+export class TargetProcess {
+    child;
+    spec;
+    stopped = false;
+    constructor(child, spec) {
+        this.child = child;
+        this.spec = spec;
+    }
+    get url() {
+        return this.spec.url;
+    }
+    get pid() {
+        return this.child.pid;
+    }
+    static async start(spec) {
+        const child = spawn(spec.command, {
+            shell: true,
+            detached: true,
+            stdio: 'ignore',
+        });
+        const proc = new TargetProcess(child, spec);
+        const childExited = new Promise((_, reject) => {
+            child.once('error', (err) => reject(err));
+            child.once('exit', (code, signal) => reject(new Error(`Target command exited before ${spec.url} became ready ` +
+                `(code=${code ?? 'null'}, signal=${signal ?? 'null'})`)));
+        });
+        const ready = waitForReady(spec.url, spec.readyTimeoutMs);
+        try {
+            await Promise.race([ready, childExited]);
+        }
+        catch (e) {
+            await proc.stop();
+            throw e;
+        }
+        return proc;
+    }
+    /** Kill the spawned process tree (process group). Idempotent. */
+    async stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        const exited = new Promise((resolve) => {
+            this.child.once('exit', () => resolve());
+            setTimeout(resolve, STOP_GRACE_MS).unref();
+        });
+        try {
+            // Negative pid kills the detached process group — the shell and its children.
+            if (this.child.pid !== undefined)
+                process.kill(-this.child.pid, 'SIGTERM');
+        }
+        catch {
+            // already gone
+        }
+        await exited;
+        try {
+            if (this.child.exitCode === null && this.child.pid !== undefined) {
+                process.kill(-this.child.pid, 'SIGKILL');
+            }
+        }
+        catch {
+            // already gone
+        }
+    }
+}

package/dist/engine/actions.d.ts

@@ -0,0 +1,26 @@
+import type { BrowserDriver, Observation } from '../driver/browser.js';
+/**
+ * Action primitives over the driver page. All coordinates are plain viewport
+ * pixels — the pinned viewport + deviceScaleFactor: 1 means model coordinates
+ * map 1:1 (KTD2). Every action returns a post-action observation so callers
+ * can verify the result immediately.
+ */
+export declare class Actions {
+    private readonly driver;
+    constructor(driver: BrowserDriver);
+    /** Single click at viewport pixel (x, y). */
+    click(x: number, y: number): Promise<Observation>;
+    /** Double click at viewport pixel (x, y). */
+    doubleClick(x: number, y: number): Promise<Observation>;
+    /** Type text into the currently focused element. */
+    type(text: string): Promise<Observation>;
+    /**
+     * Press keys in sequence. Each entry is a key name ('Enter', 'Tab') or a
+     * chord ('Control+a', 'Shift+ArrowLeft').
+     */
+    pressKeys(keys: string[]): Promise<Observation>;
+    /** Scroll the page by (dx, dy) viewport pixels. */
+    scroll(dx: number, dy: number): Promise<Observation>;
+    /** Wait ms milliseconds, then observe. */
+    wait(ms: number): Promise<Observation>;
+}

package/dist/engine/actions.js

@@ -0,0 +1,47 @@
+/**
+ * Action primitives over the driver page. All coordinates are plain viewport
+ * pixels — the pinned viewport + deviceScaleFactor: 1 means model coordinates
+ * map 1:1 (KTD2). Every action returns a post-action observation so callers
+ * can verify the result immediately.
+ */
+export class Actions {
+    driver;
+    constructor(driver) {
+        this.driver = driver;
+    }
+    /** Single click at viewport pixel (x, y). */
+    async click(x, y) {
+        await this.driver.rawPage.mouse.click(x, y);
+        return this.driver.observe({ grid: true });
+    }
+    /** Double click at viewport pixel (x, y). */
+    async doubleClick(x, y) {
+        await this.driver.rawPage.mouse.dblclick(x, y);
+        return this.driver.observe({ grid: true });
+    }
+    /** Type text into the currently focused element. */
+    async type(text) {
+        await this.driver.rawPage.keyboard.type(text);
+        return this.driver.observe({ grid: true });
+    }
+    /**
+     * Press keys in sequence. Each entry is a key name ('Enter', 'Tab') or a
+     * chord ('Control+a', 'Shift+ArrowLeft').
+     */
+    async pressKeys(keys) {
+        for (const key of keys) {
+            await this.driver.rawPage.keyboard.press(key);
+        }
+        return this.driver.observe({ grid: true });
+    }
+    /** Scroll the page by (dx, dy) viewport pixels. */
+    async scroll(dx, dy) {
+        await this.driver.rawPage.mouse.wheel(dx, dy);
+        return this.driver.observe({ grid: true });
+    }
+    /** Wait ms milliseconds, then observe. */
+    async wait(ms) {
+        await this.driver.rawPage.waitForTimeout(ms);
+        return this.driver.observe({ grid: true });
+    }
+}

package/dist/engine/loop.d.ts

@@ -0,0 +1,118 @@
+import { BrowserDriver, Observation } from '../driver/browser.js';
+import { Actions } from './actions.js';
+import { Config, ProviderRules } from '../config.js';
+import { CallCost, CallKind } from '../vision/cost.js';
+import { Ledger } from '../vision/ledger.js';
+import { JsonSchema, Message } from '../vision/openrouter.js';
+import { FingerprintRecord, Point } from '../cache/fingerprint.js';
+import { CachedAssert, FlowCache } from '../cache/store.js';
+import { ErrorRecord } from '../journal/schema.js';
+import { Logger } from '../log.js';
+import { AssertionResult } from './prompts.js';
+export interface VisionClient {
+    complete(opts: {
+        model: string;
+        messages: Message[];
+        schema?: JsonSchema;
+        escalationModels?: string[];
+        provider?: ProviderRules;
+        kind?: CallKind;
+    }): Promise<{
+        id: string;
+        content: string;
+        cost: CallCost;
+        model: string;
+    }>;
+}
+export interface TestDriverApi {
+    click(x: number, y: number): Promise<Observation>;
+    type(text: string): Promise<Observation>;
+    pressKeys(keys: string[]): Promise<Observation>;
+    scroll(dx: number, dy: number): Promise<Observation>;
+    wait(ms: number): Promise<Observation>;
+}
+export interface EngineOptions {
+    driver: BrowserDriver;
+    actions: Actions;
+    client: VisionClient;
+    ledger: Ledger;
+    config: Config;
+    /** Assertion verdicts persisted from a prior run of this flow. */
+    initialAsserts?: CachedAssert[];
+    /** Leveled logger; silent when absent. */
+    logger?: Logger;
+}
+export interface RecordOptions {
+    flowName?: string;
+    stepCap?: number;
+}
+export interface ReplayOptions {
+    flowName?: string;
+}
+export interface StepResult {
+    instruction: string;
+    action: string;
+    ok: boolean;
+    reason?: string;
+    healed?: boolean;
+    model?: string;
+}
+export interface RunResult {
+    ok: boolean;
+    reason?: string;
+    steps: StepResult[];
+    visionCalls: number;
+}
+export interface AssertResult extends AssertionResult {
+    cached: boolean;
+}
+export interface LocateResult {
+    ok: boolean;
+    reason: string | undefined;
+    healed: boolean;
+    point: Point | undefined;
+    fingerprint: FingerprintRecord | undefined;
+    model: string | undefined;
+}
+export declare class Engine {
+    private _opts;
+    private _visionCalls;
+    private _steps;
+    private _fingerprints;
+    private _assertCache;
+    private _errors;
+    /** Structured, non-fatal anomalies — journaled as evidence, never thrown. */
+    get errorRecords(): ErrorRecord[];
+    private _note;
+    constructor(_opts: EngineOptions);
+    /** Assertion verdicts collected/known this run — persist into the flow cache. */
+    get assertEntries(): CachedAssert[];
+    get visionCalls(): number;
+    record(instruction: string, tdApi?: TestDriverApi, options?: RecordOptions): Promise<RunResult>;
+    replay(flow: FlowCache, options?: ReplayOptions): Promise<RunResult>;
+    /**
+     * Resolve a single element for the `td.find()` DSL (R13). When `cached` is
+     * provided and still resolves locally, this costs zero vision calls (R2);
+     * otherwise it grounds (or heals) via the model and returns a fresh
+     * fingerprint (R4). The returned point is the viewport-pixel click target.
+     */
+    locate(instruction: string, cached?: FingerprintRecord): Promise<LocateResult>;
+    /**
+     * One locate attempt against a specific model: initial call plus the
+     * verify-then-correct loop. `modelOverride` is the escalation fallback —
+     * it keeps the action schema unless a specialist grounding model is in
+     * play (native "(x,y)" format).
+     */
+    private _locateWithModel;
+    assert(question: string): Promise<AssertResult>;
+    private _callModel;
+    private _parseAction;
+    private _parseAssertion;
+    private _resolveAction;
+    private _resolveNode;
+    private _executeAction;
+    private _buildFingerprint;
+    private _regionScreenshot;
+    private _result;
+}
+export declare function instructionMatchesNode(instruction: string, nodeSnippet: string): boolean;