microsoft
diff --git a/‎MIGRATION.md‎
Lines changed: 131 additions & 0 deletions b/‎MIGRATION.md‎
Lines changed: 131 additions & 0 deletions
diff --git a/‎README.md‎
Lines changed: 13 additions & 8 deletions b/‎README.md‎
Lines changed: 13 additions & 8 deletions
diff --git a/‎amplifier_module_provider_github_copilot/__init__.py‎
Lines changed: 98 additions & 31 deletions b/‎amplifier_module_provider_github_copilot/__init__.py‎
Lines changed: 98 additions & 31 deletions
diff --git a/‎amplifier_module_provider_github_copilot/config/_paths.py‎
Lines changed: 1 addition & 2 deletions b/‎amplifier_module_provider_github_copilot/config/_paths.py‎
Lines changed: 1 addition & 2 deletions
@@ -1,3 +1,134 @@
+# Migration Guide: v2.2.x → v2.3.0
+
+## Overview
+
+v2.3.0 raises the `github-copilot-sdk` requirement and tightens the
+environment variables the provider forwards to the SDK runtime. The
+provider's public surface (`mount`, `GitHubCopilotProvider`, entry point,
+version, documented configuration env vars
+`AMPLIFIER_PROVIDER_GITHUB_COPILOT_HOME` / `GITHUB_TOKEN`) is unchanged.
+
+User-visible changes:
+
+1. SDK requirement is now `github-copilot-sdk==1.0.0b10`.
+2. `COPILOT_CLI_PATH` is no longer honored.
+3. `COPILOT_HOME` is no longer honored.
+4. Ambient `COPILOT_SDK_AUTH_TOKEN` is no longer forwarded to the SDK runtime.
+
+---
+
+## What Changed
+
+### 1. SDK requirement: `github-copilot-sdk==1.0.0b10`
+
+- **What:** The provider now requires `github-copilot-sdk==1.0.0b10`. On
+  import, the provider checks the installed SDK version and raises a
+  clear `ImportError` if the installed version is older. The bump from
+  b9 to b10 adds 9 new `MinimalMode` session-config pins (MUST:7-15:
+  `enable_session_store`, `enable_skills`, `enable_file_hooks`,
+  `enable_host_git_operations`, `enable_on_demand_instruction_discovery`,
+  `skip_embedding_retrieval`, `embedding_cache_storage`,
+  `enable_session_telemetry`, `mcp_oauth_token_storage`) so the SDK's
+  defense-in-depth defaults are pinned explicitly. Wire-shape change only — no
+  provider API change.
+- **Behavior on upgrade:** Older SDK installs (`1.0.0b4`–`b9`) raise an
+  actionable error at provider import time that names the required
+  version and the install command.
+- **Replacement:** Reinstall through Amplifier
+  (`amplifier provider install --force github-copilot`), or pin manually:
+  `pip install 'github-copilot-sdk==1.0.0b10'`.
+- **Rollback:** Pin provider `==2.2.0` with `github-copilot-sdk==1.0.0b4`.
+  The b10 pin and b4 pin cannot be mixed. (Provider `2.3.0` requires
+  `==1.0.0b10`; pinning `2.3.x` against `b4` would fail at provider
+  import time.)
+
+### 2. `COPILOT_CLI_PATH` is no longer honored
+
+- **What:** The provider no longer forwards `COPILOT_CLI_PATH` to the SDK
+  runtime. The SDK uses its managed Copilot CLI binary for deterministic
+  behavior.
+- **Behavior on upgrade:** Any ambient `COPILOT_CLI_PATH` set by the user
+  or shell is ignored when the provider spawns the SDK runtime.
+- **Replacement:** None. If you depended on a custom CLI binary, pin
+  provider `<=2.2.x` and open an issue describing the use case.
+- **Rollback:** Pin provider `==2.2.0` with `github-copilot-sdk==1.0.0b4`.
+
+### 3. `COPILOT_HOME` is no longer honored
+
+- **What:** The provider no longer forwards `COPILOT_HOME` to the SDK
+  runtime. Session state location is controlled by the provider, not by
+  shell env.
+- **Behavior on upgrade:** Any ambient `COPILOT_HOME` set by the user or
+  shell is ignored when the provider spawns the SDK runtime.
+- **Replacement:** Use `AMPLIFIER_PROVIDER_GITHUB_COPILOT_HOME` to control the
+  provider's state root. It is resolved at provider-init time and applied
+  through the provider's path configuration.
+- **Rollback:** Pin provider `==2.2.0` with `github-copilot-sdk==1.0.0b4`.
+
+### 4. `copilot.SubprocessConfig` is no longer imported from the SDK
+
+- **What:** The provider no longer references the
+  `copilot.SubprocessConfig` symbol. Process options that used to be passed
+  via that wrapper (`copilot_home`, `cli_path`, `env`, `log_level`) are now
+  passed directly as keyword arguments on the `CopilotClient(...)`
+  constructor (`base_directory`, `env`, `log_level`, `github_token`). The
+  SDK removed `SubprocessConfig` from its public API at b7 and it has
+  remained absent through b10 — keeping it in the import surface would
+  fail at import time on any supported SDK version.
+- **Behavior on upgrade:** None for end users — `SubprocessConfig` was
+  never part of the provider's public API. Fork maintainers who
+  re-exported it from provider internals (or patched it in tests) need to
+  switch to patching `CopilotClient` directly (e.g.,
+  `monkeypatch.setattr(client_mod, "CopilotClient", FakeCopilotClient)`).
+- **Replacement:** Construct `CopilotClient(base_directory=..., env=...,
+  log_level=..., mode="copilot-cli", github_token=...)` directly. The
+  `mode="copilot-cli"` argument is required — leaving it unset falls
+  through to the SDK's default mode, which does not match the provider's
+  wiring invariants. See
+  `sdk_adapter/client.py::_ensure_client_initialized` for the canonical
+  pattern.
+- **Rollback:** Not applicable — the symbol was removed upstream.
+
+### 5. Ambient `COPILOT_SDK_AUTH_TOKEN` is no longer forwarded to the SDK
+
+- **What:** The provider scrubs `COPILOT_SDK_AUTH_TOKEN` from the env
+  handed to the spawned SDK subprocess. The SDK uses this variable as the
+  transport for the GitHub token it injects from the `github_token`
+  constructor argument (via `--auth-token-env`); the SDK only writes it
+  into the subprocess env when `github_token` is truthy. Without scrubbing,
+  an ambient parent-shell value would survive into the spawned process on
+  the no-token branch and authenticate against a credential the provider
+  never resolved.
+- **Behavior on upgrade:** When the provider runs without a resolved
+  token (`GITHUB_TOKEN`, `COPILOT_AGENT_TOKEN`, `COPILOT_GITHUB_TOKEN`,
+  and `GH_TOKEN` all unset), the SDK subprocess no longer inherits an
+  ambient `COPILOT_SDK_AUTH_TOKEN`. The provider still fails closed on
+  the no-token path with the usual `ProviderUnavailableError`. When the
+  provider resolves a token through its documented variables, the SDK
+  re-injects `COPILOT_SDK_AUTH_TOKEN` from that resolved value, so
+  authenticated runs are unchanged.
+- **Replacement:** Set one of the documented token variables
+  (`GITHUB_TOKEN`, `COPILOT_AGENT_TOKEN`, `COPILOT_GITHUB_TOKEN`, or
+  `GH_TOKEN`) so the provider resolves the token explicitly. The SDK
+  will then inject `COPILOT_SDK_AUTH_TOKEN` into the subprocess on the
+  provider's behalf.
+- **Rollback:** Pin provider `==2.2.0` with `github-copilot-sdk==1.0.0b4`.
+
+---
+
+## When
+
+Provider version `2.3.0`.
+
+---
+
+## Rollback
+
+If the new SDK or env-var behavior breaks your workflow, pin provider
+`==2.2.0` with `github-copilot-sdk==1.0.0b4`. The two cannot be mixed.
+
+---
+
 # Migration Guide: v1.0.x → v2.0.0
 
 ## Overview
 
