From 073596e996170942105c63dc4580f40ee1b9b3c1 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sat, 7 Nov 2026 23:06:06 -0800 Subject: [PATCH 01/20] 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 02/20] 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 03/20] 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 04/20] 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 cc397e3d727b241be92083503daebcc835559a46 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sat, 7 Nov 2026 23:34:34 -0800 Subject: [PATCH 05/20] feat(computer): compose apps onto a Windows computer Co-Authored-By: Claude Opus 5.5 --- src/agent_env/computers/README.md | 10 +- .../env/envs/computer/utils/composer.py | 57 +++++++---- src/agent_env/env/envs/computer/utils/gate.py | 8 +- .../envs/computer/utils/macos_vm_bundle.py | 3 +- .../env/envs/computer/utils/windows_disk.py | 33 +++++-- .../artifacts/check_windows_notes/verify.py | 63 +++++++++++++ .../computer/app/envs/notes/app.py | 29 ++++-- .../computer/app/envs/notes/setup.ps1 | 4 + .../computer/app/envs/windows-desk/env.toml | 4 + .../computer/app/tasks/windows.json | 9 ++ tst/integration/computer/windows_test.py | 19 +++- tst/unit/env/envs/test_computer_windows.py | 94 +++++++++++++++++-- 12 files changed, 284 insertions(+), 49 deletions(-) create mode 100644 tst/integration/computer/app/artifacts/check_windows_notes/verify.py create mode 100644 tst/integration/computer/app/envs/notes/setup.ps1 create mode 100644 tst/integration/computer/app/envs/windows-desk/env.toml create mode 100644 tst/integration/computer/app/tasks/windows.json diff --git a/src/agent_env/computers/README.md b/src/agent_env/computers/README.md index ce2575906..ab6851804 100644 --- a/src/agent_env/computers/README.md +++ b/src/agent_env/computers/README.md @@ -164,8 +164,9 @@ link serves then. Name it as `windows-11`, or by its id, `@local/agentenv-framew A Windows computer env is composed on the same machine (`env/envs/computer/utils/windows_disk.py`): the base booted on an overlay kept in a folder of its own, each layer installed over ssh as `agentadmin` by a PowerShell script composing -writes, as its `[install.windows]` says (its files under `C:\agentenv\drivers\`, its downloads checked by -sha256, its venv on the pinned Python, its PowerShell run scripts, elevated, and its services), then shut down and +writes, as its `[install.windows]` says (its files under `C:\agentenv\drivers\`, or an app's under +`C:\agentenv\apps\`, its downloads checked by sha256, its venv on the pinned Python, its PowerShell run scripts, +elevated, an app's install steps, elevated too, and its services), then shut down and packed onto the base's image, so every computer composed on a base shares one copy of it, and pushed to the env's image store under its key, pinned, as a Linux disk is; a compose of the same inputs on any machine reuses it, and a deploy pulls it. Gate 3 probes it at full. At the session user's sign-in, @@ -175,7 +176,10 @@ media alone, and starts each layer's services in that session, again whenever on with 4 vCPUs and 8 GB, on local Docker with KVM and on `modal_vm`; it has computer-exec and data/add, through the protocol's Windows defaults, so the probe runs its fixture there as on Linux, with Python one-liners for the commands it would give a shell. On `modal_vm` it runs in your own Modal workspace, under the evaluation's terms or a licence of your -own; whether they allow it there is yours to check. A Windows computer composes its driver alone for now, no app. +own; whether they allow it there is yours to check. An app's own server runs in the session as its services do, on a +loopback port it writes with a token to its `.agentenv` folder, which only the session user, SYSTEM and Administrators +reach; it launches the app in a Job object, which ends whatever the app started. Composing signs in as `agentadmin`, so +an app's install step for the session user can't run on Windows, and gate 1 refuses an app that declares one there. This bundle has no tasks of its own: other bundles pull its computers by alias, and `agent-env run computers` has nothing to run. diff --git a/src/agent_env/env/envs/computer/utils/composer.py b/src/agent_env/env/envs/computer/utils/composer.py index 3d8bc0d6f..24c42451d 100644 --- a/src/agent_env/env/envs/computer/utils/composer.py +++ b/src/agent_env/env/envs/computer/utils/composer.py @@ -25,7 +25,7 @@ import urllib.parse from concurrent.futures import Future, ThreadPoolExecutor, as_completed from dataclasses import dataclass, replace -from pathlib import Path, PurePosixPath +from pathlib import Path, PurePosixPath, PureWindowsPath from collections.abc import Callable, Iterator from typing import TYPE_CHECKING, Any, Literal @@ -313,7 +313,7 @@ def _composed_vm_bundle(env: ComputerEnv, base: ComputerArtifact, driver: Comput parts = [_part(layer, _services(f"driver-{gate.folder_name(driver.id, 'driver')}", layer.install), {"MCP_PORT": driver.port}, protocol, False)] parts += [_part(staged, dict(zip(gate.programs(app, base.os.type), [ - f"venv/bin/python -m agentenv_protocol.computer.serve_app {staged.served}", + f"venv/bin/python -m agentenv_protocol.computer.serve_app {shlex.quote(staged.served)}", *(service.command for service in staged.install.services)])), {"ENVIRONMENT_NAME": app.environment_name}, protocol, True) for app, staged in apps] if (lock := _vm_bundle_lock(env, base, link, parts, context, arch, progress)) is not None: @@ -357,9 +357,9 @@ def _composed_windows_disk(env: ComputerEnv, base: ComputerArtifact, driver: Com provider: SandboxProvider, progress: _Progress) -> dict: """The Windows disk of ``arch``: one of its key the env's image store holds, reused; else composed with this machine's Docker and KVM (``windows_disk``), on its base, this machine's, the store's or installed from Microsoft's - media, the driver installed over ssh as a layer on it, packed and pushed to the store under its key, as Linux disks - are. Then probed at full (gate 3). All of it holds a lock of its key, which keeps two composes of one key on this - machine from breaking each other: the other waits, then reuses it.""" + media, the driver and each app installed over ssh as a layer on it, packed and pushed to the store under its key, + as Linux disks are. Then probed at full (gate 3). All of it holds a lock of its key, which keeps two composes of one + key on this machine from breaking each other: the other waits, then reuses it.""" pair = f"disk/{arch}" with (_attempting(env, "disk", arch) as attempt, tempfile.TemporaryDirectory(prefix="agentenv-compose-") as work): @@ -367,19 +367,22 @@ def _composed_windows_disk(env: ComputerEnv, base: ComputerArtifact, driver: Com raise builder.Unbuildable(f"no link of {' or '.join(type(link).__name__ for link in provider.links)} boots " f"windows/{arch} disks, so it can't be composed here: compose it on a Linux machine " "with KVM, with the local sandbox provider") - if env.composed_apps(): - raise builder.Unbuildable("a Windows computer composes its driver alone for now, and no app") build = Path(work) / "build" context = build / "context" context.mkdir(parents=True) protocol = _stage_protocol(context) - layer = _stage_driver(context, driver, base, {}) - prefix = windows_disk.DRIVERS / gate.folder_name(driver.id, "driver") - services = _services(f"driver-{gate.folder_name(driver.id, 'driver')}", layer.install) - part = windows_disk.Part(layer.folder, prefix, layer.install, - {name: windows_disk.argv(command, prefix) for name, command in services.items()}, - {"MCP_PORT": driver.port}, - (f"{windows_disk.BUILD}\\context\\protocol",) if protocol else ()) + layer, name = _stage_driver(context, driver, base, {}), gate.folder_name(driver.id, "driver") + prefix = windows_disk.DRIVERS / name + parts = [_windows_part(layer, prefix, {program: windows_disk.argv(command, prefix) for program, command in + _services(f"driver-{name}", layer.install).items()}, + {"MCP_PORT": driver.port}, protocol)] + for app in env.composed_apps(): + staged, prefix = _stage_app(context, app, base, {}), windows_disk.APPS / gate.app_folder(app) + server = [str(prefix / "venv" / "Scripts" / "python.exe"), "-m", "agentenv_protocol.computer.serve_app", + staged.served] + commands = [server, *(windows_disk.argv(service.command, prefix) for service in staged.install.services)] + parts.append(_windows_part(staged, prefix, dict(zip(gate.programs(app, base.os.type), commands)), + {"ENVIRONMENT_NAME": app.environment_name}, protocol)) values = env.computer_values() settings = {name: values.get(name, setting.default) for name, setting in base.config.items() if setting.phase == "build"} @@ -393,7 +396,8 @@ def say(line: str) -> None: made = windows_disk.base(_key(recipe=_digest(windows_disk.RECIPE), disk_gb=disk_gb, user=user, form="windows-base", format=FORMAT), lambda: windows_disk.media(say), disk_gb, user, say, registry) - script = windows_disk.write(build, [part], settings, {"base": made.image, "layers": [part.folder]}) + script = windows_disk.write(build, parts, user, settings, + {"base": made.image, "layers": [part.folder for part in parts]}) expires = made.expires.isoformat(timespec="seconds") key = attempt.key = _key(base=made.image, base_expires=expires, provision=script, context=_digest(context), build_settings=settings, form="disk", arch=arch, format=FORMAT) @@ -494,6 +498,18 @@ def _part(layer: _Layer, programs: dict[str, str], environment: dict[str, Any], environment, _venv(layer), spec if _venv(layer) else None, layer.served, layer.steps) +def _windows_part(layer: _Layer, prefix: PureWindowsPath, services: dict[str, list[str]], + environment: dict[str, Any], protocol: bool) -> windows_disk.Part: + """``layer`` as a Windows disk installs it under ``prefix``: its ``services``' argv by name, with ``environment``, + and a venv's protocol as on Linux: this checkout's source, else an app's pinned to this release, which a driver's + requirements name themselves.""" + extra = "[app]" if layer.app else "" + spec = (f"{windows_disk.BUILD}\\context\\protocol{extra}" if protocol else + f"{_PROTOCOL}{extra}=={importlib.metadata.version(_PROTOCOL)}" if layer.app else None) + return windows_disk.Part(layer.folder, prefix, layer.install, services, environment, (spec,) if spec else (), + layer.served, tuple(step for step, _ in layer.steps)) + + def _probed(env: ComputerEnv, driver: ComputerDriverEnv, form: str, arch: str, result: dict, sandbox_provider: SandboxProvider, progress: _Progress) -> dict: """Gate 3: the build of ``result`` booted on the first link of ``sandbox_provider`` that runs ``arch``'s ``form`` @@ -745,8 +761,9 @@ def _base(base: ComputerArtifact, arch: str) -> tuple[str, str]: @dataclass(frozen=True) class _Layer: """A driver's or an app's part of a build: its folder in the build context, its prefix in the image, what it - installs, the file of its supervisord programs, and the id of its env. An app's venv also has the protocol's ``app`` extra, for the - app's own server, which listens in a folder of the app's the session user owns.""" + installs, the file of its supervisord programs, and the id of its env. An app's venv also has the protocol's ``app`` + extra, for the app's own server, which listens in a folder of the app's the session user owns; ``served`` is the + ``:`` it serves, and ``steps`` its install steps, by name and scope.""" folder: str prefix: str @@ -777,13 +794,13 @@ def _stage_app(context: Path, app: ComputerAppEnv, base: ComputerArtifact, its class from its venv and launches the app. Its folder under ``APPS`` 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}") + served = 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, 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), [ - f"venv/bin/python -m agentenv_protocol.computer.serve_app {served}", + f"venv/bin/python -m agentenv_protocol.computer.serve_app {shlex.quote(served)}", *(service.command for service in install.services)])) _stage(context, layer, f"app {app.id}", app.files, programs, {"ENVIRONMENT_NAME": app.environment_name}, from_store) @@ -914,7 +931,7 @@ def _runs(layer: _Layer) -> list[tuple[str, str]]: a build that write outside the layer's folder.""" return [*((run.scope, f"cd {layer.prefix} && {shlex.quote('./' + run.script)}") for run in layer.install.run or []), *((scope, f"cd {layer.prefix} && venv/bin/python -m agentenv_protocol.computer.run_install_step " - f"{layer.served} {step}") for step, scope in layer.steps)] + f"{shlex.quote(layer.served)} {step}") for step, scope in layer.steps)] def _as(scope: str, user: str, run: str) -> list[str]: diff --git a/src/agent_env/env/envs/computer/utils/gate.py b/src/agent_env/env/envs/computer/utils/gate.py index 1ddbb3f5e..7ded204e9 100644 --- a/src/agent_env/env/envs/computer/utils/gate.py +++ b/src/agent_env/env/envs/computer/utils/gate.py @@ -66,7 +66,8 @@ def arches(base: ComputerArtifact, driver: ComputerDriverEnv, apps: Sequence[Com def check_app(base: ComputerArtifact, driver: ComputerDriverEnv, app: ComputerAppEnv, at: str = "app") -> list[str]: """Every way ``app`` doesn't fit a composition of ``base`` and ``driver``, each named from ``at``: a platform it - doesn't support, no architecture in common, no install for the base's OS, or a port the driver listens on too.""" + doesn't support, no architecture in common, no install for the base's OS, a port the driver listens on too, or on + Windows an install step for the session user, as a Windows computer is composed over ssh as its admin.""" os = base.os if not _matching(base, app.declaration.supports): named = ", ".join(_shown(platform) for entry in app.declaration.supports for platform in supported(entry)) @@ -78,6 +79,11 @@ def check_app(base: ComputerArtifact, driver: ComputerDriverEnv, app: ComputerAp problems.append(f"{at}: {app.id} declares no install for {os.type}") elif taken := sorted(set(_ports(app, os.type)) & set(_driver_ports(driver, os.type))): problems.append(f"{at}: {app.id} listens on {', '.join(map(str, taken))}, as {driver.id} does") + if os.type == "windows" and (session := [step.name for step in app.declaration.install_steps + if step.scope == "session" and (step.os is None or os.type in step.os)]): + problems.append(f"{at}: {app.id}'s install steps {', '.join(session)} run as the session user, which a Windows " + "computer can't as it's composed, over ssh as its admin; give them scope \"system\" for " + "Windows") return problems diff --git a/src/agent_env/env/envs/computer/utils/macos_vm_bundle.py b/src/agent_env/env/envs/computer/utils/macos_vm_bundle.py index 5d35622b6..f6d37cc86 100644 --- a/src/agent_env/env/envs/computer/utils/macos_vm_bundle.py +++ b/src/agent_env/env/envs/computer/utils/macos_vm_bundle.py @@ -115,7 +115,8 @@ def _installed(part: Part) -> list[str]: if part.served is not None: lines.append(f"mkdir -p {shlex.quote(f'{prefix}/{SOCKET.parent}')}") commands = [*((run.scope, shlex.quote(f"./{run.script}")) for run in install.run or []), - *((scope, f"venv/bin/python -m agentenv_protocol.computer.run_install_step {part.served} {step}") + *((scope, f"venv/bin/python -m agentenv_protocol.computer.run_install_step {shlex.quote(part.served)} " + f"{step}") for step, scope in part.steps)] for scope, command in commands: run = f"cd {quoted} && {command}" 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..82cb5c683 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.served import ADDRESS + 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 @@ -134,7 +136,8 @@ class Base: @dataclass(frozen=True) class Part: """A layer as a Windows disk installs it: its folder under ``context/``, its prefix, its install, its services' - argv by name, the environment they're given, and what its venv installs beside its requirements.""" + argv by name, the environment they're given, what its venv installs beside its requirements, and for an app, the + ``:`` its own server serves and its install steps by name, each run elevated.""" folder: str prefix: PureWindowsPath @@ -142,6 +145,8 @@ class Part: services: dict[str, list[str]] environment: dict[str, Any] wants: tuple[str, ...] = () + served: str | None = None + steps: tuple[str, ...] = () def media_path() -> Path: @@ -320,14 +325,15 @@ def expiring(expires: str | None) -> bool: return expires is None or datetime.fromisoformat(expires) - datetime.now(timezone.utc) < timedelta(days=RENEW_DAYS) -def write(build: Path, parts: list[Part], build_settings: dict[str, Any], image: dict) -> str: - """Write ``build``'s ``provision.ps1``, which installs ``parts`` from ``build/context``, their services for - agentenv-session, ``build_settings`` as every service's ``AGENTENV_SETTING_`` and ``image`` as what the disk - says it holds; its text, which a composed disk's key covers.""" +def write(build: Path, parts: list[Part], user: str, build_settings: dict[str, Any], image: dict) -> str: + """Write ``build``'s ``provision.ps1``, which installs ``parts`` from ``build/context``, each app's own folder the + session user ``user``'s, their services for agentenv-session, ``build_settings`` as every service's + ``AGENTENV_SETTING_`` and ``image`` as what the disk says it holds; its text, which a composed disk's key + covers.""" lines = ["$ErrorActionPreference = 'Stop'", "$ProgressPreference = 'SilentlyContinue'", f"$build = '{BUILD}'", _CHECKED, _FETCH] for part in parts: - lines += [f"# {part.folder}", *_installed_part(part)] + lines += [f"# {part.folder}", *_installed_part(part, user)] settings = {f"AGENTENV_SETTING_{name.upper()}": str(value) for name, value in build_settings.items()} lines += [_written(ROOT / "build-settings.json", json.dumps(settings)), _written(ROOT / "image.json", json.dumps(image, sort_keys=True))] @@ -336,8 +342,11 @@ def write(build: Path, parts: list[Part], build_settings: dict[str, Any], image: return script -def _installed_part(part: Part) -> list[str]: - """The lines that install ``part``: its files, downloads, venv, run scripts and services.""" +def _installed_part(part: Part, user: str) -> list[str]: + """The lines that install ``part``: its files, downloads, venv, an app's own folder, its run scripts and install + steps, and its services. An app's own folder, where its server writes its address and token, holds none of the + access its parents give: only ``user``, the session user its server runs as, SYSTEM and Administrators have it, as + on Linux the session user alone reaches the server's socket.""" prefix, install = part.prefix, part.install lines = [f"New-Item -ItemType Directory -Force '{prefix}' | Out-Null", f"Copy-Item -Recurse -Force \"$build\\context\\{PureWindowsPath(part.folder)}\\*\" '{prefix}'"] @@ -354,9 +363,17 @@ def _installed_part(part: Part) -> list[str]: + " ".join(_ps(want) for want in wants) + " }") lines.append(f"Checked {{ & '{venv / 'Scripts' / 'python.exe'}' -m pip list --format=json | " f"Set-Content -Encoding utf8 '{prefix / 'installed.json'}' }}") + if part.served is not None: + own = prefix / ADDRESS.parent.as_posix() + lines += [f"New-Item -ItemType Directory -Force '{own}' | Out-Null", + f"Checked {{ icacls '{own}' /inheritance:r /grant:r {_ps(f'{user}:(OI)(CI)F')} '*S-1-5-18:(OI)(CI)F' " + "'*S-1-5-32-544:(OI)(CI)F' | Out-Null }"] for run in install.run or []: lines.append(f"$env:PREFIX = '{prefix}'; Push-Location '{prefix}'; Checked {{ & powershell -NoProfile " f"-ExecutionPolicy Bypass -File '{prefix / PureWindowsPath(run.script)}' }}; Pop-Location") + for step in part.steps: + lines.append(f"Push-Location '{prefix}'; Checked {{ & '{prefix / 'venv' / 'Scripts' / 'python.exe'}' -m " + f"agentenv_protocol.computer.run_install_step {_ps(part.served)} {_ps(step)} }}; Pop-Location") for name, argv in part.services.items(): spec = {"name": name, "prefix": str(prefix), "command": argv, "env": {**UTF8, **{key: str(value) for key, value in part.environment.items()}}} diff --git a/tst/integration/computer/app/artifacts/check_windows_notes/verify.py b/tst/integration/computer/app/artifacts/check_windows_notes/verify.py new file mode 100644 index 000000000..809060627 --- /dev/null +++ b/tst/integration/computer/app/artifacts/check_windows_notes/verify.py @@ -0,0 +1,63 @@ +"""The notes app composed onto the deployed Windows computer: ready once its server says its window is shown and its +@ready_check passes; and, read inside the computer as the session user, on the app's own venv: what its service wrote on +the deploy's settings, its secret resolved at boot, in Windows' font; its window, listed by its program and title; its +Start Menu launcher and its launch since the computer booted; what its install left in its folder: the download, its +PowerShell run script's output, run elevated, and its install step's file on the build setting its env fixes; its own +folder, which the session user, SYSTEM and Administrators alone reach; and its server, which answers its token alone.""" +import json + +from agentenv_protocol.computer.card import COMPUTER_READY +from agentenv_protocol.computer.conformance.client import Driver + +PYTHON = "C:/agentenv/apps/notes/venv/Scripts/python.exe" +FACTS = r""" +import asyncio, json, os, subprocess, tempfile, time +from pathlib import Path +import httpx +from agentenv_protocol.computer import session +from agentenv_protocol.computer.served import ADDRESS, served + +prefix = Path("C:/agentenv/apps/notes") +written = Path.home() / ".notes.json" +deadline = time.monotonic() + 60 +while not written.exists() and time.monotonic() < deadline: + time.sleep(0.5) +reached = served(prefix) +tokenless = httpx.get(f"http://127.0.0.1:{reached.port}/.well-known/agent-env.json", trust_env=False, timeout=10) +with reached.sync_client(10) as http: + answered = http.get("/.well-known/agent-env.json").status_code +acl = {} +for path in (prefix / ADDRESS.parent, prefix / ADDRESS): + listed = subprocess.run(["icacls", str(path)], capture_output=True, text=True).stdout.replace(str(path), "", 1) + acl[path.name] = sorted(line.strip().split(":")[0].rpartition("\\")[2] for line in listed.splitlines() + if ":(" in line) +print(json.dumps({ + "notes": json.loads(written.read_text()), + "windows": [window for window in asyncio.run(session.windows()) if window["title"] == "Notes"], + "launcher": (Path(os.environ["APPDATA"]) / "Microsoft/Windows/Start Menu/Programs/notes.lnk").is_file(), + "launched": sorted(path.name for path in (Path(tempfile.gettempdir()) / "agentenv" / "apps").iterdir()), + "run": (prefix / "run.txt").read_text().strip(), "installed": (prefix / "installed.txt").read_text(), + "license": (prefix / "LICENSE.txt").read_text().startswith("A. HISTORY OF THE SOFTWARE"), + "acl": acl, "token": [tokenless.status_code, answered]})) +""" +EXPECTED = { + "notes": {"signature": "-- Ada", "token": "t0ken", "edition": "pro", "font": "Segoe UI"}, + "windows": [{"instance": "pythonw.exe", "class": "TkTopLevel", "title": "Notes"}], "launcher": True, + "launched": ["notes"], "run": "elevated True in C:\\agentenv\\apps\\notes", "installed": "pro", "license": True, + "acl": {name: ["Administrators", "SYSTEM", "user"] for name in (".agentenv", "server.json")}, + "token": [403, 200]} + + +async def verify(mcp_url, env_url): + driver = await Driver.connect(env_url, 120) + status = await driver.invoke(COMPUTER_READY, "status") + app = [check for check in status.get("checks", []) if check.get("name") == "app notes"] + results = [{"id": "ready", "result": bool(status.get("ready")) and [c.get("ok") for c in app] == [True], + "description": json.dumps(app)}] + out = await driver.run(PYTHON, "-c", FACTS, timeout_s=120) + try: + facts = json.loads(out.get("stdout") or "") + except ValueError: + return results + [{"id": "facts", "result": False, "description": json.dumps(out)[-2000:]}] + return results + [{"id": name, "result": facts.get(name) == expected, + "description": json.dumps(facts.get(name))} for name, expected in EXPECTED.items()] diff --git a/tst/integration/computer/app/envs/notes/app.py b/tst/integration/computer/app/envs/notes/app.py index 67ab9e55a..5a8e5f6f2 100644 --- a/tst/integration/computer/app/envs/notes/app.py +++ b/tst/integration/computer/app/envs/notes/app.py @@ -4,15 +4,18 @@ package from Ubuntu's archive and one only a Launchpad PPA has, which its run script uses, a download checked by sha256, and an install step run as the session user on the build setting its env.toml fixes, which also leaves a welcome note in ~/Notes, where it keeps its data, so its server serves that folder as its data plane. On Linux its settings gain a -font, and its install step and ready check are Linux's.""" +font, and its install step and ready check are Linux's. On Windows it takes the same download, a PowerShell run +script, run elevated, and an install step run elevated in its folder, as Windows runs none as the session user; its +window is matched by its title there, and its font is Windows'.""" from pathlib import Path from pydantic import BaseModel, SecretStr from agentenv_protocol.computer import (AptSource, ComputerAppEnvironment, Download, Launch, Packages, Ready, RunScript, - Service, computer_app, install_step, linux, ready_check) + Service, computer_app, install_step, linux, ready_check, windows) LICENSE = "https://raw.githubusercontent.com/python/cpython/v3.12.0/LICENSE" +LICENSE_SHA256 = "3b2f81fe21d181c499c59a256c8e1968455d6689d269aa85373bfb6af41da3bf" FASTFETCH = "https://ppa.launchpadcontent.net/zhangsongcui3371/fastfetch/ubuntu" @@ -20,16 +23,26 @@ class LinuxSettings(BaseModel): font: str = "DejaVu Sans" -@computer_app(supports=[{"os": {"type": "linux", "display": ["x11"]}, "arch": ["amd64", "arm64"]}]) +class WindowsSettings(BaseModel): + font: str = "Segoe UI" + + +@computer_app(supports=[{"os": {"type": "linux", "display": ["x11"]}, "arch": ["amd64", "arm64"]}, + {"os": {"type": "windows", "display": ["dwm"]}, "arch": ["amd64"]}]) @linux(packages=Packages(apt=["hello", "fastfetch"]), sources=[AptSource(apt=FASTFETCH, suite="noble", components=["main"], key="fastfetch.asc")], - downloads=[Download(url=LICENSE, to="LICENSE.txt", - sha256="3b2f81fe21d181c499c59a256c8e1968455d6689d269aa85373bfb6af41da3bf")], + downloads=[Download(url=LICENSE, to="LICENSE.txt", sha256=LICENSE_SHA256)], run=[RunScript(script="setup.sh")], services=[Service(name="notes", command="venv/bin/python serve.py")], launch=Launch(at="boot", command=["venv/bin/python", "window.py"], window={"class": "Notes"}, ready=Ready(window=True)), paths=["Notes"], settings=LinuxSettings) +@windows(downloads=[Download(url=LICENSE, to="LICENSE.txt", sha256=LICENSE_SHA256)], + run=[RunScript(script="setup.ps1")], + services=[Service(name="notes", command="venv/Scripts/python.exe serve.py")], + launch=Launch(at="boot", command=["venv/Scripts/pythonw.exe", "window.py"], window={"title": "Notes"}, + ready=Ready(window=True)), + paths=["Notes"], settings=WindowsSettings) class Notes(ComputerAppEnvironment): skill = "skill.md" @@ -46,6 +59,10 @@ def remember(self) -> None: (Path.home() / "Notes").mkdir(exist_ok=True) (Path.home() / "Notes" / "welcome.md").write_text("# Welcome\n") - @ready_check(os="linux") + @install_step(os="windows") + def stamp(self) -> None: + Path("installed.txt").write_text(self.build_settings.edition) + + @ready_check(os=["linux", "windows"]) def written(self) -> bool: return (Path.home() / ".notes.json").exists() diff --git a/tst/integration/computer/app/envs/notes/setup.ps1 b/tst/integration/computer/app/envs/notes/setup.ps1 new file mode 100644 index 000000000..a7db1ce3b --- /dev/null +++ b/tst/integration/computer/app/envs/notes/setup.ps1 @@ -0,0 +1,4 @@ +# Run elevated once the app's files are in: whether it is, in the folder it was given. +$identity = [Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent() +$elevated = $identity.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator) +"elevated $elevated in $env:PREFIX" | Set-Content -Encoding ascii run.txt diff --git a/tst/integration/computer/app/envs/windows-desk/env.toml b/tst/integration/computer/app/envs/windows-desk/env.toml new file mode 100644 index 000000000..fc2ada7fa --- /dev/null +++ b/tst/integration/computer/app/envs/windows-desk/env.toml @@ -0,0 +1,4 @@ +type = "computer" +computer = "windows-11" +driver = "cua-driver" +apps = ["notes"] diff --git a/tst/integration/computer/app/tasks/windows.json b/tst/integration/computer/app/tasks/windows.json new file mode 100644 index 000000000..436c80c2e --- /dev/null +++ b/tst/integration/computer/app/tasks/windows.json @@ -0,0 +1,9 @@ +[ + {"id": "env", "type": "deploy_env", "env_id": "windows-desk", + "env_params": {"app_settings": {"notes": {"signature": "-- Ada", "token": "env:NOTES_TOKEN"}}}}, + {"id": "before", "type": "env_outcome_verifier", "env_id": "windows-desk", "file_artifact_id": "check_windows_notes", + "verifier_id": "before"}, + {"id": "reset", "type": "reset_env", "env_id": "windows-desk", "depends_on": ["before"]}, + {"id": "after", "type": "env_outcome_verifier", "env_id": "windows-desk", "file_artifact_id": "check_windows_notes", + "verifier_id": "after", "depends_on": ["reset"]} +] diff --git a/tst/integration/computer/windows_test.py b/tst/integration/computer/windows_test.py index 4e0e87e68..748da6d8d 100644 --- a/tst/integration/computer/windows_test.py +++ b/tst/integration/computer/windows_test.py @@ -1,7 +1,10 @@ """The Windows test bundle through ``agent-env run``, on local Docker with KVM: its desktop, cua-driver on windows-11, composed on this machine, its base installed from the evaluation ISO in this machine's cache unless one is held here, passes the conformance probe at full, cua-driver's known failure on Windows waived, before and after a reset in place; -and an agent drives Notepad on it through cua-driver's tools. Needs Docker, KVM and the ISO; the agent's task, a model endpoint too.""" +and an agent drives Notepad on it through cua-driver's tools. And the app bundle's notes app, composed onto it as a +layer, runs on its deploy's settings, its window up and its install done as its Windows install says, its own folder +and server the session user's alone, before and after a reset. Needs Docker, KVM and the ISO; the agent's task, a model +endpoint too.""" from pathlib import Path @@ -14,6 +17,7 @@ pytestmark = [pytest.mark.integration, pytest.mark.int_test_slow, skip_without_windows_media()] BUNDLE = Path(__file__).parent / "windows" +APPS = Path(__file__).parent / "app" def test_the_windows_desktop_passes_the_probe_at_full(state): @@ -38,5 +42,14 @@ def test_an_agent_saves_a_line_in_notepad_through_cua_drivers_tools(state): assert "passed (check: 1)" in ran.output, ran.output -def _run(task: str): - return CliRunner().invoke(cli, ["run", str(BUNDLE), "--task", task]) +def test_the_notes_app_composed_onto_windows_runs_as_installed_before_and_after_a_reset(state, monkeypatch): + monkeypatch.setenv("NOTES_TOKEN", "t0ken") + + ran = _run("windows", APPS) + + assert ran.exit_code == 0, ran.output + assert "passed (before: 1, after: 1)" in ran.output, ran.output + + +def _run(task: str, bundle: Path = BUNDLE): + return CliRunner().invoke(cli, ["run", str(bundle), "--task", task]) diff --git a/tst/unit/env/envs/test_computer_windows.py b/tst/unit/env/envs/test_computer_windows.py index a2b584be9..da556bc83 100644 --- a/tst/unit/env/envs/test_computer_windows.py +++ b/tst/unit/env/envs/test_computer_windows.py @@ -1,7 +1,9 @@ """A Windows computer env, composed on this machine's Docker with KVM: its base installed from Microsoft's media once and -kept here, then the driver installed over ssh by a provision script as its ``[install.windows]`` says and packed as a -thin layer on the base, under a tag of its key, which a compose of the same inputs reuses while this machine holds it; -the env's computer is a disk of the base's form. A Windows base is amd64, disk-only and started by agentenv-session.""" +kept here, then the driver and each app installed over ssh by a provision script as their ``[install.windows]`` says +and packed as a thin layer on the base, under a tag of its key, which a compose of the same inputs reuses while this +machine holds it; the env's computer is a disk of the base's form. An app's own server runs from its venv, its own +folder the session user's alone, its install steps elevated; one it runs as the session user is refused. A Windows +base is amd64, disk-only and started by agentenv-session.""" import json import threading @@ -13,12 +15,13 @@ import pytest from pydantic import ValidationError -from agentenv_protocol.computer import DriverDeclaration +from agentenv_protocol.computer import AppDeclaration, DriverDeclaration from agentenv_protocol.computer.app import Download, Packages, RunScript from agent_env.artifact.artifacts.computer import ComputerArtifact from agent_env.artifact.artifacts.file_artifact_universe import FileArtifactUniverse from agent_env.env.env import Env +from agent_env.env.envs.computer.app_env import ComputerAppEnv from agent_env.env.envs.computer.driver_env import ComputerDriverEnv from agent_env.env.envs.computer.env import ComputerEnv from agent_env.env.envs.computer.utils import composer, gate, windows_disk @@ -123,9 +126,32 @@ def _driver(folder: Path) -> ComputerDriverEnv: return Env.get(put.id, put.version) -def _put(driver: ComputerDriverEnv, link: SandboxProvider, **settings) -> ComputerEnv: - return ComputerEnv.put(id="@local/~/kit/desktop", computer=_base(), driver=driver, environment_name="desktop", - composing=Composing(sandbox_provider=link), computer_settings=settings or None) +def _notes(base: ComputerArtifact, driver: ComputerDriverEnv, folder: Path, + steps: tuple = (("stamp", "system", None),)) -> ComputerAppEnv: + """A notes app on Windows: a sync service in the venv its own server gets, an elevated run script, ``steps``, its + install steps by name, scope and the OS types they run on, and the edition its env fixes.""" + folder.mkdir(parents=True, exist_ok=True) + for name, text in (("app.py", "class Notes: ...\n"), ("setup.ps1", "'ran' | Set-Content run.txt\n")): + (folder / name).write_text(text) + files = FileArtifactUniverse.put_bundled("@local/~/kit/notes__files", files={ + name: folder / name for name in ("app.py", "setup.ps1")}) + declaration = AppDeclaration.model_validate({ + "supports": [{"os": {"type": "windows", "display": ["dwm"]}, "arch": ["amd64"]}], "permissions": [], + "settings": {"type": "object", "properties": {}}, "skill": None, "data": [], "ready_checks": [], + "build_settings": {"type": "object", "properties": {"edition": {"type": "string", "default": "home"}}}, + "install_steps": [{"name": name, "scope": scope, "os": os} for name, scope, os in steps], + "os": {"windows": {"install": {"run": [{"script": "setup.ps1"}], "services": [ + {"name": "sync", "command": "venv/Scripts/python.exe sync.py"}]}}}}) + return ComputerAppEnv.put(id="@local/~/kit/notes", environment_name="notes", module="app.py:Notes", files=files, + declaration=declaration, computer=base, driver=driver, compose=False, + build_settings={"edition": "pro"}) + + +def _put(driver: ComputerDriverEnv, link: SandboxProvider, apps: list[ComputerAppEnv] | None = None, + base: ComputerArtifact | None = None, **settings) -> ComputerEnv: + return ComputerEnv.put(id="@local/~/kit/desktop", computer=base or _base(), driver=driver, + environment_name="desktop", composing=Composing(sandbox_provider=link), + computer_settings=settings or None, apps=apps or []) def test_a_windows_env_composes_a_thin_disk_on_its_base_here_the_driver_installed_by_its_provision_script( @@ -159,6 +185,60 @@ def test_a_windows_env_composes_a_thin_disk_on_its_base_here_the_driver_installe assert computer.forms.disk.image is None and env.metadata["computer"]["disks"] == {"amd64": built["image"]} +def test_an_app_is_a_layer_of_its_own_its_server_on_its_venv_its_folder_the_session_users_its_steps_elevated( + docker, tmp_path): + base = _base() + driver = _driver(tmp_path / "desk") + env = _put(driver, FakeLinux(), apps=[_notes(base, driver, tmp_path / "notes")], base=base) + + assert env.metadata["composed"]["disk"]["amd64"]["status"] == "ready" + ((_, script, files, _),) = docker.composed + prefix, lines = PureWindowsPath("C:/agentenv/apps/notes"), script.split("\r\n") + python = prefix / "venv" / "Scripts" / "python.exe" + installed = lines[lines.index("# apps/notes") + 1:] + assert installed[:5] == [ + f"New-Item -ItemType Directory -Force '{prefix}' | Out-Null", + f"Copy-Item -Recurse -Force \"$build\\context\\apps\\notes\\*\" '{prefix}'", + f"Checked {{ & 'C:\\agentenv\\python\\python.exe' -m venv '{prefix}\\venv' }}", + f"Checked {{ & '{python}' -m pip install -q --disable-pip-version-check " + "'C:\\agentenv\\build\\context\\protocol[app]' }", + f"Checked {{ & '{python}' -m pip list --format=json | Set-Content -Encoding utf8 '{prefix}\\installed.json' }}"] + assert installed[5:9] == [ + f"New-Item -ItemType Directory -Force '{prefix}\\.agentenv' | Out-Null", + f"Checked {{ icacls '{prefix}\\.agentenv' /inheritance:r /grant:r 'user:(OI)(CI)F' '*S-1-5-18:(OI)(CI)F' " + "'*S-1-5-32-544:(OI)(CI)F' | Out-Null }", + f"$env:PREFIX = '{prefix}'; Push-Location '{prefix}'; Checked {{ & powershell -NoProfile -ExecutionPolicy " + f"Bypass -File '{prefix}\\setup.ps1' }}; Pop-Location", + f"Push-Location '{prefix}'; Checked {{ & '{python}' -m agentenv_protocol.computer.run_install_step " + "'app.py:Notes' 'stamp' }; Pop-Location"] + services = {spec["name"]: spec for spec in (json.loads(line.split(", '", 1)[1].rsplit("')", 1)[0].replace( + "''", "'")) for line in installed if "\\services\\" in line)} + environment = {"PYTHONUTF8": "1", "ENVIRONMENT_NAME": "notes"} + assert services == { + "app-notes": {"name": "app-notes", "prefix": str(prefix), "env": environment, + "command": [str(python), "-m", "agentenv_protocol.computer.serve_app", "app.py:Notes"]}, + "app-notes-sync": {"name": "app-notes-sync", "prefix": str(prefix), "env": environment, + "command": [str(python), "sync.py"]}} + driver_lines = lines[lines.index("# driver"):lines.index("# apps/notes")] + assert not any(".agentenv" in line or "run_install_step" in line for line in driver_lines) + assert any(line.endswith("\"layers\": [\"driver\", \"apps/notes\"]}')") for line in lines) + assert {"context/apps/notes/app.py", "context/apps/notes/.agentenv/build_settings.json"} <= set(files) + + +def test_an_apps_install_step_for_the_session_user_is_refused_on_windows_before_anything_is_composed(docker, + tmp_path): + base = _base() + driver = _driver(tmp_path / "desk") + notes = _notes(base, driver, tmp_path / "notes", steps=(("stamp", "system", None), + ("remember", "session", ["linux"]), + ("greet", "session", None))) + + with pytest.raises(ValueError, match=r"apps\[0\]: @local/~/kit/notes's install steps greet run as the session " + r"user, which a Windows computer can't as it's composed"): + _put(driver, FakeLinux(), apps=[notes], base=base) + assert docker.composed == [] + + def test_a_compose_of_the_same_inputs_reuses_the_disk_the_image_store_holds(docker, tmp_path): driver = _driver(tmp_path / "desk") first = _put(driver, FakeLinux()) From 8b57ba8f31613033b7cde9c67483db3cac2f152a Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sat, 7 Nov 2026 23:35:21 -0800 Subject: [PATCH 06/20] test(computer): refuse a session install step on Windows alone or composed Co-Authored-By: Claude Opus 5.5 --- tst/unit/env/envs/test_computer_windows.py | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/tst/unit/env/envs/test_computer_windows.py b/tst/unit/env/envs/test_computer_windows.py index da556bc83..d5843bdca 100644 --- a/tst/unit/env/envs/test_computer_windows.py +++ b/tst/unit/env/envs/test_computer_windows.py @@ -126,7 +126,7 @@ def _driver(folder: Path) -> ComputerDriverEnv: return Env.get(put.id, put.version) -def _notes(base: ComputerArtifact, driver: ComputerDriverEnv, folder: Path, +def _notes(base: ComputerArtifact | None, driver: ComputerDriverEnv | None, folder: Path, steps: tuple = (("stamp", "system", None),)) -> ComputerAppEnv: """A notes app on Windows: a sync service in the venv its own server gets, an elevated run script, ``steps``, its install steps by name, scope and the OS types they run on, and the edition its env fixes.""" @@ -225,17 +225,16 @@ def test_an_app_is_a_layer_of_its_own_its_server_on_its_venv_its_folder_the_sess assert {"context/apps/notes/app.py", "context/apps/notes/.agentenv/build_settings.json"} <= set(files) -def test_an_apps_install_step_for_the_session_user_is_refused_on_windows_before_anything_is_composed(docker, - tmp_path): +def test_an_apps_install_step_for_the_session_user_is_refused_on_windows_alone_or_composed(docker, tmp_path): base = _base() driver = _driver(tmp_path / "desk") - notes = _notes(base, driver, tmp_path / "notes", steps=(("stamp", "system", None), - ("remember", "session", ["linux"]), - ("greet", "session", None))) + steps = (("stamp", "system", None), ("remember", "session", ["linux"]), ("greet", "session", None)) + refused = "@local/~/kit/notes's install steps greet run as the session user, which a Windows computer can't" - with pytest.raises(ValueError, match=r"apps\[0\]: @local/~/kit/notes's install steps greet run as the session " - r"user, which a Windows computer can't as it's composed"): - _put(driver, FakeLinux(), apps=[notes], base=base) + with pytest.raises(ValueError, match=f"computer app env '@local/~/kit/notes': app: {refused}"): + _notes(base, driver, tmp_path / "notes", steps) + with pytest.raises(ValueError, match=rf"apps\[0\]: {refused}"): + _put(driver, FakeLinux(), apps=[_notes(None, None, tmp_path / "notes", steps)], base=base) assert docker.composed == [] From d9133e4f502ef4313ff6b703db76425b5017fd96 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sat, 7 Nov 2026 23:54:26 -0800 Subject: [PATCH 07/20] refactor(computer): name the driver's Windows prefix apart from each app's Co-Authored-By: Claude Opus 5.5 --- src/agent_env/env/envs/computer/utils/composer.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/agent_env/env/envs/computer/utils/composer.py b/src/agent_env/env/envs/computer/utils/composer.py index 24c42451d..fbe2d292d 100644 --- a/src/agent_env/env/envs/computer/utils/composer.py +++ b/src/agent_env/env/envs/computer/utils/composer.py @@ -372,10 +372,11 @@ def _composed_windows_disk(env: ComputerEnv, base: ComputerArtifact, driver: Com context.mkdir(parents=True) protocol = _stage_protocol(context) layer, name = _stage_driver(context, driver, base, {}), gate.folder_name(driver.id, "driver") - prefix = windows_disk.DRIVERS / name - parts = [_windows_part(layer, prefix, {program: windows_disk.argv(command, prefix) for program, command in - _services(f"driver-{name}", layer.install).items()}, - {"MCP_PORT": driver.port}, protocol)] + driver_prefix = windows_disk.DRIVERS / name + parts = [_windows_part(layer, driver_prefix, { + program: windows_disk.argv(command, driver_prefix) + for program, command in _services(f"driver-{name}", layer.install).items()}, {"MCP_PORT": driver.port}, + protocol)] for app in env.composed_apps(): staged, prefix = _stage_app(context, app, base, {}), windows_disk.APPS / gate.app_folder(app) server = [str(prefix / "venv" / "Scripts" / "python.exe"), "-m", "agentenv_protocol.computer.serve_app", From 40bd73f64966431d0c21ffd26a38b013e2e656c3 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sat, 7 Nov 2026 23:57:00 -0800 Subject: [PATCH 08/20] 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 d29bd035d3d8db43b1e8048f501063647ff4e545 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sun, 8 Nov 2026 00:01:04 -0800 Subject: [PATCH 09/20] feat(computer): leave a Windows computer's agentenv folder the admins', as /opt/agentenv is root's C:\agentenv inherited the access C:\ gives every user to change what's under it, so the session user could change a driver's or an app's files. Composing now leaves it the admins': every user reads and runs it, and the session user writes only the services' logs and each app's own folder. Co-Authored-By: Claude Opus 5.5 --- src/agent_env/computers/README.md | 8 +++++--- .../env/envs/computer/utils/windows_disk.py | 15 ++++++++++++--- tst/unit/env/envs/test_computer_windows.py | 11 ++++++++--- 3 files changed, 25 insertions(+), 9 deletions(-) diff --git a/src/agent_env/computers/README.md b/src/agent_env/computers/README.md index ab6851804..02c4aa3d4 100644 --- a/src/agent_env/computers/README.md +++ b/src/agent_env/computers/README.md @@ -176,9 +176,11 @@ media alone, and starts each layer's services in that session, again whenever on with 4 vCPUs and 8 GB, on local Docker with KVM and on `modal_vm`; it has computer-exec and data/add, through the protocol's Windows defaults, so the probe runs its fixture there as on Linux, with Python one-liners for the commands it would give a shell. On `modal_vm` it runs in your own Modal workspace, under the evaluation's terms or a licence of your -own; whether they allow it there is yours to check. An app's own server runs in the session as its services do, on a -loopback port it writes with a token to its `.agentenv` folder, which only the session user, SYSTEM and Administrators -reach; it launches the app in a Job object, which ends whatever the app started. Composing signs in as `agentadmin`, so +own; whether they allow it there is yours to check. Composing leaves `C:\agentenv` the admins', as `/opt/agentenv` is +root's on Linux: every user reads and runs what's there, and the session user writes only the services' logs and each +app's `.agentenv` folder. An app's own server runs in the session as its services do, on a loopback port it writes +with a token to that folder, which only the session user, SYSTEM and Administrators reach; it launches the app in a +Job object, which ends whatever the app started. Composing signs in as `agentadmin`, so an app's install step for the session user can't run on Windows, and gate 1 refuses an app that declares one there. This bundle has no tasks of its own: other bundles pull its computers by alias, and `agent-env run computers` has 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 82cb5c683..981a063e0 100644 --- a/src/agent_env/env/envs/computer/utils/windows_disk.py +++ b/src/agent_env/env/envs/computer/utils/windows_disk.py @@ -328,20 +328,29 @@ def expiring(expires: str | None) -> bool: def write(build: Path, parts: list[Part], user: str, build_settings: dict[str, Any], image: dict) -> str: """Write ``build``'s ``provision.ps1``, which installs ``parts`` from ``build/context``, each app's own folder the session user ``user``'s, their services for agentenv-session, ``build_settings`` as every service's - ``AGENTENV_SETTING_`` and ``image`` as what the disk says it holds; its text, which a composed disk's key - covers.""" + ``AGENTENV_SETTING_`` and ``image`` as what the disk says it holds, then leaves ``ROOT`` the admins' + (``_locked``); its text, which a composed disk's key covers.""" lines = ["$ErrorActionPreference = 'Stop'", "$ProgressPreference = 'SilentlyContinue'", f"$build = '{BUILD}'", _CHECKED, _FETCH] for part in parts: lines += [f"# {part.folder}", *_installed_part(part, user)] settings = {f"AGENTENV_SETTING_{name.upper()}": str(value) for name, value in build_settings.items()} lines += [_written(ROOT / "build-settings.json", json.dumps(settings)), - _written(ROOT / "image.json", json.dumps(image, sort_keys=True))] + _written(ROOT / "image.json", json.dumps(image, sort_keys=True)), *_locked(user)] script = "\r\n".join(lines) + "\r\n" (build / "provision.ps1").write_text(script) return script +def _locked(user: str) -> list[str]: + """The lines that leave ``ROOT`` the admins', as on Linux ``/opt/agentenv`` is root's: every user reads and runs + what's there, none of the access ``C:\\`` gives every user to change it is left, and the session user ``user`` + writes only the services' logs, and each app's own folder, which keeps its own access.""" + return [f"Checked {{ icacls '{ROOT}' /inheritance:r /grant:r '*S-1-5-32-544:(OI)(CI)F' '*S-1-5-18:(OI)(CI)F' " + "'*S-1-5-32-545:(OI)(CI)RX' | Out-Null }", + f"Checked {{ icacls '{ROOT / 'logs'}' /grant {_ps(f'{user}:(OI)(CI)M')} | Out-Null }}"] + + def _installed_part(part: Part, user: str) -> list[str]: """The lines that install ``part``: its files, downloads, venv, an app's own folder, its run scripts and install steps, and its services. An app's own folder, where its server writes its address and token, holds none of the diff --git a/tst/unit/env/envs/test_computer_windows.py b/tst/unit/env/envs/test_computer_windows.py index d5843bdca..c8607164e 100644 --- a/tst/unit/env/envs/test_computer_windows.py +++ b/tst/unit/env/envs/test_computer_windows.py @@ -1,9 +1,10 @@ """A Windows computer env, composed on this machine's Docker with KVM: its base installed from Microsoft's media once and kept here, then the driver and each app installed over ssh by a provision script as their ``[install.windows]`` says and packed as a thin layer on the base, under a tag of its key, which a compose of the same inputs reuses while this -machine holds it; the env's computer is a disk of the base's form. An app's own server runs from its venv, its own -folder the session user's alone, its install steps elevated; one it runs as the session user is refused. A Windows -base is amd64, disk-only and started by agentenv-session.""" +machine holds it, its agentenv folder left the admins' and the session user's to read; the env's computer is a disk +of the base's form. An app's own server runs from its venv, its own folder the session user's alone, its install steps +elevated; one it runs as the session user is refused. A Windows base is amd64, disk-only and started by +agentenv-session.""" import json import threading @@ -179,6 +180,10 @@ def test_a_windows_env_composes_a_thin_disk_on_its_base_here_the_driver_installe assert json.loads(daemon.split(", '", 1)[1].rsplit("')", 1)[0].replace("''", "'")) == { "name": "driver-desk-daemon", "prefix": str(prefix), "command": [str(prefix / "venv/Scripts/python.exe"), "driver.py"], "env": {"PYTHONUTF8": "1", "MCP_PORT": "18765"}} + assert lines[-3:] == [ + "Checked { icacls 'C:\\agentenv' /inheritance:r /grant:r '*S-1-5-32-544:(OI)(CI)F' '*S-1-5-18:(OI)(CI)F' " + "'*S-1-5-32-545:(OI)(CI)RX' | Out-Null }", + "Checked { icacls 'C:\\agentenv\\logs' /grant 'user:(OI)(CI)M' | Out-Null }", ""] assert {"provision.ps1", "context/driver/driver.py", "context/driver/install.ps1"} <= set(files) computer = env.computer_artifact() assert computer.os.type == "windows" and computer.forms.disk.init == "agentenv-session" From 89f45b0d9ec56a710bbb8ae85ae5a3027d999093 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sun, 8 Nov 2026 00:07:19 -0800 Subject: [PATCH 10/20] 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 11/20] 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 268592a920ddb4f6532acd030a28a339fb22e92c Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sun, 8 Nov 2026 01:20:19 -0800 Subject: [PATCH 12/20] test(computer): keep the Windows notes test in the Windows bundle A fixture plans the app bundle whole, so a Windows env there composed Windows, ISO and all, wherever KVM was; the Windows bundle is run only where its media is. Co-Authored-By: Claude Opus 5.5 --- .../computer/app/envs/notes/app.py | 29 +++----------- .../computer/app/tasks/windows.json | 9 ----- .../artifacts/check_notes}/verify.py | 10 ++--- .../envs/notes-desk}/env.toml | 0 .../computer/windows/envs/notes/app.py | 38 +++++++++++++++++++ .../computer/windows/envs/notes/env.toml | 3 ++ .../computer/windows/envs/notes/serve.py | 12 ++++++ .../{app => windows}/envs/notes/setup.ps1 | 0 .../computer/windows/envs/notes/window.py | 9 +++++ .../computer/windows/tasks/notes.json | 9 +++++ tst/integration/computer/windows_test.py | 13 +++---- 11 files changed, 88 insertions(+), 44 deletions(-) delete mode 100644 tst/integration/computer/app/tasks/windows.json rename tst/integration/computer/{app/artifacts/check_windows_notes => windows/artifacts/check_notes}/verify.py (86%) rename tst/integration/computer/{app/envs/windows-desk => windows/envs/notes-desk}/env.toml (100%) create mode 100644 tst/integration/computer/windows/envs/notes/app.py create mode 100644 tst/integration/computer/windows/envs/notes/env.toml create mode 100644 tst/integration/computer/windows/envs/notes/serve.py rename tst/integration/computer/{app => windows}/envs/notes/setup.ps1 (100%) create mode 100644 tst/integration/computer/windows/envs/notes/window.py create mode 100644 tst/integration/computer/windows/tasks/notes.json diff --git a/tst/integration/computer/app/envs/notes/app.py b/tst/integration/computer/app/envs/notes/app.py index 5a8e5f6f2..67ab9e55a 100644 --- a/tst/integration/computer/app/envs/notes/app.py +++ b/tst/integration/computer/app/envs/notes/app.py @@ -4,18 +4,15 @@ package from Ubuntu's archive and one only a Launchpad PPA has, which its run script uses, a download checked by sha256, and an install step run as the session user on the build setting its env.toml fixes, which also leaves a welcome note in ~/Notes, where it keeps its data, so its server serves that folder as its data plane. On Linux its settings gain a -font, and its install step and ready check are Linux's. On Windows it takes the same download, a PowerShell run -script, run elevated, and an install step run elevated in its folder, as Windows runs none as the session user; its -window is matched by its title there, and its font is Windows'.""" +font, and its install step and ready check are Linux's.""" from pathlib import Path from pydantic import BaseModel, SecretStr from agentenv_protocol.computer import (AptSource, ComputerAppEnvironment, Download, Launch, Packages, Ready, RunScript, - Service, computer_app, install_step, linux, ready_check, windows) + Service, computer_app, install_step, linux, ready_check) LICENSE = "https://raw.githubusercontent.com/python/cpython/v3.12.0/LICENSE" -LICENSE_SHA256 = "3b2f81fe21d181c499c59a256c8e1968455d6689d269aa85373bfb6af41da3bf" FASTFETCH = "https://ppa.launchpadcontent.net/zhangsongcui3371/fastfetch/ubuntu" @@ -23,26 +20,16 @@ class LinuxSettings(BaseModel): font: str = "DejaVu Sans" -class WindowsSettings(BaseModel): - font: str = "Segoe UI" - - -@computer_app(supports=[{"os": {"type": "linux", "display": ["x11"]}, "arch": ["amd64", "arm64"]}, - {"os": {"type": "windows", "display": ["dwm"]}, "arch": ["amd64"]}]) +@computer_app(supports=[{"os": {"type": "linux", "display": ["x11"]}, "arch": ["amd64", "arm64"]}]) @linux(packages=Packages(apt=["hello", "fastfetch"]), sources=[AptSource(apt=FASTFETCH, suite="noble", components=["main"], key="fastfetch.asc")], - downloads=[Download(url=LICENSE, to="LICENSE.txt", sha256=LICENSE_SHA256)], + downloads=[Download(url=LICENSE, to="LICENSE.txt", + sha256="3b2f81fe21d181c499c59a256c8e1968455d6689d269aa85373bfb6af41da3bf")], run=[RunScript(script="setup.sh")], services=[Service(name="notes", command="venv/bin/python serve.py")], launch=Launch(at="boot", command=["venv/bin/python", "window.py"], window={"class": "Notes"}, ready=Ready(window=True)), paths=["Notes"], settings=LinuxSettings) -@windows(downloads=[Download(url=LICENSE, to="LICENSE.txt", sha256=LICENSE_SHA256)], - run=[RunScript(script="setup.ps1")], - services=[Service(name="notes", command="venv/Scripts/python.exe serve.py")], - launch=Launch(at="boot", command=["venv/Scripts/pythonw.exe", "window.py"], window={"title": "Notes"}, - ready=Ready(window=True)), - paths=["Notes"], settings=WindowsSettings) class Notes(ComputerAppEnvironment): skill = "skill.md" @@ -59,10 +46,6 @@ def remember(self) -> None: (Path.home() / "Notes").mkdir(exist_ok=True) (Path.home() / "Notes" / "welcome.md").write_text("# Welcome\n") - @install_step(os="windows") - def stamp(self) -> None: - Path("installed.txt").write_text(self.build_settings.edition) - - @ready_check(os=["linux", "windows"]) + @ready_check(os="linux") def written(self) -> bool: return (Path.home() / ".notes.json").exists() diff --git a/tst/integration/computer/app/tasks/windows.json b/tst/integration/computer/app/tasks/windows.json deleted file mode 100644 index 436c80c2e..000000000 --- a/tst/integration/computer/app/tasks/windows.json +++ /dev/null @@ -1,9 +0,0 @@ -[ - {"id": "env", "type": "deploy_env", "env_id": "windows-desk", - "env_params": {"app_settings": {"notes": {"signature": "-- Ada", "token": "env:NOTES_TOKEN"}}}}, - {"id": "before", "type": "env_outcome_verifier", "env_id": "windows-desk", "file_artifact_id": "check_windows_notes", - "verifier_id": "before"}, - {"id": "reset", "type": "reset_env", "env_id": "windows-desk", "depends_on": ["before"]}, - {"id": "after", "type": "env_outcome_verifier", "env_id": "windows-desk", "file_artifact_id": "check_windows_notes", - "verifier_id": "after", "depends_on": ["reset"]} -] diff --git a/tst/integration/computer/app/artifacts/check_windows_notes/verify.py b/tst/integration/computer/windows/artifacts/check_notes/verify.py similarity index 86% rename from tst/integration/computer/app/artifacts/check_windows_notes/verify.py rename to tst/integration/computer/windows/artifacts/check_notes/verify.py index 809060627..9359f6c53 100644 --- a/tst/integration/computer/app/artifacts/check_windows_notes/verify.py +++ b/tst/integration/computer/windows/artifacts/check_notes/verify.py @@ -1,9 +1,9 @@ """The notes app composed onto the deployed Windows computer: ready once its server says its window is shown and its @ready_check passes; and, read inside the computer as the session user, on the app's own venv: what its service wrote on -the deploy's settings, its secret resolved at boot, in Windows' font; its window, listed by its program and title; its -Start Menu launcher and its launch since the computer booted; what its install left in its folder: the download, its -PowerShell run script's output, run elevated, and its install step's file on the build setting its env fixes; its own -folder, which the session user, SYSTEM and Administrators alone reach; and its server, which answers its token alone.""" +the deploy's settings, its secret resolved at boot; its window, listed by its program and title; its Start Menu +launcher and its launch since the computer booted; what its install left in its folder: the download, its PowerShell +run script's output, run elevated, and its install step's file on the build setting its env fixes; its own folder, +which the session user, SYSTEM and Administrators alone reach; and its server, which answers its token alone.""" import json from agentenv_protocol.computer.card import COMPUTER_READY @@ -41,7 +41,7 @@ "acl": acl, "token": [tokenless.status_code, answered]})) """ EXPECTED = { - "notes": {"signature": "-- Ada", "token": "t0ken", "edition": "pro", "font": "Segoe UI"}, + "notes": {"signature": "-- Ada", "token": "t0ken", "edition": "pro"}, "windows": [{"instance": "pythonw.exe", "class": "TkTopLevel", "title": "Notes"}], "launcher": True, "launched": ["notes"], "run": "elevated True in C:\\agentenv\\apps\\notes", "installed": "pro", "license": True, "acl": {name: ["Administrators", "SYSTEM", "user"] for name in (".agentenv", "server.json")}, diff --git a/tst/integration/computer/app/envs/windows-desk/env.toml b/tst/integration/computer/windows/envs/notes-desk/env.toml similarity index 100% rename from tst/integration/computer/app/envs/windows-desk/env.toml rename to tst/integration/computer/windows/envs/notes-desk/env.toml diff --git a/tst/integration/computer/windows/envs/notes/app.py b/tst/integration/computer/windows/envs/notes/app.py new file mode 100644 index 000000000..9fbbeac90 --- /dev/null +++ b/tst/integration/computer/windows/envs/notes/app.py @@ -0,0 +1,38 @@ +"""A notes app for the Windows computer tests, composed onto a desktop as notes-desk: its service writes the settings a +deploy gave it to ~/.notes.json, and its own server launches its window once it serves; it's ready once both have +happened. It requires no Python of its own, so its service and window run in the venv every app gets for its server. +Its install takes a download checked by sha256, and a PowerShell run script and an install step, both run elevated in +its folder, the step on the build setting its env.toml fixes; its window is matched by its title.""" +from pathlib import Path + +from pydantic import BaseModel, SecretStr + +from agentenv_protocol.computer import (ComputerAppEnvironment, Download, Launch, Ready, RunScript, Service, + computer_app, install_step, ready_check, windows) + +LICENSE = "https://raw.githubusercontent.com/python/cpython/v3.12.0/LICENSE" + + +@computer_app(supports=[{"os": {"type": "windows", "display": ["dwm"]}, "arch": ["amd64"]}]) +@windows(downloads=[Download(url=LICENSE, to="LICENSE.txt", + sha256="3b2f81fe21d181c499c59a256c8e1968455d6689d269aa85373bfb6af41da3bf")], + run=[RunScript(script="setup.ps1")], + services=[Service(name="notes", command="venv/Scripts/python.exe serve.py")], + launch=Launch(at="boot", command=["venv/Scripts/pythonw.exe", "window.py"], window={"title": "Notes"}, + ready=Ready(window=True)), + paths=["Notes"]) +class Notes(ComputerAppEnvironment): + class Settings(BaseModel): + signature: str = "-- notes" + token: SecretStr = SecretStr("") + + class BuildSettings(BaseModel): + edition: str = "home" + + @install_step() + def stamp(self) -> None: + Path("installed.txt").write_text(self.build_settings.edition) + + @ready_check() + def written(self) -> bool: + return (Path.home() / ".notes.json").exists() diff --git a/tst/integration/computer/windows/envs/notes/env.toml b/tst/integration/computer/windows/envs/notes/env.toml new file mode 100644 index 000000000..5fb1340dd --- /dev/null +++ b/tst/integration/computer/windows/envs/notes/env.toml @@ -0,0 +1,3 @@ +type = "computer_app" +module = "app.py:Notes" +build_settings = { edition = "pro" } diff --git a/tst/integration/computer/windows/envs/notes/serve.py b/tst/integration/computer/windows/envs/notes/serve.py new file mode 100644 index 000000000..de7e3d931 --- /dev/null +++ b/tst/integration/computer/windows/envs/notes/serve.py @@ -0,0 +1,12 @@ +import json +import time +from pathlib import Path + +from app import Notes + +notes = Notes() +Path.home().joinpath(".notes.json").write_text(json.dumps( + {"signature": notes.settings.signature, "token": notes.settings.token.get_secret_value(), + "edition": notes.build_settings.edition})) +while True: + time.sleep(3600) diff --git a/tst/integration/computer/app/envs/notes/setup.ps1 b/tst/integration/computer/windows/envs/notes/setup.ps1 similarity index 100% rename from tst/integration/computer/app/envs/notes/setup.ps1 rename to tst/integration/computer/windows/envs/notes/setup.ps1 diff --git a/tst/integration/computer/windows/envs/notes/window.py b/tst/integration/computer/windows/envs/notes/window.py new file mode 100644 index 000000000..48a7649ff --- /dev/null +++ b/tst/integration/computer/windows/envs/notes/window.py @@ -0,0 +1,9 @@ +"""The notes app's window, titled Notes, showing the signature its settings give.""" +import tkinter as tk + +from app import Notes + +root = tk.Tk() +root.title("Notes") +tk.Label(root, text=Notes().settings.signature).pack(padx=40, pady=40) +root.mainloop() diff --git a/tst/integration/computer/windows/tasks/notes.json b/tst/integration/computer/windows/tasks/notes.json new file mode 100644 index 000000000..74b5afcab --- /dev/null +++ b/tst/integration/computer/windows/tasks/notes.json @@ -0,0 +1,9 @@ +[ + {"id": "env", "type": "deploy_env", "env_id": "notes-desk", + "env_params": {"app_settings": {"notes": {"signature": "-- Ada", "token": "env:NOTES_TOKEN"}}}}, + {"id": "before", "type": "env_outcome_verifier", "env_id": "notes-desk", "file_artifact_id": "check_notes", + "verifier_id": "before"}, + {"id": "reset", "type": "reset_env", "env_id": "notes-desk", "depends_on": ["before"]}, + {"id": "after", "type": "env_outcome_verifier", "env_id": "notes-desk", "file_artifact_id": "check_notes", + "verifier_id": "after", "depends_on": ["reset"]} +] diff --git a/tst/integration/computer/windows_test.py b/tst/integration/computer/windows_test.py index 748da6d8d..f8ce55875 100644 --- a/tst/integration/computer/windows_test.py +++ b/tst/integration/computer/windows_test.py @@ -1,9 +1,9 @@ """The Windows test bundle through ``agent-env run``, on local Docker with KVM: its desktop, cua-driver on windows-11, composed on this machine, its base installed from the evaluation ISO in this machine's cache unless one is held here, passes the conformance probe at full, cua-driver's known failure on Windows waived, before and after a reset in place; -and an agent drives Notepad on it through cua-driver's tools. And the app bundle's notes app, composed onto it as a -layer, runs on its deploy's settings, its window up and its install done as its Windows install says, its own folder -and server the session user's alone, before and after a reset. Needs Docker, KVM and the ISO; the agent's task, a model +and an agent drives Notepad on it through cua-driver's tools. And the bundle's notes app, composed onto it as a layer, +runs on its deploy's settings, its window up and its install done as its Windows install says, its own folder and +server the session user's alone, before and after a reset. Needs Docker, KVM and the ISO; the agent's task, a model endpoint too.""" from pathlib import Path @@ -17,7 +17,6 @@ pytestmark = [pytest.mark.integration, pytest.mark.int_test_slow, skip_without_windows_media()] BUNDLE = Path(__file__).parent / "windows" -APPS = Path(__file__).parent / "app" def test_the_windows_desktop_passes_the_probe_at_full(state): @@ -45,11 +44,11 @@ def test_an_agent_saves_a_line_in_notepad_through_cua_drivers_tools(state): def test_the_notes_app_composed_onto_windows_runs_as_installed_before_and_after_a_reset(state, monkeypatch): monkeypatch.setenv("NOTES_TOKEN", "t0ken") - ran = _run("windows", APPS) + ran = _run("notes") assert ran.exit_code == 0, ran.output assert "passed (before: 1, after: 1)" in ran.output, ran.output -def _run(task: str, bundle: Path = BUNDLE): - return CliRunner().invoke(cli, ["run", str(bundle), "--task", task]) +def _run(task: str): + return CliRunner().invoke(cli, ["run", str(BUNDLE), "--task", task]) From 564806a0cf347da9ea8763751ce21c97cea7d75e Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sun, 8 Nov 2026 01:22:59 -0800 Subject: [PATCH 13/20] fix(computer): a Windows compose tries a layer's download again after a server's error A 504 from GitHub failed a compose that a retry a few seconds later passes; the base's setup already retries its downloads. Co-Authored-By: Claude Opus 5.5 --- src/agent_env/env/envs/computer/utils/windows_disk.py | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) 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 981a063e0..829fc6566 100644 --- a/src/agent_env/env/envs/computer/utils/windows_disk.py +++ b/src/agent_env/env/envs/computer/utils/windows_disk.py @@ -67,6 +67,8 @@ COMPACT_TIMEOUT_S = 1800 #: How often an install looks for setup's end, a compose for the base's ssh, and a shutdown for the guest's. INSTALL_POLL_S, BOOT_POLL_S, SHUTDOWN_POLL_S = 15, 5, 2 +#: How many times a compose tries a layer's download, and how long it waits between, as a server's error can pass. +FETCH_TRIES, FETCH_PAUSE_S = 5, 10 CPUS, MEMORY_MB = 4, 8192 #: What every service runs with: Python reading and writing files as UTF-8, as on Linux, not in Windows' code page. UTF8 = {"PYTHONUTF8": "1"} @@ -553,6 +555,7 @@ def _ps(value: str) -> str: @{build = "$($v.CurrentBuild).$($v.UBR)"; grace_minutes = [int]$g} | ConvertTo-Json -Compress""" _CHECKED = ("function Checked([scriptblock]$Run) { & $Run; if ($LASTEXITCODE) { throw \"provision: $Run exited " "$LASTEXITCODE\" } }") -_FETCH = ("function Fetch([string]$Url, [string]$Sha256, [string]$To) { Invoke-WebRequest -UseBasicParsing -Uri $Url " - "-OutFile $To; $got = (Get-FileHash -Algorithm SHA256 $To).Hash.ToLower(); if ($got -ne $Sha256) { throw " - "\"provision: $Url came with sha256 $got, not $Sha256\" } }") +_FETCH = ("function Fetch([string]$Url, [string]$Sha256, [string]$To) { for ($try = 1; ; $try++) { try { " + "Invoke-WebRequest -UseBasicParsing -Uri $Url -OutFile $To; break } catch { if ($try -ge " + f"{FETCH_TRIES}) {{ throw }}; Start-Sleep {FETCH_PAUSE_S} }} }}; $got = (Get-FileHash -Algorithm SHA256 $To)" + ".Hash.ToLower(); if ($got -ne $Sha256) { throw \"provision: $Url came with sha256 $got, not $Sha256\" } }") From 514070e02d798e20c0e5088f25c8b82f2e405b56 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sun, 8 Nov 2026 01:27:50 -0800 Subject: [PATCH 14/20] fix(computer): a Windows compose tries a download as long as the base's setup does Co-Authored-By: Claude Opus 5.5 --- src/agent_env/env/envs/computer/utils/windows_disk.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) 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 829fc6566..c3b886932 100644 --- a/src/agent_env/env/envs/computer/utils/windows_disk.py +++ b/src/agent_env/env/envs/computer/utils/windows_disk.py @@ -67,8 +67,9 @@ COMPACT_TIMEOUT_S = 1800 #: How often an install looks for setup's end, a compose for the base's ssh, and a shutdown for the guest's. INSTALL_POLL_S, BOOT_POLL_S, SHUTDOWN_POLL_S = 15, 5, 2 -#: How many times a compose tries a layer's download, and how long it waits between, as a server's error can pass. -FETCH_TRIES, FETCH_PAUSE_S = 5, 10 +#: How many times a compose tries a layer's download, and how long it waits between, as the base's setup does: a +#: server's errors can last minutes, as GitHub's release downloads' 504s have. +FETCH_TRIES, FETCH_PAUSE_S = 30, 10 CPUS, MEMORY_MB = 4, 8192 #: What every service runs with: Python reading and writing files as UTF-8, as on Linux, not in Windows' code page. UTF8 = {"PYTHONUTF8": "1"} From 11bb9f60f22e37921263e942fb0a6fc306bc8a09 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sun, 8 Nov 2026 01:51:10 -0800 Subject: [PATCH 15/20] test(computer): the protocol's Windows session launches, pauses and stops apps on a real Windows computer Co-Authored-By: Claude Opus 5.5 --- .../windows/artifacts/check_session/verify.py | 108 ++++++++++++++++++ .../computer/windows/tasks/notes.json | 4 +- tst/integration/computer/windows_test.py | 8 +- 3 files changed, 116 insertions(+), 4 deletions(-) create mode 100644 tst/integration/computer/windows/artifacts/check_session/verify.py diff --git a/tst/integration/computer/windows/artifacts/check_session/verify.py b/tst/integration/computer/windows/artifacts/check_session/verify.py new file mode 100644 index 000000000..5c1782e56 --- /dev/null +++ b/tst/integration/computer/windows/artifacts/check_session/verify.py @@ -0,0 +1,108 @@ +"""The protocol's Windows session on the deployed computer, run inside it as the session user on the notes app's venv: +a launch's exit code is its app's; a pause holds every process of the app's job, one the app started too, and they run +again after; a stop ends an app with no window at once, one whose window closes when asked within the timeout, and one +whose window won't at the timeout, nothing of it left running after each; the helper killed ends its app; and a +program that isn't there is refused, saying why.""" +import json + +from agentenv_protocol.computer.conformance.client import Driver + +PYTHON = "C:/agentenv/apps/notes/venv/Scripts/python.exe" +SESSION = r""" +import asyncio, json, os, signal, sys, tempfile, time +from pathlib import Path +from agentenv_protocol.computer import _reaping, _session_windows as session + +work = Path(tempfile.mkdtemp()) +pythonw = str(Path(sys.executable).with_name("pythonw.exe")) +(work / "writer.py").write_text( + "import subprocess, sys, time\nfrom pathlib import Path\nout = Path(sys.argv[1])\n" + "if len(sys.argv) > 2:\n subprocess.Popen([sys.executable, __file__, sys.argv[1] + '.child'])\n" + "while True:\n with out.open('a') as f:\n f.write('x')\n time.sleep(0.01)\n") +(work / "window.py").write_text( + "import sys, tkinter as tk\nroot = tk.Tk()\nroot.title(sys.argv[1])\n" + "if sys.argv[2] == 'stubborn':\n root.protocol('WM_DELETE_WINDOW', lambda: None)\nroot.mainloop()\n") +facts = {} + + +def sizes(*paths): + return [path.stat().st_size if path.exists() else 0 for path in paths] + + +async def listed(title): + return any(window["title"] == title for window in await session.windows()) + + +async def main(): + pid = await session.launch([sys.executable, "-c", "import sys; sys.exit(7)"], work, {}) + facts["exit"] = await _reaping.returncode(pid, 30) + + out = work / "writes" + files = (out, Path(f"{out}.child")) + pid = await session.launch([pythonw, str(work / "writer.py"), str(out), "spawn"], work, {}) + await asyncio.sleep(3) + with session.paused(pid): + await asyncio.sleep(0.5) + held = sizes(*files) + await asyncio.sleep(2) + still = sizes(*files) + await asyncio.sleep(2) + facts["pause"] = {"held": held == still and min(held) > 0, + "ran after": all(after > before for after, before in zip(sizes(*files), still)), + "alive": session.alive(pid)} + await session.stop(pid, 10) + ended = sizes(*files) + await asyncio.sleep(1) + facts["windowless stop"] = {"alive": session.alive(pid), "wrote after": sizes(*files) != ended} + + for title, kind, timeout_s in (("Obliging", "obliging", 10), ("Stubborn", "stubborn", 4)): + pid = await session.launch([pythonw, str(work / "window.py"), title, kind], work, {}) + deadline = time.monotonic() + 30 + while not await listed(title) and time.monotonic() < deadline: + await asyncio.sleep(0.5) + shown, started = await listed(title), time.monotonic() + await session.stop(pid, timeout_s) + facts[f"{kind} stop"] = {"shown": shown, "waited out": time.monotonic() - started >= timeout_s, + "alive": session.alive(pid), "listed": await listed(title)} + + out = work / "orphan" + pid = await session.launch([pythonw, str(work / "writer.py"), str(out)], work, {}) + await asyncio.sleep(2) + os.kill(pid, signal.SIGTERM) + await asyncio.sleep(2) + ended = sizes(out) + await asyncio.sleep(1) + facts["helper killed"] = {"alive": session.alive(pid), "wrote after": sizes(out) != ended} + + try: + await session.launch(["no-such-program.exe"], work, {}) + facts["missing program"] = "started" + except OSError as e: + facts["missing program"] = str(e) + + +asyncio.run(main()) +print(json.dumps(facts)) +""" +EXPECTED = { + "exit": 7, + "pause": {"held": True, "ran after": True, "alive": True}, + "windowless stop": {"alive": False, "wrote after": False}, + "obliging stop": {"shown": True, "waited out": False, "alive": False, "listed": False}, + "stubborn stop": {"shown": True, "waited out": True, "alive": False, "listed": False}, + "helper killed": {"alive": False, "wrote after": False}, +} +MISSING = "couldn't start no-such-program.exe: FileNotFoundError" + + +async def verify(mcp_url, env_url): + driver = await Driver.connect(env_url, 120) + out = await driver.run(PYTHON, "-c", SESSION, timeout_s=240) + try: + facts = json.loads(out.get("stdout") or "") + except ValueError: + return [{"id": "session", "result": False, "description": json.dumps(out)[-2000:]}] + missing = facts.get("missing program", "") + return [{"id": name, "result": facts.get(name) == expected, "description": json.dumps(facts.get(name))} + for name, expected in EXPECTED.items()] + [ + {"id": "missing program", "result": missing.startswith(MISSING), "description": missing}] diff --git a/tst/integration/computer/windows/tasks/notes.json b/tst/integration/computer/windows/tasks/notes.json index 74b5afcab..3cc8b8d93 100644 --- a/tst/integration/computer/windows/tasks/notes.json +++ b/tst/integration/computer/windows/tasks/notes.json @@ -3,7 +3,9 @@ "env_params": {"app_settings": {"notes": {"signature": "-- Ada", "token": "env:NOTES_TOKEN"}}}}, {"id": "before", "type": "env_outcome_verifier", "env_id": "notes-desk", "file_artifact_id": "check_notes", "verifier_id": "before"}, - {"id": "reset", "type": "reset_env", "env_id": "notes-desk", "depends_on": ["before"]}, + {"id": "session", "type": "env_outcome_verifier", "env_id": "notes-desk", "file_artifact_id": "check_session", + "verifier_id": "session", "depends_on": ["before"]}, + {"id": "reset", "type": "reset_env", "env_id": "notes-desk", "depends_on": ["session"]}, {"id": "after", "type": "env_outcome_verifier", "env_id": "notes-desk", "file_artifact_id": "check_notes", "verifier_id": "after", "depends_on": ["reset"]} ] diff --git a/tst/integration/computer/windows_test.py b/tst/integration/computer/windows_test.py index f8ce55875..0cfdc0b4b 100644 --- a/tst/integration/computer/windows_test.py +++ b/tst/integration/computer/windows_test.py @@ -3,7 +3,8 @@ passes the conformance probe at full, cua-driver's known failure on Windows waived, before and after a reset in place; and an agent drives Notepad on it through cua-driver's tools. And the bundle's notes app, composed onto it as a layer, runs on its deploy's settings, its window up and its install done as its Windows install says, its own folder and -server the session user's alone, before and after a reset. Needs Docker, KVM and the ISO; the agent's task, a model +server the session user's alone, before and after a reset; and on it the protocol's Windows session launches, pauses +and stops apps, and all they start, as an app's server does. Needs Docker, KVM and the ISO; the agent's task, a model endpoint too.""" from pathlib import Path @@ -41,13 +42,14 @@ def test_an_agent_saves_a_line_in_notepad_through_cua_drivers_tools(state): assert "passed (check: 1)" in ran.output, ran.output -def test_the_notes_app_composed_onto_windows_runs_as_installed_before_and_after_a_reset(state, monkeypatch): +def test_the_notes_app_composed_onto_windows_runs_as_installed_and_the_session_runs_apps_in_their_jobs(state, + monkeypatch): monkeypatch.setenv("NOTES_TOKEN", "t0ken") ran = _run("notes") assert ran.exit_code == 0, ran.output - assert "passed (before: 1, after: 1)" in ran.output, ran.output + assert "passed (before: 1, session: 1, after: 1)" in ran.output, ran.output def _run(task: str): From de98352452ac77ecf2f3e6593d4eade8727c86b3 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sun, 8 Nov 2026 05:16:19 -0800 Subject: [PATCH 16/20] 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 17/20] 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) From 060e34fabd6c897e330d4a6c7686006719a62d9b Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sun, 8 Nov 2026 06:21:54 -0800 Subject: [PATCH 18/20] test(computer): the Windows session check reads sizes through a handle and reports them Co-Authored-By: Claude Opus 5.5 --- .../windows/artifacts/check_session/verify.py | 27 ++++++++++++++----- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/tst/integration/computer/windows/artifacts/check_session/verify.py b/tst/integration/computer/windows/artifacts/check_session/verify.py index 5c1782e56..50320c1c8 100644 --- a/tst/integration/computer/windows/artifacts/check_session/verify.py +++ b/tst/integration/computer/windows/artifacts/check_session/verify.py @@ -22,11 +22,19 @@ (work / "window.py").write_text( "import sys, tkinter as tk\nroot = tk.Tk()\nroot.title(sys.argv[1])\n" "if sys.argv[2] == 'stubborn':\n root.protocol('WM_DELETE_WINDOW', lambda: None)\nroot.mainloop()\n") -facts = {} +facts, written = {}, {} def sizes(*paths): - return [path.stat().st_size if path.exists() else 0 for path in paths] + '''Each file's size as an open handle reads it, which a stat by name can read behind.''' + read = [] + for path in paths: + try: + with path.open("rb") as file: + read.append(file.seek(0, 2)) + except FileNotFoundError: + read.append(0) + return read async def listed(title): @@ -53,7 +61,8 @@ async def main(): await session.stop(pid, 10) ended = sizes(*files) await asyncio.sleep(1) - facts["windowless stop"] = {"alive": session.alive(pid), "wrote after": sizes(*files) != ended} + written["windowless stop"] = [ended, sizes(*files)] + facts["windowless stop"] = {"alive": session.alive(pid), "wrote after": written["windowless stop"][1] != ended} for title, kind, timeout_s in (("Obliging", "obliging", 10), ("Stubborn", "stubborn", 4)): pid = await session.launch([pythonw, str(work / "window.py"), title, kind], work, {}) @@ -72,7 +81,8 @@ async def main(): await asyncio.sleep(2) ended = sizes(out) await asyncio.sleep(1) - facts["helper killed"] = {"alive": session.alive(pid), "wrote after": sizes(out) != ended} + written["helper killed"] = [ended, sizes(out)] + facts["helper killed"] = {"alive": session.alive(pid), "wrote after": written["helper killed"][1] != ended} try: await session.launch(["no-such-program.exe"], work, {}) @@ -82,7 +92,7 @@ async def main(): asyncio.run(main()) -print(json.dumps(facts)) +print(json.dumps({"facts": facts, "written": written})) """ EXPECTED = { "exit": 7, @@ -99,10 +109,13 @@ async def verify(mcp_url, env_url): driver = await Driver.connect(env_url, 120) out = await driver.run(PYTHON, "-c", SESSION, timeout_s=240) try: - facts = json.loads(out.get("stdout") or "") + read = json.loads(out.get("stdout") or "") except ValueError: return [{"id": "session", "result": False, "description": json.dumps(out)[-2000:]}] + facts, written = read["facts"], read["written"] missing = facts.get("missing program", "") - return [{"id": name, "result": facts.get(name) == expected, "description": json.dumps(facts.get(name))} + return [{"id": name, "result": facts.get(name) == expected, + "description": json.dumps({**facts.get(name, {}), "sizes": written[name]} if name in written + else facts.get(name))} for name, expected in EXPECTED.items()] + [ {"id": "missing program", "result": missing.startswith(MISSING), "description": missing}] From 8715a2a4023d5d68a63e9bf03edcbed50ef7d8d9 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sun, 8 Nov 2026 08:31:17 -0800 Subject: [PATCH 19/20] fix(computer): a Windows compose fails a download at once on a client error Retrying 30 times, 10 s apart, made a wrong URL take five minutes to fail; a 4xx but a timeout or rate limit now fails the first time, while a server's error, a timeout and a refused connection are still tried again. Co-Authored-By: Claude Opus 5.5 --- src/agent_env/env/envs/computer/utils/windows_disk.py | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) 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 585d38113..671819dec 100644 --- a/src/agent_env/env/envs/computer/utils/windows_disk.py +++ b/src/agent_env/env/envs/computer/utils/windows_disk.py @@ -69,7 +69,8 @@ #: How often an install looks for setup's end, a compose for the base's ssh, and a shutdown for the guest's. INSTALL_POLL_S, BOOT_POLL_S, SHUTDOWN_POLL_S = 15, 5, 2 #: How many times a compose tries a layer's download, and how long it waits between, as the base's setup does: a -#: server's errors can last minutes, as GitHub's release downloads' 504s have. +#: server's errors can last minutes, as GitHub's release downloads' 504s have. A client error, 4xx, but a timeout or +#: a rate limit, fails at once, as no retry mends a wrong URL. FETCH_TRIES, FETCH_PAUSE_S = 30, 10 CPUS, MEMORY_MB = 4, 8192 #: What every service runs with: Python reading and writing files as UTF-8, as on Linux, not in Windows' code page. @@ -558,6 +559,8 @@ def _ps(value: str) -> str: _CHECKED = ("function Checked([scriptblock]$Run) { & $Run; if ($LASTEXITCODE) { throw \"provision: $Run exited " "$LASTEXITCODE\" } }") _FETCH = ("function Fetch([string]$Url, [string]$Sha256, [string]$To) { for ($try = 1; ; $try++) { try { " - "Invoke-WebRequest -UseBasicParsing -Uri $Url -OutFile $To; break } catch { if ($try -ge " - f"{FETCH_TRIES}) {{ throw }}; Start-Sleep {FETCH_PAUSE_S} }} }}; $got = (Get-FileHash -Algorithm SHA256 $To)" - ".Hash.ToLower(); if ($got -ne $Sha256) { throw \"provision: $Url came with sha256 $got, not $Sha256\" } }") + "Invoke-WebRequest -UseBasicParsing -Uri $Url -OutFile $To; break } catch { " + "$status = [int]$_.Exception.Response.StatusCode; " + f"if ($try -ge {FETCH_TRIES} -or ($status -ge 400 -and $status -lt 500 -and $status -notin 408, 429)) " + f"{{ throw }}; Start-Sleep {FETCH_PAUSE_S} }} }}; $got = (Get-FileHash -Algorithm SHA256 $To).Hash.ToLower(); " + "if ($got -ne $Sha256) { throw \"provision: $Url came with sha256 $got, not $Sha256\" } }") From 368de02943e4d22dcb9b35a8c168c3bc41c1decf Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sun, 8 Nov 2026 10:10:51 -0800 Subject: [PATCH 20/20] refactor(computer): a Windows app's folder from one place, its access granted by named accounts The Windows compose takes an app's folder from its staged layer, as _stage_app already puts it under apps_folder; the well-known SIDs are named and one helper writes a folder's access alone; write() takes its user, build settings and image by name. A test reads what a provision line writes with one helper, and the scripts the Windows bundle's verifiers run inside the computer are checked to be Python, which no linter sees in a string. Co-Authored-By: Claude Opus 5.5 --- .../env/envs/computer/utils/composer.py | 7 +++--- .../env/envs/computer/utils/windows_disk.py | 21 +++++++++++------ tst/unit/env/envs/test_computer_windows.py | 23 +++++++++++++++---- 3 files changed, 37 insertions(+), 14 deletions(-) diff --git a/src/agent_env/env/envs/computer/utils/composer.py b/src/agent_env/env/envs/computer/utils/composer.py index fda3fa8d3..ae804017e 100644 --- a/src/agent_env/env/envs/computer/utils/composer.py +++ b/src/agent_env/env/envs/computer/utils/composer.py @@ -378,7 +378,8 @@ def _composed_windows_disk(env: ComputerEnv, base: ComputerArtifact, driver: Com for program, command in _services(f"driver-{name}", layer.install).items()}, {"MCP_PORT": driver.port}, protocol)] for app in env.composed_apps(): - staged, prefix = _stage_app(context, app, base, {}), windows_disk.APPS / gate.app_folder(app) + staged = _stage_app(context, app, base, {}) + prefix = PureWindowsPath(staged.prefix) server = [str(prefix / "venv" / "Scripts" / "python.exe"), "-m", "agentenv_protocol.computer.serve_app", staged.served] commands = [server, *(windows_disk.argv(service.command, prefix) for service in staged.install.services)] @@ -397,8 +398,8 @@ def say(line: str) -> None: made = windows_disk.base(_key(recipe=_digest(windows_disk.RECIPE), disk_gb=disk_gb, user=user, form="windows-base", format=FORMAT), lambda: windows_disk.media(say), disk_gb, user, say, registry) - script = windows_disk.write(build, parts, user, settings, - {"base": made.image, "layers": [part.folder for part in parts]}) + script = windows_disk.write(build, parts, user=user, build_settings=settings, + image={"base": made.image, "layers": [part.folder for part in parts]}) expires = made.expires.isoformat(timespec="seconds") key = attempt.key = _key(base=made.image, base_expires=expires, provision=script, context=_digest(context), build_settings=settings, form="disk", arch=arch, format=FORMAT) 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 671819dec..3e5526397 100644 --- a/src/agent_env/env/envs/computer/utils/windows_disk.py +++ b/src/agent_env/env/envs/computer/utils/windows_disk.py @@ -29,7 +29,6 @@ from typing import Any, NamedTuple from agentenv_protocol.computer.app import ADDRESS -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 @@ -51,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", apps_folder("windows") +DRIVERS = ROOT / "drivers" PYTHON = ROOT / "python" / "python.exe" BUILD = ROOT / "build" #: The fewest days of its evaluation a base may have left, as a deploy needs some. @@ -73,6 +72,9 @@ #: a rate limit, fails at once, as no retry mends a wrong URL. FETCH_TRIES, FETCH_PAUSE_S = 30, 10 CPUS, MEMORY_MB = 4, 8192 +#: The groups and the account the folders under ``ROOT`` grant access to, by their well-known SIDs, as icacls takes +#: them. +ADMINISTRATORS, SYSTEM, USERS = "*S-1-5-32-544", "*S-1-5-18", "*S-1-5-32-545" #: What every service runs with: Python reading and writing files as UTF-8, as on Linux, not in Windows' code page. UTF8 = {"PYTHONUTF8": "1"} #: What a base's install prints once, as it fetches Microsoft's media. @@ -330,7 +332,7 @@ def expiring(expires: str | None) -> bool: return expires is None or datetime.fromisoformat(expires) - datetime.now(timezone.utc) < timedelta(days=RENEW_DAYS) -def write(build: Path, parts: list[Part], user: str, build_settings: dict[str, Any], image: dict) -> str: +def write(build: Path, parts: list[Part], *, user: str, build_settings: dict[str, Any], image: dict) -> str: """Write ``build``'s ``provision.ps1``, which installs ``parts`` from ``build/context``, each app's own folder the session user ``user``'s, their services for agentenv-session, ``build_settings`` as every service's ``AGENTENV_SETTING_`` and ``image`` as what the disk says it holds, then leaves ``ROOT`` the admins' @@ -351,8 +353,7 @@ def _locked(user: str) -> list[str]: """The lines that leave ``ROOT`` the admins', as on Linux ``/opt/agentenv`` is root's: every user reads and runs what's there, none of the access ``C:\\`` gives every user to change it is left, and the session user ``user`` writes only the services' logs, and each app's own folder, which keeps its own access.""" - return [f"Checked {{ icacls '{ROOT}' /inheritance:r /grant:r '*S-1-5-32-544:(OI)(CI)F' '*S-1-5-18:(OI)(CI)F' " - "'*S-1-5-32-545:(OI)(CI)RX' | Out-Null }", + return [_granted_alone(ROOT, {ADMINISTRATORS: "F", SYSTEM: "F", USERS: "RX"}), f"Checked {{ icacls '{ROOT / 'logs'}' /grant {_ps(f'{user}:(OI)(CI)M')} | Out-Null }}"] @@ -380,8 +381,7 @@ def _installed_part(part: Part, user: str) -> list[str]: if part.served is not None: own = prefix / ADDRESS.parent.as_posix() lines += [f"New-Item -ItemType Directory -Force '{own}' | Out-Null", - f"Checked {{ icacls '{own}' /inheritance:r /grant:r {_ps(f'{user}:(OI)(CI)F')} '*S-1-5-18:(OI)(CI)F' " - "'*S-1-5-32-544:(OI)(CI)F' | Out-Null }"] + _granted_alone(own, {user: "F", SYSTEM: "F", ADMINISTRATORS: "F"})] for run in install.run or []: lines.append(f"$env:PREFIX = '{prefix}'; Push-Location '{prefix}'; Checked {{ & powershell -NoProfile " f"-ExecutionPolicy Bypass -File '{prefix / PureWindowsPath(run.script)}' }}; Pop-Location") @@ -395,6 +395,13 @@ def _installed_part(part: Part, user: str) -> list[str]: return lines +def _granted_alone(folder: PureWindowsPath, access: dict[str, str]) -> str: + """The line that leaves ``folder`` with only ``access``, rights by account, which what's under it inherits, and + none of the access its parents give.""" + granted = " ".join(_ps(f"{account}:(OI)(CI){rights}") for account, rights in access.items()) + return f"Checked {{ icacls '{folder}' /inheritance:r /grant:r {granted} | Out-Null }}" + + def argv(command: str, prefix: PureWindowsPath) -> list[str]: """A service's ``command`` as the argv agentenv-session runs, split as Windows quotes it, a word in double quotes one word without them, and a relative program named under ``prefix``.""" diff --git a/tst/unit/env/envs/test_computer_windows.py b/tst/unit/env/envs/test_computer_windows.py index f6946ae4f..3803fc587 100644 --- a/tst/unit/env/envs/test_computer_windows.py +++ b/tst/unit/env/envs/test_computer_windows.py @@ -4,8 +4,9 @@ machine holds it, its agentenv folder left the admins' and the session user's to read; the env's computer is a disk of the base's form. An app's own server runs from its venv, its own folder the session user's alone, its install steps elevated; one it runs as the session user is refused. A Windows base is amd64, disk-only and started by -agentenv-session.""" +agentenv-session. The scripts the Windows test bundle's verifiers run inside the computer are Python.""" +import ast import json import threading import time @@ -31,6 +32,7 @@ from agent_env.providers.sandbox_providers.sandbox_provider import SandboxProvider URL = "https://example.com/desk.zip" +BUNDLE = Path(__file__).parents[3] / "integration" / "computer" / "windows" SERVE = "venv/Scripts/python.exe -m agentenv_protocol.computer.serve driver.py:Desk" WINDOWS = {"type": "windows", "version": "11", "edition": "Enterprise Evaluation"} DISK = {"init": "agentenv-session", "input_channel": "nocloud", "min_disk_gb": 64} @@ -155,6 +157,11 @@ def _put(driver: ComputerDriverEnv, link: SandboxProvider, apps: list[ComputerAp computer_settings=settings or None, apps=apps or []) +def _written_json(line: str) -> object: + """The JSON a provision script's line writes to its file (``windows_disk._written``).""" + return json.loads(line.split(", '", 1)[1].rsplit("')", 1)[0].replace("''", "'")) + + def test_a_windows_env_composes_a_thin_disk_on_its_base_here_the_driver_installed_by_its_provision_script( docker, tmp_path): env = _put(_driver(tmp_path / "desk"), FakeLinux(), theme="dark") @@ -177,7 +184,7 @@ def test_a_windows_env_composes_a_thin_disk_on_its_base_here_the_driver_installe assert any(line.startswith(f"Checked {{ & '{prefix}\\venv\\Scripts\\python.exe' -m pip install") and f"'-r' '{prefix}\\requirements-windows.txt'" in line for line in lines) daemon = next(line for line in lines if "services\\driver-desk-daemon.json" in line) - assert json.loads(daemon.split(", '", 1)[1].rsplit("')", 1)[0].replace("''", "'")) == { + assert _written_json(daemon) == { "name": "driver-desk-daemon", "prefix": str(prefix), "command": [str(prefix / "venv/Scripts/python.exe"), "driver.py"], "env": {"PYTHONUTF8": "1", "MCP_PORT": "18765"}} assert lines[-3:] == [ @@ -216,8 +223,7 @@ def test_an_app_is_a_layer_of_its_own_its_server_on_its_venv_its_folder_the_sess f"Bypass -File '{prefix}\\setup.ps1' }}; Pop-Location", f"Push-Location '{prefix}'; Checked {{ & '{python}' -m agentenv_protocol.computer.run_install_step " "'app.py:Notes' 'stamp' }; Pop-Location"] - services = {spec["name"]: spec for spec in (json.loads(line.split(", '", 1)[1].rsplit("')", 1)[0].replace( - "''", "'")) for line in installed if "\\services\\" in line)} + services = {spec["name"]: spec for spec in (_written_json(line) for line in installed if "\\services\\" in line)} environment = {"PYTHONUTF8": "1", "ENVIRONMENT_NAME": "notes"} assert services == { "app-notes": {"name": "app-notes", "prefix": str(prefix), "env": environment, @@ -428,3 +434,12 @@ def run(argv, **kwargs): assert ran == [["docker", "run", "--rm", "-v", f"{tmp_path}:/out", *args, "--entrypoint", "qemu-img", "machine:1", "convert", "-O", "qcow2", *over, "/out/disk.img", "/out/compact.img"]] assert (tmp_path / "disk.img").read_text() == "compacted" and not (tmp_path / "compact.img").exists() + + +@pytest.mark.parametrize("artifact, script", [("check_notes", "FACTS"), ("check_session", "SESSION")]) +def test_the_scripts_the_windows_bundles_verifiers_run_inside_the_computer_are_python(artifact, script): + verifier = ast.parse((BUNDLE / "artifacts" / artifact / "verify.py").read_text()) + (text,) = [node.value.value for node in verifier.body + if isinstance(node, ast.Assign) and [target.id for target in node.targets] == [script]] + + ast.parse(text)