bump @browserbasehq/sdk to ^2.7.0, make projectId optional

[derekmeegan]

why

SDK v2.7.0 makes projectId optional for session creation. Update all references to treat projectId as optional rather than required.

what changed

new browserbase sdk version and optional project id

test plan

[changeset-bot]

⚠️ No Changeset found

Latest commit: 02567d4

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

[cubic-dev-ai]

1 issue found across 7 files

Confidence score: 3/5

• Validation rule relaxed in packages/server/src/routes/v1/sessions/start.ts without the required integration test under packages/server/test, which could allow a breaking API behavior change to slip through.
• Given the 7/10 severity and concrete API-contract impact, there’s some regression risk despite being a single change.
• Pay close attention to packages/server/src/routes/v1/sessions/start.ts - relaxed validation needs integration coverage in packages/server/test.

Prompt for AI agents (unresolved 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/server/src/routes/v1/sessions/start.ts">

<violation number="1" location="packages/server/src/routes/v1/sessions/start.ts:114">
P1: 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 relaxes a server-side validation rule (making `x-bb-project-id` optional for browserbase sessions), which alters the API contract. There is no integration test under `packages/server/test/` that covers this new behavior — e.g., verifying that a request without `x-bb-project-id` is now accepted, and that a request without `x-bb-api-key` still returns the updated error message. Add integration tests to validate both the happy path (missing `x-bb-project-id` succeeds) and the error path (missing `x-bb-api-key` returns `"Missing required x-bb-api-key header for browserbase sessions"`).

(Based on your team's feedback about adding unit tests for new behavior.) [FEEDBACK_USED]</violation>
</file>

Architecture diagram

sequenceDiagram
    participant User as User / Client
    participant Server as Stagehand Server
    participant Core as V3 Core Logic
    participant APIClient as Stagehand API Client
    participant BBSDK as @browserbasehq/sdk
    participant BBAPI as Browserbase API

    Note over User,BBAPI: Session Initialization Flow

    User->>Server: POST /sessions/start
    Note right of Server: Headers: x-bb-api-key, [x-bb-project-id]
    
    Server->>Server: Validate Credentials
    alt API Key Missing
        Server-->>User: 400 Error (Missing x-bb-api-key)
    else API Key Present
        Server->>Core: init()
    end

    Core->>Core: requireBrowserbaseCreds()
    Note right of Core: Reads from options or ENV
    
    alt CHANGED: Project ID Check
        Note over Core: Only BROWSERBASE_API_KEY is strictly required
    end

    Core->>BBSDK: NEW: createSession({ projectId? })
    BBSDK->>BBAPI: Create Remote Browser Session
    BBAPI-->>BBSDK: sessionId, proxyUrl
    BBSDK-->>Core: Session Metadata

    Note over Core,BBAPI: Runtime API Interaction

    Core->>APIClient: Execute Action (e.g., act/observe)
    
    APIClient->>APIClient: Build Request Headers
    Note right of APIClient: Always include x-bb-api-key
    
    opt CHANGED: Project ID exists
        APIClient->>APIClient: NEW: Add x-bb-project-id to headers
    end

    APIClient->>BBAPI: Request with conditional headers
    BBAPI-->>APIClient: Response
    APIClient-->>Core: Data
    Core-->>User: Result (Streaming/JSON)

Loading

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

[cubic-dev-ai]

P1: 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 relaxes a server-side validation rule (making x-bb-project-id optional for browserbase sessions), which alters the API contract. There is no integration test under packages/server/test/ that covers this new behavior — e.g., verifying that a request without x-bb-project-id is now accepted, and that a request without x-bb-api-key still returns the updated error message. Add integration tests to validate both the happy path (missing x-bb-project-id succeeds) and the error path (missing x-bb-api-key returns "Missing required x-bb-api-key header for browserbase sessions").

(Based on your team's feedback about adding unit tests for new behavior.)

View Feedback

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/server/src/routes/v1/sessions/start.ts, line 114:

<comment>This change relaxes a server-side validation rule (making `x-bb-project-id` optional for browserbase sessions), which alters the API contract. There is no integration test under `packages/server/test/` that covers this new behavior — e.g., verifying that a request without `x-bb-project-id` is now accepted, and that a request without `x-bb-api-key` still returns the updated error message. Add integration tests to validate both the happy path (missing `x-bb-project-id` succeeds) and the error path (missing `x-bb-api-key` returns `"Missing required x-bb-api-key header for browserbase sessions"`).

(Based on your team's feedback about adding unit tests for new behavior.) </comment>

<file context>
@@ -111,10 +111,10 @@ const startRouteHandler: RouteHandler = withErrorHandling(
       bbProjectId = getOptionalHeader(request, "x-bb-project-id");
 
-      if (!bbApiKey || !bbProjectId) {
+      if (!bbApiKey) {
         return error(
           reply,
</file context>

[greptile-apps]

Greptile Summary

Updates @browserbasehq/sdk to v2.7.0 and makes projectId optional throughout the codebase. Most changes correctly propagate the optional projectId type, but the shutdown supervisor components were not fully updated.

Issues found:

• Type definition in shutdown.ts still requires projectId as a string, causing type errors when v3.ts passes potentially undefined projectId to the shutdown supervisor
• Cleanup validation in supervisor.ts prevents cleanup when projectId is missing, which breaks the intended behavior for sessions without a project ID

Confidence Score: 2/5

• This PR has type safety issues that will cause compilation errors
• The shutdown supervisor type definition wasn't updated to make projectId optional, which will cause TypeScript errors when passing undefined projectId from v3.ts:951. Additionally, the cleanup logic requires projectId to be present, preventing proper cleanup for sessions created without a project ID.
• Pay close attention to packages/core/lib/v3/types/private/shutdown.ts and packages/core/lib/v3/shutdown/supervisor.ts

Important Files Changed

Filename	Overview
packages/core/lib/v3/types/private/shutdown.ts	Type definition not updated - projectId still required instead of optional, causing type errors
packages/core/lib/v3/shutdown/supervisor.ts	Cleanup validation still requires projectId, preventing cleanup when projectId is undefined
packages/core/lib/v3/api.ts	Correctly makes projectId optional and conditionally includes header when present
packages/core/lib/v3/v3.ts	Removes projectId validation checks and updates return type, passes potentially undefined projectId to shutdown supervisor

_{Last reviewed commit: 02567d4}

[greptile-apps]

_{7 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Additional Comments (3)

packages/core/lib/v3/types/private/shutdown.ts
projectId should be optional here

      projectId?: string;

---

packages/core/lib/v3/shutdown/supervisor.ts
since projectId is now optional, this check should only require apiKey and sessionId

  if (!cfg.apiKey || !cfg.sessionId) return;

---

packages/core/lib/v3/shutdown/supervisor.ts
conditionally include projectId in the update payload

    await bb.sessions.update(cfg.sessionId, {
      status: "REQUEST_RELEASE",
      ...(cfg.projectId ? { projectId: cfg.projectId } : {}),
    });