@bonyadnouri/autoend 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bonyad Nouri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# autoend
+
+**Agent-powered end-to-end testing.** Point it at your app, walk away, get back a video-backed report.
+
+```sh
+npx autoend init    # guided setup — takes a minute
+npx autoend         # agents test your app, a report opens
+```
+
+Straight from GitHub also works: `npx github:bonyadnouri/autoend init`
+
+No test suite to write. No selectors to maintain. Agents discover your app's flows, guard them on every run, and hand you the evidence on film.
+
+![autoend report showing a hard failure verdict with tiered findings](docs/assets/report-failure.png)
+
+## How a Run works
+
+1. **Replay** — every flow agents have ever verified is re-executed: headless, parallel, deterministic, with a WebM recording per flow. No LLM in the loop, so it's fast and free.
+2. **Explore** — within the effort budget you chose, agents probe new surface: clicking, filling, navigating — looking for flows nobody wrote down and failures nobody noticed.
+3. **Report** — a local page opens with a one-glance verdict. Click into any finding and *watch* what the agent saw.
+
+Findings arrive in tiers, so signal never drowns in noise:
+
+| Tier | Meaning | Your move |
+|---|---|---|
+| **Hard failure** | Objectively broken — 5xx, crashes, console errors | Fix it |
+| **Regression** | Worked in a previous run, failed now | Fix it — or dismiss if the removal was intentional |
+| **Heal** | UI changed, goal still works; the flow script was rewritten | Watch the video, confirm the heal |
+| **Advisory** | Agent judgment: UX, accessibility, speed | Your call |
+
+![autoend report showing the all clear state](docs/assets/report-all-clear.png)
+
+## The Flow Map is yours
+
+Everything agents learn lives in your repo, in plain Playwright:
+
+```
+.autoend/
+├── flows/                 # commit this — your team's shared baseline
+│   └── checkout/
+│       ├── flow.json      # metadata: title, last passed, ...
+│       └── flow.mts       # an ordinary Playwright script
+└── runs/                  # gitignored — reports + evidence videos
+```
+
+Flows are ordinary Playwright scripts. Branches carry their own baseline, teammates share it through git, map changes show up in PRs like any other diff — and if you ever leave autoend, you walk away with a working Playwright suite. **No lock-in, by design.**
+
+## Effort: you choose how hard it tests
+
+```sh
+npx autoend              # your configured default
+npx autoend -e low       # quick pass        (~1-2 min)
+npx autoend -e high      # thorough sweep    (~5 min)
+npx autoend -e ultra     # leave it running  (~35 min)
+```
+
+Replay always completes at any effort — regression coverage is never sacrificed to a small budget. Effort only scales exploration.
+
+## Requirements
+
+- **Node.js ≥ 23.6** (flow scripts run via native TypeScript type-stripping)
+- **A Cursor API key** — exploring agents run on the [Cursor SDK](https://cursor.com/docs/sdk/typescript) ([get a key](https://cursor.com/dashboard))
+- Browsers install on first use via Playwright; [agent-browser](https://github.com/vercel-labs/agent-browser) ships as a dependency
+
+## Status
+
+Early. The architecture is settled, documented, and de-risked end-to-end; the explorer fleet is the active front.
+
+- [x] Run pipeline: replay → explore → report artifact
+- [x] Replay engine — parallel headless Playwright with per-flow video
+- [x] Report viewer — verdict, tiers, embedded evidence
+- [x] Guided setup (`autoend init`)
+- [x] Cursor SDK harness verified (agents driving agent-browser via shell)
+- [ ] Explorer fleet — flow discovery, hard-failure detection, advisories
+- [ ] Heal-and-notify on replay failures
+- [ ] Report resolution actions (dismiss / reject / suppress)
+- [ ] Fleet auth — login once, share session storage state
+
+## Under the hood
+
+Every load-bearing decision is written down — start with [`CONTEXT.md`](./CONTEXT.md) (the project glossary) and [`docs/adr/`](./docs/adr/):
+
+1. [Fly-generated tests over an accumulated Flow Map](./docs/adr/0001-fly-generated-tests-over-accumulated-flow-map.md)
+2. [agent-browser hands + Playwright artifacts](./docs/adr/0002-agent-browser-hands-playwright-artifact.md) — why exploration and replay use different engines
+3. [Cursor SDK as the agent harness](./docs/adr/0003-cursor-sdk-as-agent-harness.md)
+4. [Report as a static artifact + thin viewer](./docs/adr/0004-report-as-static-artifact.md)
+
+The short version: exploration is LLM-latency-bound, so agents drive the browser through the most token-efficient hands available (agent-browser, ~200–400 tokens per snapshot). Replay is reliability-bound, so flows persist as plain Playwright with auto-waiting and native video. The report is static files served by a dumb local viewer — portable to CI by construction.
+
+## Development
+
+```sh
+npm install
+npm test              # vitest — includes a real browser replay integration test
+npm run build         # tsc → dist/
+npm run dev -- http://localhost:3000 -e low --no-open
+```
+
+## License
+
+[MIT](./LICENSE)

package/dist/auth/session.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Fleet auth (decided in the grilling session): login ONCE with the Test
+ * Account, capture the session as storage state, inject it into every
+ * agent's browser context. One login per Run — no parallel-login lockouts.
+ *
+ * v1 supports form-based login only; OAuth/SSO/MFA Targets fail early with a
+ * clear message (CONTEXT.md: Test Account). v1.1 adds a second *producer*
+ * (user-captured session) — the consuming side stays unchanged.
+ */
+export interface TestAccount {
+    username: string;
+    password: string;
+}
+export declare function testAccountFromEnv(): TestAccount | undefined;
+/** Perform the single form login and return the path to the captured storage state. */
+export declare function produceStorageState(_target: URL, _account: TestAccount): Promise<string>;

package/dist/auth/session.js

@@ -0,0 +1,14 @@
+export function testAccountFromEnv() {
+    const username = process.env.AUTOEND_USER;
+    const password = process.env.AUTOEND_PASS;
+    if (!username || !password)
+        return undefined;
+    return { username, password };
+}
+/** Perform the single form login and return the path to the captured storage state. */
+export async function produceStorageState(_target, _account) {
+    // TODO: drive the Target's login form once (Playwright), save storageState to
+    // a Run-scoped temp file, return its path for every explorer/replay context.
+    throw new Error('fleet auth is not implemented yet (scaffold)');
+}
+//# sourceMappingURL=session.js.map

package/dist/auth/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/auth/session.ts"],"names":[],"mappings":"AAcA,MAAM,UAAU,kBAAkB;IAChC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IAC1C,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IAC1C,IAAI,CAAC,QAAQ,IAAI,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC7C,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAChC,CAAC;AAED,uFAAuF;AACvF,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAAY,EAAE,QAAqB;IAC3E,8EAA8E;IAC9E,6EAA6E;IAC7E,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;AAClE,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { rm } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+import pc from 'picocolors';
+import { loadConfig, loadDotEnv } from './config.js';
+import { handsAvailable } from './explore/hands.js';
+import { runsDir } from './report/artifact.js';
+import { EFFORT_LEVELS, isEffort } from './run/effort.js';
+import { executeRun } from './run/run.js';
+import { runSetupWizard } from './setup/wizard.js';
+import { serveReport } from './viewer/server.js';
+const USAGE = `Usage:
+  autoend init               guided setup (target, effort, API key)
+  autoend [target-url]       start a Run (falls back to your configured target)
+  autoend clean              delete all local Run artifacts
+
+Options:
+  -e, --effort <level>   ${EFFORT_LEVELS.join(' | ')} (default: from config, else mid)
+      --no-open          don't open the Report in a browser
+      --no-serve         write the Run artifact and exit (CI-style)
+      --port <n>         viewer port (default: random)
+  -h, --help             show this help
+`;
+async function main() {
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: {
+            effort: { type: 'string', short: 'e' },
+            'no-open': { type: 'boolean', default: false },
+            'no-serve': { type: 'boolean', default: false },
+            port: { type: 'string', default: '0' },
+            help: { type: 'boolean', short: 'h', default: false },
+        },
+    });
+    if (values.help) {
+        process.stdout.write(USAGE);
+        return;
+    }
+    const repoRoot = process.cwd();
+    const command = positionals[0];
+    if (command === 'init') {
+        await runSetupWizard(repoRoot);
+        return;
+    }
+    if (command === 'clean') {
+        await rm(runsDir(repoRoot), { recursive: true, force: true });
+        console.log('Local Run artifacts deleted.');
+        return;
+    }
+    if (positionals.length > 1) {
+        process.stdout.write(USAGE);
+        process.exitCode = 2;
+        return;
+    }
+    await loadDotEnv(repoRoot);
+    const config = await loadConfig(repoRoot);
+    // First contact with no target and no config: hand over to the wizard.
+    if (!command && !config) {
+        if (process.stdout.isTTY) {
+            await runSetupWizard(repoRoot);
+            return;
+        }
+        console.error('error: no target configured — run `autoend init` or pass a URL');
+        process.exitCode = 2;
+        return;
+    }
+    let target;
+    try {
+        target = new URL(command ?? config.target);
+    }
+    catch {
+        console.error(`error: "${command}" is not a valid URL`);
+        process.exitCode = 2;
+        return;
+    }
+    const effortInput = values.effort ?? config?.effort ?? 'mid';
+    if (!isEffort(effortInput)) {
+        console.error(`error: unknown effort "${effortInput}" (expected ${EFFORT_LEVELS.join(', ')})`);
+        process.exitCode = 2;
+        return;
+    }
+    const effort = effortInput;
+    if (!process.env.CURSOR_API_KEY) {
+        console.warn(pc.yellow('warning: CURSOR_API_KEY not set — exploration will be skipped (run `autoend init`)'));
+    }
+    if (!(await handsAvailable())) {
+        console.warn(pc.yellow('warning: agent-browser not found on PATH — exploration will be skipped'));
+    }
+    console.log(`${pc.cyan('Run starting')} ${target.href} ${pc.dim(`· effort ${effort}`)}`);
+    const startedMs = Date.now();
+    const { artifactDir, artifact } = await executeRun({ target, effort, repoRoot });
+    const seconds = ((Date.now() - startedMs) / 1000).toFixed(1);
+    const failures = artifact.findings.filter((f) => f.kind === 'hard-failure').length;
+    const regressions = artifact.findings.filter((f) => f.kind === 'regression').length;
+    const advisories = artifact.findings.filter((f) => f.kind === 'advisory').length;
+    const verdict = failures + regressions > 0
+        ? pc.red(`${failures} hard failures, ${regressions} regressions`)
+        : pc.green('all clear');
+    console.log(`${pc.cyan(`Run finished in ${seconds}s`)} · ${artifact.flowsReplayed} replayed · ${artifact.flowsDiscovered} discovered · ${verdict}` +
+        (artifact.heals.length + advisories > 0 ? pc.dim(` · ${artifact.heals.length} heals, ${advisories} advisories`) : ''));
+    console.log(pc.dim(`Artifact: ${artifactDir}`));
+    if (values['no-serve'])
+        return;
+    const viewer = await serveReport(artifactDir, Number(values.port));
+    console.log(`Report: ${pc.underline(viewer.url)} ${pc.dim('(Ctrl+C to stop)')}`);
+    if (!values['no-open'])
+        openInBrowser(viewer.url);
+}
+function openInBrowser(url) {
+    const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+    spawn(command, [url], { detached: true, stdio: 'ignore', shell: process.platform === 'win32' }).unref();
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,14 @@
+import type { Effort } from './run/effort.js';
+/** Persisted by `autoend init`; flags on `autoend <url>` override it. */
+export interface AutoendConfig {
+    target: string;
+    effort: Effort;
+}
+export declare function configPath(repoRoot: string): string;
+export declare function loadConfig(repoRoot: string): Promise<AutoendConfig | undefined>;
+export declare function saveConfig(repoRoot: string, config: AutoendConfig): Promise<void>;
+/** Minimal .env loader — sets vars that aren't already in the environment. */
+export declare function loadDotEnv(repoRoot: string): Promise<void>;
+export declare function appendDotEnv(repoRoot: string, key: string, value: string): Promise<void>;
+/** Ensure the host repo's .gitignore contains each line (creates the file if missing). */
+export declare function ensureGitignore(repoRoot: string, lines: string[]): Promise<string[]>;

package/dist/config.js

@@ -0,0 +1,65 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export function configPath(repoRoot) {
+    return join(repoRoot, '.autoend', 'config.json');
+}
+export async function loadConfig(repoRoot) {
+    try {
+        return JSON.parse(await readFile(configPath(repoRoot), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function saveConfig(repoRoot, config) {
+    await mkdir(join(repoRoot, '.autoend'), { recursive: true });
+    await writeFile(configPath(repoRoot), JSON.stringify(config, null, 2));
+}
+/** Minimal .env loader — sets vars that aren't already in the environment. */
+export async function loadDotEnv(repoRoot) {
+    let raw;
+    try {
+        raw = await readFile(join(repoRoot, '.env'), 'utf8');
+    }
+    catch {
+        return;
+    }
+    for (const line of raw.split('\n')) {
+        const match = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/.exec(line);
+        if (match && process.env[match[1]] === undefined) {
+            process.env[match[1]] = match[2].replace(/^["']|["']$/g, '');
+        }
+    }
+}
+export async function appendDotEnv(repoRoot, key, value) {
+    const path = join(repoRoot, '.env');
+    let raw = '';
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch {
+        // no .env yet
+    }
+    const line = `${key}=${value}`;
+    const next = raw.length === 0 ? `${line}\n` : raw.endsWith('\n') ? `${raw}${line}\n` : `${raw}\n${line}\n`;
+    await writeFile(path, next);
+}
+/** Ensure the host repo's .gitignore contains each line (creates the file if missing). */
+export async function ensureGitignore(repoRoot, lines) {
+    const path = join(repoRoot, '.gitignore');
+    let raw = '';
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch {
+        // no .gitignore yet
+    }
+    const existing = new Set(raw.split('\n').map((l) => l.trim()));
+    const missing = lines.filter((l) => !existing.has(l));
+    if (missing.length > 0) {
+        const base = raw.length === 0 || raw.endsWith('\n') ? raw : `${raw}\n`;
+        await writeFile(path, `${base}${missing.join('\n')}\n`);
+    }
+    return missing;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/explore/explorer.d.ts

@@ -0,0 +1,42 @@
+import { type FlowMeta } from '../map/flow-map.js';
+import type { ExplorationBudget } from '../run/effort.js';
+import type { Finding } from '../report/types.js';
+export interface ExploreOptions {
+    repoRoot: string;
+    target: URL;
+    budget: ExplorationBudget;
+    /** This Run's artifact directory — explorers get a scratch dir inside it. */
+    runDir: string;
+    evidenceDir: string;
+    knownFlows: FlowMeta[];
+}
+export interface ExplorationResult {
+    discovered: number;
+    findings: Finding[];
+}
+export interface ProposedFlow {
+    id: string;
+    title: string;
+    script: string;
+}
+export interface ExplorerReport {
+    flows: ProposedFlow[];
+    findings: Array<{
+        kind: 'hard-failure' | 'advisory';
+        title: string;
+        detail: string;
+    }>;
+}
+/**
+ * Phase 2 of a Run (ADR-0001/0003): spawn Cursor local agents that hold the
+ * agent-browser CLI through the SDK's shell tool, each in an isolated browser
+ * session, time-boxed by the Effort budget. Flows they propose only enter the
+ * Flow Map after verify-by-running via the replay engine (ADR-0002).
+ */
+export declare function explore(opts: ExploreOptions): Promise<ExplorationResult>;
+/** Parse an explorer's final message. Exported for tests. */
+export declare function parseExplorerReport(text: string): ExplorerReport | undefined;
+/** Dedupe proposed flows against the map and each other. Exported for tests. */
+export declare function collectProposedFlows(reports: Array<ExplorerReport | undefined>, knownFlows: FlowMeta[]): ProposedFlow[];
+/** Kebab-case a title into a flow id. Exported for tests. */
+export declare function slugify(value: string): string | undefined;

package/dist/explore/explorer.js

@@ -0,0 +1,232 @@
+import { access, mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Agent } from '@cursor/sdk';
+import { chromium } from 'playwright';
+import { addFlow } from '../map/flow-map.js';
+import { runFlowScript } from '../replay/replay.js';
+import { closeSession } from './hands.js';
+/** Each explorer gets a distinct lens so the fleet doesn't converge on one path. */
+const LENSES = [
+    'Walk the primary user journey end to end, starting from the landing page — the path a first-time visitor is meant to take.',
+    'Exercise forms and inputs: search, signup, login, contact. Fill them with plausible test data and submit.',
+    'Explore navigation: menus, headers, footers, secondary pages. Verify links lead somewhere real.',
+    'Probe edge behavior: empty states, browser back/forward, repeating an action twice, unusual but legitimate input.',
+];
+/**
+ * Extra wall-clock the hard stop allows past the soft deadline given to
+ * agents. Live-run data: explorers on a multi-page target need 60-100s wall
+ * clock at low effort ('auto' model, 5-15s/turn) — a tight grace starves them
+ * right before they report, losing all their work.
+ */
+const GRACE_MS = 60_000;
+/**
+ * Phase 2 of a Run (ADR-0001/0003): spawn Cursor local agents that hold the
+ * agent-browser CLI through the SDK's shell tool, each in an isolated browser
+ * session, time-boxed by the Effort budget. Flows they propose only enter the
+ * Flow Map after verify-by-running via the replay engine (ADR-0002).
+ */
+export async function explore(opts) {
+    const apiKey = process.env.CURSOR_API_KEY;
+    if (!apiKey) {
+        console.warn('exploration skipped: CURSOR_API_KEY not set — run `autoend init`');
+        return { discovered: 0, findings: [] };
+    }
+    const workDir = join(opts.runDir, 'explore');
+    await mkdir(workDir, { recursive: true });
+    const reports = await Promise.all(Array.from({ length: opts.budget.explorers }, (_, i) => runExplorer(i, apiKey, workDir, opts)));
+    const findings = [];
+    for (const [i, report] of reports.entries()) {
+        if (!report)
+            continue;
+        const evidence = `explore-${i}.webm`;
+        const recorded = await access(join(opts.evidenceDir, evidence)).then(() => true, () => false);
+        for (const [n, f] of report.findings.entries()) {
+            findings.push({
+                id: `explore-${i}-${n}`,
+                kind: f.kind,
+                title: f.title,
+                detail: f.detail,
+                evidence: recorded ? evidence : undefined,
+            });
+        }
+    }
+    const proposed = collectProposedFlows(reports, opts.knownFlows);
+    let discovered = 0;
+    if (proposed.length > 0) {
+        const browser = await chromium.launch();
+        try {
+            for (const flow of proposed) {
+                const scriptPath = join(workDir, `${flow.id}.mts`);
+                await writeFile(scriptPath, flow.script);
+                const outcome = await runFlowScript(browser, scriptPath, opts.target, opts.evidenceDir, `discovered-${flow.id}`);
+                if (outcome.ok) {
+                    const now = new Date().toISOString();
+                    await addFlow(opts.repoRoot, { id: flow.id, title: flow.title, discoveredAt: now, lastPassedAt: now }, flow.script);
+                    discovered += 1;
+                }
+                else {
+                    console.warn(`proposed flow "${flow.id}" failed verification and was discarded: ${outcome.error}`);
+                }
+            }
+        }
+        finally {
+            await browser.close();
+        }
+    }
+    return { discovered, findings };
+}
+async function runExplorer(index, apiKey, workDir, opts) {
+    const session = `autoend-x${index}`;
+    const agent = await Agent.create({
+        name: `autoend-explorer-${index}`,
+        model: { id: 'auto' },
+        apiKey,
+        local: { cwd: workDir },
+    });
+    try {
+        const run = await agent.send(explorerPrompt(index, session, opts));
+        const outcome = (await Promise.race([
+            run.wait(),
+            sleep(opts.budget.seconds * 1000 + GRACE_MS).then(() => 'timeout'),
+        ]));
+        if (outcome === 'timeout') {
+            await run.cancel().catch(() => { });
+            console.warn(`explorer ${index} hit the time budget before reporting`);
+            return undefined;
+        }
+        if (outcome.status !== 'finished' || typeof outcome.result !== 'string') {
+            console.warn(`explorer ${index} ended with status "${outcome.status}"${outcome.error?.message ? `: ${outcome.error.message}` : ''}`);
+            return undefined;
+        }
+        const report = parseExplorerReport(outcome.result);
+        if (!report)
+            console.warn(`explorer ${index} returned an unparseable report`);
+        return report;
+    }
+    finally {
+        agent.close();
+        await closeSession(session);
+    }
+}
+function explorerPrompt(index, session, opts) {
+    const { target, budget, evidenceDir, knownFlows } = opts;
+    const videoPath = join(evidenceDir, `explore-${index}.webm`);
+    const known = knownFlows.length > 0
+        ? knownFlows.map((f) => `- ${f.title}`).join('\n')
+        : '(none yet — this is the first exploration of this app)';
+    return `You are autoend explorer #${index}, part of a fleet testing a web app end-to-end. You have ${budget.seconds} seconds of exploration; ${Math.round(GRACE_MS / 1000)}s after that deadline you are hard-killed and any unreported work is LOST — so report early rather than perfectly.
+
+TARGET: ${target.href}
+Your lens: ${LENSES[index % LENSES.length]}
+
+## Your browser
+Drive the browser with the agent-browser CLI via shell. EVERY command MUST include \`--session ${session}\` (other agents share the daemon; the flag isolates your browser).
+
+SPEED MATTERS: every shell call costs you a turn. BATCH commands whenever possible.
+
+Protocol — first shell call (one batch):
+  agent-browser --session ${session} batch "open ${target.href}" "record start ${videoPath}" "snapshot -i -c"
+Work loop (batch an action with the checks that follow it):
+  agent-browser --session ${session} batch "click @e12" "get url" "snapshot -i -c" "console" "errors"
+  agent-browser --session ${session} batch "fill @e5 test@example.com" "click @e7" "snapshot -i -c"
+Protocol — last shell call (NEVER skip, even when out of time):
+  agent-browser --session ${session} batch "record stop" "close"
+
+## Hard rules
+- NEVER navigate off the origin ${target.origin} — if a click leaves it, go back immediately.
+- Avoid destructive or irreversible actions (deleting data, real purchases, sending messages to third parties) unless a flow cannot be completed otherwise.
+- Do not read or modify files outside your working directory. Your only tools are agent-browser and trivial shell.
+
+## What to produce
+1. FLOWS — user-meaningful paths you verified work (e.g. "Visitor completes checkout"). Known flows, do NOT re-propose:
+${known}
+   For each NEW flow, write a Playwright script:
+   - default-export \`async function flow(page, target)\` — no imports; use only the \`page\` (Playwright Page) and \`target\` (URL) arguments
+   - navigate target-relative: \`await page.goto(new URL('/pricing', target).href)\` — page.goto() takes a STRING, so \`.href\` is MANDATORY (passing the URL object is the #1 script bug)
+   - prefer role/text locators: \`page.getByRole('link', { name: 'Pricing' })\`
+   - assert by throwing: \`if (!heading?.includes('Pricing')) throw new Error('expected Pricing, got ' + heading)\`
+   - keep it under ~25 lines; it must complete in under 60s
+2. FINDINGS —
+   - kind "hard-failure": objective breakage only (console/page errors, HTTP >= 400 responses, crashes, blank pages). Include the exact error output in detail.
+   - kind "advisory": your judgment on UX, accessibility, or speed. Be sparing; only what a developer would thank you for.
+
+## Final message — STRICT
+Reply with ONLY one JSON object, no prose, no markdown fences:
+{
+  "flows": [
+    { "id": "kebab-case-id", "title": "Visitor does something meaningful", "script": "export default async function flow(page, target) { ... }" }
+  ],
+  "findings": [
+    { "kind": "hard-failure", "title": "Short statement", "detail": "Exact evidence: error text, URL, HTTP status" }
+  ]
+}
+Empty arrays are fine. An honest empty report beats an invented one.`;
+}
+/** Parse an explorer's final message. Exported for tests. */
+export function parseExplorerReport(text) {
+    const start = text.indexOf('{');
+    const end = text.lastIndexOf('}');
+    if (start < 0 || end <= start)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(text.slice(start, end + 1));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const raw = parsed;
+    const flows = [];
+    if (Array.isArray(raw.flows)) {
+        for (const f of raw.flows) {
+            const id = slugify(String(f?.id ?? f?.title ?? ''));
+            const script = typeof f?.script === 'string' ? f.script : undefined;
+            if (id && script && script.includes('export default')) {
+                flows.push({ id, title: String(f.title ?? id), script });
+            }
+        }
+    }
+    const findings = [];
+    if (Array.isArray(raw.findings)) {
+        for (const f of raw.findings) {
+            if (typeof f?.title !== 'string')
+                continue;
+            findings.push({
+                kind: f.kind === 'hard-failure' ? 'hard-failure' : 'advisory',
+                title: f.title,
+                detail: typeof f.detail === 'string' ? f.detail : '',
+            });
+        }
+    }
+    return { flows, findings };
+}
+/** Dedupe proposed flows against the map and each other. Exported for tests. */
+export function collectProposedFlows(reports, knownFlows) {
+    const taken = new Set(knownFlows.map((f) => f.id));
+    const out = [];
+    for (const report of reports) {
+        for (const flow of report?.flows ?? []) {
+            if (taken.has(flow.id))
+                continue;
+            taken.add(flow.id);
+            out.push(flow);
+        }
+    }
+    return out;
+}
+/** Kebab-case a title into a flow id. Exported for tests. */
+export function slugify(value) {
+    const slug = value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 40)
+        .replace(/-+$/, '');
+    return slug.length > 0 ? slug : undefined;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=explorer.js.map