feat(agents): add active-tab tracking and spec() to named browser sessions

[ben-reitz]

TL;DR: makes sessions remember the current tab.

---

Named sessions now remember the agent's current tab, so when the model references sessionId: "active" with the new connector we add in #2371, it will point at the same tab from one execution to the next. The record stores the tab's targetId because targets survive reconnects and CDP session ids don't.

 StoredBrowserSession { sessionId, createdAt, updatedAt, closedAt?,
+  activeTargetId? }

 connect(name) → { name, sessionId, restarted, cdp,
+  activeTargetId?,
+  setActiveTarget(targetId | undefined): Promise<boolean>,
+  spec(): Promise<SearchableCdpSpec> }

• Stale connections can't write. setActiveTarget and the activity touch share one #update helper. It writes under the per-name lock only while the record still holds the same browser, and returns false otherwise. A closed or replaced session is never brought back.
• A replacement browser starts with no active tab.
• spec() reads the CDP protocol from this connection's own browser (the path added in refactor(agents): share connector validation and load the CDP spec from a live session #2369). The connector uses it without ever seeing the Browser Run binding.

Everything here is internal. BrowserSessions gets exported in #2372.

Architecture diff

Each outlined box is a component this PR changes, with one green box per change. Grey boxes are unchanged, and dashed boxes arrive later in the stack.

flowchart TB
  classDef ctx fill:none,stroke:#8c959f,color:#8c959f
  classDef changes fill:#dafbe1,stroke:#1a7f37,color:#1f2328
  classDef later fill:none,stroke:#8c959f,stroke-dasharray:4 3,color:#57606a

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

  BS["BrowserSessions · capability.ts"]:::ctx

  subgraph NBS["NamedBrowserSessions · session-core.ts"]
    direction TB
    N1["+ connect() returns activeTargetId, setActiveTarget()"]:::changes
    N2["+ connected session gets spec()"]:::changes
    N3["+ stale connections can't write the record"]:::changes
    N1 ~~~ N2 ~~~ N3
  end

  subgraph Store["StoredBrowserSession · session-manager.ts"]
    Sc["+ activeTargetId?"]:::changes
  end

  BR["Browser Run"]:::ctx
  Spec["loadCdpSpec · spec.ts"]:::ctx
  Next["BrowserSessionConnector (next PR)<br/>reads and saves the active tab"]:::later

  Agent -->|lifecycle.use| BS
  BS --> NBS
  NBS -->|"one record per name"| Store
  NBS -->|"create · probe · CDP socket"| BR
  NBS -->|"spec() for this sessionId"| Spec
  Next -.-> BS

  style NBS stroke:#1a7f37,stroke-width:2px
  style Store stroke:#1a7f37,stroke-width:2px

Loading

[changeset-bot]

⚠️ No Changeset found

Latest commit: d9e5c51

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

[agent-think]

✅ agents import sizes: no significant changes (cfd3bdca → d9e5c511, workflow run)

[pkg-pr-new]

Open in StackBlitz

agents

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

@cloudflare/ai-chat

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

@cloudflare/codemode

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

hono-agents

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

@cloudflare/shell

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

@cloudflare/think

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

@cloudflare/voice

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

@cloudflare/worker-bundler

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

commit: d9e5c51

[devin-ai-integration]

Devin Review found 1 new potential issue.