[Python] No supported install-time delivery of the native runtime via pip/uv

[larohra]

Summary

Installing github-copilot-sdk with pip or uv installs a pure-Python wheel that contains no native Copilot runtime assets. The pinned runtime is acquired either by an explicit python -m copilot download-runtime step or lazily at first managed client construction. There is no supported way for the install command itself — including when the SDK is pulled in as another package's optional-extra dependency — to deliver the runtime.

On cold serverless workers, the lazy path adds unpredictable startup network and extraction time to the first request.

Current behavior (as of the versions below)

• python/pyproject.toml declares only Python dependencies plus a telemetry extra. There is no native-runtime distribution dependency, no [project.scripts], no setup.py, and no build hook.
• python/README.md documents python -m copilot download-runtime as a post-install step, with automatic staging on first managed stdio/TCP use if it is skipped.
• copilot/client.py resolves the runtime as explicit path → COPILOT_CLI_PATH → ensure_runtime_wrapper(), so an unconfigured client downloads on construction. The in-process (FFI) path resolves through the same helper.
• copilot/_cli_download.py downloads the pinned platform release package, verifies it against the release SHA256SUMS.txt, and stages it under a per-user cache directory (COPILOT_CLI_EXTRACT_DIR / XDG_CACHE_HOME override the location).

Version context: published Python SDK 1.0.14 pairs with native runtime 1.0.85 / protocol 3. Published 1.0.15 documentation still describes the download-runtime-then-lazy-fallback model.

Why the existing workarounds are insufficient

Wheel extras declare distribution dependencies; they cannot express an installation-time action. PEP 517 hooks run when building an sdist, not when installing a prebuilt wheel, and neither pip nor uv offers a supported post-install hook. A setup.py or import-time download workaround would be unreliable and would hide network I/O from hermetic builds, so it is explicitly not what this issue asks for.

That leaves a separate build-stage python -m copilot download-runtime invocation. This works, but it pushes a correctness burden onto every deployment:

• The prefetch must run on a host whose OS, architecture, and C library match the deployment target.
• The resulting cache must be staged into the deployed filesystem at the path the runtime process will read, with the right permissions. A build-stage user cache or a discarded CI layer does not satisfy this.
• Platforms that separate the deployment builder from the runtime filesystem need explicit cache-path coordination (for example, a consistent COPILOT_CLI_EXTRACT_DIR).

Packages that depend on the SDK through their own optional extra (your-package[copilot]) cannot offer their users a single-command install that is ready to run.

Request

A first-class, supported way to obtain the native runtime as part of installation — for example platform-specific distributions selected by wheel tags and declared as dependencies (optionally behind an extra), or another packaging mechanism the maintainers consider appropriate. The specific design is deliberately left open.

If install-time delivery is intentionally out of scope, a documented supported contract for build-time staging would still help: a stable, documented cache layout, a command to stage into an explicit target directory, and guidance for builder-versus-runtime filesystem separation.

This issue does not assert any redistribution rights for the runtime; licensing and distribution terms are for the maintainers to determine.

Related

• [v2] Consolidate runtime discovery, acquisition, and embedding #2524 — [v2] Consolidate runtime discovery, acquisition, and embedding covers runtime acquisition and packaging convergence across SDKs, but not Python install-time delivery through pip/uv or extras. Filing separately so this gap is not lost; close as duplicate if it is folded into that work.
• pip install github-copilot-sdk>=0.1.23 fails on Alpine Linux (musl) — no compatible wheel or sdist published #591 — musl wheel availability (closed), a related but distinct packaging concern.

Notes

Reported by an SDK consumer evaluating the Python SDK for a serverless agent runtime. Consumer code currently keeps the lazy download path; no workaround is being requested here, only upstream tracking.