@@ -127,27 +127,32 @@ amplifier provider models github-copilot
 
 ## Supported Models
 
-Models are discovered dynamically from the SDK at runtime — the list reflects your GitHub Copilot plan. The tables below show the current set as of SDK 1.0.0b4; run `amplifier provider models github-copilot` for the live list.
+Models are discovered dynamically from the SDK at runtime — the list reflects your GitHub Copilot plan. The tables below show the current public set as of SDK 1.0.0b10; run `amplifier provider models github-copilot` for the live list.
+
+**Routing:**
+
+| Model ID | Context | Max Output | Capabilities |
+| --- | --- | --- | --- |
+| `auto` | 128k | 16k | streaming, tools |
 
 **Anthropic:**
 
 | Model ID | Context | Max Output | Capabilities |
 | --- | --- | --- | --- |
+| `claude-opus-4.8` | 200k | 32k | streaming, tools, vision, thinking |
 | `claude-opus-4.7` | 200k | 32k | streaming, tools, vision, thinking |
+| `claude-opus-4.6` | 200k | 32k | streaming, tools, vision, thinking |
+| `claude-opus-4.5` | 200k | 32k | streaming, tools, vision |
 | `claude-sonnet-4.6` | 200k | 32k | streaming, tools, vision, thinking |
 | `claude-sonnet-4.5` | 200k | 32k | streaming, tools, vision |
 | `claude-haiku-4.5` | 200k | 64k | streaming, tools, vision |
