Skip to content

The agent that grows with you

fix(acp): deprecated copilot_acp_client alias keeps its whole former surface

Tekniumc8677aeaf483
diff --git a/agent/copilot_acp_client.py b/agent/copilot_acp_client.py
index 4fd414518bc..47023c34013 100644
--- a/agent/copilot_acp_client.py
+++ b/agent/copilot_acp_client.py
@@ -1,30 +1,67 @@
"""Deprecated alias module: use :class:`agent.acp_client.ACPClient`.
-Out-of-tree ACP providers (the ``kimchi-acp-provider`` catalog plugin) subclass
-``CopilotACPClient`` from here. It keeps its historical launch fallbacks, error wording and
-model-enablement filter so such subclasses behave as before. Remove no sooner than two minor releases after the deprecation (the plugin
-compat contract in ``plugins/AGENTS.md``).
+Listed catalog ACP providers were built on this module at their pinned versions
+(kimchi-acp-provider, kiro-acp, grok-acp, cursor-acp). They subclass ``CopilotACPClient``,
+import former module helpers (``ACP_MARKER_BASE_URL``, ``_build_subprocess_env``,
+``_acp_supported``, ``_model_selection_request``, ``_effective_timeout``) and patch
+``subprocess.Popen`` through it. So the module keeps its whole former surface: the
+Copilot-flavoured names keep their former defaults (launch env vars, the ``copilot-acp``
+placeholder, the ``copilotEnablement`` model filter, the ``gh copilot`` extension banner
+helpers), and the generic rest is served from :mod:`agent.acp_client`. The first access of
+any of these names warns once per process. Remove no sooner than two minor releases after the
+deprecation (the plugin compat contract in ``plugins/AGENTS.md``).
"""
from __future__ import annotations
+import os
+import shlex
+# A real attribute, not served by __getattr__: plugins patch ``agent.copilot_acp_client.subprocess.Popen``
+# (and ``.run``). It is the stdlib module itself, so such patches reach ACPClient's spawn and probe.
+import subprocess
import warnings
from typing import Any
+from agent import acp_client as _acp
from agent.acp_client import ACPClient
_warned = False
+_PLACEHOLDER = "copilot-acp"
+_COMMAND_ENV_VARS = ("HERMES_COPILOT_ACP_COMMAND", "COPILOT_CLI_PATH")
+_ARGS_ENV_VAR = "HERMES_COPILOT_ACP_ARGS"
+# Stderr fingerprint of the deprecated `gh copilot` extension: BOTH the product name AND a deprecation
+# marker (the new `@github/copilot` CLI legitimately mentions "copilot-cli").
+_GH_EXTENSION_REQUIRED = ("gh-copilot",)
+_GH_EXTENSION_MARKERS = ("has been deprecated", "no commands will be executed")
+_GH_EXTENSION_ERROR = (
+ "Hermes ACP mode requires the NEW GitHub Copilot CLI (github.com/github/copilot-cli), but the binary it just "
+ "spawned is the deprecated `gh copilot` extension.\n\n"
+ "Install the new CLI:\n npm install -g @github/copilot\n # then verify with: copilot --help\n\n"
+ "If `copilot` already resolves to the new CLI but you still see this,\npoint Hermes at it explicitly:\n"
+ " export HERMES_COPILOT_ACP_COMMAND=/path/to/new/copilot\n\n"
+ "Alternative: use the `copilot` provider (no ACP, hits the Copilot API\ndirectly with a Copilot subscription "
+ "token) via `hermes setup`.\n\nOriginal error:\n"
+)
+
+
+def _copilot_disabled(entry: dict[str, Any]) -> bool:
+ return str((entry.get("_meta") or {}).get("copilotEnablement") or "").strip().lower() == "disabled"
+
+
+def _is_gh_extension_banner(stderr_text: str) -> bool:
+ lower = stderr_text.lower()
+ return any(req in lower for req in _GH_EXTENSION_REQUIRED) and any(m in lower for m in _GH_EXTENSION_MARKERS)
class _DeprecatedCopilotACPClient(ACPClient):
- """ACPClient with the historical launch defaults this module's callers relied on."""
+ """ACPClient with the historical launch defaults, labels and model filter."""
default_command = "copilot"
default_args = ("--acp", "--stdio")
- command_env_vars = ("HERMES_COPILOT_ACP_COMMAND", "COPILOT_CLI_PATH")
- args_env_var = "HERMES_COPILOT_ACP_ARGS"
+ command_env_vars = _COMMAND_ENV_VARS
+ args_env_var = _ARGS_ENV_VAR
marker_base_url = "acp://copilot"
- placeholder_model = "copilot-acp"
+ placeholder_model = _PLACEHOLDER
label = "Copilot ACP"
missing_command_hint = "Install GitHub Copilot CLI or set HERMES_COPILOT_ACP_COMMAND/COPILOT_CLI_PATH."
unsupported_transport_hint = (
@@ -32,19 +69,86 @@ class _DeprecatedCopilotACPClient(ACPClient):
"HERMES_COPILOT_ACP_COMMAND / HERMES_COPILOT_ACP_ARGS to a working pair.")
def model_entry_disabled(self, entry: dict[str, Any]) -> bool:
- return str((entry.get("_meta") or {}).get("copilotEnablement") or "").strip().lower() == "disabled"
+ return _copilot_disabled(entry)
_DeprecatedCopilotACPClient.__name__ = _DeprecatedCopilotACPClient.__qualname__ = "CopilotACPClient"
+def _former_resolve_command() -> str:
+ return next((v for name in _COMMAND_ENV_VARS if (v := os.getenv(name, "").strip())), "") or "copilot"
+
+
+def _former_resolve_args() -> list[str]:
+ return shlex.split(os.getenv(_ARGS_ENV_VAR, "").strip()) or ["--acp", "--stdio"]
+
+
+def _former_enabled_id_list(entries: Any, key: str) -> list[str]:
+ return _acp._enabled_id_list(entries, key, _copilot_disabled)
+
+
+def _former_session_model_ids(session: dict[str, Any]) -> list[str]:
+ return _acp._session_model_ids(session, _copilot_disabled)
+
+
+def _former_legacy_session_model_ids(session: dict[str, Any]) -> list[str]:
+ return _acp._legacy_session_model_ids(session, _copilot_disabled)
+
+
+def _former_model_selection_request(session: dict[str, Any], requested_model: str) -> tuple[str, dict[str, str]] | None:
+ return _acp._model_selection_request(session, requested_model, placeholder=_PLACEHOLDER, disabled=_copilot_disabled)
+
+
+# Former names whose behaviour is Copilot-flavoured: served from here with their former defaults.
+_COMPAT: dict[str, Any] = {
+ "CopilotACPClient": _DeprecatedCopilotACPClient,
+ "ACP_MARKER_BASE_URL": "acp://copilot",
+ "_DEPRECATION_REQUIRED": _GH_EXTENSION_REQUIRED,
+ "_DEPRECATION_MARKERS": _GH_EXTENSION_MARKERS,
+ "_DEPRECATED_CLI_ERROR": _GH_EXTENSION_ERROR,
+ "_is_gh_copilot_deprecation_message": _is_gh_extension_banner,
+ "_resolve_command": _former_resolve_command,
+ "_resolve_args": _former_resolve_args,
+ "_enabled_id_list": _former_enabled_id_list,
+ "_session_model_ids": _former_session_model_ids,
+ "_legacy_session_model_ids": _former_legacy_session_model_ids,
+ "_model_selection_request": _former_model_selection_request,
+}
+# Former names with unchanged behaviour: the very objects agent.acp_client uses (shared caches included).
+_FORWARDED = frozenset({
+ "logger", "_DEFAULT_TIMEOUT_SECONDS", "_ROLE_LABELS", "_ACP_PROBE_CACHE", "_PROMPT_PREAMBLE", "_INITIALIZE_PARAMS",
+ "_acp_supported", "_resolve_home_dir", "_build_subprocess_env", "_jsonrpc_result", "_jsonrpc_error",
+ "_model_config_option", "_format_messages_as_prompt", "_render_message_content", "_ensure_path_within_cwd",
+ "_effective_timeout", "_fs_read_text_file", "_fs_write_text_file", "_FS_HANDLERS",
+ "contextlib", "json", "logging", "queue", "re", "tempfile", "threading", "time", "deque", "Callable", "Iterator",
+ "Path", "SimpleNamespace", "_completion_to_stream_chunks", "_extract_tool_calls_from_text",
+ "_render_tool_bridge_sections", "get_nt_namespace_error", "get_read_block_error", "get_write_denied_error",
+ "is_write_approval_required", "redact_sensitive_text", "resolve_agent_cwd",
+})
+
+
+def _former_attribute(name: str) -> Any:
+ if name in _COMPAT:
+ return _COMPAT[name]
+ if name in _FORWARDED:
+ return getattr(_acp, name)
+ if name == "hermes_subprocess_env":
+ from tools.environments.local import hermes_subprocess_env # lazy: hermes_cli.config may still be importing
+
+ return hermes_subprocess_env
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
def __getattr__(name: str) -> Any:
global _warned
- if name != "CopilotACPClient":
- raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+ value = _former_attribute(name)
if not _warned:
_warned = True
warnings.warn(
- "agent.copilot_acp_client.CopilotACPClient is deprecated; subclass agent.acp_client.ACPClient instead.",
+ f"agent.copilot_acp_client.{name} is deprecated; subclass agent.acp_client.ACPClient instead.",
DeprecationWarning, stacklevel=2)
- return _DeprecatedCopilotACPClient
+ return value
+
+
+def __dir__() -> list[str]:
+ return sorted({*globals(), *_COMPAT, *_FORWARDED, "hermes_subprocess_env"})
diff --git a/tests/agent/test_copilot_acp_alias_compat.py b/tests/agent/test_copilot_acp_alias_compat.py
new file mode 100644
index 00000000000..563ac4c85d2
--- /dev/null
+++ b/tests/agent/test_copilot_acp_alias_compat.py
@@ -0,0 +1,203 @@
+"""The deprecated ``agent.copilot_acp_client`` alias keeps every listed catalog ACP plugin working.
+
+Each test reproduces one catalog plugin's import + patch set at its pinned SHA (see
+``plugin-catalog/<name>.yaml``) against a fake ACP agent: kiro-acp@02c4dd0, grok-acp@2851d66,
+cursor-acp@d5b6146. kimchi-acp-provider@d6ffe62 is covered in ``test_acp_client.py``.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import warnings
+
+import pytest
+
+_AGENT = r'''
+import json, os, sys
+log = open(os.environ["FAKE_ACP_LOG"], "a")
+def send(o): print(json.dumps(o), flush=True)
+for line in sys.stdin:
+ msg = json.loads(line); log.write(json.dumps(msg) + "\n"); log.flush()
+ m, i = msg.get("method"), msg.get("id")
+ if m == "initialize":
+ send({"jsonrpc": "2.0", "id": i, "result": {"protocolVersion": 1}})
+ elif m == "session/new":
+ result = {"sessionId": "s1", "models": {"availableModels": [
+ {"modelId": "fast[v2]", "name": "Fast"}, {"modelId": "slow", "name": "Slow"}]}}
+ if os.environ.get("FAKE_ACP_CONFIG_OPTIONS"):
+ result["configOptions"] = [{"id": "model", "category": "model", "options": [
+ {"value": "m-a"}, {"value": "m-off", "_meta": {"copilotEnablement": "disabled"}}]}]
+ send({"jsonrpc": "2.0", "id": i, "result": result})
+ elif m == "session/prompt":
+ send({"jsonrpc": "2.0", "method": "session/update", "params": {"update": {
+ "sessionUpdate": "agent_message_chunk", "content": {"text": "hello"}}}})
+ send({"jsonrpc": "2.0", "id": i, "result": {"stopReason": "end_turn"}})
+ elif i is not None:
+ send({"jsonrpc": "2.0", "id": i, "result": {}})
+'''
+
+
+def agent(tmp_path, monkeypatch):
+ script = tmp_path / "fake_acp_agent.py"
+ script.write_text(_AGENT, encoding="utf-8")
+ log = tmp_path / "acp.jsonl"
+ monkeypatch.setenv("FAKE_ACP_LOG", str(log))
+ warnings.simplefilter("ignore", DeprecationWarning)
+
+ def methods() -> list[str]:
+ return [json.loads(line)["method"] for line in log.read_text().splitlines() if "method" in json.loads(line)]
+
+ return [sys.executable, str(script)], methods
+
+
+_HI = [{"role": "user", "content": "hi"}]
+
+
+def test_kiro_acp_pinned_import_shape(agent, tmp_path):
+ (command, script), _ = agent
+ # kiro_acp_client.py@02c4dd0: module-top import of the marker constant next to the class.
+ from agent.copilot_acp_client import ACP_MARKER_BASE_URL as _COPILAT_MARKER, CopilotACPClient
+
+ class KiroACPClient(CopilotACPClient):
+ def __init__(self, *, base_url=None, command=None, args=None, **kwargs):
+ super().__init__(base_url=base_url or "acp://kiro", acp_command=command, acp_args=args, **kwargs)
+
+ def _spawn(self):
+ try:
+ return super()._spawn()
+ except RuntimeError as exc:
+ if "Could not start Copilot ACP command" in str(exc):
+ raise RuntimeError("Could not start Kiro ACP command") from exc
+ raise
+
+ assert _COPILAT_MARKER == "acp://copilot"
+ client = KiroACPClient(command=command, args=[script], acp_cwd=str(tmp_path))
+ assert client.chat.completions.create(model=None, messages=_HI, timeout=30).choices[0].message.content == "hello"
+ missing = KiroACPClient(command=str(tmp_path / "absent"), args=["acp"], acp_cwd=str(tmp_path))
+ with pytest.raises(RuntimeError, match="Could not start Kiro ACP command"):
+ missing.chat.completions.create(messages=_HI, timeout=10)
+
+
+def test_grok_acp_pinned_import_and_popen_patch_shape(agent, tmp_path, monkeypatch):
+ (command, script), methods = agent
+ # grok_acp_client.py@2851d66: setup probe env, its own _spawn through the module's subprocess,
+ # and model selection through the former module helper.
+ import agent.copilot_acp_client as copilot_mod
+ from agent.copilot_acp_client import (
+ CopilotACPClient, _acp_supported, _build_subprocess_env, _model_selection_request)
+
+ assert _build_subprocess_env()["HOME"]
+ assert _acp_supported(command, ["stdio"]) is True # no --acp in args: no probe
+ spawned: list[list[str]] = []
+ real_popen = subprocess.Popen
+
+ def _popen(argv, *args, **kwargs):
+ spawned.append(list(argv))
+ return real_popen(argv, *args, **kwargs)
+
+ # The plugin's tests patch the module path; it must reach every ACP spawn, the base class's included.
+ monkeypatch.setattr("agent.copilot_acp_client.subprocess.Popen", _popen)
+
+ class GrokACPClient(CopilotACPClient):
+ def _spawn(self):
+ proc = copilot_mod.subprocess.Popen(
+ [self._acp_command] + self._acp_args, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+ stderr=subprocess.PIPE, text=True, bufsize=1, cwd=self._acp_cwd, env=_build_subprocess_env())
+ with self._active_process_lock:
+ self._active_processes.add(proc)
+ self.is_closed = False
+ return proc
+
+ def _run_prompt(self, prompt_text, *, timeout_seconds, model=None):
+ with self._session(timeout_seconds) as (session, request):
+ if model and model != "copilot-acp" and (selection := _model_selection_request(session, model)):
+ request(*selection)
+ parts: list[str] = []
+ request("session/prompt", {"sessionId": session["sessionId"], "prompt": [{"type": "text", "text": prompt_text}]},
+ text_parts=parts, reasoning_parts=[])
+ return "".join(parts), ""
+
+ monkeypatch.setenv("FAKE_ACP_CONFIG_OPTIONS", "1")
+ grok = GrokACPClient(command=command, args=[script], acp_cwd=str(tmp_path))
+ assert grok.chat.completions.create(model="m-a", messages=_HI, timeout=30).choices[0].message.content == "hello"
+ assert "session/set_config_option" in methods()
+ # Former semantics: the copilot placeholder and copilotEnablement-disabled ids are never selected.
+ session = {"sessionId": "s1", "configOptions": [{"id": "model", "category": "model", "options": [
+ {"value": "m-a"}, {"value": "m-off", "_meta": {"copilotEnablement": "disabled"}}]}]}
+ assert [_model_selection_request(session, m) for m in ("copilot-acp", "m-off")] == [None, None]
+
+ plain = CopilotACPClient(command=command, args=[script], acp_cwd=str(tmp_path))
+ plain.chat.completions.create(messages=_HI, timeout=30)
+ assert spawned == [[command, script], [command, script]]
+
+
+def test_cursor_acp_pinned_import_shape(agent, tmp_path):
+ (command, script), methods = agent
+ # cursor-acp __init__.py@d5b6146: own completion shaping on the former timeout normaliser,
+ # name-based model selection over the legacy session/set_model, discovery without fs access.
+ from agent.copilot_acp_client import CopilotACPClient
+
+ class CursorACPClient(CopilotACPClient):
+ def _create_chat_completion(self, *, model=None, messages=None, timeout=None, **_):
+ from agent.copilot_acp_client import _effective_timeout
+
+ text, _reasoning = self._run_prompt("prompt", timeout_seconds=_effective_timeout(timeout), model=model)
+ return text
+
+ def list_models(self, *, timeout_seconds=15.0):
+ with self._session(timeout_seconds, allow_file_requests=False) as (session, _):
+ return [m["modelId"].split("[")[0] for m in session["models"]["availableModels"]]
+
+ def _run_prompt(self, prompt_text, *, timeout_seconds, model=None):
+ with self._session(timeout_seconds) as (session, request):
+ ids = {m["name"]: m["modelId"] for m in session["models"]["availableModels"]}
+ request("session/set_model", {"sessionId": session["sessionId"], "modelId": ids[model]})
+ parts: list[str] = []
+ request("session/prompt", {"sessionId": session["sessionId"], "prompt": [{"type": "text", "text": prompt_text}]},
+ text_parts=parts, reasoning_parts=[])
+ return "".join(parts), ""
+
+ timeout = type("Timeout", (), {"connect": 5.0, "read": 30.0, "write": None, "pool": None})()
+ client = CursorACPClient(acp_command=command, acp_args=[script], acp_cwd=str(tmp_path))
+ assert client.chat.completions.create(model="Fast", messages=_HI, timeout=timeout) == "hello"
+ assert client.list_models() == ["fast", "slow"]
+ assert methods().count("session/set_model") == 1
+
+
+# Every top-level name agent/copilot_acp_client.py had before the deprecation (0c771d7a5ba).
+_FORMER_SURFACE = (
+ "ACP_MARKER_BASE_URL", "Any", "Callable", "CopilotACPClient", "Iterator", "Path", "SimpleNamespace",
+ "_ACP_PROBE_CACHE", "_DEFAULT_TIMEOUT_SECONDS", "_DEPRECATED_CLI_ERROR", "_DEPRECATION_MARKERS",
+ "_DEPRECATION_REQUIRED", "_FS_HANDLERS", "_INITIALIZE_PARAMS", "_PROMPT_PREAMBLE", "_ROLE_LABELS",
+ "_acp_supported", "_build_subprocess_env", "_completion_to_stream_chunks", "_effective_timeout",
+ "_enabled_id_list", "_ensure_path_within_cwd", "_extract_tool_calls_from_text", "_format_messages_as_prompt",
+ "_fs_read_text_file", "_fs_write_text_file", "_is_gh_copilot_deprecation_message", "_jsonrpc_error",
+ "_jsonrpc_result", "_legacy_session_model_ids", "_model_config_option", "_model_selection_request",
+ "_render_message_content", "_render_tool_bridge_sections", "_resolve_args", "_resolve_command",
+ "_resolve_home_dir", "_session_model_ids", "contextlib", "get_nt_namespace_error", "get_read_block_error",
+ "get_write_denied_error", "hermes_subprocess_env", "is_write_approval_required", "json", "logger", "logging",
+ "os", "queue", "re", "redact_sensitive_text", "resolve_agent_cwd", "shlex", "subprocess", "tempfile",
+ "threading", "time", "deque",
+)
+
+
+def test_alias_serves_its_whole_former_surface_and_warns_once(monkeypatch):
+ import agent.copilot_acp_client as alias
+
+ monkeypatch.setattr(alias, "_warned", False)
+ with warnings.catch_warnings(record=True) as caught:
+ warnings.simplefilter("always")
+ missing = [name for name in _FORMER_SURFACE if not hasattr(alias, name)]
+ assert missing == []
+ deprecations = [str(w.message) for w in caught if w.category is DeprecationWarning]
+ assert len(deprecations) == 1 and "agent.acp_client.ACPClient" in deprecations[0]
+ assert alias._session_model_ids({"models": {"availableModels": [
+ {"modelId": "a"}, {"modelId": "b", "_meta": {"copilotEnablement": "disabled"}}]}}) == ["a"]
+ for name in ("HERMES_COPILOT_ACP_COMMAND", "COPILOT_CLI_PATH", "HERMES_COPILOT_ACP_ARGS"):
+ monkeypatch.delenv(name, raising=False)
+ assert (alias._resolve_command(), alias._resolve_args()) == ("copilot", ["--acp", "--stdio"])
+ monkeypatch.setenv("COPILOT_CLI_PATH", "/opt/copilot")
+ assert alias._resolve_command() == "/opt/copilot"
diff --git a/website/docs/developer-guide/model-provider-plugin.md b/website/docs/developer-guide/model-provider-plugin.md
index cb15ebd96d5..f58546a3cc4 100644
--- a/website/docs/developer-guide/model-provider-plugin.md
+++ b/website/docs/developer-guide/model-provider-plugin.md
@@ -412,7 +412,7 @@ class MyAgentProfile(ProviderProfile):
Keep the class attributes in step with the profile's `process_*` fields. Override `_handle_server_message(msg, *, process, cwd, text_parts, reasoning_parts, allow_file_requests=True)` to render extra `session/update` kinds (call `super()` for the rest). `hermes_cli.auth.resolve_external_process_provider_credentials(name)` returns the resolved `command`/`args`/`base_url` for a `fetch_models()` probe.
-`agent.copilot_acp_client.CopilotACPClient` is a deprecated alias of `ACPClient` with the old GitHub Copilot launch defaults; importing it warns once per process. Subclass `ACPClient` instead (set `placeholder_model` to your own placeholder id). The alias stays for at least two minor releases.
+`agent.copilot_acp_client.CopilotACPClient` is a deprecated alias of `ACPClient` with the old GitHub Copilot launch defaults. The module keeps its whole former surface for listed catalog plugins pinned to it (`ACP_MARKER_BASE_URL`, its former private helpers, `subprocess` for `Popen` patching); the first access of any of its names warns once per process. Subclass `ACPClient` instead (set `placeholder_model` to your own placeholder id). The alias stays for at least two minor releases.
### Picker rows for non-api-key plugins