Repository navigation
feat(browser): a CDP address scoped to one lease (M8.16) - #658
Merged
earakely-scale merged 6 commits intoNov 13, 2026
Merged
earakely-scale merged 6 commits into
earakely-scale merged 6 commits into
Conversation
cdp {user, context?} returns an address scoped to a lease, for a user it's
granted to. A connection to it sees the lease as the browser's default
context: Target events and answers keep only its targets, pages,
cross-origin iframes and workers alike, with the contexts its user made;
commands that act in a context and name none get the lease's, and ones
naming a context or a target it doesn't see are refused, a target as
Chromium answers an unknown one. A target of another context that
auto-attaches to it is told to run and detached, unseen, so nothing it
doesn't see is ever held paused. An address with no context sees the
default context and its user's own contexts, not the leases.
A scoped address lives as long as its lease: its end revokes the address
and closes its connections, saying so. browser_connect_cdp takes a context.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…abel Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…multi env test reads each lease through its own address The driver's /svc WebSocket relay passed a close's code through but dropped its reason, so an agent behind it never heard why: "the lease ended: ask for an address again", or that the browser relaunched. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- A lease that ends while a connection to it attaches closes that connection, saying so, rather than leaving it open on an ended lease. - A download a cross-origin iframe began is its tab's context's: the control keeps each frame attached to a page as that tab's, and the relay falls back to the iframe target's context, so a scoped client hears it. The scoped-address test downloads from the iframe. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…han the lease On a connection scoped to a lease, the browser session refuses the commands that act on every context: Fetch, Tracing and Security, Storage beyond the cookie commands, and the Browser window commands on a window that isn't one of its tabs'. Its own pages' sessions still take them, as Playwright and Puppeteer use them there, and a default address is unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ping rule The rules were split across scope.py, the relay's verdict and event methods, and the guard. Each connection now has a Scope, in scope.py, that holds its state (its lease, its windows, the downloads it doesn't hear of) and answers the relay's three questions: what a command becomes (verdict), what an answer becomes (answer) and whether an event is heard (hears), which hands back a target to let go rather than letting it go itself. The dispose and attachToBrowserTarget refusals moved into it too; discovery asks the same Scope. The relay's map of each target's context is target_contexts, and a connection's map of each session's tab session_tabs, where both were called targets. Behaviour is unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
earakely-scale
deleted the
edgararakelyan/fd-4963-m816-scoping-a-cdp-address-to-one
branch
November 13, 2026 15:34
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What and why
M8.16 (FD-4963): a CDP address scoped to one lease.
M8.15 gave a website browser leased contexts and recorded who each lease is granted to, but every CDP address still saw the whole browser: every lease, every agent's contexts, the task's tabs. Now an agent's address can be scoped to one lease, which it sees as the browser's default context, and only a user the lease is granted to gets one: grants are enforced. Like the rest of the guard, this keeps cooperating agents apart; the sandbox stays the security boundary.
Design note: M8.16: Scoped CDP addresses, settled, decisions 1a, 2a, 3a and 4a.
What changes
cdp {user, origin?, context?}returns an address scoped to the leasecontextnames. A user it isn't granted to is refused (403permission_denied), a label that isn't leased too (404target_unavailable).website_browser/scope.py): its scope, the lease or the default context, plus every context its user made (decision 1). The relay keeps each target's context as Chromium reports it, pages, cross-origin iframes and workers alike.Targetevents (targetCreated,targetInfoChanged,targetDestroyed,targetCrashed,attachedToTarget,detachedFromTarget) andgetTargetskeep only what it sees.getBrowserContextslists only its user's own contexts beside the default, and on a scoped connection reports the lease asdefaultBrowserContextId.attachToTarget,activateTarget,closeTargetandgetTargetInfoon a target it doesn't see are answered as Chromium answers an unknown target.createTarget,Storagecookie commands,Browserpermission commands andsetDownloadBehaviorthat name no context get the lease's; naming a context it doesn't see is refused.Target.attachToBrowserTargetis refused: a second browser session would see past the scope.Fetch,TracingandSecurity,Storagebeyond the cookie commands, andBrowser.setWindowBounds,getWindowBoundsandsetContentsSizeon a window that isn't one of its tabs'. Its own pages' sessions still take them, as Playwright and Puppeteer use them there; a default address is unchanged (Edgar's call from the PR review, d9a6fda).SecurityjoinedFetchandTracingbecausesetIgnoreCertificateErrorsthere would drop certificate checks for every context.Runtime.runIfWaitingForDebugger) and detached, and the agent hears of neither. Its own targets keep the pause before first script that Playwright's init scripts and routes rely on.browser/v1reports every context from agentenv's own connection.1001 the lease ended: ask for an address again.json/listunder an address lists only the pages it sees.browser_connect_cdp {context?}hands the agent an address scoped to its lease. It refuses a browser whosecdptakes no context, such as one from M8.15.record'scdp_connectionsname each connection's lease./svcrelay: a relayed WebSocket's close now keeps its reason, not only its code. An agent behind a driver never heard why its connection ended, here or when the browser relaunched.Decided while building, for your review
getBrowserContextsalone. The note said the lease's id would be rewritten to the default's in everything the agent receives. That isn't needed: Playwright and Puppeteer put a target whose context isn't listed in their default context, so the relay leaves the lease's id out ofbrowserContextIdsand reports it asdefaultBrowserContextId; target ids and contexts in events stay as Chromium sends them.How it was tested
Unit:
attachToBrowserTargetrefused;cdprefusing an ungranted user and an unleased label, and the release revoking the address;browser_connect_cdpasking for a scoped address and refusing a browser that can't scope;/svcrelay keeping a close's reason.tst/unit/drivers,tst/unit/task_stepandtst/unit/task: 4,657 passed.Integration, local Docker on agent-environments-admin VMs (amd64 and arm64), with the real Node clients, a new test:
127.0.0.1embedding127.0.0.2) among them as its own target, and can't attach to seller's tab; bob isn't given an address to buyer;Chaos, on the same VMs, not committed:
waitForDebuggerOnStartnever held a tab in the default context, or a page and its shared worker in another lease;Results (both VMs torn down):
-k cdp)website_browser_test.pybrowser_computer_test.pyarm64's failures are the echo agent's: it's built for linux/amd64, and that box has no emulation.
Review fixes (Greptile round 1, in 0094591, each with a unit test):
Final head on the VMs (cd570a8, fresh amd64 and arm64 VMs, both torn down):
arm64's five failures are the echo agent's, built for linux/amd64 on a box without emulation.
Maintainability (cd570a8, Edgar's call from the PR review, behaviour unchanged): every scoping rule now lives in one
Scopeper connection inscope.py, which the relay asks about each command (verdict), answer (answer) and event (hears); the relay's two maps both calledtargetsare nowtarget_contextsandsession_tabs. The relay and contexts tests pass unchanged.Browser-wide refusals (d9a6fda): a unit test sends each of them on a scoped connection's browser session, refused, and on its page session and a default connection, passed through.
CI on 0094591: all 34 checks and the CodeBuild integration tests passed, the scoped-address and M8.15 multi env tests among them. A
set_test.pyfailure in one slow shard, the desktop's key-press probe at build, unrelated to this PR, passed on a rerun. Greptile's second round: 5/5.Found on the VMs and fixed here: the
/svcrelay dropping close reasons, and M8.15's multi env test reading lease tabs through an unscoped address, which this PR now refuses, as it should.🤖 Generated with Claude Code


Confidence Score: 5/5
The PR appears safe to merge; no new actionable issues were found.Summary
Adds CDP addresses tied to one lease and gathers connection rules in
Scope.Diagram
%%{init: {'theme': 'neutral'}}%% flowchart LR A[Agent asks for a lease address] --> B{User has a grant?} B -->|No| C[Refuse] B -->|Yes| D[Issue lease token] D --> E[Connection gets its own Scope] E --> F[Check commands and filter replies and events] G[Lease ends] --> H[Revoke token and close connections]Reviews (9) · Last reviewed commit: "browser/v1 scoped addresses: one Scope p..." · Reviewed by Greptile