[earakely-scale]

What and why

The CDP relay from #482 now checks every command an agent sends before it reaches the browser's pipe. M8.17 hands these addresses to agents next. Without a guard, one agent's Browser.close ends the browser for every connection and for the env. An agent could also route its traffic around the site proxy, save downloads outside the env's folder, or open the browser's own pages. This is FD-4954 (M8.7). Its five decisions are recorded there; this PR follows them as decided.

What the guard does (in browser_cdp.guard, a pure function the relay calls per command):

• Ending the browser: Browser.close, Browser.crash and Browser.crashGpuProcess are answered {}. Then that connection alone closes with 1000 (decision 2). To the client it looks like a real close. Its sessions are detached, and the tabs it opened stay open.
• Refused, with a CDP error in Chromium's own shape, {"code": -32000, "message": "agentenv refuses <method>: <why>"} (decision 1). Playwright and Puppeteer raise it with the reason, and the connection stays open.
  • Target.exposeDevToolsProtocol. It gives a page's own script a browser-level CDP channel, which would get around the guard.
  • Target.sendMessageToTarget. It carries a whole command inside its message, where the guard can't see it, and the relay serves flattened sessions only.
  • Target.createBrowserContext with proxyServer or proxyBypassList.
  • Page.navigate and Target.createTarget to the browser's own pages. The URL is read the way the browser reads it: tabs and newlines removed, spaces and controls trimmed from its ends, the scheme in any case.
    • The issue's list: file:, chrome:, chrome-extension:, view-source: and devtools:.
    • Added here: chrome-untrusted:, and about: pages other than about:blank and about:srcdoc, since the browser rewrites about:settings to chrome://settings.
• Downloads pinned (decision 3). Browser.setDownloadBehavior and the older Page.setDownloadBehavior are sent on as agentenv's own setting:
  • behavior: "default", with only the agent's browserContextId and eventsEnabled kept, so files land in ~/Downloads under their real names;
  • the agent's session still gets download events, and no agent changes the shared setting;
  • Playwright's connectOverCDP sets download behavior while connecting (confirmed below), and its call still succeeds.
• Dialogs (decision 4). When the deploy answers dialogs (dialogs: accept or dismiss), an agent's Page.handleJavaScriptDialog is answered {} and not sent on. The deploy's answer is always the one Chromium gets, and the dialog record stays right. With the default, agent, nothing changes.
• The record (decision 5). Each cdp_connections entry gains guarded: the first 100 commands the guard refused, changed, answered or closed it on, each with its method, what agentenv did and when. There's no action-log hook yet. M8.19 adds it together with the action log, its first consumer.

It's a guardrail, not the boundary: the sandbox's network is the boundary. The README's relay section lists all of it.

Also:

• After a connection starts closing, the relay sends none of its further commands on.
• A message that isn't a command the relay can read gets a CDP error with code -32600, instead of no answer. That's an object with a string method, and object params and a string sessionId if any.

Not in this PR:

• the action log (M8.19);
• contexts (M8.15, M8.16);
• code in the computer's session minting a token through the app socket (FD-4922).

Size: 206 lines added, 85 of them tests.

How it was tested

• ruff check: clean.

• Protocol tests: 1057 passed at 831c670. The new ones in test_browser_cdp.py:

  • guard() on a table of commands. https: and about:blank pass, while about:settings, " \tFI\nLE:///…", chrome://settings and View-Source: are refused. A context with proxyBypassList is refused, but one without a proxy is sent. An agent's dialog answer is sent when the deploy leaves dialogs to agents, and Browser.crash closes.
  • Two connections through the relay over a fake pipe:
    • Each refusal comes back with its error. The refused navigation, exposeDevToolsProtocol, the answered dialog and the close never reach the pipe.
    • Both download commands reach the pipe pinned.
    • A dialog answer is answered {} when the deploy answers dialogs.
    • One connection's Browser.close is answered {} and closes only that connection, with 1000. The other connection keeps getting answers.
    • Each connection's guarded entries are checked.

• Real Chrome 156, locally, through the relay and Playwright 1.64.1 and Puppeteer 24.43.1:

  • Playwright stays connected by http_url while Puppeteer, by ws_url, calls browser.close(). That returns cleanly, Chromium stays up, and Playwright then loads the site.
  • Its page.goto("file:///etc/hostname") fails with Protocol error (Page.navigate): agentenv refuses Page.navigate: file: URLs open the browser's own files, settings and tools.
  • Playwright's connection shows Browser.setDownloadBehavior: changed, so connectOverCDP does set download behavior, and the pinned call keeps it working.
  • feat(website-browser): per-user CDP addresses, discovery and a WebSocket relay #482's two-clients check (Playwright and Puppeteer at once, then Playwright by ws_url) still passes through the guard.

• Integration, on agent-environments-admin VMs (amd64 c6i.2xlarge, arm64 c7g.2xlarge): the browser computer's CDP test gains the same guard check. It also checks that the record shows Puppeteer's close, Playwright's refused navigation and its changed download call. The four suites, browser_computer_test.py, computer_app_test.py, chromium_app_test.py and website_browser_test.py, passed 18 of 18 on each arch at dd20437. The guard check passed on both: Puppeteer's close returned cleanly, Chromium stayed up, Playwright loaded the site, and its file: navigation came back refused.

• Review fixes (Greptile, 3/5 on dd20437), at 831c670, each with a test that fails without it:

  • P1: Target.sendMessageToTarget let a wrapped file: navigation past the guard. It's now refused.
  • P2: a command with non-object params, or a non-string method or sessionId, raised in the guard and got no answer. On dd20437 the relay test hangs waiting for it. Such commands, and messages that aren't objects, now get a CDP error with code -32600.

  These change only the relay's command handling, covered by the protocol tests. The VM run is at dd20437.

• CI on 831c670:

  • unit failed in feat(website-browser): per-user CDP addresses, discovery and a WebSocket relay #482's relay test, assert [] == ['Hang']. The relay now sends nothing once a connection starts closing, and on CI the test ended the connection before the relay had read its Hang command, so Hang never reached the pipe. It passed 48 of 48 here even under load. A scratch test that ends the connection before the relay reads Hang reproduces it. 0386620 makes the test wait until Hang is on the pipe.
  • integration-local-slow (4/8) couldn't pull mirror.gcr.io/library/registry:2 to start its local registry, so none of its tests ran.
  • Every check passed on 0386620, and Greptile gives it 5/5.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge.

Summary

The PR adds a guard to the browser’s CDP relay. Since the previous review, only the relay test changed.

• The relay filters commands before they reach the shared browser.
• The browser pins agent downloads to its default folder.
• The deploy decides who answers browser dialogs.
• The relay rejects unreadable commands and ignores commands after closing starts.
• Each browser connection records what the guard did.

_{Reviews (3) · Last reviewed commit: "test: wait for the unanswered command to..." · Reviewed by Greptile}