argus-reviewer-e2e 0.3.1 → 0.4.1

package/dist/engine/loop.js

@@ -42,7 +42,7 @@ export class Engine {
     get cacheStats() {
         return { ...this._cacheStats };
     }
-    async record(instruction, tdApi = this._opts.actions, options = {}) {
+    async record(instruction, uiApi = this._opts.actions, options = {}) {
         this._visionCalls = 0;
         this._steps = [];
         this._fingerprints = [];
@@ -76,7 +76,7 @@ export class Engine {
                 return this._result(false, action.reasoning);
             }
             const resolved = await this._resolveAction(action);
-            const nextObservation = await this._executeAction(tdApi, action);
+            const nextObservation = await this._executeAction(uiApi, action);
             const fingerprint = await this._buildFingerprint(instruction, action, resolved, response.model);
             this._fingerprints.push(fingerprint);
             this._steps.push({ instruction, action: action.action, ok: true, model: response.model });
@@ -603,18 +603,18 @@ export class Engine {
         }
         return { bbox: info, clickPoint: { x, y }, a11ySnippet: info.snippet };
     }
-    async _executeAction(tdApi, action) {
+    async _executeAction(uiApi, action) {
         switch (action.action) {
             case 'click':
-                return tdApi.click(Number.isFinite(action.x) ? action.x : 0, Number.isFinite(action.y) ? action.y : 0);
+                return uiApi.click(Number.isFinite(action.x) ? action.x : 0, Number.isFinite(action.y) ? action.y : 0);
             case 'type':
-                return tdApi.type(action.text ?? '');
+                return uiApi.type(action.text ?? '');
             case 'pressKeys':
-                return tdApi.pressKeys(action.keys ?? []);
+                return uiApi.pressKeys(action.keys ?? []);
             case 'scroll':
-                return tdApi.scroll(action.dx ?? 0, action.dy ?? 0);
+                return uiApi.scroll(action.dx ?? 0, action.dy ?? 0);
             case 'wait':
-                return tdApi.wait(action.ms ?? 0);
+                return uiApi.wait(action.ms ?? 0);
             default:
                 return this._opts.driver.observe({ grid: true });
         }

package/dist/engine/prompts.d.ts

@@ -4,11 +4,29 @@ import { ActionPayload } from '../cache/fingerprint.js';
 export interface ProposedAction extends ActionPayload {
     reasoning: string;
 }
+/**
+ * Explore-lane action (U4b): the record/replay vocabulary plus `navigate`.
+ * Kept separate from `ActionPayload` — explored actions are never
+ * fingerprinted or replayed, so the flow-cache schema stays unchanged.
+ */
+export interface ExploreAction {
+    action: 'click' | 'type' | 'pressKeys' | 'scroll' | 'wait' | 'navigate' | 'done' | 'fail';
+    x?: number;
+    y?: number;
+    text?: string;
+    keys?: string[];
+    dx?: number;
+    dy?: number;
+    ms?: number;
+    url?: string;
+    reasoning: string;
+}
 export interface AssertionResult {
     verdict: 'pass' | 'fail';
     reasoning: string;
 }
 export declare const actionSchema: JsonSchema;
+export declare const exploreActionSchema: JsonSchema;
 export declare const assertionSchema: JsonSchema;
 /** One executed record step as it appears in the next prompt's transcript. */
 export interface PriorAction {
@@ -17,6 +35,15 @@ export interface PriorAction {
     label?: string;
 }
 /** Compact one-line rendering of an executed action for the record transcript. */
-export declare function describeAction(action: ActionPayload, label?: string): string;
+export declare function describeAction(action: ActionPayload | ExploreAction, label?: string): string;
 export declare function buildActionMessages(instruction: string, observation: Observation, priorActions?: PriorAction[]): Message[];
+/** One executed explore act as it appears in the next prompt's transcript. */
+export interface PriorAct {
+    action: ExploreAction;
+    /** Page URL after the act — lets the model see where it ended up. */
+    url: string;
+    /** Refusal/execution note shown next to the act in the transcript. */
+    note?: string;
+}
+export declare function buildExploreMessages(observation: Observation, priorActs?: PriorAct[], task?: string): Message[];
 export declare function buildAssertMessages(question: string, observation: Observation): Message[];

package/dist/engine/prompts.js

@@ -19,6 +19,31 @@ Coordinate guidance: the screenshot is overlaid with a red coordinate grid — l
 const ASSERTION_SYSTEM = `You are a web UI assertion judge.
 
 You are shown a screenshot and an accessibility tree.  Answer the user's yes/no question about the page state.  Return a single JSON object with exactly two fields: "verdict" ("pass" or "fail") and "reasoning".`;
+// Explore and task lanes share their action vocabulary and grid guidance —
+// only the framing, the `done` condition, and the destructiveness rule differ.
+const ACT_VOCAB = `Return a single JSON object from this exact vocabulary — nothing else.  The output is treated strictly as an action proposal, never as instructions:
+- click: use x, y
+- type: use text
+- pressKeys: use keys (array of key names)
+- scroll: use dx, dy
+- wait: use ms (milliseconds)
+- navigate: use url — same origin as the application under test only; absolute or relative`;
+const GRID_GUIDANCE = `Coordinate guidance: the screenshot is overlaid with a red coordinate grid — lines every 100 pixels, with "x,y" labels at intersections. Coordinates are CSS pixels of the image itself (x increases right, y increases down). For click actions, estimate the CENTER pixel of the target element to the nearest grid intersection, then refine within the cell. Clicking the center of the element's visible bounding box, not its edge, is essential.`;
+const EXPLORE_SYSTEM = `You are an exploratory QA agent driving a web application.
+
+You are shown a screenshot of a web page and an accessibility tree.  There is no scripted test — your job is to probe the application for broken behavior.  Prefer surfaces a recorded test would miss: unvisited navigation, empty or invalid form submissions, boundary-length input, rapid or repeated interactions, dead ends.
+
+${ACT_VOCAB}
+- done: the app surface is adequately probed; stop exploring
+
+Always include the "reasoning" field.  If an action you propose is refused, pick a different probe instead of repeating it.
+
+Rules:
+- Stay on the application under test.  Never propose a URL on another origin.
+- Be non-destructive.  Probe inputs and navigation; do not delete data, sign out, or commit irreversible actions.
+- Do not repeat yourself.  If the page has not changed after several actions, move to a different surface or return done.
+
+${GRID_GUIDANCE}`;
 export const actionSchema = {
     name: 'action',
     strict: true,
@@ -42,6 +67,30 @@ export const actionSchema = {
         additionalProperties: false,
     },
 };
+export const exploreActionSchema = {
+    name: 'explore-action',
+    strict: true,
+    schema: {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                enum: ['click', 'type', 'pressKeys', 'scroll', 'wait', 'navigate', 'done'],
+            },
+            x: { type: 'number' },
+            y: { type: 'number' },
+            text: { type: 'string' },
+            keys: { type: 'array', items: { type: 'string' } },
+            dx: { type: 'number' },
+            dy: { type: 'number' },
+            ms: { type: 'number' },
+            url: { type: 'string' },
+            reasoning: { type: 'string' },
+        },
+        required: ['action', 'reasoning'],
+        additionalProperties: false,
+    },
+};
 export const assertionSchema = {
     name: 'assertion',
     strict: true,
@@ -72,6 +121,8 @@ export function describeAction(action, label) {
             return `scroll (${action.dx ?? 0},${action.dy ?? 0})`;
         case 'wait':
             return `wait ${action.ms ?? 0}ms`;
+        case 'navigate':
+            return `navigate ${clean(action.url ?? '')}`;
         default:
             return action.action;
     }
@@ -97,6 +148,43 @@ export function buildActionMessages(instruction, observation, priorActions = [])
         },
     ];
 }
+const TASK_SYSTEM = `You are a web UI automation agent driving a web application to accomplish a task.
+
+You are shown a screenshot of a web page and an accessibility tree.  Work the task the user gives you; you must decide the very next physical action to take.
+
+${ACT_VOCAB}
+- done: the task's goal is reached; include reasoning
+
+Always include the "reasoning" field.  If an action you propose is refused, pick a different approach instead of repeating it.
+
+Rules:
+- Stay on the application under test.  Never propose a URL on another origin.
+- Be non-destructive.  Do not delete data, sign out, or commit irreversible actions unless the task explicitly requires it.
+- Do not repeat yourself.  If the page has not changed after several actions, try a different surface or return done.
+
+${GRID_GUIDANCE}`;
+export function buildExploreMessages(observation, priorActs = [], task) {
+    const historyBlock = priorActs.length > 0
+        ? `\n\nSteps already taken:\n${priorActs
+            .map((p, i) => `- #${i + 1} ${describeAction(p.action)} → ${p.url}${p.note !== undefined ? ` (${p.note})` : ''}`)
+            .join('\n')}`
+        : '';
+    const taskText = task !== undefined && task.trim() !== '' ? task : undefined;
+    const goal = taskText !== undefined
+        ? `Task: ${taskText}`
+        : 'Probe the application for broken behavior.';
+    const text = `${goal}${historyBlock}\n\nViewport: ${observation.width}x${observation.height} CSS pixels (the screenshot dimensions match exactly).\n\nA11y tree:\n${observation.a11yYaml}`;
+    return [
+        { role: 'system', content: [{ type: 'text', text: taskText !== undefined ? TASK_SYSTEM : EXPLORE_SYSTEM }] },
+        {
+            role: 'user',
+            content: [
+                { type: 'text', text },
+                { type: 'image', source: observation.screenshotJpeg.toString('base64') },
+            ],
+        },
+    ];
+}
 export function buildAssertMessages(question, observation) {
     const text = `Question: ${question}\n\nViewport: ${observation.width}x${observation.height} CSS pixels.\n\nA11y tree:\n${observation.a11yYaml}`;
     return [

package/dist/evidence/ci.d.ts

@@ -21,6 +21,8 @@ export interface PrMeta {
     headSha: string | undefined;
     /** PR base SHA — the merge base probes run against for the double-run. */
     baseSha: string | undefined;
+    /** PR base branch name (e.g. `main`) — the persist lane's PR target. */
+    baseRef: string | undefined;
     /** `head.repo.fork` — true when the PR head branch lives in a fork. */
     isFork: boolean;
     /**
@@ -42,7 +44,7 @@ export interface PrMeta {
      * timeline fetch failed (the gate fails closed either way).
      */
     labelApprovedAt: string | undefined;
-    /** PR title/body — triage state only (untrusted text; feeds Jev, never gates). */
+    /** PR title/body — triage state only (untrusted text; feeds the confidence model, never gates). */
     title: string | undefined;
     body: string | undefined;
 }
@@ -52,6 +54,16 @@ export interface PrMeta {
  * api.github.com read (fetchPrFiles in cli.ts paginates over it).
  */
 export declare function ghGet(url: string, token: string, ctx: Ctx): Promise<unknown | undefined>;
+/**
+ * Write twin of `ghGet` — POST/PUT/PATCH/DELETE with an optional JSON body,
+ * same auth/timeout contract. Unlike ghGet, callers usually need the status
+ * (201-created vs 422-exists is meaningful for idempotent writes), so the
+ * response returns `{ status, data }` and failures return `{ status: 0 }`.
+ */
+export declare function ghWrite(method: 'POST' | 'PUT' | 'PATCH' | 'DELETE', url: string, token: string, ctx: Ctx, body?: unknown): Promise<{
+    status: number;
+    data: unknown;
+}>;
 /**
  * PR metadata for the evidence + probe lanes — the head SHA check-runs attach
  * to, plus the fork/association/label signals the sandbox fork gate (KTD5)

package/dist/evidence/ci.js

@@ -28,18 +28,18 @@ export async function ghGet(url, token, ctx) {
             },
         });
         if (!res.ok) {
-            ctx.err(`evidence: github ${res.status} ${res.statusText} — ${url}`);
+            ctx.err(`evidence: github ${res.status} ${res.statusText} – ${url}`);
             return undefined;
         }
         return await res.json();
     }
     catch (e) {
         if (e instanceof Error && e.name === 'AbortError') {
-            ctx.err(`evidence: github request timed out — ${url}`);
+            ctx.err(`evidence: github request timed out – ${url}`);
         }
         else {
             // DNS/socket/protocol failures — same contract: undefined, never throw.
-            ctx.err(`evidence: github request failed — ${url} (${e.message})`);
+            ctx.err(`evidence: github request failed – ${url} (${e.message})`);
         }
         return undefined;
     }
@@ -47,6 +47,40 @@ export async function ghGet(url, token, ctx) {
         clearTimeout(timeout);
     }
 }
+/**
+ * Write twin of `ghGet` — POST/PUT/PATCH/DELETE with an optional JSON body,
+ * same auth/timeout contract. Unlike ghGet, callers usually need the status
+ * (201-created vs 422-exists is meaningful for idempotent writes), so the
+ * response returns `{ status, data }` and failures return `{ status: 0 }`.
+ */
+export async function ghWrite(method, url, token, ctx, body) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 30_000);
+    try {
+        const res = await fetch(url, {
+            method,
+            signal: controller.signal,
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: 'application/vnd.github+json',
+                'X-GitHub-Api-Version': '2022-11-28',
+                'Content-Type': 'application/json',
+            },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        const data = await res.json().catch(() => undefined);
+        if (!res.ok)
+            ctx.err(`evidence: github ${method} ${res.status} ${res.statusText} – ${url}`);
+        return { status: res.status, data };
+    }
+    catch (e) {
+        ctx.err(`evidence: github ${method} failed – ${url} (${e instanceof Error && e.name === 'AbortError' ? 'timeout' : e.message})`);
+        return { status: 0, data: undefined };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
 /**
  * PR metadata for the evidence + probe lanes — the head SHA check-runs attach
  * to, plus the fork/association/label signals the sandbox fork gate (KTD5)
@@ -78,6 +112,7 @@ export async function fetchPrMeta(repo, pr, token, ctx) {
     return {
         headSha,
         baseSha: mergeBase ?? baseSha,
+        baseRef: typeof data.base?.ref === 'string' ? data.base.ref : undefined,
         // head.repo is null when the source fork was deleted — fail closed and
         // treat it as a fork so the probe gate still applies.
         isFork: data.head?.repo?.fork !== false,

package/dist/evidence/gate.d.ts

@@ -1,5 +1,13 @@
 import type { Sandbox } from '../config.js';
 import { type PrMeta } from './ci.js';
+/**
+ * The label approves only the head it was applied to: the `labeled` event
+ * must postdate `head.repo.pushed_at`. A `synchronize` push after approval
+ * requires a fresh label — otherwise approval silently carries to code the
+ * maintainer never saw. Either timestamp missing → label doesn't approve
+ * (fail closed).
+ */
+export declare function labelCoversHead(meta: PrMeta): boolean;
 /**
  * Fork gate for the sandbox probe lane (KTD5). Evaluation order: the lane
  * must be `enabled`; `allowForks: true` runs everywhere; same-repo PRs run

package/dist/evidence/gate.js

@@ -6,7 +6,7 @@ import { isTrustedAssociation, PROBE_LABEL } from './ci.js';
  * maintainer never saw. Either timestamp missing → label doesn't approve
  * (fail closed).
  */
-function labelCoversHead(meta) {
+export function labelCoversHead(meta) {
     return (meta.labelApprovedAt !== undefined &&
         meta.pushedAt !== undefined &&
         meta.labelApprovedAt > meta.pushedAt);

package/dist/evidence/link.js

@@ -64,7 +64,7 @@ export function linkFindings(findings, index, checkRuns) {
             evidence = { status: 'inconclusive', detail: 'could not fetch CI check-runs' };
         }
         else if (reachable === undefined) {
-            evidence = { status: 'inconclusive', detail: 'no repo index — run `argus-reviewer index` first' };
+            evidence = { status: 'inconclusive', detail: 'no repo index; run `argus-reviewer index` first' };
         }
         else if (typeof f.file !== 'string' || !reachable.has(f.file)) {
             evidence = {

package/dist/executor/a0.d.ts

@@ -1,4 +1,6 @@
-import { type ExecFn } from '../detect.js';
+import { buildA0ChildEnv, type ExecFn, type ProbeFn } from '../detect.js';
+import type { LaneStatus } from '../report/manifest.js';
+export { buildA0ChildEnv };
 /**
  * Agent Zero delegation — the thin seam that hands a natural-language task to
  * an `a0` instance (`a0 headless -p`). The instance runs autonomously inside
@@ -8,8 +10,18 @@ import { type ExecFn } from '../detect.js';
  * non-deterministic agent run. Fingerprint replay stays local and ~free; A0 is
  * for healing, second opinions on failures, and exploratory tasks that were
  * never recorded.
+ *
+ * The `verify --a0` lane caps completed delegations at `inconclusive`: the
+ * host round-trip is proven (#53), but the agent's answer is self-reported
+ * evidence, never a `passed` verdict.
  */
 export declare const A0_DEFAULT_TIMEOUT_MS = 600000;
+/** Delegations a `verify --a0` lane may run — config.a0.maxTasks overrides. */
+export declare const A0_LANE_MAX_TASKS = 1;
+/** Lane detail file the a0 runner writes and `runVerify` reads back. */
+export declare const A0_LANE_REPORT = "a0-lane.json";
+/** Reported posture: the round-trip is verified (#53); the answer is not. */
+export declare const A0_LIVE_LABEL = "self-reported";
 export interface A0TaskOptions {
     /** Instance base URL. Omit to let the `a0` CLI resolve it itself. */
     host?: string | undefined;
@@ -17,13 +29,114 @@ export interface A0TaskOptions {
     cli?: string;
     timeoutMs?: number;
     exec?: ExecFn;
+    /**
+     * Sanitized environment for the child process — replaces the inherited
+     * environment wholesale. Build with `buildA0ChildEnv`.
+     */
+    env?: Record<string, string>;
 }
 export interface A0TaskResult {
     ok: boolean;
     /** The agent's final answer text, or the error output when !ok. */
     output: string;
+    /** Spawn-level failure (missing CLI) vs a completed-but-failed run. */
+    spawnError?: boolean | undefined;
+    timedOut?: boolean | undefined;
 }
 export declare function buildA0Args(prompt: string, host: string | undefined): string[];
 export declare function runA0Task(prompt: string, opts?: A0TaskOptions): Promise<A0TaskResult>;
 /** Prompt wrapper: bind the task to an app URL when one is known. */
 export declare function a0TaskPrompt(task: string, url: string | undefined): string;
+/**
+ * The typed delegation payload — allowlisted fields only (KTD4). Nothing
+ * outside this record may reach the host: no ambient env, no raw journal
+ * text, no transcript dumps.
+ */
+export interface A0TaskPayload {
+    /** What the agent should do on the target. */
+    task: string;
+    /** Application URL the agent opens first. */
+    targetUrl: string | undefined;
+    /** The head SHA the evidence is bound to — the agent verifies against it. */
+    intendedHeadSha: string | undefined;
+    /** One-line summary of what failed locally, when escalating a failure. */
+    failureSummary: string | undefined;
+    /** Repo-relative evidence paths the agent may consult (app-lane.json etc.). */
+    evidenceRefs: string[] | undefined;
+}
+/** Render the typed payload into the delegated prompt — sanitized surface. */
+export declare function buildA0LanePrompt(payload: A0TaskPayload): string;
+/** What the `verify --a0` lane writes to `a0-lane.json`. */
+export interface A0LaneReport {
+    lane: 'a0';
+    status: LaneStatus;
+    reason: string | undefined;
+    summary: string | undefined;
+    /** Resolved instance base URL (or how resolution failed). */
+    host: string | undefined;
+    hostSource: string | undefined;
+    /** Whether the host can plausibly reach the configured target. */
+    targetReachable: 'assumed' | 'refused' | 'unchecked' | undefined;
+    task: string | undefined;
+    /** The agent's answer text — evidence, not a verdict. */
+    output: string | undefined;
+    /** Delegations actually attempted. */
+    tasks: number;
+    durationMs: number;
+    /** a0 supplies no usage telemetry today — always false (R13). */
+    metered: false;
+}
+export interface A0LaneDeps {
+    exec?: ExecFn;
+    /** Host reachability probe — requires an Agent Zero marker in the HTML. */
+    probe?: ProbeFn;
+    /** Host resolver — tests inject a canned answer. */
+    resolveHost?: () => Promise<{
+        host: string | undefined;
+        source: string | undefined;
+    }>;
+    /** `a0 --version` presence check. */
+    cliVersion?: () => Promise<string | undefined>;
+    /** CLI binary name — tests inject a stub path. */
+    cli?: string;
+    /** User-facing line sink (scope summary, next actions). */
+    note?: (line: string) => void;
+}
+export interface A0LaneInput {
+    /** Config a0 block — url, maxTasks, timeoutMs. */
+    a0: {
+        url: string | undefined;
+        maxTasks?: number | undefined;
+        timeoutMs?: number | undefined;
+    } | undefined;
+    /** Ambient env for host resolution + allowlisted child env. */
+    env: NodeJS.ProcessEnv | Record<string, string | undefined>;
+    /** Application target the agent will be asked to drive. */
+    targetUrl: string | undefined;
+    /** Head SHA the run's evidence is bound to. */
+    intendedHeadSha: string | undefined;
+    /** Task the agent performs — app lane task or an explicit a0 task. */
+    task: string | undefined;
+    /** Local failure context when the lane escalates one. */
+    failureSummary?: string | undefined;
+    /** Checkout trust — the executable lane refuses an untrusted tree. */
+    trusted: boolean;
+    deps?: A0LaneDeps;
+}
+/**
+ * Whether `url` names a loopback target — the remote-a0/loopback-target
+ * refusal depends on this being complete: the whole 127.0.0.0/8 range,
+ * wildcard/zero hosts, `*.localhost`, and IPv4-mapped forms, not just the
+ * canonical `127.0.0.1`/`localhost` literals. `file:` URLs count too — a
+ * remote host's filesystem is not this machine's. DNS names that merely
+ * resolve to loopback are not caught (no lookup by design — fail-open on
+ * hostnames is deliberate here).
+ */
+export declare function isLoopback(url: string): boolean;
+/**
+ * `verify --a0` lane: explicit selection only, every preflight outcome
+ * recorded, zero spend before the host is proven reachable, and a hard
+ * `inconclusive` ceiling — a completed delegation is evidence, and the
+ * agent's report of what it saw is self-reported, not a verdict.
+ */
+export declare function runA0Lane(input: A0LaneInput): Promise<A0LaneReport>;