refactor(agents): collapse named browser sessions into one Browser class

[ben-reitz]

TL;DR: replaces the two browser session classes with one Browser class: one object, one browser.

---

Before, a named browser went through two classes that were hard to tell apart: BrowserSessions (the Lifecycle capability) and NamedBrowserSessions (the engine under it). Every call took a name. Now there's one Browser per browser, named once:

-const sessions = new BrowserSessions({ browser: env.BROWSER, recording: true });
-await sessions.connect("research");
+const browser = new Browser({
+  provider: browserRun(env.BROWSER, { recording: true }),
+  name: "research" // optional, defaults to "default"
+});
+await browser.connect();

• resolve(), connect(), close(), liveView() lose their name argument. sessions() is gone; hosts that want more than one browser keep more than one Browser.
• Provider. browserRun(binding, options) holds the Browser Run settings (keepAliveMs, recording, guardrails). It's a plain config object for now, so bring-your-own-browser can be another provider later without changing Browser.
• Lifecycle id is browser:<name>, so several browsers can be installed on one object. Passing a store still works without Lifecycle.
• Storage keys are unchanged (browser:session:<name>, browser:retired:<name>).
• Renames: ConnectedBrowserSession → BrowserConnection, ResolvedBrowserSession → ResolvedBrowser, session-manager.ts → session-store.ts (it holds the store). The store-less openOneShotBrowserSession moves into browser-run.ts.
• Removes the incorrect "provider-independent" comments; the code is Browser Run-specific today.

Nothing here is exported yet, so no changeset. Browser is exported in #2372. Tests are ported from the old classes (browser-session-core.test.ts → browser.test.ts), plus tests for the capability id and multiple browsers on one Lifecycle.

Architecture diff

Outlined boxes are components this PR changes (green added, red removed). Grey boxes are unchanged.

flowchart TB
  classDef ctx fill:none,stroke:#8c959f,color:#8c959f
  classDef changes fill:#dafbe1,stroke:#1a7f37,color:#1f2328
  classDef removed fill:#ffebe9,stroke:#cf222e,color:#1f2328

  Agent["Agent (host Durable Object)"]:::ctx

  subgraph Old["removed"]
    direction TB
    O1["− BrowserSessions · capability.ts (one capability, every call takes a name)"]:::removed
    O2["− NamedBrowserSessions · session-core.ts (engine)"]:::removed
    O1 ~~~ O2
  end

  subgraph B["Browser · browser.ts (new)"]
    direction TB
    B1["+ one object per browser, Lifecycle id browser:<name>"]:::changes
    B2["+ resolve · connect · close · liveView"]:::changes
    B1 ~~~ B2
  end

  subgraph P["browserRun() · browser.ts (new)"]
    P1["+ Browser Run settings: keepAliveMs, recording, guardrails"]:::changes
  end

  Store["DurableBrowserSessionStore · session-store.ts (renamed)"]:::ctx
  BR["Browser Run"]:::ctx

  Agent -->|"lifecycle.use (one per browser)"| B
  B --> P
  B -->|"one record"| Store
  P --> BR

  style B fill:#dafbe1,stroke:#1a7f37,stroke-width:2px,color:#1f2328
  style P fill:#dafbe1,stroke:#1a7f37,stroke-width:2px,color:#1f2328
  style Old stroke:#cf222e,stroke-width:2px

Loading

[changeset-bot]

⚠️ No Changeset found

Latest commit: 498d9cf

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@2411

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@2411

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@2411

hono-agents

npm i https://pkg.pr.new/hono-agents@2411

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@2411

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@2411

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@2411

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@2411

commit: 498d9cf

[agent-think]

✅ agents import sizes: no significant changes (5bf07915 → 498d9cf9, workflow run)

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.