Skip to content

The agent that grows with you

test(acp): restore core coverage of the public ACPClient on a generic fake agent

Tekniumf00891f671fc
diff --git a/tests/agent/test_acp_client_invariants.py b/tests/agent/test_acp_client_invariants.py
new file mode 100644
index 00000000000..0ca1bbd8cf4
--- /dev/null
+++ b/tests/agent/test_acp_client_invariants.py
@@ -0,0 +1,494 @@
+"""Safety and lifecycle invariants of the public ACP stdio client (``agent.acp_client.ACPClient``).
+
+Every ``external_process`` model provider (a plugin profile whose ``create_client`` returns an
+``ACPClient`` subclass) inherits these, so they are pinned on the generic base with a vendor-neutral
+subclass: the agent's own permission requests are never granted (Hermes has no human channel on that
+path), the ``fs/*`` bridge is confined to the session cwd, honours the write deny-list and redacts
+secrets it hands back, and every spawned agent process is reaped by its own session or by ``close()``.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from agent.acp_client import _ACP_PROBE_CACHE, ACPClient, _acp_supported, _model_selection_request
+
+
+class _AcmeClient(ACPClient):
+ """A third-party subclass that customises only the launch defaults and labels."""
+
+ default_command = "acme-agent"
+ default_args = ("--acp", "--stdio")
+ command_env_vars = ("ACME_ACP_COMMAND",)
+ args_env_var = "ACME_ACP_ARGS"
+ marker_base_url = "acp://acme"
+ placeholder_model = "acme-acp"
+ label = "Acme ACP"
+
+
+class _FakeProcess:
+ def __init__(self) -> None:
+ self.stdin = io.StringIO()
+
+
+def _dispatch(client: ACPClient, message: dict, *, cwd: str) -> dict:
+ """Feed one agent->client request through the client and return the JSON-RPC reply it wrote."""
+ process = _FakeProcess()
+ handled = client._handle_server_message(message, process=process, cwd=cwd, text_parts=[], reasoning_parts=[])
+ assert handled
+ payload = process.stdin.getvalue().strip()
+ assert payload, "the client must answer every agent request"
+ return json.loads(payload)
+
+
+def _request(method: str, params: dict, msg_id: int = 7) -> dict:
+ return {"jsonrpc": "2.0", "id": msg_id, "method": method, "params": params}
+
+
+def client(tmp_path):
+ return _AcmeClient(acp_cwd=str(tmp_path))
+
+
[email protected](autouse=True)
+def _clear_probe_cache():
+ _ACP_PROBE_CACHE.clear()
+ yield
+ _ACP_PROBE_CACHE.clear()
+
+
+# ── permission + fs bridge ──────────────────────────────────────────────────────────────────
+
+
+def test_agent_permission_request_is_answered_cancelled_never_granted(client, tmp_path):
+ response = _dispatch(client, _request("session/request_permission", {
+ "sessionId": "s1", "toolCall": {"toolCallId": "tc1", "title": "rm -rf /", "kind": "execute"},
+ "options": [{"optionId": "allow-always", "name": "Always", "kind": "allow_always"},
+ {"optionId": "allow-once", "name": "Allow", "kind": "allow_once"}]}), cwd=str(tmp_path))
+ assert response["id"] == 7
+ assert response["result"]["outcome"] == {"outcome": "cancelled"}, response
+
+
[email protected]("redact_toggle", [True, False], ids=["redaction-on", "redaction-off"])
+def test_read_text_file_redacts_sensitive_content(client, tmp_path, redact_toggle):
+ secret_file = tmp_path / "config.env"
+ secret_file.write_text("OPENAI_API_KEY=sk-proj-abc123def456ghi789jkl012", encoding="utf-8")
+
+ # agent.redact snapshots HERMES_REDACT_SECRETS at import time into _REDACT_ENABLED, so patching
+ # os.environ is a no-op; flip the constant. The fs bridge hands file text to a third-party agent
+ # process, so it redacts whatever the user's display toggle says.
+ with patch("agent.redact._REDACT_ENABLED", redact_toggle):
+ response = _dispatch(client, _request("fs/read_text_file", {"path": str(secret_file)}), cwd=str(tmp_path))
+
+ content = (response.get("result") or {}).get("content") or ""
+ assert "abc123def456" not in content
+ assert "OPENAI_API_KEY=" in content
+
+
+def test_read_text_file_outside_the_session_cwd_is_refused(client, tmp_path):
+ workspace = tmp_path / "workspace"
+ workspace.mkdir()
+ outside = tmp_path / "outside.txt"
+ outside.write_text("OUTSIDE-SECRET-5512", encoding="utf-8")
+ escape = workspace / ".." / "outside.txt"
+
+ for path in (outside, escape):
+ response = _dispatch(client, _request("fs/read_text_file", {"path": str(path)}), cwd=str(workspace))
+ assert "error" in response and "OUTSIDE-SECRET" not in json.dumps(response), response
+
+
+def test_read_text_file_through_a_symlink_out_of_the_cwd_is_refused(client, tmp_path):
+ workspace = tmp_path / "workspace"
+ workspace.mkdir()
+ (tmp_path / "outside.txt").write_text("OUTSIDE-SECRET-5512", encoding="utf-8")
+ link = workspace / "inside-looking.txt"
+ try:
+ link.symlink_to(tmp_path / "outside.txt")
+ except OSError:
+ pytest.skip("symlinks unavailable on this host")
+
+ response = _dispatch(client, _request("fs/read_text_file", {"path": str(link)}), cwd=str(workspace))
+ assert "error" in response and "OUTSIDE-SECRET" not in json.dumps(response), response
+
+
+def test_relative_fs_paths_are_refused(client, tmp_path):
+ (tmp_path / "note.txt").write_text("hello", encoding="utf-8")
+ response = _dispatch(client, _request("fs/read_text_file", {"path": "note.txt"}), cwd=str(tmp_path))
+ assert "error" in response, response
+
+
+def test_fs_read_text_file_decodes_as_utf8_under_non_utf8_locale(client, tmp_path):
+ """Regression for #18637: the fs bridge read with the locale codec, so on GBK/CP932/CP949 hosts
+ any source file with non-ASCII content crashed the agent's read_file."""
+ target = tmp_path / "note.md"
+ target.write_text("# 中文标题\nem dash — here\n", encoding="utf-8")
+ original_read_text = Path.read_text
+
+ def strict_read_text(self, encoding=None, errors=None, **kwargs):
+ if self == target and encoding not in ("utf-8", "utf-8-sig"):
+ raise UnicodeDecodeError("gbk", b"\x94", 0, 1, "illegal multibyte sequence")
+ return original_read_text(self, encoding=encoding, errors=errors, **kwargs)
+
+ with patch.object(Path, "read_text", strict_read_text):
+ response = _dispatch(client, _request("fs/read_text_file", {"path": str(target)}), cwd=str(tmp_path))
+
+ assert "error" not in response, response
+ content = (response.get("result") or {}).get("content") or ""
+ assert "中文标题" in content and "em dash —" in content
+
+
+def test_write_text_file_outside_the_session_cwd_is_refused(client, tmp_path):
+ workspace = tmp_path / "workspace"
+ workspace.mkdir()
+ outside = tmp_path / "outside.txt"
+ response = _dispatch(client, _request("fs/write_text_file", {"path": str(outside), "content": "pwned"}),
+ cwd=str(workspace))
+ assert "error" in response, response
+ assert not outside.exists()
+
+
+def test_write_text_file_respects_safe_root(client, tmp_path):
+ safe_root = tmp_path / "workspace"
+ safe_root.mkdir()
+ outside = tmp_path / "outside.txt"
+
+ with patch.dict(os.environ, {"HERMES_WRITE_SAFE_ROOT": str(safe_root)}, clear=False):
+ response = _dispatch(client, _request("fs/write_text_file", {"path": str(outside), "content": "should-not-write"}),
+ cwd=str(tmp_path))
+
+ assert "error" in response
+ assert "HERMES_WRITE_SAFE_ROOT" in str(response["error"])
+ assert not outside.exists()
+
+
+def test_write_text_file_inside_the_cwd_lands(client, tmp_path):
+ target = tmp_path / "sub" / "out.txt"
+ response = _dispatch(client, _request("fs/write_text_file", {"path": str(target), "content": "written"}),
+ cwd=str(tmp_path))
+ assert "error" not in response, response
+ assert target.read_text(encoding="utf-8") == "written"
+
+
+def test_unknown_agent_request_gets_method_not_found(client, tmp_path):
+ response = _dispatch(client, _request("terminal/create", {"command": "id"}), cwd=str(tmp_path))
+ assert response["error"]["code"] == -32601, response
+
+
+# ── process lifecycle on a shared client ────────────────────────────────────────────────────
+#
+# Clients are cached per provider config and served to every concurrent caller, so one ACPClient can
+# run several ACP sessions at once. Each session must reap ITS OWN child on exit: reaping whatever
+# most recently claimed shared state kills a sibling's live process and leaks the session's own.
+
+
+_FAKE_ACP_SERVER = """import json
+import sys
+import time
+
+for line in sys.stdin:
+ request = json.loads(line)
+ method = request.get("method")
+ if method == "initialize":
+ result = {"protocolVersion": 1}
+ elif method == "session/new":
+ result = {"sessionId": "s1"}
+ elif method == "session/prompt":
+ time.sleep(0.4)
+ print(json.dumps({"jsonrpc": "2.0", "method": "session/update", "params": {
+ "update": {"sessionUpdate": "agent_message_chunk", "content": {"text": "done"}},
+ }}), flush=True)
+ result = {"stopReason": "end_turn"}
+ else:
+ result = {}
+ print(json.dumps({"jsonrpc": "2.0", "id": request["id"], "result": result}), flush=True)
+"""
+
+
+def _recording_client(tmp_path, spawned):
+ server = tmp_path / "fake_acp_server.py"
+ server.write_text(_FAKE_ACP_SERVER, encoding="utf-8")
+ client = _AcmeClient(command=sys.executable, args=[str(server)], acp_cwd=str(tmp_path))
+ real_spawn = client._spawn
+
+ def record_spawn():
+ proc = real_spawn()
+ spawned.append(proc)
+ return proc
+
+ client._spawn = record_spawn
+ return client
+
+
+def test_overlapping_sessions_reap_their_own_process(tmp_path):
+ spawned = []
+ client = _recording_client(tmp_path, spawned)
+
+ session_a = client._session(30)
+ session_b = client._session(30)
+ session_a.__enter__()
+ session_b.__enter__()
+
+ proc_a, proc_b = spawned
+ try:
+ session_a.__exit__(None, None, None)
+
+ leaked = proc_a.poll() is None
+ killed = proc_b.poll() is not None
+ assert not leaked and not killed, f"session A teardown: own child leaked={leaked}, sibling process killed={killed}"
+ assert client.is_closed is False, "a shared client is not closed while a sibling session is live"
+
+ session_b.__exit__(None, None, None)
+ assert proc_b.poll() is not None
+ assert client.is_closed is True, "the last session to drain still flips is_closed for single-session callers"
+ finally:
+ for proc in spawned:
+ if proc.poll() is None:
+ proc.kill()
+
+
+def test_close_terminates_every_live_session_process(tmp_path):
+ spawned = []
+ client = _recording_client(tmp_path, spawned)
+
+ session_a = client._session(30)
+ session_b = client._session(30)
+ session_a.__enter__()
+ session_b.__enter__()
+ try:
+ client.close()
+ assert all(proc.poll() is not None for proc in spawned), [proc.poll() for proc in spawned]
+ assert client.is_closed is True
+ finally:
+ for proc in spawned:
+ if proc.poll() is None:
+ proc.kill()
+
+
+def test_completed_prompt_leaves_no_agent_process(tmp_path):
+ spawned = []
+ client = _recording_client(tmp_path, spawned)
+
+ completion = client.chat.completions.create(model="acme-acp", messages=[{"role": "user", "content": "hi"}])
+
+ assert completion.choices[0].message.content == "done"
+ assert len(spawned) == 1 and spawned[0].poll() is not None
+ assert client.is_closed is True
+
+
+_CRASHING_ACP_CLI = """
+import subprocess, sys
+# Hand stderr to a straggler that writes the crash text after this process has exited, so
+# poll() reports the exit before the client has read a single stderr line.
+subprocess.Popen([sys.executable, "-c",
+ "import sys, time; time.sleep(0.3); print('fatal: agent segfaulted', file=sys.stderr)"])
+sys.exit(3)
+"""
+
+
+def test_cli_death_is_reported_as_a_crash_not_a_timeout(tmp_path):
+ """A CLI that dies must surface its crash text even when stderr lags the exit: the old path
+ raised TimeoutError there, which the agent loop retries on a different (larger) budget."""
+ server = tmp_path / "crashing_acp.py"
+ server.write_text(_CRASHING_ACP_CLI, encoding="utf-8")
+ client = _AcmeClient(command=sys.executable, args=[str(server)], acp_cwd=str(tmp_path))
+ with pytest.raises(RuntimeError, match="exited early: fatal: agent segfaulted"):
+ with client._session(30):
+ pass
+
+
+def test_model_discovery_does_not_allow_file_requests(tmp_path):
+ """``list_models`` opens a session only to read the catalog: an fs request on that path is refused."""
+ target = tmp_path / "should-not-be-read.txt"
+ target.write_text("private", encoding="utf-8")
+ server = tmp_path / "fake_acp_fs_request.py"
+ server.write_text(
+ f"""import json
+import sys
+
+initialize = json.loads(sys.stdin.readline())
+print(json.dumps({{"jsonrpc": "2.0", "id": initialize["id"], "result": {{"protocolVersion": 1}}}}), flush=True)
+session = json.loads(sys.stdin.readline())
+print(json.dumps({{"jsonrpc": "2.0", "id": 99, "method": "fs/read_text_file", "params": {{"path": {str(target)!r}}}}}), flush=True)
+file_response = json.loads(sys.stdin.readline())
+assert file_response["error"]["code"] == -32601
+print(json.dumps({{"jsonrpc": "2.0", "id": session["id"], "result": {{"sessionId": "catalog-session", "configOptions": [{{"id": "model", "options": [{{"value": "model-sol"}}]}}]}}}}), flush=True)
+""",
+ encoding="utf-8",
+ )
+ client = _AcmeClient(command=sys.executable, args=[str(server)], acp_cwd=str(tmp_path))
+
+ assert client.list_models(timeout_seconds=30) == ["model-sol"]
+
+
+# ── OpenAI facade ───────────────────────────────────────────────────────────────────────────
+
+
+def test_stream_true_preserves_tool_call_deltas(client):
+ tool_response = (
+ "<tool_call>"
+ '{"id":"call_read","type":"function",'
+ '"function":{"name":"read_file","arguments":"{\\"path\\":\\"README.md\\"}"}}'
+ "</tool_call>"
+ )
+
+ with patch.object(client, "_run_prompt", return_value=(tool_response, "")):
+ stream = client._create_chat_completion(
+ model="acme-acp", messages=[{"role": "user", "content": "read README.md"}], stream=True)
+
+ chunks = list(stream)
+ delta = chunks[0].choices[0].delta
+ assert delta.content is None
+ assert chunks[0].choices[0].finish_reason == "tool_calls"
+ assert len(delta.tool_calls) == 1
+ tool_delta = delta.tool_calls[0]
+ assert (tool_delta.index, tool_delta.id, tool_delta.function.name) == (0, "call_read", "read_file")
+ assert json.loads(tool_delta.function.arguments) == {"path": "README.md"}
+ assert chunks[1].choices == []
+
+
+def test_run_prompt_receives_picker_model(tmp_path):
+ """``_create_chat_completion`` forwards ``model`` into ``_run_prompt``: dropping it reduced the
+ selection to prompt text."""
+ client = _AcmeClient(acp_cwd=str(tmp_path))
+ seen = {}
+
+ def fake_run_prompt(prompt_text, *, timeout_seconds, model=None):
+ seen["model"] = model
+ return "ok", ""
+
+ with patch.object(_AcmeClient, "_run_prompt", side_effect=fake_run_prompt):
+ client._create_chat_completion(model="model-terra", messages=[{"role": "user", "content": "hi"}])
+ assert seen["model"] == "model-terra"
+
+
+# ── child HOME ──────────────────────────────────────────────────────────────────────────────
+
+
+def _launch_client(tmp_path):
+ return _AcmeClient(api_key="acme-acp", base_url="acp://acme", acp_command="acme-agent",
+ acp_args=["--acp", "--stdio"], acp_cwd=str(tmp_path))
+
+
+def _capture_popen(captured):
+ def _fake(cmd, **kwargs):
+ captured["cmd"], captured["kwargs"] = cmd, kwargs
+ raise FileNotFoundError("acme-agent not found")
+ return _fake
+
+
+def test_run_prompt_preserves_real_home_when_profile_home_available(monkeypatch, tmp_path):
+ hermes_home = tmp_path / "hermes"
+ (hermes_home / "home").mkdir(parents=True)
+ real_home = tmp_path / "real-home"
+ real_home.mkdir()
+ monkeypatch.setenv("HOME", str(real_home))
+ monkeypatch.setenv("HERMES_HOME", str(hermes_home))
+ # Hermeticity: an ambient HERMES_REAL_HOME / TERMINAL_HOME_MODE outranks HOME in the candidate
+ # ladder, and a containerized runner flips get_subprocess_home()'s auto mode; the host branch is
+ # the contract under test.
+ monkeypatch.delenv("HERMES_REAL_HOME", raising=False)
+ monkeypatch.delenv("TERMINAL_HOME_MODE", raising=False)
+ monkeypatch.setattr("hermes_constants.is_container", lambda: False)
+ captured = {}
+
+ # The --acp support probe runs subprocess.run before Popen; inconclusive so no host CLI interferes.
+ with patch("agent.acp_client.subprocess.run", side_effect=FileNotFoundError), \
+ patch("agent.acp_client.subprocess.Popen", side_effect=_capture_popen(captured)), \
+ pytest.raises(RuntimeError, match="Could not start Acme ACP command"):
+ _launch_client(tmp_path)._run_prompt("hello", timeout_seconds=1)
+
+ assert captured["kwargs"]["env"]["HOME"] == str(real_home)
+ assert captured["kwargs"]["env"]["HERMES_REAL_HOME"] == str(real_home)
+
+
+def test_run_prompt_passes_home_when_parent_env_is_clean(monkeypatch, tmp_path):
+ monkeypatch.delenv("HOME", raising=False)
+ monkeypatch.delenv("HERMES_HOME", raising=False)
+ captured = {}
+
+ with patch("agent.acp_client.subprocess.run", side_effect=FileNotFoundError), \
+ patch("agent.acp_client.subprocess.Popen", side_effect=_capture_popen(captured)), \
+ pytest.raises(RuntimeError, match="Could not start Acme ACP command"):
+ _launch_client(tmp_path)._run_prompt("hello", timeout_seconds=1)
+
+ assert captured["kwargs"]["env"]["HOME"]
+
+
+# ── --acp support probe (#87309) ────────────────────────────────────────────────────────────
+
+
+def _completed(returncode=0, stdout=""):
+ return subprocess.CompletedProcess(args=[], returncode=returncode, stdout=stdout, stderr="")
+
+
+def test_probe_true_when_help_advertises_acp():
+ with patch("agent.acp_client.subprocess.run", return_value=_completed(stdout="Usage: acme-agent [--acp] [--stdio]")):
+ assert _acp_supported("acme-agent", ["--acp", "--stdio"]) is True
+
+
+def test_probe_false_when_help_lacks_acp_and_run_prompt_fast_fails(tmp_path):
+ with patch("agent.acp_client.subprocess.run", return_value=_completed(stdout="Usage: other [--print] [--model]")), \
+ pytest.raises(RuntimeError, match="ACP transport not supported"):
+ _launch_client(tmp_path)._run_prompt("hello", timeout_seconds=1)
+
+
+def test_probe_inconclusive_falls_through_to_spawn_error(tmp_path):
+ """Missing binary: the probe must NOT mask the established spawn error."""
+ with patch("agent.acp_client.subprocess.run", side_effect=FileNotFoundError("acme-agent not found")), \
+ patch("agent.acp_client.subprocess.Popen", side_effect=FileNotFoundError("acme-agent not found")), \
+ pytest.raises(RuntimeError, match="Could not start Acme ACP command"):
+ _launch_client(tmp_path)._run_prompt("hello", timeout_seconds=1)
+
+
+def test_probe_skipped_for_custom_args_without_acp():
+ with patch("agent.acp_client.subprocess.run") as run_mock:
+ assert _acp_supported("mycli", ["--custom-transport"]) is True
+ run_mock.assert_not_called()
+
+
+# ── session model selection ─────────────────────────────────────────────────────────────────
+#
+# Agent CLIs may validate but IGNORE a ``--model`` spawn flag; the session runs the CLI's default
+# unless the client selects the model over ACP after ``session/new``.
+
+
+def _session_with_config_options():
+ return {"sessionId": "s1", "configOptions": [{
+ "id": "model", "category": "model", "type": "select", "currentValue": "auto",
+ "options": [{"value": "auto", "name": "Auto"}, {"value": "model-terra", "name": "Terra"},
+ {"value": "model-fable", "name": "Fable", "_meta": {"acmePolicy": "off"}}]}]}
+
+
+def _acme_disabled(entry):
+ return (entry.get("_meta") or {}).get("acmePolicy") == "off"
+
+
+def test_model_selection_prefers_stable_config_option():
+ assert _model_selection_request(_session_with_config_options(), "model-terra") == (
+ "session/set_config_option", {"sessionId": "s1", "configId": "model", "value": "model-terra"})
+
+
+def test_model_selection_rejects_disabled_config_option():
+ assert _model_selection_request(_session_with_config_options(), "model-fable", disabled=_acme_disabled) is None
+
+
+def test_model_selection_rejects_unknown_config_option():
+ assert _model_selection_request(_session_with_config_options(), "not-served-here") is None
+
+
+def test_model_selection_falls_back_to_legacy_extension():
+ legacy_session = {"sessionId": "s1", "models": {"availableModels": [{"modelId": "auto"}, {"modelId": "model-terra"}]}}
+ assert _model_selection_request(legacy_session, "model-terra") == (
+ "session/set_model", {"sessionId": "s1", "modelId": "model-terra"})
+
+
+def test_model_selection_skips_provider_placeholder_slug():
+ assert _model_selection_request(_session_with_config_options(), "acme-acp", placeholder="acme-acp") is None
diff --git a/tests/e2e/core/providers/test_native_acp_agent.py b/tests/e2e/core/providers/test_native_acp_agent.py
new file mode 100644
index 00000000000..c91df78abfa
--- /dev/null
+++ b/tests/e2e/core/providers/test_native_acp_agent.py
@@ -0,0 +1,327 @@
+"""ACP agent wire conformance, part 1: the multi-call tool flow, resume, and the process lifecycle.
+
+An ``external_process`` model provider makes Hermes spawn an external ACP agent per model call and
+speak the Agent Client Protocol to it over stdio through the public ``agent.acp_client.ACPClient``.
+Here the provider is ``fake-acp``, a user model-provider plugin written into the temp
+``HERMES_HOME`` (``tests/fakes/providers/fake_acp_agent.py::install_provider_plugin``) whose
+``create_client`` returns an ``ACPClient`` subclass, and the agent is that module run as a script: a
+fake that validates every request against the published ACP schema and replays scripted turns.
+Everything on the Hermes side is real: the ``hermes chat -q`` process, user plugin discovery, runtime
+resolution from ``config.yaml`` + the profile ``.env`` (the profile's ``process_command_env_vars`` /
+``process_args_env_var``), the ACP client, the agent loop, the ``read_file`` tool and ``state.db``.
+
+Contract under test (documented in ``agent/acp_client.py`` and the ACP spec):
+
+* each model call is a fresh agent process: ``initialize`` -> ``session/new`` (absolute cwd) ->
+ model selection via the advertised ``model`` config option -> ``session/prompt``; every request is
+ schema-valid;
+* ACP has no tools channel: Hermes' tools travel in the prompt text, a ``<tool_call>`` block in the
+ agent's message runs a REAL Hermes tool, and the result is in the next call's prompt;
+* ``--resume`` in a new process runs in a new agent process whose prompt carries the persisted history
+ (turn 1 in order, then the new question), with nothing duplicated;
+* agent-side ``session/request_permission`` is never granted (Hermes has no human channel there) and
+ ``fs/read_text_file`` is confined to the session cwd;
+* no agent process outlives the CLI, including one that ignores SIGTERM and stdin EOF.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import signal
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable
+
+import pytest
+
+from tests.e2e.core._pending_fixes import known_gate
+from tests.e2e.core.providers._native_helpers import (
+ ChatResult,
+ KnownSymptom,
+ NativeHome,
+ assert_no_duplicate_assistant_text,
+ latest_session,
+ make_home,
+ messages,
+ run_chat,
+ session_ids,
+ tool_calls_of,
+ wait_until,
+)
+from tests.fakes.providers import fake_acp_agent as acp
+
+pytest.importorskip("acp.schema", reason="the fake validates against the agent-client-protocol package (acp extra)")
+
+pytestmark = [
+ pytest.mark.platforms("linux"), # POSIX launcher script + /proc pid checks
+ pytest.mark.live_system_guard_bypass,
+]
+
+MODELS = ["fake-model-a", "fake-model-b"]
+CONFIGURED_MODEL = "fake-model-b" # NOT the agent's default: selection must happen on the wire
+CANARY = "CANARY-7731-acp"
+SECRET = "OUTSIDE-CWD-SECRET-5512"
+Q1 = "Read canary.txt and tell me what it says (Q1-marker)."
+Q2 = "Now summarise what you found (Q2-marker)."
+FINAL_ONE = f"The file says {CANARY} (FINAL-ONE)"
+FINAL_TWO = "Summary: the canary was read (FINAL-TWO)"
+LATE_TEXT = "LATE-ANSWER-65788"
+# Compaction: the turn pins ``--toolsets file`` so the prompt size does not depend on which optional tools
+# the host can advertise (browser tools appear only where agent-browser and Chromium exist). With that pin
+# the system prompt + tool bridge is ~3.5K estimated tokens and each file read adds ~0.6K, so eight reads
+# cross this absolute threshold mid-turn (ACP reports no usage, so Hermes estimates).
+COMPACT_THRESHOLD = 5_500
+COMPACT_TOOLSETS = ("--toolsets", "file")
+COMPACT_FILES = 8
+COMPACT_ASK = "Read f1.txt through f8.txt one by one, then say done (COMPACT-ASK)."
+SUMMARY = "SUMMARY-ACP-7f3: files f1..fN were read; each is lorem ipsum filler."
+FINAL_COMPACT = "All eight files read (FINAL-COMPACT)."
+
+
+# Red on current main for a tracked, open bug: key -> (the bug's own failure-message pattern, reason).
+KNOWN: dict[str, tuple[str, str]] = {
+ "late_chunk": (r"^late chunk dropped: \d+ model calls, stdout=",
+ "#65788 agent_message_chunk emitted after the session/prompt result is dropped"),
+}
+
+
+@dataclass
+class Scenario:
+ nh: NativeHome
+ fake: acp.AcpFake
+ runs: list[ChatResult] = field(default_factory=list)
+ extra: dict[str, Any] = field(default_factory=dict)
+
+
+def _acp_home(root: Path, fake: acp.AcpFake, model: str, **home_kw: Any) -> NativeHome:
+ """A temp home selecting the ``fake-acp`` user plugin provider, launch spec pointed at ``fake``."""
+ nh = make_home(root, {"provider": acp.PROVIDER, "default": model}, env_file=fake.env(), **home_kw)
+ acp.install_provider_plugin(nh.hermes_home)
+ return nh
+
+
+def _home(root: Path, turns: list[list[dict[str, Any]]], **fake_kw: Any) -> Scenario:
+ fake = acp.AcpFake(root / "acp", turns, models=MODELS, **fake_kw)
+ return Scenario(_acp_home(root, fake, CONFIGURED_MODEL), fake)
+
+
+def _alive(pid: int) -> bool:
+ """True while ``pid`` is a live (non-zombie) process."""
+ try:
+ with open(f"/proc/{pid}/stat", encoding="utf-8") as fh:
+ return fh.read().rsplit(")", 1)[1].split()[0] != "Z"
+ except (FileNotFoundError, ProcessLookupError, IndexError):
+ return False
+
+
+def _reap(fake: acp.AcpFake) -> None:
+ """Teardown: SIGKILL any fake agent this scenario spawned that is still alive (by recorded pid)."""
+ for pid in fake.pids():
+ if _alive(pid):
+ with contextlib.suppress(ProcessLookupError): # exited between the check and the kill
+ os.kill(pid, signal.SIGKILL)
+
+
+# ── scenarios (independent; run concurrently in the module fixture) ──────────────────────────
+
+
+def _flow(root: Path) -> Scenario:
+ """Turn 1 (two model calls): agent-side permission + a Hermes read_file call, then fs reads + the
+ answer. Turn 2: ``--resume`` in a new process. The agent ignores SIGTERM and stdin EOF."""
+ project = NativeHome(root).project
+ turns = [
+ [acp.tool_call("agent-native-1", "run shell", kind="execute"), acp.permission("agent-native-1"),
+ acp.message(acp.hermes_tool_call("call_rf_1", "read_file", {"path": str(project / "canary.txt")}))],
+ [acp.fs_read(str(project / "canary.txt")), acp.fs_read(str(root / "outside" / "secret.txt")),
+ acp.thought("REASONING-ONE: the tool result names the canary"), acp.message(FINAL_ONE)],
+ [acp.message(FINAL_TWO)],
+ ]
+ sc = _home(root, turns, ignore_sigterm=True)
+ (sc.nh.project / "canary.txt").write_text(CANARY + "\n", encoding="utf-8")
+ (root / "outside").mkdir()
+ (root / "outside" / "secret.txt").write_text(SECRET + "\n", encoding="utf-8")
+ sc.runs.append(run_chat(sc.nh, Q1))
+ if sc.runs[0].returncode == 0 and session_ids(sc.nh):
+ sc.extra["turn1_pids"] = sc.fake.pids()
+ sc.runs.append(run_chat(sc.nh, Q2, resume=latest_session(sc.nh)))
+ return sc
+
+
+def _late(root: Path) -> Scenario:
+ """The agent answers ``session/prompt`` first and streams the message chunk 250 ms later."""
+ sc = _home(root, [[acp.result(), acp.message(LATE_TEXT, delay=0.25)], [acp.message("SECOND-TRY-65788")]])
+ sc.runs.append(run_chat(sc.nh, "Say the late answer."))
+ return sc
+
+
+def _compaction(root: Path) -> Scenario:
+ """Eight read_file calls in one turn cross ``compression.threshold_tokens``; the summarizer runs
+ through the same ACP provider (no tool bridge -> the fake answers ``SUMMARY``)."""
+ project = NativeHome(root).project
+ turns = [[acp.thought(f"step {i}"), acp.message(acp.hermes_tool_call(
+ f"call_f{i}", "read_file", {"path": str(project / f"f{i}.txt")}))] for i in range(1, COMPACT_FILES + 1)]
+ fake = acp.AcpFake(root / "acp", [*turns, [acp.message(FINAL_COMPACT)]], models=MODELS, aux_text=SUMMARY)
+ nh = _acp_home(root, fake, CONFIGURED_MODEL,
+ extra_config={"compression": {"threshold_tokens": COMPACT_THRESHOLD, "protect_last_n": 4}})
+ for i in range(1, COMPACT_FILES + 1):
+ (nh.project / f"f{i}.txt").write_text(f"file {i} " + "lorem ipsum dolor " * 250 + "\n", encoding="utf-8")
+ sc = Scenario(nh, fake)
+ sc.runs.append(run_chat(nh, COMPACT_ASK, args=COMPACT_TOOLSETS))
+ return sc
+
+
+SCENARIOS: dict[str, Callable[[Path], Scenario]] = {"flow": _flow, "late": _late, "compaction": _compaction}
+
+
[email protected](scope="module")
+def outcomes(tmp_path_factory: pytest.TempPathFactory):
+ base = tmp_path_factory.mktemp("acp_agent")
+ with ThreadPoolExecutor(max_workers=len(SCENARIOS)) as pool:
+ futures = {name: pool.submit(fn, base / name) for name, fn in SCENARIOS.items()}
+ done = {name: fut.result() for name, fut in futures.items()}
+ yield done
+ for sc in done.values():
+ _reap(sc.fake)
+
+
+def _flow_ok(outcomes: dict[str, Scenario]) -> Scenario:
+ sc = outcomes["flow"]
+ assert len(sc.runs) == 2 and all(r.returncode == 0 for r in sc.runs), "\n\n".join(r.describe() for r in sc.runs)
+ return sc
+
+
+def _calls(fake: acp.AcpFake) -> dict[int, list[dict[str, Any]]]:
+ """Inbound client requests grouped per agent process (pid), in arrival order."""
+ grouped: dict[int, list[dict[str, Any]]] = {}
+ for rec in fake.inbound():
+ if rec["msg"] and rec["msg"].get("method"):
+ grouped.setdefault(rec["pid"], []).append(rec)
+ return grouped
+
+
+# ── tests ──────────────────────────────────────────────────────────────────────────────────────
+
+
+def test_hermes_tool_call_round_trips_through_acp_and_persists(outcomes):
+ """A ``<tool_call>`` in the agent's message runs Hermes' real read_file; the result reaches the
+ NEXT call's prompt; the CLI prints the answer; state.db pairs the call and result by id."""
+ sc = _flow_ok(outcomes)
+ assert FINAL_ONE in sc.runs[0].stdout, sc.runs[0].describe()
+ prompts = sc.fake.main_prompts()
+ assert len(prompts) == 3, f"expected 3 model calls (tool, answer, resumed answer), got {len(prompts)}"
+ first, second = acp.prompt_text(prompts[0]), acp.prompt_text(prompts[1])
+ assert '"name": "read_file"' in first, "read_file schema was not offered through the prompt tool bridge"
+ assert CANARY not in first, "the canary leaked into the prompt before the tool ran"
+ assert CANARY in second and second.index(Q1) < second.index(CANARY), (
+ "the read_file result must follow the user turn in the next call's prompt")
+
+ rows = messages(sc.nh, latest_session(sc.nh))
+ calls = [(r, tc) for r in rows if r["role"] == "assistant" for tc in tool_calls_of(r)]
+ assert [(tc["id"], tc["function"]["name"]) for _, tc in calls] == [("call_rf_1", "read_file")], calls
+ results = [r for r in rows if r["role"] == "tool"]
+ assert [r["tool_call_id"] for r in results] == ["call_rf_1"] and CANARY in results[0]["content"], results
+ finals = [r for r in rows if r["role"] == "assistant" and FINAL_ONE in (r["content"] or "")]
+ assert len(finals) == 1 and rows.index(finals[0]) > rows.index(results[0]), rows
+ assert "<tool_call>" not in "".join(r["content"] or "" for r in rows if r["role"] == "assistant"), (
+ "raw tool-call bridge markup was persisted as assistant text")
+ assert "REASONING-ONE" in (finals[0].get("reasoning") or ""), "agent_thought_chunk text was not kept as reasoning"
+
+
+def test_every_request_is_schema_valid_and_selects_the_configured_model(outcomes):
+ """Per process: initialize -> session/new (absolute project cwd) -> set_config_option(model) ->
+ session/prompt on the issued sessionId; zero requests the fake had to reject."""
+ sc = _flow_ok(outcomes)
+ assert sc.fake.invalid() == [], f"requests rejected by the ACP schema: {sc.fake.invalid()}"
+ grouped = _calls(sc.fake)
+ assert len(grouped) == 3, f"one agent process per model call expected, got {len(grouped)}"
+ for pid, recs in grouped.items():
+ methods = [r["msg"]["method"] for r in recs if r["msg"]["method"] not in ("session/cancel",)]
+ assert methods == ["initialize", "session/new", "session/set_config_option", "session/prompt"], (pid, methods)
+ init, new, select, prompt = (r["msg"]["params"] for r in recs[:4])
+ assert init["protocolVersion"] == acp.PROTOCOL_VERSION
+ assert Path(new["cwd"]) == sc.nh.project.resolve(), new
+ assert select["value"] == CONFIGURED_MODEL and select["configId"] == "model", select
+ assert select["sessionId"] == prompt["sessionId"], (select, prompt)
+
+
+def test_agent_permission_is_never_granted_and_fs_reads_stay_in_cwd(outcomes):
+ """The agent's own permission request is refused; fs/read_text_file inside the session cwd returns
+ the file, outside it returns a JSON-RPC error and no content."""
+ sc = _flow_ok(outcomes)
+ outcomes_seen = [r["msg"]["result"]["outcome"] for r in sc.fake.records() if r.get("kind") == "permission_outcome"]
+ assert len(outcomes_seen) == 1, sc.fake.records()
+ assert outcomes_seen[0].get("outcome") != "selected", f"Hermes granted an agent-side permission: {outcomes_seen}"
+ reads = [r for r in sc.fake.records() if r.get("kind") == "fs_read_result"]
+ assert len(reads) == 2 and not any(r["errors"] for r in reads), reads
+ inside, outside = reads[0]["msg"], reads[1]["msg"]
+ assert CANARY in inside["result"]["content"], inside
+ assert "error" in outside and SECRET not in str(outside), f"fs read escaped the session cwd: {outside}"
+
+
+def test_resume_reaches_the_agent_with_persisted_history_in_order(outcomes):
+ """``--resume`` in a new CLI process: a new agent process whose prompt carries turn 1 (question, tool
+ result, answer) in order and then the new question; one session, nothing persisted twice. How the
+ ACP session is opened (seeded ``session/new`` or ``session/load``) is not part of the contract."""
+ sc = _flow_ok(outcomes)
+ assert FINAL_TWO in sc.runs[1].stdout, sc.runs[1].describe()
+ resumed_pids = [pid for pid in _calls(sc.fake) if pid not in sc.extra["turn1_pids"]]
+ assert len(resumed_pids) == 1, "the resumed turn must run in its own agent process"
+ text = acp.prompt_text(sc.fake.main_prompts()[-1])
+ order = [text.find(s) for s in (Q1, CANARY, FINAL_ONE, Q2)]
+ assert -1 not in order and order == sorted(order), f"resumed prompt lost or reordered history: {order}"
+ sessions = session_ids(sc.nh)
+ rows = messages(sc.nh, sessions[-1])
+ assert len(sessions) == 1 and [r["content"] for r in rows if r["role"] == "user"] == [Q1, Q2], rows
+ assert_no_duplicate_assistant_text(rows, FINAL_ONE)
+ assert_no_duplicate_assistant_text(rows, FINAL_TWO)
+
+
+def test_no_agent_process_outlives_the_cli(outcomes):
+ """Every spawned agent is gone once the CLI exits, even one ignoring SIGTERM and stdin EOF."""
+ sc = _flow_ok(outcomes)
+ pids = sc.fake.pids()
+ wedged = {r["pid"] for r in sc.fake.events("signal")}
+ assert len(pids) == 3 and wedged, "vacuity: the scenario must spawn 3 agents that ignored SIGTERM"
+ wait_until(lambda: not [p for p in pids if _alive(p)], 10.0, f"agent processes {pids} to exit")
+
+
+def _transcript(record: dict[str, Any]) -> str:
+ text = acp.prompt_text(record)
+ return text[text.find("Conversation transcript:"):]
+
+
+def test_compaction_in_an_acp_session_keeps_the_next_prompt_valid_and_grounded(outcomes):
+ """Auto compaction mid-turn: the summary is produced through the ACP agent itself, the next
+ main-turn prompt is schema-valid and carries the summary + the user's ask + the protected tail
+ (latest tool result) while the summarized tool output is gone; the turn completes once."""
+ sc = outcomes["compaction"]
+ run = sc.runs[0]
+ assert run.returncode == 0 and FINAL_COMPACT in run.stdout, run.describe()
+ assert sc.fake.invalid() == [], f"requests rejected by the ACP schema: {sc.fake.invalid()}"
+ aux = sc.fake.aux_prompts()
+ assert aux, "compaction never called the summarizer through the ACP provider"
+ assert "file 2 lorem" in acp.prompt_text(aux[0]), "the summarizer did not receive the history to compact"
+ after = [r for r in sc.fake.main_prompts() if r["t"] > aux[0]["t"]]
+ assert after, "no main-turn call followed the compaction"
+ final = _transcript(after[-1])
+ assert SUMMARY in final and COMPACT_ASK in final, "post-compaction prompt lost the summary or the user's ask"
+ assert f"file {COMPACT_FILES} lorem" in final, "post-compaction prompt lost the latest tool result"
+ assert "file 2 lorem" not in final, "summarized tool output is still resent after compaction"
+ rows = messages(sc.nh, latest_session(sc.nh))
+ assert_no_duplicate_assistant_text(rows, FINAL_COMPACT)
+ assert any(FINAL_COMPACT in (r["content"] or "") for r in rows if r["role"] == "assistant"), rows
+
+
+def test_message_chunk_after_prompt_result_reaches_the_user(outcomes):
+ sc = outcomes["late"]
+ run = sc.runs[0]
+ assert run.returncode == 0, run.describe()
+ assert sc.fake.invalid() == [], sc.fake.invalid()
+ rows = messages(sc.nh, latest_session(sc.nh))
+ with known_gate(KNOWN, "late_chunk", raises=KnownSymptom):
+ if LATE_TEXT not in run.stdout:
+ raise KnownSymptom(f"late chunk dropped: {len(sc.fake.main_prompts())} model calls, stdout={run.stdout!r}")
+ assert_no_duplicate_assistant_text(rows, LATE_TEXT)
+ assert len(sc.fake.main_prompts()) == 1, "a delivered late chunk must not trigger an empty-response retry"
diff --git a/tests/e2e/core/providers/test_native_acp_agent_errors.py b/tests/e2e/core/providers/test_native_acp_agent_errors.py
new file mode 100644
index 00000000000..9ba29afc893
--- /dev/null
+++ b/tests/e2e/core/providers/test_native_acp_agent_errors.py
@@ -0,0 +1,171 @@
+"""ACP agent wire conformance, part 2: ACP error responses and agent crashes.
+
+The agent (``tests/fakes/providers/fake_acp_agent.py``, behind the ``fake-acp`` user plugin provider) answers ``session/prompt`` with JSON-RPC errors from
+the ACP / JSON-RPC 2.0 error space or dies mid-stream. Each row drives one real ``hermes chat -q`` and
+asserts the retry semantics the user sees:
+
+* transient failures (``-32603`` internal error, a crash after a partial chunk) are retried with a
+ fresh agent process and the turn then succeeds, with none of the failed attempt's text persisted;
+* ``-32000 Authentication required`` is not retried: surfaced once, one model call;
+* persistent failures (``-32602`` invalid params, repeated crashes) stop after the configured retry
+ budget (``agent.api_max_retries: 2``) and are surfaced ONCE — never a loop, never a duplicate;
+* no agent process survives the CLI in any row.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import re
+import signal
+import subprocess
+import sys
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from tests.e2e.core._pending_fixes import known_gate
+from tests.e2e.core.providers._native_helpers import (
+ ChatResult,
+ KnownSymptom,
+ NativeHome,
+ latest_session,
+ make_home,
+ messages,
+ run_chat,
+ wait_until,
+)
+from tests.fakes.providers import fake_acp_agent as acp
+
+pytest.importorskip("acp.schema", reason="the fake validates against the agent-client-protocol package (acp extra)")
+
+pytestmark = [
+ pytest.mark.platforms("linux"), # POSIX launcher script + /proc pid checks
+ pytest.mark.live_system_guard_bypass,
+]
+
+API_MAX_RETRIES = 2 # _native_helpers.make_home pins agent.api_max_retries
+OK_TEXT = "RECOVERED-ANSWER-OK"
+PARTIAL = "PARTIAL-BEFORE-CRASH "
+CRASH_STDERR = "fatal: agent segfaulted (fake)"
+
+
+# Red on current main for a tracked, open bug: key -> (the bug's own failure-message pattern, reason).
+KNOWN: dict[str, tuple[str, str]] = {
+ "auth_remedy": (r"^remedy 'hermes [^']+' is a dead end for an external_process provider: ",
+ "#121290 an ACP provider's auth failure tells the user to run a hermes command that cannot "
+ "handle it (agent/turn_failure_copy.py oauth_relogin_command names `auth add <slug> --type oauth` "
+ "for a profile with no auth_handler)"),
+}
+
+
+@dataclass(frozen=True)
+class Row:
+ turns: list[list[dict[str, Any]]]
+ succeeds: bool
+ model_calls: int
+ visible: str # text the user must see exactly once (answer or the agent's error message)
+ never_persisted: tuple[str, ...] = ()
+
+
+ROWS: dict[str, Row] = {
+ "internal_error_retried": Row(
+ [[acp.rpc_error(-32603, "Internal error: upstream hiccup")], [acp.message(OK_TEXT)]],
+ succeeds=True, model_calls=2, visible=OK_TEXT, never_persisted=("upstream hiccup",)),
+ "crash_mid_stream_retried": Row(
+ [[acp.message(PARTIAL), acp.crash(3, CRASH_STDERR)], [acp.message(OK_TEXT)]],
+ succeeds=True, model_calls=2, visible=OK_TEXT, never_persisted=(PARTIAL.strip(),)),
+ "auth_required_not_retried": Row(
+ [[acp.rpc_error(-32000, "Authentication required")]] * 3,
+ succeeds=False, model_calls=1, visible="Authentication required"),
+ "invalid_params_bounded": Row(
+ [[acp.rpc_error(-32602, "Invalid params: prompt exceeds agent limit")]] * 4,
+ succeeds=False, model_calls=API_MAX_RETRIES, visible="prompt exceeds agent limit"),
+ "crash_every_time_bounded": Row(
+ [[acp.message(PARTIAL), acp.crash(3, CRASH_STDERR)]] * 4,
+ succeeds=False, model_calls=API_MAX_RETRIES, visible=CRASH_STDERR, never_persisted=(PARTIAL.strip(),)),
+}
+
+
+@dataclass
+class Outcome:
+ nh: NativeHome
+ fake: acp.AcpFake
+ run: ChatResult
+ extra: dict[str, Any] = field(default_factory=dict)
+
+
+def _alive(pid: int) -> bool:
+ try:
+ with open(f"/proc/{pid}/stat", encoding="utf-8") as fh:
+ return fh.read().rsplit(")", 1)[1].split()[0] != "Z"
+ except (FileNotFoundError, ProcessLookupError, IndexError):
+ return False
+
+
+def _drive(root: Path, row: Row) -> Outcome:
+ fake = acp.AcpFake(root / "acp", row.turns)
+ nh = make_home(root, {"provider": acp.PROVIDER, "default": acp.PLACEHOLDER_MODEL}, env_file=fake.env())
+ acp.install_provider_plugin(nh.hermes_home)
+ return Outcome(nh, fake, run_chat(nh, "Answer the question, please."))
+
+
[email protected](scope="module")
+def outcomes(tmp_path_factory: pytest.TempPathFactory):
+ base = tmp_path_factory.mktemp("acp_agent_errors")
+ with ThreadPoolExecutor(max_workers=len(ROWS)) as pool:
+ futures = {name: pool.submit(_drive, base / name, row) for name, row in ROWS.items()}
+ done = {name: fut.result() for name, fut in futures.items()}
+ yield done
+ for out in done.values():
+ for pid in out.fake.pids():
+ if _alive(pid):
+ with contextlib.suppress(ProcessLookupError): # exited between the check and the kill
+ os.kill(pid, signal.SIGKILL)
+
+
[email protected]("name", list(ROWS))
+def test_acp_failure_is_retried_per_semantics_and_surfaced_once(outcomes, name):
+ row, out = ROWS[name], outcomes[name]
+ run, fake = out.run, out.fake
+ assert fake.invalid() == [], f"requests rejected by the ACP schema: {fake.invalid()}"
+ assert len(fake.main_prompts()) == row.model_calls, (
+ f"{name}: {len(fake.main_prompts())} model calls, expected {row.model_calls}\n{run.describe()}")
+ assert (run.returncode == 0) is row.succeeds, run.describe()
+ assert run.stdout.count(row.visible) == 1, f"{row.visible!r} must be shown exactly once\n{run.describe()}"
+ rows = messages(out.nh, latest_session(out.nh))
+ persisted = "\n".join(r["content"] or "" for r in rows if r["role"] == "assistant")
+ for text in row.never_persisted:
+ assert text not in persisted, f"failed-attempt text {text!r} was persisted: {rows}"
+ if row.succeeds:
+ assert persisted.count(OK_TEXT) == 1, rows
+ pids = fake.pids()
+ assert len(pids) == row.model_calls, f"one agent process per model call expected: {pids}"
+ wait_until(lambda: not [p for p in pids if _alive(p)], 10.0, f"agent processes {pids} to exit")
+
+
+REMEDY_RE = re.compile(r"`(hermes [^`]+)`")
+
+
+# What a remedy command says when it cannot do anything for this provider.
+DEAD_END_MARKERS = ("not implemented", "cannot be handled")
+
+
+def test_auth_failure_remedy_is_an_actionable_command(outcomes):
+ """The sign-in remedy printed for an ACP ``Authentication required`` must not be a dead end: any
+ ``hermes ...`` command it names has to be implemented for this provider (here an ``external_process``
+ plugin profile whose agent subprocess owns its own sign-in)."""
+ out = outcomes["auth_required_not_retried"]
+ assert out.run.returncode != 0 and "Authentication required" in out.run.stdout, out.run.describe()
+ for command in REMEDY_RE.findall(out.run.stdout):
+ argv = [sys.executable, "-m", "hermes_cli.main", *command.split()[1:]]
+ proc = subprocess.run(argv, cwd=out.nh.project, env=out.nh.env(), capture_output=True, text=True,
+ timeout=60, stdin=subprocess.DEVNULL, check=False)
+ said = (proc.stdout + proc.stderr).lower()
+ with known_gate(KNOWN, "auth_remedy", raises=KnownSymptom):
+ if proc.returncode != 0 and any(marker in said for marker in DEAD_END_MARKERS):
+ raise KnownSymptom(f"remedy {command!r} is a dead end for an external_process provider: "
+ f"{said.strip()[:300]}")
diff --git a/tests/e2e/core/providers/test_native_acp_agent_streaming.py b/tests/e2e/core/providers/test_native_acp_agent_streaming.py
new file mode 100644
index 00000000000..2e97a4f46d8
--- /dev/null
+++ b/tests/e2e/core/providers/test_native_acp_agent_streaming.py
@@ -0,0 +1,244 @@
+"""ACP agent wire conformance, part 3: a long deep-reasoning turn must stream progress while in flight.
+
+The fake agent (``tests/fakes/providers/fake_acp_agent.py``, behind the ``fake-acp`` user plugin provider) streams an early message chunk and then
+``agent_thought_chunk`` updates for ~4 s before its final chunk and the ``session/prompt`` result, the
+shape of a deep-reasoning tier that thinks for minutes. The contract: chunks the agent has already
+emitted reach the user's surface BEFORE the turn completes, so a long turn never looks hung.
+
+Two real surfaces, each timestamped against the fake's own clock (same host):
+
+* the Desktop/TUI event stream (``python -m tui_gateway.entry`` over stdio): ``reasoning.delta`` /
+ ``message.delta`` events carrying the agent's text (#120550);
+* ACP composition — Hermes itself served as an ACP agent (``hermes acp``) on top of an ``external_process``
+ ACP provider: the outer client must get ``session/update`` chunks before the inner turn ends (#101507).
+
+Both are red on main (the ACP client buffers the whole response, then replays it as a stream), so
+both are ``known_gate`` cells that XFAIL only on :class:`KnownSymptom` for "no progress before the result".
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import queue
+import signal
+import subprocess
+import sys
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable
+
+import pytest
+
+from tests.e2e.core._pending_fixes import known_gate
+from tests.e2e.core.providers._native_helpers import TURN_TIMEOUT, KnownSymptom, NativeHome, make_home
+from tests.fakes.providers import fake_acp_agent as acp
+
+pytest.importorskip("acp.schema", reason="the fake validates against the agent-client-protocol package (acp extra)")
+
+pytestmark = [
+ pytest.mark.platforms("linux"), # POSIX launcher script + /proc pid checks
+ pytest.mark.live_system_guard_bypass,
+]
+
+HEAD, ANSWER, THOUGHT = "DEEP-HEAD ", "DEEP-ANSWER-DONE", "DEEP-THOUGHT"
+THOUGHT_STEPS, STEP_S = 8, 0.5
+MIN_SPAN_S = THOUGHT_STEPS * STEP_S * 0.75 # vacuity: the agent really spent seconds before its result
+MARKERS = (HEAD.strip(), THOUGHT, ANSWER)
+
+
+# Red on current main for a tracked, open bug: key -> (the bug's own failure-message pattern, reason).
+KNOWN: dict[str, tuple[str, str]] = {
+ "tui_stream": (r"^tui_stream: no agent chunk reached the surface during the [\d.]+s turn",
+ "#120550 the ACP client buffers the whole turn: no reasoning/message delta reaches the UI in flight"),
+ "nested_acp": (r"^nested_acp: no agent chunk reached the surface during the [\d.]+s turn",
+ "#101507 hermes acp over an ACP provider forwards inner ACP chunks only after the inner turn ends"),
+}
+
+
+def _deep_turn() -> list[dict[str, Any]]:
+ thoughts = [acp.thought(f"{THOUGHT}-{i} ", delay=STEP_S) for i in range(THOUGHT_STEPS)]
+ return [acp.message(HEAD, delay=0.5), *thoughts, acp.message(ANSWER, delay=STEP_S), acp.result()]
+
+
+@dataclass
+class Observed:
+ fake: acp.AcpFake
+ received: list[tuple[float, dict[str, Any]]] = field(default_factory=list) # (wall clock, message)
+ final_text: str = ""
+ returncode: int | None = None
+ stderr: str = ""
+
+
+def _pump(proc: subprocess.Popen, sink: queue.Queue[tuple[float, dict[str, Any]] | None]) -> None:
+ for line in proc.stdout: # type: ignore[union-attr]
+ try:
+ sink.put((time.time(), json.loads(line)))
+ except json.JSONDecodeError:
+ continue
+ sink.put(None)
+
+
+class _LineRpc:
+ """Newline-delimited JSON-RPC 2.0 over a child's stdio; keeps every inbound message with its arrival time."""
+
+ def __init__(self, proc: subprocess.Popen, obs: Observed, on_request: Callable[[dict[str, Any]], Any]):
+ self.proc, self.obs, self.on_request = proc, obs, on_request
+ self.inbox: queue.Queue[tuple[float, dict[str, Any]] | None] = queue.Queue()
+ self.next_id = 0
+ threading.Thread(target=_pump, args=(proc, self.inbox), daemon=True).start()
+
+ def send(self, msg: dict[str, Any]) -> None:
+ self.proc.stdin.write(json.dumps(msg) + "\n") # type: ignore[union-attr]
+ self.proc.stdin.flush() # type: ignore[union-attr]
+
+ def until(self, pred: Callable[[dict[str, Any]], bool], timeout: float = TURN_TIMEOUT) -> dict[str, Any]:
+ deadline = time.monotonic() + timeout
+ while time.monotonic() < deadline:
+ try:
+ item = self.inbox.get(timeout=0.5)
+ except queue.Empty:
+ continue
+ if item is None:
+ raise AssertionError(f"child closed stdout (rc={self.proc.poll()})")
+ self.obs.received.append(item)
+ msg = item[1]
+ if "method" in msg and "id" in msg:
+ self.send({"jsonrpc": "2.0", "id": msg["id"], **self.on_request(msg)})
+ if pred(msg):
+ return msg
+ raise AssertionError(f"timed out after {timeout}s")
+
+ def call(self, method: str, params: dict[str, Any], timeout: float = TURN_TIMEOUT) -> Any:
+ self.next_id += 1
+ rid = self.next_id
+ self.send({"jsonrpc": "2.0", "id": rid, "method": method, "params": params})
+ msg = self.until(lambda m: m.get("id") == rid and "method" not in m, timeout)
+ assert "error" not in msg, f"{method} failed: {msg['error']}"
+ return msg.get("result")
+
+
+def _refuse(msg: dict[str, Any]) -> dict[str, Any]:
+ return {"error": {"code": -32601, "message": f"test client does not implement {msg['method']}"}}
+
+
+def _run_child(argv: list[str], nh: NativeHome, fake: acp.AcpFake, drive: Callable[[_LineRpc], str]) -> Observed:
+ obs = Observed(fake)
+ stderr_path = nh.root / "child_stderr.log"
+ with open(stderr_path, "w", encoding="utf-8") as err:
+ proc = subprocess.Popen(argv, cwd=nh.project, env=nh.env(), stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+ stderr=err, text=True, bufsize=1)
+ try:
+ obs.final_text = drive(_LineRpc(proc, obs, _refuse))
+ finally:
+ proc.stdin.close() # type: ignore[union-attr]
+ try:
+ proc.wait(timeout=60)
+ except subprocess.TimeoutExpired:
+ proc.kill()
+ proc.wait(timeout=10)
+ obs.returncode, obs.stderr = proc.returncode, stderr_path.read_text(encoding="utf-8")[-3000:]
+ return obs
+
+
+def _home(root: Path) -> tuple[NativeHome, acp.AcpFake]:
+ fake = acp.AcpFake(root / "acp", [_deep_turn()])
+ nh = make_home(root, {"provider": acp.PROVIDER, "default": acp.PLACEHOLDER_MODEL}, env_file=fake.env())
+ acp.install_provider_plugin(nh.hermes_home)
+ return nh, fake
+
+
+def _tui_gateway(root: Path) -> Observed:
+ nh, fake = _home(root)
+
+ def drive(rpc: _LineRpc) -> str:
+ def event(etype: str) -> Callable[[dict[str, Any]], bool]:
+ return lambda m: m.get("method") == "event" and (m.get("params") or {}).get("type") == etype
+
+ rpc.until(event("gateway.ready"), 120)
+ sid = rpc.call("session.create", {})["session_id"]
+ rpc.call("prompt.submit", {"session_id": sid, "text": "Think deeply, then answer."})
+ done = rpc.until(event("message.complete"))
+ return str((done["params"].get("payload") or {}).get("text") or "")
+
+ return _run_child([sys.executable, "-m", "tui_gateway.entry"], nh, fake, drive)
+
+
+def _nested_acp(root: Path) -> Observed:
+ nh, fake = _home(root)
+
+ def drive(rpc: _LineRpc) -> str:
+ rpc.call("initialize", {"protocolVersion": 1, "clientCapabilities": {}, "clientInfo": {"name": "e2e", "version": "1"}}, 120)
+ sid = rpc.call("session/new", {"cwd": str(nh.project), "mcpServers": []}, 120)["sessionId"]
+ result = rpc.call("session/prompt", {"sessionId": sid, "prompt": [{"type": "text", "text": "Think deeply, then answer."}]})
+ assert result.get("stopReason") == "end_turn", result
+ return "".join(_chunk_text(m) for _, m in rpc.obs.received)
+
+ return _run_child([sys.executable, "-m", "hermes_cli.main", "acp"], nh, fake, drive)
+
+
+def _chunk_text(msg: dict[str, Any]) -> str:
+ params = msg.get("params") or {}
+ if msg.get("method") == "session/update": # outer ACP surface
+ content = (params.get("update") or {}).get("content") or {}
+ return str(content.get("text") or "") if isinstance(content, dict) else ""
+ if msg.get("method") == "event" and params.get("type") in ("message.delta", "reasoning.delta"): # TUI surface
+ return str((params.get("payload") or {}).get("text") or "")
+ return ""
+
+
+SURFACES: dict[str, Callable[[Path], Observed]] = {"tui_stream": _tui_gateway, "nested_acp": _nested_acp}
+
+
[email protected](scope="module")
+def observed(tmp_path_factory: pytest.TempPathFactory):
+ base = tmp_path_factory.mktemp("acp_agent_stream")
+ with ThreadPoolExecutor(max_workers=len(SURFACES)) as pool:
+ futures = {name: pool.submit(fn, base / name) for name, fn in SURFACES.items()}
+ done = {name: fut.result() for name, fut in futures.items()}
+ yield done
+ for obs in done.values():
+ for pid in obs.fake.pids():
+ if os.path.exists(f"/proc/{pid}"):
+ try:
+ os.kill(pid, signal.SIGKILL)
+ except ProcessLookupError:
+ pass
+
+
+def _agent_timeline(fake: acp.AcpFake) -> tuple[float, float]:
+ """(first chunk sent, prompt result sent) on the fake agent's clock, for the single main turn."""
+ outs = [r for r in fake.records() if r["dir"] == "out" and r["turn"] == 0]
+ first = min(r["t"] for r in outs if (r["msg"] or {}).get("method") == "session/update")
+ done = min(r["t"] for r in outs if "stopReason" in ((r["msg"] or {}).get("result") or {}))
+ return first, done
+
+
[email protected]("surface", SURFACES)
+def test_long_reasoning_turn_streams_progress_before_it_completes(observed, surface):
+ obs = observed[surface]
+ assert obs.fake.invalid() == [], f"requests rejected by the ACP schema: {obs.fake.invalid()}"
+ assert ANSWER in obs.final_text, f"turn did not complete with the agent's answer: {obs.final_text!r}\n{obs.stderr}"
+ first, done = _agent_timeline(obs.fake)
+ assert done - first >= MIN_SPAN_S, f"vacuity: the agent streamed for only {done - first:.2f}s"
+ seen_at = _first_marker_arrival(obs.received)
+ with known_gate(KNOWN, surface, raises=KnownSymptom):
+ if seen_at is None or seen_at >= done - 0.3:
+ late = [round(t - done, 2) for t, m in obs.received if _chunk_text(m)]
+ raise KnownSymptom(f"{surface}: no agent chunk reached the surface during the {done - first:.1f}s turn; "
+ f"chunk arrivals relative to the result: {late}")
+ assert seen_at >= first, "a chunk cannot arrive before the agent sent it"
+
+
+def _first_marker_arrival(received: list[tuple[float, dict[str, Any]]]) -> float | None:
+ """Arrival time of the delta that first completes one of the agent's markers (surfaces may re-split
+ chunks, so match on the accumulated text, not per delta)."""
+ buffer = ""
+ for t, msg in received:
+ buffer += _chunk_text(msg)
+ if any(k in buffer for k in MARKERS):
+ return t
+ return None
diff --git a/tests/fakes/providers/fake_acp_agent.py b/tests/fakes/providers/fake_acp_agent.py
new file mode 100644
index 00000000000..18ddae7c546
--- /dev/null
+++ b/tests/fakes/providers/fake_acp_agent.py
@@ -0,0 +1,511 @@
+#!/usr/bin/env python3
+"""Fake ACP agent executable for an ``external_process`` model provider (``agent.acp_client.ACPClient``).
+
+An ``external_process`` provider makes Hermes spawn an external agent process per model call and
+speak the Agent Client Protocol to it: JSON-RPC 2.0, one JSON object per line over stdio
+(https://agentclientprotocol.com/protocol/overview). This module is that process. It
+
+* answers ``<cmd> --help`` with a usage text advertising ``--acp`` (Hermes probes it before spawning);
+* validates every client request against the published ACP schema (the ``agent-client-protocol``
+ package's pydantic models, ``acp.schema``) plus the spec rules the models do not encode
+ (initialize-first, absolute ``cwd``, no custom root fields, known ``sessionId``) and REJECTS
+ malformed ones with a JSON-RPC ``-32602 Invalid params`` / ``-32600`` error, as an agent would;
+* builds every message it sends from the same schema models, so a shape drift fails here first;
+* replays a scripted turn per main-turn ``session/prompt`` (thought / message chunks with delays,
+ ``tool_call`` / ``tool_call_update``, ``session/request_permission``, ``fs/read_text_file``,
+ the ``{stopReason}`` result, JSON-RPC errors, a hard crash, chunks AFTER the result);
+* appends every inbound and outbound message, with wall-clock time and pid, to
+ ``<state>/transcript.jsonl`` (shared by every process of one scenario).
+
+Test-side API: :class:`AcpFake` (write the script, build the launcher, read the transcript),
+:func:`install_provider_plugin` (the ``fake-acp`` provider a real user plugin would register in a
+``HERMES_HOME``) and the action builders (:func:`thought`, :func:`message`, ...). Run as a script it
+is the agent itself: ``fake_acp_agent.py --acp --stdio --state <dir>``.
+"""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+import signal
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+from pydantic import ValidationError
+
+PROTOCOL_VERSION = 1
+TOOLS_MARKER = "Available tools"
+AUX_ANSWER = "fake-acp auxiliary answer"
+LAUNCHER_NAME = "fake-acp-agent"
+PROVIDER = "fake-acp"
+PLACEHOLDER_MODEL = "fake-acp"
+COMMAND_ENV_VAR = "FAKE_ACP_COMMAND"
+ARGS_ENV_VAR = "FAKE_ACP_ARGS"
+# A user model-provider plugin, as a third party ships one: an ``external_process`` profile whose
+# ``create_client`` returns a subclass of the public ``ACPClient`` base.
+_PLUGIN_INIT = f'''"""Fake external_process provider: drives an ACP agent CLI through agent.acp_client.ACPClient."""
+
+from agent.acp_client import ACPClient
+from providers import register_provider
+from providers.base import ProviderProfile
+
+
+class FakeACPClient(ACPClient):
+ default_command = "{LAUNCHER_NAME}"
+ default_args = ("--acp", "--stdio")
+ command_env_vars = ("{COMMAND_ENV_VAR}",)
+ args_env_var = "{ARGS_ENV_VAR}"
+ marker_base_url = "acp://{PROVIDER}"
+ placeholder_model = "{PLACEHOLDER_MODEL}"
+ label = "Fake ACP"
+
+
+class FakeACPProfile(ProviderProfile):
+ def create_client(self, **client_kwargs):
+ return FakeACPClient(**client_kwargs)
+
+
+register_provider(FakeACPProfile(
+ name="{PROVIDER}", api_mode="chat_completions", env_vars=(), base_url="acp://{PROVIDER}",
+ auth_type="external_process", process_command="{LAUNCHER_NAME}", process_args=("--acp", "--stdio"),
+ process_command_env_vars=("{COMMAND_ENV_VAR}",), process_args_env_var="{ARGS_ENV_VAR}",
+ static_models=("{PLACEHOLDER_MODEL}",)))
+'''
+_PLUGIN_MANIFEST = f"name: {PROVIDER}\nkind: model-provider\nversion: 0.0.1\ndescription: fake ACP agent provider (tests)\n"
+USAGE = """usage: fake-acp-agent [options]
+
+Options:
+ --acp Run as an Agent Client Protocol server
+ --stdio Use stdio transport (with --acp)
+ --state <dir> (fake) scenario directory holding script.json / transcript.jsonl
+ -h, --help Show help
+"""
+
+
+# ── test-side API ────────────────────────────────────────────────────────────────────────────
+
+
+def thought(text: str, delay: float = 0.0) -> dict[str, Any]:
+ return {"type": "thought", "text": text, "delay": delay}
+
+
+def message(text: str, delay: float = 0.0) -> dict[str, Any]:
+ return {"type": "message", "text": text, "delay": delay}
+
+
+def tool_call(call_id: str, title: str, kind: str = "other", status: str = "pending") -> dict[str, Any]:
+ return {"type": "tool_call", "id": call_id, "title": title, "kind": kind, "status": status}
+
+
+def tool_update(call_id: str, status: str = "completed", text: str = "") -> dict[str, Any]:
+ return {"type": "tool_update", "id": call_id, "status": status, "text": text}
+
+
+def permission(call_id: str, title: str = "run a command") -> dict[str, Any]:
+ return {"type": "permission", "id": call_id, "title": title}
+
+
+def fs_read(path: str) -> dict[str, Any]:
+ return {"type": "fs_read", "path": path}
+
+
+def result(stop_reason: str = "end_turn") -> dict[str, Any]:
+ return {"type": "result", "stopReason": stop_reason}
+
+
+def rpc_error(code: int, msg: str, data: Any = None) -> dict[str, Any]:
+ return {"type": "error", "code": code, "message": msg, "data": data}
+
+
+def crash(exit_code: int = 1, stderr: str = "fatal: agent crashed") -> dict[str, Any]:
+ return {"type": "crash", "code": exit_code, "stderr": stderr}
+
+
+def hermes_tool_call(call_id: str, name: str, args: dict[str, Any]) -> str:
+ """Text a model behind ACP emits to call a Hermes tool (ACP has no OpenAI tools channel)."""
+ body = {"id": call_id, "type": "function", "function": {"name": name, "arguments": json.dumps(args)}}
+ return f"<tool_call>{json.dumps(body)}</tool_call>"
+
+
+def install_provider_plugin(hermes_home: Path) -> Path:
+ """Write the ``fake-acp`` model-provider plugin into ``hermes_home`` the way a user installs one
+ (``$HERMES_HOME/plugins/model-providers/<name>/``); returns the plugin dir."""
+ plugin_dir = Path(hermes_home) / "plugins" / "model-providers" / PROVIDER
+ plugin_dir.mkdir(parents=True, exist_ok=True)
+ (plugin_dir / "__init__.py").write_text(_PLUGIN_INIT, encoding="utf-8")
+ (plugin_dir / "plugin.yaml").write_text(_PLUGIN_MANIFEST, encoding="utf-8")
+ return plugin_dir
+
+
+class AcpFake:
+ """One scenario directory: ``script.json`` in, ``transcript.jsonl`` out, plus a launcher."""
+
+ def __init__(self, state_dir: Path, turns: list[list[dict[str, Any]]], *, models: list[str] | None = None,
+ current_model: str | None = None, ignore_sigterm: bool = False, load_session: bool = True,
+ aux_text: str = AUX_ANSWER):
+ self.state_dir = Path(state_dir)
+ self.state_dir.mkdir(parents=True, exist_ok=True)
+ script = {"turns": turns, "models": models or [], "current_model": current_model,
+ "ignore_sigterm": ignore_sigterm, "load_session": load_session, "aux_text": aux_text}
+ (self.state_dir / "script.json").write_text(json.dumps(script), encoding="utf-8")
+ self.launcher = self.state_dir / LAUNCHER_NAME
+ self.launcher.write_text(
+ f'#!/bin/sh\nexec "{sys.executable}" "{Path(__file__).resolve()}" "$@"\n', encoding="utf-8")
+ self.launcher.chmod(0o755)
+
+ def env(self) -> dict[str, str]:
+ """Profile ``.env`` entries that point the ``fake-acp`` provider's launch spec at this fake."""
+ return {COMMAND_ENV_VAR: str(self.launcher), ARGS_ENV_VAR: f"--acp --stdio --state {self.state_dir}"}
+
+ def records(self) -> list[dict[str, Any]]:
+ path = self.state_dir / "transcript.jsonl"
+ if not path.exists():
+ return []
+ return [json.loads(line) for line in path.read_text(encoding="utf-8").splitlines() if line.strip()]
+
+ def inbound(self, method: str | None = None) -> list[dict[str, Any]]:
+ """Client->agent messages (requests, notifications, responses), optionally one method."""
+ return [r for r in self.records() if r["dir"] == "in" and (method is None or r["msg"].get("method") == method)]
+
+ def main_prompts(self) -> list[dict[str, Any]]:
+ """Main-turn ``session/prompt`` records (those carrying Hermes' tool bridge)."""
+ return [r for r in self.inbound("session/prompt") if r.get("main")]
+
+ def aux_prompts(self) -> list[dict[str, Any]]:
+ """Auxiliary ``session/prompt`` records (no tool bridge: compaction summaries, titles)."""
+ return [r for r in self.inbound("session/prompt") if not r.get("main")]
+
+ def invalid(self) -> list[dict[str, Any]]:
+ return [r for r in self.records() if r["dir"] == "in" and r.get("errors")]
+
+ def pids(self) -> list[int]:
+ return sorted({r["pid"] for r in self.records() if r["dir"] == "spawn"})
+
+ def events(self, kind: str) -> list[dict[str, Any]]:
+ return [r for r in self.records() if r["dir"] == kind]
+
+
+def prompt_text(record: dict[str, Any]) -> str:
+ return "".join(b.get("text", "") for b in record["msg"]["params"].get("prompt", []) if b.get("type") == "text")
+
+
+# ── agent process ────────────────────────────────────────────────────────────────────────────
+
+
+class Agent:
+ """One spawned agent process (one Hermes model call)."""
+
+ def __init__(self, state_dir: Path):
+ from acp import schema # validation/building uses the published ACP models
+
+ self.s = schema
+ self.state_dir = state_dir
+ self.script = json.loads((state_dir / "script.json").read_text(encoding="utf-8"))
+ self.initialized = False
+ self.client_caps: dict[str, Any] = {}
+ self.sessions: set[str] = set()
+ self.turn: int | None = None
+ self.next_id = 1000
+ self.request_schemas = {
+ "initialize": schema.InitializeRequest,
+ "session/new": schema.NewSessionRequest,
+ "session/load": schema.LoadSessionRequest,
+ "session/prompt": schema.PromptRequest,
+ "session/set_model": schema.SetSessionModelRequest,
+ "session/set_config_option": schema.SetSessionConfigOptionSelectRequest,
+ "session/cancel": schema.CancelNotification,
+ }
+ self.handlers = {
+ "initialize": self._initialize, "session/new": self._new_session, "session/load": self._load_session,
+ "session/set_model": self._ack, "session/set_config_option": self._set_config_option,
+ "session/prompt": self._prompt,
+ }
+
+ # transcript + wire ------------------------------------------------------------------------
+
+ def log(self, direction: str, msg: Any = None, **extra: Any) -> None:
+ rec = {"t": time.time(), "pid": os.getpid(), "turn": self.turn, "dir": direction, "msg": msg, **extra}
+ with open(self.state_dir / "transcript.jsonl", "a", encoding="utf-8") as fh:
+ fh.write(json.dumps(rec) + "\n")
+
+ def send(self, msg: dict[str, Any]) -> None:
+ self.log("out", msg)
+ sys.stdout.write(json.dumps(msg) + "\n")
+ sys.stdout.flush()
+
+ def dump(self, model: Any) -> dict[str, Any]:
+ return model.model_dump(by_alias=True, exclude_none=True, mode="json")
+
+ def reply(self, msg_id: Any, result_model: Any) -> None:
+ body = result_model if isinstance(result_model, dict) or result_model is None else self.dump(result_model)
+ self.send({"jsonrpc": "2.0", "id": msg_id, "result": body})
+
+ def error(self, msg_id: Any, code: int, text: str, data: Any = None) -> None:
+ err = {"code": code, "message": text, **({"data": data} if data is not None else {})}
+ self.send({"jsonrpc": "2.0", "id": msg_id, "error": err})
+
+ def update(self, session_id: str, update_model: Any) -> None:
+ note = self.s.SessionNotification(session_id=session_id, update=update_model)
+ self.send({"jsonrpc": "2.0", "method": "session/update", "params": self.dump(note)})
+
+ def read(self) -> dict[str, Any] | None:
+ line = sys.stdin.readline()
+ if not line:
+ return None
+ try:
+ msg = json.loads(line)
+ except json.JSONDecodeError as exc:
+ self.log("in", line.rstrip("\n"), errors=[f"parse error: {exc}"])
+ self.error(None, -32700, "Parse error")
+ return {}
+ return msg
+
+ # validation -------------------------------------------------------------------------------
+
+ def validate(self, msg: dict[str, Any]) -> list[str]:
+ """Spec violations of one client request/notification (empty list = valid)."""
+ errors: list[str] = []
+ if msg.get("jsonrpc") != "2.0":
+ errors.append("jsonrpc must be '2.0'")
+ method = msg.get("method")
+ if "id" in msg and not isinstance(msg["id"], (int, str)):
+ errors.append("id must be a string or integer")
+ model = self.request_schemas.get(method)
+ if model is None:
+ return errors
+ params = msg.get("params")
+ try:
+ parsed = model.model_validate(params)
+ except ValidationError as exc:
+ return errors + [f"schema: {e['loc']} {e['msg']}" for e in exc.errors()]
+ allowed = {f.alias or name for name, f in model.model_fields.items()}
+ errors += [f"custom root field {k!r} (spec: use _meta)" for k in sorted(set(params) - allowed)]
+ if method != "initialize" and not self.initialized:
+ errors.append("request before initialize")
+ if method in ("session/new", "session/load") and not os.path.isabs(parsed.cwd):
+ errors.append("cwd must be an absolute path")
+ sid = getattr(parsed, "session_id", None)
+ if method not in ("session/load",) and sid is not None and sid not in self.sessions:
+ errors.append(f"unknown sessionId {sid!r}")
+ return errors
+
+ # request handlers -------------------------------------------------------------------------
+
+ def _initialize(self, msg_id: Any, params: dict[str, Any]) -> None:
+ self.initialized = True
+ self.client_caps = params.get("clientCapabilities") or {}
+ caps = self.s.AgentCapabilities(load_session=bool(self.script.get("load_session")))
+ self.reply(msg_id, self.s.InitializeResponse(
+ protocol_version=PROTOCOL_VERSION, agent_capabilities=caps, auth_methods=[],
+ agent_info=self.s.Implementation(name="fake-acp-agent", title="Fake ACP Agent", version="1.0.0")))
+
+ def _session_response(self, session_id: str) -> Any:
+ models = self.script.get("models") or []
+ options = None
+ if models:
+ current = self.script.get("current_model") or models[0]
+ options = [self.s.SessionConfigOptionSelect(
+ id="model", name="Model", category="model", type="select", current_value=current,
+ options=[self.s.SessionConfigSelectOption(value=m, name=m) for m in models])]
+ return self.s.NewSessionResponse(session_id=session_id, config_options=options)
+
+ def _new_session(self, msg_id: Any, params: dict[str, Any]) -> None:
+ session_id = f"fake-sess-{os.getpid()}-{len(self.sessions) + 1}"
+ self.sessions.add(session_id)
+ self.reply(msg_id, self._session_response(session_id))
+
+ def _load_session(self, msg_id: Any, params: dict[str, Any]) -> None:
+ self.sessions.add(params["sessionId"])
+ self.reply(msg_id, self.s.LoadSessionResponse())
+
+ def _ack(self, msg_id: Any, params: dict[str, Any]) -> None:
+ self.reply(msg_id, {})
+
+ def _set_config_option(self, msg_id: Any, params: dict[str, Any]) -> None:
+ models = self.script.get("models") or []
+ if params.get("configId") != "model" or params.get("value") not in models:
+ self.error(msg_id, -32602, "Invalid params", {"reason": "unknown config option or value"})
+ return
+ self.script["current_model"] = params["value"]
+ self.reply(msg_id, self.s.SetSessionConfigOptionResponse(config_options=self._session_response("x").config_options))
+
+ def _claim_turn(self) -> int:
+ """Next scripted turn index, shared across every process of the scenario (file lock)."""
+ with open(self.state_dir / "turn.counter", "a+", encoding="utf-8") as fh:
+ fcntl.flock(fh, fcntl.LOCK_EX)
+ fh.seek(0)
+ index = int(fh.read().strip() or 0)
+ fh.seek(0)
+ fh.truncate()
+ fh.write(str(index + 1))
+ return index
+
+ def _prompt(self, msg_id: Any, params: dict[str, Any]) -> None:
+ text = "".join(b.get("text", "") for b in params["prompt"] if b.get("type") == "text")
+ session_id = params["sessionId"]
+ if TOOLS_MARKER not in text: # auxiliary call (title/summary): never consumes a scripted turn
+ self.update(session_id, self._chunk("agent_message_chunk", self.script.get("aux_text") or AUX_ANSWER))
+ self.reply(msg_id, self.s.PromptResponse(stop_reason="end_turn"))
+ return
+ turns = self.script.get("turns") or []
+ index = self._claim_turn()
+ self.turn = index
+ self.log("turn", {"index": index})
+ actions = turns[index] if index < len(turns) else [message("(fake-acp: script exhausted)")]
+ replied = False
+ for action in actions:
+ replied = self._run_action(action, msg_id, session_id) or replied
+ if not replied:
+ self.reply(msg_id, self.s.PromptResponse(stop_reason="end_turn"))
+
+ # scripted actions -------------------------------------------------------------------------
+
+ def _chunk(self, kind: str, text: str) -> Any:
+ cls = {"agent_message_chunk": self.s.AgentMessageChunk, "agent_thought_chunk": self.s.AgentThoughtChunk}[kind]
+ return cls(session_update=kind, content=self.s.TextContentBlock(type="text", text=text))
+
+ def _run_action(self, action: dict[str, Any], msg_id: Any, session_id: str) -> bool:
+ """Perform one scripted action; True when it answered the pending ``session/prompt``."""
+ if action.get("delay"):
+ time.sleep(float(action["delay"])) # health: allow HX013 -- the scripted agent-side delay IS the behaviour under test
+ return bool(self._actions[action["type"]](self, action, msg_id, session_id))
+
+ def _a_thought(self, action, msg_id, session_id):
+ self.update(session_id, self._chunk("agent_thought_chunk", action["text"]))
+
+ def _a_message(self, action, msg_id, session_id):
+ self.update(session_id, self._chunk("agent_message_chunk", action["text"]))
+
+ def _a_tool_call(self, action, msg_id, session_id):
+ self.update(session_id, self.s.ToolCallStart(
+ session_update="tool_call", tool_call_id=action["id"], title=action["title"], kind=action["kind"],
+ status=action["status"]))
+
+ def _a_tool_update(self, action, msg_id, session_id):
+ content = None
+ if action.get("text"):
+ content = [self.s.ContentToolCallContent(
+ type="content", content=self.s.TextContentBlock(type="text", text=action["text"]))]
+ self.update(session_id, self.s.ToolCallProgress(
+ session_update="tool_call_update", tool_call_id=action["id"], status=action["status"], content=content))
+
+ def _a_permission(self, action, msg_id, session_id):
+ req = self.s.RequestPermissionRequest(
+ session_id=session_id,
+ tool_call=self.s.ToolCallUpdate(tool_call_id=action["id"], title=action["title"], kind="execute"),
+ options=[self.s.PermissionOption(option_id="allow-once", name="Allow once", kind="allow_once"),
+ self.s.PermissionOption(option_id="reject-once", name="Reject", kind="reject_once")])
+ response = self._client_request("session/request_permission", self.dump(req))
+ self._check_response(response, self.s.RequestPermissionResponse, "permission_outcome")
+
+ def _a_fs_read(self, action, msg_id, session_id):
+ if not (self.client_caps.get("fs") or {}).get("readTextFile"):
+ self.log("fs_skipped", {"reason": "client did not advertise fs.readTextFile"})
+ return
+ req = self.s.ReadTextFileRequest(session_id=session_id, path=action["path"])
+ response = self._client_request("fs/read_text_file", self.dump(req))
+ self._check_response(response, self.s.ReadTextFileResponse, "fs_read_result")
+
+ def _a_result(self, action, msg_id, session_id):
+ self.reply(msg_id, self.s.PromptResponse(stop_reason=action["stopReason"]))
+ return True
+
+ def _a_error(self, action, msg_id, session_id):
+ self.error(msg_id, int(action["code"]), action["message"], action.get("data"))
+ return True
+
+ def _a_crash(self, action, msg_id, session_id):
+ self.log("crash", {"code": action["code"]})
+ sys.stderr.write(action["stderr"] + "\n")
+ sys.stderr.flush()
+ os._exit(int(action["code"]))
+
+ _actions = {"thought": _a_thought, "message": _a_message, "tool_call": _a_tool_call, "tool_update": _a_tool_update,
+ "permission": _a_permission, "fs_read": _a_fs_read, "result": _a_result, "error": _a_error,
+ "crash": _a_crash}
+
+ def _client_request(self, method: str, params: dict[str, Any]) -> dict[str, Any] | None:
+ self.next_id += 1
+ req_id = self.next_id
+ self.send({"jsonrpc": "2.0", "id": req_id, "method": method, "params": params})
+ while (msg := self.read()) is not None:
+ if msg.get("id") == req_id and "method" not in msg:
+ return msg
+ self.dispatch(msg)
+ return None
+
+ def _check_response(self, response: dict[str, Any] | None, model: Any, kind: str) -> None:
+ errors: list[str] = []
+ if response is None:
+ errors.append("client closed stdin before answering")
+ elif "result" in response:
+ try:
+ model.model_validate(response["result"])
+ except ValidationError as exc:
+ errors += [f"schema: {e['loc']} {e['msg']}" for e in exc.errors()]
+ elif not isinstance((response or {}).get("error"), dict):
+ errors.append("response carries neither result nor error")
+ self.log("in", response, kind=kind, errors=errors)
+
+ # loop -------------------------------------------------------------------------------------
+
+ def dispatch(self, msg: dict[str, Any]) -> None:
+ method = msg.get("method")
+ errors = self.validate(msg) if method else ["unsolicited response"]
+ main = method == "session/prompt" and TOOLS_MARKER in "".join(
+ b.get("text", "") for b in ((msg.get("params") or {}).get("prompt") or []) if isinstance(b, dict))
+ self.log("in", msg, errors=errors, main=main)
+ if "id" not in msg or not method:
+ return # notification (session/cancel) or stray response
+ if errors:
+ code = -32600 if errors == ["request before initialize"] else -32602
+ self.error(msg["id"], code, "Invalid params" if code == -32602 else "Invalid request", {"errors": errors})
+ return
+ handler = self.handlers.get(method)
+ if handler is None:
+ self.error(msg["id"], -32601, f"Method not found: {method}")
+ return
+ handler(msg["id"], msg.get("params") or {})
+
+ def serve(self) -> int:
+ self.log("spawn", {"argv": sys.argv[1:], "cwd": os.getcwd()})
+ while (msg := self.read()) is not None:
+ if msg:
+ self.dispatch(msg)
+ if self.script.get("ignore_sigterm"):
+ # A wedged agent: ignores SIGTERM AND stdin EOF; only SIGKILL ends it.
+ self.log("wedged", {"reason": "stdin closed; ignoring EOF"})
+ while True:
+ time.sleep(3600) # health: allow HX013 -- a wedged agent that only SIGKILL ends
+ self.log("exit", {"reason": "stdin closed"})
+ return 0
+
+
+def _install_signals(agent: Agent) -> None:
+ def _on_term(signum, _frame):
+ if agent.script.get("ignore_sigterm"):
+ agent.log("signal", {"signal": signum, "ignored": True})
+ return
+ agent.log("exit", {"reason": f"signal {signum}"})
+ os._exit(0)
+
+ signal.signal(signal.SIGTERM, _on_term)
+
+
+def main(argv: list[str]) -> int:
+ if not argv or "-h" in argv or "--help" in argv:
+ sys.stdout.write(USAGE)
+ return 0
+ if "--acp" not in argv or "--state" not in argv:
+ sys.stderr.write("error: unknown option; this fake only runs with --acp --stdio --state <dir>\n")
+ return 1
+ agent = Agent(Path(argv[argv.index("--state") + 1]))
+ _install_signals(agent)
+ return agent.serve()
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv[1:]))