feat: upgrade stagehand to v3

[Kylejeong2]

what

upgrade to stagehand v3

[greptile-apps]

Greptile Overview

Greptile Summary

This PR upgrades the @browserbasehq/stagehand dependency from v2.5.2 to v3.0.1, adapting the codebase to breaking API changes in the new version.

Key Changes

• Stagehand Initialization API: Replaced modelClientOptions: {apiKey} with model: {apiKey, modelName} object structure
• Property Naming: Changed browserbaseSessionID → browserbaseSessionId (camelCase consistency)
• Page Access: Migrated from stagehand.page to stagehand.context.pages()[0]
• Session Validation: Replaced browser-level checks (browser.isConnected(), page.isClosed()) with context-based validation (context.pages())
• Cookie Management: Removed cookie injection feature as this is now handled by Stagehand v3 internally
• Browser Event Handlers: Removed manual browser disconnect handlers as Stagehand v3 manages lifecycle
• Model Configuration: Changed from enum-based AvailableModelSchema to flexible string-based model names
• Dependency Cleanup: Moved mcpvals to devDependencies and removed playwright-core dependency

Compatibility Impact

All core Stagehand methods (act, extract, observe, navigate) maintain backward-compatible APIs, requiring no changes to tool implementations. The changes are isolated to initialization and session management layers.

Confidence Score: 4/5

• This PR is safe to merge with minor risks around cookie functionality removal and session lifecycle changes
• The upgrade correctly adapts to Stagehand v3 API changes with proper migration patterns. Score is 4/5 (not 5/5) due to: (1) removal of cookie injection feature without migration path may break existing users relying on this functionality, and (2) removal of browser disconnect handlers changes error recovery behavior - while Stagehand v3 may handle this internally, the removal of explicit cleanup on disconnect could lead to resource leaks if v3 doesn't handle all edge cases
• Pay attention to src/sessionManager.ts - the removal of cookie injection and browser disconnect handlers represents significant behavioral changes that could impact production users

Important Files Changed

File Analysis

Filename	Score	Overview
package.json	5/5	Updated @browserbasehq/stagehand from v2.5.2 to v3.0.1, moved mcpvals from dependencies to devDependencies (v0.0.3 → v0.4.0), removed playwright-core from devDependencies
config.d.ts	5/5	Removed playwright-core Cookie import and cookies configuration field as cookie management moved to Stagehand v3
src/index.ts	5/5	Changed modelName from AvailableModelSchema enum to generic string, improved validation logic, added tools: {} to capabilities, updated version to 2.3.0
src/sessionManager.ts	4/5	Migrated to Stagehand v3 API: replaced modelClientOptions with model object, changed browserbaseSessionID to browserbaseSessionId, replaced stagehand.page with stagehand.context.pages()[0], removed browser disconnect handlers and cookie injection logic, simplified session validation

Sequence Diagram

sequenceDiagram
    participant Client as MCP Client
    participant Server as MCP Server
    participant SM as SessionManager
    participant SH as Stagehand v3
    participant BB as Browserbase

    Client->>Server: Initialize with config
    Server->>SM: Create SessionManager
    
    Client->>Server: Execute tool (act/extract/observe)
    Server->>SM: getSession(sessionId)
    
    alt Default session not exists
        SM->>SM: ensureDefaultSessionInternal()
        SM->>SH: new Stagehand({model: {apiKey, modelName}})
        SH->>BB: Create browser session
        BB-->>SH: Return session + context
        SH->>SH: context.pages()[0]
        SH-->>SM: Return initialized Stagehand
        SM->>SM: Store session with browserbaseSessionId
    else Session exists
        SM->>SH: Validate via context.pages()
        alt Session stale
            SM->>SH: stagehand.close()
            SM->>SM: Recreate session
        end
    end
    
    SM-->>Server: Return BrowserSession
    Server->>SH: Call tool method (act/extract/observe)
    SH->>BB: Execute browser automation
    BB-->>SH: Return result
    SH-->>Server: Return tool result
    Server-->>Client: Return response
    
    Client->>Server: Cleanup session
    Server->>SM: cleanupSession(sessionId)
    SM->>SH: stagehand.close()
    SH->>BB: Close browser session
    SM->>SM: Remove from session map

Loading

Additional Comments (1)

1. src/index.ts, line 77-80 (link)

   logic: cookies field removed from config.d.ts and no longer used in sessionManager.ts, but still present in schema

_{16 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}