-| `claude-opus-4.6` | 200k | 32k | streaming, tools, vision, thinking |
-| `claude-opus-4.6-1m` | 1M | 64k | streaming, tools, vision, thinking |
-| `claude-opus-4.5` | 200k | 32k | streaming, tools, vision |
-| `claude-sonnet-4` | 216k | 88k | streaming, tools, vision |
 
 **OpenAI:**
 
 | Model ID | Context | Max Output | Capabilities |
 | --- | --- | --- | --- |
-| `gpt-5.5` | 400k | 128k | streaming, tools, vision, thinking |
-| `gpt-5.4` | 400k | 128k | streaming, tools, vision, thinking |
+| `gpt-5.5` | 1.05M | 128k | streaming, tools, vision, thinking |
+| `gpt-5.4` | 1.05M | 128k | streaming, tools, vision, thinking |
 | `gpt-5.3-codex` | 400k | 128k | streaming, tools, vision, thinking |
 | `gpt-5.2-codex` | 400k | 128k | streaming, tools, vision, thinking |
 | `gpt-5.2` | 400k | 128k | streaming, tools, vision, thinking |
@@ -504,7 +509,7 @@ Running `amplifier init` before authentication:
 ## Dependencies
 
 - `amplifier-core` (provided by Amplifier runtime, not installed separately)
-- `github-copilot-sdk==1.0.0b4`
+- `github-copilot-sdk==1.0.0b10`
 - `pyyaml>=6.0`
 
 > **Note:** `github-copilot-sdk` is installed automatically when you install or initialize
 
@@ -1,9 +1,11 @@
 """GitHub Copilot Provider for Amplifier.
 
-Three-Medium Architecture:
-- Python for mechanism (~300 lines)
-- YAML for policy (~200 lines)
-- Markdown for contracts (~400 lines)
+Two-Medium Architecture:
+- Python for mechanism AND policy (config/_*.py)
+- Markdown for contracts (contracts/*.md)
+
+YAML is reserved exclusively for SDK-correlated tabular data
+(config/data/errors.yaml, events.yaml) — never for policy.
 
 Contract: contracts/provider-protocol.md
 """
@@ -26,6 +28,9 @@
 from importlib.metadata import PackageNotFoundError as _PkgNotFoundError
 from importlib.metadata import version as _pkg_version
 
+from packaging.version import InvalidVersion as _InvalidVersion
+from packaging.version import Version as _Version
+
 from ._identity import PROVIDER_ID
 
 # Single source of truth for pytest detection — defined in _platform.py.
@@ -39,42 +44,75 @@
 
 
 def _check_sdk_version(version_str: str) -> None:
