fix(agents): retry connect() when the browser expires mid-connect

[ben-reitz]

TL;DR: fixes a race in connecting to the browser.

Browser.connect() gives the host a working browser. It does two steps:

1. resolve() checks whether the browser is still alive, and creates a replacement if it isn't.
2. connect() then opens a CDP WebSocket to the resolved browser.

The persistent browser tool later in this stack uses it.

connect() could throw if a browser expired after resolve()'s liveness probe but before the WebSocket upgrade. It now replaces the browser, the same way resolve() does. This fixes the Devin thread on #2302.

connect()
  resolved = resolve()                  // probe: alive
  attach(resolved)
    upgrade → 404 / 410                 // expired in between
      retire the record if it still holds resolved.sessionId
      attach(resolve())                 → restarted: true
    any other failure                   → throw

• Retries once. A second failure throws.
• Safe under races. The record is retired under the browser's lock, and only if it still holds the dead browser. A caller that already replaced the browser keeps its replacement, and both callers report restarted: true.
• Public error change (patch changeset). When Browser Run returns no WebSocket, connectBrowserSession now throws BrowserRenderingError, with the HTTP status in the message, instead of a plain Error. It still extends Error, so existing catch blocks keep working.

Tests in browser.test.ts: a 410 on upgrade returns a replacement; a 502 is not retried.

Architecture diff

Each outlined box is a component this PR changes, with one green box per change. Grey boxes are unchanged.

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

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

  subgraph B["Browser · browser.ts"]
    direction TB
    N1["+ connect() retries once on a 404/410 upgrade"]:::changes
    N2["+ retires the dead record only if it's still current"]:::changes
    N1 ~~~ N2
  end

  subgraph Run["connectBrowserSession · browser-run.ts"]
    R1["+ throws BrowserRenderingError with the upgrade status"]:::changes
  end

  Store["StoredBrowserSession · session-store.ts"]:::ctx
  BR["Browser Run"]:::ctx

  Agent -->|lifecycle.use| B
  B -->|"one record"| Store
  B -->|"open CDP socket"| Run
  Run -->|"WebSocket upgrade"| BR

  style B stroke:#1a7f37,stroke-width:2px
  style Run stroke:#1a7f37,stroke-width:2px

Loading

[changeset-bot]

🦋 Changeset detected

Latest commit: 2eb5d4a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
agents	Patch
@cloudflare/agent-think	Patch

Not sure what this means? Click here to learn what changesets are.

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

[pkg-pr-new]

Open in StackBlitz

agents

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

@cloudflare/ai-chat

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

@cloudflare/codemode

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

hono-agents

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

@cloudflare/shell

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

@cloudflare/think

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

@cloudflare/voice

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

@cloudflare/worker-bundler

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

commit: 2eb5d4a

[agent-think]

✅ agents import sizes: no significant changes (e8379676 → e339ad85, workflow run)

[devin-ai-integration]

Devin Review found 1 new potential issue.

[devin-ai-integration]

🔍 Connector remains outside the retry

The retry applies to Browser.connect(), but BrowserConnector calls connectBrowserSession() directly. Its probe-to-upgrade race remains, despite the PR description naming the connector as a beneficiary.

---

Was this helpful? React with 👍 or 👎 to provide feedback.