diff --git a/dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/CopilotCliVersionGuard.cs b/dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/CopilotCliVersionGuard.cs new file mode 100644 index 00000000000..e402b5f0803 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/CopilotCliVersionGuard.cs @@ -0,0 +1,68 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.Globalization; +using System.Text.RegularExpressions; + +namespace Microsoft.Agents.AI.GitHub.Copilot; + +/// +/// Checks that the GitHub Copilot CLI in use meets the minimum supported version. +/// +internal static partial class CopilotCliVersionGuard +{ + /// The minimum supported GitHub Copilot CLI version. + internal static readonly Version MinimumVersion = new(1, 0, 85); + + // Only the leading major.minor.patch is compared; any suffix is ignored, + // so prerelease builds such as "1.0.85-3" count as 1.0.85. + [GeneratedRegex(@"^\s*v?(\d+)\.(\d+)\.(\d+)", RegexOptions.CultureInvariant)] + private static partial Regex VersionPrefixRegex(); + + /// + /// Reads the leading major.minor.patch from a version string. + /// + /// The version string reported by the CLI. + /// The parsed version, or if it could not be read. + internal static Version? Parse(string? version) + { + if (version is null) + { + return null; + } + + Match match = VersionPrefixRegex().Match(version); + if (!match.Success + || !int.TryParse(match.Groups[1].Value, NumberStyles.None, CultureInfo.InvariantCulture, out int major) + || !int.TryParse(match.Groups[2].Value, NumberStyles.None, CultureInfo.InvariantCulture, out int minor) + || !int.TryParse(match.Groups[3].Value, NumberStyles.None, CultureInfo.InvariantCulture, out int patch)) + { + return null; + } + + return new Version(major, minor, patch); + } + + /// + /// Throws if the given CLI version is older than or could not be read. + /// + /// The version string reported by the CLI. + /// The version is unsupported or could not be read. + internal static void EnsureSupported(string? version) + { + Version? parsed = Parse(version); + if (parsed is null || parsed < MinimumVersion) + { + throw new InvalidOperationException( + $"GitHub Copilot CLI version {MinimumVersion} or higher is required, but version '{version}' was detected."); + } + } + + /// + /// Creates the error used when the CLI version could not be determined. + /// + /// The error raised while reading the version. + /// The exception to throw. + internal static InvalidOperationException CreateUndeterminedVersionException(Exception innerException) => + new($"GitHub Copilot CLI version {MinimumVersion} or higher is required, but the version could not be determined.", innerException); +} diff --git a/dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/GitHubCopilotAgent.cs b/dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/GitHubCopilotAgent.cs index 4f3828744ed..652a8716d33 100644 --- a/dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/GitHubCopilotAgent.cs +++ b/dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/GitHubCopilotAgent.cs @@ -39,6 +39,8 @@ public sealed class GitHubCopilotAgent : AIAgent, IAsyncDisposable private readonly bool _ownsClient; private readonly JsonSerializerOptions _jsonSerializerOptions; private readonly ILogger _logger; + private readonly SemaphoreSlim _startLock = new(1, 1); + private volatile bool _cliVersionChecked; /// /// Initializes a new instance of the class. @@ -58,6 +60,10 @@ public sealed class GitHubCopilotAgent : AIAgent, IAsyncDisposable /// SessionConfig.OnPermissionRequest) and defers all other tools. If the caller supplies their own /// OnPreToolUse hook, it takes precedence and the caller is fully responsible for approval handling; in that /// case a warning is logged for any approval-required tool that will not be automatically gated. + /// + /// GitHub Copilot CLI version 1.0.85 or higher is required. The version is checked the first time the agent runs, + /// and an is thrown if it is older or cannot be determined. + /// /// public GitHubCopilotAgent( CopilotClient copilotClient, @@ -97,6 +103,10 @@ public GitHubCopilotAgent( /// When a tool wrapped in is registered, the agent installs a default /// Hooks.OnPreToolUse handler that returns "ask" for those tools (routing the decision to /// SessionConfig.OnPermissionRequest) and defers all other tools. + /// + /// GitHub Copilot CLI version 1.0.85 or higher is required. The version is checked the first time the agent runs, + /// and an is thrown if it is older or cannot be determined. + /// /// public GitHubCopilotAgent( CopilotClient copilotClient, @@ -303,11 +313,71 @@ public async ValueTask DisposeAsync() { await this._copilotClient.DisposeAsync().ConfigureAwait(false); } + + this._startLock.Dispose(); } private async Task EnsureClientStartedAsync(CancellationToken cancellationToken) { - await this._copilotClient.StartAsync(cancellationToken).ConfigureAwait(false); + if (this._cliVersionChecked) + { + await this._copilotClient.StartAsync(cancellationToken).ConfigureAwait(false); + return; + } + + // Only one start and version check may run at a time, so a failed check can't stop a client + // that another concurrent run has already accepted. + await this._startLock.WaitAsync(cancellationToken).ConfigureAwait(false); + try + { + await this._copilotClient.StartAsync(cancellationToken).ConfigureAwait(false); + + if (this._cliVersionChecked) + { + return; + } + + try + { + string? version; + try + { + GetStatusResponse status = await this._copilotClient.GetStatusAsync(cancellationToken).ConfigureAwait(false); + version = status?.Version; + } + catch (Exception ex) when (ex is not OperationCanceledException) + { + throw CopilotCliVersionGuard.CreateUndeterminedVersionException(ex); + } + + CopilotCliVersionGuard.EnsureSupported(version); + } + catch (InvalidOperationException) when (this._ownsClient) + { + await this.StopOwnedClientAfterFailedCheckAsync().ConfigureAwait(false); + throw; + } + + // Only a successful check is remembered, so a failed check is repeated on the next run. + this._cliVersionChecked = true; + } + finally + { + this._startLock.Release(); + } + } + + private async Task StopOwnedClientAfterFailedCheckAsync() + { + try + { + await this._copilotClient.StopAsync().ConfigureAwait(false); + } + catch (Exception ex) + { + // Keep the original version check error; a failure to stop is only logged. + this._logger.LogFailedToStopClientAfterVersionCheck(ex); + } } /// diff --git a/dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/GitHubCopilotAgentLogMessages.cs b/dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/GitHubCopilotAgentLogMessages.cs index 147af174458..687a2d57dcc 100644 --- a/dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/GitHubCopilotAgentLogMessages.cs +++ b/dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/GitHubCopilotAgentLogMessages.cs @@ -1,5 +1,6 @@ // Copyright (c) Microsoft. All rights reserved. +using System; using System.Diagnostics.CodeAnalysis; using Microsoft.Extensions.Logging; @@ -28,4 +29,14 @@ public static partial void LogApprovalGatingSkippedDueToCustomHook( this ILogger logger, int count, string tools); + + /// + /// Logs when stopping an owned Copilot client fails after the Copilot CLI version check failed. + /// + [LoggerMessage( + Level = LogLevel.Debug, + Message = "Failed to stop the GitHub Copilot client after the Copilot CLI version check failed.")] + public static partial void LogFailedToStopClientAfterVersionCheck( + this ILogger logger, + Exception exception); } diff --git a/dotnet/tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/CopilotCliVersionGuardTests.cs b/dotnet/tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/CopilotCliVersionGuardTests.cs new file mode 100644 index 00000000000..3d19255cea9 --- /dev/null +++ b/dotnet/tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/CopilotCliVersionGuardTests.cs @@ -0,0 +1,55 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; + +namespace Microsoft.Agents.AI.GitHub.Copilot.UnitTests; + +/// +/// Unit tests for the class. +/// +public sealed class CopilotCliVersionGuardTests +{ + [Theory] + [InlineData("1.0.85")] + [InlineData("1.0.85-3")] + [InlineData("1.0.90-0.unstable.abc")] + [InlineData("v1.0.106")] + [InlineData("2.0.0")] + public void EnsureSupported_WithSupportedVersion_DoesNotThrow(string version) + { + // Act & Assert + CopilotCliVersionGuard.EnsureSupported(version); + } + + [Theory] + [InlineData("1.0.64")] + [InlineData("1.0.84")] + [InlineData("0.9.999")] + [InlineData("dev")] + [InlineData("")] + [InlineData(null)] + public void EnsureSupported_WithUnsupportedOrUnreadableVersion_Throws(string? version) + { + // Act + InvalidOperationException exception = Assert.Throws( + () => CopilotCliVersionGuard.EnsureSupported(version)); + + // Assert + Assert.Contains("1.0.85 or higher is required", exception.Message); + Assert.Contains($"'{version}'", exception.Message); + } + + [Fact] + public void CreateUndeterminedVersionException_KeepsInnerException() + { + // Arrange + Exception inner = new InvalidOperationException("not connected"); + + // Act + InvalidOperationException exception = CopilotCliVersionGuard.CreateUndeterminedVersionException(inner); + + // Assert + Assert.Contains("version could not be determined", exception.Message); + Assert.Same(inner, exception.InnerException); + } +} diff --git a/python/packages/github_copilot/README.md b/python/packages/github_copilot/README.md index 04352d65582..3b29333a472 100644 --- a/python/packages/github_copilot/README.md +++ b/python/packages/github_copilot/README.md @@ -10,6 +10,10 @@ pip install agent-framework-github-copilot The GitHub Copilot agent enables integration with GitHub Copilot, allowing you to interact with Copilot's agentic capabilities through the Agent Framework. +The agent requires GitHub Copilot CLI version 1.0.85 or higher. When the agent starts, it checks the CLI version +and raises an error if the version is older or cannot be determined. This applies to the CLI bundled with the +`github-copilot-sdk` package as well as one selected with `cli_path`, `GITHUB_COPILOT_CLI_PATH`, or `COPILOT_CLI_PATH`. + ## Context providers and function middleware Context providers can contribute messages, instructions, and tools to a run. diff --git a/python/packages/github_copilot/agent_framework_github_copilot/_agent.py b/python/packages/github_copilot/agent_framework_github_copilot/_agent.py index 4295475b092..6bda3a13640 100644 --- a/python/packages/github_copilot/agent_framework_github_copilot/_agent.py +++ b/python/packages/github_copilot/agent_framework_github_copilot/_agent.py @@ -7,6 +7,7 @@ import inspect import json import logging +import re import sys import warnings import weakref @@ -188,6 +189,36 @@ async def _resolve_function_approval( logger = logging.getLogger("agent_framework.github_copilot") +# Minimum supported Copilot CLI runtime version. +_MIN_COPILOT_CLI_VERSION = (1, 0, 85) +_VERSION_PREFIX = re.compile(r"^\s*v?(\d+)\.(\d+)\.(\d+)") + + +def _parse_cli_version(version: object) -> tuple[int, int, int] | None: + """Parse the leading ``major.minor.patch`` of a CLI version, ignoring any suffix.""" + if not isinstance(version, str): + return None + match = _VERSION_PREFIX.match(version) + if match is None: + return None + return int(match.group(1)), int(match.group(2)), int(match.group(3)) + + +async def _ensure_supported_cli_version(client: CopilotClient) -> None: + """Raise ``AgentException`` unless the connected Copilot CLI meets the minimum version.""" + minimum = ".".join(str(part) for part in _MIN_COPILOT_CLI_VERSION) + try: + version: object = (await client.get_status()).version + except Exception as ex: + raise AgentException( + f"GitHub Copilot CLI version {minimum} or higher is required, but the version could not be determined." + ) from ex + parsed = _parse_cli_version(version) + if parsed is None or parsed < _MIN_COPILOT_CLI_VERSION: + raise AgentException( + f"GitHub Copilot CLI version {minimum} or higher is required, but version '{version}' was detected." + ) + def _provider_service_session_state_keys(agent: object, client: object | None) -> frozenset[str]: """Return provider-owned session-state keys declared by the Copilot agent or client.""" @@ -713,6 +744,7 @@ def __init__( # are forwarded verbatim to the Copilot SDK by _build_session_kwargs. self._default_options = opts self._started = False + self._start_lock = asyncio.Lock() self._file_hooks_warning_emitted = False async def __aenter__(self) -> Self: @@ -732,35 +764,51 @@ async def start(self) -> None: agent as an async context manager. Raises: - AgentException: If the client fails to start. + AgentException: If the client fails to start or the Copilot CLI is older than the + minimum supported version. """ if self._started: return - if self._client is None: - cli_path = self._settings.get("cli_path") or None - log_level = self._settings.get("log_level") or None - base_directory = self._settings.get("base_directory") or None - telemetry = self._settings.get("telemetry") or None - if isinstance(telemetry, str): - telemetry = _parse_telemetry_config(telemetry) - - client_kwargs: dict[str, Any] = {} - if cli_path: - client_kwargs["connection"] = RuntimeConnection.for_stdio(path=cli_path) - if log_level: - client_kwargs["log_level"] = log_level - if base_directory: - client_kwargs["base_directory"] = base_directory - if telemetry: - client_kwargs["telemetry"] = telemetry - self._client = CopilotClient(**client_kwargs) + # Only one start may run at a time, so a failed check can't stop a client that another + # concurrent start has already accepted. + async with self._start_lock: + if self._started: + return + + if self._client is None: + cli_path = self._settings.get("cli_path") or None + log_level = self._settings.get("log_level") or None + base_directory = self._settings.get("base_directory") or None + telemetry = self._settings.get("telemetry") or None + if isinstance(telemetry, str): + telemetry = _parse_telemetry_config(telemetry) + + client_kwargs: dict[str, Any] = {} + if cli_path: + client_kwargs["connection"] = RuntimeConnection.for_stdio(path=cli_path) + if log_level: + client_kwargs["log_level"] = log_level + if base_directory: + client_kwargs["base_directory"] = base_directory + if telemetry: + client_kwargs["telemetry"] = telemetry + self._client = CopilotClient(**client_kwargs) + + try: + await self._client.start() + except Exception as ex: + raise AgentException(f"Failed to start GitHub Copilot client: {ex}") from ex + + try: + await _ensure_supported_cli_version(self._client) + except BaseException: + if self._owns_client: + with contextlib.suppress(Exception): + await self._client.stop() + raise - try: - await self._client.start() self._started = True - except Exception as ex: - raise AgentException(f"Failed to start GitHub Copilot client: {ex}") from ex async def stop(self) -> None: """Stop the Copilot client and clean up resources. diff --git a/python/packages/github_copilot/tests/test_github_copilot_agent.py b/python/packages/github_copilot/tests/test_github_copilot_agent.py index b0d6ad71f33..3c2ae35770f 100644 --- a/python/packages/github_copilot/tests/test_github_copilot_agent.py +++ b/python/packages/github_copilot/tests/test_github_copilot_agent.py @@ -1,5 +1,6 @@ # Copyright (c) Microsoft. All rights reserved. +import asyncio import base64 import inspect import json @@ -51,6 +52,8 @@ from agent_framework_github_copilot import GitHubCopilotAgent, GitHubCopilotOptions, RawGitHubCopilotAgent from agent_framework_github_copilot._feature_usage import FeatureIndex +SUPPORTED_CLI_VERSION = "1.0.106" + def copilot_options(options: GitHubCopilotOptions) -> GitHubCopilotOptions: """Return GitHub Copilot options with concrete TypedDict typing for tests.""" @@ -160,6 +163,7 @@ def _side_effect(*args: Any, **kwargs: Any) -> MagicMock: client = MagicMock() client.start = AsyncMock() + client.get_status = AsyncMock(return_value=MagicMock(version=SUPPORTED_CLI_VERSION)) client.stop = AsyncMock(return_value=[]) client.create_session = _validating("create_session") client.resume_session = _validating("resume_session") @@ -344,6 +348,7 @@ async def test_start_creates_client(self) -> None: with patch("agent_framework_github_copilot._agent.CopilotClient") as MockClient: mock_client = MagicMock() mock_client.start = AsyncMock() + mock_client.get_status = AsyncMock(return_value=MagicMock(version=SUPPORTED_CLI_VERSION)) MockClient.return_value = mock_client agent = GitHubCopilotAgent() @@ -392,6 +397,7 @@ async def test_stop_calls_client_stop_when_agent_owns_client(self) -> None: with patch("agent_framework_github_copilot._agent.CopilotClient") as MockClient: mock_client = MagicMock() mock_client.start = AsyncMock() + mock_client.get_status = AsyncMock(return_value=MagicMock(version=SUPPORTED_CLI_VERSION)) mock_client.stop = AsyncMock() MockClient.return_value = mock_client @@ -401,11 +407,98 @@ async def test_stop_calls_client_stop_when_agent_owns_client(self) -> None: mock_client.stop.assert_called_once() + @pytest.mark.parametrize("version", ["1.0.85", "1.0.85-3", "1.0.90-0.unstable.abc", "2.0.0"]) + async def test_start_accepts_supported_cli_version(self, mock_client: MagicMock, version: str) -> None: + """Test that start succeeds when the CLI reports the minimum version or newer.""" + mock_client.get_status = AsyncMock(return_value=MagicMock(version=version)) + agent = GitHubCopilotAgent(client=mock_client) + + await agent.start() + + assert agent._started is True # type: ignore + + @pytest.mark.parametrize("version", ["1.0.64", "1.0.84", "0.9.999", "dev", "", None]) + async def test_start_rejects_old_or_unreadable_cli_version(self, mock_client: MagicMock, version: Any) -> None: + """Test that start fails when the CLI is too old or its version can't be read.""" + mock_client.get_status = AsyncMock(return_value=MagicMock(version=version)) + agent = GitHubCopilotAgent(client=mock_client) + + with pytest.raises(AgentException, match=r"version 1\.0\.85 or higher is required"): + await agent.start() + + assert agent._started is False # type: ignore + mock_client.stop.assert_not_called() + + async def test_start_rejects_when_cli_status_fails(self, mock_client: MagicMock) -> None: + """Test that start fails when the CLI version can't be queried.""" + mock_client.get_status = AsyncMock(side_effect=RuntimeError("status.get not supported")) + agent = GitHubCopilotAgent(client=mock_client) + + with pytest.raises(AgentException, match="could not be determined"): + await agent.start() + + assert agent._started is False # type: ignore + + async def test_start_stops_owned_client_on_unsupported_cli_version(self) -> None: + """Test that an agent-owned client is stopped when the CLI version is unsupported.""" + with patch("agent_framework_github_copilot._agent.CopilotClient") as MockClient: + mock_client = MagicMock() + mock_client.start = AsyncMock() + mock_client.stop = AsyncMock() + mock_client.get_status = AsyncMock(return_value=MagicMock(version="1.0.64")) + MockClient.return_value = mock_client + + agent = GitHubCopilotAgent() + with pytest.raises(AgentException): + await agent.start() + + mock_client.stop.assert_called_once() + + async def test_start_stops_owned_client_when_cancelled_during_version_check(self) -> None: + """Test that an agent-owned client is stopped when start is cancelled during the version check.""" + with patch("agent_framework_github_copilot._agent.CopilotClient") as MockClient: + mock_client = MagicMock() + mock_client.start = AsyncMock() + mock_client.stop = AsyncMock() + mock_client.get_status = AsyncMock(side_effect=asyncio.CancelledError()) + MockClient.return_value = mock_client + + agent = GitHubCopilotAgent() + with pytest.raises(asyncio.CancelledError): + await agent.start() + + mock_client.stop.assert_called_once() + assert agent._started is False # type: ignore + + async def test_start_concurrent_calls_check_version_once(self) -> None: + """Test that concurrent start calls start the client and check the CLI version only once.""" + with patch("agent_framework_github_copilot._agent.CopilotClient") as MockClient: + mock_client = MagicMock() + mock_client.start = AsyncMock() + mock_client.stop = AsyncMock() + + async def get_status() -> MagicMock: + await asyncio.sleep(0) + return MagicMock(version=SUPPORTED_CLI_VERSION) + + mock_client.get_status = AsyncMock(side_effect=get_status) + MockClient.return_value = mock_client + + agent = GitHubCopilotAgent() + await asyncio.gather(agent.start(), agent.start()) + + MockClient.assert_called_once() + mock_client.start.assert_called_once() + mock_client.get_status.assert_called_once() + mock_client.stop.assert_not_called() + assert agent._started is True # type: ignore + async def test_start_creates_client_with_options(self) -> None: """Test that start creates client with cli_path and log_level from settings.""" with patch("agent_framework_github_copilot._agent.CopilotClient") as MockClient: mock_client = MagicMock() mock_client.start = AsyncMock() + mock_client.get_status = AsyncMock(return_value=MagicMock(version=SUPPORTED_CLI_VERSION)) MockClient.return_value = mock_client agent = GitHubCopilotAgent( @@ -422,6 +515,7 @@ async def test_start_passes_base_directory_to_client(self) -> None: with patch("agent_framework_github_copilot._agent.CopilotClient") as MockClient: mock_client = MagicMock() mock_client.start = AsyncMock() + mock_client.get_status = AsyncMock(return_value=MagicMock(version=SUPPORTED_CLI_VERSION)) MockClient.return_value = mock_client agent = GitHubCopilotAgent(default_options=copilot_options({"base_directory": "/custom/copilot/home"})) @@ -441,6 +535,7 @@ async def test_start_passes_telemetry_to_client(self) -> None: with patch("agent_framework_github_copilot._agent.CopilotClient") as MockClient: mock_client = MagicMock() mock_client.start = AsyncMock() + mock_client.get_status = AsyncMock(return_value=MagicMock(version=SUPPORTED_CLI_VERSION)) MockClient.return_value = mock_client agent = GitHubCopilotAgent( @@ -463,6 +558,7 @@ async def test_start_parses_json_telemetry_string(self) -> None: ): mock_client = MagicMock() mock_client.start = AsyncMock() + mock_client.get_status = AsyncMock(return_value=MagicMock(version=SUPPORTED_CLI_VERSION)) MockClient.return_value = mock_client agent = GitHubCopilotAgent() @@ -478,6 +574,7 @@ async def test_start_ignores_malformed_telemetry_string(self) -> None: ): mock_client = MagicMock() mock_client.start = AsyncMock() + mock_client.get_status = AsyncMock(return_value=MagicMock(version=SUPPORTED_CLI_VERSION)) MockClient.return_value = mock_client agent = GitHubCopilotAgent() @@ -493,6 +590,7 @@ async def test_start_ignores_non_object_telemetry_string(self) -> None: ): mock_client = MagicMock() mock_client.start = AsyncMock() + mock_client.get_status = AsyncMock(return_value=MagicMock(version=SUPPORTED_CLI_VERSION)) MockClient.return_value = mock_client agent = GitHubCopilotAgent() @@ -505,6 +603,7 @@ async def test_start_base_directory_not_set_when_unspecified(self) -> None: with patch("agent_framework_github_copilot._agent.CopilotClient") as MockClient: mock_client = MagicMock() mock_client.start = AsyncMock() + mock_client.get_status = AsyncMock(return_value=MagicMock(version=SUPPORTED_CLI_VERSION)) MockClient.return_value = mock_client agent = GitHubCopilotAgent() @@ -521,6 +620,7 @@ async def test_start_base_directory_from_env_variable(self) -> None: ): mock_client = MagicMock() mock_client.start = AsyncMock() + mock_client.get_status = AsyncMock(return_value=MagicMock(version=SUPPORTED_CLI_VERSION)) MockClient.return_value = mock_client agent = GitHubCopilotAgent()