Skip to content

feat(browser): a CDP address scoped to one lease (M8.16) - #658

Merged
earakely-scale merged 6 commits into
mainfrom
edgararakelyan/fd-4963-m816-scoping-a-cdp-address-to-one
Nov 13, 2026
Merged

earakely-scale merged 6 commits into
mainfrom
edgararakelyan/fd-4963-m816-scoping-a-cdp-address-to-one

Conversation

@earakely-scale

@earakely-scale earakely-scale commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

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 lease context names. A user it isn't granted to is refused (403 permission_denied), a label that isn't leased too (404 target_unavailable).
  • What a connection sees (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.
    • Target events (targetCreated, targetInfoChanged, targetDestroyed, targetCrashed, attachedToTarget, detachedFromTarget) and getTargets keep only what it sees.
    • getBrowserContexts lists only its user's own contexts beside the default, and on a scoped connection reports the lease as defaultBrowserContextId.
    • attachToTarget, activateTarget, closeTarget and getTargetInfo on a target it doesn't see are answered as Chromium answers an unknown target.
    • createTarget, Storage cookie commands, Browser permission commands and setDownloadBehavior that name no context get the lease's; naming a context it doesn't see is refused.
    • Download events only for frames in contexts it sees.
    • Target.attachToBrowserTarget is refused: a second browser session would see past the scope.
    • On a scoped connection's browser session, the commands that act on every context are refused: Fetch, Tracing and Security, Storage beyond the cookie commands, and Browser.setWindowBounds, getWindowBounds and setContentsSize on 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). Security joined Fetch and Tracing because setIgnoreCertificateErrors there would drop certificate checks for every context.
  • Auto-attach (decision 2): a target of another context that auto-attaches to a connection is told to run (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.
  • The default address (decision 3) sees the default context and its user's own contexts, not the leases. No address sees everything; browser/v1 reports every context from agentenv's own connection.
  • Lifetime (decision 4): a scoped token is per user and lease, kept in memory only. A lease's end, by release, reset, relaunch or dispose, revokes it and closes its connections with 1001 the lease ended: ask for an address again.
  • Discovery: json/list under 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 whose cdp takes no context, such as one from M8.15.
  • record's cdp_connections name each connection's lease.
  • Computer /svc relay: 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

  1. The lease shows as the default through getBrowserContexts alone. 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 of browserContextIds and reports it as defaultBrowserContextId; target ids and contexts in events stay as Chromium sends them.
  2. A target whose context isn't known is the default context's, so a scoped connection never sees one.
  3. A connection to a lease that has already ended is accepted and then closed with the lease-ended reason, so the client sees why, rather than a bare handshake refusal.

How it was tested

  • Unit:

    • the relay over a fake browser with pages in the default context and in two leases: what a scoped and a default connection hear and get answered, the lease's context added to commands, foreign targets refused as unknown, attachToBrowserTarget refused;
    • a user's own contexts seen on both kinds of address, another user's on neither;
    • a foreign target that auto-attaches run and detached unheard;
    • a lease's end closing its connections, a connection to an ended lease refused;
    • scoped tokens: one per user and lease, in memory, revoked with the lease;
    • cdp refusing an ungranted user and an unleased label, and the release revoking the address;
    • browser_connect_cdp asking for a scoped address and refusing a browser that can't scope;
    • the /svc relay keeping a close's reason.
    • agentenv-protocol's tests with tst/unit/drivers, tst/unit/task_step and tst/unit/task: 4,657 passed.
  • Integration, local Docker on agent-environments-admin VMs (amd64 and arm64), with the real Node clients, a new test:

    • steps lease buyer for ada and seller for bob, each signed in by its own cookie with a tab open;
    • ada's address to buyer lists only buyer's targets, a cross-origin iframe (127.0.0.1 embedding 127.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;
    • Playwright on buyer's address finds one context with buyer's cookie and tabs, opens a page and clicks inside the cross-origin iframe; Puppeteer on seller's finds seller alone; Playwright on the default address finds none of the leases' tabs;
    • Playwright on buyer's and seller's addresses at once each click in their iframe ten times, both getting there, which also shows what M8.15's done-when left partly shown;
    • releasing buyer closes its connection with the lease-ended reason, and its address is refused after.
  • Chaos, on the same VMs, not committed:

    1. a scoped agent holding every new target with waitForDebuggerOnStart never held a tab in the default context, or a page and its shared worker in another lease;
    2. scoped connections open while their leases are released at once: every release answered 200, each connection closed with 1001;
    3. the app server killed with scoped connections open: back, the scoped address is gone and a default one still works.
  • Results (both VMs torn down):

    Tier amd64 arm64
    The new scoped-address test passed passed
    M8.15's multi env test, now with a scoped address per lease passed passed
    CDP tests (-k cdp) 7 of 7 3 of 7
    Multi env tests 6 of 6 5 of 6
    website_browser_test.py 4 of 4 4 of 4
    The rest of browser_computer_test.py 23 passed, 1 skipped 23 passed, 1 skipped
    Chaos, all three passed passed

    arm64'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):

    • a lease that ends while a connection to it attaches closes that connection with the lease-ended reason, rather than leaving it open on an ended lease;
    • a download a cross-origin iframe began belongs to its tab's context: the control keeps each frame attached to a page as that tab's, and the relay falls back to the iframe target's context. The scoped-address test now downloads from the iframe through Playwright and checks the lease lists it.
  • Final head on the VMs (cd570a8, fresh amd64 and arm64 VMs, both torn down):

    Tier amd64 arm64
    The scoped-address test passed passed
    M8.15's contexts test passed passed
    M8.15's multi env test passed passed
    Chaos, all three passed passed
    CDP tests 7 of 7 3 of 7
    Multi env tests 6 of 6 5 of 6

    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 Scope per connection in scope.py, which the relay asks about each command (verdict), answer (answer) and event (hears); the relay's two maps both called targets are now target_contexts and session_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.py failure 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 /svc relay 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

RetriggerView in GreptileConfidence 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.

  • CDP addresses can now stay inside one browser lease.
  • Browser connection steps can ask for an agent's lease-scoped address.
  • WebSocket relays now carry close reasons along with close codes.

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]
Loading

Reviews (9) · Last reviewed commit: "browser/v1 scoped addresses: one Scope p..." · Reviewed by Greptile

earakely-scale and others added 3 commits November 12, 2026 16:38
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>
earakely-scale and others added 3 commits November 12, 2026 18:06
- 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
earakely-scale merged commit 8e4ec9e into main Nov 13, 2026
38 of 39 checks passed
@earakely-scale
earakely-scale deleted the edgararakelyan/fd-4963-m816-scoping-a-cdp-address-to-one branch November 13, 2026 15:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant