Add fallback support for Chrome Dev and other Chrome variants

[antonvishal]

I didn’t have Chrome Stable or Canary installed only Chrome Dev so Stagehand kept failing to find a local browser.

This PR improves browser discovery by supporting Chrome Stable, Beta, Dev, Canary, and Chromium, while preserving existing platform-specific fallbacks. It also makes the configured executablePath work correctly.

---

Summary by cubic

Adds robust local Chrome discovery for Stable, Beta, Dev, Canary, and Chromium. Fixes failures when only non‑Stable Chrome is installed, handles empty PATH on Linux, and improves error messages.

• New Features

  • Prioritized discovery by channel on macOS (system/user Applications), Windows (Program Files/LocalAppData), and Linux (PATH); includes Chromium.
  • TS: new findChromeExecutable used by launchLocalBrowser, integrating chrome-launcher legacy discoveries.
  • Python: refactored discovery helpers and support for CHROME_PATH.

• Bug Fixes

  • browser.executable_path now bypasses discovery in both sdk-ts and sdk-python.
  • Linux: PATH lookup tolerates empty PATH and no longer falls back to the process PATH; recognizes google-chrome-beta and google-chrome-unstable.
  • Clear, Stagehand-specific “browser not found” error with guidance.

^{Written for commit 1c04106. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 1c04106

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.

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

[github-actions]

This PR is from an external contributor and must be approved by a stagehand team member with write access before CI can run.
Approving the latest commit mirrors it into an internal PR owned by the approver.
If new commits are pushed later, the internal PR stays open but is marked stale until someone approves the latest external commit and refreshes it.

[cubic-dev-ai]

All reported issues were addressed across 6 files

Architecture diagram

sequenceDiagram
    participant Client as Client Code
    participant Resolver as resolveBrowserSource()
    participant Launcher as launchLocalBrowser()
    participant ChromeFinder as findChromeExecutable()
    participant ChromeLauncher as chrome-launcher
    participant Process as Browser Process

    Note over Client,Process: Local Browser Discovery Flow

    Client->>Resolver: Provide browser config (type: "local")
    alt executablePath is set
        Resolver->>Launcher: options.executablePath = "/custom/chrome"
        Launcher->>ChromeLauncher: launch({ chromePath: "/custom/chrome" })
        ChromeLauncher->>Process: Start Chrome at custom path
        Process-->>ChromeLauncher: Port assigned
        ChromeLauncher-->>Launcher: { port, kill }
        Launcher-->>Client: { cdpUrl, close }
    else No executablePath
        Resolver->>Launcher: options without executablePath
        Launcher->>ChromeFinder: findChromeExecutable({ legacyInstallations })

        alt CHROME_PATH env set and valid
            ChromeFinder->>ChromeFinder: Check CHROME_PATH
            ChromeFinder-->>Launcher: Return configured path
        else CHROME_PATH not set or invalid
            alt Platform is macOS
                ChromeFinder->>ChromeFinder: Enumerate chromeExecutableCandidates()
                Note over ChromeFinder: Order: Stable, Beta, Dev, Canary, Chromium<br/>Check /Applications and ~/Applications
            else Platform is Windows
                ChromeFinder->>ChromeFinder: Enumerate WINDOWS_APPLICATIONS
                Note over ChromeFinder: Check LOCALAPPDATA, PROGRAMFILES, PROGRAMFILES(X86)<br/>Includes Chrome SxS for Canary
            else Platform is Linux
                ChromeFinder->>ChromeFinder: Search PATH directories
                Note over ChromeFinder: Order: google-chrome-stable,<br/>google-chrome, google-chrome-beta,<br/>google-chrome-unstable, chromium-browser, chromium
            end

            alt Found in our candidates
                ChromeFinder-->>Launcher: Return first executable
            else Not found in our candidates
                ChromeFinder->>ChromeLauncher: legacyInstallations()
                ChromeLauncher-->>ChromeFinder: Legacy discovered paths
                ChromeFinder->>ChromeFinder: Apply channel ordering
                alt Found in legacy results
                    ChromeFinder-->>Launcher: Return legacy path
                else No browser found at all
                    ChromeFinder-->>Launcher: Throw Error (CHROME_NOT_FOUND_MESSAGE)
                    Note over Launcher,Client: "No supported local browser installation found.<br/>Set executablePath or CHROME_PATH"
                end
            end
        end

        Launcher->>ChromeLauncher: launch({ chromePath })
        ChromeLauncher->>Process: Start Chrome
        Process-->>ChromeLauncher: Port assigned
        ChromeLauncher-->>Launcher: { port, kill }
        Launcher-->>Client: { cdpUrl, close }
    end

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>