Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

perf(browser): 消除固定 DOM 读取的交互等待并保留生命周期检查

Dashf4be3f8bd043
diff --git a/packages/browser-control-runtime/package.json b/packages/browser-control-runtime/package.json
index f4695a75d6..c5e58a05a7 100644
--- a/packages/browser-control-runtime/package.json
+++ b/packages/browser-control-runtime/package.json
@@ -8,6 +8,7 @@
"types": "./src/index.ts",
"exports": {
".": "./src/index.ts",
+ "./dom-read": "./src/dom-read.ts",
"./config-dir": "./src/shim/_local/text-utils.ts",
"./ssrf-runtime": "./src/shim/ssrf-runtime.ts"
},
diff --git a/packages/browser-control-runtime/src/__tests__/interaction-proxy-policy.test.ts b/packages/browser-control-runtime/src/__tests__/interaction-proxy-policy.test.ts
index f8f7e0e58b..b349f3a87e 100644
--- a/packages/browser-control-runtime/src/__tests__/interaction-proxy-policy.test.ts
+++ b/packages/browser-control-runtime/src/__tests__/interaction-proxy-policy.test.ts
@@ -1,4 +1,6 @@
import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { runInNewContext } from 'node:vm';
+import { readBrowserDom } from '../shim/browser-dom-read.js';
const mocks = vi.hoisted(() => ({
assertBrowserNavigationResultAllowed: vi.fn(async () => undefined),
@@ -24,7 +26,7 @@ vi.mock('../_generated/extension/src/browser/pw-session.js', () => ({
assertPageNavigationCompletedSafely: mocks.assertPageNavigationCompletedSafely,
closeBlockedNavigationTarget: mocks.closeBlockedNavigationTarget,
quarantineTargetWithoutClosing: mocks.quarantineTargetWithoutClosing,
- createObservedDialogAbortSignalForPage: () => ({ signal: undefined, cleanup: vi.fn() }),
+ createObservedDialogAbortSignalForPage: ({ parentSignal }: { parentSignal?: AbortSignal }) => ({ signal: parentSignal ?? new AbortController().signal, cleanup: vi.fn() }),
ensurePageState: vi.fn(),
forceDisconnectPlaywrightForTarget: vi.fn(async () => undefined),
getPageForTargetId: mocks.getPageForTargetId,
@@ -47,6 +49,93 @@ import {
setInputFilesViaPlaywright,
} from '../_generated/extension/src/browser/pw-tools-core.interactions.js';
+// Regression: fixed reads used the 250ms interaction grace window. This unit
+// tier verifies the real read helper's policy/result/cleanup boundary; the live
+// browser regression verifies isolated-world execution and iframe detection.
+describe('fixed DOM reads', () => {
+ const options = { cdpUrl: 'http://127.0.0.1:18800', targetId: 'page-1',
+ spec: { kind: 'login-wall' }, ssrfPolicy: { hostnameAllowlist: ['allowed.example'] },
+ browserProxyMode: 'explicit-browser-proxy' as const };
+ const url = 'https://allowed.example/';
+ function pageFixture(afterEvaluate?: () => void) {
+ const detach = vi.fn(async () => {});
+ const frame = { id: 'frame-1', loaderId: 'document-1' };
+ const send = vi.fn(async (method: string, params?: Record<string, unknown>) => {
+ if (method === 'Page.getFrameTree') return { frameTree: { frame: { ...frame } } };
+ if (method === 'Page.createIsolatedWorld') {
+ expect(params).toEqual({ frameId: 'frame-1', worldName: 'cindy-dom-read' });
+ return { executionContextId: 17 };
+ }
+ expect(method).toBe('Runtime.evaluate');
+ expect(params).toMatchObject({ contextId: 17, returnByValue: true, timeout: 20000 });
+ const value = runInNewContext(String(params?.expression), {
+ location: { href: url },
+ document: { querySelectorAll: () => [], querySelector: (selector: string) => selector === 'input[type=password]' ? {} : null },
+ });
+ afterEvaluate?.();
+ return { result: { value } };
+ });
+ const page = { url: () => url, context: () => ({ newCDPSession: async () => ({ send, detach }) }) };
+ mocks.getPageForTargetId.mockResolvedValue(page);
+ return { page, send, detach, frame };
+ }
+ beforeEach(() => {
+ vi.clearAllMocks();
+ mocks.assertPageNavigationCompletedSafely.mockResolvedValue(undefined);
+ });
+ it('returns fixed login detection with both policy checks and releases the CDP session', async () => {
+ const { detach } = pageFixture();
+ await expect(readBrowserDom(options)).resolves.toEqual({ url, value: { password: true, code: false } });
+ expect(mocks.assertPageNavigationCompletedSafely).toHaveBeenCalledTimes(2);
+ expect(mocks.assertPageNavigationCompletedSafely).toHaveBeenLastCalledWith(expect.objectContaining({
+ ssrfPolicy: options.ssrfPolicy, browserProxyMode: options.browserProxyMode,
+ }));
+ expect(detach).toHaveBeenCalledOnce();
+ });
+ it.each(['before', 'after'])('does not return content when navigation policy rejects %s the read', async (phase) => {
+ const { send, detach } = pageFixture();
+ if (phase === 'after') mocks.assertPageNavigationCompletedSafely.mockResolvedValueOnce(undefined);
+ mocks.assertPageNavigationCompletedSafely.mockRejectedValueOnce(new Error('Navigation blocked'));
+ await expect(readBrowserDom(options)).rejects.toThrow('Navigation blocked');
+ expect(send).toHaveBeenCalledTimes(phase === 'before' ? 0 : 3);
+ expect(detach).toHaveBeenCalledTimes(phase === 'before' ? 0 : 1);
+ });
+ it('rejects caller-supplied code instead of treating it as a read-only assertion', async () => {
+ const { send } = pageFixture();
+ await expect(readBrowserDom({ ...options, spec: { kind: 'login-wall', fn: '() => location.reload()' } })).rejects.toThrow();
+ expect(send).not.toHaveBeenCalled();
+ });
+ it('discards results after navigation or cancellation and detaches in both cases', async () => {
+ const controller = new AbortController();
+ const changed = pageFixture(() => { changed.page.url = () => 'https://allowed.example/next'; });
+ await expect(readBrowserDom(options)).rejects.toThrow('PAGE_CHANGED');
+ expect(changed.detach).toHaveBeenCalledOnce();
+ const cancelled = pageFixture(() => controller.abort(new Error('cancelled')));
+ await expect(readBrowserDom({ ...options, signal: controller.signal })).rejects.toThrow('cancelled');
+ expect(cancelled.detach).toHaveBeenCalledOnce();
+ });
+ it('rejects results from a replaced document even when its URL stays the same', async () => {
+ const changed = pageFixture(() => { changed.frame.loaderId = 'document-2'; });
+ await expect(readBrowserDom(options)).rejects.toThrow('PAGE_CHANGED');
+ expect(changed.detach).toHaveBeenCalledOnce();
+ });
+ it('bounds a stalled protocol read and still releases its session', async () => {
+ vi.useFakeTimers();
+ try {
+ const { send, detach } = pageFixture();
+ const original = send.getMockImplementation()!;
+ send.mockImplementation((method, params) => method === 'Runtime.evaluate'
+ ? new Promise(() => {}) : original(method, params));
+ const assertion = expect(readBrowserDom(options)).rejects.toThrow('DOM read timed out');
+ await vi.advanceTimersByTimeAsync(20000);
+ await assertion;
+ expect(detach).toHaveBeenCalledOnce();
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+});
+
describe('Playwright interaction proxy navigation policy', () => {
beforeEach(() => {
vi.clearAllMocks();
diff --git a/packages/browser-control-runtime/src/_generated/extension/src/browser/routes/agent.act.ts b/packages/browser-control-runtime/src/_generated/extension/src/browser/routes/agent.act.ts
index e8365e8be8..bb192227cb 100644
--- a/packages/browser-control-runtime/src/_generated/extension/src/browser/routes/agent.act.ts
+++ b/packages/browser-control-runtime/src/_generated/extension/src/browser/routes/agent.act.ts
@@ -40,6 +40,7 @@ import {
import { registerBrowserAgentActHookRoutes } from "./agent.act.hooks.js";
import { normalizeActRequest, validateBatchTargetIds } from "./agent.act.normalize.js";
import { resolveActionTargetIds } from "../../../../../shim/browser-action-targets.js";
+import { readBrowserDom } from "../../../../../shim/browser-dom-read.js";
import { type ActKind, isActKind } from "./agent.act.shared.js";
import {
browserNavigationPolicyForProfile,
@@ -459,6 +460,23 @@ export function registerBrowserAgentActRoutes(
...extra,
});
};
+ // Only structured host reads enter this path. Arbitrary fn is
+ // ignored here, never trusted as a promise of read-only behavior.
+ if (action.kind === "evaluate" && body.domRead !== undefined && !isExistingSession) {
+ if (!evaluateEnabled) {
+ return jsonActError(res, 403, ACT_ERROR_CODES.evaluateDisabled,
+ browserEvaluateDisabledMessage("evaluate"));
+ }
+ const observed = await readBrowserDom({
+ cdpUrl, targetId: tab.targetId, spec: body.domRead,
+ timeoutMs: action.timeoutMs, ssrfPolicy,
+ browserProxyMode: navigationPolicy.browserProxyMode, signal: req.signal,
+ });
+ if ("blockedByDialog" in observed) {
+ return res.json({ ok: true, targetId: tab.targetId, ...observed });
+ }
+ return res.json({ ok: true, targetId: tab.targetId, url: observed.url, result: observed.value });
+ }
const profileName = profileCtx.profile.name;
if (isExistingSession) {
const initialTabTargetIds = hasNavigationResultPolicy
diff --git a/packages/browser-control-runtime/src/dom-read.ts b/packages/browser-control-runtime/src/dom-read.ts
new file mode 100644
index 0000000000..abadb25ed5
--- /dev/null
+++ b/packages/browser-control-runtime/src/dom-read.ts
@@ -0,0 +1,180 @@
+/**
+ * `extract` — structured DOM extraction, compiled to a single injected JS
+ * function shared by the isolated DOM reader and the legacy `act:evaluate`
+ * fallback. Pulling just the fields you need is far cheaper than a
+ * full-page snapshot + letting the model hunt for them in thousands of nodes.
+ *
+ * `buildExtractFnSource()` is a PURE function (spec → JS source string) so it is
+ * unit-testable without a browser. All selectors/attrs are injected via
+ * `JSON.stringify` (never string-concatenated) to avoid breaking out of the
+ * generated source.
+ */
+
+import { z } from "zod";
+
+/** Reusable zod schema for an extract spec — shared by the `browser` tool input
+ * and recipe `extract` steps so the two never drift. */
+export const ExtractSpecSchema = z.object({
+ from: z.string().optional(),
+ multiple: z.boolean().optional(),
+ fields: z.record(
+ z.string(),
+ z.union([
+ z.string(),
+ z.object({
+ selector: z.string().optional(),
+ attr: z.string().optional(),
+ type: z.enum(["text", "html", "attr", "href"]).optional(),
+ }),
+ ]),
+ ),
+ limit: z.number().int().positive().optional(),
+});
+
+/** A field is either a CSS selector shorthand (→ trimmed textContent) or a spec. */
+export type ExtractFieldSpec =
+ | string
+ | {
+ /** CSS selector relative to the record container; omit = the container itself. */
+ selector?: string;
+ /** Attribute name (implies type 'attr' unless `type` says otherwise). */
+ attr?: string;
+ /** How to read the resolved element. Default 'text'. */
+ type?: "text" | "html" | "attr" | "href";
+ };
+
+export interface ExtractSpec {
+ /** Container selector. With `multiple`, one record per match; else a single record. Omit = whole document. */
+ from?: string;
+ /** querySelectorAll over `from` → one record each. */
+ multiple?: boolean;
+ /** Field name → how to extract it. */
+ fields: Record<string, ExtractFieldSpec>;
+ /** Cap the number of records (only meaningful with `multiple`). */
+ limit?: number;
+}
+
+interface NormalizedField {
+ selector?: string;
+ attr?: string;
+ type: "text" | "html" | "attr" | "href";
+}
+
+/**
+ * Agent-facing teaching hint embedded in the extract result when a selector is
+ * invalid — mirrors the upstream "teach via error" idiom (SELECTOR_UNSUPPORTED_MESSAGE):
+ * the error itself shows the correct usage so the model self-corrects.
+ */
+export const EXTRACT_FIELD_HINT =
+ "fields 的简写 string 是**纯 CSS 选择器**(取该元素 textContent);" +
+ '要取属性用对象形式 {selector:"h3 a", attr:"title"};取链接用 {selector:"a", type:"href"}。' +
+ '不要把属性名拼进选择器(如 "h3 a@title" 非法),也不要写自然语言。' +
+ "不确定真实结构时,先用 snapshot(可带 selector 收窄)看 DOM,再据此写 extract 的选择器。";
+
+/** All selector strings referenced by a spec (`from` + each field's selector). */
+export function collectSelectors(spec: ExtractSpec): string[] {
+ const out: string[] = [];
+ if (spec.from) out.push(spec.from);
+ for (const f of Object.values(spec.fields)) {
+ if (typeof f === "string") out.push(f);
+ else if (f.selector) out.push(f.selector);
+ }
+ return out;
+}
+
+/** Expand field shorthands to a uniform `{selector, attr, type}` shape. */
+function normalizeFields(
+ fields: Record<string, ExtractFieldSpec>,
+): Record<string, NormalizedField> {
+ const out: Record<string, NormalizedField> = {};
+ for (const [name, f] of Object.entries(fields)) {
+ if (typeof f === "string") {
+ out[name] = { selector: f, type: "text" };
+ } else {
+ out[name] = {
+ selector: f.selector,
+ attr: f.attr,
+ type: f.type ?? (f.attr ? "attr" : "text"),
+ };
+ }
+ }
+ return out;
+}
+
+/**
+ * Compile an extract spec into a zero-arg JS function source string suitable for
+ * `act:evaluate`. The function runs in page context and returns
+ * `{ ok: true, count, records }`.
+ */
+export function buildExtractFnSource(spec: ExtractSpec): string {
+ const normalized = {
+ from: spec.from,
+ multiple: Boolean(spec.multiple),
+ limit: spec.limit,
+ fields: normalizeFields(spec.fields),
+ };
+ // The whole spec + hint are embedded as JSON literals — selectors/attrs are
+ // data, not code, so there is no injection surface.
+ const specLiteral = JSON.stringify(normalized);
+ const hintLiteral = JSON.stringify(EXTRACT_FIELD_HINT);
+ // querySelector is guarded: an invalid selector (e.g. natural language, or the
+ // "h3 a@title" attr-in-selector mistake) is collected into `bad` and reported
+ // as ok:false + hint, instead of throwing and killing the whole extract.
+ return `() => {
+ const SPEC = ${specLiteral};
+ const HINT = ${hintLiteral};
+ const bad = [];
+ const qOne = (root, s) => { try { return root.querySelector(s); } catch (e) { bad.push(s); return null; } };
+ const qAll = (root, s) => { try { return Array.from(root.querySelectorAll(s)); } catch (e) { bad.push(s); return []; } };
+ const containers = SPEC.from
+ ? (SPEC.multiple ? qAll(document, SPEC.from) : [qOne(document, SPEC.from)].filter(Boolean))
+ : [document];
+ const limited = SPEC.limit ? containers.slice(0, SPEC.limit) : containers;
+ const pick = (container, f) => {
+ const el = f.selector ? qOne(container, f.selector) : container;
+ if (!el) return null;
+ if (f.type === 'html') return el.innerHTML;
+ if (f.type === 'href') {
+ const h = el.getAttribute('href');
+ try { return h == null ? null : new URL(h, location.href).href; } catch (_e) { return h; }
+ }
+ if (f.type === 'attr') return f.attr ? el.getAttribute(f.attr) : null;
+ return (el.textContent || '').trim();
+ };
+ const records = limited.map((container) => {
+ const rec = {};
+ for (const name of Object.keys(SPEC.fields)) rec[name] = pick(container, SPEC.fields[name]);
+ return rec;
+ });
+ if (bad.length) {
+ return { ok: false, error: 'invalid CSS selector(s): ' + Array.from(new Set(bad)).join(', '), hint: HINT, count: records.length, records };
+ }
+ return { ok: true, count: records.length, records };
+}`;
+}
+
+/** Fixed internal reads, not an assertion that arbitrary JavaScript is safe. */
+export const BrowserDomReadSchema = z.discriminatedUnion("kind", [
+ z.object({ kind: z.literal("extract"), extract: ExtractSpecSchema }).strict(),
+ z.object({ kind: z.literal("login-wall") }).strict(),
+]);
+export type BrowserDomRead = z.infer<typeof BrowserDomReadSchema>;
+
+export const LOGIN_WALL_FN = `() => {
+ const docs = [document];
+ for (const frame of document.querySelectorAll('iframe')) {
+ try { if (frame.contentDocument) docs.push(frame.contentDocument); } catch {}
+ }
+ const has = (selector) => docs.some((doc) => doc.querySelector(selector));
+ return {
+ password: !!has('input[type=password]'),
+ code: !!has('input[autocomplete="one-time-code"]'),
+ };
+}`;
+
+export function buildDomReadSource(input: unknown): string {
+ const read = BrowserDomReadSchema.parse(input);
+ return read.kind === "extract"
+ ? buildExtractFnSource(read.extract)
+ : LOGIN_WALL_FN;
+}
diff --git a/packages/browser-control-runtime/src/shim/browser-dom-read.ts b/packages/browser-control-runtime/src/shim/browser-dom-read.ts
new file mode 100644
index 0000000000..360b63368e
--- /dev/null
+++ b/packages/browser-control-runtime/src/shim/browser-dom-read.ts
@@ -0,0 +1,120 @@
+import type { SsrFPolicy } from "../_generated/extension/src/infra/net/ssrf.js";
+import type { BrowserNavigationPolicyOptions } from "../_generated/extension/src/browser/navigation-guard.js";
+import {
+ assertPageNavigationCompletedSafely,
+ createObservedDialogAbortSignalForPage,
+ getPageForTargetId,
+ isBrowserObservedDialogBlockedError,
+} from "../_generated/extension/src/browser/pw-session.js";
+import { withPageScopedCdpClient } from "../_generated/extension/src/browser/pw-session.page-cdp.js";
+import { normalizeTimeoutMs } from "../_generated/extension/src/browser/pw-tools-core.shared.js";
+import { buildDomReadSource } from "../dom-read.js";
+
+/** Fixed DOM queries run in an isolated world: page-overridden getters and
+ * querySelector cannot turn a read into an interaction. Never accepts JS source
+ * or grants cross-origin access. Navigation policy is checked before and after. */
+export async function readBrowserDom(opts: {
+ cdpUrl: string;
+ targetId: string;
+ spec: unknown;
+ timeoutMs?: number;
+ ssrfPolicy?: SsrFPolicy;
+ browserProxyMode?: BrowserNavigationPolicyOptions["browserProxyMode"];
+ signal?: AbortSignal;
+}): Promise<
+ | { url: string; value: unknown }
+ | { blockedByDialog: true; browserState: unknown }
+> {
+ const source = buildDomReadSource(opts.spec);
+ opts.signal?.throwIfAborted();
+ const page = await getPageForTargetId(opts);
+ const dialog = createObservedDialogAbortSignalForPage({
+ page,
+ parentSignal: opts.signal,
+ });
+ const deadline = new AbortController();
+ const timeoutMs = normalizeTimeoutMs(opts.timeoutMs, 20000);
+ const timer = setTimeout(
+ () => deadline.abort(new Error("DOM read timed out")),
+ timeoutMs,
+ );
+ const signal = AbortSignal.any([dialog.signal, deadline.signal]);
+ let onAbort: () => void;
+ const aborted = new Promise<never>((_, reject) => {
+ onAbort = () => reject(signal.reason);
+ signal.addEventListener("abort", onAbort, { once: true });
+ });
+ // Also bound protocol commands that Chrome queues behind a modal or busy page.
+ const bounded = <T>(pending: Promise<T>) => Promise.race([pending, aborted]);
+ const validatePage = () =>
+ assertPageNavigationCompletedSafely({
+ cdpUrl: opts.cdpUrl,
+ targetId: opts.targetId,
+ page,
+ response: null,
+ ssrfPolicy: opts.ssrfPolicy,
+ browserProxyMode: opts.browserProxyMode,
+ });
+ try {
+ signal.throwIfAborted();
+ await bounded(validatePage());
+ // A modal can also delay CDP detach. Return its actionable state promptly;
+ // the scoped helper still completes cleanup when Chrome resumes commands.
+ const observed = await bounded(
+ withPageScopedCdpClient({
+ cdpUrl: opts.cdpUrl,
+ targetId: opts.targetId,
+ page,
+ fn: async (rawSend) => {
+ const send = (method: string, params?: Record<string, unknown>) => {
+ signal.throwIfAborted();
+ return bounded(rawSend(method, params));
+ };
+ const tree = (await send("Page.getFrameTree")) as {
+ frameTree: { frame: { id: string; loaderId: string } };
+ };
+ const world = (await send("Page.createIsolatedWorld", {
+ frameId: tree.frameTree.frame.id,
+ worldName: "cindy-dom-read",
+ })) as { executionContextId: number };
+ signal.throwIfAborted();
+ const result = (await send("Runtime.evaluate", {
+ contextId: world.executionContextId,
+ expression: `(() => ({ url: location.href, value: (${source})() }))()`,
+ returnByValue: true,
+ timeout: timeoutMs,
+ })) as {
+ exceptionDetails?: unknown;
+ result: { value?: { url: string; value: unknown } };
+ };
+ if (result.exceptionDetails || !result.result.value)
+ throw new Error("DOM read failed; observe the page again.");
+ await bounded(validatePage());
+ const current = (await send("Page.getFrameTree")) as typeof tree;
+ if (
+ current.frameTree.frame.id !== tree.frameTree.frame.id ||
+ current.frameTree.frame.loaderId !== tree.frameTree.frame.loaderId
+ ) {
+ throw new Error(
+ "PAGE_CHANGED: the document changed during the DOM read.",
+ );
+ }
+ return result.result.value;
+ },
+ }),
+ );
+ signal.throwIfAborted();
+ if (page.url() !== observed.url)
+ throw new Error("PAGE_CHANGED: the page navigated during the DOM read.");
+ return observed;
+ } catch (error) {
+ if (isBrowserObservedDialogBlockedError(error)) {
+ return { blockedByDialog: true, browserState: error.browserState };
+ }
+ throw error;
+ } finally {
+ clearTimeout(timer);
+ signal.removeEventListener("abort", onAbort!);
+ dialog.cleanup();
+ }
+}
diff --git a/packages/browser-control-runtime/src/types.ts b/packages/browser-control-runtime/src/types.ts
index 3c84a82893..4d63ab923d 100644
--- a/packages/browser-control-runtime/src/types.ts
+++ b/packages/browser-control-runtime/src/types.ts
@@ -95,6 +95,8 @@ export interface BrowserActRequest {
textGone?: string;
timeoutMs?: number;
fn?: string;
+ /** Host-built structured read. Runtimes without this optimization use fn. */
+ domRead?: import('./dom-read.js').BrowserDomRead;
}
export interface BrowserControlRequest {
diff --git a/packages/browser-control-runtime/upstream/MAINTAINING.md b/packages/browser-control-runtime/upstream/MAINTAINING.md
index 8f4030d9f9..a745e78b85 100644
--- a/packages/browser-control-runtime/upstream/MAINTAINING.md
+++ b/packages/browser-control-runtime/upstream/MAINTAINING.md
@@ -179,7 +179,7 @@ pnpm --filter @cindy/browser-control-runtime test # 契约 + SSRF guard
- **实际页面对照**:`scripts/browser-live-history-compare.mjs` 按 `--source-root` 加载指定 checkout 的真实 MCP/runtime,用 attach-only 连接已授权的 Cindy 专用浏览器,不启停 Chrome 或复制登录态。页面计划中的 role/name/href/selector 必须来自当次侦察;每步校验 URL 与实际业务信息,加载未完成的等待和补读计入指标。登录、重置起始页面、独立 alias 探测不计入流程;原始步骤与结果落到显式 `--out` 路径。只用于已授权的只读导航,不把线上提交、上传或发布塞进比较计划。
- **`requests` / `responseBody`(L1 runtime)**:接的是 vendored **已存在但原先没接线**的两条路由(`GET /requests`、`POST /response/body`,见 `_generated/.../pw-tools-core.activity.ts` / `pw-tools-core.responses.ts`)。runtime 复用 per-page 自动捕获缓冲(上限 500、page 关闭自动清),`runtime.ts` 的 `planDispatch` 加两个 case 即可,无新监听、无泄漏。语义:很多页面背后是 JSON API,读接口比扒 DOM 又稳又省。`responseBody` 在 chrome-mcp 接管态返 501,但默认 managed profile 不触发。
-- **`extract`(L2 MCP,`extract.ts`)**:纯组合现有 `act:evaluate`。`buildExtractFnSource(spec)` 是**纯函数**,把字段 schema 编译成注入 JS(选择器一律 `JSON.stringify` 注入,防注入),handler 改写成 `act:{kind:'evaluate',fn}`。不碰 runtime 包。**报错教模型(对齐上游 `SELECTOR_UNSUPPORTED_MESSAGE` 范式)**:生成的 fn 给 `querySelector` 包 try/catch,非法选择器 → 返回 `{ok:false, error, hint}`(`EXTRACT_FIELD_HINT` 教正确字段格式);handler 跑前用 `collectSelectors` 预检 selector 含 `@`(观察到模型爱写 `h3 a@title`)→ 直接返回教学报错,不空跑。**不加 `@attr` 语法糖**(上游无此约定)。
+- **`extract`(L2 MCP,`extract.ts`)**:字段契约和纯函数 `buildExtractFnSource(spec)` 由 runtime 的 `dom-read.ts` 共享,选择器一律经 `JSON.stringify` 注入。直接 extract 和快照后的固定登录墙检测携带内部 `domRead` 结构;CDP 路径在隔离世界执行固定读取,避免网页改写 DOM 方法产生副作用,省去通用交互的 250 ms 延迟。仍检查 evaluate 开关、读取前后导航策略和页面 URL,不授予跨域访问。任意调用方 `fn` 不参与此路径;普通 evaluate、点击和含 guard 的配方保持原守卫。旧 runtime、嵌入式和 chrome-mcp 后端继续执行同时传入的 `fn`,没有新增模型可用的只读标志或工具 action。非法选择器仍返回 `{ok:false, error, hint}`,MCP 预检含 `@` 的误用并提示正确格式,不加 `@attr` 语法糖。隔离世界、登录 iframe 和守卫的真实 Chrome 回归:`node --import tsx scripts/browser-dom-read-live-check.mjs`,另加 `--evaluate-disabled` 验证关闭执行时仍拒绝读取。
- **`recipe` / `siteguide`(L2 MCP)**:`recipe-loader.ts`(`parseRecipes`/`parseSiteGuides` 纯函数 + `loadRecipes`/`loadSiteGuides` 用 `import.meta.glob('./recipes/*/{recipe,siteguide}.json',{query:'?raw',eager:true})` 打包)+ `recipe-runner.ts`(`runRecipe(recipe,inputs,{call})` 纯执行器,注入 `call` 可单测)。数据在 `packages/lizi-mcps/src/browser/recipes/<site>/`。**交互步(click/type/select)直接用稳定 CSS `selector`**——vendored `act` 对 `SELECTOR_ALLOWED_KINDS`(click/type/select/hover/wait)支持 selector 直传,**无需 snapshot→ref**,所以配方不写死 ref、跨会话不腐烂(`fill` 是 ref-only,配方用 `type` 输入文本)。registry 懒加载(首次 recipe/siteguide 调用才解析,坏配方不拖垮整个工具)。`siteguide` **按需 action 拉取**,不进常驻 rules,保持缓存前缀小。**命名 `siteguide` 而非 `sitemap`**:避免和网站自己的 `/sitemap.xml` 撞概念(实测中模型会把 `sitemap` 误解成去抓 sitemap.xml)。
- **配方分层 + 自我成长(L1 内置 + L2 用户,rule 20)**:配方/指南是"可成长"的——内置 L1(随 app 版本发布)+ 用户本地 L2(`userData/browser-recipes/<site>/`)按 **recipe id / siteguide site 整条覆盖**合并,provenance 三态 `builtin`/`user`/`overridden`(`recipe-loader.ts` 的纯函数 `mergeRecipes`/`mergeSiteGuides`)。**恢复默认 = 删 L2 该站文件**(回落 L1,不写快照)。
- **解耦**:`@cindy/mcps` 不碰 fs/electron;host 经 `BrowserMcpDeps.getUserRecipes?`(读)/`saveUserRecipe?`(写)注入。host 侧在 `apps/desktop/src/main/browser-recipes/{loader,writer}.ts`(蓝本 `local-themes/{loader,writer}`),loader 扫盘 + 调 @cindy/mcps `parseRecipes` + 算 `version` 内容指纹。
@@ -197,6 +197,12 @@ pnpm --filter @cindy/browser-control-runtime test # 契约 + SSRF guard
> 加新 action 改了 `browser` 工具 schema → 会话启动一次性注册(`maker-core/.../claude-code/index.ts:713`),一次性失效缓存前缀、稳态不降;按规则 10 实测。新增 action 要两端同步:runtime `types.ts` 的 `BrowserControlAction` ⇄ `tools.ts` 的 `ACTIONS`(exhaustive switch 会强制对齐)。
+### 固定 DOM 读取的生命周期边界(2026-10-27)
+
+- 读取沿用已有弹窗中断信号,并给 CDP 命令设置总时限。弹窗期间 Chrome 可能暂停 detach:及时返回 `blockedByDialog`,原 scoped session 的 finally 在 Chrome 恢复后完成释放,不新增连接缓存或重试。
+- 读取前后的主 frame `loaderId` 必须一致,防止同网址刷新后返回旧文档的结果;页面 URL 与导航策略检查仍保留。同网址内的动态内容没有通用“已加载”判据,调用方仍需等待真实业务文字或元素。
+- `scripts/browser-dom-read-live-check.mjs` 包含真实弹窗、同网址刷新、慢加载与连续 500 次读取检查。资源样本在垃圾回收后读取页面 JS heap、命名隔离世界数量和 CDP session 释放情况;不等同于长时间整进程内存保证。
+
### 配方按使用维护与等待条件(2026-10-23)
- `recipe` 支持 `site + recipeDraft` 内存试跑;`saveRecipe` 仅接受同一 MCP 会话已通过验证的相同内容。正常检查不请求模型,不定时后台刷新;失败交给当前任务模型观察、同 id 一轮修订,失败回普通操作。修复预算为会话内状态,MCP 会话重建后重新计数;暂停状态写进配方,跨重启保留。
diff --git a/packages/browser-control-runtime/upstream/browser-runtime.lock.json b/packages/browser-control-runtime/upstream/browser-runtime.lock.json
index 6f233db946..c09ad06ca6 100644
--- a/packages/browser-control-runtime/upstream/browser-runtime.lock.json
+++ b/packages/browser-control-runtime/upstream/browser-runtime.lock.json
@@ -90,6 +90,10 @@
"file": "extension/src/browser/routes/agent.act.hooks.ts",
"desc": "apply the effective browser proxy mode to direct input file uploads"
},
+ {
+ "file": "extension/src/browser/routes/agent.act.ts",
+ "desc": "execute fixed structured DOM reads in an isolated world without the interaction grace delay"
+ },
{
"file": "extension/src/browser/routes/agent.act.ts",
"desc": "resolve the selected tab alias before comparing or executing action targets"
@@ -120,7 +124,7 @@
}
],
"fileCount": 335,
- "contentHash": "0e13e4827f1eea59d796bb5727e1775aac55b5066f98fe204458801fba1f6171",
+ "contentHash": "1e5b9ed7f2156b726934dd3f3fd1f2c306129d12dc25bdd1471b2e233e390d24",
"fsSafe": {
"package": "@openclaw/fs-safe",
"version": "0.4.0"
diff --git a/packages/lizi-mcps/src/browser/browserMcpServer.test.ts b/packages/lizi-mcps/src/browser/browserMcpServer.test.ts
index ad9db0da97..f474643cd9 100644
--- a/packages/lizi-mcps/src/browser/browserMcpServer.test.ts
+++ b/packages/lizi-mcps/src/browser/browserMcpServer.test.ts
@@ -482,7 +482,7 @@ describe('createBrowserMcpServer', () => {
await h.cleanup();
});
- it('compiles extract into an act:evaluate call', async () => {
+ it('sends a structured DOM read with an evaluate fallback for other runtimes', async () => {
const h = await makeHarness();
await h.client.callTool({
name: 'call_tool',
@@ -501,6 +501,9 @@ describe('createBrowserMcpServer', () => {
expect(call.action).toBe('act');
expect(call.targetId).toBe('t1');
expect(call.request?.kind).toBe('evaluate');
+ expect(call.request).toMatchObject({ domRead: { kind: 'extract',
+ extract: { from: '.book', multiple: true, fields: { title: 'h3', price: '.price_color' } },
+ } });
// The compiled fn carries the field schema and is a function source.
expect(call.request?.fn).toContain('querySelectorAll');
expect(call.request?.fn).toContain('.book');
@@ -1130,7 +1133,8 @@ describe('createBrowserMcpServer', () => {
expect(parsed.loginWall).toBeUndefined();
}
// The check runs on the tab the snapshot came from.
- expect(h.calls[1]).toMatchObject({ action: 'act', targetId: 't9', request: { kind: 'evaluate' } });
+ expect(h.calls[1]).toMatchObject({ action: 'act', targetId: 't9',
+ request: { kind: 'evaluate', domRead: { kind: 'login-wall' } } });
await h.cleanup();
});
diff --git a/packages/lizi-mcps/src/browser/extract.ts b/packages/lizi-mcps/src/browser/extract.ts
index cabec99546..9c56eb93a3 100644
--- a/packages/lizi-mcps/src/browser/extract.ts
+++ b/packages/lizi-mcps/src/browser/extract.ts
@@ -1,152 +1,5 @@
-/**
- * `extract` — structured DOM extraction, compiled to a single injected JS
- * function that runs via the existing `act:evaluate` primitive (no new runtime
- * capability needed). Pulling just the fields you need is far cheaper than a
- * full-page snapshot + letting the model hunt for them in thousands of nodes.
- *
- * `buildExtractFnSource()` is a PURE function (spec → JS source string) so it is
- * unit-testable without a browser. All selectors/attrs are injected via
- * `JSON.stringify` (never string-concatenated) to avoid breaking out of the
- * generated source.
- */
-
-import { z } from 'zod';
-
-/** Reusable zod schema for an extract spec — shared by the `browser` tool input
- * and recipe `extract` steps so the two never drift. */
-export const ExtractSpecSchema = z.object({
- from: z.string().optional(),
- multiple: z.boolean().optional(),
- fields: z.record(
- z.string(),
- z.union([
- z.string(),
- z.object({
- selector: z.string().optional(),
- attr: z.string().optional(),
- type: z.enum(['text', 'html', 'attr', 'href']).optional(),
- }),
- ]),
- ),
- limit: z.number().int().positive().optional(),
-});
-
-/** A field is either a CSS selector shorthand (→ trimmed textContent) or a spec. */
-export type ExtractFieldSpec =
- | string
- | {
- /** CSS selector relative to the record container; omit = the container itself. */
- selector?: string;
- /** Attribute name (implies type 'attr' unless `type` says otherwise). */
- attr?: string;
- /** How to read the resolved element. Default 'text'. */
- type?: 'text' | 'html' | 'attr' | 'href';
- };
-
-export interface ExtractSpec {
- /** Container selector. With `multiple`, one record per match; else a single record. Omit = whole document. */
- from?: string;
- /** querySelectorAll over `from` → one record each. */
- multiple?: boolean;
- /** Field name → how to extract it. */
- fields: Record<string, ExtractFieldSpec>;
- /** Cap the number of records (only meaningful with `multiple`). */
- limit?: number;
-}
-
-interface NormalizedField {
- selector?: string;
- attr?: string;
- type: 'text' | 'html' | 'attr' | 'href';
-}
-
-/**
- * Agent-facing teaching hint embedded in the extract result when a selector is
- * invalid — mirrors the upstream "teach via error" idiom (SELECTOR_UNSUPPORTED_MESSAGE):
- * the error itself shows the correct usage so the model self-corrects.
- */
-export const EXTRACT_FIELD_HINT =
- 'fields 的简写 string 是**纯 CSS 选择器**(取该元素 textContent);' +
- '要取属性用对象形式 {selector:"h3 a", attr:"title"};取链接用 {selector:"a", type:"href"}。' +
- '不要把属性名拼进选择器(如 "h3 a@title" 非法),也不要写自然语言。' +
- '不确定真实结构时,先用 snapshot(可带 selector 收窄)看 DOM,再据此写 extract 的选择器。';
-
-/** All selector strings referenced by a spec (`from` + each field's selector). */
-export function collectSelectors(spec: ExtractSpec): string[] {
- const out: string[] = [];
- if (spec.from) out.push(spec.from);
- for (const f of Object.values(spec.fields)) {
- if (typeof f === 'string') out.push(f);
- else if (f.selector) out.push(f.selector);
- }
- return out;
-}
-
-/** Expand field shorthands to a uniform `{selector, attr, type}` shape. */
-function normalizeFields(fields: Record<string, ExtractFieldSpec>): Record<string, NormalizedField> {
- const out: Record<string, NormalizedField> = {};
- for (const [name, f] of Object.entries(fields)) {
- if (typeof f === 'string') {
- out[name] = { selector: f, type: 'text' };
- } else {
- out[name] = {
- selector: f.selector,
- attr: f.attr,
- type: f.type ?? (f.attr ? 'attr' : 'text'),
- };
- }
- }
- return out;
-}
-
-/**
- * Compile an extract spec into a zero-arg JS function source string suitable for
- * `act:evaluate`. The function runs in page context and returns
- * `{ ok: true, count, records }`.
- */
-export function buildExtractFnSource(spec: ExtractSpec): string {
- const normalized = {
- from: spec.from,
- multiple: Boolean(spec.multiple),
- limit: spec.limit,
- fields: normalizeFields(spec.fields),
- };
- // The whole spec + hint are embedded as JSON literals — selectors/attrs are
- // data, not code, so there is no injection surface.
- const specLiteral = JSON.stringify(normalized);
- const hintLiteral = JSON.stringify(EXTRACT_FIELD_HINT);
- // querySelector is guarded: an invalid selector (e.g. natural language, or the
- // "h3 a@title" attr-in-selector mistake) is collected into `bad` and reported
- // as ok:false + hint, instead of throwing and killing the whole extract.
- return `() => {
- const SPEC = ${specLiteral};
- const HINT = ${hintLiteral};
- const bad = [];
- const qOne = (root, s) => { try { return root.querySelector(s); } catch (e) { bad.push(s); return null; } };
- const qAll = (root, s) => { try { return Array.from(root.querySelectorAll(s)); } catch (e) { bad.push(s); return []; } };
- const containers = SPEC.from
- ? (SPEC.multiple ? qAll(document, SPEC.from) : [qOne(document, SPEC.from)].filter(Boolean))
- : [document];
- const limited = SPEC.limit ? containers.slice(0, SPEC.limit) : containers;
- const pick = (container, f) => {
- const el = f.selector ? qOne(container, f.selector) : container;
- if (!el) return null;
- if (f.type === 'html') return el.innerHTML;
- if (f.type === 'href') {
- const h = el.getAttribute('href');
- try { return h == null ? null : new URL(h, location.href).href; } catch (_e) { return h; }
- }
- if (f.type === 'attr') return f.attr ? el.getAttribute(f.attr) : null;
- return (el.textContent || '').trim();
- };
- const records = limited.map((container) => {
- const rec = {};
- for (const name of Object.keys(SPEC.fields)) rec[name] = pick(container, SPEC.fields[name]);
- return rec;
- });
- if (bad.length) {
- return { ok: false, error: 'invalid CSS selector(s): ' + Array.from(new Set(bad)).join(', '), hint: HINT, count: records.length, records };
- }
- return { ok: true, count: records.length, records };
-}`;
-}
+// One contract for isolated reads and guarded compatibility execution.
+export {
+ buildExtractFnSource, collectSelectors, EXTRACT_FIELD_HINT, ExtractSpecSchema,
+ type ExtractFieldSpec, type ExtractSpec,
+} from '@cindy/browser-control-runtime/dom-read';
diff --git a/packages/lizi-mcps/src/browser/tools.ts b/packages/lizi-mcps/src/browser/tools.ts
index 3357b6c04e..abf9a28414 100644
--- a/packages/lizi-mcps/src/browser/tools.ts
+++ b/packages/lizi-mcps/src/browser/tools.ts
@@ -6,6 +6,7 @@ import {
type BrowserControlRuntime,
} from '@cindy/browser-control-runtime';
import { z } from 'zod';
+import { LOGIN_WALL_FN } from '@cindy/browser-control-runtime/dom-read';
import {
INLINE_IMAGE_TARGET_BYTES,
@@ -209,25 +210,13 @@ const MAX_RESULT_BYTES = 200_000;
* owner should fill it from their own device. A cheap DOM check after a
* snapshot; any failure means no hint.
*/
-const LOGIN_WALL_FN = `() => {
- const docs = [document];
- for (const frame of document.querySelectorAll('iframe')) {
- try { if (frame.contentDocument) docs.push(frame.contentDocument); } catch {}
- }
- const has = (selector) => docs.some((doc) => doc.querySelector(selector));
- return {
- password: !!has('input[type=password]'),
- code: !!has('input[autocomplete="one-time-code"]'),
- };
-}`;
-
async function detectLoginWall(runtime: BrowserControlRuntime, profile: unknown, targetId: unknown) {
try {
const checked = await runtime.call({
action: 'act',
...(typeof profile === 'string' ? { profile } : {}),
...(typeof targetId === 'string' ? { targetId } : {}),
- request: { kind: 'evaluate', fn: LOGIN_WALL_FN, timeoutMs: 2000 },
+ request: { kind: 'evaluate', fn: LOGIN_WALL_FN, domRead: { kind: 'login-wall' }, timeoutMs: 2000 },
} as BrowserControlRequest);
const found = (checked.data as { result?: { password?: unknown; code?: unknown } } | undefined)?.result;
if (!checked.ok || (found?.password !== true && found?.code !== true)) return null;
@@ -1006,8 +995,8 @@ export function registerBrowserTools(registry: BrowserToolRegistry, deps: Browse
let result;
if (args.action === 'extract') {
- // `extract` is composition over the existing `evaluate` primitive:
- // compile the field schema to an injected fn and run it on the page.
+ // Supply the fixed read spec for the runtime's isolated DOM reader,
+ // plus the generated fn for backends using the legacy evaluate path.
if (!args.extract) {
return errorResult('extract', 'extract requires an `extract` spec ({ from?, multiple?, fields, limit? })');
}
@@ -1037,6 +1026,7 @@ export function registerBrowserTools(registry: BrowserToolRegistry, deps: Browse
request: {
kind: 'evaluate',
fn: buildExtractFnSource(spec),
+ domRead: { kind: 'extract', extract: spec },
...(args.timeoutMs ? { timeoutMs: args.timeoutMs } : {}),
},
} as BrowserControlRequest);
diff --git a/scripts/browser-dom-read-live-check.mjs b/scripts/browser-dom-read-live-check.mjs
new file mode 100644
index 0000000000..e789c776a4
--- /dev/null
+++ b/scripts/browser-dom-read-live-check.mjs
@@ -0,0 +1,403 @@
+/** Integration tier: real Chrome verifies the read optimization against page
+ * prototype overrides, same-origin/cross-origin login frames and the unchanged
+ * evaluate guard. Uses only synthetic pages in a disposable browser profile.
+ * Run: node --import tsx scripts/browser-dom-read-live-check.mjs */
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import http from "node:http";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+
+const tempRoot = await fs.mkdtemp(
+ path.join(os.tmpdir(), "cindy-dom-read-check-"),
+);
+const evaluateDisabled = process.argv.includes("--evaluate-disabled");
+process.env.XDT_BROWSER_RUNTIME_DIR = tempRoot;
+const listen = (server) =>
+ new Promise((resolve) =>
+ server.listen(0, "127.0.0.1", () => resolve(server.address().port)),
+ );
+const close = (server) => new Promise((resolve) => server.close(resolve));
+const reserve = net.createServer();
+const cdpPort = await listen(reserve);
+await close(reserve);
+const cross = http.createServer((_req, res) =>
+ res.end('<input type="password">'),
+);
+const crossPort = await listen(cross);
+let releaseData;
+let dataArrived;
+const dataRequested = new Promise((resolve) => {
+ dataArrived = resolve;
+});
+const server = http.createServer((req, res) => {
+ res.setHeader("Content-Type", "text/html; charset=utf-8");
+ if (req.url === "/data") {
+ releaseData = () => res.end("ready");
+ dataArrived();
+ return;
+ }
+ if (req.url === "/dynamic")
+ return res.end(`<main id="status">loading</main><script>
+ fetch('/data').then(r => r.text()).then(text => document.getElementById('status').textContent = text);
+ </script>`);
+ if (req.url === "/code")
+ return res.end('<input autocomplete="one-time-code">');
+ res.end(`<main><article><b title="read-title">Read result</b><a href="/next">Link</a></article></main>
+ ${req.url === "/password" ? '<input type="password">' : ""}
+ ${req.url === "/frames" ? '<iframe src="/code"></iframe>' : ""}
+ <iframe src="http://127.0.0.1:${crossPort}/"></iframe>
+ <script>
+ window.pageHookCalls = 0;
+ Document.prototype.querySelector = Document.prototype.querySelectorAll = function () {
+ window.pageHookCalls++; throw new Error('page hook must not run during a fixed read');
+ };
+ Object.defineProperty(Node.prototype, 'textContent', { get() {
+ window.pageHookCalls++; return 'page-controlled getter';
+ } });
+ </script>`);
+});
+const port = await listen(server);
+const base = `http://127.0.0.1:${port}`;
+const { createBrowserControlRuntime } =
+ await import("../packages/browser-control-runtime/src/runtime.ts");
+const { BrowserToolRegistry } =
+ await import("../packages/lizi-mcps/src/browser/tool-registry.ts");
+const { registerBrowserTools } =
+ await import("../packages/lizi-mcps/src/browser/tools.ts");
+const { LOGIN_WALL_FN } =
+ await import("../packages/browser-control-runtime/src/dom-read.ts");
+const { getPageForTargetId, respondToObservedDialogOnPage } =
+ await import("../packages/browser-control-runtime/src/_generated/extension/src/browser/pw-session.ts");
+const config = {
+ browser: {
+ enabled: true,
+ headless: true,
+ evaluateEnabled: !evaluateDisabled,
+ defaultProfile: "dom-read-check",
+ profiles: { "dom-read-check": { cdpPort, color: "#00D9C5" } },
+ ssrfPolicy: { dangerouslyAllowPrivateNetwork: true },
+ },
+};
+const runtime = createBrowserControlRuntime({ config, logSink: () => {} });
+const registry = new BrowserToolRegistry();
+registerBrowserTools(registry, {
+ getRuntime: () => runtime,
+ supportsSemanticQueries: () => false,
+});
+let targetId;
+const call = async (args) => {
+ const response = await registry.call("browser", { targetId, ...args });
+ const result = JSON.parse(
+ response.content
+ .filter((x) => x.type === "text")
+ .map((x) => x.text)
+ .join(""),
+ );
+ assert.equal(result.ok, true, JSON.stringify(result));
+ return result;
+};
+const timeout = globalThis.setTimeout;
+let navigationGraceTimers = 0;
+globalThis.setTimeout = function (fn, ms, ...args) {
+ if (
+ ms === 250 &&
+ new Error().stack.includes("scheduleDelayedInteractionNavigationGuard")
+ )
+ navigationGraceTimers++;
+ return timeout(fn, ms, ...args);
+};
+try {
+ assert.equal((await runtime.call({ action: "start" })).ok, true);
+ const opened = await runtime.call({ action: "open", url: base + "/frames" });
+ assert.equal(opened.ok, true);
+ targetId = opened.data.targetId;
+ if (!evaluateDisabled) {
+ await call({ action: "act", request: { kind: "wait", loadState: "load" } });
+ const priorTimers = navigationGraceTimers;
+ const extracted = await call({
+ action: "extract",
+ extract: {
+ from: "article",
+ multiple: true,
+ fields: {
+ text: "b",
+ title: { selector: "b", attr: "title" },
+ html: { selector: "b", type: "html" },
+ href: { selector: "a", type: "href" },
+ },
+ },
+ });
+ assert.deepEqual(extracted.data.result.records, [
+ {
+ text: "Read result",
+ title: "read-title",
+ html: "Read result",
+ href: base + "/next",
+ },
+ ]);
+ const snapshot = await call({
+ action: "snapshot",
+ refs: "role",
+ selector: "main",
+ });
+ assert.deepEqual(snapshot.loginWall.fields, ["one-time-code"]);
+ assert.equal(
+ navigationGraceTimers,
+ priorTimers,
+ "fixed reads entered the interaction grace window",
+ );
+ const tampered = await runtime.call({
+ action: "act",
+ targetId,
+ request: {
+ kind: "evaluate",
+ fn: '() => { window.pageHookCalls++; return "unexpected code"; }',
+ domRead: { kind: "login-wall" },
+ },
+ });
+ assert.deepEqual(tampered.data.result, { password: false, code: true });
+ const inspected = await call({
+ action: "act",
+ request: { kind: "evaluate", fn: "() => window.pageHookCalls" },
+ });
+ assert.equal(inspected.data.result, 0);
+ assert.ok(
+ navigationGraceTimers > priorTimers,
+ "general evaluate lost its navigation guard",
+ );
+ for (const [page, fields] of [
+ ["/password", ["password"]],
+ ["/cross-only", undefined],
+ ]) {
+ await call({ action: "navigate", url: base + page });
+ const observed = await call({
+ action: "snapshot",
+ refs: "role",
+ selector: "main",
+ });
+ assert.deepEqual(observed.loginWall?.fields, fields);
+ }
+ // Integration regression: a modal appearing during the read must return
+ // blockedByDialog, rather than leave a protocol command pending behind it.
+ const page = await getPageForTargetId({
+ cdpUrl: `http://127.0.0.1:${cdpPort}`,
+ targetId,
+ });
+ const modalContext = page.context();
+ const beforeModalSession = modalContext.newCDPSession.bind(modalContext);
+ const modalDetaches = [];
+ let dialog, alertDone;
+ modalContext.newCDPSession = async (...args) => {
+ const session = await beforeModalSession(...args),
+ send = session.send.bind(session);
+ const detach = session.detach.bind(session);
+ session.detach = () => {
+ const pending = detach();
+ modalDetaches.push(pending);
+ return pending;
+ };
+ session.send = async (method, params) => {
+ const result = await send(method, params);
+ if (method === "Page.getFrameTree" && !dialog) {
+ const shown = page.waitForEvent("dialog");
+ alertDone = page
+ .evaluate(() => alert("read regression"))
+ .catch(() => {});
+ dialog = await shown;
+ }
+ return result;
+ };
+ return session;
+ };
+ let deadline;
+ try {
+ const reading = runtime.call({
+ action: "act",
+ targetId,
+ request: {
+ kind: "evaluate",
+ fn: LOGIN_WALL_FN,
+ domRead: { kind: "login-wall" },
+ timeoutMs: 500,
+ },
+ });
+ const response = await Promise.race([
+ reading,
+ new Promise((_, reject) => {
+ deadline = timeout(
+ () => reject(new Error("DOM read hung behind modal")),
+ 3000,
+ );
+ }),
+ ]);
+ assert.equal(
+ response.data?.blockedByDialog,
+ true,
+ JSON.stringify(response),
+ );
+ } finally {
+ clearTimeout(deadline);
+ modalContext.newCDPSession = beforeModalSession;
+ if (dialog) await respondToObservedDialogOnPage({ page, accept: false });
+ await alertDone;
+ await Promise.all(modalDetaches);
+ }
+ // Same-URL SPA content still requires its business readiness condition.
+ await call({ action: "navigate", url: base + "/dynamic" });
+ await dataRequested;
+ const statusSpec = { fields: { status: "#status" } };
+ assert.equal(
+ (await call({ action: "extract", extract: statusSpec })).data.result
+ .records[0].status,
+ "loading",
+ );
+ releaseData();
+ await call({
+ action: "act",
+ request: {
+ kind: "wait",
+ fn: "() => document.getElementById('status').textContent === 'ready'",
+ timeoutMs: 3000,
+ },
+ });
+ assert.equal(
+ (await call({ action: "extract", extract: statusSpec })).data.result
+ .records[0].status,
+ "ready",
+ );
+ await call({ action: "navigate", url: base + "/cross-only" });
+
+ // Count actual sessions and execution contexts on this disposable page.
+ const context = page.context();
+ const originalSession = context.newCDPSession.bind(context);
+ const observer = await originalSession(page);
+ const worlds = new Set();
+ observer.on("Runtime.executionContextCreated", ({ context }) => {
+ if (context.name === "cindy-dom-read") worlds.add(context.id);
+ });
+ observer.on("Runtime.executionContextDestroyed", ({ executionContextId }) =>
+ worlds.delete(executionContextId),
+ );
+ observer.on("Runtime.executionContextsCleared", () => worlds.clear());
+ await observer.send("Runtime.enable");
+ let active = 0,
+ peak = 0,
+ openedSessions = 0,
+ replaceAfterRead = false;
+ context.newCDPSession = async (...args) => {
+ const session = await originalSession(...args);
+ active++;
+ openedSessions++;
+ peak = Math.max(peak, active);
+ const detach = session.detach.bind(session),
+ send = session.send.bind(session);
+ session.detach = async () => {
+ try {
+ await detach();
+ } finally {
+ active--;
+ }
+ };
+ session.send = async (method, params) => {
+ const result = await send(method, params);
+ if (replaceAfterRead && method === "Runtime.evaluate") {
+ replaceAfterRead = false;
+ await page.reload({ waitUntil: "load" });
+ }
+ return result;
+ };
+ return session;
+ };
+ const resourceSamples = [];
+ try {
+ // Force a real reload after evaluation but before result validation.
+ replaceAfterRead = true;
+ const stale = await registry.call("browser", {
+ targetId,
+ action: "extract",
+ extract: { fields: { text: "b" } },
+ });
+ assert.equal(stale.isError, true);
+ assert.match(JSON.stringify(stale), /PAGE_CHANGED/);
+ assert.equal(active, 0);
+ const sample = async (reads) => {
+ await observer.send("HeapProfiler.collectGarbage");
+ const heap = await observer.send("Runtime.getHeapUsage");
+ resourceSamples.push({
+ reads,
+ active,
+ worlds: worlds.size,
+ heapUsed: heap.usedSize,
+ });
+ };
+ for (let i = 0; i < 510; i++) {
+ const read = await call({
+ action: "extract",
+ extract: { fields: { text: "b" } },
+ });
+ assert.equal(read.data.result.records[0].text, "Read result");
+ assert.equal(active, 0, "read left an attached CDP session");
+ if (i === 9 || ((i + 1 - 10) % 100 === 0 && i >= 10))
+ await sample(i + 1 - 10);
+ }
+ assert.ok(
+ resourceSamples.every(
+ (row) => row.worlds === resourceSamples[0].worlds,
+ ),
+ "isolated contexts accumulated",
+ );
+ assert.ok(
+ resourceSamples.at(-1).heapUsed <
+ resourceSamples[0].heapUsed + 2_000_000,
+ "retained page heap grew by over 2 MB",
+ );
+ console.log(
+ JSON.stringify({ resourceSamples, openedSessions, peak, active }),
+ );
+ } finally {
+ context.newCDPSession = originalSession;
+ await observer.detach();
+ }
+ console.log(
+ JSON.stringify({
+ ok: true,
+ checks: [
+ "text/attribute/html/href extraction",
+ "page prototype isolation",
+ "same-origin code detection",
+ "cross-origin frame exclusion",
+ "password detection",
+ "no arbitrary fn on read path",
+ "general evaluate retains grace",
+ "modal read returns blockedByDialog",
+ "same-URL delayed content requires business wait",
+ "same-URL reload rejects stale result",
+ "500 repeated reads release sessions and reuse isolated world",
+ ],
+ navigationGraceTimers,
+ }),
+ );
+ } else {
+ const denied = await runtime.call({
+ action: "act",
+ targetId,
+ request: {
+ kind: "evaluate",
+ fn: LOGIN_WALL_FN,
+ domRead: { kind: "login-wall" },
+ },
+ });
+ assert.equal(denied.ok, false);
+ assert.equal(denied.status, 403);
+ console.log(
+ JSON.stringify({ ok: true, checks: ["evaluate-disabled gate retained"] }),
+ );
+ }
+} finally {
+ globalThis.setTimeout = timeout;
+ await runtime.call({ action: "stop" });
+ await Promise.all([close(server), close(cross)]);
+ await fs.rm(tempRoot, { recursive: true, force: true });
+}
diff --git a/scripts/browser-runtime/sync.mjs b/scripts/browser-runtime/sync.mjs
index 5010905f89..8746c07a9e 100644
--- a/scripts/browser-runtime/sync.mjs
+++ b/scripts/browser-runtime/sync.mjs
@@ -291,6 +291,39 @@ const LOCAL_PATCHES = {
},
],
'extension/src/browser/routes/agent.act.ts': [
+ {
+ desc: 'execute fixed structured DOM reads in an isolated world without the interaction grace delay',
+ transform: (source) => applyExactReplacements(source, [
+ [
+ `import { normalizeActRequest, validateBatchTargetIds } from "./agent.act.normalize.js";`,
+ `import { normalizeActRequest, validateBatchTargetIds } from "./agent.act.normalize.js";
+import { readBrowserDom } from "../../../../../shim/browser-dom-read.js";`,
+ ],
+ [
+ ` const profileName = profileCtx.profile.name;
+ if (isExistingSession) {`,
+ ` // Only structured host reads enter this path. Arbitrary fn is
+ // ignored here, never trusted as a promise of read-only behavior.
+ if (action.kind === "evaluate" && body.domRead !== undefined && !isExistingSession) {
+ if (!evaluateEnabled) {
+ return jsonActError(res, 403, ACT_ERROR_CODES.evaluateDisabled,
+ browserEvaluateDisabledMessage("evaluate"));
+ }
+ const observed = await readBrowserDom({
+ cdpUrl, targetId: tab.targetId, spec: body.domRead,
+ timeoutMs: action.timeoutMs, ssrfPolicy,
+ browserProxyMode: navigationPolicy.browserProxyMode, signal: req.signal,
+ });
+ if ("blockedByDialog" in observed) {
+ return res.json({ ok: true, targetId: tab.targetId, ...observed });
+ }
+ return res.json({ ok: true, targetId: tab.targetId, url: observed.url, result: observed.value });
+ }
+ const profileName = profileCtx.profile.name;
+ if (isExistingSession) {`,
+ ],
+ ]),
+ },
{
desc: 'resolve the selected tab alias before comparing or executing action targets',
transform: (source) => applyExactReplacements(source, [