@agenttool/browser 0.1.0 → 0.3.0

package/dist/src/browser.js

@@ -3,9 +3,12 @@ import { existsSync } from "node:fs";
 import { chmod, lstat, mkdir, realpath } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { performance } from "node:perf_hooks";
+import { resolveBrowserCapabilities, } from "./capabilities.js";
 import { asBrowserError, BrowserError } from "./errors.js";
+import { planBrowserAction, } from "./planning.js";
 import { BrowserNetworkPolicy, redactHtmlUrlAttributes, redactUrlReferenceForOutput, redactUrlForOutput, redactUrlsInText, } from "./policy.js";
-import { boundText, compactAriaSnapshot, intersectsViewport, looksLikeSensitiveControl, parseAriaCandidates, redactAriaSecrets, redactSensitiveInputValues, } from "./snapshot.js";
+import { boundText, compactAriaSnapshot, intersectsViewport, looksLikeSensitiveControl, parseAriaCandidates, parseStructuralAriaCandidates, redactAriaSecrets, redactSensitiveInputValues, } from "./snapshot.js";
 import { OBSERVATION_SCHEMA, } from "./types.js";
 export const DEFAULT_BROWSER_LIMITS = Object.freeze({
     maxSnapshotChars: 24_000,
@@ -20,6 +23,12 @@ const DEFAULT_VIEWPORT = Object.freeze({ width: 1280, height: 720 });
 const DEFAULT_ACTION_TIMEOUT_MS = 10_000;
 const DEFAULT_NAVIGATION_TIMEOUT_MS = 30_000;
 const MAX_RESPONSE_HINT_CHARS = 4_096;
+const MAX_RETAINED_SNAPSHOTS_PER_TAB = 8;
+const MAX_STRUCTURAL_CONTEXT_ELEMENTS = 32;
+const VIEWPORT_SETTLE_INTERVAL_MS = 25;
+const VIEWPORT_SETTLE_MAX_MS = 1_000;
+const VIEWPORT_SETTLE_STABLE_INTERVALS = 2;
+const VIEWPORT_SETTLE_TOLERANCE_PX = 0.5;
 const RESPONSE_HINT_HEADERS = Object.freeze([
     "link",
     "content-location",
@@ -39,9 +48,12 @@ export class AgentBrowser {
     browser;
     states = new Map();
     pageStates = new Map();
+    requestPolicyDenials = new Map();
     activeTabId = null;
     nextTabNumber = 1;
+    requestPolicyDenialSequence = 0;
     closed = false;
+    closePromise = null;
     operationTail = Promise.resolve();
     constructor(options, context, browser) {
         this.sessionId = `session_${randomUUID()}`;
@@ -49,8 +61,7 @@ export class AgentBrowser {
         this.context = context;
         this.browser = browser;
         this.policy = new BrowserNetworkPolicy({
-            allowPublicWeb: options.allowPublicWeb,
-            allowLocalNetwork: options.allowLocalNetwork,
+            capabilities: options.capabilities,
             ...(options.resolveHostname
                 ? { resolveHostname: options.resolveHostname }
                 : {}),
@@ -79,7 +90,7 @@ export class AgentBrowser {
                 viewport: normalized.viewport,
                 acceptDownloads: false,
                 ignoreHTTPSErrors: false,
-                serviceWorkers: "block",
+                serviceWorkers: normalized.capabilities.runtime.serviceWorkers,
             };
             if (normalized.profile.mode === "persistent") {
                 context = await runtime.launchPersistentContext(normalized.profile.directory, { ...launchOptions, ...contextOptions });
@@ -101,13 +112,7 @@ export class AgentBrowser {
         }
         catch (error) {
             try {
-                await context?.close();
-            }
-            catch {
-                // Preserve the launch error; cleanup failure is secondary.
-            }
-            try {
-                await browser?.close();
+                await closeRuntime(browser, context);
             }
             catch {
                 // Preserve the launch error; cleanup failure is secondary.
@@ -122,9 +127,12 @@ export class AgentBrowser {
     async openUnlocked(url) {
         this.assertOpen();
         const destination = await this.policy.assertAllowed(url);
+        this.assertOpen();
         const page = await this.context.newPage();
+        this.assertOpen();
         const state = this.registerPage(page);
         this.activeTabId = state.id;
+        const denialSequence = this.requestPolicyDenialSequence;
         try {
             this.clearMainDocumentResponse(state);
             const response = await page.goto(destination.href, {
@@ -132,9 +140,15 @@ export class AgentBrowser {
                 timeout: this.options.navigationTimeoutMs,
             });
             this.queueMainDocumentResponse(state, response);
+            const denial = this.requestPolicyDenialAfter(denialSequence, state.id);
+            if (denial)
+                throw denial;
         }
         catch (error) {
             this.invalidate(state);
+            const denial = this.requestPolicyDenialAfter(denialSequence, state.id);
+            if (denial)
+                throw denial;
             throw asBrowserError(error, "action_failed", "Navigation was attempted once and did not complete.");
         }
         return this.observeUnlocked({ tabId: state.id });
@@ -151,8 +165,12 @@ export class AgentBrowser {
         }
         const state = this.getState(options.tabId);
         this.activeTabId = state.id;
-        this.invalidate(state);
-        const snapshotId = `${this.sessionId}:${state.id}:${state.revision}`;
+        await this.awaitWindowViewportSettled(state.page);
+        this.assertOpen();
+        state.revision += 1;
+        const observationRevision = state.revision;
+        const observationNavigationEpoch = state.navigationEpoch;
+        const snapshotId = `${this.sessionId}:${state.id}:${observationRevision}`;
         const viewport = state.page.viewportSize() ?? this.options.viewport;
         const includeText = options.includeText ?? true;
         const maxTextChars = boundedPositiveInteger(options.maxTextChars, this.options.limits.maxTextChars, "maxTextChars", this.options.limits.maxTextChars);
@@ -163,39 +181,63 @@ export class AgentBrowser {
                 timeout: this.options.actionTimeoutMs,
             });
             const candidates = parseAriaCandidates(raw).slice(0, this.options.limits.maxSnapshotElements * 3);
-            const inspected = await Promise.all(candidates.map(async (candidate) => {
-                const locator = state.page.locator(`aria-ref=${candidate.nativeRef}`);
-                try {
-                    if ((await locator.count()) !== 1 || !(await locator.isVisible())) {
+            const structuralCandidateScanLimit = MAX_STRUCTURAL_CONTEXT_ELEMENTS * 3;
+            const allStructuralCandidates = parseStructuralAriaCandidates(raw);
+            const structuralCandidates = allStructuralCandidates.slice(0, structuralCandidateScanLimit);
+            const [inspected, inspectedStructural] = await Promise.all([
+                Promise.all(candidates.map(async (candidate) => {
+                    const locator = state.page.locator(`aria-ref=${candidate.nativeRef}`);
+                    try {
+                        if ((await locator.count()) !== 1 || !(await locator.isVisible())) {
+                            return null;
+                        }
+                        if (!intersectsViewport(await locator.boundingBox(), viewport)) {
+                            return null;
+                        }
+                        const attributeNames = [
+                            "type",
+                            "autocomplete",
+                            "name",
+                            "id",
+                            "placeholder",
+                            "aria-label",
+                        ];
+                        const values = await Promise.all(attributeNames.map((name) => locator.getAttribute(name)));
+                        const attributes = {};
+                        attributeNames.forEach((name, index) => {
+                            attributes[name] = values[index] ?? null;
+                        });
+                        return {
+                            candidate,
+                            secret: looksLikeSensitiveControl(attributes, candidate.name),
+                        };
+                    }
+                    catch {
+                        // The page changed while it was being observed. Omit that target;
+                        // never guess a replacement ref.
                         return null;
                     }
-                    if (!intersectsViewport(await locator.boundingBox(), viewport))
+                })),
+                Promise.all(structuralCandidates.map(async (candidate) => {
+                    const locator = state.page.locator(`aria-ref=${candidate.nativeRef}`);
+                    try {
+                        if ((await locator.count()) !== 1 || !(await locator.isVisible())) {
+                            return null;
+                        }
+                        if (!intersectsViewport(await locator.boundingBox(), viewport)) {
+                            return null;
+                        }
+                        return candidate.nativeRef;
+                    }
+                    catch {
+                        // Structural context is optional. Omit a node whose geometry
+                        // changed rather than exposing an unbound or guessed context.
                         return null;
-                    const attributeNames = [
-                        "type",
-                        "autocomplete",
-                        "name",
-                        "id",
-                        "placeholder",
-                        "aria-label",
-                    ];
-                    const values = await Promise.all(attributeNames.map((name) => locator.getAttribute(name)));
-                    const attributes = {};
-                    attributeNames.forEach((name, index) => {
-                        attributes[name] = values[index] ?? null;
-                    });
-                    return {
-                        candidate,
-                        secret: looksLikeSensitiveControl(attributes, candidate.name),
-                    };
-                }
-                catch {
-                    // The page changed while it was being observed. Omit that target;
-                    // never guess a replacement ref.
-                    return null;
-                }
-            }));
+                    }
+                })),
+            ]);
             const visibleRefs = new Set();
+            const visibleStructuralRefs = new Set();
             const secretRefs = new Set();
             const publicRefs = new Map();
             for (const item of inspected) {
@@ -207,16 +249,21 @@ export class AgentBrowser {
                 if (item.secret)
                     secretRefs.add(item.candidate.nativeRef);
             }
+            for (const nativeRef of inspectedStructural) {
+                if (nativeRef)
+                    visibleStructuralRefs.add(nativeRef);
+            }
             const sanitizedRaw = redactUrlsInText(redactAriaSecrets(raw, secretRefs));
             const compact = compactAriaSnapshot(sanitizedRaw, {
                 publicRefs,
                 visibleRefs,
+                visibleStructuralRefs,
                 secretRefs,
                 maxChars: this.options.limits.maxSnapshotChars,
                 maxElements: this.options.limits.maxSnapshotElements,
+                maxStructuralElements: MAX_STRUCTURAL_CONTEXT_ELEMENTS,
             });
-            state.snapshotId = snapshotId;
-            state.refs = new Map(compact.refs.map((ref) => {
+            const snapshotRefs = new Map(compact.refs.map((ref) => {
                 const nativeRef = publicRefsEntries(publicRefs, ref.ref);
                 return [ref.ref, nativeRef];
             }));
@@ -240,13 +287,15 @@ export class AgentBrowser {
                 : null;
             if (responseSequence !== state.responseSequence)
                 response = null;
+            this.assertObservationCurrent(state, observationRevision, observationNavigationEpoch);
+            this.rememberSnapshot(state, snapshotId, snapshotRefs, observationNavigationEpoch);
             return {
                 schema: OBSERVATION_SCHEMA,
                 sessionId: this.sessionId,
                 snapshotId,
                 tabId: state.id,
                 pageId: state.id,
-                revision: state.revision,
+                revision: observationRevision,
                 url,
                 title,
                 snapshot: compact.snapshot,
@@ -254,7 +303,8 @@ export class AgentBrowser {
                 refs: compact.refs,
                 response,
                 truncated: {
-                    snapshot: compact.truncated.snapshot,
+                    snapshot: compact.truncated.snapshot
+                        || allStructuralCandidates.length > structuralCandidateScanLimit,
                     text: textTruncated,
                     elements: compact.truncated.elements
                         || candidates.length
@@ -265,24 +315,37 @@ export class AgentBrowser {
             };
         }
         catch (error) {
-            state.snapshotId = null;
-            state.refs.clear();
             throw asBrowserError(error, "action_failed", "Could not create a bounded browser observation.");
         }
     }
     async act(action) {
-        return this.withLock(() => this.actUnlocked(action));
+        const capturedAction = captureBrowserAction(action);
+        return this.withLock(() => this.actUnlocked(capturedAction));
+    }
+    /** Return the immutable authority manifest selected when this session launched. */
+    capabilities() {
+        return this.options.capabilities;
+    }
+    /**
+     * Forecast possible consequences without touching the page or executing the
+     * action. Planning is advisory and never widens launch-time authority.
+     */
+    plan(action) {
+        this.assertOpen();
+        validateAction(action, this.options);
+        return planBrowserAction(action, this.options.capabilities);
     }
     /**
      * Atomic convenience for process adapters: no other session operation can
      * interleave between the one action attempt and its read-only observation.
      */
     async actAndObserve(action) {
+        const capturedAction = captureBrowserAction(action);
         return this.withLock(async () => {
-            const actionResult = await this.actUnlocked(action);
+            const actionResult = await this.actUnlocked(capturedAction);
             try {
                 const observation = await this.observeUnlocked({
-                    ...(action.kind !== "close_tab" && actionResult.tabId
+                    ...(capturedAction.kind !== "close_tab" && actionResult.tabId
                         ? { tabId: actionResult.tabId }
                         : {}),
                 });
@@ -316,15 +379,20 @@ export class AgentBrowser {
             return this.closeTab(state);
         let resolved = null;
         if ("ref" in action && typeof action.ref === "string") {
-            resolved = await this.resolveRef(state, action.ref, action.snapshotId, action.kind !== "scroll");
+            resolved = await this.resolveRef(state, action.ref, action.snapshotId, action.kind !== "scroll", true);
         }
-        if (action.kind === "navigate")
-            await this.policy.assertAllowed(action.url);
+        const navigationDestination = action.kind === "navigate"
+            ? await this.policy.assertAllowed(action.url)
+            : null;
+        this.assertOpen();
+        const denialSequence = this.requestPolicyDenialSequence;
         try {
+            if (resolved)
+                this.assertResolvedRefCurrent(resolved);
             switch (action.kind) {
                 case "navigate":
                     this.clearMainDocumentResponse(state);
-                    this.queueMainDocumentResponse(state, await state.page.goto(action.url, {
+                    this.queueMainDocumentResponse(state, await state.page.goto(navigationDestination.href, {
                         waitUntil: "domcontentloaded",
                         timeout: this.options.navigationTimeoutMs,
                     }));
@@ -377,8 +445,14 @@ export class AgentBrowser {
                 default:
                     throw new BrowserError("invalid_action", "Unsupported browser action.");
             }
+            const denial = this.requestPolicyDenialAfter(denialSequence, state.id);
+            if (denial)
+                throw denial;
         }
         catch (error) {
+            const denial = this.requestPolicyDenialAfter(denialSequence, state.id);
+            if (denial)
+                throw denial;
             throw asBrowserError(error, "action_failed", "Browser action was attempted once and did not complete.");
         }
         finally {
@@ -393,9 +467,12 @@ export class AgentBrowser {
         this.assertOpen();
         validateExtractInput(input, this.options.limits.maxExtractChars);
         const state = this.getState(input.tabId);
+        const refTargeted = "ref" in input && typeof input.ref === "string";
+        let resolved = null;
         let locator;
-        if ("ref" in input && typeof input.ref === "string") {
-            locator = (await this.resolveRef(state, input.ref, input.snapshotId, false)).locator;
+        if (refTargeted) {
+            resolved = await this.resolveRef(state, input.ref, input.snapshotId, false, false);
+            locator = resolved.locator;
         }
         else {
             locator = state.page.locator(input.selector ?? "body");
@@ -404,16 +481,25 @@ export class AgentBrowser {
         const rawUrl = state.page.url();
         try {
             if (input.format === "links") {
-                const linkLocator = locator.locator("a[href]");
-                const count = await linkLocator.count();
+                const selfLinkLocator = refTargeted
+                    ? locator.locator("xpath=self::*[local-name()='a'][@href]")
+                    : null;
+                const selfLinkCount = selfLinkLocator
+                    ? Math.min(await selfLinkLocator.count(), 1)
+                    : 0;
+                const descendantLinkLocator = locator.locator("a[href]");
+                const descendantLinkCount = await descendantLinkLocator.count();
+                const count = selfLinkCount + descendantLinkCount;
                 const links = [];
                 let usedChars = 0;
                 let truncated = count > this.options.limits.maxExtractLinks;
                 const limit = Math.min(count, this.options.limits.maxExtractLinks);
                 for (let index = 0; index < limit; index += 1) {
-                    const link = linkLocator.nth(index);
+                    const link = index < selfLinkCount
+                        ? selfLinkLocator.nth(index)
+                        : descendantLinkLocator.nth(index - selfLinkCount);
                     const href = await link.getAttribute("href");
-                    if (!href)
+                    if (href === null)
                         continue;
                     const text = redactUrlsInText((await link.textContent())?.trim() ?? "");
                     const resolvedHref = redactUrlForOutput(safeResolveUrl(href, rawUrl));
@@ -425,6 +511,9 @@ export class AgentBrowser {
                     usedChars += chars;
                     links.push({ text, href: resolvedHref });
                 }
+                if (resolved)
+                    this.assertResolvedRefCurrent(resolved);
+                this.assertOpen();
                 return {
                     format: input.format,
                     sessionId: this.sessionId,
@@ -442,6 +531,9 @@ export class AgentBrowser {
                 ? redactHtmlUrlAttributes(redactSensitiveInputValues(await locator.innerHTML()))
                 : await locator.innerText();
             const bounded = boundText(redactUrlsInText(rawContent), maxChars);
+            if (resolved)
+                this.assertResolvedRefCurrent(resolved);
+            this.assertOpen();
             return {
                 format: input.format,
                 sessionId: this.sessionId,
@@ -475,8 +567,11 @@ export class AgentBrowser {
         const artifactPath = join(this.options.outputDir, `${timestamp}-${state.id}-${randomUUID()}.png`);
         try {
             await validateCanonicalStoragePaths(this.options.profile, this.options.outputDir);
+            this.assertOpen();
             await ensurePrivateDirectory(this.options.outputDir, "artifact");
+            this.assertOpen();
             await validateCanonicalStoragePaths(this.options.profile, this.options.outputDir);
+            this.assertOpen();
             const bytes = await state.page.screenshot({
                 path: artifactPath,
                 fullPage,
@@ -484,6 +579,7 @@ export class AgentBrowser {
             });
             if (process.platform !== "win32")
                 await chmod(artifactPath, 0o600);
+            this.assertOpen();
             const rawUrl = state.page.url();
             return {
                 sessionId: this.sessionId,
@@ -519,42 +615,53 @@ export class AgentBrowser {
                 title: boundText(redactUrlsInText(await state.page.title()), 512).value,
                 active: state.id === this.activeTabId,
             });
+            this.assertOpen();
         }
         return summaries;
     }
-    async close() {
-        return this.withLock(() => this.closeUnlocked());
-    }
-    async closeUnlocked() {
-        if (this.closed)
-            return;
+    close() {
+        if (this.closePromise)
+            return this.closePromise;
         this.closed = true;
         this.states.clear();
         this.pageStates.clear();
-        try {
-            await this.context.close();
-        }
-        finally {
-            await this.browser?.close();
-        }
+        this.requestPolicyDenials.clear();
+        const closing = Promise.resolve().then(() => closeRuntime(this.browser, this.context));
+        this.closePromise = closing;
+        return closing;
     }
     async installRequestPolicy() {
         await this.context.route("**/*", async (route) => {
+            const request = route.request();
+            try {
+                await this.policy.assertAllowed(request.url());
+            }
+            catch (error) {
+                this.recordMainFrameRequestPolicyDenial(request, asBrowserError(error, "network_blocked", "Browser request was denied by the launch-time network policy."));
+                await route.abort("blockedbyclient");
+                return;
+            }
             try {
-                await this.policy.assertAllowed(route.request().url());
                 await route.continue();
             }
             catch {
                 await route.abort("blockedbyclient");
             }
         });
-        // HTTP routing does not cover WebSockets. V0 blocks every WebSocket
-        // connection instead of claiming the HTTP(S) DNS policy covers it.
         await this.context.routeWebSocket("**/*", async (route) => {
-            await route.close({
-                code: 1008,
-                reason: "WebSockets are blocked by AgentBrowser policy",
-            });
+            try {
+                await this.policy.assertWebSocketAllowed(route.url());
+                if (typeof route.connectToServer !== "function") {
+                    throw new BrowserError("invalid_options", "Browser runtime cannot pass an allowed WebSocket to its server.");
+                }
+                route.connectToServer();
+            }
+            catch {
+                await route.close({
+                    code: 1008,
+                    reason: "WebSocket destination is outside this browser authority",
+                });
+            }
         });
     }
     refreshPages() {
@@ -562,6 +669,7 @@ export class AgentBrowser {
             if (state.page.isClosed()) {
                 this.states.delete(state.id);
                 this.pageStates.delete(state.page);
+                this.requestPolicyDenials.delete(state.id);
             }
         }
         for (const page of this.context.pages()) {
@@ -581,24 +689,28 @@ export class AgentBrowser {
             id: `tab_${this.nextTabNumber++}`,
             page,
             revision: 0,
-            snapshotId: null,
-            refs: new Map(),
+            navigationEpoch: 0,
+            snapshots: new Map(),
             response: null,
             responseDocumentUrl: null,
             responseCapture: Promise.resolve(),
             responseSequence: 0,
         };
+        this.watchPageEvents(state);
         this.pageStates.set(page, state);
         this.states.set(state.id, state);
         this.activeTabId = state.id;
-        this.watchMainDocumentResponses(state);
         return state;
     }
-    watchMainDocumentResponses(state) {
+    watchPageEvents(state) {
         if (typeof state.page.on !== "function"
             || typeof state.page.mainFrame !== "function") {
-            return;
+            throw new BrowserError("invalid_options", "Browser runtime must support page frame-navigation events and main-frame identity.");
         }
+        state.page.on("framenavigated", () => {
+            state.navigationEpoch += 1;
+            this.invalidate(state);
+        });
         state.page.on("response", (response) => {
             try {
                 const request = response.request();
@@ -717,17 +829,34 @@ export class AgentBrowser {
     }
     invalidate(state) {
         state.revision += 1;
-        state.snapshotId = null;
-        state.refs.clear();
+        state.snapshots.clear();
+    }
+    rememberSnapshot(state, snapshotId, refs, navigationEpoch) {
+        state.snapshots.set(snapshotId, { navigationEpoch, refs });
+        while (state.snapshots.size > MAX_RETAINED_SNAPSHOTS_PER_TAB) {
+            const oldest = state.snapshots.keys().next().value;
+            if (oldest === undefined)
+                break;
+            state.snapshots.delete(oldest);
+        }
     }
-    async resolveRef(state, ref, snapshotId, requireEnabled) {
+    assertObservationCurrent(state, revision, navigationEpoch) {
+        this.assertOpen();
+        if (state.revision !== revision
+            || state.navigationEpoch !== navigationEpoch) {
+            throw new BrowserError("action_failed", "The page navigated while it was being observed; observe the tab again.");
+        }
+    }
+    async resolveRef(state, ref, snapshotId, requireEnabled, requireCurrentViewport) {
         if (!snapshotId) {
             throw new BrowserError("snapshot_required", "A snapshotId is required for every ref-targeted operation.");
         }
-        if (state.snapshotId !== snapshotId) {
+        const snapshot = state.snapshots.get(snapshotId);
+        if (!snapshot
+            || snapshot.navigationEpoch !== state.navigationEpoch) {
             throw new BrowserError("stale_snapshot", "The snapshot is stale; observe the tab again before acting.");
         }
-        const nativeRef = state.refs.get(ref);
+        const nativeRef = snapshot.refs.get(ref);
         if (!nativeRef) {
             throw new BrowserError("ref_not_found", "The ref does not belong to this snapshot.");
         }
@@ -742,16 +871,168 @@ export class AgentBrowser {
         if (!(await locator.isVisible())) {
             throw new BrowserError("ref_hidden", "The snapshot ref is no longer visible.");
         }
+        if (requireCurrentViewport
+            && !intersectsViewport(await locator.boundingBox(), state.page.viewportSize() ?? this.options.viewport)) {
+            throw new BrowserError("stale_snapshot", "The snapshot ref moved outside the current viewport; observe the tab again before acting.");
+        }
         if (requireEnabled && !(await locator.isEnabled())) {
             throw new BrowserError("ref_disabled", "The snapshot ref is disabled.");
         }
-        return { state, locator };
+        const resolved = { state, locator, snapshotId, snapshot };
+        this.assertResolvedRefCurrent(resolved);
+        return resolved;
+    }
+    assertResolvedRefCurrent(resolved) {
+        this.assertOpen();
+        if (resolved.state.navigationEpoch !== resolved.snapshot.navigationEpoch
+            || resolved.state.snapshots.get(resolved.snapshotId) !== resolved.snapshot) {
+            throw new BrowserError("stale_snapshot", "The snapshot is stale; observe the tab again before acting.");
+        }
+    }
+    /**
+     * Playwright's wheel dispatch and a page's own smooth scrolling can outlive
+     * the action promise. Sample top-level viewport geometry before issuing refs
+     * so the observation is less likely to describe an in-flight window scroll.
+     * This is deliberately best-effort: a probe failure must not turn an already
+     * executed action into a reported action failure.
+     */
+    async awaitWindowViewportSettled(page) {
+        try {
+            const documentElement = page.locator("html");
+            const deadline = performance.now() + VIEWPORT_SETTLE_MAX_MS;
+            const remainingTimeout = () => {
+                const remaining = deadline - performance.now();
+                return remaining > 0 ? Math.max(1, Math.ceil(remaining)) : null;
+            };
+            const initialTimeout = remainingTimeout();
+            if (initialTimeout === null)
+                return;
+            let previous = await documentElement.boundingBox({
+                timeout: initialTimeout,
+            });
+            if (!previous)
+                return;
+            let stableIntervals = 0;
+            while (true) {
+                const remainingBeforeWait = deadline - performance.now();
+                if (remainingBeforeWait <= 0)
+                    return;
+                await page.waitForTimeout(Math.min(VIEWPORT_SETTLE_INTERVAL_MS, remainingBeforeWait));
+                const probeTimeout = remainingTimeout();
+                if (probeTimeout === null)
+                    return;
+                const current = await documentElement.boundingBox({
+                    timeout: probeTimeout,
+                });
+                if (!current)
+                    return;
+                if (Math.abs(current.x - previous.x) <= VIEWPORT_SETTLE_TOLERANCE_PX
+                    && Math.abs(current.y - previous.y) <= VIEWPORT_SETTLE_TOLERANCE_PX) {
+                    stableIntervals += 1;
+                    if (stableIntervals >= VIEWPORT_SETTLE_STABLE_INTERVALS)
+                        return;
+                }
+                else {
+                    stableIntervals = 0;
+                }
+                previous = current;
+            }
+        }
+        catch {
+            // Observation remains available when a custom runtime cannot expose
+            // stable document geometry or the page changes during this probe.
+        }
+    }
+    recordMainFrameRequestPolicyDenial(request, error) {
+        try {
+            if (!request.isNavigationRequest())
+                return;
+        }
+        catch {
+            return;
+        }
+        // A popup's initial navigation can be routed before Playwright has created
+        // a Frame object or exposed the Page through context.pages(). Such a
+        // request is still a navigation request. Keep only this genuinely
+        // unframed race session-ambiguous so a concurrent action can surface
+        // uncertainty without guessing which tab created it.
+        let frame;
+        try {
+            frame = request.frame();
+        }
+        catch {
+            this.recordRequestPolicyDenial(error, null);
+            return;
+        }
+        // A denied subframe navigation is real policy enforcement, but it is not
+        // the result of the top-level action. Recording it against the tab would
+        // falsely turn a successful click into a failed action.
+        try {
+            if (frame.parentFrame() !== null)
+                return;
+        }
+        catch {
+            // A runtime that cannot classify a returned frame has crossed the same
+            // attribution boundary as an unregistered popup.
+            this.recordRequestPolicyDenial(error, null);
+            return;
+        }
+        try {
+            this.refreshPages();
+        }
+        catch {
+            // The policy decision must still be surfaced and the route aborted even
+            // if a custom runtime cannot enumerate/register the new page in time.
+            this.recordRequestPolicyDenial(error, null);
+            return;
+        }
+        for (const state of this.states.values()) {
+            try {
+                if (state.page.mainFrame() === frame) {
+                    this.recordRequestPolicyDenial(error, state.id);
+                    return;
+                }
+            }
+            catch {
+                // A custom runtime may not expose a stable frame identity.
+            }
+        }
+        // A navigation request can race page registration (notably for popups).
+        // Preserve the policy denial at session scope and report an uncertain
+        // action outcome rather than inventing an attribution.
+        this.recordRequestPolicyDenial(error, null);
+    }
+    recordRequestPolicyDenial(error, tabId) {
+        this.requestPolicyDenialSequence += 1;
+        this.requestPolicyDenials.set(tabId, {
+            sequence: this.requestPolicyDenialSequence,
+            error: tabId === null
+                ? new BrowserError("action_failed", "A navigation request was policy-blocked while an action was pending, but its tab could not be attributed; the current action outcome is uncertain.", { cause: error })
+                : error,
+            tabId,
+        });
+    }
+    requestPolicyDenialAfter(sequence, tabId) {
+        const scoped = this.requestPolicyDenials.get(tabId);
+        const ambiguous = this.requestPolicyDenials.get(null);
+        let latest = null;
+        for (const denial of [scoped, ambiguous]) {
+            if (denial
+                && denial.sequence > sequence
+                && (!latest || denial.sequence > latest.sequence)) {
+                latest = denial;
+            }
+        }
+        return latest?.error ?? null;
     }
     async newTab(url) {
         const destination = url ? await this.policy.assertAllowed(url) : null;
+        this.assertOpen();
         const page = await this.context.newPage();
+        this.assertOpen();
         const state = this.registerPage(page);
         if (destination) {
+            const denialSequence = this.requestPolicyDenialSequence;
             try {
                 this.clearMainDocumentResponse(state);
                 const response = await page.goto(destination.href, {
@@ -759,9 +1040,15 @@ export class AgentBrowser {
                     timeout: this.options.navigationTimeoutMs,
                 });
                 this.queueMainDocumentResponse(state, response);
+                const denial = this.requestPolicyDenialAfter(denialSequence, state.id);
+                if (denial)
+                    throw denial;
             }
             catch (error) {
                 this.invalidate(state);
+                const denial = this.requestPolicyDenialAfter(denialSequence, state.id);
+                if (denial)
+                    throw denial;
                 throw asBrowserError(error, "action_failed", "New-tab navigation was attempted once and did not complete.");
             }
             this.invalidate(state);
@@ -780,6 +1067,7 @@ export class AgentBrowser {
         }
         this.states.delete(state.id);
         this.pageStates.delete(state.page);
+        this.requestPolicyDenials.delete(state.id);
         this.refreshPages();
         return {
             ok: true,
@@ -817,6 +1105,9 @@ export class AgentBrowser {
         }
     }
     withLock(operation) {
+        if (this.closed) {
+            return Promise.reject(new BrowserError("browser_closed", "Browser session is closed."));
+        }
         const previous = this.operationTail;
         let release;
         this.operationTail = new Promise((resolveTurn) => {
@@ -919,16 +1210,31 @@ function authorityContainsUserinfo(reference) {
     const authority = authorityEnd < 0 ? remainder : remainder.slice(0, authorityEnd);
     return authority.includes("@");
 }
+function captureBrowserAction(action) {
+    const captured = {
+        ...action,
+    };
+    if (Array.isArray(captured.values)) {
+        captured.values = Object.freeze([...captured.values]);
+    }
+    return Object.freeze(captured);
+}
 async function loadDefaultRuntime() {
     const playwright = await import("playwright-core");
     return playwright.chromium;
 }
+async function closeRuntime(browser, context) {
+    // An ephemeral session owns the Browser process, and Browser.close() closes
+    // its contexts while also terminating a child that a stuck Context.close()
+    // could otherwise orphan. A persistent launch returns only its context.
+    if (browser) {
+        await browser.close();
+        return;
+    }
+    await context?.close();
+}
 function normalizeOptions(options) {
-    for (const [name, value] of [
-        ["headless", options.headless],
-        ["allowPublicWeb", options.allowPublicWeb],
-        ["allowLocalNetwork", options.allowLocalNetwork],
-    ]) {
+    for (const [name, value] of [["headless", options.headless]]) {
         if (value !== undefined && typeof value !== "boolean") {
             throw new BrowserError("invalid_options", `${name} must be a boolean.`);
         }
@@ -995,10 +1301,19 @@ function normalizeOptions(options) {
     if (profile.mode === "persistent") {
         validateDedicatedProfileDirectory(profile.directory, outputDir);
     }
+    const capabilities = resolveBrowserCapabilities({
+        ...(options.authority ? { authority: options.authority } : {}),
+        ...(options.allowPublicWeb !== undefined
+            ? { allowPublicWeb: options.allowPublicWeb }
+            : {}),
+        ...(options.allowLocalNetwork !== undefined
+            ? { allowLocalNetwork: options.allowLocalNetwork }
+            : {}),
+        profileMode: profile.mode,
+    });
     return {
         headless: options.headless ?? true,
-        allowPublicWeb: options.allowPublicWeb ?? true,
-        allowLocalNetwork: options.allowLocalNetwork ?? false,
+        capabilities,
         profile,
         ...(channel ? { channel } : {}),
         ...(executablePath ? { executablePath } : {}),