Add user-agent

[miguelg719]

why

For observability into stagehand sessions

what changed

• Added a custom Stagehand/<version> user agent header to CDP connections.

test plan

---

Summary by cubic

Set a custom User-Agent on CDP WebSocket connections: Stagehand/ using STAGEHAND_VERSION. This helps servers identify the client for logging and compatibility.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 4a0c58d

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	Patch
@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 Overview

Greptile Summary

Added custom User-Agent: Stagehand/<version> header to CDP WebSocket connections for improved observability and session identification.

Changes:

• Modified CdpConnection.connect() to pass headers option to WebSocket constructor
• Import STAGEHAND_VERSION from auto-generated version file
• Added changeset documenting the patch

The implementation is straightforward and follows the existing codebase patterns. The STAGEHAND_VERSION constant is generated during build via gen-version.ts script and already used in other parts of the codebase (api.ts, sdkErrors.ts).

Confidence Score: 5/5

• This PR is safe to merge with no risk
• Simple, focused change that adds observability without modifying core logic. The import path is correct, follows existing patterns in the codebase, and the ws library supports the headers option natively
• No files require special attention

Important Files Changed

Filename	Overview
packages/core/lib/v3/understudy/cdp.ts	Added custom User-Agent header to CDP WebSocket connection for observability
.changeset/tricky-mangos-prove.md	Standard changeset entry documenting the user-agent addition

Sequence Diagram

sequenceDiagram
    participant Client as Stagehand Client
    participant CDP as CdpConnection
    participant WS as WebSocket (ws library)
    participant Server as CDP Server

    Client->>CDP: CdpConnection.connect(wsUrl)
    CDP->>WS: new WebSocket(wsUrl, {headers})
    Note over WS: Headers include:<br/>User-Agent: Stagehand/<version>
    WS->>Server: WebSocket handshake<br/>with User-Agent header
    Server-->>WS: Connection established
    WS-->>CDP: 'open' event
    CDP-->>Client: Return CdpConnection instance
    Note over Server: Server can now identify<br/>Stagehand sessions via<br/>User-Agent for logging

Loading

[cubic-dev-ai]

No issues found across 2 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant App as Stagehand Core (CdpConnection)
    participant WS as WebSocket Client (ws)
    participant Server as CDP Server (e.g. Browserbase)
    
    Note over App,Server: Establishing CDP Connection
    
    App->>App: NEW: Retrieve STAGEHAND_VERSION
    App->>WS: connect(wsUrl)
    Note right of App: NEW: Set headers: { "User-Agent": "Stagehand/X.X.X" }
    
    WS->>Server: CHANGED: HTTP Upgrade Request (with User-Agent)
    
    alt Handshake Success
        Server-->>WS: 101 Switching Protocols
        WS-->>App: resolve()
    else Handshake Failure
        Server-->>WS: Error / Connection Refused
        WS-->>App: reject(error)
    end

    Note over Server: Server logs User-Agent for observability/version tracking (NEW)

Loading

[greptile-apps]

_{2 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}