Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,13 @@
Ready,
RunScript,
Service,
Windows,
computer_app,
install,
install_step,
linux,
ready_check,
windows,
)
from .errors import (
BackgroundUnavailable,
Expand Down Expand Up @@ -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",
Expand Down
110 changes: 110 additions & 0 deletions packages/agentenv-protocol/src/agentenv_protocol/computer/_job.py
Original file line number Diff line number Diff line change
@@ -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:])
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -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 ""
Loading
Loading