[docs]: add keepAlive docs

[seanmcguire12]

why

• adds documentation for the new keepAlive param

note:

• hold off on merging until after release

---

Summary by cubic

Add keepAlive docs to Stagehand, detailing behavior in Browserbase and Local, close() semantics, defaults/overrides, and how to reconnect via browserbaseSessionID. Addresses Linear STG-1380.

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: 6eaa9cd

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

[greptile-apps]

Greptile Summary

Added comprehensive documentation for the new keepAlive parameter that controls browser lifecycle after close() or process termination.

• Added detailed "Keep Alive" section in browser configuration docs with behavior comparison table for Browserbase vs Local environments
• Documented top-level keepAlive option in V3Options interface with clear defaults and override behavior
• Added explanatory note to close() method describing different behaviors based on keepAlive setting
• Included practical code examples showing reconnection patterns using browserbaseSessionID
• Clear documentation that keepAlive overrides browserbaseSessionCreateParams.keepAlive when both are set

Confidence Score: 5/5

• This PR is safe to merge with no risk
• Documentation-only PR that accurately documents an existing feature (keepAlive) with clear examples, behavior tables, and consistent messaging across configuration and reference docs
• No files require special attention

Important Files Changed

Filename	Overview
packages/docs/v3/configuration/browser.mdx	Added comprehensive keepAlive documentation section with behavior tables, code examples, and environment-specific explanations
packages/docs/v3/references/stagehand.mdx	Added keepAlive parameter documentation to V3Options interface and clarified close() method behavior with keep-alive enabled

_{Last reviewed commit: 6eaa9cd}

[greptile-apps]

_{2 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[cubic-dev-ai]

cubic analysis

No issues found across 2 files

Confidence score: 5/5

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

Linked issue analysis

Linked issue: STG-1380: add docs for keepAlive

Status	Acceptance criteria	Notes
✅	Add documentation for new `keepAlive` param	Added keepAlive docs in browser.mdx and stagehand.mdx
✅	Detail behavior in Browserbase environment	Browserbase section describes session persistence
✅	Detail behavior in Local environment	Local section explains detached Chrome behavior
✅	Document close() semantics (disconnect vs terminate)	Note explains close() disconnects when keepAlive true
✅	Document defaults and overrides (default false; top-level overrides browserbaseSessionCreateParams.keepAlive)	ParamField states default false and override behavior
✅	Show how to reconnect via browserbaseSessionID	Reconnection example using browserbaseSessionID added
✅	Add keepAlive to V3Options interface/reference docs	keepAlive?: boolean added to V3Options
❌	Hold off on merging until after next release (do this just after we cut next release)	No merge gating in diffs; only PR description note

Architecture diagram

sequenceDiagram
    participant App as User Script
    participant SH as Stagehand SDK
    participant BB as Browserbase API
    participant Local as Local Chrome Process

    Note over App, SH: NEW: keepAlive initialization logic
    App->>SH: new Stagehand({ keepAlive, env })
    SH->>SH: NEW: Resolve keepAlive (overrides sessionCreateParams)

    alt env == 'BROWSERBASE'
        SH->>BB: Connect/Create Session
        BB-->>SH: sessionID
    else env == 'LOCAL'
        SH->>Local: Launch Browser Process
    end

    App->>SH: init()
    SH-->>App: Ready

    Note over App, BB: Shutdown / Lifecycle Changes

    alt Process Crash or SIGTERM/SIGINT
        alt NEW: keepAlive is true
            SH-->>SH: Ignore cleanup handlers
            Note right of SH: Browser stays running
        else keepAlive is false (default)
            SH->>SH: Trigger emergency cleanup
            SH->>BB: Terminate Session / Kill Process
        end
    end

    App->>SH: close()
    
    alt NEW: keepAlive is true
        alt env == 'BROWSERBASE'
            SH->>BB: CHANGED: Disconnect WebSocket only
            Note right of BB: Session remains ACTIVE
        else env == 'LOCAL'
            SH->>Local: CHANGED: Detach from Node.js event loop
            Note right of Local: Process remains OPEN
        end
    else keepAlive is false (default)
        alt env == 'BROWSERBASE'
            SH->>BB: Terminate Session (API call)
        else env == 'LOCAL'
            SH->>Local: Kill process & delete temp profile
        end
    end

    opt NEW: Reconnection Flow (Browserbase)
        App->>SH: new Stagehand({ browserbaseSessionID })
        SH->>BB: Connect to existing sessionID
        BB-->>SH: Session State
    end

Loading