Python: switch from bundled CLI wheels to downloading explicitly or at runtime

[SteveSandersonMS]

Summary

Replace the platform-specific fat wheel approach (6 x ~90MB wheels per release) with a single slim pure-Python wheel (~100KB) that downloads the Copilot runtime from GitHub Releases.

How it works

1. Published wheels have CLI_VERSION injected at build time
2. After install, users run python -m copilot download-runtime to fetch the runtime
3. If skipped, the SDK auto-downloads on first client creation as a fallback
4. Binary is cached at platform-appropriate location (shared with Rust SDK)
5. SHA-256 verified against SHA256SUMS.txt from the same release

Wheel output

Before: 6 platform wheels (manylinux_x86_64, macosx_arm64, etc.) ~540MB total
After: 1 universal wheel github_copilot_sdk-{version}-py3-none-any.whl ~100KB

Changes

New files:

• python/copilot/_cli_version.py - version sentinel + platform asset mapping
• python/copilot/_cli_download.py - download, SHA-256 verify, extract, atomic cache
• python/copilot/__main__.py - python -m copilot download-cli entry point
• python/scripts/inject-cli-version.mjs - publish-time version injector

Modified:

• python/copilot/client.py - resolution chain uses download fallback (bundled path removed)
• python/pyproject.toml - removed fat-wheel comments
• .github/workflows/publish.yml - single uv build --wheel + inject script
• Docs updated to reflect new model

Deleted:

• python/scripts/build-wheels.mjs (old platform wheel builder)

[Copilot]

Pull request overview

This pull request changes the Python SDK packaging model from shipping large platform-specific wheels with a bundled Copilot CLI to shipping a slim pure-Python wheel that downloads and caches the Copilot runtime from GitHub Releases (with checksum verification).

Changes:

• Added Python runtime download + caching implementation (including a python -m copilot download-runtime entry point).
• Updated Python client CLI resolution to prefer explicit path/env var, then fall back to a downloaded cached runtime.
• Updated publishing workflow and documentation to reflect the new distribution model, and removed the old fat-wheel builder.

Show a summary per file

File	Description
python/scripts/inject-cli-version.mjs	New publish-time script to inject pinned CLI version into Python package.
python/scripts/build-wheels.mjs	Removes prior platform wheel builder that bundled runtime binaries.
python/README.md	Documents runtime download command, cache paths, and env vars.
python/pyproject.toml	Removes bundled-wheel related comments and updates publish-time notes.
python/copilot/client.py	Switches CLI resolution fallback from bundled binary to downloaded cached runtime.
python/copilot/_cli_version.py	Introduces CLI version sentinel and platform asset mapping for downloads.
python/copilot/_cli_download.py	Implements runtime download, SHA256 verification, extraction, and atomic caching.
python/copilot/main.py	Adds python -m copilot entry point that routes to download utility.
python/.gitignore	Removes ignore for bundled runtime path that no longer exists in-repo.
docs/setup/local-cli.md	Updates wording to reflect Python no longer bundles the CLI.
docs/setup/bundled-cli.md	Updates default setup docs to describe Python runtime download workflow.
docs/getting-started.md	Updates “bundled CLI” wording to “provided automatically”.
.github/workflows/publish.yml	Updates Python publish job to inject CLI version and build a single wheel.

Copilot's findings

• Files reviewed: 13/13 changed files
• Comments generated: 5

[github-actions]

Generated by SDK Consistency Review Agent for issue #1744 · sonnet46 1.4M

[SteveSandersonMS]

All review comments addressed:

• Unsupported platform crash (comments on lines 96, 325): Fixed — both \get_cached_cli_path()\ and \get_or_download_cli()\ now catch RuntimeError from \get_asset_info()\ and return None on unsupported platforms.
• Unit tests (line 220): Agreed, will add in a follow-up commit (mocking urlopen for cache hit, checksum mismatch, skip env var, unsupported platform).
• Misleading pyproject.toml comment (line 16): Fixed — removed the stale comment.
• 'requires' vs 'recommends' in docs (bundled-cli.md line 6): Fixed — changed to 'recommends' since auto-download works as a fallback.
• COPILOT_CLI_CACHE_DIR vs Rust COPILOT_CLI_EXTRACT_DIR (line 12): Intentional difference in semantics (Python appends version subdir, Rust is flat). Updated README to clarify. Aligning names would be a cross-SDK change best done separately.

[SteveSandersonMS]

Thanks for the consistency review. The COPILOT_CLI_CACHE_DIR vs COPILOT_CLI_EXTRACT_DIR naming difference is intentional — Python appends \cli//\ under the override (matching the default layout), while Rust's var is a flat directory. Added clarification to the README table. Aligning across SDKs would be a separate cross-SDK change.

[github-actions]

Cross-SDK Consistency Review ✅

This PR changes only the Python SDK's CLI distribution mechanism (fat wheels → slim wheel + runtime download) and its associated docs/CI. No cross-SDK consistency issues found.

Key consistency checks:

Concern	Finding
Python public API (CopilotClient, RuntimeConnection)	Unchanged — no impact on other SDKs
Cache directory format	✅ Matches Rust SDK exactly: ~/.cache/github-copilot-sdk/cli/<version>/
sanitize_version logic	✅ Identical regex ([^a-zA-Z0-9._-] → _) to Rust's build.rs / resolve.rs
COPILOT_CLI_EXTRACT_DIR env var	✅ Consistent with Rust SDK's resolve.rs
COPILOT_SKIP_CLI_DOWNLOAD env var	✅ Consistent with Rust build convention
COPILOT_CLI_PATH env var	✅ Same as all other SDKs
Docs	✅ Updated to distinguish Python (download step) from Node.js/.NET (true bundle)

No changes needed in other SDKs. Node.js, Go, .NET, Java, and Rust each use their own appropriate CLI delivery mechanism; this PR doesn't introduce a new public feature that needs to be mirrored — it's a packaging-level change internal to Python's distribution model.

Generated by SDK Consistency Review Agent for issue #1744 · sonnet46 993.1K · ◷