@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/browser-session.js

@@ -0,0 +1,649 @@
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { observePage, observationResult } from './browser-observation.js';
+const sessions = new Map();
+export const IMAGE_LIMIT = 512 * 1024;
+export const PENDING_IMAGE_LIMIT = 10;
+const BATCH_IMAGE_LIMIT = 10;
+const BATCH_IMAGE_BYTES = 2 * 1024 * 1024;
+const KEY_RELEASE_GRACE_MS = 250;
+const TAB_LIMIT = 12;
+const imageBudgets = new WeakMap();
+/** Browser tools whose arguments and outputs are projected before anything persists them. */
+export function isBrowserToolName(name) {
+    return name === 'qa.browser_session' || name === 'browser.panel';
+}
+const OPERATIONS = ['open', 'snapshot', 'click', 'fill', 'press', 'hold', 'move', 'scroll', 'wait', 'screenshot', 'close', 'tabs', 'new_tab', 'select_tab', 'close_tab', 'navigate', 'back', 'forward', 'refresh', 'elements'];
+/** Track only pages in this session's isolated browser context, including link popups. */
+function trackTab(session, page) {
+    for (const [id, existing] of session.tabs)
+        if (existing === page)
+            return id;
+    const id = randomUUID();
+    session.tabs.set(id, page);
+    page.setDefaultTimeout(10_000);
+    const record = (error) => { session.errors.push(error.slice(0, 400)); if (session.errors.length > 20)
+        session.errors.shift(); };
+    page.on('pageerror', (error) => record(error.message));
+    page.on('console', (message) => { if (message.type() === 'error')
+        record(message.text()); });
+    page.on('dialog', (dialog) => { void dialog.dismiss().catch(() => { }); });
+    page.on('close', () => {
+        session.tabs.delete(id);
+        if (session.tabId === id) {
+            const next = session.tabs.entries().next().value;
+            if (next)
+                [session.tabId, session.page] = next;
+            else
+                void close(session);
+        }
+    });
+    return id;
+}
+async function tabList(session, signal) {
+    const tabs = await boundedTransport(session, signal, Promise.all([...session.tabs].map(async ([tabId, page]) => ({
+        tabId, active: tabId === session.tabId, url: page.url().slice(0, 2048), title: (await page.title()).slice(0, 300),
+    }))), 'Browser tabs exceeded the 10-second observation timeout; session closed.');
+    let result = JSON.stringify({ sessionId: session.id, tabs });
+    // Titles and URLs are untrusted Unicode; bound encoded bytes, not characters.
+    while (Buffer.byteLength(result, 'utf8') > 20 * 1024) {
+        for (const tab of tabs) {
+            tab.url = tab.url.slice(0, Math.floor(tab.url.length / 2));
+            tab.title = tab.title.slice(0, Math.floor(tab.title.length / 2));
+        }
+        result = JSON.stringify({ sessionId: session.id, tabs });
+    }
+    return result;
+}
+function owner(context) {
+    return context.browserSessionOwner ?? (context.toolState ??= { fileReads: new Map() });
+}
+function text(args, name, max = 2048) {
+    const value = args[name];
+    if (typeof value !== 'string' || !value || value.length > max)
+        throw new Error(`${name} must be a nonempty string of at most ${max} characters`);
+    return value;
+}
+const inViewport = (args) => Number.isSafeInteger(args.x) && Number.isSafeInteger(args.y) && args.x >= 0 && args.x <= 1279 && args.y >= 0 && args.y <= 799;
+const holdDuration = (args) => Number.isSafeInteger(args.durationMs) && args.durationMs >= 50 && args.durationMs <= 5000;
+function webUrl(value) {
+    const url = new URL(value);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password)
+        throw new Error('Use an HTTP(S) URL without embedded credentials');
+    return url.href;
+}
+/** Project telemetry before any event consumer can persist a browser input. */
+export function browserEventArguments(args) {
+    function project(value, depth = 0, jsonDepth = 0, literal = false) {
+        if (depth >= 64)
+            return '[REDACTED: browser arguments exceed sanitization limit]';
+        if (typeof value === 'string') {
+            // Invalid calls are published before schema validation. Inspect nested
+            // containers and encoded JSON too, without mutating the live arguments.
+            const first = value.trimStart()[0];
+            if (depth === 0 || first === '{' || first === '[' || first === '"') {
+                if (jsonDepth >= 8 || value.length > 8 * 1024 * 1024)
+                    return '[REDACTED: browser arguments exceed sanitization limit]';
+                try {
+                    return JSON.stringify(project(JSON.parse(value), depth + 1, jsonDepth + 1));
+                }
+                catch {
+                    return literal ? value : '[REDACTED: invalid browser arguments]';
+                }
+            }
+            return value;
+        }
+        if (Array.isArray(value))
+            return value.map(entry => project(entry, depth + 1, jsonDepth));
+        if (value && typeof value === 'object') {
+            return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, key === 'value' ? '[REDACTED]'
+                    // Valid encoded JSON is still inspected, but ordinary schema strings
+                    // such as CSS attribute selectors need not be valid JSON.
+                    : project(entry, depth + 1, jsonDepth, ['operation', 'sessionId', 'selector', 'url', 'key'].includes(key))]));
+        }
+        return value;
+    }
+    return project(args);
+}
+function detachBrowserClose(browser) {
+    // Playwright transport shutdown is not reliably abortable. Own the rejection,
+    // but never let a stalled close hold an invocation or its final budget cleanup.
+    void Promise.resolve().then(() => browser.close()).catch(() => { });
+    return Promise.resolve();
+}
+/** Serialize notifications per browser so a cancellation cannot overtake open. */
+async function publishLifecycle(session, type) {
+    if (!session.notify)
+        return;
+    session.lifecycle = session.lifecycle.then(async () => {
+        try {
+            await session.notify?.(type, { browserId: session.id });
+        }
+        catch { /* Browser telemetry must not prevent teardown or tool execution. */ }
+    });
+    await session.lifecycle;
+}
+async function close(session) {
+    if (session.closing)
+        return await session.closing;
+    session.closing = (async () => {
+        session.screenshots.clear();
+        // Do not await an unbounded Playwright transport shutdown.
+        await detachBrowserClose(session.browser);
+        if (session.announced)
+            await publishLifecycle(session, 'browser.headless.closed');
+        // Keep a closing session in the owner registry until its close event
+        // settles, so run teardown also awaits cancellations already underway.
+        sessions.delete(session.id);
+    })();
+    await session.closing;
+}
+export async function disposeBrowserSessions(identity) {
+    if (!identity)
+        return;
+    imageBudgets.delete(identity);
+    await Promise.all([...sessions.values()].filter(session => session.owner === identity).map(close));
+}
+/** Headless isolated profile; never attaches to the user's existing browser. */
+async function launch(signal) {
+    const specifier = 'playwright-core';
+    const { chromium } = await import(specifier);
+    const failures = [];
+    for (const channel of [undefined, 'msedge', 'chrome']) {
+        signal.throwIfAborted();
+        try {
+            const pending = chromium.launch({ headless: true, ...(channel ? { channel } : {}), timeout: 15_000 });
+            return await new Promise((resolve, reject) => {
+                const abort = () => {
+                    signal.removeEventListener('abort', abort);
+                    reject(signal.reason);
+                };
+                signal.addEventListener('abort', abort, { once: true });
+                if (signal.aborted)
+                    abort();
+                // Playwright launch is not abortable. Reject immediately on cancellation,
+                // but retain cleanup ownership of a browser that finishes launching later.
+                pending.then(browser => {
+                    signal.removeEventListener('abort', abort);
+                    if (signal.aborted) {
+                        void detachBrowserClose(browser);
+                        reject(signal.reason);
+                    }
+                    else
+                        resolve(browser);
+                }, error => {
+                    signal.removeEventListener('abort', abort);
+                    reject(error);
+                });
+            });
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            failures.push((error instanceof Error ? error.message : String(error)).split('\n')[0]);
+        }
+    }
+    throw new Error(`Browser unavailable: install Chrome/Edge or the Chromium version required by playwright-core. ${failures.join('; ').slice(0, 1000)}`);
+}
+class BrowserOperationTimeoutError extends Error {
+}
+/** Own late transport settlement without awaiting an unresponsive browser close. */
+async function boundedTransport(session, signal, pending, timeoutMessage) {
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        const cleanup = () => { clearTimeout(timer); signal.removeEventListener('abort', abort); };
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            void close(session);
+            reject(error);
+        };
+        const abort = () => fail(signal.reason);
+        const timer = setTimeout(() => fail(new BrowserOperationTimeoutError(timeoutMessage)), 10_000);
+        signal.addEventListener('abort', abort, { once: true });
+        if (signal.aborted)
+            abort();
+        pending.then(value => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(value);
+        }, error => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error);
+        });
+    });
+}
+async function snapshot(session, signal) {
+    signal.throwIfAborted();
+    // Playwright's default timeout does not apply to evaluate. The renderer can
+    // remain busy indefinitely; reject promptly and retain asynchronous cleanup
+    // ownership without waiting for an equally stalled browser.close().
+    const evaluation = session.page.evaluate(observePage, { sessionId: session.id, tabId: session.tabId, errors: session.errors.slice(-10) });
+    const output = await boundedTransport(session, signal, evaluation, 'Browser snapshot exceeded the 10-second observation timeout; session closed.');
+    return observationResult(output, { sessionId: session.id, tabId: session.tabId });
+}
+/**
+ * Reserve one screenshot against the image budget every browser tool in this
+ * agent tool batch shares. The reservation is a fixed estimate; `commit` trims
+ * it to the real size once known and `refund` returns a reservation whose
+ * capture never produced an image.
+ */
+export function reserveBrowserImage(context) {
+    const identity = owner(context);
+    // Embedders without a batch marker conservatively share one allowance
+    // for this owner until disposal; closing a page is never a reset.
+    const batch = context.browserToolBatch ?? identity;
+    let budget = imageBudgets.get(identity);
+    if (!budget || budget.batch !== batch) {
+        budget = { batch, count: 0, bytes: 0 };
+        imageBudgets.set(identity, budget);
+    }
+    const held = budget;
+    // Reserve before awaiting capture so parallel sessions share the cap.
+    // Claiming an image or closing/reopening a session cannot refund it.
+    if (held.count >= BATCH_IMAGE_LIMIT || held.bytes + IMAGE_LIMIT > BATCH_IMAGE_BYTES)
+        throw new Error('Screenshot batch budget reached (10 images or 2 MiB per agent tool batch); request further screenshots in a later model turn.');
+    held.count++;
+    held.bytes += IMAGE_LIMIT;
+    let settled = false;
+    return {
+        commit: (bytes) => {
+            if (settled)
+                return;
+            settled = true;
+            held.bytes -= IMAGE_LIMIT - bytes;
+        },
+        refund: () => {
+            if (settled)
+                return;
+            settled = true;
+            held.count--;
+            held.bytes -= IMAGE_LIMIT;
+        },
+    };
+}
+export function createBrowserSessionTool(authorize) {
+    return {
+        name: 'qa.browser_session', family: 'browser', capability: 'browser', executionMode: 'sequential',
+        description: 'Persistent isolated headless browser with typed GUI operations. Open returns sessionId; reuse it for tabs/new_tab/select_tab/close_tab/navigate/back/forward/refresh/elements/snapshot/click/fill/press/hold/move/scroll/wait/screenshot/close. Tab operations return opaque tabId values; page operations optionally target tabId, otherwise the selected tab. Click a selector or screenshot-observed viewport coordinates (x/y) with left/right/middle buttons. Wait for a selector to become visible, or pause for durationMs. Hold a key for a bounded duration (always released); move the pointer to screenshot-observed viewport coordinates. Snapshots expose observed CSS selectors and errors. Screenshot returns a native image, not encoded text; each agent tool batch permits at most 10 images and 2 MiB of image bytes across sessions. Prefer this to generating shell or Python browser probes. Browser capability and normal approvals are required; an installed Chrome/Edge or Playwright Chromium is needed.',
+        parameters: { type: 'object', properties: {
+                operation: { type: 'string', enum: OPERATIONS }, sessionId: { type: 'string' },
+                url: { type: 'string', description: 'HTTP(S) target for open/navigate; optional for new_tab (blank by default)' },
+                tabId: { type: 'string', description: 'Observed tab id; required for select_tab/close_tab, optional page target' },
+                button: { type: 'string', enum: ['left', 'right', 'middle'], description: 'Mouse button for click; default left' },
+                selector: { type: 'string', description: 'Observed CSS selector for fill; for click unless x/y is given; for wait unless durationMs is given; optional focus target for press/hold' },
+                value: { type: 'string', description: 'Text for fill' }, key: { type: 'string', description: 'Playwright key name, e.g. Enter or ArrowUp' },
+                durationMs: { type: 'integer', minimum: 50, maximum: 5000, description: 'Required duration for hold (key released automatically); for wait, a fixed pause instead of a selector' },
+                x: { type: 'integer', minimum: 0, maximum: 1279, description: 'Screenshot-observed viewport x for move, or for click instead of a selector' },
+                y: { type: 'integer', minimum: 0, maximum: 799, description: 'Screenshot-observed viewport y for move, or for click instead of a selector' },
+                deltaY: { type: 'integer', minimum: -3000, maximum: 3000 },
+            }, required: ['operation'], additionalProperties: false },
+        eventOutput: output => {
+            try {
+                const data = JSON.parse(output);
+                return JSON.stringify({ sessionId: data.sessionId, screenshotId: data.screenshotId, closed: data.closed });
+            }
+            catch {
+                return 'Browser observation (content omitted)';
+            }
+        },
+        resultImages: output => {
+            try {
+                const pending = sessions.get(JSON.parse(output).sessionId)?.screenshots;
+                const image = pending?.get(output);
+                pending?.delete(output);
+                return image ? [image] : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        execute: async (args, context) => {
+            const operation = text(args, 'operation', 20);
+            if (!OPERATIONS.includes(operation) || Object.keys(args).some(key => !['operation', 'sessionId', 'url', 'selector', 'value', 'key', 'durationMs', 'x', 'y', 'deltaY', 'tabId', 'button'].includes(key)))
+                throw new Error('Invalid browser operation or argument');
+            const identity = owner(context);
+            // Validate before launching or asking for approval.
+            const url = ['open', 'navigate'].includes(operation) || (operation === 'new_tab' && args.url !== undefined) ? webUrl(text(args, 'url')) : undefined;
+            if (args.button !== undefined && (operation !== 'click' || !['left', 'right', 'middle'].includes(args.button)))
+                throw new Error('button must be left, right or middle for click');
+            if (args.tabId !== undefined)
+                text(args, 'tabId', 64);
+            if (['select_tab', 'close_tab'].includes(operation))
+                text(args, 'tabId', 64);
+            // Click targets a selector or screenshot coordinates, and wait targets a
+            // selector or a duration; naming the alternatives lets a model recover.
+            const pointClick = operation === 'click' && args.selector === undefined && (args.x !== undefined || args.y !== undefined);
+            const timedWait = operation === 'wait' && args.selector === undefined && args.durationMs !== undefined;
+            if (operation === 'click' && args.selector !== undefined && (args.x !== undefined || args.y !== undefined))
+                throw new Error('click takes either a selector or x/y coordinates, not both');
+            if (operation === 'wait' && args.selector !== undefined && args.durationMs !== undefined)
+                throw new Error('wait takes either a selector or durationMs, not both');
+            if (operation === 'click' && args.selector === undefined && !pointClick)
+                throw new Error('click requires a selector or observed viewport coordinates x=0..1279, y=0..799');
+            if (operation === 'wait' && args.selector === undefined && !timedWait)
+                throw new Error('wait requires a selector or integer durationMs between 50 and 5000');
+            const selector = ['click', 'fill', 'wait'].includes(operation) && !pointClick && !timedWait || args.selector !== undefined ? text(args, 'selector', 1024) : undefined;
+            if (operation === 'fill' && (typeof args.value !== 'string' || args.value.length > 16000))
+                throw new Error('fill requires a string value of at most 16000 characters');
+            if (operation === 'press' || operation === 'hold')
+                text(args, 'key', 80);
+            if ((operation === 'hold' || timedWait) && !holdDuration(args))
+                throw new Error(`${operation} requires integer durationMs between 50 and 5000`);
+            if ((operation === 'move' || pointClick) && !inViewport(args))
+                throw new Error(`${operation} requires observed viewport coordinates x=0..1279, y=0..799`);
+            if (operation === 'scroll' && (!Number.isSafeInteger(args.deltaY) || Math.abs(args.deltaY) > 3000))
+                throw new Error('scroll requires integer deltaY between -3000 and 3000');
+            let session = operation === 'open' ? undefined : sessions.get(text(args, 'sessionId', 64));
+            if (operation !== 'open' && (!session || session.closing || session.owner !== identity))
+                throw new Error('Unknown browser session for this agent; open a page first');
+            if (session && args.tabId !== undefined && !session.tabs.has(args.tabId))
+                throw new Error('Unknown tab for this browser session');
+            await authorize('qa.browser_session', browserEventArguments(args), context);
+            context.signal.throwIfAborted();
+            if (!session) {
+                if ([...sessions.values()].filter(item => item.owner === identity).length >= 3)
+                    throw new Error('Close an existing browser session before opening another (maximum 3)');
+                const browser = await launch(context.signal);
+                let closing;
+                const closeBrowser = () => closing ??= detachBrowserClose(browser);
+                try {
+                    context.signal.throwIfAborted();
+                    // Browser.newPage owns a single-page context which rejects new tabs.
+                    // An explicit context keeps every tab in this isolated session profile.
+                    const pending = browser.newContext({ viewport: { width: 1280, height: 800 }, acceptDownloads: false }).then((isolated) => {
+                        if (closing || context.signal.aborted) {
+                            void Promise.resolve().then(() => isolated.close()).catch(() => { });
+                            throw new Error('Browser closed while creating context');
+                        }
+                        return isolated.newPage();
+                    });
+                    const page = await new Promise((resolve, reject) => {
+                        let settled = false;
+                        const cleanup = () => { clearTimeout(timer); context.signal.removeEventListener('abort', abort); };
+                        const fail = (error) => {
+                            if (settled)
+                                return;
+                            settled = true;
+                            cleanup();
+                            void closeBrowser();
+                            reject(error);
+                        };
+                        const abort = () => fail(context.signal.reason);
+                        const timer = setTimeout(() => fail(new BrowserOperationTimeoutError('Browser page creation exceeded the 10-second timeout; browser closed. Open a new session before retrying.')), 10_000);
+                        context.signal.addEventListener('abort', abort, { once: true });
+                        if (context.signal.aborted)
+                            abort();
+                        pending.then(page => {
+                            if (settled) {
+                                // A deadline need not abort the invocation signal. Retain cleanup
+                                // ownership of late pages without registering or operating them.
+                                void Promise.resolve().then(() => page.close()).catch(() => { });
+                                void closeBrowser();
+                                return;
+                            }
+                            settled = true;
+                            cleanup();
+                            resolve(page);
+                        }, error => {
+                            // Own late rejection even after the deadline/cancellation won.
+                            fail(error);
+                        });
+                    });
+                    context.signal.throwIfAborted();
+                    page.setDefaultTimeout(10_000);
+                    session = { id: randomUUID(), owner: identity, browser, page, tabs: new Map(), tabId: '', errors: [], pending: Promise.resolve(), screenshots: new Map(), announced: false, lifecycle: Promise.resolve(), notify: context.sessionScope ? context.onBrowserEvent : undefined };
+                    session.tabId = trackTab(session, page);
+                    page.context?.().on('page', (newPage) => {
+                        if (session.tabs.size >= TAB_LIMIT || session.closing) {
+                            void newPage.close().catch(() => { });
+                            return;
+                        }
+                        trackTab(session, newPage);
+                    });
+                    sessions.set(session.id, session);
+                }
+                catch (error) {
+                    // Cleanup owns late resources but must not delay cancellation while
+                    // Playwright is still stuck creating the page or closing its browser.
+                    if (context.signal.aborted)
+                        void closeBrowser();
+                    else
+                        await closeBrowser();
+                    throw error;
+                }
+            }
+            const current = session;
+            const run = current.pending.then(async () => {
+                context.signal.throwIfAborted();
+                let releasingHeldKey = false;
+                let keyReleaseFailed = false;
+                const abort = () => { if (!releasingHeldKey)
+                    void close(current); };
+                context.signal.addEventListener('abort', abort, { once: true });
+                try {
+                    if (current.closing || sessions.get(current.id) !== current)
+                        throw new Error('Browser session closed. Open a new session before retrying.');
+                    if (args.tabId !== undefined && operation !== 'close_tab') {
+                        const target = current.tabs.get(args.tabId);
+                        if (!target)
+                            throw new Error('Unknown tab for this browser session');
+                        current.tabId = args.tabId;
+                        current.page = target;
+                    }
+                    if (operation === 'tabs')
+                        return await tabList(current, context.signal);
+                    if (operation === 'new_tab') {
+                        if (current.tabs.size >= TAB_LIMIT)
+                            throw new Error('Close a tab before opening another (maximum 12)');
+                        const pending = current.page.context().newPage();
+                        // Own pages arriving after cancellation/deadline even if browser.close stalls.
+                        const guarded = pending.then(page => {
+                            if (current.closing || context.signal.aborted) {
+                                void Promise.resolve().then(() => page.close()).catch(() => { });
+                                throw new Error('Browser closed while creating tab');
+                            }
+                            return page;
+                        });
+                        const page = await boundedTransport(current, context.signal, guarded, 'Browser tab creation exceeded the 10-second timeout; session closed.');
+                        if (page.isClosed())
+                            throw new Error('Browser tab closed while opening; list tabs before retrying.');
+                        if (![...current.tabs.values()].includes(page) && current.tabs.size >= TAB_LIMIT) {
+                            void page.close().catch(() => { });
+                            throw new Error('Close a tab before opening another (maximum 12)');
+                        }
+                        current.tabId = trackTab(current, page);
+                        current.page = page;
+                        await page.goto(url ?? 'about:blank', { waitUntil: 'domcontentloaded', timeout: 30_000 });
+                    }
+                    if (operation === 'close_tab') {
+                        const closingId = args.tabId;
+                        const closingPage = current.tabs.get(closingId);
+                        if (!closingPage)
+                            throw new Error('Unknown tab for this browser session');
+                        await boundedTransport(current, context.signal, closingPage.close(), 'Browser tab close exceeded the 10-second timeout; session closed.');
+                        current.tabs.delete(closingId);
+                        if (!current.tabs.size) {
+                            await close(current);
+                            return JSON.stringify({ sessionId: current.id, tabId: closingId, closed: true });
+                        }
+                        if (current.tabId === closingId)
+                            [current.tabId, current.page] = current.tabs.entries().next().value;
+                        return await tabList(current, context.signal);
+                    }
+                    if (operation === 'navigate')
+                        await current.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
+                    if (operation === 'back')
+                        await current.page.goBack({ waitUntil: 'domcontentloaded', timeout: 30_000 });
+                    if (operation === 'forward')
+                        await current.page.goForward({ waitUntil: 'domcontentloaded', timeout: 30_000 });
+                    if (operation === 'refresh')
+                        await current.page.reload({ waitUntil: 'domcontentloaded', timeout: 30_000 });
+                    if (operation === 'close') {
+                        await close(current);
+                        return JSON.stringify({ sessionId: current.id, closed: true });
+                    }
+                    if (operation === 'open') {
+                        await current.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
+                        // This is intentionally a *headless* operation. It may expand the
+                        // correct session's browser tool pane, but must never claim the
+                        // displayed CEF surface is attached to this Playwright page.
+                        context.signal.throwIfAborted();
+                        if (current.closing || sessions.get(current.id) !== current)
+                            throw new Error('Browser closed while opening');
+                        current.announced = true;
+                        await publishLifecycle(current, 'browser.headless.opened');
+                    }
+                    if (operation === 'click' && !pointClick)
+                        await current.page.locator(selector).click({ button: args.button ?? 'left' });
+                    if (operation === 'fill')
+                        await current.page.locator(selector).fill(args.value);
+                    const assertInputSession = () => {
+                        context.signal.throwIfAborted();
+                        if (sessions.get(current.id) !== current)
+                            throw new Error('Browser input session closed. Open a new session before retrying.');
+                    };
+                    const rawInput = async (action) => {
+                        assertInputSession();
+                        await boundedTransport(current, context.signal, Promise.resolve().then(() => {
+                            assertInputSession();
+                            return action();
+                        }), `Browser ${operation} exceeded the 10-second input timeout; session closed. Open a new session before retrying.`);
+                    };
+                    if (operation === 'press') {
+                        await rawInput(async () => {
+                            if (selector)
+                                await current.page.locator(selector).focus();
+                            assertInputSession();
+                            await current.page.keyboard.press(args.key);
+                        });
+                    }
+                    if (operation === 'hold') {
+                        // Give responsive transports time to release before closing, but
+                        // bound the complete sequence even when no cancellation arrives.
+                        releasingHeldKey = true;
+                        try {
+                            await new Promise((resolve, reject) => {
+                                let releaseTimer;
+                                let settled = false;
+                                const cleanup = () => {
+                                    clearTimeout(deadlineTimer);
+                                    clearTimeout(releaseTimer);
+                                    context.signal.removeEventListener('abort', abortHold);
+                                };
+                                const fail = (error) => {
+                                    if (settled)
+                                        return;
+                                    settled = true;
+                                    cleanup();
+                                    void close(current);
+                                    reject(error);
+                                };
+                                const abortHold = () => {
+                                    releaseTimer ??= setTimeout(() => fail(context.signal.reason), KEY_RELEASE_GRACE_MS);
+                                };
+                                const deadlineTimer = setTimeout(() => fail(new BrowserOperationTimeoutError('Browser hold exceeded the 10-second input timeout; session closed. Open a new session before retrying.')), 10_000);
+                                context.signal.addEventListener('abort', abortHold, { once: true });
+                                const holding = (async () => {
+                                    if (selector)
+                                        await current.page.locator(selector).focus();
+                                    assertInputSession();
+                                    try {
+                                        await current.page.keyboard.down(args.key);
+                                        assertInputSession();
+                                        await delay(args.durationMs, undefined, { signal: context.signal });
+                                    }
+                                    finally {
+                                        try {
+                                            await current.page.keyboard.up(args.key);
+                                        }
+                                        catch (error) {
+                                            if (!current.page.isClosed()) {
+                                                keyReleaseFailed = true;
+                                                throw error;
+                                            }
+                                        }
+                                    }
+                                })();
+                                // Own late settlement after either deadline expires, including a
+                                // transport rejection that arrives after detached browser close.
+                                holding.then(() => {
+                                    if (settled)
+                                        return;
+                                    settled = true;
+                                    cleanup();
+                                    resolve();
+                                }, error => {
+                                    if (settled)
+                                        return;
+                                    settled = true;
+                                    cleanup();
+                                    reject(error);
+                                });
+                            });
+                        }
+                        finally {
+                            releasingHeldKey = false;
+                        }
+                    }
+                    if (operation === 'move')
+                        await rawInput(() => current.page.mouse.move(args.x, args.y));
+                    if (pointClick)
+                        await rawInput(() => current.page.mouse.click(args.x, args.y, { button: args.button ?? 'left' }));
+                    if (operation === 'scroll')
+                        await rawInput(() => current.page.mouse.wheel(0, args.deltaY));
+                    if (timedWait)
+                        await delay(args.durationMs, undefined, { signal: context.signal });
+                    else if (operation === 'wait')
+                        await current.page.locator(selector).waitFor({ state: 'visible' });
+                    context.signal.throwIfAborted();
+                    if (operation === 'screenshot') {
+                        // An agent must consume its own pending observations. Never silently
+                        // evict another invocation's successful result to make room.
+                        if (current.screenshots.size >= PENDING_IMAGE_LIMIT)
+                            throw new Error('Consume pending screenshots before capturing another (maximum 10 per session)');
+                        const reservation = reserveBrowserImage(context);
+                        let committed = false;
+                        try {
+                            const data = await current.page.screenshot({ type: 'jpeg', quality: 60, timeout: 10_000 });
+                            context.signal.throwIfAborted();
+                            if (data.length > IMAGE_LIMIT)
+                                throw new Error('Screenshot exceeds the 512 KiB visual observation limit');
+                            const screenshotId = randomUUID();
+                            const output = JSON.stringify({ sessionId: current.id, tabId: current.tabId, screenshotId, bytes: data.length, width: 1280, height: 800 });
+                            current.screenshots.set(output, { mimeType: 'image/jpeg', data: data.toString('base64') });
+                            reservation.commit(data.length);
+                            committed = true;
+                            return output;
+                        }
+                        finally {
+                            if (!committed)
+                                reservation.refund();
+                        }
+                    }
+                    return await snapshot(current, context.signal);
+                }
+                catch (error) {
+                    if (context.signal.aborted || error instanceof BrowserOperationTimeoutError)
+                        void close(current);
+                    else if (operation === 'open')
+                        await close(current);
+                    if (!keyReleaseFailed)
+                        context.signal.throwIfAborted();
+                    throw error;
+                }
+                finally {
+                    context.signal.removeEventListener('abort', abort);
+                }
+            });
+            current.pending = run.catch(() => { });
+            return await run;
+        },
+    };
+}