Skip to content

feat(browser): browser/v1 contexts, leased beside the default one (M8.15) - #642

Merged
earakely-scale merged 9 commits into
mainfrom
edgararakelyan/fd-4962-m815-browserv1-contexts-leases-grants
Nov 12, 2026
Merged

earakely-scale merged 9 commits into
mainfrom
edgararakelyan/fd-4962-m815-browserv1-contexts-leases-grants

Conversation

@earakely-scale

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

Copy link
Copy Markdown
Collaborator

What and why

M8.15 (FD-4962): a website browser leases browser contexts beside its default one.

Until now a website browser had one set of cookies, local storage, tabs and downloads, so a task couldn't sign two users in at once, and contexts an agent made over CDP were invisible to agentenv. Now a task leases a context by a label, and each lease has its own cookies, local storage, tabs and downloads folder in the same Chromium.

Design note: M8.15: browser/v1 contexts, decisions 1a, 2a, 3a, 4b and 5a.

What changes

  • New ops:
    • contexts/lease {label} returns {context, id}. Leasing the same label again returns the same lease, so a retried step is harmless.
    • contexts/grant {context, user} records an agent a lease is for. Nothing enforces grants yet; M8.16 will (decision 1a).
    • contexts/release {context} closes the lease's tabs, disposes the context and deletes its folder. Releasing a label that isn't leased does nothing.
    • contexts/list lists every lease with who made it and its grants.
    • Labels are lowercase letters, digits and -, at most 40 characters. A task's label can't start with agent- (decision 2a).
  • context on the existing ops: tabs/*, cookies/*, local_storage/*, downloads/list and downloads/get take an optional context, a lease's label. Without one they act on the default context exactly as before, error messages included.
  • Downloads: a lease's downloads go to ~/Contexts/<label>/Downloads/, and ~/Downloads stays the default context's (decision 4b). Uploads stay shared. Each download and tab in record names its context.
  • Contexts agents make over CDP:
    • A context an agent creates through the relay is leased to it as agent-<user>-<n> and granted to it. One made where the relay didn't see is listed as agent-unknown-<n>, granted to nobody.
    • The relay refuses an agent disposing the task's lease or another agent's context. An agent may dispose its own.
    • An agent's setDownloadBehavior for a lease is pinned to that lease's folder.
  • Lifetime: a reset, or any relaunch of the browser, ends every lease (decision 3a). The lease table lives in memory, since a server restart relaunches the browser anyway.
  • Data plane:
    • data/get gains contexts: each lease's cookies, local storage, tabs, downloads, grants and who made it. Each lease's finished downloads are among the files.
    • data/add leases any context it names that isn't leased, then loads its cookies, local storage and tabs. A snapshot therefore round-trips (decision 5a). Files under Contexts/<label>/Downloads/ load into that lease.
  • Task steps:
    • browser_lease_context {label, grants?} and browser_release_context {label} are new.
    • The cookie, local storage, tab and sign-in steps take a context.
    • A step's to_dict only gains context when it's set, so tasks saved before this don't get new versions.
    • A step naming a context on a browser that leases none fails before any call.

Decided while building, for your review

  1. Dispose rules in the relay: only the agent that made a context may dispose it. The task's leases end only by release.
  2. disposeOnDetach: an agent context made with it (Playwright's default) ends its lease when that agent's connection closes, as Chromium disposes it.
  3. Downloads re-pinned: after an agent connection that set download behaviour closes, every lease's downloads are sent to its folder again, in case Chromium reset them when that session ended.
  4. Leftover folders: ~/Contexts is cleared before each launch, since a killed app server can't clean up after itself.
  5. data/get top level: closed_tabs stays the browser's whole history, each tab naming its context. cookies, local_storage, tabs and downloads are the default context's.
  6. An unknown label answers 404 target_unavailable. The note said not_found; this uses the computer error that already exists.
  7. Step fields: the lease and release steps take label, and the other steps name a lease as context.

How it was tested

  • Unit:

    • test_browser_contexts.py, new, 24 tests:
      • leases, labels and grants;
      • contexts agents make, their labels and the dispose rules;
      • each context's tabs, cookies, origins and downloads;
      • release and the end of the browser;
      • a release and a lease of the same label at once;
      • what a load may name;
      • the ops.
    • The relay: an agent's context is leased to it, its downloads are pinned, and dispose is refused for another agent's context or the task's lease. A disposeOnDetach context ends on disconnect.
    • Steps: the lease and release steps, context on cookies and tabs, a browser that leases none, config problems, round trips, and sign-in into a lease.
    • After merging main (twice, for M8.23's recordings and M8.20's network log): agentenv-protocol's tests and tst/unit/task_step + tst/unit/task all pass.
  • Integration, local Docker on agent-environments-admin VMs (amd64 and arm64), a new test in browser_computer_test.py:

    • Two leases made by steps each sign in to a loopback site as their own user, in tabs the default context doesn't list.
    • Five leases of one label at once are one lease.
    • A download lands in the lease's folder and is listed there only.
    • An agent's CDP context is agent-ada-1; bob can't dispose it, and ada can't dispose the task's lease but can dispose her own.
    • data/get carries the leases and their downloads. After agents have acted, a load still leases a released one back with its cookies; its tabs, like the default context's, can't be loaded then, so the test opens one with an op.
    • A reset leaves no lease and no folder.
  • Chaos, on the same VMs, not committed:

    • 60 leases and releases at once;
    • 8 agent connections churning;
    • a download released mid-flight;
    • the app server killed with leases open;
    • chromium killed.
  • Results:

    Tier amd64 arm64
    The new contexts test, on the head passed passed
    Chaos, all five scenarios, on the head passed passed
    browser_computer_test.py, the rest of it 31 of 31 27 of 31
    website_browser_test.py 4 of 4 4 of 4
    • arm64's four failures are the known ones: the echo agent is built for linux/amd64, and that box has no emulation. They fail the same way without this change.
    • The two browser tiers ran just before the merge of M8.20; CI's slow integration shards run them on the head.
    • What chaos saw:
      1. 60 leases and releases at once all answered 200, and the folders on disk matched the leases listed.
      2. Of the 8 agent connections, the 4 made with disposeOnDetach were gone once they closed. The other 4 stayed leased to their own agents.
      3. A download in a lease released at once landed in no other context.
      4. With the app server killed, no lease or folder was left, and leasing again worked.
      5. With chromium killed, every lease ended and its folder went.
    • Building the chaos test found two real bugs, fixed in 630e899: a release and a lease of one label at once could delete the new lease's folder, and a killed app server left its leases' folders behind.
    • Both VMs are torn down.
  • Review fixes (Greptile rounds 1 and 2, in b819fd8 and 375d168, each with a unit test):

    • page ops follow the tab last brought to the front in any context, as before contexts;
    • an agent's disposed context moves its folder aside at once, so a lease of its label right after keeps its own;
    • a load into an existing agent lease finds it before checking who may lease the label, and that check runs inside the lease lock;
    • origins are kept by context id from the first load, so a context found later keeps its local storage;
    • a download an iframe began belongs to its tab's context.
  • Review round (d0b104b), from Edgar's read of the PR:

    • The page driver's computer_tabs sees every context. tabs/list takes every: all contexts' tabs, each naming its context, the screen's the active one. Switching to or closing a lease's tab acts in its lease, so an agent can act on whatever its screen shows. A browser built before this gets the old list.

    • browser_sign_in into a context refuses a label that isn't leased, before it asks the site for a session, rather than signing a new, empty lease in.

    • A new multi env test: chromium as the multi env's browser, two leases each signed in to the env's shop.test as their own user, each opening https://shop.test/api/session by name, over https through the gateway. Each page says its own user; the default context has neither's cookies.

    • VMs, amd64 and arm64, on d0b104b (both torn down):

      Tier amd64 arm64
      Two leases in a multi env sign in by name passed passed
      The contexts test passed passed
      Multi env tests (-k multi_env) 7 of 7 6 of 7
      website_browser_test.py passed passed
      Chaos, all five scenarios passed passed
      The rest of browser_computer_test.py 25 passed, 3 skipped 22 passed, 3 failed

      arm64's four failures are the echo agent's: it's built for linux/amd64, and that box has no emulation.

  • CI on d0b104b: all 34 checks and the CodeBuild integration tests passed. A plugin_settings_test.py failure in one unit shard, unrelated to this PR, passed on a rerun.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 5/5

The changes appear safe to merge; no new blocking issue was found.

Summary

Adds named browser contexts with separate cookies, storage, tabs, and downloads.

  • A browser keeps each labeled context's cookies, tabs, and downloads separate.
  • CDP-created contexts are leased to the agent that made them.
  • Browser snapshots include and restore each labeled context.
  • Task steps and the page driver can work with a named browser context.

Reviews (8) · Last reviewed commit: "browser/v1 contexts: the agent's tab too..." · Reviewed by Greptile

earakely-scale and others added 3 commits November 12, 2026 10:47
A website browser now leases browser contexts by a label: each has its own
cookies, local storage, tabs and a downloads folder in
~/Contexts/<label>/Downloads. contexts/lease is idempotent, contexts/grant
records the agents a lease is for (not enforced yet), contexts/release ends
it and contexts/list lists them. The tabs, cookies, local_storage and
downloads ops take a context, else act on the default context as before.

A context an agent makes over its CDP address is leased to it as
agent-<user>-<n>; only that agent may dispose it, and a lease's downloads
stay pinned to its folder. A reset or relaunch of the browser ends every
lease. data/get carries each lease under contexts, with its downloads, and
data/add leases any it names that are missing, so a snapshot round-trips.

Task steps: browser_lease_context and browser_release_context, and a
context on the cookie, local storage, tab and sign-in steps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nd clear leftover folders before each launch

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…2-m815-browserv1-contexts-leases-grants

# Conflicts:
#	packages/agentenv-protocol/src/agentenv_protocol/website_browser/environment.py
#	src/agent_env/task/episode/rules.py
earakely-scale and others added 3 commits November 12, 2026 11:21
…d leases a context by its cookies, then a tab opens

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…2-m815-browserv1-contexts-leases-grants

# Conflicts:
#	packages/agentenv-protocol/src/agentenv_protocol/website_browser/environment.py
#	packages/agentenv-protocol/src/agentenv_protocol/website_browser/log.py
#	packages/agentenv-protocol/tests/test_browser_data.py
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale marked this pull request as ready for review November 12, 2026 20:18
@earakely-scale
earakely-scale requested a review from a team as a code owner November 12, 2026 20:18
- The page's operations (page/*, navigate, history, dialog/answer,
  files/choose) follow the tab last brought to the front in any context,
  as before contexts, rather than only the default context's.
- A context an agent disposed has its folder moved aside at once, so a
  lease of its label right after keeps a folder of its own.
- A load into a lease that exists finds it before checking who may lease
  the label, so signing in to an agent's lease works.
- Origins are kept by context id from the first load, so a context found
  only later keeps its local storage.
- A download an iframe began belongs to its tab's context.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
earakely-scale and others added 2 commits November 12, 2026 12:37
…an't lease an ended agent's label as the task's

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…n-in needs a lease

- tabs/list takes every: all contexts' tabs, each naming its context, the
  page's tab the active one. The page driver's computer_tabs uses it when
  the browser leases contexts, and switches to or closes a lease's tab in
  its lease, so an agent can act on the tab on its screen.
- browser_sign_in into a context refuses a label that isn't leased, before
  it asks the site for a session, rather than leasing a new one.
- A multi env test: two leases in chromium as its browser each sign in to
  its site and open it by name, over https through the gateway.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale merged commit 976ca89 into main Nov 12, 2026
64 of 66 checks passed
@earakely-scale
earakely-scale deleted the edgararakelyan/fd-4962-m815-browserv1-contexts-leases-grants branch November 12, 2026 22:15
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