Raven-1/tests/test_subagent_host_env.py
Dizhan Xue b2b3d52cc3
fix(acp_client): end an agent with its host on macOS and sweep what a dead host left (#953)
## Summary

On macOS an ACP agent outlives a Raven host that dies without closing it (killed, crashed, OOM-killed). The agent runs in a session of its own, so it gets none of the host's signals, and only `AcpClient.close` ends it. #942 closed this on Linux with a parent-death wrapper and a launch-record sweep. On macOS both were no-ops. This PR brings both layers to macOS.

**1. The agent ends with its host (`raven/acp_client/leftovers.py`, `_DARWIN_BINDING`).** macOS has no `PR_SET_PDEATHSIG`. Instead, the exec wrapper double-forks a small watcher before it execs the agent, then reaps the middle child.
- The watcher is adopted by launchd, so the agent has no child it did not start.
- It stays in the agent's process group, closes every descriptor it inherited (so it holds none of the agent's pipes), and changes to `/`.
- It waits on the host's exit with kqueue (`EVFILT_PROC` / `NOTE_EXIT`), then ends the whole group. An `npx` launcher's grandchild goes with it, which the Linux signal does not reach.
- If the host is already gone when the watch is set, registration fails with `ESRCH`, and that counts as an exit.
- It ends the group only while the agent leads its own group, which every launch does. Any other failure leaves the agent as it would have been.
- `close()` ends the watcher along with the rest of the group.
- Cost: about 4 MiB RSS per launched agent.

