python: add in-process (FFI) transport

Implement the in-process (FFI) transport for the Python SDK at parity with
the .NET/Rust/TypeScript implementations. Instead of spawning the runtime as
a child process, the SDK loads the runtime's native shared library into the
host process (via stdlib ctypes) and drives JSON-RPC over its C ABI; the
native host spawns the residual worker itself.

- api: RuntimeConnection.for_inprocess() + InProcessRuntimeConnection; add a
  per-connection env field to ChildProcessRuntimeConnection (stdio/tcp).
- default transport: honor COPILOT_SDK_DEFAULT_CONNECTION=inprocess.
- ffi host: new copilot/_ffi_runtime_host.py (ctypes bindings, outbound
  callback with drain/lifetime guarding, RTLD_NOW load, process-like adapter
  so JsonRpcClient works unchanged).
- client wiring: start/stop/force_stop route through the FFI host.
- env guards: reject env/telemetry/working_directory with in-process, and
  reject env set on both client and connection for child-process transports.
- bundling: fetch the native runtime library only opt-in — via
  `download-runtime --in-process` or lazily on first in-process use; never for
  stdio/tcp users.
- tests: in-process E2E smoke test; harness honors the inprocess default with
  env mirroring + cwd redirect; conftest neutralizes ambient HMAC for
  in-process; CI transport matrix cell.
- docs: python/README.md in-process section; APIs flagged experimental.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: a96d1a82-c80e-40f1-a3df-a9708429b68b

Author: SteveSandersonMS

.github/workflows/python-sdk-tests.yml

@@ -31,7 +31,7 @@ permissions:
 
 jobs:
   test:
-    name: "Python SDK Tests"
+    name: "Python SDK Tests (${{ matrix.os }}, ${{ matrix.transport }})"
     if: github.event.repository.fork == false
     env:
       POWERSHELL_UPDATECHECK: Off
@@ -41,6 +41,7 @@ jobs:
         os: [ubuntu-latest, macos-latest, windows-latest]
         # Test the oldest supported Python version to make sure compatibility is maintained.
         python-version: ["3.11"]
+        transport: ["default", "inprocess"]
     runs-on: ${{ matrix.os }}
     defaults:
       run:
@@ -86,6 +87,11 @@ jobs:
         if: runner.os == 'Windows'
         run: pwsh.exe -Command "Write-Host 'PowerShell ready'"
 
+      - name: Select inprocess transport
+        if: matrix.transport == 'inprocess'
+        run: |
+          echo "COPILOT_SDK_DEFAULT_CONNECTION=inprocess" >> "$GITHUB_ENV"
+
       - name: Run Python SDK tests
         env:
           COPILOT_HMAC_KEY: ${{ secrets.COPILOT_DEVELOPER_CLI_INTEGRATION_HMAC_KEY }}

python/README.md

@@ -32,6 +32,17 @@ 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.
 
