add cdp headers

[aditya-silna]

why

unblocking a local configuration

what changed

added ability to pass headers to the browser

test plan

---

Summary by cubic

Adds support for custom CDP headers on WebSocket connections to the browser. Enables local setups that require auth or custom proxies.

• New Features
  • Added cdpHeaders to LocalBrowserLaunchOptions.
  • CdpConnection.connect accepts headers and merges with the default User-Agent (overrides allowed).
  • V3Context and V3 pass cdpHeaders through when connecting via cdpUrl in LOCAL mode, with an integration test validating launchOptions usage.

^{Written for commit af91fd6. Summary will update on new commits. Review in cubic}

[changeset-bot]

🦋 Changeset detected

Latest commit: af91fd6

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

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Minor
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server	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

[greptile-apps]

Greptile Summary

Added support for custom CDP headers when connecting to local browsers via cdpUrl.

• Added cdpHeaders optional field to LocalBrowserLaunchOptionsSchema as Record<string, string>
• Modified CdpConnection.connect() to accept optional headers and merge them with the default User-Agent header
• User-provided headers can override the default User-Agent header
• Headers are threaded through V3Context.create() to CdpConnection.connect()
• Implementation is straightforward and follows the existing pattern for optional parameters

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The changes are well-contained and follow existing patterns. The implementation adds optional headers support without breaking existing functionality, properly merges user headers with defaults, and threads the parameter cleanly through the call stack
• No files require special attention

Important Files Changed

Filename	Overview
packages/core/lib/v3/types/public/api.ts	Added cdpHeaders field to LocalBrowserLaunchOptionsSchema - clean type definition
packages/core/lib/v3/understudy/cdp.ts	Modified connect() to accept optional headers and merge with default User-Agent header
packages/core/lib/v3/understudy/context.ts	Threaded cdpHeaders through V3Context.create() to CdpConnection.connect()
packages/core/lib/v3/v3.ts	Passed cdpHeaders from launch options to V3Context.create() call

_{Last reviewed commit: b5a8065}

[greptile-apps]

_{4 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[cubic-dev-ai]

1 issue found across 4 files

Confidence score: 3/5

• There is a concrete risk of breaking the Stagehand REST API because packages/core/lib/v3/types/public/api.ts modifies a shared request shape without the required integration test coverage under packages/server/test.
• The issue is medium severity (6/10) and could affect client/server interoperability, so this isn't quite a risk-free merge.
• Pay close attention to packages/core/lib/v3/types/public/api.ts - shared request shape changed without the mandated integration test.

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/core/lib/v3/types/public/api.ts">

<violation number="1" location="packages/core/lib/v3/types/public/api.ts:44">
P2: Custom agent: **Any breaking changes to Stagehand REST API client / server implementation must be covered by an integration test under packages/server/test**

This change modifies a shared request shape (`LocalBrowserLaunchOptionsSchema`) in the public API types file, and the new `cdpHeaders` option is plumbed through `V3` and `V3Context` to `CdpConnection.connect`. Per the rule, any changes to `packages/core/**/types/public/api.ts` shared request/response shapes must be covered by at least one integration test under `packages/server/test/`. No such test exists for the `cdpHeaders` feature. Please add an integration test that exercises session start with `cdpHeaders` in the launch options to verify the field is accepted and correctly forwarded.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant App as Client Application
    participant V3 as V3 Orchestrator
    participant Context as V3Context
    participant CDP as CdpConnection
    participant WS as WebSocket (ws)
    participant Browser as Remote Browser / CDP Proxy

    Note over App,V3: Initialization with LocalBrowserLaunchOptions
    App->>V3: init(options)
    Note right of App: Includes NEW: cdpHeaders record

    opt if options.cdpUrl is present
        V3->>Context: create(cdpUrl, { cdpHeaders, ... })
        
        Context->>CDP: CHANGED: connect(wsUrl, { headers: cdpHeaders })
        
        CDP->>CDP: Merge defaults (User-Agent) with NEW: cdpHeaders
        
        CDP->>WS: new WebSocket(wsUrl, { headers })
        WS->>Browser: NEW: Connection Request + Custom Headers
        
        alt Connection Successful
            Browser-->>WS: 101 Switching Protocols
            WS-->>CDP: "open" event
            CDP-->>Context: CdpConnection instance
            Context-->>V3: V3Context instance
            V3-->>App: Session Ready
        else Connection Failed (Auth/Network)
            Browser-->>WS: Error (e.g. 401 Unauthorized)
            WS-->>CDP: "error" event
            CDP-->>Context: Connection Rejected
            Context-->>V3: Throw Error
        end
    end

    Note over V3,Browser: Control flow via CDP WebSocket

Loading

---

Since this is your first cubic review, here's how it works:

• cubic automatically reviews your code and comments on bugs and improvements
• Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
• Add one-off context when rerunning by tagging @cubic-dev-ai with guidance or docs links (including llms.txt)
• Ask questions if you need clarification on any suggestion

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[pirate]

good idea