From 073596e996170942105c63dc4580f40ee1b9b3c1 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sat, 7 Nov 2026 23:06:06 -0800 Subject: [PATCH 1/9] feat(computer): the app runtime on Windows: a session of its own and app servers on loopback - session.py picks the OS's way: _session_posix (Linux, macOS, as before) or _session_windows, sharing _reaping. - On Windows an app launches through _job, a standard-library helper that holds a Job object named for its pid: the app and all it starts are in it, it outlives the server, and a server finds it by name to stop it (its windows asked to close, then the job ended) or pause it (each process suspended). Windows are listed with EnumWindows, by program, class and title; the menu launcher is a Start Menu shortcut. - served.py: an app's server answers on its folder's Unix socket, or on Windows on a loopback port it writes with a token, which it checks on every request and WebSocket; the driver's apps and svc, the launcher and the page driver reach it either way, through no proxy the environment names. Co-Authored-By: Claude Opus 5.5 --- .../src/agentenv_protocol/computer/_job.py | 106 +++++++ .../agentenv_protocol/computer/_reaping.py | 47 +++ .../computer/_session_posix.py | 130 +++++++++ .../computer/_session_windows.py | 273 ++++++++++++++++++ .../src/agentenv_protocol/computer/app.py | 4 +- .../agentenv_protocol/computer/app_runtime.py | 7 +- .../src/agentenv_protocol/computer/apps.py | 17 +- .../src/agentenv_protocol/computer/launch.py | 10 +- .../agentenv_protocol/computer/serve_app.py | 19 +- .../src/agentenv_protocol/computer/served.py | 105 +++++++ .../src/agentenv_protocol/computer/session.py | 161 +---------- .../src/agentenv_protocol/computer/svc.py | 23 +- .../tests/test_computer_app_server.py | 10 +- .../tests/test_computer_serve.py | 53 +++- .../tests/test_computer_served.py | 93 ++++++ .../tests/test_computer_session_windows.py | 182 ++++++++++++ .../tests/test_computer_svc_forward.py | 53 ++-- src/agent_env/drivers/envs/page/driver.py | 5 +- 18 files changed, 1076 insertions(+), 222 deletions(-) create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/computer/_job.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/computer/_reaping.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/computer/_session_posix.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/computer/served.py create mode 100644 packages/agentenv-protocol/tests/test_computer_served.py create mode 100644 packages/agentenv-protocol/tests/test_computer_session_windows.py diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/_job.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/_job.py new file mode 100644 index 000000000..33aefe674 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/_job.py @@ -0,0 +1,106 @@ +"""Run a Windows app in a Job object that holds it and everything it starts: ``python -I -S _job.py -- ``. The +Windows ``session`` launches every app through it, by path, so it loads nothing but the standard library. + +It names the job for its own pid (``job_name``), joins the job, then starts the app, so the app and whatever it starts +are in the job; it says ``started`` once the app has, or why it couldn't on stderr, and stays until the job holds no +process but itself, then exits with the app's exit code. It holds the job's only handle, which ends the job when it +closes: the app lives as long as this does, outliving the server that launched it, as a POSIX app's session does, and a +server, restarted or not, finds the job by name to pause or stop it.""" +from __future__ import annotations + +import ctypes +import os +import subprocess +import sys +import time + +#: How often the job is looked at for processes besides this one, once the app has exited. +POLL_S = 0.2 +#: ``JOBOBJECT_INFORMATION_CLASS`` values and the limit and access flags used. +BASIC_ACCOUNTING_INFORMATION, BASIC_PROCESS_ID_LIST, EXTENDED_LIMIT_INFORMATION = 1, 3, 9 +KILL_ON_JOB_CLOSE = 0x2000 +JOB_OBJECT_QUERY, JOB_OBJECT_TERMINATE = 0x0004, 0x0008 +STARTED = b"started" + + +class BasicLimits(ctypes.Structure): + _fields_ = [("PerProcessUserTimeLimit", ctypes.c_int64), ("PerJobUserTimeLimit", ctypes.c_int64), + ("LimitFlags", ctypes.c_uint32), ("MinimumWorkingSetSize", ctypes.c_size_t), + ("MaximumWorkingSetSize", ctypes.c_size_t), ("ActiveProcessLimit", ctypes.c_uint32), + ("Affinity", ctypes.c_size_t), ("PriorityClass", ctypes.c_uint32), ("SchedulingClass", ctypes.c_uint32)] + + +class IoCounters(ctypes.Structure): + _fields_ = [(name, ctypes.c_uint64) for name in ("ReadOperationCount", "WriteOperationCount", "OtherOperationCount", + "ReadTransferCount", "WriteTransferCount", "OtherTransferCount")] + + +class ExtendedLimits(ctypes.Structure): + _fields_ = [("BasicLimitInformation", BasicLimits), ("IoInfo", IoCounters), + ("ProcessMemoryLimit", ctypes.c_size_t), ("JobMemoryLimit", ctypes.c_size_t), + ("PeakProcessMemoryUsed", ctypes.c_size_t), ("PeakJobMemoryUsed", ctypes.c_size_t)] + + +class Accounting(ctypes.Structure): + _fields_ = [("TotalUserTime", ctypes.c_int64), ("TotalKernelTime", ctypes.c_int64), + ("ThisPeriodTotalUserTime", ctypes.c_int64), ("ThisPeriodTotalKernelTime", ctypes.c_int64), + ("TotalPageFaultCount", ctypes.c_uint32), ("TotalProcesses", ctypes.c_uint32), + ("ActiveProcesses", ctypes.c_uint32), ("TotalTerminatedProcesses", ctypes.c_uint32)] + + +def job_name(pid: int) -> str: + """The name of the job the helper running as ``pid`` holds, in the session's own namespace.""" + return f"Local\\agentenv-app-{pid}" + + +def kernel32() -> ctypes.WinDLL: + """``kernel32``, its calls typed as this module and ``session`` use them.""" + dll = ctypes.WinDLL("kernel32", use_last_error=True) + handle, dword, wide = ctypes.c_void_p, ctypes.c_uint32, ctypes.c_wchar_p + dll.CreateJobObjectW.argtypes, dll.CreateJobObjectW.restype = [ctypes.c_void_p, wide], handle + dll.OpenJobObjectW.argtypes, dll.OpenJobObjectW.restype = [dword, ctypes.c_int, wide], handle + dll.SetInformationJobObject.argtypes = [handle, ctypes.c_int, ctypes.c_void_p, dword] + dll.QueryInformationJobObject.argtypes = [handle, ctypes.c_int, ctypes.c_void_p, dword, ctypes.c_void_p] + dll.AssignProcessToJobObject.argtypes = [handle, handle] + dll.TerminateJobObject.argtypes = [handle, ctypes.c_uint] + dll.GetCurrentProcess.restype = handle + dll.CloseHandle.argtypes = [handle] + return dll + + +def active_processes(dll: ctypes.WinDLL, job: int) -> int: + """How many processes the job ``job`` holds now.""" + accounting = Accounting() + if not dll.QueryInformationJobObject(job, BASIC_ACCOUNTING_INFORMATION, ctypes.byref(accounting), + ctypes.sizeof(accounting), None): + raise ctypes.WinError(ctypes.get_last_error()) + return accounting.ActiveProcesses + + +def main(argv: list[str]) -> None: + command = argv[argv.index("--") + 1:] + dll = kernel32() + job = dll.CreateJobObjectW(None, job_name(os.getpid())) + limits = ExtendedLimits() + limits.BasicLimitInformation.LimitFlags = KILL_ON_JOB_CLOSE + if not job or not dll.SetInformationJobObject(job, EXTENDED_LIMIT_INFORMATION, ctypes.byref(limits), + ctypes.sizeof(limits)) \ + or not dll.AssignProcessToJobObject(job, dll.GetCurrentProcess()): + raise ctypes.WinError(ctypes.get_last_error()) + try: + app = subprocess.Popen(command, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, + stderr=subprocess.DEVNULL) + except OSError as e: + sys.stderr.write(f"{type(e).__name__}: {e}\n") + sys.exit(2) + sys.stdout.buffer.write(STARTED + b"\n") + sys.stdout.flush() + code = app.wait() + while active_processes(dll, job) > 1: + time.sleep(POLL_S) + # An exit code is 32 bits, which Python's exit takes as a signed number. + sys.exit(code - (1 << 32) if code >= 1 << 31 else code) + + +if __name__ == "__main__": + main(sys.argv[1:]) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/_reaping.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/_reaping.py new file mode 100644 index 000000000..821ab99c4 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/_reaping.py @@ -0,0 +1,47 @@ +"""The processes a computer app's server launched, each reaped once it exits, so its exit code can be asked for; shared +by every OS's session (``session``).""" +from __future__ import annotations + +import asyncio +from typing import Optional + +#: The processes launched into the session, kept until they exit so each is reaped. +_running: set[asyncio.Task] = set() +#: Each launched process's reaping, by pid, until its exit is asked for: its return code, negative for a signal. +_exits: dict[int, asyncio.Future] = {} +#: How many exits no one has asked for are kept, the latest. +KEPT_EXITS = 16 + + +def reap(process: asyncio.subprocess.Process) -> None: + """Reap ``process`` once it exits, its exit kept until it's asked for or ``KEPT_EXITS`` later ones push it out.""" + reaped = asyncio.ensure_future(process.wait()) + _running.add(reaped) + reaped.add_done_callback(_running.discard) + _exits[process.pid] = reaped + reaped.add_done_callback(lambda _: _forget_old_exits()) + + +def forget(pid: int) -> None: + """No one asks how ``pid`` exited: a process the server stopped.""" + _exits.pop(pid, None) + + +def _forget_old_exits() -> None: + """Drop all but the latest ``KEPT_EXITS`` exits no one has asked for.""" + for pid in [pid for pid, reaped in _exits.items() if reaped.done()][:-KEPT_EXITS]: + del _exits[pid] + + +async def returncode(pid: int, timeout_s: float) -> Optional[int]: + """The return code the process ``launch`` started as ``pid`` exited with, negative for the signal that ended it, + once it's reaped within ``timeout_s``; None for one ``launch`` didn't start or that hasn't exited.""" + reaped = _exits.get(pid) + if reaped is None: + return None + try: + code = await asyncio.wait_for(asyncio.shield(reaped), timeout_s) + except TimeoutError: + return None + _exits.pop(pid, None) + return code diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_posix.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_posix.py new file mode 100644 index 000000000..548d90810 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_posix.py @@ -0,0 +1,130 @@ +"""What a computer app's own server does in the desktop session on Linux and macOS (``session``): wait for the X +session, launch the app into a session of its own and stop or pause it by its process group, add its freedesktop menu +launcher and list the X session's windows.""" +from __future__ import annotations + +import asyncio +import contextlib +import os +import re +import signal +import sys +from pathlib import Path +from typing import Iterator, Optional + +from . import _reaping + +#: How often a starting session is looked for. +POLL_S = 0.2 +#: Moves the fds an app is launched with into place, run on its own so it loads nothing but the standard library. +WITH_FDS = Path(__file__).with_name("_with_fds.py") + + +async def wait_until_up() -> None: + """Until the X display's socket is there.""" + display = os.environ["DISPLAY"].lstrip(":").split(".")[0] + while not Path(f"/tmp/.X11-unix/X{display}").exists(): + await asyncio.sleep(POLL_S) + + +async def launch(argv: list[str], cwd: Path, env: dict[str, str], fds: Optional[dict[int, int]] = None) -> int: + """Start ``argv`` in ``cwd``, in a session of its own so it outlives the server, with the server's environment and + ``env``, and ``fds``, the server's fds it inherits by the number each gets in it; its pid.""" + if fds: + argv = [sys.executable, "-I", "-S", str(WITH_FDS), *(f"{source}={target}" for target, source in fds.items()), + "--", *argv] + process = await asyncio.create_subprocess_exec( + *argv, cwd=cwd, env={**os.environ, **env}, start_new_session=True, stdin=asyncio.subprocess.DEVNULL, + stdout=asyncio.subprocess.DEVNULL, stderr=asyncio.subprocess.DEVNULL, pass_fds=tuple((fds or {}).values())) + _reaping.reap(process) + return process.pid + + +async def stop(pid: int, timeout_s: float) -> None: + """End the session ``launch`` started as ``pid``, every process in it: asked to exit, a paused one continued so it + can, then killed after ``timeout_s``. No one asks how it exited once it's stopped.""" + _reaping.forget(pid) + try: + os.killpg(pid, signal.SIGTERM) + except ProcessLookupError: + return + with contextlib.suppress(ProcessLookupError, PermissionError): # macOS refuses a group of zombies alone + os.killpg(pid, signal.SIGCONT) + try: + await asyncio.wait_for(_exited(pid), timeout_s) + except TimeoutError: + with contextlib.suppress(ProcessLookupError): + os.killpg(pid, signal.SIGKILL) + + +@contextlib.contextmanager +def paused(pid: int) -> Iterator[None]: + """Every process of the session ``launch`` started as ``pid`` stopped while the block runs, and continued after.""" + try: + os.killpg(pid, signal.SIGSTOP) + except (ProcessLookupError, PermissionError): + yield + return + try: + yield + finally: + with contextlib.suppress(ProcessLookupError, PermissionError): + os.killpg(pid, signal.SIGCONT) + + +def alive(pid: int) -> bool: + """Whether a process of the session ``launch`` started as ``pid`` is running, its first or one it started.""" + try: + os.killpg(pid, 0) + except ProcessLookupError: + return False + except PermissionError: + return True + return True + + +async def _exited(pid: int) -> None: + while alive(pid): + await asyncio.sleep(POLL_S) + + +def add_launcher(name: str, folder: Path) -> Path: + """The desktop entry that launches the app ``name`` in ``folder`` through its own server, written where the + session user's menu finds it.""" + entry = Path.home() / ".local/share/applications" / f"agentenv-app-{folder.name}.desktop" + entry.parent.mkdir(parents=True, exist_ok=True) + entry.write_text(f"[Desktop Entry]\nType=Application\nName={name}\n" + f"Exec={folder}/venv/bin/python -m agentenv_protocol.computer.launch {folder}\nTerminal=false\n") + return entry + + +async def windows() -> list[dict[str, str]]: + """The window manager's top-level windows, each as its WM_CLASS ``instance`` and ``class`` and its ``title``, read + with ``xprop``: ``_NET_WM_NAME``, or ``WM_NAME`` for a window that sets only that; a window that closes while it's + read is left out.""" + listed = await _xprop("-root", "_NET_CLIENT_LIST") + found = [] + for window in re.findall(r"0x[0-9a-f]+", listed.partition("#")[2]): + props = await _xprop("-id", window, "WM_CLASS", "_NET_WM_NAME", "WM_NAME") + names = dict(re.findall(r'^(WM_CLASS|_NET_WM_NAME|WM_NAME)[^=]*= (.*)$', props, re.MULTILINE)) + parts = _strings(names.get("WM_CLASS", "")) + if len(parts) == 2: + title = _strings(names.get("_NET_WM_NAME") or names.get("WM_NAME", "")) + found.append({"instance": parts[0], "class": parts[1], "title": title[0] if title else ""}) + return found + + +def _strings(value: str) -> list[str]: + """The quoted strings of an ``xprop`` value, as the window holds them, without the escapes ``xprop`` prints.""" + return [re.sub(r"\\(.)", r"\1", text) for text in re.findall(r'"((?:[^"\\]|\\.)*)"', value)] + + +async def _xprop(*args: str) -> str: + process = await asyncio.create_subprocess_exec("xprop", *args, stdout=asyncio.subprocess.PIPE, + stderr=asyncio.subprocess.DEVNULL) + try: + out, _ = await process.communicate() + except asyncio.CancelledError: + process.kill() + raise + return out.decode(errors="replace") if process.returncode == 0 else "" diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py new file mode 100644 index 000000000..c3892a553 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py @@ -0,0 +1,273 @@ +"""What a computer app's own server does in the desktop session on Windows (``session``). agentenv-session starts the +server in the session user's sign-in, so the session is up and its desktop is the user's. An app launches through +``_job`` into a Job object that holds it and everything it starts, found by the helper's pid: stopping it asks its +windows to close, then ends the job after the timeout, and pausing it suspends each of its processes. Its menu launcher +is a Start Menu shortcut, and the session's windows are listed with ``EnumWindows``, each by its class, its program's +file name and its title.""" +from __future__ import annotations + +import asyncio +import contextlib +import ctypes +import os +import re +import subprocess +import sys +import time +from dataclasses import dataclass +from pathlib import Path +from typing import Iterator, Optional + +from . import _job, _reaping + +#: The helper that runs an app in its job, run on its own so it loads nothing but the standard library. +JOB = Path(__file__).with_name("_job.py") +#: How long the helper may take to start the app and say so. +START_TIMEOUT_S = 30.0 +#: How often a stopping app is looked at for having ended. +POLL_S = 0.2 +WM_CLOSE = 0x0010 +#: A Start Menu shortcut, from its path, program, arguments and folder in the environment, as PowerShell writes one. +SHORTCUT = ("$s = (New-Object -ComObject WScript.Shell).CreateShortcut($env:AGENTENV_SHORTCUT); " + "$s.TargetPath = $env:AGENTENV_TARGET; $s.Arguments = $env:AGENTENV_ARGUMENTS; " + "$s.WorkingDirectory = $env:AGENTENV_FOLDER; $s.Save()") +#: What a file name can't hold on Windows. +UNSAFE = re.compile(r'[\\/:*?"<>|\x00-\x1f]') + + +async def wait_until_up() -> None: + """At once: the server runs in the session user's sign-in, so the session is up.""" + + +async def launch(argv: list[str], cwd: Path, env: dict[str, str], fds: Optional[dict[int, int]] = None) -> int: + """Start ``argv`` in ``cwd`` in a job of its own (``_job``), which outlives the server, with the server's + environment and ``env``; the helper's pid, by which the job is found. A Windows app can't be handed fds.""" + if fds: + raise NotImplementedError("a Windows app can't be handed the server's fds") + process = await asyncio.create_subprocess_exec( + sys.executable, "-I", "-S", str(JOB), "--", *argv, cwd=cwd, env={**os.environ, **env}, + stdin=asyncio.subprocess.DEVNULL, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE, + creationflags=subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.CREATE_NO_WINDOW) + try: + said = await asyncio.wait_for(process.stdout.readline(), START_TIMEOUT_S) + except BaseException: + # Its job's only handle closes with it, which ends whatever it started. + with contextlib.suppress(ProcessLookupError): + process.kill() + _reaping.reap(process) + raise + if said.strip() != _job.STARTED: + why = ((await process.stderr.read()).decode(errors="replace").strip().splitlines() or [""])[-1] + await process.wait() + raise OSError(f"couldn't start {argv[0]}: {why or f'its job helper exited {process.returncode}'}") + _reaping.reap(process) + return process.pid + + +async def stop(pid: int, timeout_s: float) -> None: + """End the job the helper ``pid`` holds, every process in it: its windows asked to close, then the job ended after + ``timeout_s``, or at once when it has no window to close. No one asks how it exited once it's stopped.""" + _reaping.forget(pid) + job = _win32.open_job(pid) + if job is None: + return + try: + windows = [window for window in _win32.windows() if window.pid in _app_pids(job, pid)] + for window in windows: + _win32.post_close(window.handle) + deadline = time.monotonic() + (timeout_s if windows else 0) + while _app_pids(job, pid) and time.monotonic() < deadline: + await asyncio.sleep(POLL_S) + if _app_pids(job, pid): + _win32.terminate_job(job) + finally: + _win32.close(job) + + +@contextlib.contextmanager +def paused(pid: int) -> Iterator[None]: + """Every process of the job the helper ``pid`` holds suspended while the block runs, and resumed after.""" + job = _win32.open_job(pid) + if job is None: + yield + return + suspended = [] + try: + for app_pid in _app_pids(job, pid): + if _win32.suspend(app_pid): + suspended.append(app_pid) + yield + finally: + for app_pid in suspended: + _win32.resume(app_pid) + _win32.close(job) + + +def alive(pid: int) -> bool: + """Whether the job the helper ``pid`` holds is there, which it is while any process of the app runs.""" + job = _win32.open_job(pid) + if job is None: + return False + _win32.close(job) + return True + + +def add_launcher(name: str, folder: Path) -> Path: + """The Start Menu shortcut, named ``name``, that launches the app in ``folder`` through its own server, written + where the session user's Start Menu finds it.""" + entry = Path(os.environ["APPDATA"]) / "Microsoft/Windows/Start Menu/Programs" / f"{UNSAFE.sub('_', name)}.lnk" + entry.parent.mkdir(parents=True, exist_ok=True) + subprocess.run(["powershell", "-NoProfile", "-NonInteractive", "-Command", SHORTCUT], check=True, + capture_output=True, timeout=60, creationflags=subprocess.CREATE_NO_WINDOW, + env={**os.environ, "AGENTENV_SHORTCUT": str(entry), "AGENTENV_FOLDER": str(folder), + "AGENTENV_TARGET": str(folder / "venv" / "Scripts" / "pythonw.exe"), + "AGENTENV_ARGUMENTS": f'-m agentenv_protocol.computer.launch "{folder}"'}) + return entry + + +async def windows() -> list[dict[str, str]]: + """The session's shown top-level windows, each as its program's file name, lowercased, its ``instance``, its window + class its ``class``, and its ``title``; a window that's hidden or cloaked, as a suspended Store app's frame is, is + left out.""" + return await asyncio.to_thread(lambda: [ + {"instance": window.program, "class": window.class_name, "title": window.title} + for window in _win32.windows() if window.shown]) + + +def _app_pids(job: int, helper: int) -> list[int]: + """The processes of the job ``job`` but the helper ``helper`` that holds it.""" + return [pid for pid in _win32.job_pids(job) if pid != helper] + + +@dataclass(frozen=True) +class Window: + """A top-level window as ``EnumWindows`` lists it: its ``handle``, the ``pid`` of its process, that process's + ``program`` file name, lowercased, its ``class_name`` and ``title``, and whether it's ``shown``.""" + + handle: int + pid: int + program: str + class_name: str + title: str + shown: bool + + +class _Win32: + """The Win32 calls this module makes, each a method, so its logic is tested apart from them.""" + + PROCESS_QUERY_LIMITED_INFORMATION, PROCESS_SUSPEND_RESUME = 0x1000, 0x0800 + DWMWA_CLOAKED = 14 + #: How many process ids a job's list is read with room for, before it's read again with room for all. + PIDS = 64 + + def __init__(self) -> None: + self._dlls: Optional[tuple] = None + + def open_job(self, helper: int) -> Optional[int]: + """A handle to the job the helper ``helper`` holds, to query and end it, or None when it isn't there.""" + return self._api()[0].OpenJobObjectW(_job.JOB_OBJECT_QUERY | _job.JOB_OBJECT_TERMINATE, False, + _job.job_name(helper)) or None + + def job_pids(self, job: int) -> list[int]: + kernel32 = self._api()[0] + room = self.PIDS + while True: + listed = _pid_list(room)() + if kernel32.QueryInformationJobObject(job, _job.BASIC_PROCESS_ID_LIST, ctypes.byref(listed), + ctypes.sizeof(listed), None): + return list(listed.ProcessIdList[:listed.NumberOfProcessIdsInList]) + if listed.NumberOfAssignedProcesses <= room: + raise ctypes.WinError(ctypes.get_last_error()) + room = listed.NumberOfAssignedProcesses + + def terminate_job(self, job: int) -> None: + if not self._api()[0].TerminateJobObject(job, 1): + raise ctypes.WinError(ctypes.get_last_error()) + + def close(self, handle: int) -> None: + self._api()[0].CloseHandle(handle) + + def suspend(self, pid: int) -> bool: + """Whether the process ``pid`` was there to suspend, and was.""" + return bool(self._on_process(pid, self.PROCESS_SUSPEND_RESUME, + lambda process: self._api()[3].NtSuspendProcess(process) == 0)) + + def resume(self, pid: int) -> None: + self._on_process(pid, self.PROCESS_SUSPEND_RESUME, lambda process: self._api()[3].NtResumeProcess(process)) + + def post_close(self, window: int) -> None: + self._api()[1].PostMessageW(window, WM_CLOSE, 0, 0) + + def windows(self) -> list[Window]: + _, user32, dwmapi, _ = self._api() + handles: list[int] = [] + listing = ctypes.WINFUNCTYPE(ctypes.c_int, ctypes.c_void_p, ctypes.c_void_p)( + lambda window, _: handles.append(window) or True) + user32.EnumWindows(listing, None) + found = [] + for handle in handles: + pid, cloaked = ctypes.c_uint32(), ctypes.c_uint32() + user32.GetWindowThreadProcessId(handle, ctypes.byref(pid)) + class_name, title = ctypes.create_unicode_buffer(256), ctypes.create_unicode_buffer( + user32.GetWindowTextLengthW(handle) + 1) + user32.GetClassNameW(handle, class_name, len(class_name)) + user32.GetWindowTextW(handle, title, len(title)) + dwmapi.DwmGetWindowAttribute(handle, self.DWMWA_CLOAKED, ctypes.byref(cloaked), ctypes.sizeof(cloaked)) + found.append(Window(handle, pid.value, self._program(pid.value), class_name.value, title.value, + bool(user32.IsWindowVisible(handle)) and not cloaked.value)) + return found + + def _program(self, pid: int) -> str: + """The file name of the program running as ``pid``, lowercased, or empty where it can't be read.""" + def read(process: int) -> str: + path, size = ctypes.create_unicode_buffer(32768), ctypes.c_uint32(32768) + if not self._api()[0].QueryFullProcessImageNameW(process, 0, path, ctypes.byref(size)): + return "" + return path.value.rpartition("\\")[2].lower() + return self._on_process(pid, self.PROCESS_QUERY_LIMITED_INFORMATION, read) or "" + + def _on_process(self, pid: int, access: int, act): + """``act`` on a handle to the process ``pid`` opened for ``access``, closed after; None where it can't be + opened, as for a process that has exited.""" + kernel32 = self._api()[0] + process = kernel32.OpenProcess(access, False, pid) + if not process: + return None + try: + return act(process) + finally: + kernel32.CloseHandle(process) + + def _api(self) -> tuple: + """``kernel32``, ``user32``, ``dwmapi`` and ``ntdll``, bound on first use, so this module imports anywhere.""" + if self._dlls is None: + kernel32 = _job.kernel32() + kernel32.OpenProcess.argtypes, kernel32.OpenProcess.restype = [ctypes.c_uint32, ctypes.c_int, + ctypes.c_uint32], ctypes.c_void_p + kernel32.QueryFullProcessImageNameW.argtypes = [ctypes.c_void_p, ctypes.c_uint32, ctypes.c_wchar_p, + ctypes.c_void_p] + user32 = ctypes.WinDLL("user32", use_last_error=True) + user32.EnumWindows.argtypes = [ctypes.c_void_p, ctypes.c_void_p] + user32.GetWindowThreadProcessId.argtypes = [ctypes.c_void_p, ctypes.c_void_p] + user32.GetWindowTextLengthW.argtypes = user32.IsWindowVisible.argtypes = [ctypes.c_void_p] + user32.GetClassNameW.argtypes = user32.GetWindowTextW.argtypes = [ctypes.c_void_p, ctypes.c_wchar_p, + ctypes.c_int] + user32.PostMessageW.argtypes = [ctypes.c_void_p, ctypes.c_uint, ctypes.c_size_t, ctypes.c_ssize_t] + dwmapi = ctypes.WinDLL("dwmapi") + dwmapi.DwmGetWindowAttribute.argtypes = [ctypes.c_void_p, ctypes.c_uint32, ctypes.c_void_p, + ctypes.c_uint32] + ntdll = ctypes.WinDLL("ntdll") + ntdll.NtSuspendProcess.argtypes = ntdll.NtResumeProcess.argtypes = [ctypes.c_void_p] + self._dlls = (kernel32, user32, dwmapi, ntdll) + return self._dlls + + +def _pid_list(room: int) -> type[ctypes.Structure]: + """``JOBOBJECT_BASIC_PROCESS_ID_LIST`` with room for ``room`` process ids.""" + class Listed(ctypes.Structure): + _fields_ = [("NumberOfAssignedProcesses", ctypes.c_uint32), ("NumberOfProcessIdsInList", ctypes.c_uint32), + ("ProcessIdList", ctypes.c_size_t * room)] + return Listed + + +_win32 = _Win32() diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/app.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/app.py index 02ca54702..8d76776e1 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/app.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/app.py @@ -30,6 +30,7 @@ from .app_runtime import AppRuntime from .errors import InvalidArgument from .platform import detect +from .served import SOCKET as SOCKET #: The environment variable a computer delivers its apps' settings in: JSON of each app's values by its name. APP_SETTINGS_ENV = "AGENTENV_APP_SETTINGS" @@ -41,11 +42,10 @@ WINDOW_KEYS = frozenset({"class", "instance", "title"}) #: The framework extension an app's own server serves: its launch as params, and its ``launch`` and ``ready`` methods. COMPUTER_APP = "urn:agentenv:computer-app/v1" -#: Where an app's own server listens, in the app's folder, and where it says why it last failed to start. -SOCKET = Path(".agentenv/server.sock") #: Written in an app's folder by its computer's driver once an agent acts there, by a tool call or on a route the app #: opens to agents: a fresh computer starts without it, and an app that resets removes its own. AGENT_ACTED = Path(".agentenv/agent-acted") +#: Where an app's server says why it last failed to start, in the app's folder. FAILURE = Path(".agentenv/server.failure") #: The values of an app's build settings its env fixes in its computer's image, in the app's folder. BUILD_SETTINGS = Path(".agentenv/build_settings.json") diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/app_runtime.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/app_runtime.py index bf125781c..ca90be65b 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/app_runtime.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/app_runtime.py @@ -11,6 +11,7 @@ import shlex import signal import sys +import tempfile import time from collections.abc import Awaitable, Callable from datetime import datetime, timezone @@ -25,8 +26,10 @@ from .app import Launch #: Where an app's server marks that it launched the app since the computer booted, at boot or on demand: a folder a -#: boot clears, under /tmp on macOS, which has no /run and lets the session user write nothing at its root. -LAUNCHED = Path("/tmp/agentenv/apps" if sys.platform == "darwin" else "/run/agentenv/apps") +#: boot clears, under /tmp on macOS, which has no /run and lets the session user write nothing at its root, and on +#: Windows in the session user's temp folder, whose disk each boot starts afresh. +LAUNCHED = (Path("/tmp/agentenv/apps") if sys.platform == "darwin" else + Path(tempfile.gettempdir()) / "agentenv" / "apps" if sys.platform == "win32" else Path("/run/agentenv/apps")) #: How long one readiness check may take; an app's checks run at once. CHECK_TIMEOUT_S = 10.0 #: Where an app's server keeps the pid of the app it launched last, in the app's folder, so a server that restarts can diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/apps.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/apps.py index 696f23a29..657e8400c 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/apps.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/apps.py @@ -1,5 +1,5 @@ """The apps composed onto a computer, as its driver finds them, whether each is ready, and how the driver fronts them. -Each app's own server answers on its folder's socket (``serve_app``): its card says how the app launches and which +Each app's own server answers where its folder says (``served``): its card says how the app launches and which paths it owns, and its ``computer-app/v1`` ``ready`` whether it's ready. Every app's server must answer before the computer is ready; an app that starts with the computer must also be ready, and a ``demand`` app, or a boot app while the computer holds its launch (``boot_launch_held``), is checked once something launches it. The driver lists @@ -10,6 +10,7 @@ import asyncio import copy import json +import sys from datetime import datetime, timezone from pathlib import Path from typing import Optional @@ -18,12 +19,13 @@ from .. import client from ..types import RPC_PATH, WELL_KNOWN_PATH, EnvironmentCard -from .app import AGENT_ACTED, COMPUTER_APP, FAILURE, SOCKET +from .app import AGENT_ACTED, COMPUTER_APP, FAILURE from .app_runtime import CHECK_TIMEOUT_S, LAUNCHES, AppReadiness, boot_launch_held from .operations import ReadyCheck +from .served import served #: Where a composed computer installs its apps, a folder each. -APPS = Path("/opt/agentenv/apps") +APPS = Path("C:/agentenv/apps" if sys.platform == "win32" else "/opt/agentenv/apps") #: How long an app's server may take to answer, its checks run at once, before it counts as not answering. ANSWER_TIMEOUT_S = CHECK_TIMEOUT_S + 5 @@ -38,7 +40,7 @@ async def check(folder: Path) -> ReadyCheck: its card once the server answers.""" name = folder.name try: - async with _client(folder / SOCKET) as http: + async with served(folder).client(ANSWER_TIMEOUT_S) as http: card = (await http.get(WELL_KNOWN_PATH)).raise_for_status().json() name = card["name"] launch = client.extension_params(card, COMPUTER_APP).get("launch") @@ -109,7 +111,7 @@ def endpoint(card: dict, method: str) -> str: async def served_card(folder: Path) -> Optional[dict]: """The card the app in ``folder`` serves, or None while its server isn't answering.""" try: - async with _client(folder / SOCKET) as http: + async with served(folder).client(ANSWER_TIMEOUT_S) as http: return (await http.get(WELL_KNOWN_PATH)).raise_for_status().json() except (httpx.HTTPError, OSError, ValueError): return None @@ -149,11 +151,6 @@ def _unanswered(folder: Path) -> str: return "its server isn't answering yet" -def _client(socket: Path) -> httpx.AsyncClient: - return httpx.AsyncClient(transport=httpx.AsyncHTTPTransport(uds=str(socket)), base_url="http://app", - timeout=ANSWER_TIMEOUT_S) - - def note_agent_acted(folders: list[Path]) -> None: """Note in each app's folder that an agent has acted in the computer, where it isn't noted yet.""" for folder in folders: diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/launch.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/launch.py index 0232cf6c7..cb391e831 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/launch.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/launch.py @@ -1,22 +1,20 @@ """Launch a computer app through its own server, as its menu launcher does: -``python -m agentenv_protocol.computer.launch `` asks the server on the folder's socket to launch it, so -the server starts every copy of the app.""" +``python -m agentenv_protocol.computer.launch `` asks the folder's server (``served``) to launch it, so the +server starts every copy of the app.""" from __future__ import annotations import sys from pathlib import Path -import httpx - from ..types import WELL_KNOWN_PATH -from .app import SOCKET from .apps import endpoint +from .served import served def main(argv: list[str]) -> None: if len(argv) != 1: raise SystemExit("usage: python -m agentenv_protocol.computer.launch ") - with httpx.Client(transport=httpx.HTTPTransport(uds=str(Path(argv[0]) / SOCKET)), base_url="http://app") as http: + with served(Path(argv[0])).sync_client(timeout=5.0) as http: card = http.get(WELL_KNOWN_PATH).raise_for_status().json() http.post(endpoint(card, "launch"), json={}).raise_for_status() diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/serve_app.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/serve_app.py index c3b2f52ab..02d6a900d 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/serve_app.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/serve_app.py @@ -1,7 +1,8 @@ """Serve a computer app's class from its file, as its computer's program starts it: ``python -m agentenv_protocol.computer.serve_app :``, run in the app's folder, serves the class's card and -``computer-app/v1`` on the Unix socket ``.agentenv/server.sock`` there, which only the computer reaches, so it takes no -control token (``CONTROL_TOKEN_ENV``): the driver checks it in front of the app. Before it serves, it keeps a copy of +``computer-app/v1`` where only the computer reaches it (``served``): on Linux and macOS the Unix socket +``.agentenv/server.sock`` there, on Windows a loopback port it writes there with a token. It takes no control token +(``CONTROL_TOKEN_ENV``): the driver checks it in front of the app. Before it serves, it keeps a copy of the app's data paths as installed, which a reset puts back; once it serves, it adds the app's launcher and launches a boot app (``AppRuntime.start``). A server that can't start, or whose start fails once it serves, writes why to ``.agentenv/server.failure``, which its computer's driver reports, and exits. Needs the ``app`` extra.""" @@ -18,7 +19,8 @@ from ..types import CONTROL_TOKEN_ENV from ._load import load_class -from .app import FAILURE, SOCKET, ComputerAppEnvironment +from .app import FAILURE, ComputerAppEnvironment +from .served import LOOPBACK, SOCKET, bind, guarded USAGE = "usage: python -m agentenv_protocol.computer.serve_app :" @@ -43,7 +45,6 @@ def _serve(argv: list[str]) -> None: runtime = app._computer_app_runtime() app._computer_app_data_plane().keep_initial() asgi = app.create_app().streamable_http_app() - server = uvicorn.Server(uvicorn.Config(asgi, uds=str(SOCKET), log_level="warning")) serving, failed = asgi.router.lifespan_context, [] def stop(task: asyncio.Task) -> None: @@ -60,8 +61,14 @@ async def lifespan(scope): started.cancel() asgi.router.lifespan_context = lifespan - SOCKET.unlink(missing_ok=True) - server.run() + if LOOPBACK: + listening, token = bind(Path.cwd()) + server = uvicorn.Server(uvicorn.Config(guarded(asgi, token), log_level="warning")) + server.run(sockets=[listening]) + else: + server = uvicorn.Server(uvicorn.Config(asgi, uds=str(SOCKET), log_level="warning")) + SOCKET.unlink(missing_ok=True) + server.run() if failed: raise failed[0] diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/served.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/served.py new file mode 100644 index 000000000..69952c3b8 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/served.py @@ -0,0 +1,105 @@ +"""Where a computer app's own server answers, and how its computer reaches it (``serve_app``, ``apps``, ``svc``, +``launch``). On Linux and macOS it serves on the Unix socket ``SOCKET`` in the app's folder, which only the computer +reaches, so it takes no token. On Windows, whose asyncio serves no Unix socket, it serves on a free port of 127.0.0.1 +and writes that port, with a token it draws, to ``ADDRESS`` there; it answers only a request carrying the token, so no +other user of the computer gets in, and whatever reaches the app reads both from that file.""" +from __future__ import annotations + +import hmac +import json +import os +import secrets +import socket +import sys +from dataclasses import dataclass +from pathlib import Path +from typing import Any, Awaitable, Callable, Generator, Optional + +import httpx + +#: Where an app's own server listens on Linux and macOS, in the app's folder. +SOCKET = Path(".agentenv/server.sock") +#: Where an app's server on Windows writes the port it serves on and its token, in the app's folder. +ADDRESS = Path(".agentenv/server.json") +#: The header a request to an app's server on loopback carries its token in. +TOKEN_HEADER = "x-agentenv-app-token" +#: Whether this OS's app servers serve on loopback rather than a Unix socket. +LOOPBACK = sys.platform == "win32" + +Asgi = Callable[[dict, Callable[[], Awaitable[dict]], Callable[[dict], Awaitable[None]]], Awaitable[None]] + + +@dataclass(frozen=True) +class Served: + """An app's server as its computer reaches it: on its Unix ``socket``, or on ``port`` of 127.0.0.1 with ``token``, + through no proxy the environment names.""" + + socket: Optional[Path] = None + port: Optional[int] = None + token: Optional[str] = None + + def client(self, timeout: Optional[float]) -> httpx.AsyncClient: + return httpx.AsyncClient(**self._client_args(httpx.AsyncHTTPTransport), timeout=timeout) + + def sync_client(self, timeout: Optional[float]) -> httpx.Client: + return httpx.Client(**self._client_args(httpx.HTTPTransport), timeout=timeout) + + def _client_args(self, transport: type) -> dict[str, Any]: + if self.socket is not None: + return {"transport": transport(uds=str(self.socket)), "base_url": "http://app"} + return {"base_url": f"http://127.0.0.1:{self.port}", "auth": _Token(self.token), "trust_env": False} + + +def served(folder: Path) -> Served: + """How the server of the app in ``folder`` is reached: on the port and with the token it wrote, where it serves on + loopback, else on its socket. Nothing answering either way is an ``OSError`` once it's asked.""" + try: + written = json.loads((folder / ADDRESS).read_text(encoding="utf-8")) + except FileNotFoundError: + return Served(socket=folder / SOCKET) + return Served(port=written["port"], token=written["token"]) + + +def bind(folder: Path) -> tuple[socket.socket, str]: + """A socket listening on a free port of 127.0.0.1 and a token drawn for it, both written to ``ADDRESS`` in + ``folder`` once it listens, so a client that reads them finds the server, its connection waiting until the server + takes it.""" + listening = socket.create_server(("127.0.0.1", 0)) + token = secrets.token_urlsafe(32) + address = folder / ADDRESS + written = address.with_name(f"{address.name}.part") + written.write_text(json.dumps({"port": listening.getsockname()[1], "token": token}), encoding="utf-8") + os.replace(written, address) + return listening, token + + +def guarded(app: Asgi, token: str) -> Asgi: + """``app`` answering only a request or WebSocket that carries ``token`` in ``TOKEN_HEADER``, which it takes out + before ``app`` sees the request; any other is refused with 403, or a WebSocket closed with 1008 before it opens.""" + expected, header = token.encode(), TOKEN_HEADER.encode() + + async def guard(scope: dict, receive: Callable[[], Awaitable[dict]], send: Callable[[dict], Awaitable[None]]): + if scope["type"] not in ("http", "websocket"): + return await app(scope, receive, send) + given = [value for name, value in scope["headers"] if name == header] + if len(given) != 1 or not hmac.compare_digest(given[0], expected): + if scope["type"] == "websocket": + return await send({"type": "websocket.close", "code": 1008}) + await send({"type": "http.response.start", "status": 403, + "headers": [(b"content-type", b"text/plain; charset=utf-8")]}) + return await send({"type": "http.response.body", "body": b"this app's server takes its token alone"}) + return await app({**scope, "headers": [(name, value) for name, value in scope["headers"] if name != header]}, + receive, send) + + return guard + + +class _Token(httpx.Auth): + """``TOKEN_HEADER`` set on every request a client sends, in place of any it carried.""" + + def __init__(self, token: str) -> None: + self.token = token + + def auth_flow(self, request: httpx.Request) -> Generator[httpx.Request, httpx.Response, None]: + request.headers[TOKEN_HEADER] = self.token + yield request diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/session.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/session.py index f57cc8c4f..7248d9354 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/session.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/session.py @@ -1,157 +1,16 @@ -"""What a computer app's own server does in the desktop session, the Linux way: wait for the session, launch the app -into it and stop it, add its menu launcher and list the session's windows. Another OS type brings its own.""" +"""What a computer app's own server does in the desktop session, its OS's way: wait for the session, launch the app +into it in a group that holds whatever it starts, stop, pause and look for that group, add the app's menu launcher and +list the session's windows. Linux and macOS share the POSIX way (``_session_posix``); Windows has its own +(``_session_windows``). How a launched process exited is kept alike for both (``_reaping``).""" from __future__ import annotations -import asyncio -import contextlib -import os -import re -import signal import sys -from pathlib import Path -from typing import Iterator, Optional -#: How often a starting session is looked for. -POLL_S = 0.2 -#: Moves the fds an app is launched with into place, run on its own so it loads nothing but the standard library. -WITH_FDS = Path(__file__).with_name("_with_fds.py") -#: The processes launched into the session, kept until they exit so each is reaped. -_running: set[asyncio.Task] = set() -#: Each launched process's reaping, by pid, until its exit is asked for: its return code, negative for a signal. -_exits: dict[int, asyncio.Future] = {} -#: How many exits no one has asked for are kept, the latest. -KEPT_EXITS = 16 +from ._reaping import returncode +if sys.platform == "win32": + from ._session_windows import add_launcher, alive, launch, paused, stop, wait_until_up, windows +else: + from ._session_posix import add_launcher, alive, launch, paused, stop, wait_until_up, windows -async def wait_until_up() -> None: - """Until the X display's socket is there.""" - display = os.environ["DISPLAY"].lstrip(":").split(".")[0] - while not Path(f"/tmp/.X11-unix/X{display}").exists(): - await asyncio.sleep(POLL_S) - - -async def launch(argv: list[str], cwd: Path, env: dict[str, str], fds: Optional[dict[int, int]] = None) -> int: - """Start ``argv`` in ``cwd``, in a session of its own so it outlives the server, with the server's environment and - ``env``, and ``fds``, the server's fds it inherits by the number each gets in it; its pid.""" - if fds: - argv = [sys.executable, "-I", "-S", str(WITH_FDS), *(f"{source}={target}" for target, source in fds.items()), - "--", *argv] - process = await asyncio.create_subprocess_exec( - *argv, cwd=cwd, env={**os.environ, **env}, start_new_session=True, stdin=asyncio.subprocess.DEVNULL, - stdout=asyncio.subprocess.DEVNULL, stderr=asyncio.subprocess.DEVNULL, pass_fds=tuple((fds or {}).values())) - reaped = asyncio.ensure_future(process.wait()) - _running.add(reaped) - reaped.add_done_callback(_running.discard) - _exits[process.pid] = reaped - reaped.add_done_callback(lambda _: _forget_old_exits()) - return process.pid - - -def _forget_old_exits() -> None: - """Drop all but the latest ``KEPT_EXITS`` exits no one has asked for.""" - for pid in [pid for pid, reaped in _exits.items() if reaped.done()][:-KEPT_EXITS]: - del _exits[pid] - - -async def returncode(pid: int, timeout_s: float) -> Optional[int]: - """The return code the process ``launch`` started as ``pid`` exited with, negative for the signal that ended it, - once it's reaped within ``timeout_s``; None for one ``launch`` didn't start or that hasn't exited.""" - reaped = _exits.get(pid) - if reaped is None: - return None - try: - code = await asyncio.wait_for(asyncio.shield(reaped), timeout_s) - except TimeoutError: - return None - _exits.pop(pid, None) - return code - - -async def stop(pid: int, timeout_s: float) -> None: - """End the session ``launch`` started as ``pid``, every process in it: asked to exit, a paused one continued so it - can, then killed after ``timeout_s``. No one asks how it exited once it's stopped.""" - _exits.pop(pid, None) - try: - os.killpg(pid, signal.SIGTERM) - except ProcessLookupError: - return - with contextlib.suppress(ProcessLookupError, PermissionError): # macOS refuses a group of zombies alone - os.killpg(pid, signal.SIGCONT) - try: - await asyncio.wait_for(_exited(pid), timeout_s) - except TimeoutError: - with contextlib.suppress(ProcessLookupError): - os.killpg(pid, signal.SIGKILL) - - -@contextlib.contextmanager -def paused(pid: int) -> Iterator[None]: - """Every process of the session ``launch`` started as ``pid`` stopped while the block runs, and continued after.""" - try: - os.killpg(pid, signal.SIGSTOP) - except (ProcessLookupError, PermissionError): - yield - return - try: - yield - finally: - with contextlib.suppress(ProcessLookupError, PermissionError): - os.killpg(pid, signal.SIGCONT) - - -def alive(pid: int) -> bool: - """Whether a process of the session ``launch`` started as ``pid`` is running, its first or one it started.""" - try: - os.killpg(pid, 0) - except ProcessLookupError: - return False - except PermissionError: - return True - return True - - -async def _exited(pid: int) -> None: - while alive(pid): - await asyncio.sleep(POLL_S) - - -def add_launcher(name: str, folder: Path) -> Path: - """The desktop entry that launches the app ``name`` in ``folder`` through its own server, written where the - session user's menu finds it.""" - entry = Path.home() / ".local/share/applications" / f"agentenv-app-{folder.name}.desktop" - entry.parent.mkdir(parents=True, exist_ok=True) - entry.write_text(f"[Desktop Entry]\nType=Application\nName={name}\n" - f"Exec={folder}/venv/bin/python -m agentenv_protocol.computer.launch {folder}\nTerminal=false\n") - return entry - - -async def windows() -> list[dict[str, str]]: - """The window manager's top-level windows, each as its WM_CLASS ``instance`` and ``class`` and its ``title``, read - with ``xprop``: ``_NET_WM_NAME``, or ``WM_NAME`` for a window that sets only that; a window that closes while it's - read is left out.""" - listed = await _xprop("-root", "_NET_CLIENT_LIST") - found = [] - for window in re.findall(r"0x[0-9a-f]+", listed.partition("#")[2]): - props = await _xprop("-id", window, "WM_CLASS", "_NET_WM_NAME", "WM_NAME") - names = dict(re.findall(r'^(WM_CLASS|_NET_WM_NAME|WM_NAME)[^=]*= (.*)$', props, re.MULTILINE)) - parts = _strings(names.get("WM_CLASS", "")) - if len(parts) == 2: - title = _strings(names.get("_NET_WM_NAME") or names.get("WM_NAME", "")) - found.append({"instance": parts[0], "class": parts[1], "title": title[0] if title else ""}) - return found - - -def _strings(value: str) -> list[str]: - """The quoted strings of an ``xprop`` value, as the window holds them, without the escapes ``xprop`` prints.""" - return [re.sub(r"\\(.)", r"\1", text) for text in re.findall(r'"((?:[^"\\]|\\.)*)"', value)] - - -async def _xprop(*args: str) -> str: - process = await asyncio.create_subprocess_exec("xprop", *args, stdout=asyncio.subprocess.PIPE, - stderr=asyncio.subprocess.DEVNULL) - try: - out, _ = await process.communicate() - except asyncio.CancelledError: - process.kill() - raise - return out.decode(errors="replace") if process.returncode == 0 else "" +__all__ = ["add_launcher", "alive", "launch", "paused", "returncode", "stop", "wait_until_up", "windows"] diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/svc.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/svc.py index 6544adae2..1873bcebe 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/svc.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/svc.py @@ -18,11 +18,11 @@ from starlette.requests import Request from starlette.responses import Response, StreamingResponse from starlette.websockets import WebSocket, WebSocketDisconnect -from websockets.asyncio.client import ClientConnection, unix_connect +from websockets.asyncio.client import ClientConnection, connect, unix_connect from ..agent_env_environment import _error_response -from .app import SOCKET from .errors import DeliveryFailed +from .served import TOKEN_HEADER, served #: The methods the route forwards. METHODS = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"] @@ -57,9 +57,9 @@ def passed_on(headers: Iterable[tuple[str, str]], *dropped: str) -> list[tuple[s def to_app(headers: Iterable[tuple[str, str]], host: str, scheme: str, prefix: str) -> list[tuple[str, str]]: """A caller's headers as the app gets them: passed on without the control token's ``Authorization`` or any address - the caller forwarded, and with the one it reached the driver at, its ``host``, ``scheme`` and the app's - ``prefix``.""" - return passed_on(headers, "authorization", *FORWARDED) + [ + the caller forwarded, nor any app token, which the driver sets itself where the app takes one, and with the + address it reached the driver at, its ``host``, ``scheme`` and the app's ``prefix``.""" + return passed_on(headers, "authorization", TOKEN_HEADER, *FORWARDED) + [ ("x-forwarded-host", host), ("x-forwarded-proto", scheme), ("x-forwarded-prefix", prefix)] @@ -119,8 +119,7 @@ async def forward(folder: Path, name: str, request: Request) -> Response: client's own, its body and its answer streamed; it takes as long as the app does.""" headers = to_app(request.headers.items(), request.headers.get("host", ""), request.url.scheme, f"/svc/{name}") has_body = request.headers.get("content-length", "0") != "0" or "transfer-encoding" in request.headers - http = httpx.AsyncClient(transport=httpx.AsyncHTTPTransport(uds=str(folder / SOCKET)), base_url="http://app", - timeout=None) + http = served(folder).client(timeout=None) http.headers.clear() try: answer = await http.send(http.build_request(request.method, target(request), headers=_bytes(headers), @@ -161,10 +160,14 @@ async def relay(folder: Path, name: str, websocket: WebSocket, opened: Optional[ websocket.headers.items(), host, "https" if websocket.url.scheme == "wss" else "http", f"/svc/{name}") if key.lower() != "host" and not key.lower().startswith("sec-websocket-")] offered = [p.strip() for p in websocket.headers.get("sec-websocket-protocol", "").split(",") if p.strip()] + reached, uri = served(folder), f"ws://{host or 'app'}{target(websocket)}" + options = {"subprotocols": offered or None, "max_size": None, "compression": None, "ping_interval": None, + "user_agent_header": None} try: - upstream = await unix_connect(str(folder / SOCKET), f"ws://{host or 'app'}{target(websocket)}", - additional_headers=headers, subprotocols=offered or None, max_size=None, - compression=None, ping_interval=None, user_agent_header=None) + upstream = await ( + unix_connect(str(reached.socket), uri, additional_headers=headers, **options) if reached.socket else + connect(uri, host="127.0.0.1", port=reached.port, proxy=None, + additional_headers=[*headers, (TOKEN_HEADER, reached.token)], **options)) except (OSError, ValueError, asyncio.TimeoutError, websockets.WebSocketException): await websocket.close(code=1011) return diff --git a/packages/agentenv-protocol/tests/test_computer_app_server.py b/packages/agentenv-protocol/tests/test_computer_app_server.py index 227203572..672e6642d 100644 --- a/packages/agentenv-protocol/tests/test_computer_app_server.py +++ b/packages/agentenv-protocol/tests/test_computer_app_server.py @@ -30,7 +30,7 @@ from agentenv_protocol import client # noqa: E402 from agentenv_protocol.computer import (ComputerAppEnvironment, Launch, ReadyCheck, Ready, linux, # noqa: E402 ready_check) -from agentenv_protocol.computer import app, app_runtime, apps, session # noqa: E402 +from agentenv_protocol.computer import _reaping, _session_posix, app, app_runtime, apps, session # noqa: E402 from agentenv_protocol.computer.app import COMPUTER_APP, FAILURE, SOCKET # noqa: E402 from agentenv_protocol.computer.platform import Platform # noqa: E402 from agentenv_protocol.types import CONTROL_TOKEN_ENV, DATA_OBJECTS_EXTENSION_URI, WELL_KNOWN_PATH # noqa: E402 @@ -373,7 +373,7 @@ async def test_the_session_launches_an_app_in_a_session_of_its_own_from_its_fold "{os.environ['DISPLAY']} {os.getsid(0) == os.getpid()}\")" await session.launch([sys.executable, "-c", script], tmp_path, {"ENVIRONMENT_NAME": "notes"}) - await asyncio.gather(*session._running) + await asyncio.gather(*_reaping._running) assert (tmp_path / "seen").read_text() == f"{os.path.realpath(tmp_path)} notes :99 True" @@ -382,7 +382,7 @@ async def test_the_session_launches_an_app_in_a_session_of_its_own_from_its_fold async def test_a_stop_ends_what_the_app_started_though_its_first_process_exited(tmp_path): sleeper = f"{sys.executable} -c 'import time; time.sleep(60)' & exit 0" pid = await session.launch(["sh", "-c", sleeper], tmp_path, {}) - await asyncio.gather(*session._running) + await asyncio.gather(*_reaping._running) running = session.alive(pid) await session.stop(pid, 5) @@ -395,7 +395,7 @@ async def test_a_paused_session_runs_nothing_until_the_block_ends_and_a_stop_end counter = (f"{sys.executable} -c 'import os, time\nn = 0\nwhile True:\n n += 1\n open(\"count.new\", \"w\")" ".write(str(n))\n os.replace(\"count.new\", \"count\")\n time.sleep(0.02)' & exit 0") pid = await session.launch(["sh", "-c", counter], tmp_path, {}) - await asyncio.gather(*session._running) + await asyncio.gather(*_reaping._running) await asyncio.sleep(0.5) def count() -> int: @@ -440,7 +440,7 @@ async def test_the_sessions_windows_are_listed_by_class_instance_and_title_from_ async def xprop(*args): return replies[args] - monkeypatch.setattr(session, "_xprop", xprop) + monkeypatch.setattr(_session_posix, "_xprop", xprop) assert await session.windows() == [{"instance": "mail", "class": "Mail", "title": 'Inbox "work"'}, {"instance": "xcalc", "class": "XCalc", "title": "Calculator"}] diff --git a/packages/agentenv-protocol/tests/test_computer_serve.py b/packages/agentenv-protocol/tests/test_computer_serve.py index 775d48d26..0c87aecc2 100644 --- a/packages/agentenv-protocol/tests/test_computer_serve.py +++ b/packages/agentenv-protocol/tests/test_computer_serve.py @@ -3,6 +3,7 @@ from __future__ import annotations import asyncio +import json import os import sys @@ -16,6 +17,7 @@ from agentenv_protocol.computer import ComputerDriverEnvironment, run_install_step, serve_app # noqa: E402 from agentenv_protocol.computer.app import BUILD_SETTINGS, FAILURE, SOCKET # noqa: E402 from agentenv_protocol.computer.app_runtime import AppRuntime # noqa: E402 +from agentenv_protocol.computer.served import ADDRESS # noqa: E402 from agentenv_protocol.computer.serve import USAGE, main # noqa: E402 DRIVER = '''from desk_helpers import SIZE @@ -146,7 +148,8 @@ def test_what_isnt_a_driver_class_exits_saying_why(tmp_path, served, monkeypatch @pytest.fixture def app_folder(tmp_path, monkeypatch, isolated): """An app's folder, holding ``APP`` and what its last server left, whose server only runs its app's lifespan, as - uvicorn runs it around serving; each server is recorded.""" + uvicorn runs it around serving, through the ASGI lifespan protocol; each server is recorded, with the sockets it + was handed.""" (tmp_path / "app.py").write_text(APP) (tmp_path / SOCKET).parent.mkdir() (tmp_path / SOCKET).write_text("left by the last server") @@ -154,13 +157,24 @@ def app_folder(tmp_path, monkeypatch, isolated): monkeypatch.chdir(tmp_path) ran = [] - def run(server): + def run(server, sockets=None): async def lifespan(): - async with server.config.app.router.lifespan_context(server.config.app): - await asyncio.sleep(0.05) + inbox, sent = asyncio.Queue(), [] + + async def send(message): + sent.append(message["type"]) + + await inbox.put({"type": "lifespan.startup"}) + running = asyncio.ensure_future(server.config.app({"type": "lifespan", "asgi": {"version": "3.0"}, + "state": {}}, inbox.get, send)) + while not {"lifespan.startup.complete", "lifespan.startup.failed"} & set(sent): + await asyncio.sleep(0.01) + await asyncio.sleep(0.05) + await inbox.put({"type": "lifespan.shutdown"}) + await running asyncio.run(lifespan()) - ran.append(server) + ran.append((server, sockets)) monkeypatch.setattr(serve_app.uvicorn.Server, "run", run) return tmp_path, ran @@ -179,8 +193,8 @@ async def start(runtime): serve_app.main(["app.py:Notes"]) - (server,) = ran - assert CONTROL_TOKEN_ENV not in os.environ + ((server, sockets),) = ran + assert CONTROL_TOKEN_ENV not in os.environ and sockets is None assert server.config.uds == str(SOCKET) and not server.should_exit assert not (folder / SOCKET).exists() and not (folder / FAILURE).exists() assert len(started) == 1 and isinstance(started[0], AppRuntime) @@ -197,10 +211,33 @@ async def start(runtime): with pytest.raises(PermissionError): serve_app.main(["app.py:Notes"]) - assert ran[0].should_exit is True + assert ran[0][0].should_exit is True assert (folder / FAILURE).read_text() == "PermissionError: ~/.local/share/applications isn't writable" +def test_an_apps_server_on_windows_serves_on_a_loopback_port_it_writes_in_its_folder_with_a_token(app_folder, + monkeypatch): + folder, ran = app_folder + monkeypatch.setattr(serve_app, "LOOPBACK", True) + + async def start(runtime): + pass + + monkeypatch.setattr(AppRuntime, "start", start) + + serve_app.main(["app.py:Notes"]) + + ((server, sockets),) = ran + written = json.loads((folder / ADDRESS).read_text()) + try: + assert server.config.uds is None and [listening.getsockname() for listening in sockets] == [ + ("127.0.0.1", written["port"])] + assert len(written["token"]) >= 32 and not (folder / FAILURE).exists() + finally: + for listening in sockets: + listening.close() + + @pytest.mark.parametrize("argv, failure", [ ([], f"SystemExit: {serve_app.USAGE}"), (["app.py"], f"SystemExit: {serve_app.USAGE}"), (["missing.py:Notes"], "SystemExit: missing.py isn't a file"), diff --git a/packages/agentenv-protocol/tests/test_computer_served.py b/packages/agentenv-protocol/tests/test_computer_served.py new file mode 100644 index 000000000..6942f69fd --- /dev/null +++ b/packages/agentenv-protocol/tests/test_computer_served.py @@ -0,0 +1,93 @@ +"""Where an app's own server answers and how its computer reaches it: on its folder's Unix socket unless it wrote a +loopback port and token there, as it does on Windows. On loopback it answers only a request or WebSocket carrying its +token, once, which it takes out before the app sees the request, and a client reaches it through no proxy the +environment names.""" +from __future__ import annotations + +import asyncio +import contextlib +import json +from pathlib import Path + +import httpx +import pytest + +uvicorn = pytest.importorskip("uvicorn") + +from starlette.applications import Starlette # noqa: E402 +from starlette.requests import Request # noqa: E402 +from starlette.responses import JSONResponse # noqa: E402 +from starlette.routing import Route, WebSocketRoute # noqa: E402 +from starlette.websockets import WebSocket # noqa: E402 +from websockets.asyncio.client import connect # noqa: E402 +from websockets.exceptions import InvalidStatus # noqa: E402 + +from agentenv_protocol.computer.served import ADDRESS, SOCKET, TOKEN_HEADER, Served, bind, guarded, served # noqa: E402 + + +async def _headers(request: Request) -> JSONResponse: + return JSONResponse(dict(request.headers.items())) + + +async def _hello(websocket: WebSocket) -> None: + await websocket.accept() + await websocket.send_text("hello") + await websocket.close() + + +@contextlib.asynccontextmanager +async def _serving(folder: Path): + """An app answering its headers and a WebSocket hello, served on loopback with its token, as on Windows.""" + (folder / ADDRESS).parent.mkdir(parents=True, exist_ok=True) + listening, token = bind(folder) + app = Starlette(routes=[Route("/headers", _headers), WebSocketRoute("/hello", _hello)]) + server = uvicorn.Server(uvicorn.Config(guarded(app, token), log_level="warning", lifespan="off")) + serving = asyncio.create_task(server.serve(sockets=[listening])) + while not server.started: + await asyncio.sleep(0.01) + try: + yield token + finally: + server.should_exit = True + await serving + + +def test_an_app_that_wrote_no_loopback_address_is_reached_on_its_socket(tmp_path): + assert served(tmp_path) == Served(socket=tmp_path / SOCKET) + + +@pytest.mark.asyncio +async def test_an_app_on_loopback_answers_its_token_alone_and_the_app_never_sees_it(tmp_path, monkeypatch): + monkeypatch.setenv("HTTP_PROXY", "http://127.0.0.1:9") + monkeypatch.setenv("ALL_PROXY", "http://127.0.0.1:9") + async with _serving(tmp_path) as token: + reached = served(tmp_path) + async with reached.client(timeout=5) as http: + seen = (await http.get("/headers", headers={TOKEN_HEADER: "forged"})).json() + port = reached.port + async with httpx.AsyncClient(base_url=f"http://127.0.0.1:{port}", trust_env=False) as bare: + missing = await bare.get("/headers") + wrong = await bare.get("/headers", headers={TOKEN_HEADER: "nope"}) + twice = await bare.get("/headers", headers=[(TOKEN_HEADER, token), (TOKEN_HEADER, token)]) + async with connect(f"ws://127.0.0.1:{port}/hello", additional_headers=[(TOKEN_HEADER, token)], + proxy=None) as websocket: + hello = await websocket.recv() + with pytest.raises(InvalidStatus) as refused: + async with connect(f"ws://127.0.0.1:{port}/hello", proxy=None): + pass + + assert TOKEN_HEADER not in seen and seen["host"] == f"127.0.0.1:{port}" + assert (missing.status_code, wrong.status_code, twice.status_code) == (403, 403, 403) + assert hello == "hello" and refused.value.response.status_code == 403 + + +def test_a_loopback_address_is_written_whole_with_the_port_listened_on(tmp_path): + (tmp_path / ADDRESS).parent.mkdir() + listening, token = bind(tmp_path) + try: + written = json.loads((tmp_path / ADDRESS).read_text()) + assert written == {"port": listening.getsockname()[1], "token": token} and len(token) >= 32 + assert listening.getsockname()[0] == "127.0.0.1" + assert sorted(path.name for path in (tmp_path / ADDRESS).parent.iterdir()) == [ADDRESS.name] + finally: + listening.close() diff --git a/packages/agentenv-protocol/tests/test_computer_session_windows.py b/packages/agentenv-protocol/tests/test_computer_session_windows.py new file mode 100644 index 000000000..4cc8e57fe --- /dev/null +++ b/packages/agentenv-protocol/tests/test_computer_session_windows.py @@ -0,0 +1,182 @@ +"""The Windows session's own logic, its Win32 calls faked and its job helper stood in for: a launch goes through the +helper and returns its pid once the app has started, or fails saying why it couldn't, and hands no fds; stopping asks +the app's windows to close, then ends the job after the timeout, or at once with no window to ask; pausing suspends each +of the app's processes but the helper's and resumes them, even when the block raises; a job that's gone is neither +alive, stopped nor paused; the windows listed are those shown, by program, class and title; and the menu launcher is a +Start Menu shortcut PowerShell writes, named for the app.""" +from __future__ import annotations + +import subprocess +import sys +import time +from pathlib import Path + +import pytest + +from agentenv_protocol.computer import _reaping, _session_posix, _session_windows, session +from agentenv_protocol.computer._session_windows import Window + +HELPER = 900 +FAKE_HELPER = '''import sys, time +command = sys.argv[sys.argv.index("--") + 1:] +if command[0] == "missing": + sys.stderr.write("Traceback (most recent call last):\\nFileNotFoundError: [WinError 2] missing\\n") + sys.exit(2) +print("started", flush=True) +time.sleep(0.1) +sys.exit(int(command[0])) +''' + + +class FakeWin32: + """Jobs by their helper's pid, each a list of the pids in it, the helper's first; the session's windows; and every + call that acts, recorded. An app whose window is asked to close ``closes`` or doesn't.""" + + def __init__(self, jobs: dict[int, list[int]], windows: list[Window], closes: bool = True) -> None: + self.jobs, self._windows, self.closes = jobs, windows, closes + self.posted, self.terminated, self.suspended, self.resumed, self.open = [], [], [], [], 0 + + def open_job(self, helper): + if helper not in self.jobs: + return None + self.open += 1 + return helper + + def job_pids(self, job): + return list(self.jobs[job]) + + def terminate_job(self, job): + self.terminated.append(job) + self.jobs[job] = [] + + def close(self, handle): + self.open -= 1 + + def suspend(self, pid): + self.suspended.append(pid) + return True + + def resume(self, pid): + self.resumed.append(pid) + + def post_close(self, handle): + self.posted.append(handle) + if self.closes: + window = next(window for window in self._windows if window.handle == handle) + for pids in self.jobs.values(): + if window.pid in pids: + pids.remove(window.pid) + + def windows(self): + return list(self._windows) + + +def _window(handle: int, pid: int, shown: bool = True, title: str = "Notes") -> Window: + return Window(handle=handle, pid=pid, program="python.exe", class_name="TkTopLevel", title=title, shown=shown) + + +@pytest.fixture +def win32(monkeypatch): + def install(*args, **kwargs) -> FakeWin32: + fake = FakeWin32(*args, **kwargs) + monkeypatch.setattr(_session_windows, "_win32", fake) + monkeypatch.setattr(_session_windows, "POLL_S", 0.01) + return fake + return install + + +@pytest.mark.asyncio +async def test_stopping_asks_the_apps_windows_to_close_and_ends_the_job_only_if_they_dont(win32): + obliging = win32({HELPER: [HELPER, 901, 902]}, [_window(1, 901), _window(2, 777), _window(3, 902, shown=False)]) + await _session_windows.stop(HELPER, timeout_s=5) + stubborn = win32({HELPER: [HELPER, 901]}, [_window(1, 901)], closes=False) + started = time.monotonic() + await _session_windows.stop(HELPER, timeout_s=0.2) + + assert obliging.posted == [1, 3] and obliging.terminated == [] and obliging.open == 0 + assert stubborn.posted == [1] and stubborn.terminated == [HELPER] and time.monotonic() - started >= 0.2 + + +@pytest.mark.asyncio +async def test_an_app_with_no_window_to_ask_is_ended_at_once_and_a_gone_job_is_left_be(win32): + windowless = win32({HELPER: [HELPER, 901]}, [_window(1, 777)]) + started = time.monotonic() + await _session_windows.stop(HELPER, timeout_s=10) + gone = win32({}, []) + await _session_windows.stop(HELPER, timeout_s=10) + + assert windowless.terminated == [HELPER] and time.monotonic() - started < 1 + assert gone.terminated == [] and gone.open == 0 and not _session_windows.alive(HELPER) + + +def test_pausing_suspends_every_process_but_the_helper_and_resumes_them_even_when_the_block_raises(win32): + fake = win32({HELPER: [HELPER, 901, 902]}, []) + with pytest.raises(RuntimeError): + with _session_windows.paused(HELPER): + paused_then = (list(fake.suspended), list(fake.resumed)) + raise RuntimeError("the copy failed") + gone = win32({}, []) + with _session_windows.paused(HELPER): + pass + + assert paused_then == ([901, 902], []) and fake.resumed == [901, 902] and fake.open == 0 + assert gone.suspended == [] and _session_windows.alive(HELPER) is False + + +@pytest.mark.asyncio +async def test_the_sessions_windows_are_the_shown_ones_by_program_class_and_title(win32): + win32({}, [_window(1, 901, title="Inbox"), _window(2, 902, shown=False, title="Cloaked")]) + + assert await _session_windows.windows() == [{"instance": "python.exe", "class": "TkTopLevel", "title": "Inbox"}] + + +def test_the_menu_launcher_is_a_start_menu_shortcut_powershell_writes_named_for_the_app(tmp_path, monkeypatch): + ran = [] + monkeypatch.setenv("APPDATA", str(tmp_path)) + monkeypatch.setattr(subprocess, "CREATE_NO_WINDOW", 0x08000000, raising=False) + monkeypatch.setattr(subprocess, "run", lambda argv, **kwargs: ran.append((argv, kwargs))) + folder = Path("C:/agentenv/apps/notes") + + entry = _session_windows.add_launcher('Notes: "draft"', folder) + + ((argv, kwargs),) = ran + assert entry == tmp_path / "Microsoft/Windows/Start Menu/Programs" / "Notes_ _draft_.lnk" and entry.parent.is_dir() + assert argv[:3] == ["powershell", "-NoProfile", "-NonInteractive"] and argv[-1] == _session_windows.SHORTCUT + assert {key: kwargs["env"][key] for key in ("AGENTENV_SHORTCUT", "AGENTENV_TARGET", "AGENTENV_ARGUMENTS")} == { + "AGENTENV_SHORTCUT": str(entry), "AGENTENV_TARGET": str(folder / "venv" / "Scripts" / "pythonw.exe"), + "AGENTENV_ARGUMENTS": f'-m agentenv_protocol.computer.launch "{folder}"'} + assert kwargs["check"] is True and kwargs["creationflags"] == 0x08000000 + + +@pytest.fixture +def helper(tmp_path, monkeypatch): + """The job helper stood in for by a script that starts the app named by its exit code, or can't start + ``missing``; process flags only Windows takes, as none.""" + script = tmp_path / "_job.py" + script.write_text(FAKE_HELPER) + monkeypatch.setattr(_session_windows, "JOB", script) + for flag in ("CREATE_NEW_PROCESS_GROUP", "CREATE_NO_WINDOW"): + monkeypatch.setattr(subprocess, flag, 0, raising=False) + return script + + +@pytest.mark.asyncio +async def test_a_launch_returns_the_helpers_pid_once_the_app_has_started_and_its_exit_is_the_apps(helper, tmp_path): + pid = await _session_windows.launch(["7"], tmp_path, {}) + + assert await _reaping.returncode(pid, timeout_s=10) == 7 + + +@pytest.mark.asyncio +async def test_a_launch_that_cant_start_the_app_says_why_and_one_with_fds_is_refused(helper, tmp_path): + with pytest.raises(OSError, match=r"couldn't start missing: FileNotFoundError: \[WinError 2\] missing"): + await _session_windows.launch(["missing"], tmp_path, {}) + with pytest.raises(NotImplementedError, match="fds"): + await _session_windows.launch(["0"], tmp_path, {}, fds={3: 7}) + + +def test_the_session_is_its_oss_own(): + own = _session_windows if sys.platform == "win32" else _session_posix + + assert (session.launch, session.stop, session.paused, session.windows) == (own.launch, own.stop, own.paused, + own.windows) diff --git a/packages/agentenv-protocol/tests/test_computer_svc_forward.py b/packages/agentenv-protocol/tests/test_computer_svc_forward.py index 39f0f8040..4f1969880 100644 --- a/packages/agentenv-protocol/tests/test_computer_svc_forward.py +++ b/packages/agentenv-protocol/tests/test_computer_svc_forward.py @@ -1,4 +1,5 @@ -"""The driver's /svc// in front of an app's own server on its socket: a WebSocket is relayed both ways, with the +"""The driver's /svc// in front of an app's own server, on its socket as on Linux and macOS and on a loopback port +with its token as on Windows, alike: a WebSocket is relayed both ways, with the subprotocol the app picks, until the app closes it with its code, and only with the control token, off the routes the app opens to agents, and a Host that's a host; an answer streams through as the app sends it, 20 MB whole; every method and body goes on to the path as it came, still escaped, and the caller's headers, and only those, pass on as @@ -36,6 +37,7 @@ from agentenv_protocol import CONTROL_TOKEN_ENV, client # noqa: E402 from agentenv_protocol.computer import ComputerAppEnvironment, apps, linux, svc # noqa: E402 from agentenv_protocol.computer.app import AGENT_ACTED, SOCKET # noqa: E402 +from agentenv_protocol.computer.served import TOKEN_HEADER, bind, guarded # noqa: E402 from agentenv_protocol.tool_context import EMPTY # noqa: E402 MB = 1 << 20 @@ -107,19 +109,32 @@ async def _echo(self, websocket: WebSocket) -> None: else websocket.send_bytes(message["bytes"][::-1])) +@pytest.fixture(params=["socket", "loopback"]) +def transport(request) -> str: + """Where the app's server answers: its folder's Unix socket, as on Linux and macOS, or a loopback port with a + token, as on Windows.""" + return request.param + + @contextlib.asynccontextmanager -async def _computer(monkeypatch): - """The Echo app served on its socket in a computer's apps folder, and a driver in front of it on loopback, with a - control token; the app, and the driver's URL.""" +async def _computer(monkeypatch, transport: str): + """The Echo app served in a computer's apps folder over ``transport``, and a driver in front of it on loopback, with + a control token; the app, and the driver's URL.""" with tempfile.TemporaryDirectory(dir="/tmp", prefix="apps-") as root: folder = Path(root) / "echo" (folder / SOCKET).parent.mkdir(parents=True) monkeypatch.setattr(apps, "APPS", Path(root)) monkeypatch.setenv("ENVIRONMENT_NAME", "echo") app = Echo() - server = uvicorn.Server(uvicorn.Config(app.create_app().streamable_http_app(), uds=str(folder / SOCKET), - log_level="warning", lifespan="off")) - serving = asyncio.create_task(server.serve()) + asgi = app.create_app().streamable_http_app() + if transport == "loopback": + listening, token = bind(folder) + server = uvicorn.Server(uvicorn.Config(guarded(asgi, token), log_level="warning", lifespan="off")) + serving = asyncio.create_task(server.serve(sockets=[listening])) + else: + server = uvicorn.Server(uvicorn.Config(asgi, uds=str(folder / SOCKET), log_level="warning", + lifespan="off")) + serving = asyncio.create_task(server.serve()) while not server.started: await asyncio.sleep(0.01) monkeypatch.delenv("ENVIRONMENT_NAME") @@ -133,8 +148,8 @@ async def _computer(monkeypatch): @pytest.mark.asyncio -async def test_a_websocket_through_svc_reaches_the_app_both_ways_until_it_closes_and_only_with_the_token(monkeypatch): - async with _computer(monkeypatch) as (_, url): +async def test_a_websocket_through_svc_reaches_the_app_both_ways_until_it_closes_and_only_with_the_token(monkeypatch, transport): + async with _computer(monkeypatch, transport) as (_, url): ws = url.replace("http", "ws") + "/svc/echo/echo" async with connect(ws, additional_headers=client.control_headers(TOKEN), subprotocols=["cdp"]) as socket: hello = json.loads(await socket.recv()) @@ -168,8 +183,8 @@ async def test_a_websocket_through_svc_reaches_the_app_both_ways_until_it_closes @pytest.mark.asyncio async def test_an_agents_call_on_a_route_the_app_opens_and_a_tool_call_note_in_its_folder_that_an_agent_acted( - monkeypatch): - async with _computer(monkeypatch) as (_, url): + monkeypatch, transport): + async with _computer(monkeypatch, transport) as (_, url): marker = apps.APPS / "echo" / AGENT_ACTED async with httpx.AsyncClient() as http: await http.get(url + "/svc/echo/headers", headers=client.control_headers(TOKEN)) @@ -193,8 +208,8 @@ async def test_an_agents_call_on_a_route_the_app_opens_and_a_tool_call_note_in_i @pytest.mark.asyncio -async def test_an_answer_streams_through_svc_as_the_app_sends_it_20_mb_whole(monkeypatch): - async with _computer(monkeypatch) as (app, url): +async def test_an_answer_streams_through_svc_as_the_app_sends_it_20_mb_whole(monkeypatch, transport): + async with _computer(monkeypatch, transport) as (app, url): async with httpx.AsyncClient(base_url=url, headers=client.control_headers(TOKEN), timeout=30) as http: async with http.stream("GET", "/svc/echo/big") as answer: chunks, first = answer.aiter_raw(), [] @@ -212,13 +227,13 @@ async def first_mb() -> None: @pytest.mark.asyncio async def test_every_method_and_body_goes_on_and_headers_pass_but_the_hop_ones_token_and_forwarded_address( - monkeypatch): + monkeypatch, transport): payload = b"x" * (3 * MB) - async with _computer(monkeypatch) as (_, url): + async with _computer(monkeypatch, transport) as (_, url): async with httpx.AsyncClient(base_url=url, headers=client.control_headers(TOKEN), timeout=30) as http: seen = await http.get("/svc/echo/headers", headers={ "x-forwarded-host": "evil.test", "x-forwarded-prefix": "/elsewhere", "connection": "x-drop", - "x-drop": "1", "x-kept": "1"}) + "x-drop": "1", "x-kept": "1", TOKEN_HEADER: "forged"}) put = (await http.put("/svc/echo/upload", content=payload)).json() deleted = (await http.delete("/svc/echo/upload")).json() tokenless = httpx.AsyncClient(base_url=url) @@ -235,7 +250,7 @@ async def test_every_method_and_body_goes_on_and_headers_pass_but_the_hop_ones_t assert seen.json()["host"] == host and got["x-kept"] == "1" assert {key: got[key] for key in svc.FORWARDED} == { "x-forwarded-host": host, "x-forwarded-proto": "http", "x-forwarded-prefix": "/svc/echo"} - assert "authorization" not in got and "x-drop" not in got + assert "authorization" not in got and "x-drop" not in got and TOKEN_HEADER not in got assert seen.headers.get_list("set-cookie") == ["a=1", "b=2"] and "x-secret" not in seen.headers assert seen.headers["x-kept"] == "1" assert put == {"method": "PUT", "bytes": 3 * MB, "sha256": hashlib.sha256(payload).hexdigest()} @@ -248,10 +263,10 @@ async def test_every_method_and_body_goes_on_and_headers_pass_but_the_hop_ones_t @pytest.mark.asyncio -async def test_the_drivers_server_logs_a_path_under_a_route_open_to_agents_only_up_to_the_route(monkeypatch, caplog): +async def test_the_drivers_server_logs_a_path_under_a_route_open_to_agents_only_up_to_the_route(monkeypatch, transport, caplog): for logger in svc.SERVER_LOGGERS: monkeypatch.setattr(logging.getLogger(logger), "filters", []) - async with _computer(monkeypatch) as (_, url): + async with _computer(monkeypatch, transport) as (_, url): async with httpx.AsyncClient(base_url=url, headers=client.control_headers(TOKEN)) as http: with caplog.at_level(logging.INFO): opened = await http.get("/svc/echo/raw/a-secret/open") diff --git a/src/agent_env/drivers/envs/page/driver.py b/src/agent_env/drivers/envs/page/driver.py index 8503ab774..ca1fe8d3f 100644 --- a/src/agent_env/drivers/envs/page/driver.py +++ b/src/agent_env/drivers/envs/page/driver.py @@ -50,7 +50,7 @@ upload, ) from agentenv_protocol.computer import apps -from agentenv_protocol.computer.app import SOCKET +from agentenv_protocol.computer.served import served from agentenv_protocol.website_browser import BROWSER BUTTONS = {"left": 1, "right": 2, "middle": 4, "back": 8, "forward": 16} @@ -310,8 +310,7 @@ def _ended(folder: Path) -> Optional[str]: def _http(folder: Path) -> httpx.AsyncClient: - return httpx.AsyncClient(transport=httpx.AsyncHTTPTransport(uds=str(folder / SOCKET)), base_url="http://app", - timeout=CALL_TIMEOUT_S) + return served(folder).client(CALL_TIMEOUT_S) def _mouse(kind: str, x: float, y: float, button: str = "none", buttons: int = 0, count: int = 0, From 92ca3578de886b6641518c68574fccfc5193eb29 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sat, 7 Nov 2026 23:14:04 -0800 Subject: [PATCH 2/9] feat(computer): declare a Windows app with @windows; reap a launch by reading its pipes to their end Co-Authored-By: Claude Opus 5.5 --- .../agentenv_protocol/computer/__init__.py | 5 +++- .../agentenv_protocol/computer/_reaping.py | 10 +++++-- .../src/agentenv_protocol/computer/app.py | 29 ++++++++++++++++++- 3 files changed, 40 insertions(+), 4 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/__init__.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/__init__.py index 678080857..5ea9cf930 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/__init__.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/__init__.py @@ -21,11 +21,13 @@ Ready, RunScript, Service, + Windows, computer_app, install, install_step, linux, ready_check, + windows, ) from .errors import ( BackgroundUnavailable, @@ -123,7 +125,8 @@ def __getattr__(name: str) -> Any: __all__ = [ "ComputerDriverEnvironment", "computer_driver", "DEFAULT_IDENTITY", "DriverDeclaration", "MacOSDriver", "X11Driver", - "ComputerAppEnvironment", "computer_app", "install", "linux", "install_step", "ready_check", "Linux", "Service", + "ComputerAppEnvironment", "computer_app", "install", "linux", "windows", "install_step", "ready_check", "Linux", + "Windows", "Service", "Launch", "Ready", "Packages", "AptSource", "Download", "RunScript", "AppDeclaration", "AppOs", "APP_SETTINGS_ENV", "part_bytes", diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/_reaping.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/_reaping.py index 821ab99c4..a997a7afd 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/_reaping.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/_reaping.py @@ -14,14 +14,20 @@ def reap(process: asyncio.subprocess.Process) -> None: - """Reap ``process`` once it exits, its exit kept until it's asked for or ``KEPT_EXITS`` later ones push it out.""" - reaped = asyncio.ensure_future(process.wait()) + """Reap ``process`` once it exits, its exit kept until it's asked for or ``KEPT_EXITS`` later ones push it out; any + pipe it was started with is read to its end, so it closes with the process.""" + reaped = asyncio.ensure_future(_exited(process)) _running.add(reaped) reaped.add_done_callback(_running.discard) _exits[process.pid] = reaped reaped.add_done_callback(lambda _: _forget_old_exits()) +async def _exited(process: asyncio.subprocess.Process) -> int: + await process.communicate() + return process.returncode + + def forget(pid: int) -> None: """No one asks how ``pid`` exited: a process the server stopped.""" _exits.pop(pid, None) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/app.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/app.py index 8d76776e1..31cf49da5 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/app.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/app.py @@ -145,6 +145,20 @@ class Linux(BaseModel): ports: Optional[list[int]] = None +class Windows(BaseModel): + """How a Windows computer installs the app: as on Linux, with no apt; ``run`` scripts are PowerShell (``.ps1``), run + elevated as the computer is composed, and ``services`` run in the session user's sign-in.""" + + model_config = ConfigDict(extra="forbid") + + files: LayerPath = "." + python: Optional[LayerPath] = None + downloads: Optional[list[Download]] = None + run: Optional[list[RunScript]] = None + services: list[Service] = Field(default_factory=list) + ports: Optional[list[int]] = None + + class Ready(BaseModel): """When the app is ready: its window shown, a port answering or a command exiting 0, within ``timeout_s``.""" @@ -169,7 +183,8 @@ class Launch(BaseModel): at: Literal["boot", "demand"] = "boot" command: list[str] - #: Matches the app's window by its WM_CLASS ``class`` or ``instance`` and its ``title``, as given. + #: Matches the app's window by ``class``, ``instance`` and ``title``, as given: on X11 its WM_CLASS class and + #: instance; on Windows its window class and its program's file name, lowercased, such as ``notepad.exe``. window: Optional[dict[str, str]] = None ready: Optional[Ready] = None #: Variables set in the app's environment, over its server's. @@ -337,6 +352,18 @@ def linux(*, files: str = ".", packages: Optional[Packages] = None, python: Opti launch=launch, paths=paths, skill=skill, settings=settings, build_settings=build_settings) +def windows(*, files: str = ".", python: Optional[str] = None, downloads: Optional[list[Download]] = None, + run: Optional[list[RunScript]] = None, services: Optional[list[Service]] = None, + ports: Optional[list[int]] = None, launch: Optional[Launch] = None, paths: Optional[list[str]] = None, + skill: Optional[str] = None, settings: Optional[type[BaseModel]] = None, + build_settings: Optional[type[BaseModel]] = None) -> Callable: + """``@install`` for Windows: how a Windows computer installs the app, ``Windows``'s fields, and what is its own + there.""" + return install("windows", Windows(files=files, python=python, downloads=downloads, run=run, + services=services or [], ports=ports), + launch=launch, paths=paths, skill=skill, settings=settings, build_settings=build_settings) + + def install_step(scope: Literal["system", "session"] = "system", *, os: Union[str, list[str], None] = None) -> Callable: """Mark a method a computer runs as it installs the app, after its files, packages, venv and run scripts, in the From 4063ab5f1be6fe5facd357a186c6e6344315c766 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sat, 7 Nov 2026 23:18:00 -0800 Subject: [PATCH 3/9] test(computer): @windows takes every Windows field and declares its install under windows Co-Authored-By: Claude Opus 5.5 --- .../tests/test_computer_declare.py | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/packages/agentenv-protocol/tests/test_computer_declare.py b/packages/agentenv-protocol/tests/test_computer_declare.py index dcb1f2e6f..2abfc737a 100644 --- a/packages/agentenv-protocol/tests/test_computer_declare.py +++ b/packages/agentenv-protocol/tests/test_computer_declare.py @@ -18,7 +18,7 @@ from agentenv_protocol.computer import AppDeclaration # noqa: E402 from agentenv_protocol.computer._declare import _Stub, _StubModule, declare, main # noqa: E402 from agentenv_protocol.computer import (APP_SETTINGS_ENV, ComputerAppEnvironment, Launch, Linux, # noqa: E402 - install, linux) + Windows, install, linux, windows) from agentenv_protocol.computer import app as app_module # noqa: E402 from agentenv_protocol.computer.app import BUILD_SETTINGS # noqa: E402 from pydantic import BaseModel # noqa: E402 @@ -350,10 +350,25 @@ def test_a_declaration_stored_before_each_os_had_its_own_part_reads_as_its_linux assert AppDeclaration.model_validate(declared.model_dump(mode="json")) == declared -def test_linux_takes_every_field_of_a_linux_install_and_what_install_adds_for_an_os(): +def test_linux_and_windows_take_every_field_of_their_install_and_what_install_adds_for_an_os(): added = set(inspect.signature(install).parameters) - {"os_type", "spec"} assert set(inspect.signature(linux).parameters) == set(Linux.model_fields) | added + assert set(inspect.signature(windows).parameters) == set(Windows.model_fields) | added + + +def test_a_windows_app_declares_its_install_and_launch_under_windows(): + @windows(python="requirements.txt", services=[{"name": "sync", "command": "bin/sync.exe"}], + launch=Launch(command=["notes"], window={"title": "Notes"})) + class Notes(ComputerAppEnvironment): + pass + + declared = Notes.declaration() + + assert list(declared.os) == ["windows"] + assert declared.os["windows"].install == {"files": ".", "python": "requirements.txt", + "services": [{"name": "sync", "command": "bin/sync.exe"}]} + assert declared.os["windows"].launch == Launch(command=["notes"], window={"title": "Notes"}) def test_an_apps_code_needs_only_the_plain_package(): From 95195109246c18c5465492bf6cdda9c65a812bbf Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sat, 7 Nov 2026 23:25:43 -0800 Subject: [PATCH 4/9] fix(computer): pause a Windows app's processes until none is new, and name the window buffers' sizes Co-Authored-By: Claude Opus 5.5 --- .../computer/_session_windows.py | 17 ++++++++------ .../src/agentenv_protocol/computer/served.py | 5 +++-- .../tests/test_computer_session_windows.py | 22 +++++++++++-------- 3 files changed, 26 insertions(+), 18 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py index c3892a553..95e207d97 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py @@ -86,16 +86,17 @@ async def stop(pid: int, timeout_s: float) -> None: @contextlib.contextmanager def paused(pid: int) -> Iterator[None]: - """Every process of the job the helper ``pid`` holds suspended while the block runs, and resumed after.""" + """Every process of the job the helper ``pid`` holds suspended while the block runs, and resumed after. One not yet + suspended can start another, so the job is listed again until it holds none that's new.""" job = _win32.open_job(pid) if job is None: yield return - suspended = [] + suspended, seen = [], {pid} try: - for app_pid in _app_pids(job, pid): - if _win32.suspend(app_pid): - suspended.append(app_pid) + while fresh := [app_pid for app_pid in _win32.job_pids(job) if app_pid not in seen]: + seen.update(fresh) + suspended += [app_pid for app_pid in fresh if _win32.suspend(app_pid)] yield finally: for app_pid in suspended: @@ -159,6 +160,8 @@ class _Win32: DWMWA_CLOAKED = 14 #: How many process ids a job's list is read with room for, before it's read again with room for all. PIDS = 64 + #: The characters a window class's name and a program's full path take at most, with the closing NUL. + CLASS_NAME_CHARS, PATH_CHARS = 256, 32768 def __init__(self) -> None: self._dlls: Optional[tuple] = None @@ -208,7 +211,7 @@ def windows(self) -> list[Window]: for handle in handles: pid, cloaked = ctypes.c_uint32(), ctypes.c_uint32() user32.GetWindowThreadProcessId(handle, ctypes.byref(pid)) - class_name, title = ctypes.create_unicode_buffer(256), ctypes.create_unicode_buffer( + class_name, title = ctypes.create_unicode_buffer(self.CLASS_NAME_CHARS), ctypes.create_unicode_buffer( user32.GetWindowTextLengthW(handle) + 1) user32.GetClassNameW(handle, class_name, len(class_name)) user32.GetWindowTextW(handle, title, len(title)) @@ -220,7 +223,7 @@ def windows(self) -> list[Window]: def _program(self, pid: int) -> str: """The file name of the program running as ``pid``, lowercased, or empty where it can't be read.""" def read(process: int) -> str: - path, size = ctypes.create_unicode_buffer(32768), ctypes.c_uint32(32768) + path, size = ctypes.create_unicode_buffer(self.PATH_CHARS), ctypes.c_uint32(self.PATH_CHARS) if not self._api()[0].QueryFullProcessImageNameW(process, 0, path, ctypes.byref(size)): return "" return path.value.rpartition("\\")[2].lower() diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/served.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/served.py index 69952c3b8..bab1bb443 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/served.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/served.py @@ -1,8 +1,9 @@ """Where a computer app's own server answers, and how its computer reaches it (``serve_app``, ``apps``, ``svc``, ``launch``). On Linux and macOS it serves on the Unix socket ``SOCKET`` in the app's folder, which only the computer reaches, so it takes no token. On Windows, whose asyncio serves no Unix socket, it serves on a free port of 127.0.0.1 -and writes that port, with a token it draws, to ``ADDRESS`` there; it answers only a request carrying the token, so no -other user of the computer gets in, and whatever reaches the app reads both from that file.""" +and writes that port, with a token it draws, to ``ADDRESS`` there, in a folder its computer keeps the session user's +own; it answers only a request carrying the token, so no other user of the computer gets in, and whatever reaches the +app reads both from that file.""" from __future__ import annotations import hmac diff --git a/packages/agentenv-protocol/tests/test_computer_session_windows.py b/packages/agentenv-protocol/tests/test_computer_session_windows.py index 4cc8e57fe..712cc2f8f 100644 --- a/packages/agentenv-protocol/tests/test_computer_session_windows.py +++ b/packages/agentenv-protocol/tests/test_computer_session_windows.py @@ -1,9 +1,9 @@ """The Windows session's own logic, its Win32 calls faked and its job helper stood in for: a launch goes through the helper and returns its pid once the app has started, or fails saying why it couldn't, and hands no fds; stopping asks the app's windows to close, then ends the job after the timeout, or at once with no window to ask; pausing suspends each -of the app's processes but the helper's and resumes them, even when the block raises; a job that's gone is neither -alive, stopped nor paused; the windows listed are those shown, by program, class and title; and the menu launcher is a -Start Menu shortcut PowerShell writes, named for the app.""" +of the app's processes but the helper's, and any one starts as they're suspended, and resumes them, even when the block +raises; a job that's gone is neither alive, stopped nor paused; the windows listed are those shown, by program, class +and title; and the menu launcher is a Start Menu shortcut PowerShell writes, named for the app.""" from __future__ import annotations import subprocess @@ -30,10 +30,12 @@ class FakeWin32: """Jobs by their helper's pid, each a list of the pids in it, the helper's first; the session's windows; and every - call that acts, recorded. An app whose window is asked to close ``closes`` or doesn't.""" + call that acts, recorded. An app whose window is asked to close ``closes`` or doesn't, and a process ``spawns`` one + into its job just before it's suspended.""" - def __init__(self, jobs: dict[int, list[int]], windows: list[Window], closes: bool = True) -> None: - self.jobs, self._windows, self.closes = jobs, windows, closes + def __init__(self, jobs: dict[int, list[int]], windows: list[Window], closes: bool = True, + spawns: dict[int, int] | None = None) -> None: + self.jobs, self._windows, self.closes, self.spawns = jobs, windows, closes, spawns or {} self.posted, self.terminated, self.suspended, self.resumed, self.open = [], [], [], [], 0 def open_job(self, helper): @@ -53,6 +55,8 @@ def close(self, handle): self.open -= 1 def suspend(self, pid): + if pid in self.spawns: + next(pids for pids in self.jobs.values() if pid in pids).append(self.spawns[pid]) self.suspended.append(pid) return True @@ -109,8 +113,8 @@ async def test_an_app_with_no_window_to_ask_is_ended_at_once_and_a_gone_job_is_l assert gone.terminated == [] and gone.open == 0 and not _session_windows.alive(HELPER) -def test_pausing_suspends_every_process_but_the_helper_and_resumes_them_even_when_the_block_raises(win32): - fake = win32({HELPER: [HELPER, 901, 902]}, []) +def test_pausing_suspends_every_process_but_the_helper_and_those_they_start_and_resumes_them_even_on_a_raise(win32): + fake = win32({HELPER: [HELPER, 901, 902]}, [], spawns={902: 903, 903: 904}) with pytest.raises(RuntimeError): with _session_windows.paused(HELPER): paused_then = (list(fake.suspended), list(fake.resumed)) @@ -119,7 +123,7 @@ def test_pausing_suspends_every_process_but_the_helper_and_resumes_them_even_whe with _session_windows.paused(HELPER): pass - assert paused_then == ([901, 902], []) and fake.resumed == [901, 902] and fake.open == 0 + assert paused_then == ([901, 902, 903, 904], []) and fake.resumed == [901, 902, 903, 904] and fake.open == 0 assert gone.suspended == [] and _session_windows.alive(HELPER) is False From 40bd73f64966431d0c21ffd26a38b013e2e656c3 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sat, 7 Nov 2026 23:57:00 -0800 Subject: [PATCH 5/9] fix(computer): run a Windows app's job helper on the base interpreter, whose pid names its job A venv's python.exe on Windows is a launcher that runs the interpreter as a child, so the pid a launch held wasn't the helper's, and pausing, stopping and finding the job found none. Co-Authored-By: Claude Opus 5.5 --- .../src/agentenv_protocol/computer/_session_windows.py | 5 ++++- .../agentenv-protocol/tests/test_computer_session_windows.py | 5 +++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py index 95e207d97..b927186b0 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py @@ -22,6 +22,9 @@ #: The helper that runs an app in its job, run on its own so it loads nothing but the standard library. JOB = Path(__file__).with_name("_job.py") +#: The interpreter the helper runs on: the base one, as a venv's python.exe is a launcher that runs it as a child, and +#: the helper names its job for its own pid, which must be the pid a launch returns. +PYTHON = Path(sys.base_prefix) / "python.exe" #: How long the helper may take to start the app and say so. START_TIMEOUT_S = 30.0 #: How often a stopping app is looked at for having ended. @@ -45,7 +48,7 @@ async def launch(argv: list[str], cwd: Path, env: dict[str, str], fds: Optional[ if fds: raise NotImplementedError("a Windows app can't be handed the server's fds") process = await asyncio.create_subprocess_exec( - sys.executable, "-I", "-S", str(JOB), "--", *argv, cwd=cwd, env={**os.environ, **env}, + str(PYTHON), "-I", "-S", str(JOB), "--", *argv, cwd=cwd, env={**os.environ, **env}, stdin=asyncio.subprocess.DEVNULL, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE, creationflags=subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.CREATE_NO_WINDOW) try: diff --git a/packages/agentenv-protocol/tests/test_computer_session_windows.py b/packages/agentenv-protocol/tests/test_computer_session_windows.py index 712cc2f8f..84439c20f 100644 --- a/packages/agentenv-protocol/tests/test_computer_session_windows.py +++ b/packages/agentenv-protocol/tests/test_computer_session_windows.py @@ -154,11 +154,12 @@ def test_the_menu_launcher_is_a_start_menu_shortcut_powershell_writes_named_for_ @pytest.fixture def helper(tmp_path, monkeypatch): - """The job helper stood in for by a script that starts the app named by its exit code, or can't start - ``missing``; process flags only Windows takes, as none.""" + """The job helper stood in for by a script, on this interpreter, that starts the app named by its exit code, or + can't start ``missing``; process flags only Windows takes, as none.""" script = tmp_path / "_job.py" script.write_text(FAKE_HELPER) monkeypatch.setattr(_session_windows, "JOB", script) + monkeypatch.setattr(_session_windows, "PYTHON", Path(sys.executable)) for flag in ("CREATE_NEW_PROCESS_GROUP", "CREATE_NO_WINDOW"): monkeypatch.setattr(subprocess, flag, 0, raising=False) return script From 89f45b0d9ec56a710bbb8ae85ae5a3027d999093 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sun, 8 Nov 2026 00:07:19 -0800 Subject: [PATCH 6/9] fix(computer): a Windows app's stop waits until the job it ended holds no process Ending a job returns before its processes have, and a reset puts the app's files back once its stop returns, which a process still holding one open would refuse. The session's windows are listed off the event loop. Co-Authored-By: Claude Opus 5.5 --- .../computer/_session_windows.py | 11 +++++-- .../tests/test_computer_session_windows.py | 30 ++++++++++++------- 2 files changed, 28 insertions(+), 13 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py index b927186b0..9562656de 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py @@ -29,6 +29,9 @@ START_TIMEOUT_S = 30.0 #: How often a stopping app is looked at for having ended. POLL_S = 0.2 +#: How long a job ended by force is waited on to hold no process, so whatever its app had open is closed once a stop +#: returns, as a reset then puts the app's files back. +ENDED_TIMEOUT_S = 5.0 WM_CLOSE = 0x0010 #: A Start Menu shortcut, from its path, program, arguments and folder in the environment, as PowerShell writes one. SHORTCUT = ("$s = (New-Object -ComObject WScript.Shell).CreateShortcut($env:AGENTENV_SHORTCUT); " @@ -69,13 +72,14 @@ async def launch(argv: list[str], cwd: Path, env: dict[str, str], fds: Optional[ async def stop(pid: int, timeout_s: float) -> None: """End the job the helper ``pid`` holds, every process in it: its windows asked to close, then the job ended after - ``timeout_s``, or at once when it has no window to close. No one asks how it exited once it's stopped.""" + ``timeout_s``, or at once when it has no window to close, and waited on until it holds none. No one asks how it + exited once it's stopped.""" _reaping.forget(pid) job = _win32.open_job(pid) if job is None: return try: - windows = [window for window in _win32.windows() if window.pid in _app_pids(job, pid)] + windows = [window for window in await asyncio.to_thread(_win32.windows) if window.pid in _app_pids(job, pid)] for window in windows: _win32.post_close(window.handle) deadline = time.monotonic() + (timeout_s if windows else 0) @@ -83,6 +87,9 @@ async def stop(pid: int, timeout_s: float) -> None: await asyncio.sleep(POLL_S) if _app_pids(job, pid): _win32.terminate_job(job) + deadline = time.monotonic() + ENDED_TIMEOUT_S + while _win32.job_pids(job) and time.monotonic() < deadline: + await asyncio.sleep(POLL_S) finally: _win32.close(job) diff --git a/packages/agentenv-protocol/tests/test_computer_session_windows.py b/packages/agentenv-protocol/tests/test_computer_session_windows.py index 84439c20f..39f353218 100644 --- a/packages/agentenv-protocol/tests/test_computer_session_windows.py +++ b/packages/agentenv-protocol/tests/test_computer_session_windows.py @@ -1,9 +1,10 @@ """The Windows session's own logic, its Win32 calls faked and its job helper stood in for: a launch goes through the helper and returns its pid once the app has started, or fails saying why it couldn't, and hands no fds; stopping asks -the app's windows to close, then ends the job after the timeout, or at once with no window to ask; pausing suspends each -of the app's processes but the helper's, and any one starts as they're suspended, and resumes them, even when the block -raises; a job that's gone is neither alive, stopped nor paused; the windows listed are those shown, by program, class -and title; and the menu launcher is a Start Menu shortcut PowerShell writes, named for the app.""" +the app's windows to close, then ends the job after the timeout, or at once with no window to ask, and waits until it +holds no process; pausing suspends each of the app's processes but the helper's, and any one starts as they're +suspended, and resumes them, even when the block raises; a job that's gone is neither alive, stopped nor paused; the +windows listed are those shown, by program, class and title; and the menu launcher is a Start Menu shortcut PowerShell +writes, named for the app.""" from __future__ import annotations import subprocess @@ -30,26 +31,32 @@ class FakeWin32: """Jobs by their helper's pid, each a list of the pids in it, the helper's first; the session's windows; and every - call that acts, recorded. An app whose window is asked to close ``closes`` or doesn't, and a process ``spawns`` one - into its job just before it's suspended.""" + call that acts, recorded. An app whose window is asked to close ``closes`` or doesn't, a process ``spawns`` one + into its job just before it's suspended, and a job ended by force holds its processes for ``lingers`` more looks; + one that holds none is gone, as its handles close.""" def __init__(self, jobs: dict[int, list[int]], windows: list[Window], closes: bool = True, - spawns: dict[int, int] | None = None) -> None: - self.jobs, self._windows, self.closes, self.spawns = jobs, windows, closes, spawns or {} + spawns: dict[int, int] | None = None, lingers: int = 0) -> None: + self.jobs, self._windows, self.closes, self.spawns, self.lingers = jobs, windows, closes, spawns or {}, lingers + self.ending: dict[int, int] = {} self.posted, self.terminated, self.suspended, self.resumed, self.open = [], [], [], [], 0 def open_job(self, helper): - if helper not in self.jobs: + if not self.jobs.get(helper): return None self.open += 1 return helper def job_pids(self, job): + if job in self.ending: + self.ending[job] -= 1 + if self.ending[job] < 0: + self.jobs[job] = [] return list(self.jobs[job]) def terminate_job(self, job): self.terminated.append(job) - self.jobs[job] = [] + self.ending[job] = self.lingers def close(self, handle): self.open -= 1 @@ -93,12 +100,13 @@ def install(*args, **kwargs) -> FakeWin32: async def test_stopping_asks_the_apps_windows_to_close_and_ends_the_job_only_if_they_dont(win32): obliging = win32({HELPER: [HELPER, 901, 902]}, [_window(1, 901), _window(2, 777), _window(3, 902, shown=False)]) await _session_windows.stop(HELPER, timeout_s=5) - stubborn = win32({HELPER: [HELPER, 901]}, [_window(1, 901)], closes=False) + stubborn = win32({HELPER: [HELPER, 901]}, [_window(1, 901)], closes=False, lingers=3) started = time.monotonic() await _session_windows.stop(HELPER, timeout_s=0.2) assert obliging.posted == [1, 3] and obliging.terminated == [] and obliging.open == 0 assert stubborn.posted == [1] and stubborn.terminated == [HELPER] and time.monotonic() - started >= 0.2 + assert stubborn.jobs[HELPER] == [] and not _session_windows.alive(HELPER) @pytest.mark.asyncio From e73ce0ff4d6dfa75dd44f97a91dbc227f4abaa97 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sun, 8 Nov 2026 00:18:32 -0800 Subject: [PATCH 7/9] fix(computer): a Windows app is alive while its job holds a process, not while the job is there Co-Authored-By: Claude Opus 5.5 --- .../src/agentenv_protocol/computer/_session_windows.py | 9 ++++++--- .../tests/test_computer_session_windows.py | 6 +++--- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py index 9562656de..8a2f33bfd 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py @@ -115,12 +115,15 @@ def paused(pid: int) -> Iterator[None]: def alive(pid: int) -> bool: - """Whether the job the helper ``pid`` holds is there, which it is while any process of the app runs.""" + """Whether a process of the job the helper ``pid`` holds runs, the helper or one of the app's; a job a stop just + ended is there, empty, until its last handle closes.""" job = _win32.open_job(pid) if job is None: return False - _win32.close(job) - return True + try: + return bool(_win32.job_pids(job)) + finally: + _win32.close(job) def add_launcher(name: str, folder: Path) -> Path: diff --git a/packages/agentenv-protocol/tests/test_computer_session_windows.py b/packages/agentenv-protocol/tests/test_computer_session_windows.py index 39f353218..d13e21dbd 100644 --- a/packages/agentenv-protocol/tests/test_computer_session_windows.py +++ b/packages/agentenv-protocol/tests/test_computer_session_windows.py @@ -32,8 +32,8 @@ class FakeWin32: """Jobs by their helper's pid, each a list of the pids in it, the helper's first; the session's windows; and every call that acts, recorded. An app whose window is asked to close ``closes`` or doesn't, a process ``spawns`` one - into its job just before it's suspended, and a job ended by force holds its processes for ``lingers`` more looks; - one that holds none is gone, as its handles close.""" + into its job just before it's suspended, and a job ended by force holds its processes for ``lingers`` more looks, + then none, though it's there until its handles close.""" def __init__(self, jobs: dict[int, list[int]], windows: list[Window], closes: bool = True, spawns: dict[int, int] | None = None, lingers: int = 0) -> None: @@ -42,7 +42,7 @@ def __init__(self, jobs: dict[int, list[int]], windows: list[Window], closes: bo self.posted, self.terminated, self.suspended, self.resumed, self.open = [], [], [], [], 0 def open_job(self, helper): - if not self.jobs.get(helper): + if helper not in self.jobs: return None self.open += 1 return helper From de98352452ac77ecf2f3e6593d4eade8727c86b3 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sun, 8 Nov 2026 05:16:19 -0800 Subject: [PATCH 8/9] refactor(computer): reach an app's server by its OS's transport, from one module, and key the apps folder by OS On Windows an app's server is reached on the address it wrote, and one that hasn't written it isn't answering, which every caller handles; it used to fall back to a Unix socket, which Windows has none of, so a readiness check raised instead of saying the server hadn't started or why it failed. Served opens an app's WebSocket too, so svc no longer knows either transport, and app.py keeps the paths, so an app's own code still imports no websockets. apps_folder(os) says where a computer of each OS keeps its apps, which composing uses for the computer it composes rather than the OS it runs on. _Win32 names its DLLs, and kernel32's calls are typed in one place. Co-Authored-By: Claude Opus 5.5 --- .../src/agentenv_protocol/computer/_job.py | 2 + .../computer/_session_windows.py | 48 +++++++++++-------- .../src/agentenv_protocol/computer/app.py | 5 +- .../src/agentenv_protocol/computer/apps.py | 15 ++++-- .../src/agentenv_protocol/computer/served.py | 40 +++++++++------- .../src/agentenv_protocol/computer/svc.py | 23 +++++---- .../tests/test_computer_app_server.py | 16 ++++++- .../tests/test_computer_declare.py | 2 +- .../tests/test_computer_serve.py | 3 +- .../tests/test_computer_served.py | 20 ++++++-- .../tests/test_computer_svc_forward.py | 2 + .../env/envs/computer/utils/composer.py | 13 ++--- src/agent_env/env/envs/computer/utils/gate.py | 8 ++-- .../env/envs/computer/utils/windows_disk.py | 4 +- 14 files changed, 129 insertions(+), 72 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/_job.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/_job.py index 33aefe674..07996b76a 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/_job.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/_job.py @@ -65,6 +65,8 @@ def kernel32() -> ctypes.WinDLL: dll.TerminateJobObject.argtypes = [handle, ctypes.c_uint] dll.GetCurrentProcess.restype = handle dll.CloseHandle.argtypes = [handle] + dll.OpenProcess.argtypes, dll.OpenProcess.restype = [dword, ctypes.c_int, dword], handle + dll.QueryFullProcessImageNameW.argtypes = [handle, dword, wide, ctypes.c_void_p] return dll diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py index 8a2f33bfd..ef27cd542 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py @@ -16,7 +16,7 @@ import time from dataclasses import dataclass from pathlib import Path -from typing import Iterator, Optional +from typing import Iterator, NamedTuple, Optional from . import _job, _reaping @@ -177,15 +177,15 @@ class _Win32: CLASS_NAME_CHARS, PATH_CHARS = 256, 32768 def __init__(self) -> None: - self._dlls: Optional[tuple] = None + self._dlls: Optional[_Dlls] = None def open_job(self, helper: int) -> Optional[int]: """A handle to the job the helper ``helper`` holds, to query and end it, or None when it isn't there.""" - return self._api()[0].OpenJobObjectW(_job.JOB_OBJECT_QUERY | _job.JOB_OBJECT_TERMINATE, False, - _job.job_name(helper)) or None + return self._api().kernel32.OpenJobObjectW(_job.JOB_OBJECT_QUERY | _job.JOB_OBJECT_TERMINATE, False, + _job.job_name(helper)) or None def job_pids(self, job: int) -> list[int]: - kernel32 = self._api()[0] + kernel32 = self._api().kernel32 room = self.PIDS while True: listed = _pid_list(room)() @@ -197,25 +197,26 @@ def job_pids(self, job: int) -> list[int]: room = listed.NumberOfAssignedProcesses def terminate_job(self, job: int) -> None: - if not self._api()[0].TerminateJobObject(job, 1): + if not self._api().kernel32.TerminateJobObject(job, 1): raise ctypes.WinError(ctypes.get_last_error()) def close(self, handle: int) -> None: - self._api()[0].CloseHandle(handle) + self._api().kernel32.CloseHandle(handle) def suspend(self, pid: int) -> bool: """Whether the process ``pid`` was there to suspend, and was.""" return bool(self._on_process(pid, self.PROCESS_SUSPEND_RESUME, - lambda process: self._api()[3].NtSuspendProcess(process) == 0)) + lambda process: self._api().ntdll.NtSuspendProcess(process) == 0)) def resume(self, pid: int) -> None: - self._on_process(pid, self.PROCESS_SUSPEND_RESUME, lambda process: self._api()[3].NtResumeProcess(process)) + self._on_process(pid, self.PROCESS_SUSPEND_RESUME, lambda process: self._api().ntdll.NtResumeProcess(process)) def post_close(self, window: int) -> None: - self._api()[1].PostMessageW(window, WM_CLOSE, 0, 0) + self._api().user32.PostMessageW(window, WM_CLOSE, 0, 0) def windows(self) -> list[Window]: - _, user32, dwmapi, _ = self._api() + dlls = self._api() + user32, dwmapi = dlls.user32, dlls.dwmapi handles: list[int] = [] listing = ctypes.WINFUNCTYPE(ctypes.c_int, ctypes.c_void_p, ctypes.c_void_p)( lambda window, _: handles.append(window) or True) @@ -237,7 +238,7 @@ def _program(self, pid: int) -> str: """The file name of the program running as ``pid``, lowercased, or empty where it can't be read.""" def read(process: int) -> str: path, size = ctypes.create_unicode_buffer(self.PATH_CHARS), ctypes.c_uint32(self.PATH_CHARS) - if not self._api()[0].QueryFullProcessImageNameW(process, 0, path, ctypes.byref(size)): + if not self._api().kernel32.QueryFullProcessImageNameW(process, 0, path, ctypes.byref(size)): return "" return path.value.rpartition("\\")[2].lower() return self._on_process(pid, self.PROCESS_QUERY_LIMITED_INFORMATION, read) or "" @@ -245,7 +246,7 @@ def read(process: int) -> str: def _on_process(self, pid: int, access: int, act): """``act`` on a handle to the process ``pid`` opened for ``access``, closed after; None where it can't be opened, as for a process that has exited.""" - kernel32 = self._api()[0] + kernel32 = self._api().kernel32 process = kernel32.OpenProcess(access, False, pid) if not process: return None @@ -254,14 +255,9 @@ def _on_process(self, pid: int, access: int, act): finally: kernel32.CloseHandle(process) - def _api(self) -> tuple: - """``kernel32``, ``user32``, ``dwmapi`` and ``ntdll``, bound on first use, so this module imports anywhere.""" + def _api(self) -> _Dlls: + """The DLLs this class calls, bound on first use, so this module imports anywhere.""" if self._dlls is None: - kernel32 = _job.kernel32() - kernel32.OpenProcess.argtypes, kernel32.OpenProcess.restype = [ctypes.c_uint32, ctypes.c_int, - ctypes.c_uint32], ctypes.c_void_p - kernel32.QueryFullProcessImageNameW.argtypes = [ctypes.c_void_p, ctypes.c_uint32, ctypes.c_wchar_p, - ctypes.c_void_p] user32 = ctypes.WinDLL("user32", use_last_error=True) user32.EnumWindows.argtypes = [ctypes.c_void_p, ctypes.c_void_p] user32.GetWindowThreadProcessId.argtypes = [ctypes.c_void_p, ctypes.c_void_p] @@ -274,10 +270,20 @@ def _api(self) -> tuple: ctypes.c_uint32] ntdll = ctypes.WinDLL("ntdll") ntdll.NtSuspendProcess.argtypes = ntdll.NtResumeProcess.argtypes = [ctypes.c_void_p] - self._dlls = (kernel32, user32, dwmapi, ntdll) + self._dlls = _Dlls(_job.kernel32(), user32, dwmapi, ntdll) return self._dlls +class _Dlls(NamedTuple): + """The DLLs ``_Win32`` calls, each with the calls it makes typed: ``kernel32``'s in ``_job``, as the helper makes + some of them too.""" + + kernel32: ctypes.WinDLL + user32: ctypes.WinDLL + dwmapi: ctypes.WinDLL + ntdll: ctypes.WinDLL + + def _pid_list(room: int) -> type[ctypes.Structure]: """``JOBOBJECT_BASIC_PROCESS_ID_LIST`` with room for ``room`` process ids.""" class Listed(ctypes.Structure): diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/app.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/app.py index 31cf49da5..f4efe6fbc 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/app.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/app.py @@ -30,7 +30,6 @@ from .app_runtime import AppRuntime from .errors import InvalidArgument from .platform import detect -from .served import SOCKET as SOCKET #: The environment variable a computer delivers its apps' settings in: JSON of each app's values by its name. APP_SETTINGS_ENV = "AGENTENV_APP_SETTINGS" @@ -42,6 +41,10 @@ WINDOW_KEYS = frozenset({"class", "instance", "title"}) #: The framework extension an app's own server serves: its launch as params, and its ``launch`` and ``ready`` methods. COMPUTER_APP = "urn:agentenv:computer-app/v1" +#: Where an app's own server listens on Linux and macOS, in the app's folder. +SOCKET = Path(".agentenv/server.sock") +#: Where an app's server on Windows writes the port it serves on and its token, in the app's folder. +ADDRESS = Path(".agentenv/server.json") #: Written in an app's folder by its computer's driver once an agent acts there, by a tool call or on a route the app #: opens to agents: a fresh computer starts without it, and an app that resets removes its own. AGENT_ACTED = Path(".agentenv/agent-acted") diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/apps.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/apps.py index 657e8400c..437dd639c 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/apps.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/apps.py @@ -10,9 +10,8 @@ import asyncio import copy import json -import sys from datetime import datetime, timezone -from pathlib import Path +from pathlib import Path, PurePath, PurePosixPath, PureWindowsPath from typing import Optional import httpx @@ -22,10 +21,18 @@ from .app import AGENT_ACTED, COMPUTER_APP, FAILURE from .app_runtime import CHECK_TIMEOUT_S, LAUNCHES, AppReadiness, boot_launch_held from .operations import ReadyCheck +from .platform import detect from .served import served -#: Where a composed computer installs its apps, a folder each. -APPS = Path("C:/agentenv/apps" if sys.platform == "win32" else "/opt/agentenv/apps") + +def apps_folder(os_type: str) -> PurePath: + """Where a composed computer of ``os_type`` installs its apps, a folder each: what its computer finds them by, and + what composing one installs them under, whatever OS composes it.""" + return PureWindowsPath("C:/agentenv/apps") if os_type == "windows" else PurePosixPath("/opt/agentenv/apps") + + +#: Where this computer installs its apps. +APPS = Path(apps_folder(detect().os)) #: How long an app's server may take to answer, its checks run at once, before it counts as not answering. ANSWER_TIMEOUT_S = CHECK_TIMEOUT_S + 5 diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/served.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/served.py index bab1bb443..77467fe05 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/served.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/served.py @@ -1,9 +1,10 @@ -"""Where a computer app's own server answers, and how its computer reaches it (``serve_app``, ``apps``, ``svc``, -``launch``). On Linux and macOS it serves on the Unix socket ``SOCKET`` in the app's folder, which only the computer -reaches, so it takes no token. On Windows, whose asyncio serves no Unix socket, it serves on a free port of 127.0.0.1 -and writes that port, with a token it draws, to ``ADDRESS`` there, in a folder its computer keeps the session user's -own; it answers only a request carrying the token, so no other user of the computer gets in, and whatever reaches the -app reads both from that file.""" +"""How a computer app's own server is reached, over HTTP or a WebSocket, and how it serves (``serve_app``, ``apps``, +``svc``, ``launch``). On Linux and macOS it serves on the Unix socket ``SOCKET`` in the app's folder, which only the +computer reaches, so it takes no token. On Windows, whose asyncio serves no Unix socket, it serves on a free port of +127.0.0.1 and writes that port, with a token it draws, to ``ADDRESS`` there, in a folder its computer keeps the session +user's own; it answers only a request carrying the token, so no other user of the computer gets in, and whatever +reaches the app reads both from that file. Needs the ``app`` or ``computer`` extra; an app's own code imports none of +it.""" from __future__ import annotations import hmac @@ -17,11 +18,10 @@ from typing import Any, Awaitable, Callable, Generator, Optional import httpx +from websockets.asyncio.client import ClientConnection, connect, unix_connect + +from .app import ADDRESS, SOCKET -#: Where an app's own server listens on Linux and macOS, in the app's folder. -SOCKET = Path(".agentenv/server.sock") -#: Where an app's server on Windows writes the port it serves on and its token, in the app's folder. -ADDRESS = Path(".agentenv/server.json") #: The header a request to an app's server on loopback carries its token in. TOKEN_HEADER = "x-agentenv-app-token" #: Whether this OS's app servers serve on loopback rather than a Unix socket. @@ -33,7 +33,7 @@ @dataclass(frozen=True) class Served: """An app's server as its computer reaches it: on its Unix ``socket``, or on ``port`` of 127.0.0.1 with ``token``, - through no proxy the environment names.""" + through no proxy the environment names; over HTTP, or a WebSocket.""" socket: Optional[Path] = None port: Optional[int] = None @@ -45,6 +45,14 @@ def client(self, timeout: Optional[float]) -> httpx.AsyncClient: def sync_client(self, timeout: Optional[float]) -> httpx.Client: return httpx.Client(**self._client_args(httpx.HTTPTransport), timeout=timeout) + async def websocket(self, uri: str, headers: list[tuple[str, str]], **options: Any) -> ClientConnection: + """A WebSocket opened to ``uri`` on the app's server, sending ``headers``, and the token where it takes one, + with websockets' ``options``.""" + if self.socket is not None: + return await unix_connect(str(self.socket), uri, additional_headers=headers, **options) + return await connect(uri, host="127.0.0.1", port=self.port, proxy=None, + additional_headers=[*headers, (TOKEN_HEADER, self.token)], **options) + def _client_args(self, transport: type) -> dict[str, Any]: if self.socket is not None: return {"transport": transport(uds=str(self.socket)), "base_url": "http://app"} @@ -52,12 +60,12 @@ def _client_args(self, transport: type) -> dict[str, Any]: def served(folder: Path) -> Served: - """How the server of the app in ``folder`` is reached: on the port and with the token it wrote, where it serves on - loopback, else on its socket. Nothing answering either way is an ``OSError`` once it's asked.""" - try: - written = json.loads((folder / ADDRESS).read_text(encoding="utf-8")) - except FileNotFoundError: + """How the server of the app in ``folder`` is reached: on Windows, on the port and with the token it wrote there, + raising ``FileNotFoundError`` until it has; elsewhere on its socket. Nothing answering is an ``OSError`` either + way, once it's asked or here.""" + if not LOOPBACK: return Served(socket=folder / SOCKET) + written = json.loads((folder / ADDRESS).read_text(encoding="utf-8")) return Served(port=written["port"], token=written["token"]) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/svc.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/svc.py index 1873bcebe..1581e1acb 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/svc.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/svc.py @@ -18,7 +18,7 @@ from starlette.requests import Request from starlette.responses import Response, StreamingResponse from starlette.websockets import WebSocket, WebSocketDisconnect -from websockets.asyncio.client import ClientConnection, connect, unix_connect +from websockets.asyncio.client import ClientConnection from ..agent_env_environment import _error_response from .errors import DeliveryFailed @@ -119,14 +119,17 @@ async def forward(folder: Path, name: str, request: Request) -> Response: client's own, its body and its answer streamed; it takes as long as the app does.""" headers = to_app(request.headers.items(), request.headers.get("host", ""), request.url.scheme, f"/svc/{name}") has_body = request.headers.get("content-length", "0") != "0" or "transfer-encoding" in request.headers - http = served(folder).client(timeout=None) + try: + http = served(folder).client(timeout=None) + except OSError as e: + return _not_answering(name, e) http.headers.clear() try: answer = await http.send(http.build_request(request.method, target(request), headers=_bytes(headers), content=request.stream() if has_body else None), stream=True) except (httpx.HTTPError, OSError) as e: await http.aclose() - return _error_response(DeliveryFailed(f"app {name}'s server isn't answering: {type(e).__name__}: {e}")) + return _not_answering(name, e) except BaseException: await http.aclose() raise @@ -160,14 +163,10 @@ async def relay(folder: Path, name: str, websocket: WebSocket, opened: Optional[ websocket.headers.items(), host, "https" if websocket.url.scheme == "wss" else "http", f"/svc/{name}") if key.lower() != "host" and not key.lower().startswith("sec-websocket-")] offered = [p.strip() for p in websocket.headers.get("sec-websocket-protocol", "").split(",") if p.strip()] - reached, uri = served(folder), f"ws://{host or 'app'}{target(websocket)}" - options = {"subprotocols": offered or None, "max_size": None, "compression": None, "ping_interval": None, - "user_agent_header": None} try: - upstream = await ( - unix_connect(str(reached.socket), uri, additional_headers=headers, **options) if reached.socket else - connect(uri, host="127.0.0.1", port=reached.port, proxy=None, - additional_headers=[*headers, (TOKEN_HEADER, reached.token)], **options)) + upstream = await served(folder).websocket( + f"ws://{host or 'app'}{target(websocket)}", headers, subprotocols=offered or None, max_size=None, + compression=None, ping_interval=None, user_agent_header=None) except (OSError, ValueError, asyncio.TimeoutError, websockets.WebSocketException): await websocket.close(code=1011) return @@ -178,6 +177,10 @@ async def relay(folder: Path, name: str, websocket: WebSocket, opened: Optional[ await _both_ways(websocket, upstream) +def _not_answering(name: str, e: BaseException) -> Response: + return _error_response(DeliveryFailed(f"app {name}'s server isn't answering: {type(e).__name__}: {e}")) + + def _utf8(value: str) -> str: """A header value decoded as Latin-1 as the string ``websockets`` sends as the same bytes, which it encodes as UTF-8; bytes that aren't UTF-8 become replacement characters.""" diff --git a/packages/agentenv-protocol/tests/test_computer_app_server.py b/packages/agentenv-protocol/tests/test_computer_app_server.py index 672e6642d..bf97a2e5e 100644 --- a/packages/agentenv-protocol/tests/test_computer_app_server.py +++ b/packages/agentenv-protocol/tests/test_computer_app_server.py @@ -1,7 +1,8 @@ """A computer app's own server: it adds the app's launcher, launches a boot app once per boot and says whether the app is ready (``computer-app/v1``); its computer's driver finds it on the socket in the app's folder and asks it, lists it as a child environment and forwards its requests to it, only with the computer's control token when it has one, and -leaves the paths it owns out of its own data/get.""" +leaves the paths it owns out of its own data/get. On Windows one that wrote no address isn't answering, or says why it +failed to start.""" from __future__ import annotations import asyncio @@ -27,6 +28,7 @@ import httpx # noqa: E402 import agentenv_protocol.computer.launch as launcher # noqa: E402 +import agentenv_protocol.computer.served as transports # noqa: E402 from agentenv_protocol import client # noqa: E402 from agentenv_protocol.computer import (ComputerAppEnvironment, Launch, ReadyCheck, Ready, linux, # noqa: E402 ready_check) @@ -243,6 +245,18 @@ async def missing(argv, cwd, env): assert not (tmp_path / "launched").exists() +@pytest.mark.asyncio +async def test_on_windows_an_app_whose_server_wrote_no_address_isnt_answering_or_failed_to_start(tmp_path, monkeypatch): + monkeypatch.setattr(transports, "LOOPBACK", True) + (tmp_path / "gone").mkdir() + (tmp_path / "broken" / FAILURE).parent.mkdir(parents=True) + (tmp_path / "broken" / FAILURE).write_text("RuntimeError: no mailbox") + + assert [await apps.check(tmp_path / name) for name in ("broken", "gone")] == [ + ReadyCheck("app broken", False, "its server failed to start: RuntimeError: no mailbox"), + ReadyCheck("app gone", False, "its server isn't answering yet")] + + @pytest.mark.asyncio async def test_the_driver_asks_each_apps_server_on_the_socket_in_its_folder(desktop, monkeypatch): shown, launched = desktop diff --git a/packages/agentenv-protocol/tests/test_computer_declare.py b/packages/agentenv-protocol/tests/test_computer_declare.py index 2abfc737a..6edc7afc5 100644 --- a/packages/agentenv-protocol/tests/test_computer_declare.py +++ b/packages/agentenv-protocol/tests/test_computer_declare.py @@ -376,7 +376,7 @@ def test_an_apps_code_needs_only_the_plain_package(): import importlib.abc, sys class Blocked(importlib.abc.MetaPathFinder): def find_spec(self, name, path, target=None): - if name.split(".")[0] in ("mcp", "av", "PIL", "uvicorn"): + if name.split(".")[0] in ("mcp", "av", "PIL", "uvicorn", "websockets"): raise ImportError(name) sys.meta_path.insert(0, Blocked()) from agentenv_protocol.computer import ComputerAppEnvironment, Linux, computer_app diff --git a/packages/agentenv-protocol/tests/test_computer_serve.py b/packages/agentenv-protocol/tests/test_computer_serve.py index 0c87aecc2..67b8a652e 100644 --- a/packages/agentenv-protocol/tests/test_computer_serve.py +++ b/packages/agentenv-protocol/tests/test_computer_serve.py @@ -15,9 +15,8 @@ from agentenv_protocol import CONTROL_TOKEN_ENV # noqa: E402 from agentenv_protocol.computer import ComputerDriverEnvironment, run_install_step, serve_app # noqa: E402 -from agentenv_protocol.computer.app import BUILD_SETTINGS, FAILURE, SOCKET # noqa: E402 +from agentenv_protocol.computer.app import ADDRESS, BUILD_SETTINGS, FAILURE, SOCKET # noqa: E402 from agentenv_protocol.computer.app_runtime import AppRuntime # noqa: E402 -from agentenv_protocol.computer.served import ADDRESS # noqa: E402 from agentenv_protocol.computer.serve import USAGE, main # noqa: E402 DRIVER = '''from desk_helpers import SIZE diff --git a/packages/agentenv-protocol/tests/test_computer_served.py b/packages/agentenv-protocol/tests/test_computer_served.py index 6942f69fd..15d3fde01 100644 --- a/packages/agentenv-protocol/tests/test_computer_served.py +++ b/packages/agentenv-protocol/tests/test_computer_served.py @@ -1,5 +1,5 @@ -"""Where an app's own server answers and how its computer reaches it: on its folder's Unix socket unless it wrote a -loopback port and token there, as it does on Windows. On loopback it answers only a request or WebSocket carrying its +"""Where an app's own server answers and how its computer reaches it: on its folder's Unix socket, or on Windows on +the loopback port and token it wrote there, nothing answering till it has. On loopback it answers only a request or WebSocket carrying its token, once, which it takes out before the app sees the request, and a client reaches it through no proxy the environment names.""" from __future__ import annotations @@ -22,7 +22,9 @@ from websockets.asyncio.client import connect # noqa: E402 from websockets.exceptions import InvalidStatus # noqa: E402 -from agentenv_protocol.computer.served import ADDRESS, SOCKET, TOKEN_HEADER, Served, bind, guarded, served # noqa: E402 +import agentenv_protocol.computer.served as transports # noqa: E402 +from agentenv_protocol.computer.app import ADDRESS, SOCKET # noqa: E402 +from agentenv_protocol.computer.served import TOKEN_HEADER, Served, bind, guarded, served # noqa: E402 async def _headers(request: Request) -> JSONResponse: @@ -52,12 +54,20 @@ async def _serving(folder: Path): await serving -def test_an_app_that_wrote_no_loopback_address_is_reached_on_its_socket(tmp_path): - assert served(tmp_path) == Served(socket=tmp_path / SOCKET) +def test_an_app_is_reached_on_its_socket_but_on_windows_none_answers_till_its_server_wrote_its_address(tmp_path, + monkeypatch): + monkeypatch.setattr(transports, "LOOPBACK", False) + on_its_socket = served(tmp_path) + monkeypatch.setattr(transports, "LOOPBACK", True) + + with pytest.raises(FileNotFoundError): + served(tmp_path) + assert on_its_socket == Served(socket=tmp_path / SOCKET) @pytest.mark.asyncio async def test_an_app_on_loopback_answers_its_token_alone_and_the_app_never_sees_it(tmp_path, monkeypatch): + monkeypatch.setattr(transports, "LOOPBACK", True) monkeypatch.setenv("HTTP_PROXY", "http://127.0.0.1:9") monkeypatch.setenv("ALL_PROXY", "http://127.0.0.1:9") async with _serving(tmp_path) as token: diff --git a/packages/agentenv-protocol/tests/test_computer_svc_forward.py b/packages/agentenv-protocol/tests/test_computer_svc_forward.py index 4f1969880..c99666c6e 100644 --- a/packages/agentenv-protocol/tests/test_computer_svc_forward.py +++ b/packages/agentenv-protocol/tests/test_computer_svc_forward.py @@ -37,6 +37,7 @@ from agentenv_protocol import CONTROL_TOKEN_ENV, client # noqa: E402 from agentenv_protocol.computer import ComputerAppEnvironment, apps, linux, svc # noqa: E402 from agentenv_protocol.computer.app import AGENT_ACTED, SOCKET # noqa: E402 +import agentenv_protocol.computer.served as transports # noqa: E402 from agentenv_protocol.computer.served import TOKEN_HEADER, bind, guarded # noqa: E402 from agentenv_protocol.tool_context import EMPTY # noqa: E402 @@ -124,6 +125,7 @@ async def _computer(monkeypatch, transport: str): folder = Path(root) / "echo" (folder / SOCKET).parent.mkdir(parents=True) monkeypatch.setattr(apps, "APPS", Path(root)) + monkeypatch.setattr(transports, "LOOPBACK", transport == "loopback") monkeypatch.setenv("ENVIRONMENT_NAME", "echo") app = Echo() asgi = app.create_app().streamable_http_app() diff --git a/src/agent_env/env/envs/computer/utils/composer.py b/src/agent_env/env/envs/computer/utils/composer.py index 3d8bc0d6f..9241b6141 100644 --- a/src/agent_env/env/envs/computer/utils/composer.py +++ b/src/agent_env/env/envs/computer/utils/composer.py @@ -29,7 +29,7 @@ from collections.abc import Callable, Iterator from typing import TYPE_CHECKING, Any, Literal -from agentenv_protocol.computer import apps as installed_apps +from agentenv_protocol.computer.apps import apps_folder from agentenv_protocol.computer.app import BUILD_SETTINGS, SOCKET from agent_env.artifact.artifacts.computer import LOCAL_IMAGE_PREFIX, ComputerArtifact @@ -73,9 +73,9 @@ #: holds some other way, its labels or how it's built, and leave it for any other, so images aren't built again for #: nothing. FORMAT = 1 -#: Where a driver's files go in a composed computer, in a folder named for the driver; an app's, under APPS. +#: Where a driver's files go in a composed computer, in a folder named for the driver; an app's go under its OS's apps +#: folder (``apps_folder``). DRIVERS = "/opt/agentenv/drivers" -APPS = str(installed_apps.APPS) KEY_LABEL = "dev.agentenv.computer-key" # What a build installed and whether it was emulated, kept on its image for an env that reuses it. INSTALLED_LABEL, EMULATED_LABEL = "dev.agentenv.installed", "dev.agentenv.emulated" @@ -774,12 +774,13 @@ def _stage_app(context: Path, app: ComputerAppEnv, base: ComputerArtifact, from_store: dict[str, tuple[str, str]]) -> _Layer: """Write the app's install files under ``context/apps//``, with the values of its build settings the env fixes, and its supervisord programs beside them, run under its name: its services and its own server, which serves - its class from its venv and launches the app. Its folder under ``APPS`` is named for its environment name.""" + its class from its venv and launches the app. Its folder under its OS's apps folder is named for its environment + name.""" install, name = app.install[base.os.type], gate.app_folder(app) file, _, cls = app.module.partition(":") served = shlex.quote(f"{PurePosixPath(file).relative_to(install.files)}:{cls}") - layer = _Layer(f"apps/{name}", f"{APPS}/{name}", install, f"agentenv-app-{name}.conf", app.id, app=True, - served=served, + layer = _Layer(f"apps/{name}", str(apps_folder(base.os.type) / name), install, f"agentenv-app-{name}.conf", app.id, + app=True, served=served, steps=tuple((step.name, step.scope) for step in app.declaration.install_steps if step.os is None or base.os.type in step.os)) programs = dict(zip(gate.programs(app, base.os.type), [ diff --git a/src/agent_env/env/envs/computer/utils/gate.py b/src/agent_env/env/envs/computer/utils/gate.py index 1ddbb3f5e..5018d4b85 100644 --- a/src/agent_env/env/envs/computer/utils/gate.py +++ b/src/agent_env/env/envs/computer/utils/gate.py @@ -9,7 +9,7 @@ from pathlib import PurePosixPath from typing import TYPE_CHECKING, Any -from agentenv_protocol.computer.apps import APPS +from agentenv_protocol.computer.apps import apps_folder from agentenv_protocol.computer.platform import Platform, supported from jsonschema import Draft202012Validator @@ -87,8 +87,8 @@ def folder_name(name: str, fallback: str) -> str: def app_folder(app: ComputerAppEnv) -> str: - """The name of the folder ``app`` is installed in, under ``APPS``, and of its programs: its environment name's, the - one name a computer knows it by.""" + """The name of the folder ``app`` is installed in, under its computer's apps folder (``apps_folder``), and of its + programs: its environment name's, the one name a computer knows it by.""" return folder_name(app.environment_name, "app") @@ -107,7 +107,7 @@ def _apps(base: ComputerArtifact, driver: ComputerDriverEnv, apps: list[Computer problems += [f"apps: {app.id} is named {environment_name!r}, as the computer env is, which names the computer's " "own files" for app in distinct if app.environment_name == environment_name] for kind, keys in (("environment name", lambda app: [app.environment_name]), - ("folder", lambda app: [f"{APPS}/{app_folder(app)}"]), + ("folder", lambda app: [str(apps_folder(base.os.type) / app_folder(app))]), ("program", lambda app: programs(app, base.os.type)), ("port", lambda app: _ports(app, base.os.type))): claims: dict[object, list[str]] = {} diff --git a/src/agent_env/env/envs/computer/utils/windows_disk.py b/src/agent_env/env/envs/computer/utils/windows_disk.py index 652ea7f0a..82b2c8f84 100644 --- a/src/agent_env/env/envs/computer/utils/windows_disk.py +++ b/src/agent_env/env/envs/computer/utils/windows_disk.py @@ -28,6 +28,8 @@ from pathlib import Path, PurePosixPath, PureWindowsPath from typing import Any, NamedTuple +from agentenv_protocol.computer.apps import apps_folder + from agent_env.artifact.artifacts.computer import DISK_BASE_FILE, DISK_FILE, DISK_OWNER from agent_env.artifact.artifacts.docker_image import docker_login, push_local_image from agent_env.config.paths import cache_root @@ -48,7 +50,7 @@ ADMIN = "agentadmin" #: Where agent-env's own files are on a Windows computer, and each layer's folder under them. ROOT = PureWindowsPath("C:/agentenv") -DRIVERS, APPS = ROOT / "drivers", ROOT / "apps" +DRIVERS, APPS = ROOT / "drivers", apps_folder("windows") PYTHON = ROOT / "python" / "python.exe" BUILD = ROOT / "build" #: The fewest days of its evaluation a base may have left, as a deploy needs some. From 71695ab97b02cb9ac00cdb2aec4eaefbf671f563 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sun, 8 Nov 2026 06:21:29 -0800 Subject: [PATCH 9/9] fix(computer): a Windows app's stop waits for each process it ended to have exited Its job's list of processes says only that one is no longer in the job; its own handle says it has exited, so none still writes once a stop returns and a reset puts the app's files back. Once in about 27 windowless stops on a real Windows computer, a file still grew after the stop returned. Co-Authored-By: Claude Opus 5.5 --- .../src/agentenv_protocol/computer/_job.py | 2 + .../computer/_session_windows.py | 40 ++++++++++++++----- .../tests/test_computer_session_windows.py | 25 ++++++++---- 3 files changed, 50 insertions(+), 17 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/_job.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/_job.py index 07996b76a..546fd1a4c 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/_job.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/_job.py @@ -67,6 +67,8 @@ def kernel32() -> ctypes.WinDLL: dll.CloseHandle.argtypes = [handle] dll.OpenProcess.argtypes, dll.OpenProcess.restype = [dword, ctypes.c_int, dword], handle dll.QueryFullProcessImageNameW.argtypes = [handle, dword, wide, ctypes.c_void_p] + dll.WaitForMultipleObjects.argtypes, dll.WaitForMultipleObjects.restype = [dword, ctypes.c_void_p, ctypes.c_int, + dword], dword return dll diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py index ef27cd542..f3c786a6c 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/_session_windows.py @@ -29,8 +29,8 @@ START_TIMEOUT_S = 30.0 #: How often a stopping app is looked at for having ended. POLL_S = 0.2 -#: How long a job ended by force is waited on to hold no process, so whatever its app had open is closed once a stop -#: returns, as a reset then puts the app's files back. +#: How long a job ended by force is waited on for each of its processes to have exited, so none still writes once a +#: stop returns and whatever they had open is closed, as a reset then puts the app's files back. ENDED_TIMEOUT_S = 5.0 WM_CLOSE = 0x0010 #: A Start Menu shortcut, from its path, program, arguments and folder in the environment, as PowerShell writes one. @@ -72,8 +72,8 @@ async def launch(argv: list[str], cwd: Path, env: dict[str, str], fds: Optional[ async def stop(pid: int, timeout_s: float) -> None: """End the job the helper ``pid`` holds, every process in it: its windows asked to close, then the job ended after - ``timeout_s``, or at once when it has no window to close, and waited on until it holds none. No one asks how it - exited once it's stopped.""" + ``timeout_s``, or at once when it has no window to close, and waited on until each process it held has exited and + it holds none. No one asks how it exited once it's stopped.""" _reaping.forget(pid) job = _win32.open_job(pid) if job is None: @@ -86,10 +86,16 @@ async def stop(pid: int, timeout_s: float) -> None: while _app_pids(job, pid) and time.monotonic() < deadline: await asyncio.sleep(POLL_S) if _app_pids(job, pid): - _win32.terminate_job(job) - deadline = time.monotonic() + ENDED_TIMEOUT_S - while _win32.job_pids(job) and time.monotonic() < deadline: - await asyncio.sleep(POLL_S) + ending = _win32.open_processes(_win32.job_pids(job)) + try: + _win32.terminate_job(job) + deadline = time.monotonic() + ENDED_TIMEOUT_S + await asyncio.to_thread(_win32.wait_exited, ending, ENDED_TIMEOUT_S) + while _win32.job_pids(job) and time.monotonic() < deadline: + await asyncio.sleep(POLL_S) + finally: + for process in ending: + _win32.close(process) finally: _win32.close(job) @@ -169,7 +175,9 @@ class Window: class _Win32: """The Win32 calls this module makes, each a method, so its logic is tested apart from them.""" - PROCESS_QUERY_LIMITED_INFORMATION, PROCESS_SUSPEND_RESUME = 0x1000, 0x0800 + PROCESS_QUERY_LIMITED_INFORMATION, PROCESS_SUSPEND_RESUME, SYNCHRONIZE = 0x1000, 0x0800, 0x00100000 + #: The most handles one wait takes (``MAXIMUM_WAIT_OBJECTS``). + WAIT_HANDLES = 64 DWMWA_CLOAKED = 14 #: How many process ids a job's list is read with room for, before it's read again with room for all. PIDS = 64 @@ -203,6 +211,20 @@ def terminate_job(self, job: int) -> None: def close(self, handle: int) -> None: self._api().kernel32.CloseHandle(handle) + def open_processes(self, pids: list[int]) -> list[int]: + """Handles to wait on each process of ``pids`` that's there; one that's gone has none.""" + kernel32 = self._api().kernel32 + return [process for pid in pids if (process := kernel32.OpenProcess(self.SYNCHRONIZE, False, pid))] + + def wait_exited(self, processes: list[int], timeout_s: float) -> None: + """Wait until each of ``processes``, handles, has exited, every thread of it ended, or ``timeout_s`` passes: a + process's own handle says it has, where its job's list says only that it's no longer in the job.""" + kernel32, deadline = self._api().kernel32, time.monotonic() + timeout_s + for first in range(0, len(processes), self.WAIT_HANDLES): + some = processes[first:first + self.WAIT_HANDLES] + kernel32.WaitForMultipleObjects(len(some), (ctypes.c_void_p * len(some))(*some), True, + max(0, int((deadline - time.monotonic()) * 1000))) + def suspend(self, pid: int) -> bool: """Whether the process ``pid`` was there to suspend, and was.""" return bool(self._on_process(pid, self.PROCESS_SUSPEND_RESUME, diff --git a/packages/agentenv-protocol/tests/test_computer_session_windows.py b/packages/agentenv-protocol/tests/test_computer_session_windows.py index d13e21dbd..56e8a8ebb 100644 --- a/packages/agentenv-protocol/tests/test_computer_session_windows.py +++ b/packages/agentenv-protocol/tests/test_computer_session_windows.py @@ -1,10 +1,10 @@ """The Windows session's own logic, its Win32 calls faked and its job helper stood in for: a launch goes through the helper and returns its pid once the app has started, or fails saying why it couldn't, and hands no fds; stopping asks -the app's windows to close, then ends the job after the timeout, or at once with no window to ask, and waits until it -holds no process; pausing suspends each of the app's processes but the helper's, and any one starts as they're -suspended, and resumes them, even when the block raises; a job that's gone is neither alive, stopped nor paused; the -windows listed are those shown, by program, class and title; and the menu launcher is a Start Menu shortcut PowerShell -writes, named for the app.""" +the app's windows to close, then ends the job after the timeout, or at once with no window to ask, and waits until +each process it held has exited and it holds none; pausing suspends each of the app's processes but the helper's, and +any one starts as they're suspended, and resumes them, even when the block raises; a job that's gone is neither alive, +stopped nor paused; the windows listed are those shown, by program, class and title; and the menu launcher is a Start +Menu shortcut PowerShell writes, named for the app.""" from __future__ import annotations import subprocess @@ -39,7 +39,7 @@ def __init__(self, jobs: dict[int, list[int]], windows: list[Window], closes: bo spawns: dict[int, int] | None = None, lingers: int = 0) -> None: self.jobs, self._windows, self.closes, self.spawns, self.lingers = jobs, windows, closes, spawns or {}, lingers self.ending: dict[int, int] = {} - self.posted, self.terminated, self.suspended, self.resumed, self.open = [], [], [], [], 0 + self.posted, self.terminated, self.suspended, self.resumed, self.waited, self.open = [], [], [], [], [], 0 def open_job(self, helper): if helper not in self.jobs: @@ -54,6 +54,13 @@ def job_pids(self, job): self.jobs[job] = [] return list(self.jobs[job]) + def open_processes(self, pids): + self.open += len(pids) + return list(pids) + + def wait_exited(self, processes, timeout_s): + self.waited.append(list(processes)) + def terminate_job(self, job): self.terminated.append(job) self.ending[job] = self.lingers @@ -104,8 +111,9 @@ async def test_stopping_asks_the_apps_windows_to_close_and_ends_the_job_only_if_ started = time.monotonic() await _session_windows.stop(HELPER, timeout_s=0.2) - assert obliging.posted == [1, 3] and obliging.terminated == [] and obliging.open == 0 + assert obliging.posted == [1, 3] and obliging.terminated == obliging.waited == [] and obliging.open == 0 assert stubborn.posted == [1] and stubborn.terminated == [HELPER] and time.monotonic() - started >= 0.2 + assert stubborn.waited == [[HELPER, 901]] and stubborn.open == 0 assert stubborn.jobs[HELPER] == [] and not _session_windows.alive(HELPER) @@ -117,7 +125,8 @@ async def test_an_app_with_no_window_to_ask_is_ended_at_once_and_a_gone_job_is_l gone = win32({}, []) await _session_windows.stop(HELPER, timeout_s=10) - assert windowless.terminated == [HELPER] and time.monotonic() - started < 1 + assert windowless.terminated == [HELPER] and windowless.waited == [[HELPER, 901]] and windowless.open == 0 + assert time.monotonic() - started < 1 assert gone.terminated == [] and gone.open == 0 and not _session_windows.alive(HELPER)