python: switch from bundled CLI wheels to download-at-first-use

Replace the platform-specific fat wheel approach (6 × ~90MB wheels per release)
with a single slim pure-Python wheel that downloads the CLI binary from GitHub
Releases on first use and caches it locally.

Key changes:
- New _cli_version.py: platform asset mapping, version sentinel (injected at
  publish time by inject-cli-version.mjs)
- New _cli_download.py: download, SHA-256 verify, extract, atomic cache logic
- New __main__.py: 'python -m copilot download-cli' pre-download command
- Updated client.py resolution chain: explicit > env var > downloaded (removed
  bundled binary fallback entirely)
- Updated publish.yml: single 'uv build --wheel' instead of build-wheels.mjs
- Removed build-wheels.mjs (old fat wheel builder)
- Updated docs to reflect Python's new download model

The cache directory is shared with the Rust SDK:
  Linux:   ~/.cache/github-copilot-sdk/cli/{version}/copilot
  macOS:   ~/Library/Caches/github-copilot-sdk/cli/{version}/copilot
  Windows: %LOCALAPPDATA%\github-copilot-sdk\cli\{version}\copilot.exe

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: SteveSandersonMS

.github/workflows/publish.yml

@@ -214,8 +214,10 @@ jobs:
         run: npm ci --ignore-scripts
       - name: Set version
         run: sed -i "s/^version = .*/version = \"${{ needs.version.outputs.version }}\"/" pyproject.toml
-      - name: Build platform wheels
-        run: node scripts/build-wheels.mjs --output-dir dist
+      - name: Inject CLI version
+        run: node scripts/inject-cli-version.mjs
+      - name: Build wheel
+        run: uv build --wheel --out-dir dist
       - name: Upload artifact
         uses: actions/upload-artifact@v7.0.0
         with:

docs/getting-started.md

@@ -18,7 +18,7 @@ Copilot: In Tokyo it's 75°F and sunny. Great day to be outside!
 
 Before you begin, make sure you have:
 
-* **GitHub Copilot CLI** installed and authenticated (the Node.js, Python, and .NET SDKs bundle the CLI automatically—see [Bundled CLI](./setup/bundled-cli.md). Required for Go, Java, and Rust unless using their application-level CLI bundling features.)
+* **GitHub Copilot CLI** installed and authenticated (the Node.js, Python, and .NET SDKs provide the CLI automatically—see [Bundled CLI](./setup/bundled-cli.md). Required for Go, Java, and Rust unless using their application-level CLI bundling features.)
 * Your preferred language runtime:
   * **Node.js** 20+ or **Python** 3.11+ or **Go** 1.24+ or **Rust** 1.94+ or **Java** 17+ or **.NET** 8.0+
 

docs/setup/bundled-cli.md

@@ -1,12 +1,20 @@
 # Default setup (bundled CLI)
 
-The Node.js, Python, and .NET SDKs include the Copilot CLI as a dependency—your app ships with everything it needs, with no extra installation or configuration required.
+The Node.js and .NET SDKs include the Copilot CLI as a dependency—your app ships with everything it needs, with no extra installation or configuration required.
+
+The Python SDK recommends a one-time download step after installation:
+
+```bash
+python -m copilot download-runtime
+```
+
+This downloads the matching runtime and caches it locally. If you skip this step, the SDK will attempt to download it automatically on first use as a fallback.
 
 **Best for:** Most applications—desktop apps, standalone tools, CLI utilities, prototypes, and more.
 
 ## How it works
 
-When you install the SDK, the Copilot CLI binary is included automatically. The SDK starts it as a child process and communicates over stdio. There's nothing extra to configure.
+When you install the SDK, the Copilot runtime is included automatically (Node.js, .NET) or downloaded via `python -m copilot download-runtime` (Python). The SDK starts it as a child process and communicates over stdio. There's nothing extra to configure.
 
 ```mermaid
 flowchart TB

docs/setup/local-cli.md

@@ -1,6 +1,6 @@
 # Local CLI setup
 
-Use a specific CLI binary instead of the SDK's bundled CLI. This is an advanced option—you supply the CLI path explicitly, and you are responsible for ensuring version compatibility with the SDK.
+Use a specific CLI binary instead of the SDK's automatic CLI management. This is an advanced option—you supply the CLI path explicitly, and you are responsible for ensuring version compatibility with the SDK.
 
 **Use when:** You need to pin a specific CLI version, or work with the Go SDK (which does not bundle a CLI).
 

python/.gitignore

@@ -169,6 +169,3 @@ uv.lock
 # Build script caches
 .cli-cache/
 .build-temp/
-
-# Bundled CLI binary (only in platform wheels, not in repo)
-copilot/bin/

python/README.md

@@ -20,6 +20,33 @@ To include OpenTelemetry support:
 pip install "github-copilot-sdk[telemetry]"
 ```
 
+## Runtime
+
+Published wheels include a pinned runtime version. After installing, download the
+runtime:
+
+```bash
+python -m copilot download-runtime
+```
+
+This caches the runtime binary locally. If you skip this step, the SDK will
+attempt to download it automatically on first use as a fallback.
+
+| Platform | Cache path |
+|----------|-----------|
+| Linux | `~/.cache/github-copilot-sdk/cli/<version>/copilot` |
+| macOS | `~/Library/Caches/github-copilot-sdk/cli/<version>/copilot` |
+| Windows | `%LOCALAPPDATA%\github-copilot-sdk\cli\<version>\copilot.exe` |
+
+### Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `COPILOT_CLI_PATH` | Use this specific binary instead of downloading |
+| `COPILOT_CLI_CACHE_DIR` | Override the default cache directory (version subdirectory still appended) |
+| `COPILOT_SKIP_CLI_DOWNLOAD` | Set to `1` to disable auto-download |
+| `COPILOT_CLI_DOWNLOAD_BASE_URL` | Override the GitHub Releases download URL |
+
 ## Run the Sample
 
 Try the interactive chat sample (from the repo root):

python/copilot/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m copilot`."""
+
+from ._cli_download import main
+
+if __name__ == "__main__":
+    main()