PLAT-424: automate high-assurance Fleet SDK releases

.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: SDK CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: sdk-ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: warp-ubuntu-latest-x64-4x
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@v8.3.2
+        with:
+          enable-cache: true
+      - run: uv sync --extra dev --extra cli --locked
+      - run: uv run --locked pytest
+
+  package:
+    name: Build and inspect distributions
+    runs-on: warp-ubuntu-latest-x64-4x
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v8.3.2
+        with:
+          enable-cache: true
+      - run: uv build --no-sources
+      - run: uvx twine check dist/*
+      - name: Verify package metadata
+        run: |
+          VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          python scripts/validate-release-artifacts.py --version "$VERSION"
+      - name: Smoke-test the wheel and source distribution
+        run: |
+          uv run --isolated --no-project --with dist/*.whl python -c "import fleet; print(fleet.__version__)"
+          uv run --isolated --no-project --with dist/*.tar.gz python -c "import fleet; print(fleet.__version__)"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: fleet-python-sdk-dist-${{ github.sha }}
+          path: dist/
+          if-no-files-found: error
+          retention-days: 14

.github/workflows/release.yml

@@ -0,0 +1,113 @@
+name: Release Fleet Python SDK
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: fleet-python-release
+  cancel-in-progress: false
+
+jobs:
+  release_please:
+    runs-on: warp-ubuntu-latest-x64-4x
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+      version: ${{ steps.release.outputs.version }}
+      release_sha: ${{ steps.release.outputs.sha }}
+    steps:
+      - id: release
+        uses: googleapis/release-please-action@v5
+        with:
+          # A GitHub App/PAT token is required so the bot's release PR runs CI.
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  test-build-publish:
+    if: ${{ needs.release_please.outputs.release_created == 'true' }}
+    needs: release_please
+    runs-on: warp-ubuntu-latest-x64-4x
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ needs.release_please.outputs.release_sha }}
+          fetch-depth: 0
+      - name: Fetch canonical main and release tag
+        run: git fetch --force origin "main:refs/remotes/origin/main" "refs/tags/${{ needs.release_please.outputs.tag_name }}:refs/tags/${{ needs.release_please.outputs.tag_name }}"
+      - name: Validate tag, version, and main ancestry
+        run: scripts/validate-release-tag.sh "${{ needs.release_please.outputs.tag_name }}"
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v8.3.2
+        with:
+          enable-cache: true
+      - name: Run the full SDK suite at the tagged commit
+        run: |
+          uv sync --extra dev --extra cli --locked
+          uv run --locked pytest
+      - name: Build the publishable artifacts once
+        run: uv build --no-sources
+      - run: uvx twine check dist/*
+      - name: Verify exact artifact versions
+        run: python scripts/validate-release-artifacts.py --version "${{ needs.release_please.outputs.version }}"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: fleet-python-${{ needs.release_please.outputs.version }}
+          path: dist/
+          if-no-files-found: error
+          retention-days: 90
+      - name: Publish the tested artifacts through PyPI Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@v1.14.1
+        with:
+          packages-dir: dist/
+
+  finalize-github-release:
+    if: ${{ needs.release_please.outputs.release_created == 'true' }}
+    needs: [release_please, test-build-publish]
+    runs-on: warp-ubuntu-latest-x64-4x
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: fleet-python-${{ needs.release_please.outputs.version }}
+          path: dist/
+      - name: Attach artifacts and publish the draft GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ needs.release_please.outputs.tag_name }}
+        run: |
+          gh release upload "$RELEASE_TAG" dist/* --clobber --repo "$GITHUB_REPOSITORY"
+          gh release edit "$RELEASE_TAG" --draft=false --verify-tag --repo "$GITHUB_REPOSITORY"
+
+  notify-internal-consumers:
+    if: ${{ needs.release_please.outputs.release_created == 'true' }}
+    needs: [release_please, finalize-github-release]
+    runs-on: warp-ubuntu-latest-x64-4x
+    steps:
+      - name: Request a separate Theseus consumer update PR
+        env:
+          GH_TOKEN: ${{ secrets.FLEET_SDK_CONSUMER_TOKEN }}
+          VERSION: ${{ needs.release_please.outputs.version }}
+          TAG: ${{ needs.release_please.outputs.tag_name }}
+        run: |
+          if [ -z "$GH_TOKEN" ]; then
+            echo "::error::FLEET_SDK_CONSUMER_TOKEN must be configured for cross-repository updates"
+            exit 1
+          fi
+          gh api --method POST repos/fleet-ai/theseus/dispatches \
+            -f event_type=fleet-sdk-released \
+            -f "client_payload[version]=$VERSION" \
+            -f "client_payload[tag]=$TAG"

.release-please-manifest.json

@@ -0,0 +1,4 @@
+{
+  ".": "0.2.132"
+}
+

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help install-dev build test clean publish-to-pypi validate-tag unasync
+.PHONY: help install-dev build test clean validate-tag unasync release-help
 
 # Use the active Python interpreter (python3 preferred, fallback to python)
 PYTHON ?= $(shell command -v python3 || command -v python)
@@ -11,7 +11,7 @@ help:
 	@echo "test           Run tests"
 	@echo "clean          Clean build artifacts"
 	@echo "validate-tag   Validate release tag format"
-	@echo "publish-to-pypi Publish package to PyPI"
+	@echo "release-help    Show the automated release process"
 	@echo "unasync        Generate sync code from async sources"
 
 install-dev:
@@ -81,18 +81,10 @@ validate-tag:
 	fi
 	./scripts/validate-release-tag.sh $(TAG)
 
-publish-to-pypi: build
-	@echo "⚠️  Warning: Direct publishing is deprecated for security reasons"
-	@echo "🔒 Recommended: Use GitHub Actions workflow with OIDC authentication"
-	@echo "📋 To publish via GitHub Actions:"
-	@echo "   1. Ensure PyPI Trusted Publisher is configured"
-	@echo "   2. Create release tag: git tag fleet-python-v<VERSION>"
-	@echo "   3. Push tag: git push origin fleet-python-v<VERSION>"
-	@echo ""
-	@echo "Proceeding with direct upload in 5 seconds..."
-	@sleep 5
-	twine check dist/*
-	twine upload dist/*
+release-help:
+	@echo "Fleet SDK releases are automated from protected main."
+	@echo "Merge the reviewed Release Please PR; do not create or push tags manually."
+	@echo "See docs/releases.md for gates, configuration, retry, and rollback guidance."
 
 # Local development
 dev-setup: install-dev

docs/releases.md

@@ -0,0 +1,24 @@
+# Fleet Python SDK releases
+
+Fleet SDK releases originate only from protected `main`.
+
+1. Release Please opens or updates a release PR containing the version bump and `CHANGELOG.md`.
+2. Required SDK CI tests Python 3.9–3.14 and builds, inspects, installs, and retains the wheel and sdist.
+3. Merging the approved release PR makes Release Please create the immutable `fleet-python-vX.Y.Z` tag and a draft GitHub release.
+4. The release workflow checks out that exact commit, proves the tag is on `origin/main`, reruns the full suite, builds once, verifies both artifact versions, and publishes those files through the protected `pypi` environment using OIDC Trusted Publishing.
+5. Only after PyPI succeeds does automation attach the artifacts, publish the GitHub release, and dispatch a separate Theseus consumer-update PR.
+
+## Required repository configuration
+
+- Protect `main` and require all `SDK CI` jobs plus review approval.
+- Admit `fleet-ai/fleet-sdk` to the WarpBuild runner group, then set repository variable `WARPBUILD_RUNNER` to `warp-ubuntu-latest-x64-4x`. Workflows fall back to `ubuntu-latest` while that integration is unavailable instead of remaining queued indefinitely.
+- Configure the `pypi` GitHub environment with required reviewers and PyPI Trusted Publisher subject `fleet-ai/fleet-sdk`, workflow `.github/workflows/release.yml`, environment `pypi`.
+- Set `RELEASE_PLEASE_TOKEN` to a narrowly scoped GitHub App token or fine-grained PAT that can update release PRs and contents. The bot-authored PR must trigger required CI.
+- Set `FLEET_SDK_CONSUMER_TOKEN` to a narrowly scoped token allowed only to dispatch the `fleet-sdk-released` event to `fleet-ai/theseus`.
+
+## Failure and retry policy
+
+- A failed test, build, metadata check, environment approval, or PyPI upload leaves the GitHub release in draft. Fix forward; do not move or recreate the immutable tag.
+- PyPI versions are immutable. If PyPI accepted the files but a later GitHub/consumer step failed, rerun only the failed job or finalize the existing draft release; do not republish the version.
+- If failure happens before PyPI accepts the files, rerun the failed workflow job at the same tagged SHA. The retained workflow artifact is evidence; the publish job still rebuilds and verifies from the tag before uploading.
+- To roll back a defective release, publish a new patch release. Never delete or retarget a published tag.

fleet/__init__.py

@@ -26,6 +26,8 @@
 )
 from .client import Fleet, SyncEnv, Session
 from ._async.client import AsyncFleet, AsyncEnv, AsyncSession
+from .browser import BrowserLease, host_from_url
+from ._async.browser import AsyncBrowserLease
 from .models import InstanceResponse, Environment, Run
 from .instance.models import Resource, ResetResponse
 
@@ -79,14 +81,18 @@
 from . import global_client as _global_client
 from ._async import global_client as _async_global_client
 
-__version__ = "0.2.124"
+__version__ = "0.2.132"  # x-release-please-version
 
 __all__ = [
     # Core classes
     "Fleet",
     "SyncEnv",
     "AsyncFleet",
     "AsyncEnv",
+    # Browser lease (orchestrator-managed /v1/browser)
+    "BrowserLease",
+    "AsyncBrowserLease",
+    "host_from_url",
     # Models
     "InstanceResponse",
     "SyncEnv",

fleet/_async/__init__.py

@@ -44,7 +44,7 @@
 from .. import env
 from . import global_client as _async_global_client
 
-__version__ = "0.2.124"
+__version__ = "0.2.132"  # x-release-please-version
 
 __all__ = [
     # Core classes