STG-1537: switch local binary downloads to server-v3

Author: monadoid

.github/workflows/publish-pypi.yml

@@ -17,19 +17,19 @@ jobs:
       matrix:
         include:
           - os: ubuntu-latest
-            binary_name: stagehand-server-linux-x64
+            binary_name: stagehand-server-v3-linux-x64
             output_path: src/stagehand/_sea/stagehand-linux-x64
             wheel_platform_tag: manylinux2014_x86_64
           - os: macos-latest
-            binary_name: stagehand-server-darwin-arm64
+            binary_name: stagehand-server-v3-darwin-arm64
             output_path: src/stagehand/_sea/stagehand-darwin-arm64
             wheel_platform_tag: macosx_11_0_arm64
           - os: macos-15-intel
-            binary_name: stagehand-server-darwin-x64
+            binary_name: stagehand-server-v3-darwin-x64
             output_path: src/stagehand/_sea/stagehand-darwin-x64
             wheel_platform_tag: macosx_10_9_x86_64
           - os: windows-latest
-            binary_name: stagehand-server-win32-x64.exe
+            binary_name: stagehand-server-v3-win32-x64.exe
             output_path: src/stagehand/_sea/stagehand-win32-x64.exe
             wheel_platform_tag: win_amd64
 
@@ -45,7 +45,7 @@ jobs:
         with:
           version: "0.9.13"
 
-      - name: Resolve latest stagehand/server release
+      - name: Resolve latest stagehand/server-v3 release
         id: stagehand-server-release
         uses: actions/github-script@v6
         with:
@@ -56,12 +56,12 @@ jobs:
               repo: 'stagehand',
               per_page: 100,
             });
-            const release = data.find(r => typeof r.tag_name === 'string' && r.tag_name.startsWith('stagehand-server/v'));
+            const release = data.find(r => typeof r.tag_name === 'string' && r.tag_name.startsWith('stagehand-server-v3/v'));
             if (!release) {
-              core.setFailed('No stagehand-server/v* release found in browserbase/stagehand');
+              core.setFailed('No stagehand-server-v3/v* release found in browserbase/stagehand');
               return;
             }
-            core.info(`Using stagehand/server release tag: ${release.tag_name}`);
+            core.info(`Using stagehand/server-v3 release tag: ${release.tag_name}`);
             core.setOutput('tag', release.tag_name);
             core.setOutput('id', String(release.id));
 

CONTRIBUTING.md

@@ -40,19 +40,19 @@ $ uv run python scripts/download-binary.py
 
 This will:
 - Detect your platform (macOS, Linux, Windows) and architecture (x64, arm64)