**2. The sweep at the next launch runs on macOS.** This is the backstop for when the watcher itself is gone. The decision logic is unchanged; each `/proc` read has a macOS equivalent:
- process start time: `sysctl KERN_PROC_PID` (`kinfo_proc.p_starttime`, in microseconds). It reads any process, including launchd and zombies; `proc_pidinfo` refuses launchd with EPERM.
- group members: `proc_listpids(PROC_PGRP_ONLY)`
- launch mark: `sysctl KERN_PROCARGS2`. EINVAL (gone, zombie, or another user's process) counts as no mark.
- boot identity: `kern.bootsessionuuid` and `kern.boottime`. macOS has no PID namespaces, so the namespace is a fixed value.

macOS hides the environment of its own platform binaries (`/bin/sh`, `/bin/sleep`). Only a group member that is not one can show the mark, such as the agent's node or python process, or the watcher. What cannot be read still leaves a group alone.

**Linux is unchanged.** The Linux wrapper string is byte-identical to main's `_WRAPPER`. `_start_ticks` is renamed to `_start_time`, which now dispatches by platform. `CONTEXT.md` (Leftover agent, Launch mark) is updated to match.

**Windows lifetime handling is provided by #951.** This PR adds the macOS wrapper and sweep; these helpers remain a no-op on Windows.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Before rebasing onto the merged Windows lifetime change, on macOS 26.6.2, arm64, Python 3.12 (project venv):

- `uv run pytest tests/test_acp_leftovers.py tests/test_subagent_host_env.py tests/test_acp_client_teardown.py tests/test_acp_client_launch.py -q -p no:cacheprovider -m "slow or not slow"` -> 117 passed, 9 skipped (Linux-only mechanisms).
- Every other `tests/test_*acp*.py` and `tests/test_*subagent*.py` file, run one file at a time -> all pass except `tests/test_subagent_dag_runner.py`. On this Mac that file hangs at the same two points with this branch and with main's `leftovers.py`:
  - after `TestBackgroundRun::test_a_run_that_ignores_cancellation_fails_named_instead_of_hanging_loop_close` fails;
  - with that test deselected, after `TestBackgroundRun::test_the_failure_path_reaps_a_subagent_child_left_running` (21 passed in both runs).
  It is unrelated to this change; Linux CI covers that file.
- Red/green with a stand-in host (`AcpClient.launch`, then `kill -9` of the host). The stand-in agent ignores SIGTERM, never reads stdin, and starts a child of its own.
  - main: 3 s later the agent is alive with ppid 1, and its child is alive.
  - this branch: 3 s later both are gone.
- Sweep backstop: kill the watcher, then `kill -9` the host. The agent stays (ppid 1). The next host's launch ends the agent and its child.
- `uv run ruff format --check` and `uv run ruff check` on the changed files -> clean. `make check-source-language` and `make check-large-files` -> clean.

New macOS tests cover:
- a killed host ending the agent and what it started;
- the watcher holding none of the agent's pipes and being the only member left after the agent exits;
- the watcher ending nothing when the agent does not lead its group;
- the exec keeping the agent's pid and argv;
- SIGPIPE and SIGXFSZ reaching the agent at their defaults;
- the start-time, member, environment and boot readers (including an empty argv entry and a platform binary).

Most existing Linux tests now run on macOS too.

After rebasing onto the merged Windows lifetime change, on Linux / Python 3.12:

- The only manual conflict resolution is in `CONTEXT.md`: retain both platform descriptions, scope the record sweep to Linux and macOS, and remove the stale sentence that macOS only has explicit teardown.
- The macOS implementation and its tests are byte-identical to the approved revision. The Windows implementation and its tests are byte-identical to main; the shared client and environment-test logic also match main, with only the macOS comments/docstring added.
- `uv run --no-sync pytest tests/test_acp_leftovers.py tests/test_acp_windows.py tests/test_acp_client_launch.py tests/test_acp_client_teardown.py tests/test_subagent_host_env.py tests/test_subagent_acp.py tests/test_living_docs.py -q -x` -> 468 passed, 10 macOS-only tests skipped.
- `uv run --no-sync ty check raven/acp_client` and `uv run --no-sync lint-imports` -> passed; all 10 import contracts kept.
- `uv run --no-sync pre-commit run --from-ref origin/main --to-ref HEAD` -> passed for every applicable hook.
- `make check-large-files check-source-language check-commits` with the existing environment and `UV_NO_SYNC=1` -> passed.

Native macOS and Windows tests were not repeated after this documentation-only conflict resolution. The current-head Windows re-review before the rebase reported 65 passed and 79 platform-specific skips.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

- User-visible: on macOS an ACP agent is now SIGKILLed with its whole process group when its host exits without closing it. On Linux the parent-death signal ends the direct child; the launch-record sweep handles surviving marked descendants. An agent that relied on outliving its host no longer does.
- Each launched agent on macOS carries one extra idle process (about 4 MiB) in its group until the group is closed or the host exits.
- The sweep only acts on groups recorded by a dead host in the same boot, whose leader start time matches and which still hold a member carrying that host's mark. A recycled pid or group number is left alone.
- Rollback: revert this commit. Record files a macOS host left under `acp-launches/` are then inert, because the sweep is a no-op on macOS again.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

#928 (macOS); #951 provides the Windows lifetime handling.
2026-10-15 11:43:29 +08:00

562 lines
24 KiB
Python

"""What the host tells a child about itself survives the login-shell boundary.
Both variables here are captured from raven's own environment and re-applied over
a login shell's, which is the step that drops them if it is missed: the capture
runs `$SHELL -lic` from a minimal base precisely so raven's own variables do not
leak, so anything the host means the child to see has to be overlaid back.
Windows has no login shell, so the same boundary is crossed there by a registry
read; the sections at the end cover that capture and the launch that consumes it.
"""
from __future__ import annotations
import asyncio
import os
import shlex
import sys
from pathlib import Path
from typing import Any, NoReturn
import pytest
import raven.agent.subagent.probe as probe_mod
from raven.acp_client import leftovers, windows
from raven.acp_client.client import AcpClient
from raven.acp_client.protocol import AcpConnectionError
from raven.agent.subagent.backends import env as backend_env
from raven.agent.subagent.probe import probe_all
from raven.agent.subagent.role import SUBAGENT_ENV_VAR, is_subagent_process
from raven.config.schema import ThirdPartyAcpSubagentConfig
def _reporting_child(script: Path, variable: str) -> str:
"""Write a child that reports one variable, and return the command that runs it.
The write is staged and renamed so that the observed path existing means its
content is whole. ``write_text`` creates the file before it writes into it, so a
parent polling on existence can read an empty string from a child that is about
to report correctly -- which is what a loaded CI runner saw as
``assert '' == '/tmp/.../custom-home'`` while the same test passed every local
run. ``os.replace`` is atomic within a filesystem, so there is no window to lose.
The fallback is a word rather than an empty string for the same reason: a
variable that genuinely did not arrive must fail loudly, not look like the race.
"""
script.write_text(
"import os, pathlib, time\n"
"target = pathlib.Path(os.environ['OUTPUT'])\n"
"partial = target.with_name(target.name + '.partial')\n"
f"partial.write_text(os.environ.get({variable!r}, '<missing>'))\n"
"os.replace(partial, target)\n"
"time.sleep(60)\n",
encoding="utf-8",
)
return f"{shlex.quote(sys.executable)} {shlex.quote(str(script))}"
async def test_acp_child_inherits_custom_raven_home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
host_home = tmp_path / "custom-home"
host_home.mkdir()
observed = tmp_path / "observed.txt"
command = _reporting_child(tmp_path / "child.py", "RAVEN_HOME")
monkeypatch.setenv("RAVEN_HOME", str(host_home))
monkeypatch.setattr(backend_env, "login_shell_env", lambda: {"PATH": os.environ["PATH"], "OUTPUT": str(observed)})
client = await AcpClient.launch(name="env-probe", command=command)
try:
for _ in range(100):
if observed.exists():
break
await asyncio.sleep(0.01)
assert observed.read_text(encoding="utf-8") == str(host_home)
finally:
await client.close()
async def test_acp_child_is_told_it_serves_as_a_subagent(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
"""Without this the gate in ``raven.agent.subagent.role`` never fires: a child
``raven acp`` builds a full registry because nothing ever tells it otherwise,
which is how a DAG node's sub-agent came to hold ``spawn`` and delegate the
node's whole task to a background receipt."""
observed = tmp_path / "observed.txt"
command = _reporting_child(tmp_path / "child.py", SUBAGENT_ENV_VAR)
# The capture the launch overlays onto, standing in for the user's login
# shell: it carries no role variable, so a passing read proves the overlay
# rather than a value inherited from the test runner.
monkeypatch.setattr(backend_env, "login_shell_env", lambda: {"PATH": os.environ["PATH"], "OUTPUT": str(observed)})
client = await AcpClient.launch(name="role-probe", command=command)
try:
for _ in range(100):
if observed.exists():
break
await asyncio.sleep(0.01)
arrived = observed.read_text(encoding="utf-8")
finally:
await client.close()
# Judged by the reader rather than against a literal: what the host writes and
# what the child accepts are two halves of one contract, and a test holding
# the written form alone would pass while the child ignored it.
monkeypatch.setenv(SUBAGENT_ENV_VAR, arrived)
assert is_subagent_process(), f"the child was handed {arrived!r}, which it does not read as a sub-agent role"
@pytest.mark.parametrize("legacy", [True, False])
async def test_acp_launch_preserves_stored_windows_path_quotes(tmp_path, monkeypatch, legacy):
from types import SimpleNamespace
from raven.utils import commands
monkeypatch.setattr(commands, "os", SimpleNamespace(name="nt"))
monkeypatch.setattr(backend_env, "login_shell_env", lambda: dict(os.environ))
folder = tmp_path / "agent's saved files"
script = folder / "reply argv.py"
config = folder / "config.json"
quote = shlex.quote if legacy else commands.command_quote
command = f"{quote(sys.executable)} {quote(str(script))} --config {quote(str(config))}"
started: list[tuple[str, ...]] = []
_record_acp_spawn(monkeypatch, started)
monkeypatch.setattr(leftovers, "bind_to_host", _unbound)
with pytest.raises(AcpConnectionError):
await AcpClient.launch(name="stored-command", command=command)
assert started == [(sys.executable, str(script), "--config", str(config))]
# --- Windows: the capture --------------------------------------------------
#
# Windows has no login shell. The capture rebuilds PATH from the two registry
# stores a new terminal's Path is assembled from, and keeps every other value
# raven already has. The fixtures are shaped the way Windows hands them over:
# the stores' REG_EXPAND_SZ values unexpanded, and raven's own environment with
# every name upper-cased, which is how CPython's ``os.environ`` holds it there.
class _FakeKey:
def __init__(self, values: dict[str, str]) -> None:
self.values = values
def __enter__(self) -> "_FakeKey":
return self
def __exit__(self, *_: Any) -> None:
return None
class _FakeWinreg:
"""``winreg`` over two stores a test edits; a store set to ``None`` refuses the read."""
HKEY_LOCAL_MACHINE = 0x80000002
HKEY_CURRENT_USER = 0x80000001
REG_EXPAND_SZ = 2
def __init__(self, machine: dict[str, str] | None, user: dict[str, str] | None) -> None:
self.machine = machine
self.user = user
def OpenKey(self, hive: int, _subkey: str) -> _FakeKey:
store = self.machine if hive == self.HKEY_LOCAL_MACHINE else self.user
if store is None:
raise PermissionError(5, "Access is denied")
return _FakeKey(dict(store))
def QueryInfoKey(self, key: _FakeKey) -> tuple[int, int, int]:
return (0, len(key.values), 0)
def EnumValue(self, key: _FakeKey, index: int) -> tuple[str, str, int]:
name = list(key.values)[index]
return (name, key.values[name], self.REG_EXPAND_SZ)
# What `reg query` shows in each store on a default install.
_STOCK_MACHINE = {
"ComSpec": r"%SystemRoot%\system32\cmd.exe",
"Path": r"%SystemRoot%\system32;%SystemRoot%",
"PSModulePath": r"%ProgramFiles%\WindowsPowerShell\Modules",
"TEMP": r"%SystemRoot%\TEMP",
"TMP": r"%SystemRoot%\TEMP",
"USERNAME": "SYSTEM",
"windir": r"%SystemRoot%",
}
_STOCK_USER = {
"Path": r"%USERPROFILE%\AppData\Local\Microsoft\WindowsApps",
"TEMP": r"%USERPROFILE%\AppData\Local\Temp",
"TMP": r"%USERPROFILE%\AppData\Local\Temp",
}
# Raven's own environment, as the logon built it from those stores.
_LOGON = {
"COMSPEC": r"C:\Windows\system32\cmd.exe",
"PATH": r"C:\Windows\system32;C:\Windows;C:\Users\me\AppData\Local\Microsoft\WindowsApps",
"SYSTEMROOT": r"C:\Windows",
"TEMP": r"C:\Users\me\AppData\Local\Temp",
"TMP": r"C:\Users\me\AppData\Local\Temp",
"USERNAME": "me",
"USERPROFILE": r"C:\Users\me",
"WINDIR": r"C:\Windows",
}
@pytest.fixture
def windows_host(monkeypatch: pytest.MonkeyPatch) -> _FakeWinreg:
"""Raven started on Windows over the stock stores, with no capture taken yet.
The ambient environment goes first: on Linux it can hold one variable under two
spellings (``HTTP_PROXY`` beside ``http_proxy``), which Windows never can, and a
test that read it would measure the machine it ran on.
"""
for name in list(os.environ):
if not name.startswith("PYTEST_"):
monkeypatch.delenv(name)
for name, value in _LOGON.items():
monkeypatch.setenv(name, value)
registry = _FakeWinreg(dict(_STOCK_MACHINE), dict(_STOCK_USER))
monkeypatch.setitem(sys.modules, "winreg", registry)
monkeypatch.setattr(backend_env, "_on_windows", lambda: True)
monkeypatch.setattr(backend_env, "_LOGIN_ENV", None)
monkeypatch.setattr(backend_env, "_LOGIN_ENV_FAILED", False)
return registry
def _no_shell(argv: list[str], **_: Any) -> NoReturn:
raise AssertionError(f"no shell is started on Windows, got {argv}")
def test_windows_capture_takes_path_from_the_stores_and_every_other_value_from_raven(
windows_host: _FakeWinreg,
) -> None:
r"""The reported failure: an installer ran after the gateway started. Only PATH moves.
A terminal opened after ``uv tool install`` builds its Path from the store the
installer wrote, and so does this capture. The stores' other values are what
Windows builds an environment *from* -- ``ComSpec`` and ``TEMP`` unexpanded, the
machine's own ``USERNAME`` -- so copied over raven's they would hand a child a
``ComSpec`` that ``Popen(shell=True)`` cannot start, a ``TEMP`` that is no
directory, and a second spelling of names raven already has.
"""
windows_host.user["Path"] += r";C:\Users\me\.local\bin"
captured = backend_env._capture_windows(consequence="subagents inherit raven's environment")
assert captured is not None
assert captured["PATH"] == (
r"C:\Windows\system32;C:\Windows;C:\Users\me\AppData\Local\Microsoft\WindowsApps;C:\Users\me\.local\bin;"
r"C:\Windows\system32;C:\Windows;C:\Users\me\AppData\Local\Microsoft\WindowsApps"
)
assert {name: value for name, value in captured.items() if name != "PATH"} == {
name: value for name, value in os.environ.items() if name != "PATH"
}
def test_windows_capture_expands_stored_references_with_ravens_own_values_first(
windows_host: _FakeWinreg,
) -> None:
r"""A reference in a stored Path resolves to what a terminal of this logon would get.
Raven's own values win because they are the logon's -- the machine store's
``USERNAME`` is ``SYSTEM`` -- and the child carries them beside this PATH. A
variable an installer added after raven started is only in the stores, where the
user's shadows the machine's and may hold a reference of its own.
"""
windows_host.machine.update({"Path": r"C:\Users\%USERNAME%\bin;%NVM_HOME%", "NVM_HOME": r"C:\nvm\machine"})
windows_host.user.update({"Path": "%NVM_SYMLINK%", "NVM_HOME": r"C:\nvm\user", "NVM_SYMLINK": r"%NVM_HOME%\nodejs"})
captured = backend_env._capture_windows(consequence="subagents inherit raven's environment")
assert captured is not None
assert captured["PATH"].split(";")[:3] == [r"C:\Users\me\bin", r"C:\nvm\user", r"C:\nvm\user\nodejs"]
def test_windows_capture_keeps_the_users_store_when_the_machines_refuses(windows_host: _FakeWinreg) -> None:
"""HKLM can refuse a read; the user's entries must not be lost with it."""
windows_host.machine = None
captured = backend_env._capture_windows(consequence="subagents inherit raven's environment")
assert captured is not None
assert captured["PATH"] == r"C:\Users\me\AppData\Local\Microsoft\WindowsApps;" + _LOGON["PATH"]
def test_windows_capture_reports_failure_when_no_store_reads(windows_host: _FakeWinreg) -> None:
"""Both stores refusing is the one case the caller must fall back on ``os.environ``."""
windows_host.machine = None
windows_host.user = None
assert backend_env._capture_windows(consequence="subagents inherit raven's environment") is None
@pytest.mark.parametrize(
"value,expected",
[
(r"C:\50%;%userprofile%\bin", r"C:\50%;C:\Users\me\bin"),
(r"%UNKNOWN%;%USERPROFILE%\bin", r"%UNKNOWN%;C:\Users\me\bin"),
(r"%EMPTY%;%NESTED%", r";C:\Users\me\bin"),
(r"C:\plain%", r"C:\plain%"),
],
)
def test_windows_expansion_keeps_literal_percent_and_later_references(value, expected):
context = {"USERPROFILE": r"C:\Users\me", "EMPTY": "", "NESTED": r"%USERPROFILE%\bin"}
assert backend_env._expand_windows(value, context) == expected
def test_windows_expansion_resolves_each_name_once():
"""A name is expanded once, however many references reach it.
``A`` refers to ``B`` twice and ``B`` to ``C`` twice, so a walk without the memo
reads ``C`` once per path to it -- eight times here, and exponentially more as
the graph branches deeper -- while the result is the same either way.
"""
class _Counting(dict):
def __init__(self, values):
super().__init__(values)
self.reads = dict.fromkeys(values, 0)
def __getitem__(self, name):
self.reads[name] += 1
return super().__getitem__(name)
context = _Counting({"A": "%B%%B%", "B": "%C%%C%", "C": "c"})
assert backend_env._expand_windows("%A%%A%", context) == "cccccccc"
assert context.reads == {"A": 1, "B": 1, "C": 1}
@pytest.mark.parametrize("references", [{"A": "%A%"}, {"A": "%B%", "B": "%A%"}])
def test_windows_expansion_refuses_cycles(references):
with pytest.raises(ValueError, match="cyclic"):
backend_env._expand_windows("%A%", references)
def test_windows_expansion_bounds_output_before_joining(monkeypatch):
monkeypatch.setattr(backend_env, "_MAX_EXPANDED_ENV_CHARS", 16)
assert backend_env._expand_windows("%B%%B%", {"A": "abcd", "B": "%A%%A%"}) == "abcd" * 4
with pytest.raises(ValueError, match="limit"):
backend_env._expand_windows("%B%%B%x", {"A": "abcd", "B": "%A%%A%"})
def test_windows_expansion_bounds_reference_depth(monkeypatch):
monkeypatch.setattr(backend_env, "_MAX_ENV_REFERENCE_DEPTH", 2)
assert backend_env._expand_windows("%A%", {"A": "%B%", "B": "done"}) == "done"
with pytest.raises(ValueError, match="nested"):
backend_env._expand_windows("%A%", {"A": "%B%", "B": "%C%", "C": "done"})
def test_windows_invalid_expansion_keeps_the_last_capture(windows_host):
before = backend_env.login_shell_env()
windows_host.user.update({"Path": "%LOOP%", "LOOP": "%LOOP%"})
assert backend_env.refresh_login_shell_env() is False
assert backend_env.login_shell_env() == before
def test_windows_registry_non_strings_do_not_become_path_components(windows_host):
windows_host.machine["Path"] = 123
windows_host.user["Path"] = r"C:\valid"
captured = backend_env._capture_windows(consequence="keeping the old capture")
assert captured["PATH"] == r"C:\valid;" + _LOGON["PATH"]
@pytest.mark.parametrize("program", [r"C:\tools\agent.exe", r".\agent.exe", "bin/agent.exe"])
def test_windows_explicit_program_is_not_looked_up_again(monkeypatch, program):
monkeypatch.setattr(backend_env, "_on_windows", lambda: True)
def unexpected_lookup(*args, **kwargs):
raise AssertionError("an explicit program must bypass PATH lookup")
monkeypatch.setattr(backend_env.shutil, "which", unexpected_lookup)
assert backend_env.resolve_program([program, "acp"], {"PATH": "elsewhere"}) == [program, "acp"]
def test_a_refresh_on_windows_reads_the_stores_again(
windows_host: _FakeWinreg, monkeypatch: pytest.MonkeyPatch
) -> None:
"""Check again, Connect and Test each refresh the capture; on Windows that is another registry read.
Routed to the login-shell capture instead, a refresh found no shell, kept the
first capture, and an agent installed after it stayed missing until a restart --
the case the Windows capture exists for. Git for Windows exports ``SHELL`` to
what it starts, and driving that bash would have been worse: an MSYS
environment, a ``:``-joined PATH of ``/c/...`` entries and no ``SystemRoot``,
swapped in for every probe and spawn after it.
"""
monkeypatch.setenv("SHELL", r"C:\Program Files\Git\usr\bin\bash.exe")
monkeypatch.setattr(backend_env.subprocess, "run", _no_shell)
assert r"C:\Users\me\.local\bin" not in backend_env.login_shell_env()["PATH"]
windows_host.user["Path"] += r";C:\Users\me\.local\bin"
assert backend_env.refresh_login_shell_env() is True
assert r"C:\Users\me\.local\bin" in backend_env.login_shell_env()["PATH"]
async def test_windows_probe_finds_agents_on_the_captured_path(
tmp_path: Path, windows_host: _FakeWinreg, monkeypatch: pytest.MonkeyPatch
) -> None:
"""The capture is read by name -- ``probe_all`` asks it for ``PATH`` -- so it is checked through the probe.
One agent sits on the PATH raven started with, one only in a directory the
user's store gained afterwards. Stored under the registry's ``Path`` spelling,
the capture left the probe an empty PATH and both read as missing, the first of
them found before the capture existed.
"""
boot_bin, fresh_bin = tmp_path / "boot-bin", tmp_path / "fresh-bin"
for directory, name in ((boot_bin, "on-boot-agent"), (fresh_bin, "fresh-agent")):
_executable(directory, f"{name}.exe")
monkeypatch.setenv("PATH", str(boot_bin))
windows_host.user["Path"] = str(fresh_bin)
monkeypatch.setattr(os, "pathsep", ";")
monkeypatch.setattr(probe_mod, "acp_snapshot_for", lambda cfg: None)
rows = [
ThirdPartyAcpSubagentConfig(name=name, command=f"{name}.exe --acp") for name in ("on-boot-agent", "fresh-agent")
]
results = await probe_all([(cfg, "config") for cfg in rows])
assert [(r.name, r.status, r.target) for r in results] == [
("on-boot-agent", "attention", str(boot_bin / "on-boot-agent.exe")),
("fresh-agent", "attention", str(fresh_bin / "fresh-agent.exe")),
]
# --- Windows: the launch ---------------------------------------------------
def _unbound(argv: list[str], env: Any, cwd: str | None) -> list[str]:
"""The wrapper that ties an agent to its host on Linux and macOS is no part of a simulated Windows launch."""
return argv
def _recording_refusal(started: list[tuple[str, ...]]) -> Any:
async def refuse(*argv: str, **_: Any) -> NoReturn:
started.append(argv)
raise FileNotFoundError(2, "not started in a test")
return refuse
def _record_acp_spawn(monkeypatch: pytest.MonkeyPatch, started: list[tuple[str, ...]]) -> None:
refuse = _recording_refusal(started)
async def refuse_windows(argv, **kwargs):
await refuse(*argv, **kwargs)
monkeypatch.setattr(asyncio, "create_subprocess_exec", refuse)
monkeypatch.setattr(windows, "launch", refuse_windows)
async def test_on_windows_a_bare_program_starts_from_the_childs_own_path(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""CreateProcess finds a bare name on the gateway's own PATH, never on the env block it is handed.
So an agent installed after raven started, which the refreshed capture and the
probe both find, would still not start. The launch looks the name up on the
child's PATH itself, by CreateProcess's own rule that a name with no extension
means ``.exe``.
"""
fresh_bin = tmp_path / "fresh-bin"
fresh_bin.mkdir()
(fresh_bin / "fresh-agent.exe").write_text("", encoding="utf-8")
(fresh_bin / "fresh-agent.exe").chmod(0o755)
monkeypatch.setattr(backend_env, "_on_windows", lambda: True)
monkeypatch.setattr(backend_env, "login_shell_env", lambda: {"PATH": str(fresh_bin)})
started: list[tuple[str, ...]] = []
_record_acp_spawn(monkeypatch, started)
monkeypatch.setattr(leftovers, "bind_to_host", _unbound)
with pytest.raises(AcpConnectionError):
await AcpClient.launch(name="fresh", command="fresh-agent acp")
assert started == [(str(fresh_bin / "fresh-agent.exe"), "acp")]
async def test_off_windows_the_launch_leaves_the_lookup_to_exec(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""POSIX ``exec`` already resolves a bare name on the PATH of the env it is handed."""
fresh_bin = tmp_path / "fresh-bin"
fresh_bin.mkdir()
(fresh_bin / "fresh-agent.exe").write_text("", encoding="utf-8")
(fresh_bin / "fresh-agent.exe").chmod(0o755)
monkeypatch.setattr(backend_env, "_on_windows", lambda: False)
monkeypatch.setattr(backend_env, "login_shell_env", lambda: {"PATH": str(fresh_bin)})
started: list[tuple[str, ...]] = []
_record_acp_spawn(monkeypatch, started)
with pytest.raises(AcpConnectionError):
await AcpClient.launch(name="fresh", command="fresh-agent acp")
assert started == [("fresh-agent", "acp")]
def test_on_windows_a_shim_on_the_childs_path_is_not_made_the_program(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""A ``.cmd`` shim runs through cmd.exe, whose parser would get the arguments -- a cli agent's prompt among them."""
npm_bin = tmp_path / "npm"
npm_bin.mkdir()
(npm_bin / "codex.cmd").write_text("", encoding="utf-8")
(npm_bin / "codex.cmd").chmod(0o755)
monkeypatch.setattr(backend_env, "_on_windows", lambda: True)
child_env = {"PATH": str(npm_bin)}
assert backend_env.resolve_program(["codex", "exec", "a & b"], child_env) == ["codex", "exec", "a & b"]
assert backend_env.resolve_program(["codex.cmd", "exec"], child_env) == ["codex.cmd", "exec"]
def _executable(directory: Path, name: str) -> Path:
directory.mkdir(exist_ok=True)
program = directory / name
program.write_text("", encoding="utf-8")
program.chmod(0o755)
return program
async def test_on_windows_an_acp_server_that_is_a_batch_file_starts_from_the_childs_path(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""An npm-installed acp server has no ``.exe`` to find, only ``npx.cmd``.
Its argv is configuration -- the turns travel over stdio -- so the acp launch
lets the batch file stand in, found on the child's PATH like any program.
"""
npx = _executable(tmp_path / "npm", "npx.cmd")
monkeypatch.setattr(backend_env, "_on_windows", lambda: True)
monkeypatch.setattr(backend_env, "login_shell_env", lambda: {"PATH": str(npx.parent)})
started: list[tuple[str, ...]] = []
_record_acp_spawn(monkeypatch, started)
monkeypatch.setattr(leftovers, "bind_to_host", _unbound)
with pytest.raises(AcpConnectionError):
await AcpClient.launch(name="npm", command="npx -y @scope/server")
assert started == [(str(npx), "-y", "@scope/server")]
def test_on_windows_the_lookup_takes_path_order_then_exe_first(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
"""The order a terminal finds a name in, so the program that starts is the one the user runs there."""
early_batch = _executable(tmp_path / "early", "agent.cmd")
late_exe = _executable(tmp_path / "late", "agent.exe")
both_exe = _executable(tmp_path / "both", "tool.exe")
_executable(tmp_path / "both", "tool.cmd")
monkeypatch.setattr(backend_env, "_on_windows", lambda: True)
child_env = {"PATH": os.pathsep.join(str(tmp_path / d) for d in ("early", "late", "both"))}
assert backend_env.resolve_program(["agent", "acp"], child_env, batch_files=True) == [str(early_batch), "acp"]
assert backend_env.resolve_program(["agent", "acp"], child_env) == [str(late_exe), "acp"]
assert backend_env.resolve_program(["tool", "acp"], child_env, batch_files=True) == [str(both_exe), "acp"]
def test_on_windows_only_a_bare_startable_name_is_looked_up(monkeypatch: pytest.MonkeyPatch) -> None:
"""A path already names its program, and CreateProcess starts no ``.js``, whatever the PATH holds."""
monkeypatch.setattr(backend_env, "_on_windows", lambda: True)
monkeypatch.setattr(backend_env.shutil, "which", lambda program, path=None: f"/elsewhere/{program}")
child_env = {"PATH": "/elsewhere"}
for argv in ([r"C:\Tools\npx", "-y"], ["tools/npx", "-y"], ["server.js", "--stdio"]):
assert backend_env.resolve_program(argv, child_env, batch_files=True) == argv
assert backend_env.resolve_program(["npx", "-y"], child_env, batch_files=True) == ["/elsewhere/npx.exe", "-y"]
assert backend_env.resolve_program(["npx.cmd", "-y"], child_env, batch_files=True) == ["/elsewhere/npx.cmd", "-y"]