+To pre-provision the native library required by the in-process (FFI) transport
+(see [In-process (FFI) transport](#in-process-ffi-transport)), pass `--in-process`:
+
+```bash
+python -m copilot download-runtime --in-process
+```
+
+This additionally fetches the native runtime shared library and places it next to
+the cached binary. Stdio/TCP users never download it. When omitted, the library is
+downloaded lazily on first use of the in-process transport.
+
 | Platform | Cache path |
 |----------|-----------|
 | Linux | `~/.cache/github-copilot-sdk/cli/<version>/copilot` |
@@ -136,7 +147,7 @@ asyncio.run(main())
 ## Features
 
 - ✅ Full JSON-RPC protocol support
-- ✅ stdio and TCP transports
+- ✅ stdio, TCP, and in-process (FFI) transports
 - ✅ Real-time streaming events
 - ✅ Session history with `get_events()`
 - ✅ Type hints throughout
@@ -184,8 +195,9 @@ CopilotClient(connection=..., log_level="debug", github_token=..., ...)
 All options are kw-only parameters:
 
 - `connection` (RuntimeConnection | None): How to reach the runtime. Use
-  `RuntimeConnection.for_stdio(...)`, `RuntimeConnection.for_tcp(...)`, or
-  `RuntimeConnection.for_uri(...)`. Defaults to a stdio connection with the bundled binary.
+  `RuntimeConnection.for_stdio(...)`, `RuntimeConnection.for_tcp(...)`,
+  `RuntimeConnection.for_uri(...)`, or `RuntimeConnection.for_inprocess(...)`.
+  Defaults to a stdio connection with the bundled binary.
 - `working_directory` (str | None): Working directory for the CLI process (default: current dir).
 - `log_level` (str): Log level (default: "info").
 - `env` (dict | None): Environment variables for the CLI process.
@@ -204,6 +216,49 @@ All options are kw-only parameters:
 - `RuntimeConnection.for_stdio(path=None, args=None)` — spawn a local CLI process and talk over stdio.
 - `RuntimeConnection.for_tcp(port=0, connection_token=None, path=None, args=None)` — spawn a local CLI in TCP mode.
 - `RuntimeConnection.for_uri(url, connection_token=None)` — connect to an existing CLI server (e.g. `"localhost:8080"`).
+- `RuntimeConnection.for_inprocess(path=None, args=None)` — host the runtime in-process via its native C ABI (FFI). See [In-process (FFI) transport](#in-process-ffi-transport).
+
+Child-process connections (`for_stdio`/`for_tcp`) also expose a per-connection
+`env` field for the spawned process. Set it on the returned connection instead of
+the client-level `env` — setting both raises:
+
+```python
+conn = RuntimeConnection.for_stdio()
+conn.env = {"MY_VAR": "value"}
+client = CopilotClient(connection=conn)  # do NOT also pass env=... here
+```
+
+### In-process (FFI) transport
+
+> ⚠️ **Experimental.** The in-process transport loads the runtime's native shared
+> library into your process and drives JSON-RPC over its C ABI (via stdlib
+> `ctypes`), instead of spawning a child process. The native host spawns the
+> residual worker itself.
+
+```python
+from copilot import CopilotClient, RuntimeConnection
+
+client = CopilotClient(connection=RuntimeConnection.for_inprocess())
+await client.start()
+try:
+    pong = await client.ping("hello")
+    print(pong.message)
+finally:
+    await client.stop()
+```
+
+**Requirements & behavior:**
+
+- Requires the native runtime library next to the CLI. Pre-provision it with
+  `python -m copilot download-runtime --in-process`, or let the SDK download it
+  lazily on first use of this transport.
+- Because the runtime shares this single host process, per-client options that
+  lower to environment variables or a working directory **cannot** be honored and
+  are rejected: `env`, `telemetry`, and `working_directory` all raise `ValueError`
+  with `for_inprocess()`. Set the corresponding values on the host process
+  environment / working directory before creating the client instead.
+- Set `COPILOT_SDK_DEFAULT_CONNECTION=inprocess` to select the in-process
+  transport by default when no explicit `connection` is supplied.
 
 **`CopilotClient.create_session()`:**
 

python/copilot/__init__.py

@@ -36,6 +36,7 @@
     CopilotClient,
     GetAuthStatusResponse,
     GetStatusResponse,
+    InProcessRuntimeConnection,
     LogLevel,
     ModelBilling,
     ModelCapabilities,
@@ -235,6 +236,7 @@
     "GitHubTelemetryEvent",
     "GitHubTelemetryNotification",
     "InfiniteSessionConfig",
+    "InProcessRuntimeConnection",
     "InputOptions",
     "LargeToolOutputConfig",
     "LlmInferenceHeaders",

python/copilot/_cli_download.py

@@ -16,6 +16,7 @@
 
 from __future__ import annotations
 
+import base64
 import hashlib
 import io
 import os
@@ -35,6 +36,9 @@
     get_asset_info,
     get_checksums_url,
     get_download_url,
+    get_npm_platform,
+    get_runtime_lib_packument_url,
+    get_runtime_lib_url,
 )
 
 _CACHE_DIR_NAME = "github-copilot-sdk"
@@ -304,6 +308,137 @@ def download_cli(version: str | None = None, *, force: bool = False) -> str:
     return str(binary_path)
 
 
+def _fetch_url_bytes(url: str, *, timeout: int) -> bytes:
+    """Download bytes from ``url`` with retries."""
+    last_exc: Exception | None = None
+    for attempt in range(_MAX_RETRIES):
+        try:
+            with urlopen(url, timeout=timeout) as response:
+                return response.read()
+        except (HTTPError, URLError) as exc:
+            last_exc = exc
+            if attempt < _MAX_RETRIES - 1:
+                time.sleep(2**attempt)
+    raise RuntimeError(f"Failed to download from {url}: {last_exc}") from last_exc
+
+
+def _fetch_runtime_integrity(npm_platform: str, version: str) -> str | None:
+    """Return the npm ``dist.integrity`` (Subresource Integrity) for the tarball.
+
+    Best-effort: returns None if the packument can't be fetched or parsed.
+    """
+    import json
+
+    url = get_runtime_lib_packument_url(npm_platform)
+    try:
+        raw = _fetch_url_bytes(url, timeout=30)
+        packument = json.loads(raw)
+        dist = packument.get("versions", {}).get(version, {}).get("dist", {})
+        integrity = dist.get("integrity")
+        return integrity if isinstance(integrity, str) else None
+    except (RuntimeError, ValueError, KeyError):
+        return None
+
+
+def _verify_integrity(data: bytes, integrity: str) -> None:
+    """Verify data against an npm Subresource Integrity string (e.g. ``sha512-<b64>``)."""
+    algo, _, b64 = integrity.partition("-")
+    algo = algo.lower()
+    if algo not in ("sha512", "sha384", "sha256"):
+        return  # Unknown/unsupported algorithm — skip rather than fail.
+    expected = base64.b64decode(b64)
+    actual = hashlib.new(algo, data).digest()
+    if actual != expected:
+        raise RuntimeError(
+            f"Integrity mismatch for runtime library ({algo}): "
+            "downloaded tarball does not match the npm registry checksum."
+        )
+
+
+def _extract_runtime_node(data: bytes, npm_platform: str) -> bytes:
+    """Extract ``package/prebuilds/<npm_platform>/runtime.node`` from an npm tarball."""
+    target = f"package/prebuilds/{npm_platform}/runtime.node"
+    with tarfile.open(fileobj=io.BytesIO(data), mode="r:gz") as tf:
+        for name in tf.getnames():
+            if name == target or name.endswith(f"/prebuilds/{npm_platform}/runtime.node"):
+                member = tf.getmember(name)
+                extracted = tf.extractfile(member)
+                if extracted is not None:
+                    return extracted.read()
+        raise RuntimeError(f"'{target}' not found in runtime package for {npm_platform}.")
+
+
+def ensure_runtime_library(cli_path: str, version: str | None = None) -> str | None:
+    """Ensure the native in-process (FFI) runtime library sits next to ``cli_path``.
+
+    The library is NOT part of the GitHub Releases CLI archive; it ships in the npm
+    platform package ``@github/copilot-<platform>`` under
+    ``package/prebuilds/<platform>/runtime.node``. This helper downloads that tarball
+    and writes the library next to the CLI binary under its natural platform name
+    (``libcopilot_runtime.so`` / ``.dylib`` / ``copilot_runtime.dll``).
+
+    This is opt-in — only invoked when the in-process transport is actually selected
+    (lazy) or via ``python -m copilot download-runtime --in-process`` (explicit). The
+    default stdio download path never fetches these extra bytes.
+
+    Returns the absolute path to the library, or None if it could not be provisioned
+    (e.g. download disabled or unsupported platform). Raises RuntimeError on
+    download/verification failure.
+    """
+    # Import lazily to avoid a hard dependency for stdio-only users.
+    from ._ffi_runtime_host import _natural_library_name, resolve_library_path
+
+    # Already present (bundled prebuilds layout in dev, or a prior download)?
+    existing = resolve_library_path(cli_path)
+    if existing is not None:
+        return existing
+
+    if _should_skip_download():
+        return None
+
+    ver = version or CLI_VERSION
+    if not ver:
+        return None
+
+    try:
+        npm_platform = get_npm_platform()
+    except RuntimeError:
+        return None
+
+    cli_dir = Path(cli_path).resolve().parent
+    lib_path = cli_dir / _natural_library_name()
+    if lib_path.exists():
+        return str(lib_path)
+
+    url = get_runtime_lib_url(ver, npm_platform)
+    data = _fetch_url_bytes(url, timeout=600)
+
+    integrity = _fetch_runtime_integrity(npm_platform, ver)
+    if integrity:
+        _verify_integrity(data, integrity)
+
+    lib_bytes = _extract_runtime_node(data, npm_platform)
+
+    # Write atomically next to the CLI so concurrent starts don't observe a partial
+    # library. A rename within the same directory is atomic on POSIX and Windows.
+    cli_dir.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(dir=cli_dir, prefix=".runtime-lib-")
+    try:
+        with os.fdopen(fd, "wb") as out:
+            out.write(lib_bytes)
+        os.replace(tmp_name, lib_path)
+    except OSError:
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        if lib_path.exists():
+            return str(lib_path)
+        raise
+
+    return str(lib_path)
+
+
 def get_or_download_cli(version: str | None = None) -> str | None:
     """Get the cached CLI binary, downloading it if necessary.
 
@@ -361,6 +496,15 @@ def main() -> None:
         "--version",
         help="Runtime version to download (default: pinned version)",
     )
+    dl_parser.add_argument(
+        "--in-process",
+        action="store_true",
+        help=(
+            "Also download the native in-process (FFI) runtime library "
+            "(prebuilds/<platform>/runtime.node) and place it next to the CLI. "
+            "Only needed for the experimental in-process transport."
+        ),
+    )
 
     args = parser.parse_args()
 
@@ -378,6 +522,17 @@ def main() -> None:
         try:
             path = download_cli(ver, force=args.force)
             print(f"Runtime cached at: {path}")
+            if args.in_process:
+                print("Downloading in-process (FFI) runtime library...")
+                lib_path = ensure_runtime_library(path, ver)
+                if lib_path:
+                    print(f"Runtime library cached at: {lib_path}")
+                else:
+                    print(
+                        "Warning: could not provision the in-process runtime library "
+                        "(download disabled or unsupported platform).",
+                        file=sys.stderr,
+                    )
         except RuntimeError as exc:
             print(f"Error: {exc}", file=sys.stderr)
             sys.exit(1)