3/4 Add local Chrome support to Go

[monadoid]

Local Chrome needs the Stagehand extension unpacked on disk, while Browserbase needs the same extension as a ZIP. This bundles one canonical extension archive into the Go module and safely extracts it when needed.

• Adds deterministic extension packaging and drift checks.
• Adds a hand-written Chrome launcher for macOS, Linux, and Windows.
• Matches the shared Chrome flag and browser-option behavior.
• Cleans up owned Chrome processes, profiles, and extracted extension files.

The next PR wires this into the public client alongside Browserbase.

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

[cubic-dev-ai]

All reported issues were addressed across 13 files

Architecture diagram

sequenceDiagram
    participant CI as CI Pipeline
    participant Dev as Developer
    participant Just as Justfile
    participant GoGen as Go Generate
    participant ExtPack as extensionpack Command
    participant Server as Server Build
    participant ExtAssets as extensionassets Package
    participant GoSDK as Go SDK
    participant Chrome as Chrome Process

    Note over CI,Chrome: NEW: Local Chrome support with bundled extension

    CI->>Just: just check
    Just->>ExtPack: run --check
    ExtPack->>ExtPack: verify stagehand-extension.zip in Go module

    Dev->>Just: just generate
    Just->>Server: pnpm build (server)
    Server->>Server: produce artifacts/stagehand-extension.zip
    Just->>GoGen: go generate ./...
    GoGen->>ExtPack: run extensionpack
    ExtPack->>ExtPack: sync built ZIP to internal/extensionassets/
    ExtPack->>ExtAssets: update stagehand-extension.zip (embedded)
    ExtAssets->>ExtAssets: validate version matches server package.json

    Note over ExtAssets,Chrome: Runtime: Local Chrome Launch

    GoSDK->>ExtAssets: Materialize()
    ExtAssets->>ExtAssets: extract ZIP to temp dir
    ExtAssets-->>GoSDK: directory path + cleanup func
    GoSDK->>Chrome: findChromePath()
    alt CHROME_PATH env set
        Chrome-->>GoSDK: explicit path
    else macOS/Linux/Windows
        Chrome-->>GoSDK: OS-specific candidates
    end
    GoSDK->>GoSDK: availablePort() (if port 0)
    GoSDK->>Chrome: exec.Command(chromePath, flags...)
    Note over GoSDK,Chrome: flags include --load-extension=<extracted dir>
    GoSDK->>GoSDK: configureChromeProcess() (platform-specific)
    GoSDK->>Chrome: command.Start()
    GoSDK->>Chrome: waitForChrome() polling /json/version
    alt timeout
        Chrome-->>GoSDK: error
        GoSDK->>Chrome: close() → terminate + kill
        GoSDK->>Chrome: cleanup profile & extension dir
    else success
        Chrome-->>GoSDK: CDP URL available
    end

    Note over GoSDK,Chrome: Graceful Shutdown

    GoSDK->>Chrome: close()
    alt Unix
        Chrome->>Chrome: syscall.Kill(-pid, SIGTERM)
        opt after timeout
            Chrome->>Chrome: syscall.Kill(-pid, SIGKILL)
        end
    else Windows
        Chrome->>Chrome: taskkill /PID /T /F
    end
    GoSDK->>GoSDK: os.RemoveAll(userDataDir)
    GoSDK->>ExtAssets: cleanup() → os.RemoveAll(extension dir)

    Note over CI,Dev: CI Integration

    CI->>CI: install chrome-version:stable
    CI->>CI: set CHROME_PATH dynamically
    CI->>GoSDK: go test (with CHROME_PATH env)
    GoSDK->>Chrome: launchChrome() for integration test

Loading

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

Re-trigger cubic</sub>

[sameelarif]

lgtm but check cubic comments

[changeset-bot]

⚠️ No Changeset found

Latest commit: 7c2ad68

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]

All reported issues were addressed across 8 files (changes from recent commits).

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

Re-trigger cubic</sub>