agentenv-framework-protocol 0.1.484__tar.gz → 0.1.486__tar.gz

{agentenv_framework_protocol-0.1.484 → agentenv_framework_protocol-0.1.486}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.484
+Version: 0.1.486
 Summary: Open data-plane protocol and server SDK for agent environments.
 Project-URL: Homepage, https://www.agentenvframework.com
 Project-URL: Documentation, https://www.agentenvframework.com/docs

{agentenv_framework_protocol-0.1.484 → agentenv_framework_protocol-0.1.486}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentenv-framework-protocol"
-version = "0.1.484"
+version = "0.1.486"
 description = "Open data-plane protocol and server SDK for agent environments."
 readme = "README.md"
 license = "Apache-2.0"

{agentenv_framework_protocol-0.1.484 → agentenv_framework_protocol-0.1.486}/src/agentenv_protocol/computer/__init__.py

@@ -21,11 +21,13 @@ from .app import (
     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",

agentenv_framework_protocol-0.1.486/src/agentenv_protocol/computer/_job.py

@@ -0,0 +1,110 @@
+"""Run a Windows app in a Job object that holds it and everything it starts: ``python -I -S _job.py -- <argv>``. 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]
+    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
+
+
+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:])

agentenv_framework_protocol-0.1.486/src/agentenv_protocol/computer/_reaping.py

@@ -0,0 +1,53 @@
+"""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; 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)
+
+
+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

agentenv_framework_protocol-0.1.484/src/agentenv_protocol/computer/session.py → agentenv_framework_protocol-0.1.486/src/agentenv_protocol/computer/_session_posix.py

@@ -1,5 +1,6 @@
-"""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 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
@@ -11,16 +12,12 @@ 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")
-#: 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
 
 
 async def wait_until_up() -> None:
@@ -39,38 +36,14 @@ async def launch(argv: list[str], cwd: Path, env: dict[str, str], fds: Optional[
     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())
+    _reaping.reap(process)
     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)
+    _reaping.forget(pid)
     try:
         os.killpg(pid, signal.SIGTERM)
     except ProcessLookupError:

agentenv_framework_protocol-0.1.486/src/agentenv_protocol/computer/_session_windows.py

@@ -0,0 +1,317 @@
+"""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, NamedTuple, 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")
+#: 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.
+POLL_S = 0.2
+#: 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.
+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(
+        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:
+        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, 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:
+        return
+    try:
+        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)
+        while _app_pids(job, pid) and time.monotonic() < deadline:
+            await asyncio.sleep(POLL_S)
+        if _app_pids(job, pid):
+            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)
+
+
+@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. 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, seen = [], {pid}
+    try:
+        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:
+            _win32.resume(app_pid)
+        _win32.close(job)
+
+
+def alive(pid: int) -> bool:
+    """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
+    try:
+        return bool(_win32.job_pids(job))
+    finally:
+        _win32.close(job)
+
+
+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, 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
+    #: 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[_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().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().kernel32
+        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().kernel32.TerminateJobObject(job, 1):
+            raise ctypes.WinError(ctypes.get_last_error())
+
+    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,
+                                     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().ntdll.NtResumeProcess(process))
+
+    def post_close(self, window: int) -> None:
+        self._api().user32.PostMessageW(window, WM_CLOSE, 0, 0)
+
+    def windows(self) -> list[Window]:
+        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)
+        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(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))
+            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(self.PATH_CHARS), ctypes.c_uint32(self.PATH_CHARS)
+            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 ""
+
+    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().kernel32
+        process = kernel32.OpenProcess(access, False, pid)
+        if not process:
+            return None
+        try:
+            return act(process)
+        finally:
+            kernel32.CloseHandle(process)
+
+    def _api(self) -> _Dlls:
+        """The DLLs this class calls, bound on first use, so this module imports anywhere."""
+        if self._dlls is None:
+            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 = _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):
+        _fields_ = [("NumberOfAssignedProcesses", ctypes.c_uint32), ("NumberOfProcessIdsInList", ctypes.c_uint32),
+                    ("ProcessIdList", ctypes.c_size_t * room)]
+    return Listed
+
+
+_win32 = _Win32()

{agentenv_framework_protocol-0.1.484 → agentenv_framework_protocol-0.1.486}/src/agentenv_protocol/computer/app.py

@@ -41,11 +41,14 @@ _PATHS = TypeAdapter(list[RelativePath])
 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.
+#: 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")
+#: 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")
@@ -145,6 +148,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 +186,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 +355,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