specweave 2.0.3 → 2.2.0

package/dist/src/core/jev/browse.js

@@ -0,0 +1,721 @@
+/**
+ * Jev headless browser delegation.
+ *
+ * A mechanical navigation loop where Jev picks the next action from an enumerated set
+ * of things visible on the page. The loop is always HEADLESS: it never launches a
+ * visible window, never types text the model chose (values come from `inputs` only),
+ * never leaves `allowDomains`, and hands control back to the agent the moment the page
+ * needs judgement (login, captcha, payment, free text).
+ *
+ * Playwright is loaded lazily — it is not a dependency of this package.
+ *
+ * @module core/jev/browse
+ */
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import { createRequire } from 'module';
+import * as path from 'path';
+import { createJevClient } from './client.js';
+import { JEV_DEFAULTS, loadJevConfig } from './config.js';
+/* ------------------------------------------------------------------ constants */
+/** Interactive things worth enumerating. Everything else is page furniture. */
+const INTERACTIVE_SELECTOR = 'a[href], button, [role=button], [role=link], [role=tab], [role=menuitem], input, select, textarea, summary, [onclick]';
+/** Controls we never click on the agent's behalf unless `allowSensitive` is set. */
+const SENSITIVE = /delete|remove|pay|purchase|buy|checkout|confirm order|send|submit|sign in|log in|password|unsubscribe|transfer/i;
+/**
+ * The same judgement for a link's destination: a harmless label ("Manage", "Preferences")
+ * can hide `/account/subscription/cancel?confirm=1`, and a GET performs it.
+ */
+const SENSITIVE_URL = /(^|[/_.-])(delete|destroy|remove|cancel|unsubscribe|opt-out|logout|signout|checkout|purchase|payments?|transfers?|refunds?)([/_.?&=-]|$)|[?&](confirm|delete|cancel|unsubscribe)=/i;
+/** Stamped on every described element so an action binds to it, not to its ordinal. */
+const REF_ATTR = 'data-jev-ref';
+const MAX_ELEMENTS = 120;
+const MAX_NAME_CHARS = 80;
+const MAX_EXCERPT_CHARS = 1500;
+const MAX_PAGE_TEXT_CHARS = 4000;
+const HARD_MAX_STEPS = 40;
+const DEFAULT_MAX_MS = 60000;
+const DEFAULT_MIN_CONFIDENCE = 0.55;
+const HISTORY_STEPS = 8;
+const ACTION_TIMEOUT_MS = 10000;
+/** Grace for a click that kicks off its navigation from JS (SPA routing, deferred assign). */
+const SETTLE_MS = 150;
+const PLAYWRIGHT_HINT = 'npm i -g playwright && npx playwright install chromium';
+const FIXED_ACTIONS = {
+    SCROLL_DOWN: 'Scroll further down this page to reveal content that is not visible yet.',
+    SCROLL_UP: 'Scroll back up this page to content that has scrolled out of view.',
+    BACK: 'Go back to the previous page; this page is a dead end or the wrong turn.',
+    WAIT: 'The page is still loading or updating; wait briefly and look again.',
+    DONE: 'The goal is fully achieved and visible on this page; nothing further is needed.',
+    BLOCKED: 'The goal cannot be reached from here: the path does not exist, the page is an error, or the site refuses.',
+    NEEDS_AGENT: 'This step needs login, a captcha, a payment, a file upload, free text, or a judgement only the agent can make.',
+};
+const NEXT_INSTRUCTIONS = 'Given the goal and the page described in the state, which single action moves closest to achieving the goal? Pick exactly one.';
+const GOAL_REACHED = {
+    type: 'noul',
+    instructions: 'Given the goal and the current page, is the requested end state already visible?',
+    criteria: {
+        true: 'the page currently shows the end state the goal describes',
+        false: 'the end state is not visible yet, or only a link towards it is visible',
+    },
+};
+/* ------------------------------------------------------------------- utilities */
+function collapse(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function messageOf(error) {
+    return error?.message ?? String(error);
+}
+function hostOf(url) {
+    try {
+        return new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return '';
+    }
+}
+/** Host-suffix match: `docs.example.com` is inside `example.com`. */
+function hostAllowed(host, allow) {
+    if (!host)
+        return false;
+    return allow.some((raw) => {
+        const d = raw.replace(/^\./, '').trim().toLowerCase();
+        if (!d)
+            return false;
+        return host === d || host.endsWith(`.${d}`);
+    });
+}
+/**
+ * The project's `jev.browse` settings, or the built-in defaults when the config cannot
+ * be read. Never throws: browsing degrades to the defaults rather than failing.
+ */
+function browseConfig(projectRoot) {
+    try {
+        return loadJevConfig(projectRoot).browse;
+    }
+    catch {
+        return { allowDomains: [...JEV_DEFAULTS.browse.allowDomains], maxSteps: JEV_DEFAULTS.browse.maxSteps };
+    }
+}
+/**
+ * Let an action's navigation actually commit before anyone reads `page.url()`.
+ *
+ * `click()` resolves as soon as the click is dispatched: a `history.pushState` route
+ * change or a `fetch().then(() => location.assign(...))` has not happened yet, so the
+ * URL still reads as the previous (allowed) page. Sleep first so the handler can start
+ * the navigation, then wait for the new document to commit.
+ */
+async function settle(page) {
+    await sleep(SETTLE_MS);
+    try {
+        if (typeof page.waitForLoadState === 'function') {
+            await page.waitForLoadState('domcontentloaded', { timeout: ACTION_TIMEOUT_MS });
+        }
+    }
+    catch {
+        /* no navigation to wait for is the normal case — carry on */
+    }
+}
+/** Best-effort retreat from a page we are not allowed to be on. */
+async function retreat(page) {
+    try {
+        await page.goBack({ waitUntil: 'domcontentloaded', timeout: ACTION_TIMEOUT_MS });
+    }
+    catch {
+        /* best effort — we are leaving anyway */
+    }
+}
+/**
+ * Why this link must never be offered or followed (null = fine). The label is only half
+ * the story: the target decides what a click actually does.
+ */
+function linkRefusal(href, base, allowSensitive) {
+    const raw = (href ?? '').trim();
+    if (!raw)
+        return null;
+    let target;
+    try {
+        target = new URL(raw, base || undefined);
+    }
+    catch {
+        return `unreadable link target "${raw.slice(0, 60)}"`;
+    }
+    if (target.protocol !== 'http:' && target.protocol !== 'https:') {
+        return `link target is not a web page (${target.protocol})`;
+    }
+    if (allowSensitive)
+        return null;
+    let where = `${target.pathname}${target.search}`;
+    try {
+        where = decodeURIComponent(where);
+    }
+    catch {
+        /* keep the encoded form — it is still worth matching */
+    }
+    if (SENSITIVE.test(where) || SENSITIVE_URL.test(where)) {
+        return `link target looks destructive (${where.slice(0, 60)})`;
+    }
+    return null;
+}
+/** Lazy Playwright: injected → local install → global npm root. Never throws. */
+async function loadPlaywright(injected) {
+    const pick = (mod) => {
+        const m = mod;
+        if (m && typeof m === 'object' && m.chromium)
+            return m;
+        if (m && typeof m === 'object' && m.default?.chromium)
+            return m.default;
+        return null;
+    };
+    const direct = pick(injected);
+    if (direct)
+        return direct;
+    const specs = ['playwright', 'playwright-core'];
+    for (const spec of specs) {
+        try {
+            const found = pick(await import(spec));
+            if (found)
+                return found;
+        }
+        catch {
+            /* not installed next to us — try the next strategy */
+        }
+    }
+    try {
+        const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+        const res = spawnSync(npm, ['root', '-g'], { encoding: 'utf-8', timeout: 15000 });
+        const root = String(res.stdout ?? '').trim().split(/\r?\n/).pop() ?? '';
+        if (root) {
+            const req = createRequire(path.join(root, 'noop.js'));
+            for (const spec of specs) {
+                try {
+                    const found = pick(req(spec));
+                    if (found)
+                        return found;
+                }
+                catch {
+                    /* keep looking */
+                }
+            }
+        }
+    }
+    catch {
+        /* npm missing or sandboxed — fall through to the hint */
+    }
+    return null;
+}
+/**
+ * Runs in the page: describe every interactive element we could act on.
+ *
+ * With `stamp` it also writes `data-jev-ref="<i>"` on each described element (and clears
+ * it from the ones it skips), so the action taken after the Jev round trip is aimed at
+ * the element itself instead of at an ordinal the page is free to shift meanwhile.
+ */
+function describeElements(els, stamp) {
+    const out = [];
+    els.forEach((el, i) => {
+        const any = el;
+        const unstamp = () => {
+            if (!stamp)
+                return;
+            try {
+                any.removeAttribute?.('data-jev-ref');
+            }
+            catch {
+                /* nothing we can do from in here */
+            }
+        };
+        let visible = true;
+        try {
+            const rect = any.getBoundingClientRect();
+            const view = any.ownerDocument?.defaultView;
+            const style = view?.getComputedStyle ? view.getComputedStyle(el) : null;
+            visible =
+                rect.width > 0 &&
+                    rect.height > 0 &&
+                    (!style || (style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0'));
+        }
+        catch {
+            visible = true;
+        }
+        if (!visible) {
+            unstamp();
+            return;
+        }
+        const tag = String(any.tagName ?? '').toLowerCase();
+        const type = String(any.getAttribute?.('type') ?? '').toLowerCase();
+        const explicitRole = String(any.getAttribute?.('role') ?? '').toLowerCase();
+        const role = explicitRole ||
+            (tag === 'a' ? 'link' : tag === 'input' ? (type || 'text') + ' input' : tag || 'element');
+        const raw = any.getAttribute?.('aria-label') ||
+            (typeof any.innerText === 'string' ? any.innerText : '') ||
+            any.getAttribute?.('placeholder') ||
+            any.getAttribute?.('title') ||
+            (typeof any.value === 'string' ? any.value : '') ||
+            any.getAttribute?.('name') ||
+            '';
+        const name = String(raw).replace(/\s+/g, ' ').trim().slice(0, 80);
+        if (!name) {
+            unstamp();
+            return;
+        }
+        const textish = ['text', 'search', 'email', 'url', 'tel', 'password', 'number', ''];
+        const kind = tag === 'textarea' || (tag === 'input' && textish.indexOf(type) >= 0)
+            ? 'input'
+            : tag === 'select'
+                ? 'select'
+                : 'clickable';
+        const href = tag === 'a' ? String(any.getAttribute?.('href') ?? '') : '';
+        if (stamp) {
+            try {
+                any.setAttribute?.('data-jev-ref', String(i));
+            }
+            catch {
+                /* an element we cannot stamp is one we will refuse to act on later */
+            }
+        }
+        out.push(href ? { i, role, name, href, kind } : { i, role, name, kind });
+    });
+    return out;
+}
+async function observe(page) {
+    const url = page.url();
+    let title = '';
+    try {
+        title = typeof page.title === 'function' ? String(await page.title()) : '';
+    }
+    catch {
+        title = '';
+    }
+    let bodyText = '';
+    try {
+        bodyText = String((await page.evaluate(() => (document.body ? document.body.innerText : ''))) ?? '');
+    }
+    catch {
+        bodyText = '';
+    }
+    const pageText = collapse(bodyText).slice(0, MAX_PAGE_TEXT_CHARS);
+    let elements = [];
+    try {
+        const raw = (await page.locator(INTERACTIVE_SELECTOR).evaluateAll(describeElements, true));
+        const seen = new Set();
+        for (const el of Array.isArray(raw) ? raw : []) {
+            if (!el || typeof el.i !== 'number' || !el.name)
+                continue;
+            const key = `${el.role}|${el.name.toLowerCase()}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            elements.push({ ...el, name: el.name.slice(0, MAX_NAME_CHARS) });
+            if (elements.length >= MAX_ELEMENTS)
+                break;
+        }
+    }
+    catch {
+        elements = [];
+    }
+    return { url, title, pageText, textExcerpt: pageText.slice(0, MAX_EXCERPT_CHARS), elements };
+}
+/** Enumerate the answers: one option per thing Jev is allowed to do here. */
+function buildCandidates(elements, inputs, allowSensitive, baseUrl) {
+    const candidates = new Map();
+    const criteria = {};
+    const inputKeys = Object.keys(inputs);
+    for (const el of elements) {
+        if (!allowSensitive && SENSITIVE.test(el.name))
+            continue;
+        if (linkRefusal(el.href, baseUrl, allowSensitive))
+            continue;
+        const key = `a${el.i}`;
+        if (el.kind === 'clickable') {
+            const label = `Click ${el.role} '${el.name}'`;
+            candidates.set(key, { key, label, index: el.i, role: el.role, name: el.name });
+            criteria[key] = label;
+        }
+        else if (el.kind === 'input') {
+            const match = inputKeys.find((k) => k.toLowerCase() === el.name.toLowerCase());
+            if (!match)
+                continue;
+            const label = `Type the provided value into '${el.name}'`;
+            candidates.set(key, { key, label, index: el.i, input: inputs[match], role: el.role, name: el.name });
+            criteria[key] = label;
+        }
+    }
+    for (const [key, description] of Object.entries(FIXED_ACTIONS)) {
+        candidates.set(key, { key, label: key });
+        criteria[key] = description;
+    }
+    return { candidates, criteria };
+}
+/**
+ * Bind the action to the element, not to its ordinal. Between `observe()` and here sits a
+ * full Jev round trip, and anything the page does meanwhile — a lazily loaded row, an ad,
+ * a cookie banner, an SPA re-render — shifts the ordinals. We re-read the element by its
+ * `data-jev-ref` stamp and refuse when it is not the one Jev was shown, or when it has
+ * become a control we are not allowed to touch. Returns a refusal, or null when it is safe.
+ */
+async function recheckTarget(page, chosen, allowSensitive, baseUrl) {
+    let live = null;
+    try {
+        const raw = (await page
+            .locator(`[${REF_ATTR}="${chosen.index}"]`)
+            .evaluateAll(describeElements, false));
+        live = Array.isArray(raw) && raw.length > 0 ? raw[0] : null;
+    }
+    catch {
+        return 'could not re-check the chosen element before acting';
+    }
+    if (!live || !live.name)
+        return 'the chosen element is no longer on the page';
+    const name = String(live.name).slice(0, MAX_NAME_CHARS);
+    if (live.role !== chosen.role || name !== chosen.name) {
+        return `the element changed after it was chosen (now ${live.role} '${name}')`;
+    }
+    if (!allowSensitive && SENSITIVE.test(name))
+        return 'the element is now a sensitive control';
+    const refusal = linkRefusal(live.href, baseUrl, allowSensitive);
+    return refusal ? `refusing to act: ${refusal}` : null;
+}
+function fingerprint(url, elements) {
+    return `${url}::${elements.map((e) => `${e.i}${e.role}${e.name}`).join('|')}`;
+}
+async function capture(page, dir, n) {
+    if (!dir)
+        return null;
+    const file = path.join(dir, `step-${n}.png`);
+    try {
+        await page.screenshot({ path: file, fullPage: false });
+        return file;
+    }
+    catch {
+        return null;
+    }
+}
+function screenshotDirFor(opts) {
+    try {
+        const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const dir = opts.screenshotDir ??
+            path.join(opts.projectRoot ?? process.cwd(), '.specweave', 'state', 'jev-browse', stamp);
+        fs.mkdirSync(dir, { recursive: true });
+        return dir;
+    }
+    catch {
+        return null;
+    }
+}
+function errorResult(error, extra) {
+    return {
+        status: 'error',
+        url: '',
+        title: '',
+        steps: [],
+        pageText: '',
+        screenshots: [],
+        elapsedMs: 0,
+        cost: 0,
+        error,
+        ...extra,
+    };
+}
+/* ----------------------------------------------------------------------- loop */
+/**
+ * Run the headless browse loop. Always resolves — failures come back as
+ * `status: 'error'` so an agent can keep going without a try/catch.
+ */
+export async function runBrowse(opts) {
+    const started = Date.now();
+    const goal = (opts.goal ?? '').trim();
+    if (!goal)
+        return errorResult('a goal is required');
+    const startUrl = (opts.url ?? '').trim();
+    if (!startUrl)
+        return errorResult('a start url is required');
+    if (!hostOf(startUrl))
+        return errorResult(`not a browsable url: ${startUrl}`);
+    // Flags win over `jev.browse` in .specweave/config.json, which wins over "this host only".
+    const cfgBrowse = browseConfig(opts.projectRoot);
+    const allow = opts.allowDomains?.length
+        ? opts.allowDomains
+        : cfgBrowse.allowDomains.length
+            ? cfgBrowse.allowDomains
+            : [hostOf(startUrl)];
+    // Nothing is fetched, screenshotted or sent to Jev from an origin the operator excluded
+    // — including the very first page, which used to be loaded unconditionally.
+    if (!hostAllowed(hostOf(startUrl), allow)) {
+        return errorResult(`start url is outside the allowed origins (${hostOf(startUrl)} not in ${allow.join(', ')})`, { status: 'blocked', handoff: `${goal} — start url ${startUrl} is not an allowed origin` });
+    }
+    const client = opts.client ?? createJevClient(opts.projectRoot);
+    if (!client)
+        return errorResult('jev unavailable');
+    const pw = await loadPlaywright(opts.playwright);
+    if (!pw)
+        return errorResult(`playwright is not installed — ${PLAYWRIGHT_HINT}`);
+    const maxSteps = Math.max(1, Math.min(opts.maxSteps ?? cfgBrowse.maxSteps, HARD_MAX_STEPS));
+    const maxMs = opts.maxMs ?? DEFAULT_MAX_MS;
+    const minConfidence = opts.minConfidence ?? DEFAULT_MIN_CONFIDENCE;
+    const inputs = opts.inputs ?? {};
+    const allowSensitive = opts.allowSensitive === true;
+    const dir = screenshotDirFor(opts);
+    const steps = [];
+    const screenshots = [];
+    const history = [];
+    let status = 'step_limit';
+    let error;
+    let cost = 0;
+    let url = startUrl;
+    let title = '';
+    let pageText = '';
+    let prevSignature = '';
+    let unconfirmedDone = 0;
+    // HEADLESS IS NOT AN OPTION — there is deliberately no way to open a window here.
+    let browser;
+    try {
+        browser = await pw.chromium.launch({ headless: true });
+    }
+    catch (e) {
+        return errorResult(`could not launch headless chromium: ${messageOf(e)} — ${PLAYWRIGHT_HINT}`, {
+            elapsedMs: Date.now() - started,
+            handoff: `${goal} — browser unavailable`,
+        });
+    }
+    let page = null;
+    try {
+        page = await browser.newPage();
+        await page.goto(startUrl, { waitUntil: 'domcontentloaded', timeout: ACTION_TIMEOUT_MS * 3 });
+        for (let n = 1; n <= maxSteps; n++) {
+            if (Date.now() - started > maxMs) {
+                status = 'budget';
+                break;
+            }
+            // Backstop for a navigation that committed after the previous step's check (SPA
+            // routing, a deferred `location.assign`). Checked BEFORE we observe or screenshot,
+            // so an off-origin page is never scraped or sent to Jev.
+            const landedUrl = page.url();
+            const landedHost = hostOf(landedUrl);
+            if (!hostAllowed(landedHost, allow)) {
+                steps.push({
+                    n,
+                    url: landedUrl,
+                    action: 'origin check',
+                    choice: '',
+                    confidence: 0,
+                    apiMs: 0,
+                    executed: false,
+                    reason: `navigated outside the allowed origins (${landedHost || landedUrl})`,
+                });
+                await retreat(page);
+                url = page.url();
+                status = 'blocked';
+                break;
+            }
+            const obs = await observe(page);
+            url = obs.url;
+            title = obs.title;
+            pageText = obs.pageText;
+            const shot = await capture(page, dir, n);
+            if (shot)
+                screenshots.push(shot);
+            const { candidates, criteria } = buildCandidates(obs.elements, inputs, allowSensitive, obs.url);
+            const state = {
+                goal,
+                url: obs.url,
+                title: obs.title,
+                textExcerpt: obs.textExcerpt,
+                elements: obs.elements.map((e) => ({ i: e.i, role: e.role, name: e.name, href: e.href ?? null })),
+                history: history.slice(-HISTORY_STEPS),
+            };
+            let answerChoice = '';
+            let confidence = 0;
+            let goalReached = 0;
+            let apiMs = 0;
+            try {
+                const response = await client.ask(state, { next: { type: 'choice', instructions: NEXT_INSTRUCTIONS, criteria }, goal_reached: GOAL_REACHED }, { kind: 'browse' });
+                cost += response.usage.cost ?? 0;
+                apiMs = response.latencyMs;
+                const next = response.answers.next;
+                if (next && next.type === 'choice') {
+                    answerChoice = next.choice;
+                    confidence = next.confidence;
+                }
+                const reached = response.answers.goal_reached;
+                goalReached = reached && reached.type === 'noul' ? reached.noul : 0;
+            }
+            catch (e) {
+                status = 'error';
+                error = messageOf(e);
+                steps.push({ n, url: obs.url, action: 'ask', choice: '', confidence: 0, apiMs: 0, executed: false, reason: error });
+                break;
+            }
+            const chosen = candidates.get(answerChoice);
+            const action = chosen?.label ?? answerChoice ?? 'unknown';
+            const step = { n, url: obs.url, action, choice: answerChoice, confidence, apiMs, executed: false };
+            if (!chosen) {
+                step.reason = `Jev returned an unknown option "${answerChoice}"`;
+                steps.push(step);
+                status = 'blocked';
+                break;
+            }
+            if (confidence < minConfidence) {
+                step.reason = `confidence ${confidence.toFixed(2)} below minimum ${minConfidence} (goal_reached ${goalReached.toFixed(2)})`;
+                steps.push(step);
+                status = 'low_confidence';
+                break;
+            }
+            const signature = `${answerChoice}::${fingerprint(obs.url, obs.elements)}`;
+            switch (answerChoice) {
+                case 'DONE': {
+                    if (goalReached >= 0.8) {
+                        step.executed = true;
+                        step.reason = `goal visible (${goalReached.toFixed(2)})`;
+                        steps.push(step);
+                        status = 'done';
+                    }
+                    else if (unconfirmedDone === 0) {
+                        unconfirmedDone++;
+                        step.reason = `done claimed but the goal is not visible (${goalReached.toFixed(2)}) — looking again`;
+                        steps.push(step);
+                        history.push({ action, outcome: 'done not confirmed' });
+                        prevSignature = signature;
+                        continue;
+                    }
+                    else {
+                        step.reason = 'done claimed twice without the goal being visible';
+                        steps.push(step);
+                        status = 'blocked';
+                    }
+                    break;
+                }
+                case 'BLOCKED': {
+                    step.reason = 'Jev reports the goal is unreachable from here';
+                    steps.push(step);
+                    status = 'blocked';
+                    break;
+                }
+                case 'NEEDS_AGENT': {
+                    step.reason = 'the page needs a human or agent judgement (login, captcha, payment, free text)';
+                    steps.push(step);
+                    status = 'needs_agent';
+                    break;
+                }
+                default: {
+                    if (signature === prevSignature) {
+                        step.reason = 'no progress: the same action on an unchanged page';
+                        steps.push(step);
+                        status = 'blocked';
+                        break;
+                    }
+                    prevSignature = signature;
+                    try {
+                        if (answerChoice === 'SCROLL_DOWN') {
+                            await page.evaluate((d) => window.scrollBy(0, Math.round(window.innerHeight * 0.9) * d), 1);
+                        }
+                        else if (answerChoice === 'SCROLL_UP') {
+                            await page.evaluate((d) => window.scrollBy(0, Math.round(window.innerHeight * 0.9) * d), -1);
+                        }
+                        else if (answerChoice === 'BACK') {
+                            await page.goBack({ waitUntil: 'domcontentloaded', timeout: ACTION_TIMEOUT_MS });
+                        }
+                        else if (answerChoice === 'WAIT') {
+                            await sleep(1000);
+                        }
+                        else if (chosen.index !== undefined) {
+                            // Act on the element itself, never on its ordinal: `observe()` stamped it,
+                            // and this re-check refuses the step if the page swapped it meanwhile.
+                            const stale = await recheckTarget(page, chosen, allowSensitive, obs.url);
+                            if (stale) {
+                                step.reason = stale;
+                                steps.push(step);
+                                history.push({ action, outcome: 'skipped: the page changed under the choice' });
+                                continue;
+                            }
+                            const target = page.locator(`[${REF_ATTR}="${chosen.index}"]`).nth(0);
+                            if (chosen.input !== undefined) {
+                                await target.fill(chosen.input, { timeout: ACTION_TIMEOUT_MS });
+                            }
+                            else {
+                                await target.click({ timeout: ACTION_TIMEOUT_MS });
+                            }
+                        }
+                        step.executed = true;
+                    }
+                    catch (e) {
+                        step.reason = `action failed: ${messageOf(e)}`;
+                        steps.push(step);
+                        history.push({ action, outcome: 'action failed' });
+                        continue;
+                    }
+                    // Wait for any navigation the action started to commit — `page.url()` read
+                    // straight after `click()` still reports the previous, allowed page.
+                    await settle(page);
+                    const landed = page.url();
+                    if (!hostAllowed(hostOf(landed), allow)) {
+                        step.reason = `navigated outside the allowed origins (${hostOf(landed) || landed})`;
+                        steps.push(step);
+                        await retreat(page);
+                        url = page.url();
+                        status = 'blocked';
+                        break;
+                    }
+                    steps.push(step);
+                    history.push({ action, outcome: `now at ${landed}` });
+                    url = landed;
+                    continue;
+                }
+            }
+            break;
+        }
+        if (status !== 'error') {
+            try {
+                // Only re-read the page when we are still somewhere we are allowed to be: the
+                // final observation ends up in `pageText`, and that must never be off-origin.
+                if (hostAllowed(hostOf(page.url()), allow)) {
+                    const final = await observe(page);
+                    url = final.url;
+                    title = final.title;
+                    pageText = final.pageText;
+                }
+            }
+            catch {
+                /* keep the last known observation */
+            }
+        }
+    }
+    catch (e) {
+        status = 'error';
+        error = messageOf(e);
+    }
+    finally {
+        try {
+            if (page?.close)
+                await page.close();
+        }
+        catch {
+            /* ignore */
+        }
+        try {
+            await browser.close();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    const result = {
+        status,
+        url,
+        title,
+        steps,
+        pageText,
+        screenshots,
+        elapsedMs: Date.now() - started,
+        cost,
+    };
+    if (error)
+        result.error = error;
+    if (status !== 'done')
+        result.handoff = `${goal} — unfinished at ${url} (${status})`;
+    return result;
+}
+//# sourceMappingURL=browse.js.map