@anweat/dsh-browser 0.1.13-alpha.1 → 0.1.14-alpha.2

package/lib/browser-service.js

@@ -30,66 +30,66 @@ import { configuredBrowserTools } from "./freedom.js";
 import { filterOpencliCatalog, parseOpencliCatalog } from "./opencli-catalog.js";
 import { UsageGovernor } from "./usage-policy.js";
 /** Rules-aware content extractor (runs in the page). */
-const EXTRACTOR_FN = `(ruleList) => {
-  const doc = document
-  const title = doc.title ? doc.title.trim() : ''
-  let host = ''
-  try { host = location.hostname } catch (e) {}
-  const norm = (h) => { const x = h.toLowerCase(); return x.startsWith('www.') ? x.slice(4) : x }
-  let rule = null
-  for (const r of ruleList) {
-    const rh = norm(r.hostname)
-    if (host === rh || host.endsWith('.' + rh)) rule = r
-  }
-  const pick = (selectors) => {
-    for (const sel of selectors) {
-      try {
-        const el = doc.querySelector(sel)
-        if (el && (el.textContent || '').trim().length > 40) return el
-      } catch (e) {}
-    }
-    return null
-  }
-  const content = rule ? pick(rule.contentSelectors) : (pick(['article', 'main', '[role="main"]']) || doc.body)
-  if (content && rule && rule.removeSelectors) {
-    for (const sel of rule.removeSelectors) {
-      try { content.querySelectorAll(sel).forEach((el) => el.remove()) } catch (e) {}
-    }
-  }
-  const text = content ? (content.innerText || content.textContent || '') : ''
-  return { title, text, html: doc.documentElement.outerHTML.slice(0, 2000000), usedRule: rule ? rule.hostname : null }
+const EXTRACTOR_FN = `(ruleList) => {
+  const doc = document
+  const title = doc.title ? doc.title.trim() : ''
+  let host = ''
+  try { host = location.hostname } catch (e) {}
+  const norm = (h) => { const x = h.toLowerCase(); return x.startsWith('www.') ? x.slice(4) : x }
+  let rule = null
+  for (const r of ruleList) {
+    const rh = norm(r.hostname)
+    if (host === rh || host.endsWith('.' + rh)) rule = r
+  }
+  const pick = (selectors) => {
+    for (const sel of selectors) {
+      try {
+        const el = doc.querySelector(sel)
+        if (el && (el.textContent || '').trim().length > 40) return el
+      } catch (e) {}
+    }
+    return null
+  }
+  const content = rule ? pick(rule.contentSelectors) : (pick(['article', 'main', '[role="main"]']) || doc.body)
+  if (content && rule && rule.removeSelectors) {
+    for (const sel of rule.removeSelectors) {
+      try { content.querySelectorAll(sel).forEach((el) => el.remove()) } catch (e) {}
+    }
+  }
+  const text = content ? (content.innerText || content.textContent || '') : ''
+  return { title, text, html: doc.documentElement.outerHTML.slice(0, 2000000), usedRule: rule ? rule.hostname : null }
 }`;
 /** Platform search-page list extractor (runs in the page). */
-const LIST_EXTRACTOR = `(spec) => {
-  const items = []
-  const nodes = document.querySelectorAll(spec.item)
-  for (let i = 0; i < nodes.length && items.length < 20; i++) {
-    const el = nodes[i]
-    const titleEl = spec.title ? el.querySelector(spec.title) : null
-    const linkEl = spec.link ? el.querySelector(spec.link) : null
-    const textEl = spec.text ? el.querySelector(spec.text) : null
-    const title = (titleEl ? titleEl.textContent : el.textContent || '').trim().replace(/\\s+/g, ' ')
-    let url = linkEl ? (linkEl.href || linkEl.getAttribute('href') || '') : ''
-    if (url && url.startsWith('/')) url = location.origin + url
-    if (!url && linkEl === null && titleEl) { const a = titleEl.closest ? titleEl.closest('a') : null; if (a) url = a.href }
-    const snippet = textEl ? (textEl.textContent || '').trim().replace(/\\s+/g, ' ').slice(0, 300) : ''
-    if (!url || !title || title.length < 2) continue
-    items.push({ url, title, snippet })
-  }
-  return items
+const LIST_EXTRACTOR = `(spec) => {
+  const items = []
+  const nodes = document.querySelectorAll(spec.item)
+  for (let i = 0; i < nodes.length && items.length < 20; i++) {
+    const el = nodes[i]
+    const titleEl = spec.title ? el.querySelector(spec.title) : null
+    const linkEl = spec.link ? el.querySelector(spec.link) : null
+    const textEl = spec.text ? el.querySelector(spec.text) : null
+    const title = (titleEl ? titleEl.textContent : el.textContent || '').trim().replace(/\\s+/g, ' ')
+    let url = linkEl ? (linkEl.href || linkEl.getAttribute('href') || '') : ''
+    if (url && url.startsWith('/')) url = location.origin + url
+    if (!url && linkEl === null && titleEl) { const a = titleEl.closest ? titleEl.closest('a') : null; if (a) url = a.href }
+    const snippet = textEl ? (textEl.textContent || '').trim().replace(/\\s+/g, ' ').slice(0, 300) : ''
+    if (!url || !title || title.length < 2) continue
+    items.push({ url, title, snippet })
+  }
+  return items
 }`;
-const CRAWL_EXTRACTOR = `(maxChars) => {
-  const root = document.querySelector('article, main, [role="main"]') || document.body
-  const text = ((root && (root.innerText || root.textContent)) || '').replace(/\\n{3,}/g, '\\n\\n').trim().slice(0, maxChars)
-  const links = []
-  for (const anchor of document.querySelectorAll('a[href]')) {
-    try {
-      const url = new URL(anchor.href, location.href)
-      if ((url.protocol === 'http:' || url.protocol === 'https:') && !links.includes(url.href)) links.push(url.href)
-      if (links.length >= 500) break
-    } catch (e) {}
-  }
-  return { title: document.title || '', text, links }
+const CRAWL_EXTRACTOR = `(maxChars) => {
+  const root = document.querySelector('article, main, [role="main"]') || document.body
+  const text = ((root && (root.innerText || root.textContent)) || '').replace(/\\n{3,}/g, '\\n\\n').trim().slice(0, maxChars)
+  const links = []
+  for (const anchor of document.querySelectorAll('a[href]')) {
+    try {
+      const url = new URL(anchor.href, location.href)
+      if ((url.protocol === 'http:' || url.protocol === 'https:') && !links.includes(url.href)) links.push(url.href)
+      if (links.length >= 500) break
+    } catch (e) {}
+  }
+  return { title: document.title || '', text, links }
 }`;
 function uid() {
     return crypto.randomUUID();
@@ -117,6 +117,35 @@ function storageStateOptions(statePath, label, allowMissing = false) {
         throw new Error(`dsh-browser: ${label} storageState path is not a file: ${statePath}`);
     return { storageState: statePath };
 }
+function boundedString(value, label, max) {
+    if (!value || value.length > max)
+        throw new Error(`${label} must contain 1 to ${max} characters`);
+    return value;
+}
+function boundedTimeout(value, label) {
+    const resolved = value ?? 15_000;
+    if (!Number.isFinite(resolved) || resolved < 1 || resolved > 30_000)
+        throw new Error(`${label} must be between 1 and 30,000 ms`);
+    return resolved;
+}
+function redactCaptureText(value, max = 2_000) {
+    return value
+        .replace(/\b(authorization|cookie|set-cookie|password|passwd|secret|token|api[-_]?key|session[-_]?id)\b\s*[:=]\s*([^\s,;]+)/gi, '$1=[redacted]')
+        .slice(0, max);
+}
+function redactCaptureUrl(value) {
+    try {
+        const parsed = new URL(value);
+        for (const key of [...parsed.searchParams.keys()]) {
+            if (/token|key|auth|session|cookie|password|secret/i.test(key))
+                parsed.searchParams.set(key, '[redacted]');
+        }
+        return parsed.toString().slice(0, 2_000);
+    }
+    catch {
+        return redactCaptureText(value);
+    }
+}
 export class BrowserService {
     config;
     browser;
@@ -128,6 +157,10 @@ export class BrowserService {
     authProfiles;
     usageGovernor;
     opencliCatalogCache;
+    captureConsoleEnabled = false;
+    captureNetworkEnabled = false;
+    capturedConsole = [];
+    capturedRequests = [];
     constructor(config) {
         this.config = config;
         this.authProfiles = new AuthProfileStore(config.authProfiles);
@@ -140,10 +173,35 @@ export class BrowserService {
         if (!this.config.enabled)
             throw new Error('dsh-browser: browser service is disabled');
     }
+    browserConnected(browser = this.browser) {
+        return !!browser && (typeof browser.isConnected !== 'function' || browser.isConnected());
+    }
+    clearActiveState() {
+        this.activeContext = undefined;
+        this.activePage = undefined;
+        this.activeProfile = undefined;
+        this.activeRulePack = undefined;
+        this.resetCapture();
+    }
+    handleBrowserDisconnected(browser) {
+        // A late event from an older process must not invalidate its replacement.
+        if (this.browser !== browser)
+            return;
+        this.browser = undefined;
+        this.launching = undefined;
+        this.clearActiveState();
+    }
+    trackBrowser(browser) {
+        this.browser = browser;
+        browser.on?.('disconnected', () => this.handleBrowserDisconnected(browser));
+        return browser;
+    }
     async ensure() {
         this.assertEnabled();
-        if (this.browser)
+        if (this.browserConnected())
             return this.browser;
+        if (this.browser)
+            this.handleBrowserDisconnected(this.browser);
         if (!this.launching) {
             this.launching = (async () => {
                 const pw = loadBrowserRuntime(this.config.browserRuntime);
@@ -153,14 +211,14 @@ export class BrowserService {
                 if (this.config.executablePath)
                     launchOptions.executablePath = this.config.executablePath;
                 try {
-                    this.browser = await pw.chromium.launch(launchOptions);
+                    return this.trackBrowser(await pw.chromium.launch(launchOptions));
                 }
                 catch (error) {
                     const msg = String(error);
                     if (/Executable doesn't exist|playwright install|not found/i.test(msg)) {
                         if (this.config.autoInstall) {
                             await this.installChromium();
-                            this.browser = await pw.chromium.launch(launchOptions);
+                            return this.trackBrowser(await pw.chromium.launch(launchOptions));
                         }
                         else {
                             throw new Error('dsh-browser: chromium is not installed for ' + this.config.browserRuntime + '. Run the browser_install tool, or: node "' + browserRuntimeCliPath(this.config.browserRuntime) + '" install chromium');
@@ -170,13 +228,16 @@ export class BrowserService {
                         throw error;
                     }
                 }
-                return this.browser;
-            })().catch((error) => {
+            })();
+        }
+        const launching = this.launching;
+        try {
+            return await launching;
+        }
+        finally {
+            if (this.launching === launching)
                 this.launching = undefined;
-                throw error;
-            });
         }
-        return this.launching;
     }
     /** Run `playwright install chromium` from the bundled playwright CLI. */
     installChromium() {
@@ -203,14 +264,27 @@ export class BrowserService {
         return response;
     }
     async transientContext(url, opts = {}) {
-        const browser = await this.ensure();
         const profileId = opts.anonymous ? undefined : (opts.authProfile ?? this.config.defaultAuthProfile);
         const profile = profileId ? this.authProfiles.resolve(profileId, url) : undefined;
         const rulePack = resolveRulePack(this.config.rulePacks, opts.rulePack, url);
         const stateOptions = profile
             ? storageStateOptions(profile.storageStatePath, `auth profile ${profile.id}`, profile.persistState)
             : (!opts.anonymous ? storageStateOptions(this.config.storageStatePath, 'global') : {});
-        const context = await browser.newContext(stateOptions);
+        let context;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const browser = await this.ensure();
+            try {
+                context = await browser.newContext(stateOptions);
+                break;
+            }
+            catch (error) {
+                if (attempt > 0 || this.browserConnected(browser))
+                    throw error;
+                this.handleBrowserDisconnected(browser);
+            }
+        }
+        if (!context)
+            throw new Error('dsh-browser: browser context could not be created after reconnecting');
         try {
             if (rulePack?.initScriptPath)
                 await context.addInitScript({ path: rulePack.initScriptPath });
@@ -224,7 +298,17 @@ export class BrowserService {
     async persistAndClose(session) {
         try {
             if (session.profile?.persistState) {
-                const state = await session.context.storageState();
+                let state;
+                try {
+                    state = await session.context.storageState();
+                }
+                catch (error) {
+                    // A crashed browser cannot provide state. Filesystem failures below
+                    // still propagate so failed persistence is never reported as success.
+                    if (/target page, context or browser has been closed|browser has been closed|browser disconnected/i.test(String(error)))
+                        return;
+                    throw error;
+                }
                 fs.mkdirSync(path.dirname(session.profile.storageStatePath), { recursive: true });
                 const temporary = session.profile.storageStatePath + '.tmp-' + uid().slice(0, 8);
                 fs.writeFileSync(temporary, JSON.stringify(state, null, 2), { encoding: 'utf8', mode: 0o600 });
@@ -543,6 +627,8 @@ export class BrowserService {
     }
     // ── interactive surface (one persistent context + page) ──────────────────
     async ensureActivePage(targetUrl, opts = {}) {
+        if (this.activePage && (this.activePage.isClosed() || !this.browserConnected()))
+            await this.closePage();
         if (this.activePage && !this.activePage.isClosed()) {
             if (!targetUrl)
                 return this.activePage;
@@ -566,12 +652,150 @@ export class BrowserService {
             this.activeContext = await browser.newContext(storageStateOptions(this.config.storageStatePath, 'global'));
         }
         this.activePage = await this.activeContext.newPage();
+        this.attachCapture(this.activePage);
         return this.activePage;
     }
-    async captureScreenshot(page) {
+    attachCapture(page) {
+        const release = () => {
+            if (this.activePage !== page)
+                return;
+            const context = this.activeContext;
+            const profile = this.activeProfile;
+            this.clearActiveState();
+            if (context)
+                void this.persistAndClose({ context, ...profile ? { profile } : {} }).catch(() => { });
+        };
+        page.on('close', release);
+        page.on('crash', release);
+        page.on('console', (message) => {
+            if (!this.captureConsoleEnabled)
+                return;
+            const location = message.location?.();
+            this.capturedConsole.push({
+                type: String(message.type?.() ?? 'log').slice(0, 40),
+                text: redactCaptureText(String(message.text?.() ?? '')),
+                ...location?.url ? { url: redactCaptureUrl(location.url) } : {},
+                timestamp: new Date().toISOString(),
+            });
+            if (this.capturedConsole.length > 200)
+                this.capturedConsole.splice(0, this.capturedConsole.length - 200);
+        });
+        page.on('response', (response) => {
+            if (!this.captureNetworkEnabled)
+                return;
+            const status = Number(response.status?.() ?? 0);
+            if (status < 400)
+                return;
+            const request = response.request?.();
+            this.capturedRequests.push({
+                method: String(request?.method?.() ?? 'GET').slice(0, 20),
+                url: redactCaptureUrl(String(response.url?.() ?? '')),
+                status,
+                timestamp: new Date().toISOString(),
+            });
+            if (this.capturedRequests.length > 200)
+                this.capturedRequests.splice(0, this.capturedRequests.length - 200);
+        });
+        page.on('requestfailed', (request) => {
+            if (!this.captureNetworkEnabled)
+                return;
+            this.capturedRequests.push({
+                method: String(request.method?.() ?? 'GET').slice(0, 20),
+                url: redactCaptureUrl(String(request.url?.() ?? '')),
+                failure: redactCaptureText(String(request.failure?.()?.errorText ?? 'request failed'), 500),
+                timestamp: new Date().toISOString(),
+            });
+            if (this.capturedRequests.length > 200)
+                this.capturedRequests.splice(0, this.capturedRequests.length - 200);
+        });
+    }
+    resetCapture(capture = []) {
+        this.captureConsoleEnabled = capture.includes('console');
+        this.captureNetworkEnabled = capture.includes('network');
+        this.capturedConsole = [];
+        this.capturedRequests = [];
+    }
+    resolveTarget(page, target) {
+        if (!target || (typeof target !== 'string' && typeof target !== 'object'))
+            throw new Error('browser target must be a selector string or locator object');
+        const spec = typeof target === 'string' ? { selector: target } : target;
+        const modes = [spec.selector, spec.role, spec.text, spec.label].filter(value => value !== undefined);
+        if (modes.length !== 1)
+            throw new Error('browser target requires exactly one of selector, role, text, or label');
+        if (spec.name !== undefined && spec.role === undefined)
+            throw new Error('browser target name is only valid with role');
+        let root = page;
+        if (spec.frame) {
+            const frameModes = [spec.frame.selector, spec.frame.name, spec.frame.url].filter(value => value !== undefined);
+            if (frameModes.length !== 1)
+                throw new Error('browser frame requires exactly one of selector, name, or url');
+            if (spec.frame.selector)
+                root = page.frameLocator(boundedString(spec.frame.selector, 'frame selector', 500));
+            else {
+                const frame = page.frame(spec.frame.name
+                    ? { name: boundedString(spec.frame.name, 'frame name', 500) }
+                    : { url: boundedString(spec.frame.url, 'frame url', 2_000) });
+                if (!frame)
+                    throw new Error('browser target frame was not found');
+                root = frame;
+            }
+        }
+        if (spec.selector)
+            return root.locator(boundedString(spec.selector, 'selector', 500));
+        if (spec.role)
+            return root.getByRole(boundedString(spec.role, 'role', 100), {
+                ...spec.name !== undefined ? { name: boundedString(spec.name, 'role name', 2_000) } : {},
+                exact: spec.exact ?? false,
+            });
+        if (spec.text)
+            return root.getByText(boundedString(spec.text, 'text locator', 2_000), { exact: spec.exact ?? false });
+        return root.getByLabel(boundedString(spec.label, 'label locator', 2_000), { exact: spec.exact ?? false });
+    }
+    screenshotFile(options) {
+        const filename = options.filename ?? `shot-${Date.now()}-${uid().slice(0, 8)}.${options.format === 'jpeg' ? 'jpg' : 'png'}`;
+        if (filename !== path.basename(filename) || !/^[\w.() -]{1,160}$/.test(filename)) {
+            throw new Error('browser_screenshot filename must be a plain file name inside snapshotDir');
+        }
+        const extension = path.extname(filename).toLowerCase();
+        const inferred = extension === '.jpg' || extension === '.jpeg' ? 'jpeg' : extension === '.png' ? 'png' : undefined;
+        const format = options.format ?? inferred ?? 'png';
+        if (inferred && inferred !== format)
+            throw new Error('browser_screenshot filename extension does not match format');
+        if (!inferred)
+            throw new Error('browser_screenshot filename must end in .png, .jpg, or .jpeg');
+        return { file: path.join(this.config.snapshotDir, filename), format };
+    }
+    async captureScreenshot(page, options = {}) {
         fs.mkdirSync(this.config.snapshotDir, { recursive: true });
-        const file = path.join(this.config.snapshotDir, 'shot-' + Date.now() + '-' + uid().slice(0, 8) + '.png');
-        await page.screenshot({ path: file, fullPage: true });
+        if (options.target && options.clip)
+            throw new Error('browser_screenshot cannot combine target and clip');
+        if (options.target && options.fullPage)
+            throw new Error('browser_screenshot cannot combine target and fullPage');
+        if (options.quality !== undefined && (!Number.isInteger(options.quality) || options.quality < 0 || options.quality > 100)) {
+            throw new Error('browser_screenshot quality must be an integer from 0 to 100');
+        }
+        const { file, format } = this.screenshotFile(options);
+        if (format === 'png' && options.quality !== undefined)
+            throw new Error('browser_screenshot quality is only supported for jpeg');
+        const screenshotOptions = {
+            path: file,
+            type: format,
+            ...options.quality !== undefined ? { quality: options.quality } : {},
+        };
+        if (options.clip) {
+            const { x, y, width, height } = options.clip;
+            if (![x, y, width, height].every(Number.isFinite) || x < 0 || y < 0 || width <= 0 || height <= 0 || width > 20_000 || height > 20_000) {
+                throw new Error('browser_screenshot clip must use finite non-negative coordinates and dimensions from 1 to 20,000');
+            }
+            screenshotOptions.clip = options.clip;
+        }
+        else if (!options.target) {
+            screenshotOptions.fullPage = options.fullPage ?? true;
+        }
+        if (options.target)
+            await this.resolveTarget(page, options.target).screenshot(screenshotOptions);
+        else
+            await page.screenshot(screenshotOptions);
         return file;
     }
     async readState(page, includeScreenshot) {
@@ -587,6 +811,7 @@ export class BrowserService {
     }
     async open(url, opts = {}) {
         const page = await this.ensureActivePage(url, opts);
+        this.resetCapture(opts.capture);
         page.setDefaultTimeout(30_000);
         await this.navigate(page, url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
         await page.waitForLoadState('networkidle', { timeout: 8_000 }).catch(() => { });
@@ -595,32 +820,75 @@ export class BrowserService {
             await page.waitForTimeout(opts.waitMs);
         return this.readState(page, true);
     }
-    async click(selector, opts = {}) {
+    async click(target, opts = {}) {
         const page = await this.ensureActivePage();
-        await page.waitForSelector(selector, { timeout: opts.timeoutMs ?? 15_000 });
-        await page.click(selector);
+        await this.resolveTarget(page, target).click({ timeout: boundedTimeout(opts.timeoutMs, 'browser_click timeoutMs') });
         if (opts.waitMs !== undefined)
             await page.waitForTimeout(opts.waitMs);
         else
             await page.waitForTimeout(500);
         return this.readState(page, true);
     }
-    async type(selector, text, opts = {}) {
+    async type(target, text, opts = {}) {
+        const page = await this.ensureActivePage();
+        await this.resolveTarget(page, target).fill(text, { timeout: boundedTimeout(opts.timeoutMs, 'browser_type timeoutMs') });
+        return this.readState(page, false);
+    }
+    async wait(target, opts = {}) {
         const page = await this.ensureActivePage();
-        await page.waitForSelector(selector, { timeout: opts.timeoutMs ?? 15_000 });
-        await page.fill(selector, text);
+        const modes = [target !== undefined, opts.urlPattern !== undefined, opts.networkIdle === true, opts.timeMs !== undefined].filter(Boolean);
+        if (modes.length !== 1)
+            throw new Error('browser_wait requires exactly one target, urlPattern, networkIdle=true, or timeMs');
+        const timeout = boundedTimeout(opts.timeoutMs, 'browser_wait timeoutMs');
+        if (target !== undefined)
+            await this.resolveTarget(page, target).waitFor({ state: opts.state ?? 'visible', timeout });
+        else if (opts.urlPattern !== undefined)
+            await page.waitForURL(boundedString(opts.urlPattern, 'urlPattern', 2_000), { timeout });
+        else if (opts.networkIdle)
+            await page.waitForLoadState('networkidle', { timeout });
+        else {
+            const timeMs = opts.timeMs;
+            if (!Number.isFinite(timeMs) || timeMs < 0 || timeMs > 10_000)
+                throw new Error('browser_wait timeMs must be between 0 and 10,000');
+            await page.waitForTimeout(timeMs);
+        }
         return this.readState(page, false);
     }
-    async hover(selector, opts = {}) {
+    async press(target, key, opts = {}) {
         const page = await this.ensureActivePage();
-        const timeoutMs = opts.timeoutMs ?? 15_000;
+        const value = boundedString(key, 'browser_press key', 100);
+        if (target !== undefined)
+            await this.resolveTarget(page, target).press(value, { timeout: boundedTimeout(opts.timeoutMs, 'browser_press timeoutMs') });
+        else
+            await page.keyboard.press(value);
+        return this.readState(page, false);
+    }
+    async select(target, values, opts = {}) {
+        if (values.length < 1 || values.length > 20)
+            throw new Error('browser_select requires 1 to 20 values');
+        values.forEach(value => boundedString(value, 'browser_select value', 2_000));
+        const page = await this.ensureActivePage();
+        await this.resolveTarget(page, target).selectOption([...values], { timeout: boundedTimeout(opts.timeoutMs, 'browser_select timeoutMs') });
+        return this.readState(page, false);
+    }
+    async check(target, checked = true, opts = {}) {
+        const page = await this.ensureActivePage();
+        const locator = this.resolveTarget(page, target);
+        if (checked)
+            await locator.check({ timeout: boundedTimeout(opts.timeoutMs, 'browser_check timeoutMs') });
+        else
+            await locator.uncheck({ timeout: boundedTimeout(opts.timeoutMs, 'browser_check timeoutMs') });
+        return this.readState(page, false);
+    }
+    async hover(target, opts = {}) {
+        const page = await this.ensureActivePage();
+        const timeoutMs = boundedTimeout(opts.timeoutMs, 'browser_hover timeoutMs');
         const waitMs = Math.min(Math.max(opts.waitMs ?? 300, 0), timeoutMs);
-        await page.waitForSelector(selector, { timeout: timeoutMs });
-        await page.hover(selector);
+        await this.resolveTarget(page, target).hover({ timeout: timeoutMs });
         await page.waitForTimeout(waitMs);
         return this.readState(page, true);
     }
-    async setFiles(selector, files, opts = {}) {
+    async setFiles(target, files, opts = {}) {
         if (files.length === 0 || files.length > 20)
             throw new Error('browser_set_files requires 1 to 20 files');
         const resolved = files.map(file => {
@@ -635,8 +903,7 @@ export class BrowserService {
         if (totalBytes > 512 * 1024 * 1024)
             throw new Error('browser_set_files total upload size exceeds 512 MiB');
         const page = await this.ensureActivePage();
-        await page.waitForSelector(selector, { timeout: opts.timeoutMs ?? 15_000 });
-        await page.setInputFiles(selector, resolved);
+        await this.resolveTarget(page, target).setInputFiles(resolved, { timeout: boundedTimeout(opts.timeoutMs, 'browser_set_files timeoutMs') });
         return { ...await this.readState(page, true), files: resolved.map(file => path.basename(file)) };
     }
     async evaluate(expression, opts = {}) {
@@ -648,15 +915,38 @@ export class BrowserService {
         const page = await this.ensureActivePage();
         const timeoutMs = Math.min(Math.max(opts.timeoutMs ?? 15_000, 1_000), 30_000);
         let timer;
+        let timedOut = false;
         const timeout = new Promise((_resolve, reject) => {
             timer = setTimeout(() => {
-                void this.closePage();
-                reject(new Error('browser_evaluate timed out after ' + timeoutMs + 'ms; the active page was closed'));
+                timedOut = true;
+                void (async () => {
+                    try {
+                        const session = await page.context().newCDPSession(page);
+                        try {
+                            await session.send('Runtime.terminateExecution');
+                        }
+                        finally {
+                            await session.detach().catch(() => { });
+                        }
+                        reject(new Error('browser_evaluate timed out after ' + timeoutMs + 'ms; page JavaScript was terminated and the active page remains open'));
+                    }
+                    catch (error) {
+                        reject(new Error('browser_evaluate timed out after ' + timeoutMs + 'ms; unable to terminate page JavaScript without closing the active page: ' + String(error).slice(0, 200)));
+                    }
+                })();
             }, timeoutMs);
         });
         try {
             const script = `(async () => {\nconst value = await (${source}\n);\nconst json = JSON.stringify(value);\nif (json === undefined) throw new Error('expression result is not JSON-serializable');\nreturn { resultJson: json.slice(0, 100000), truncated: json.length > 100000 };\n})()`;
-            const result = await Promise.race([page.evaluate(script), timeout]);
+            let result;
+            try {
+                result = await Promise.race([page.evaluate(script), timeout]);
+            }
+            catch (error) {
+                if (timedOut)
+                    throw new Error('browser_evaluate timed out after ' + timeoutMs + 'ms; page JavaScript was terminated and the active page remains open');
+                throw error;
+            }
             return {
                 url: page.url(),
                 resultJson: result.resultJson,
@@ -684,9 +974,30 @@ export class BrowserService {
         const page = await this.ensureActivePage();
         return this.readState(page, false);
     }
-    async screenshot() {
+    consoleMessages(opts = {}) {
+        const severities = ['debug', 'log', 'info', 'warning', 'error'];
+        const threshold = opts.level ? severities.indexOf(opts.level) : 0;
+        if (opts.level && threshold < 0)
+            throw new Error('browser_console level must be debug, log, info, warning, or error');
+        const limit = Math.min(Math.max(Math.trunc(opts.limit ?? 100), 1), 200);
+        const records = this.capturedConsole.filter(record => {
+            const index = severities.indexOf(record.type === 'warn' ? 'warning' : record.type);
+            return index < 0 || index >= threshold;
+        }).slice(-limit);
+        if (opts.clear)
+            this.capturedConsole = [];
+        return { enabled: this.captureConsoleEnabled, records };
+    }
+    networkRequests(opts = {}) {
+        const limit = Math.min(Math.max(Math.trunc(opts.limit ?? 100), 1), 200);
+        const records = this.capturedRequests.slice(-limit);
+        if (opts.clear)
+            this.capturedRequests = [];
+        return { enabled: this.captureNetworkEnabled, records };
+    }
+    async screenshot(options = {}) {
         const page = await this.ensureActivePage();
-        return { path: await this.captureScreenshot(page) };
+        return { path: await this.captureScreenshot(page, options) };
     }
     async recipe(steps, opts = {}) {
         if (!opts.url && (!this.activePage || this.activePage.isClosed()))
@@ -714,15 +1025,14 @@ export class BrowserService {
         }
     }
     async closePage() {
-        if (this.activePage) {
-            await this.activePage.close().catch(() => { });
-        }
-        this.activePage = undefined;
-        if (this.activeContext)
-            await this.persistAndClose({ context: this.activeContext, ...this.activeProfile ? { profile: this.activeProfile } : {} });
-        this.activeContext = undefined;
-        this.activeProfile = undefined;
-        this.activeRulePack = undefined;
+        const page = this.activePage;
+        const context = this.activeContext;
+        const profile = this.activeProfile;
+        this.clearActiveState();
+        if (page)
+            await page.close().catch(() => { });
+        if (context)
+            await this.persistAndClose({ context, ...profile ? { profile } : {} });
     }
     async status() {
         let chromiumInstalled = false;
@@ -786,8 +1096,8 @@ export class BrowserService {
             builtinScripts: BUILTIN_SCRIPTS.map(script => script.id),
             externalUserscriptsRequireApproval: ['standard', 'autonomous'].includes(this.config.automationMode),
             mutatingRecipesRequireApproval: this.config.automationMode === 'standard',
-            ...(this.activePage && !this.activePage.isClosed() ? { activeUrl: this.activePage.url() } : {}),
-            ...this.activeProfile ? { activeAuthProfile: this.activeProfile.id } : {},
+            ...(this.browserConnected() && this.activePage && !this.activePage.isClosed() ? { activeUrl: this.activePage.url() } : {}),
+            ...(this.browserConnected() && this.activePage && !this.activePage.isClosed() && this.activeProfile ? { activeAuthProfile: this.activeProfile.id } : {}),
         };
     }
     async close() {