-    """Raise ImportError if SDK version does not satisfy >=1.0.0b4.
-
-    Extracted for testability — module-level code that runs under SKIP_SDK_CHECK
-    cannot be reached by unit tests; this function can be imported and tested
-    directly.
+    """Raise ImportError if SDK version does not satisfy >=1.0.0b10.
+
+    The b10 floor matches what the adapter actually calls:
+    ``CopilotClient(base_directory=..., mode="copilot-cli", ...)`` plus the
+    9 MinimalMode kwargs pinned at b10 (``enable_session_store``,
+    ``enable_skills``, ``enable_file_hooks``, ``enable_host_git_operations``,
+    ``enable_on_demand_instruction_discovery``, ``skip_embedding_retrieval``,
+    ``embedding_cache_storage``, ``enable_session_telemetry``,
+    ``mcp_oauth_token_storage``). Eight are new ``create_session`` kwargs in
+    b10 (the seven feature toggles plus ``mcp_oauth_token_storage``; verified
+    against SDK b10 ``client.py:1582-1605`` and absent from b9); passing any of
+    them to b9 raises ``TypeError: unexpected keyword argument`` at the first
+    ``create_session(...)`` call. ``enable_session_telemetry`` is a pre-existing
+    b9 kwarg consolidated under MinimalMode now.
+    Surfacing the floor at import time gives the user the actionable
+    reinstall message instead of a deferred ``TypeError``.
+
+    The floor is the symbol-availability minimum (``>=1.0.0b10``); the
+    exact pyproject pin (``==1.0.0b10``) is enforced separately by
+    ``tests/_sdk_version_gate.py``. Earlier 1.x betas lack required
+    MinimalMode kwargs and are rejected here at import time.
+
+    Extracted for testability — module-level code that runs under
+    SKIP_SDK_CHECK cannot be reached by unit tests; this function can be
+    imported and tested directly.
 
     Contract: sdk-boundary:Membrane:MUST:5
     """
-    try:
-        ver_parts = tuple(int(x) for x in version_str.split(".")[:2] if x.isdigit())
-    except (ValueError, TypeError):  # pragma: no cover — malformed version string
-        ver_parts = (0, 0)
-    if ver_parts < (1, 0):
+    if _parse_sdk_version(version_str) < _SDK_FLOOR:
         raise ImportError(
-            f"github-copilot-sdk=={version_str} is installed but ==1.0.0b4 is required. "
-            "Upgrade with: pip install 'github-copilot-sdk==1.0.0b4' "
-            "or reinstall the provider: amplifier provider install --force github-copilot"
+            f"github-copilot-sdk=={version_str} is below the symbol-availability "
+            "floor (>=1.0.0b10 required; MinimalMode MUST:7-15 kwargs added at b10). "
+            "Pinned target: ==1.0.0b10 (pyproject.toml). "
+            "Reinstall with: pip install 'github-copilot-sdk==1.0.0b10' "
+            f"or: amplifier provider install --force {PROVIDER_ID}"
         )
 
 
+_SDK_FLOOR: _Version = _Version("1.0.0b10")
+_SDK_UNPARSEABLE: _Version = _Version("0.0.0a0")
+
+
+def _parse_sdk_version(version_str: str) -> _Version:
+    """Parse a github-copilot-sdk PyPI release identifier (PEP 440).
+
+    Uses ``packaging.version.Version`` for full PEP 440 coverage (pre/post/
+    local/dev releases all ordered correctly). Unparseable input maps to a
+    sentinel below every real release so the guard fails closed.
+    """
+    try:
+        return _Version(version_str)
+    except _InvalidVersion:
+        return _SDK_UNPARSEABLE
+
+
 if not _SKIP_SDK_CHECK:  # pragma: no cover
     try:
         _sdk_version = _pkg_version("github-copilot-sdk")
     except _PkgNotFoundError as _e:
         # SDK required; tests only run with SDK installed
         raise ImportError(
             "Required dependency 'github-copilot-sdk' is not installed. "
-            "Install with:  pip install 'github-copilot-sdk==1.0.0b4'"
+            "Install with:  pip install 'github-copilot-sdk==1.0.0b10'"
         ) from _e
     # Contract: sdk-boundary:Membrane:MUST:5 — fail at import time on wrong version.
-    # Presence-only check passes silently for SDK 0.1.x which lacks SubprocessConfig,
-    # causing a cryptic ConfigurationError deep in the init flow instead.
     _check_sdk_version(_sdk_version)
 
 # E402: These imports are intentionally after SDK check - we verify SDK
-# installation before importing modules that depend on it (Three-Medium).
+# installation before importing modules that depend on it (Two-Medium Architecture).
 import logging  # noqa: E402
 from collections.abc import Awaitable, Callable  # noqa: E402
 from typing import Any, NoReturn  # noqa: E402
@@ -89,7 +127,7 @@ def _check_sdk_version(version_str: str) -> None:
 
 # Contract: provider-protocol:public_api:MUST:1 — must match pyproject.toml [project].version
 # Verified by tests/test_behaviors.py::TestPackageVersionConsistency
-__version__ = "2.2.0"
+__version__ = "2.3.0"
 
 # Amplifier module metadata
 __amplifier_module_type__ = "provider"
@@ -192,6 +230,39 @@ async def _acquire_shared_client() -> CopilotClientWrapper:
     return result_client
 
 
+async def _cancel_prewarm_task() -> None:
+    """Cancel the in-flight prewarm task, if any, and await its termination.
+
+    Idempotent; safe to call from both the success-path cleanup() closure and
+    the mount() failure handler. Contract: sdk-protection:Subprocess:MUST:5.
+    """
+    global _prewarm_task
+    task = _prewarm_task
+    if task is None or task.done():
+        _prewarm_task = None
+        return
+    task.cancel()
+    try:
+        await task
+    except asyncio.CancelledError:
+        pass
+    except Exception:
+        # _prewarm() at __init__.py:374-386 catches and logs Exception itself
+        # (with redaction). By the time the task resolves here only
+        # CancelledError or a re-raised non-Exception should surface; still,
+        # log at DEBUG (not WARN) so a future regression that removes the
+        # inner handler leaves a traceable signal without competing with
+        # the original mount-failure WARN being handled by the caller.
+        # Contract: sdk-protection:Subprocess:MUST:5.
+        # Pinned by: tests/test_client_lifecycle.py::TestPrewarmSubprocess::
+        #   test_cancel_prewarm_task_suppresses_inner_exception_branch.
+        logging.getLogger(__name__).debug(
+            "[CLEANUP] cancel-site suppressed non-CancelledError from prewarm task",
+            exc_info=True,
+        )
+    _prewarm_task = None
+
+
 async def _release_shared_client() -> None:
     """Release a reference to the shared client, closing when count reaches 0.
 
