@znmin/claude-remote-cli 0.3.2 → 0.4.0

package/src/local/browser.js

@@ -1,290 +1,290 @@
-import * as fs from 'node:fs/promises';
-import path from 'node:path';
-import os from 'node:os';
-import { createRequire } from 'node:module';
-import { randomUUID } from 'node:crypto';
-import { chromium } from 'playwright';
-import { execute, exists, withLock } from '../system.js';
-
-const require = createRequire(import.meta.url);
-const PLAYWRIGHT_VERSION = require('playwright/package.json').version;
-let preparation;
-
-const cacheDirectory = () => process.env.CLAUDE_REMOTE_CACHE_DIR || path.join(os.homedir(), '.cache', 'claude-remote');
-export const browserMarker = () => path.join(cacheDirectory(), `browser-ready-${PLAYWRIGHT_VERSION}`);
-
-// The marker records which executable a completed install produced, so a
-// warm start skips spawning the Playwright installer entirely.
-export async function browserReady() {
-  const executable = chromium.executablePath();
-  try { return (await fs.readFile(browserMarker(), 'utf8')).trim() === executable && await exists(executable); }
-  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
-}
-
-const BROWSER_NAMES = { chrome: 'Google Chrome', msedge: 'Microsoft Edge', chromium: 'Chromium（Playwright 自带）' };
-
-// Standard install locations of Chrome and Edge. Windows checks per-machine
-// and per-user installs; Edge ships with Windows 10/11.
-export function systemBrowserCandidates(kind, env = process.env, platform = process.platform, home = os.homedir()) {
-  if (platform === 'win32') {
-    const relative = kind === 'chrome' ? ['Google', 'Chrome', 'Application', 'chrome.exe'] : ['Microsoft', 'Edge', 'Application', 'msedge.exe'];
-    const bases = [env.ProgramFiles, env.ProgramW6432, env['ProgramFiles(x86)'], env.LOCALAPPDATA].filter(Boolean);
-    return [...new Set(bases.map(base => path.win32.join(base, ...relative)))];
-  }
-  if (platform === 'darwin') {
-    const app = kind === 'chrome' ? 'Google Chrome' : 'Microsoft Edge';
-    return ['/Applications', path.join(home, 'Applications')].map(directory => path.join(directory, app + '.app', 'Contents', 'MacOS', app));
-  }
-  return kind === 'chrome' ? ['/opt/google/chrome/chrome'] : ['/opt/microsoft/msedge/msedge'];
-}
-
-// CLAUDE_REMOTE_BROWSER picks one explicitly; otherwise an installed Chrome,
-// then Edge, and only without either the downloaded Chromium.
-export async function chooseBrowser(env = process.env, { platform = process.platform, home = os.homedir(),
-  fileExists = file => exists(file).catch(() => false) } = {}) {
-  const wanted = (env.CLAUDE_REMOTE_BROWSER || '').trim().toLowerCase();
-  if (wanted && !(wanted in BROWSER_NAMES)) throw new Error('CLAUDE_REMOTE_BROWSER 只能是 chrome、msedge 或 chromium。');
-  if (wanted === 'chromium') return { kind: 'chromium', explicit: true };
-  for (const kind of wanted ? [wanted] : ['chrome', 'msedge'])
-    for (const file of systemBrowserCandidates(kind, env, platform, home))
-      if (await fileExists(file)) return { kind, file, explicit: Boolean(wanted) };
-  if (wanted) throw new Error(`找不到 ${BROWSER_NAMES[wanted]}。请安装后重试，或去掉 CLAUDE_REMOTE_BROWSER 改为自动选择。`);
-  return { kind: 'chromium', explicit: false };
-}
-
-export const browserName = choice => BROWSER_NAMES[choice.kind];
-
-// Returns the browser to launch. A system browser needs no download.
-export async function installBrowser(log = console.error, { debug = () => {}, force = false, env = process.env } = {}) {
-  const choice = await chooseBrowser(env);
-  if (choice.kind !== 'chromium') { debug(`使用系统浏览器：${browserName(choice)}（${choice.file}）`); return choice; }
-  await installChromium(log, { debug, force });
-  return { ...choice, file: chromium.executablePath() };
-}
-
-export async function installChromium(log = console.error, { debug = () => {}, force = false } = {}) {
-  if (!force && await browserReady()) { debug('浏览器缓存可用：' + chromium.executablePath()); return; }
-  if (force) preparation = null;
-  if (!preparation) preparation = (async () => {
-    const cli = path.join(path.dirname(require.resolve('playwright/package.json')), 'cli.js');
-    // Keep the lock outside Playwright's cache: its installer replaces browser directories.
-    await withLock(path.join(cacheDirectory(), 'browser-install'), async () => {
-      if (!force && await browserReady()) return;
-      if (!await exists(chromium.executablePath())) log('正在下载浏览器…');
-      else debug('检查浏览器缓存：' + chromium.executablePath());
-      // The CLI checks completion markers and prepares headed AND headless binaries.
-      const result = await execute(process.execPath, [cli, 'install', 'chromium'], { capture: true, timeout: 600000 });
-      if (!await exists(chromium.executablePath())) throw new Error('浏览器安装未完成：' + result.stderr);
-      await fs.mkdir(cacheDirectory(), { recursive: true });
-      await fs.writeFile(browserMarker(), chromium.executablePath() + '\n');
-    });
-  })().catch(error => { preparation = null; throw error; });
-  await preparation;
-}
-
-// Runs inside each frame. Refs persist on elements across snapshots; the
-// per-document token keeps refs from a previous page from matching new ones.
-function collectElements({ limit, textLimit }) {
-  const attribute = 'data-claude-remote-ref';
-  window.__claudeRemote ||= { token: Math.random().toString(36).slice(2, 7), next: 0 };
-  const state = window.__claudeRemote;
-  const query = 'a,button,input,textarea,select,summary,[role="button"],[role="link"],[role="checkbox"],' +
-    '[role="radio"],[role="tab"],[role="menuitem"],[role="option"],[role="switch"],[contenteditable="true"],[onclick]';
-  const found = [];
-  const visit = root => {
-    for (const element of root.querySelectorAll(query)) found.push(element);
-    for (const element of root.querySelectorAll('*')) if (element.shadowRoot) visit(element.shadowRoot);
-  };
-  visit(document);
-  const elements = [];
-  for (const element of found) {
-    if (elements.length >= limit) break;
-    if (!element.getClientRects().length) continue;
-    let ref = element.getAttribute(attribute);
-    if (!ref || !ref.startsWith(state.token + '-')) {
-      ref = `${state.token}-${++state.next}`;
-      element.setAttribute(attribute, ref);
-    }
-    const item = { selector: `[${attribute}="${ref}"]`, tag: element.tagName.toLowerCase(),
-      text: (element.innerText || element.getAttribute('aria-label') || element.getAttribute('placeholder') ||
-        element.getAttribute('title') || '').trim().slice(0, 200) };
-    const type = element.getAttribute('type'); if (type) item.type = type;
-    const name = element.getAttribute('name'); if (name) item.name = name;
-    if (element.tagName === 'A' && element.getAttribute('href')) item.href = element.getAttribute('href').slice(0, 200);
-    if ('value' in element && typeof element.value === 'string' && element.value && type !== 'password')
-      item.value = element.value.slice(0, 200);
-    if (element.disabled) item.disabled = true;
-    if (element.checked) item.checked = true;
-    elements.push(item);
-  }
-  return { text: (document.body?.innerText || '').slice(0, textLimit), elements, more: found.length > elements.length };
-}
-
-export class Browser {
-  constructor({ headless = false, log = console.error, env = process.env } = {}) {
-    this.headless = headless; this.log = log; this.env = env; this.pages = new Map(); this.logs = new Map();
-  }
-
-  async launchChromium() {
-    await installChromium(this.log);
-    try { return await chromium.launch({ headless: this.headless }); }
-    catch (error) {
-      // The cache marker may be stale (e.g. browsers removed by hand): reinstall once.
-      if (!/Executable doesn't exist|executable/i.test(error.message)) throw error;
-      await installChromium(this.log, { force: true });
-      return chromium.launch({ headless: this.headless });
-    }
-  }
-
-  async start() {
-    if (!this.starting) this.starting = (async () => {
-      const choice = await installBrowser(this.log, { env: this.env });
-      if (choice.kind === 'chromium') this.browser = await this.launchChromium();
-      else {
-        // Each launch uses a fresh temporary profile, never the user's own.
-        try { this.browser = await chromium.launch({ headless: this.headless, executablePath: choice.file }); }
-        catch (error) {
-          const reason = error.message.split('\n')[0];
-          if (choice.explicit) throw new Error(`无法启动 ${browserName(choice)}：${reason}`);
-          this.log(`无法启动 ${browserName(choice)}，改用 Playwright 自带 Chromium：${reason}`);
-          this.browser = await this.launchChromium();
-        }
-      }
-      this.browser.on('disconnected', () => { this.starting = null; this.context = null; this.browser = null; this.pages.clear(); this.logs.clear(); });
-      this.context = await this.browser.newContext({ viewport: { width: 1280, height: 800 } });
-    })().catch(error => { this.starting = null; throw error; });
-    await this.starting;
-  }
-
-  page(id) {
-    const page = this.pages.get(id);
-    if (!page || page.isClosed()) throw new Error('找不到浏览器页面，请先调用 browser_open。');
-    return page;
-  }
-
-  // Selectors from iframes look like "frame=2 >> [data-claude-remote-ref=...]".
-  locator(page, selector) {
-    const match = selector.match(/^frame=(\d+) >> ([\s\S]+)$/);
-    if (!match) return page.locator(selector);
-    const frame = page.frames()[Number(match[1])];
-    if (!frame || frame.isDetached()) throw new Error('找不到对应 iframe，请重新调用 browser_snapshot。');
-    return frame.locator(match[2]);
-  }
-
-  async open(url = 'about:blank') {
-    await this.start();
-    if (this.pages.size >= 16) throw new Error('浏览器页面过多，请先调用 browser_close 关闭部分页面。');
-    const page = await this.context.newPage(), id = randomUUID();
-    this.pages.set(id, page); this.logs.set(id, []);
-    const record = message => {
-      const entries = this.logs.get(id); if (!entries) return;
-      entries.push(message.slice(0, 1000)); if (entries.length > 200) entries.shift();
-    };
-    page.on('console', message => record(`${message.type()}: ${message.text()}`));
-    page.on('pageerror', error => record('pageerror: ' + error.message));
-    page.on('requestfailed', request => record(`requestfailed: ${request.url()} ${request.failure()?.errorText}`));
-    let navigationError;
-    try { await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 }); }
-    catch (error) { navigationError = error.message; record(error.message); }
-    return { ...await this.snapshot(id), ...(navigationError ? { navigation_error: navigationError } : {}) };
-  }
-
-  async navigate(id, { url, action }) {
-    const page = this.page(id);
-    const options = { waitUntil: 'domcontentloaded', timeout: 30000 };
-    let navigationError;
-    try {
-      if (url) await page.goto(url, options);
-      else if (action === 'back') await page.goBack(options);
-      else if (action === 'forward') await page.goForward(options);
-      else if (action === 'reload') await page.reload(options);
-      else throw new Error('请提供 url，或 action 为 back、forward、reload 之一。');
-    } catch (error) {
-      if (!url && !action) throw error;
-      navigationError = error.message;
-    }
-    return { ...await this.snapshot(id), ...(navigationError ? { navigation_error: navigationError } : {}) };
-  }
-
-  async snapshot(id) {
-    const page = this.page(id);
-    const main = await page.mainFrame().evaluate(collectElements, { limit: 200, textLimit: 12000 });
-    const frames = [];
-    const all = page.frames();
-    for (let index = 0; index < all.length && frames.length < 10; index++) {
-      const frame = all[index];
-      if (frame === page.mainFrame() || frame.isDetached()) continue;
-      try {
-        const state = await frame.evaluate(collectElements, { limit: 50, textLimit: 2000 });
-        frames.push({ frame: index, url: frame.url(), text: state.text,
-          elements: state.elements.map(element => ({ ...element, selector: `frame=${index} >> ${element.selector}` })) });
-      } catch { /* detached or not yet loaded */ }
-    }
-    return { page_id: id, url: page.url(), title: await page.title(), text: main.text, elements: main.elements,
-      ...(main.more ? { more_elements: true } : {}), ...(frames.length ? { frames } : {}) };
-  }
-
-  async action(id, action, selector, value) {
-    const page = this.page(id);
-    const options = { timeout: 15000 };
-    if (action === 'click') await this.locator(page, selector).click(options);
-    else if (action === 'fill') await this.locator(page, selector).fill(value, options);
-    else if (action === 'hover') await this.locator(page, selector).hover(options);
-    else if (action === 'select') await this.locator(page, selector).selectOption(value, options);
-    else if (action === 'press') {
-      if (selector) await this.locator(page, selector).press(value, options);
-      else await page.keyboard.press(value);
-    }
-    return this.snapshot(id);
-  }
-
-  async scroll(id, { selector, x = 0, y = 0 }) {
-    const page = this.page(id);
-    if (selector) await this.locator(page, selector).scrollIntoViewIfNeeded({ timeout: 15000 });
-    else {
-      // mouse.wheel does not wait for the scroll to happen; give it a moment.
-      await page.mouse.wheel(x, y);
-      await page.waitForTimeout(200);
-    }
-    return this.snapshot(id);
-  }
-
-  async waitFor(id, { selector, text, state = 'visible', timeout = 10000 }) {
-    const page = this.page(id);
-    if (selector) await this.locator(page, selector).first().waitFor({ state, timeout });
-    else if (text) await page.getByText(text).first().waitFor({ state, timeout });
-    else await page.waitForLoadState('load', { timeout });
-    return this.snapshot(id);
-  }
-
-  async evaluate(id, expression) {
-    const result = await this.page(id).evaluate(expression);
-    return { page_id: id, result: result === undefined ? null : result };
-  }
-
-  async screenshot(id, { fullPage = false, selector } = {}) {
-    const page = this.page(id);
-    const options = { type: 'png', timeout: 15000 };
-    const buffer = selector ? await this.locator(page, selector).screenshot(options)
-      : await page.screenshot({ ...options, fullPage });
-    return { content: [{ type: 'image', data: buffer.toString('base64'), mimeType: 'image/png' }] };
-  }
-
-  readLogs(id, limit = 20) {
-    this.page(id);
-    const logs = this.logs.get(id);
-    return { logs: logs.slice(-limit), total: logs.length, truncated: logs.length > limit };
-  }
-
-  async closePage(id) {
-    await this.page(id).close(); this.pages.delete(id); this.logs.delete(id);
-    return { closed: id };
-  }
-
-  async close() {
-    if (this.starting) await this.starting.catch(() => {});
-    await this.browser?.close();
-    this.browser = null; this.context = null; this.starting = null;
-    this.pages.clear(); this.logs.clear();
-  }
-}
+import * as fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { createRequire } from 'node:module';
+import { randomUUID } from 'node:crypto';
+import { chromium } from 'playwright';
+import { execute, exists, withLock } from '../system.js';
+
+const require = createRequire(import.meta.url);
+const PLAYWRIGHT_VERSION = require('playwright/package.json').version;
+let preparation;
+
+const cacheDirectory = () => process.env.CLAUDE_REMOTE_CACHE_DIR || path.join(os.homedir(), '.cache', 'claude-remote');
+export const browserMarker = () => path.join(cacheDirectory(), `browser-ready-${PLAYWRIGHT_VERSION}`);
+
+// The marker records which executable a completed install produced, so a
+// warm start skips spawning the Playwright installer entirely.
+export async function browserReady() {
+  const executable = chromium.executablePath();
+  try { return (await fs.readFile(browserMarker(), 'utf8')).trim() === executable && await exists(executable); }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+const BROWSER_NAMES = { chrome: 'Google Chrome', msedge: 'Microsoft Edge', chromium: 'Chromium（Playwright 自带）' };
+
+// Standard install locations of Chrome and Edge. Windows checks per-machine
+// and per-user installs; Edge ships with Windows 10/11.
+export function systemBrowserCandidates(kind, env = process.env, platform = process.platform, home = os.homedir()) {
+  if (platform === 'win32') {
+    const relative = kind === 'chrome' ? ['Google', 'Chrome', 'Application', 'chrome.exe'] : ['Microsoft', 'Edge', 'Application', 'msedge.exe'];
+    const bases = [env.ProgramFiles, env.ProgramW6432, env['ProgramFiles(x86)'], env.LOCALAPPDATA].filter(Boolean);
+    return [...new Set(bases.map(base => path.win32.join(base, ...relative)))];
+  }
+  if (platform === 'darwin') {
+    const app = kind === 'chrome' ? 'Google Chrome' : 'Microsoft Edge';
+    return ['/Applications', path.join(home, 'Applications')].map(directory => path.join(directory, app + '.app', 'Contents', 'MacOS', app));
+  }
+  return kind === 'chrome' ? ['/opt/google/chrome/chrome'] : ['/opt/microsoft/msedge/msedge'];
+}
+
+// CLAUDE_REMOTE_BROWSER picks one explicitly; otherwise an installed Chrome,
+// then Edge, and only without either the downloaded Chromium.
+export async function chooseBrowser(env = process.env, { platform = process.platform, home = os.homedir(),
+  fileExists = file => exists(file).catch(() => false) } = {}) {
+  const wanted = (env.CLAUDE_REMOTE_BROWSER || '').trim().toLowerCase();
+  if (wanted && !(wanted in BROWSER_NAMES)) throw new Error('CLAUDE_REMOTE_BROWSER 只能是 chrome、msedge 或 chromium。');
+  if (wanted === 'chromium') return { kind: 'chromium', explicit: true };
+  for (const kind of wanted ? [wanted] : ['chrome', 'msedge'])
+    for (const file of systemBrowserCandidates(kind, env, platform, home))
+      if (await fileExists(file)) return { kind, file, explicit: Boolean(wanted) };
+  if (wanted) throw new Error(`找不到 ${BROWSER_NAMES[wanted]}。请安装后重试，或去掉 CLAUDE_REMOTE_BROWSER 改为自动选择。`);
+  return { kind: 'chromium', explicit: false };
+}
+
+export const browserName = choice => BROWSER_NAMES[choice.kind];
+
+// Returns the browser to launch. A system browser needs no download.
+export async function installBrowser(log = console.error, { debug = () => {}, force = false, env = process.env } = {}) {
+  const choice = await chooseBrowser(env);
+  if (choice.kind !== 'chromium') { debug(`使用系统浏览器：${browserName(choice)}（${choice.file}）`); return choice; }
+  await installChromium(log, { debug, force });
+  return { ...choice, file: chromium.executablePath() };
+}
+
+export async function installChromium(log = console.error, { debug = () => {}, force = false } = {}) {
+  if (!force && await browserReady()) { debug('浏览器缓存可用：' + chromium.executablePath()); return; }
+  if (force) preparation = null;
+  if (!preparation) preparation = (async () => {
+    const cli = path.join(path.dirname(require.resolve('playwright/package.json')), 'cli.js');
+    // Keep the lock outside Playwright's cache: its installer replaces browser directories.
+    await withLock(path.join(cacheDirectory(), 'browser-install'), async () => {
+      if (!force && await browserReady()) return;
+      if (!await exists(chromium.executablePath())) log('正在下载浏览器…');
+      else debug('检查浏览器缓存：' + chromium.executablePath());
+      // The CLI checks completion markers and prepares headed AND headless binaries.
+      const result = await execute(process.execPath, [cli, 'install', 'chromium'], { capture: true, timeout: 600000 });
+      if (!await exists(chromium.executablePath())) throw new Error('浏览器安装未完成：' + result.stderr);
+      await fs.mkdir(cacheDirectory(), { recursive: true });
+      await fs.writeFile(browserMarker(), chromium.executablePath() + '\n');
+    });
+  })().catch(error => { preparation = null; throw error; });
+  await preparation;
+}
+
+// Runs inside each frame. Refs persist on elements across snapshots; the
+// per-document token keeps refs from a previous page from matching new ones.
+function collectElements({ limit, textLimit }) {
+  const attribute = 'data-claude-remote-ref';
+  window.__claudeRemote ||= { token: Math.random().toString(36).slice(2, 7), next: 0 };
+  const state = window.__claudeRemote;
+  const query = 'a,button,input,textarea,select,summary,[role="button"],[role="link"],[role="checkbox"],' +
+    '[role="radio"],[role="tab"],[role="menuitem"],[role="option"],[role="switch"],[contenteditable="true"],[onclick]';
+  const found = [];
+  const visit = root => {
+    for (const element of root.querySelectorAll(query)) found.push(element);
+    for (const element of root.querySelectorAll('*')) if (element.shadowRoot) visit(element.shadowRoot);
+  };
+  visit(document);
+  const elements = [];
+  for (const element of found) {
+    if (elements.length >= limit) break;
+    if (!element.getClientRects().length) continue;
+    let ref = element.getAttribute(attribute);
+    if (!ref || !ref.startsWith(state.token + '-')) {
+      ref = `${state.token}-${++state.next}`;
+      element.setAttribute(attribute, ref);
+    }
+    const item = { selector: `[${attribute}="${ref}"]`, tag: element.tagName.toLowerCase(),
+      text: (element.innerText || element.getAttribute('aria-label') || element.getAttribute('placeholder') ||
+        element.getAttribute('title') || '').trim().slice(0, 200) };
+    const type = element.getAttribute('type'); if (type) item.type = type;
+    const name = element.getAttribute('name'); if (name) item.name = name;
+    if (element.tagName === 'A' && element.getAttribute('href')) item.href = element.getAttribute('href').slice(0, 200);
+    if ('value' in element && typeof element.value === 'string' && element.value && type !== 'password')
+      item.value = element.value.slice(0, 200);
+    if (element.disabled) item.disabled = true;
+    if (element.checked) item.checked = true;
+    elements.push(item);
+  }
+  return { text: (document.body?.innerText || '').slice(0, textLimit), elements, more: found.length > elements.length };
+}
+
+export class Browser {
+  constructor({ headless = false, log = console.error, env = process.env } = {}) {
+    this.headless = headless; this.log = log; this.env = env; this.pages = new Map(); this.logs = new Map();
+  }
+
+  async launchChromium() {
+    await installChromium(this.log);
+    try { return await chromium.launch({ headless: this.headless }); }
+    catch (error) {
+      // The cache marker may be stale (e.g. browsers removed by hand): reinstall once.
+      if (!/Executable doesn't exist|executable/i.test(error.message)) throw error;
+      await installChromium(this.log, { force: true });
+      return chromium.launch({ headless: this.headless });
+    }
+  }
+
+  async start() {
+    if (!this.starting) this.starting = (async () => {
+      const choice = await installBrowser(this.log, { env: this.env });
+      if (choice.kind === 'chromium') this.browser = await this.launchChromium();
+      else {
+        // Each launch uses a fresh temporary profile, never the user's own.
+        try { this.browser = await chromium.launch({ headless: this.headless, executablePath: choice.file }); }
+        catch (error) {
+          const reason = error.message.split('\n')[0];
+          if (choice.explicit) throw new Error(`无法启动 ${browserName(choice)}：${reason}`);
+          this.log(`无法启动 ${browserName(choice)}，改用 Playwright 自带 Chromium：${reason}`);
+          this.browser = await this.launchChromium();
+        }
+      }
+      this.browser.on('disconnected', () => { this.starting = null; this.context = null; this.browser = null; this.pages.clear(); this.logs.clear(); });
+      this.context = await this.browser.newContext({ viewport: { width: 1280, height: 800 } });
+    })().catch(error => { this.starting = null; throw error; });
+    await this.starting;
+  }
+
+  page(id) {
+    const page = this.pages.get(id);
+    if (!page || page.isClosed()) throw new Error('找不到浏览器页面，请先调用 browser_open。');
+    return page;
+  }
+
+  // Selectors from iframes look like "frame=2 >> [data-claude-remote-ref=...]".
+  locator(page, selector) {
+    const match = selector.match(/^frame=(\d+) >> ([\s\S]+)$/);
+    if (!match) return page.locator(selector);
+    const frame = page.frames()[Number(match[1])];
+    if (!frame || frame.isDetached()) throw new Error('找不到对应 iframe，请重新调用 browser_snapshot。');
+    return frame.locator(match[2]);
+  }
+
+  async open(url = 'about:blank') {
+    await this.start();
+    if (this.pages.size >= 16) throw new Error('浏览器页面过多，请先调用 browser_close 关闭部分页面。');
+    const page = await this.context.newPage(), id = randomUUID();
+    this.pages.set(id, page); this.logs.set(id, []);
+    const record = message => {
+      const entries = this.logs.get(id); if (!entries) return;
+      entries.push(message.slice(0, 1000)); if (entries.length > 200) entries.shift();
+    };
+    page.on('console', message => record(`${message.type()}: ${message.text()}`));
+    page.on('pageerror', error => record('pageerror: ' + error.message));
+    page.on('requestfailed', request => record(`requestfailed: ${request.url()} ${request.failure()?.errorText}`));
+    let navigationError;
+    try { await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 }); }
+    catch (error) { navigationError = error.message; record(error.message); }
+    return { ...await this.snapshot(id), ...(navigationError ? { navigation_error: navigationError } : {}) };
+  }
+
+  async navigate(id, { url, action }) {
+    const page = this.page(id);
+    const options = { waitUntil: 'domcontentloaded', timeout: 30000 };
+    let navigationError;
+    try {
+      if (url) await page.goto(url, options);
+      else if (action === 'back') await page.goBack(options);
+      else if (action === 'forward') await page.goForward(options);
+      else if (action === 'reload') await page.reload(options);
+      else throw new Error('请提供 url，或 action 为 back、forward、reload 之一。');
+    } catch (error) {
+      if (!url && !action) throw error;
+      navigationError = error.message;
+    }
+    return { ...await this.snapshot(id), ...(navigationError ? { navigation_error: navigationError } : {}) };
+  }
+
+  async snapshot(id) {
+    const page = this.page(id);
+    const main = await page.mainFrame().evaluate(collectElements, { limit: 200, textLimit: 12000 });
+    const frames = [];
+    const all = page.frames();
+    for (let index = 0; index < all.length && frames.length < 10; index++) {
+      const frame = all[index];
+      if (frame === page.mainFrame() || frame.isDetached()) continue;
+      try {
+        const state = await frame.evaluate(collectElements, { limit: 50, textLimit: 2000 });
+        frames.push({ frame: index, url: frame.url(), text: state.text,
+          elements: state.elements.map(element => ({ ...element, selector: `frame=${index} >> ${element.selector}` })) });
+      } catch { /* detached or not yet loaded */ }
+    }
+    return { page_id: id, url: page.url(), title: await page.title(), text: main.text, elements: main.elements,
+      ...(main.more ? { more_elements: true } : {}), ...(frames.length ? { frames } : {}) };
+  }
+
+  async action(id, action, selector, value) {
+    const page = this.page(id);
+    const options = { timeout: 15000 };
+    if (action === 'click') await this.locator(page, selector).click(options);
+    else if (action === 'fill') await this.locator(page, selector).fill(value, options);
+    else if (action === 'hover') await this.locator(page, selector).hover(options);
+    else if (action === 'select') await this.locator(page, selector).selectOption(value, options);
+    else if (action === 'press') {
+      if (selector) await this.locator(page, selector).press(value, options);
+      else await page.keyboard.press(value);
+    }
+    return this.snapshot(id);
+  }
+
+  async scroll(id, { selector, x = 0, y = 0 }) {
+    const page = this.page(id);
+    if (selector) await this.locator(page, selector).scrollIntoViewIfNeeded({ timeout: 15000 });
+    else {
+      // mouse.wheel does not wait for the scroll to happen; give it a moment.
+      await page.mouse.wheel(x, y);
+      await page.waitForTimeout(200);
+    }
+    return this.snapshot(id);
+  }
+
+  async waitFor(id, { selector, text, state = 'visible', timeout = 10000 }) {
+    const page = this.page(id);
+    if (selector) await this.locator(page, selector).first().waitFor({ state, timeout });
+    else if (text) await page.getByText(text).first().waitFor({ state, timeout });
+    else await page.waitForLoadState('load', { timeout });
+    return this.snapshot(id);
+  }
+
+  async evaluate(id, expression) {
+    const result = await this.page(id).evaluate(expression);
+    return { page_id: id, result: result === undefined ? null : result };
+  }
+
+  async screenshot(id, { fullPage = false, selector } = {}) {
+    const page = this.page(id);
+    const options = { type: 'png', timeout: 15000 };
+    const buffer = selector ? await this.locator(page, selector).screenshot(options)
+      : await page.screenshot({ ...options, fullPage });
+    return { content: [{ type: 'image', data: buffer.toString('base64'), mimeType: 'image/png' }] };
+  }
+
+  readLogs(id, limit = 20) {
+    this.page(id);
+    const logs = this.logs.get(id);
+    return { logs: logs.slice(-limit), total: logs.length, truncated: logs.length > limit };
+  }
+
+  async closePage(id) {
+    await this.page(id).close(); this.pages.delete(id); this.logs.delete(id);
+    return { closed: id };
+  }
+
+  async close() {
+    if (this.starting) await this.starting.catch(() => {});
+    await this.browser?.close();
+    this.browser = null; this.context = null; this.starting = null;
+    this.pages.clear(); this.logs.clear();
+  }
+}