-- Download the latest stagehand-server binary from GitHub releases
+- Download the latest stagehand-server-v3 binary from GitHub releases
 - Place it in `bin/sea/` where the SDK expects to find it
 
 ### Manual download (alternative)
 
 You can also manually download from [GitHub releases](https://github.com/browserbase/stagehand/releases):
 
-1. Find the latest `stagehand/server vX.X.X` release
+1. Find the latest `stagehand/server-v3 vX.X.X` release
 2. Download the binary for your platform:
-   - macOS ARM: `stagehand-server-darwin-arm64`
-   - macOS Intel: `stagehand-server-darwin-x64`
-   - Linux: `stagehand-server-linux-x64` or `stagehand-server-linux-arm64`
-   - Windows: `stagehand-server-win32-x64.exe` or `stagehand-server-win32-arm64.exe`
+   - macOS ARM: `stagehand-server-v3-darwin-arm64`
+   - macOS Intel: `stagehand-server-v3-darwin-x64`
+   - Linux: `stagehand-server-v3-linux-x64` or `stagehand-server-v3-linux-arm64`
+   - Windows: `stagehand-server-v3-win32-x64.exe` or `stagehand-server-v3-win32-arm64.exe`
 3. Rename it to match the expected format (remove `-server` from the name):
    - `stagehand-darwin-arm64`, `stagehand-linux-x64`, `stagehand-win32-x64.exe`, etc.
 4. Place it in `bin/sea/` directory

RELEASE_WORKFLOWS.md

@@ -11,14 +11,14 @@ This repo publishes the `stagehand` Python package to PyPI when a **GitHub Relea
    - Publishes the GitHub Release + git tag.
 4. Wait for GitHub Actions to publish to PyPI (automatic).
    - Trigger: GitHub Release `published` event runs `.github/workflows/publish-pypi.yml`.
-   - Builds platform wheels that embed the Stagehand server binary (downloaded from the latest `stagehand-server/v*` GitHub Release in `browserbase/stagehand`), then publishes to PyPI.
+   - Builds platform wheels that embed the Stagehand server binary (downloaded from the latest `stagehand-server-v3/v*` GitHub Release in `browserbase/stagehand`), then publishes to PyPI.
 
 ## Important implementation notes
 
 - **Server binary bundling into wheels**
-  - `.github/workflows/publish-pypi.yml` downloads the prebuilt Stagehand server SEA binary from the latest `stagehand-server/v*` GitHub Release in `browserbase/stagehand`, then places it into `src/stagehand/_sea/*` before running `uv build --wheel`.
+  - `.github/workflows/publish-pypi.yml` downloads the prebuilt Stagehand server SEA binary from the latest `stagehand-server-v3/v*` GitHub Release in `browserbase/stagehand`, then places it into `src/stagehand/_sea/*` before running `uv build --wheel`.
 - **Stagehand server version selection (current behavior)**
-  - `publish-pypi.yml` resolves the latest GitHub Release tag matching `stagehand-server/v*` from `browserbase/stagehand` and downloads the matching `stagehand-server-<platform>` release asset for each wheel build.
+  - `publish-pypi.yml` resolves the latest GitHub Release tag matching `stagehand-server-v3/v*` from `browserbase/stagehand` and downloads the matching `stagehand-server-v3-<platform>` release asset for each wheel build.
 - **Secrets**
   - PyPI publish uses `secrets.STAGEHAND_PYPI_TOKEN || secrets.PYPI_TOKEN`.
   - `.github/workflows/release-doctor.yml` runs `bin/check-release-environment` on qualifying PRs and fails if `PYPI_TOKEN` is missing.

scripts/download-binary.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-Download the stagehand-server binary for local development.
+Download the stagehand-server-v3 binary for local development.
 
 This script downloads the appropriate binary for your platform from GitHub releases
 and places it in bin/sea/ for use during development and testing.
@@ -43,7 +43,7 @@ def get_platform_info() -> tuple[str, str]:
 
 def get_binary_filename(plat: str, arch: str) -> str:
     """Get the expected binary filename for this platform."""
-    name = f"stagehand-server-{plat}-{arch}"
+    name = f"stagehand-server-v3-{plat}-{arch}"
     return name + (".exe" if plat == "win32" else "")
 
 
@@ -53,11 +53,11 @@ def get_local_filename(plat: str, arch: str) -> str:
     return name + (".exe" if plat == "win32" else "")
 
 def _parse_server_tag(tag: str) -> tuple[int, int, int] | None:
-    # Expected: stagehand-server/vX.Y.Z
-    if not tag.startswith("stagehand-server/v"):
+    # Expected: stagehand-server-v3/vX.Y.Z
+    if not tag.startswith("stagehand-server-v3/v"):
         return None
 
-    ver = tag.removeprefix("stagehand-server/v")
+    ver = tag.removeprefix("stagehand-server-v3/v")
     # Drop any pre-release/build metadata (we only expect stable tags here).
     ver = ver.split("-", 1)[0].split("+", 1)[0]
     parts = ver.split(".")
@@ -86,7 +86,7 @@ def _http_get_json(url: str) -> Any:
 
 
 def resolve_latest_server_tag() -> str:
-    """Resolve the latest stagehand-server/v* tag from GitHub releases."""
+    """Resolve the latest stagehand-server-v3/v* tag from GitHub releases."""
     repo = "browserbase/stagehand"
     releases_url = f"https://api.github.com/repos/{repo}/releases?per_page=100"
     try:
@@ -113,7 +113,7 @@ def resolve_latest_server_tag() -> str:
             best = (parsed, tag)
 
     if best is None:
-        raise RuntimeError("No stagehand-server/v* GitHub Releases found for browserbase/stagehand")
+        raise RuntimeError("No stagehand-server-v3/v* GitHub Releases found for browserbase/stagehand")
 
     return best[1]
 
@@ -126,7 +126,7 @@ def download_binary(version: str) -> None:
 
     # GitHub release URL
     repo = "browserbase/stagehand"
-    tag = version if version.startswith("stagehand-server/v") else f"stagehand-server/{version}"
+    tag = version if version.startswith("stagehand-server-v3/v") else f"stagehand-server-v3/{version}"
     url = f"https://github.com/{repo}/releases/download/{tag}/{binary_filename}"
 
     # Destination path
@@ -186,13 +186,13 @@ def main() -> None:
 Examples:
   python scripts/download-binary.py
   python scripts/download-binary.py --version v3.2.0
-  python scripts/download-binary.py --version stagehand-server/v3.2.0
+  python scripts/download-binary.py --version stagehand-server-v3/v3.2.0
         """,
     )
     parser.add_argument(
         "--version",
         default=None,
-        help="Stagehand server release tag/version to download (e.g. v3.2.0 or stagehand-server/v3.2.0). Defaults to latest stagehand-server/* GitHub Release.",
+        help="Stagehand server release tag/version to download (e.g. v3.2.0 or stagehand-server-v3/v3.2.0). Defaults to latest stagehand-server-v3/* GitHub Release.",
     )
 
     args = parser.parse_args()