@@ -350,15 +421,7 @@ async def _prewarm() -> None:
 
         async def cleanup() -> None:
             # Contract: sdk-protection:Subprocess:MUST:5 — Cancel prewarm task
-            global _prewarm_task
-            if _prewarm_task is not None and not _prewarm_task.done():  # pragma: no cover
-                # Prewarm cancelled during shutdown — unlikely in tests
-                _prewarm_task.cancel()
-                try:
-                    await _prewarm_task
-                except asyncio.CancelledError:
-                    pass  # Expected
-                _prewarm_task = None
+            await _cancel_prewarm_task()
 
             # Contract: streaming-contract:ProgressiveStreaming:SHOULD:3 — cancel tasks
             await provider.cancel_emit_tasks()
@@ -370,6 +433,10 @@ async def cleanup() -> None:
 
         return cleanup
     except Exception as e:
+        # Cancel prewarm before releasing the client it depends on.
+        # Contract: sdk-protection:Subprocess:MUST:5 — leaked task would
+        # otherwise survive against a closing client.
+        await _cancel_prewarm_task()
         # Release our reference if mount fails
         await _release_shared_client()
 
 
@@ -57,8 +57,7 @@ def _resolve_absolute(value: str, env_name: str) -> Path:
     expanded = Path(value).expanduser()
     if not expanded.is_absolute():
         raise ValueError(
-            f"{env_name}={value!r} must be absolute after Path.expanduser(); "
-            f"got {expanded!s}"
+            f"{env_name}={value!r} must be absolute after Path.expanduser(); got {expanded!s}"
         )
     return expanded
Original file line number	Diff line number	Diff line change
`@@ -57,8 +57,7 @@ def _resolve_absolute(value: str, env_name: str) -> Path:`
`57`	`57`	`expanded = Path(value).expanduser()`
`58`	`58`	`if not expanded.is_absolute():`
`59`	`59`	`raise ValueError(`
`60`		`- f"{env_name}={value!r} must be absolute after Path.expanduser(); "`
`61`		`- f"got {expanded!s}"`
	`60`	`+ f"{env_name}={value!r} must be absolute after Path.expanduser(); got {expanded!s}"`
`62`	`61`	`)`
`63`	`62`	`return expanded`
`64`	`63`