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
10 changes: 7 additions & 3 deletions packages/agentenv-protocol/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -793,7 +793,8 @@ class MailApp(ComputerAppEnvironment):
it runs on (`platform.detect()`).
- **`launch=Launch(...)`** says how it starts in the desktop session: with it (`at="boot"`) or when
the agent opens it (`"demand"`). `ready=Ready(...)` says when it's ready, within `timeout_s` of its
launch: a window matching `launch.window` by its class, instance or title, a port answering on
launch: a window matching `launch.window` by its class, instance or title (on Hyprland, a Wayland
app ID or an X window's class, its program's file name, and its title), a port answering on
loopback, or a command exiting 0. `env` sets variables in the app's environment, over its server's. `@ready_check` marks a method for readiness that needs logic (a
sync one runs in a thread), and `@install_step(scope=...)` one a computer runs as it installs the
app, after its run scripts, offline and without the class's `__init__`. Each runs on every OS the
Expand Down Expand Up @@ -827,13 +828,16 @@ desktop session, and `ready` (GET: an `AppReadiness` of `ready`, `problems`, `la
and `timeout_s`), which runs the app's readiness checks then, at once, each within 10 s. A server
that can't start, or whose start in the session fails (adding the launcher, say), writes why to
`.agentenv/server.failure` in the folder and exits, and the driver reports that in its place. Once
the X display is up, when `DISPLAY` names one, the server adds the app's launcher to the session user's
the session is up, the X display when `DISPLAY` names one or on Hyprland its Wayland display and its
IPC, the server adds the app's launcher to the session user's
menu, which runs `python -m agentenv_protocol.computer.launch <folder>` to ask the server, so the
server starts every copy of the app, and launches a `boot` app, once per boot. An app that runs with
no desktop, a website browser alone, gets no launcher. The driver finds each app by the socket in its
folder: the computer is ready once every app's server answers and each `boot` app, and each app with
no launch, says it's ready; a `demand` app counts once something launches it. What the server does
in the session (`agentenv_protocol.computer.session`) is Linux's.
in the session (`agentenv_protocol.computer.session`) is Linux's. On Hyprland it lists windows through
Hyprland's IPC (`hyprctl -j clients`), which sees native Wayland windows and XWayland's alike, where
X's `xprop` sees only XWayland's.

The server serves the app's data plane and its skill. With `paths` alone, `data/add` writes the files
it's given under them and refuses any other path, or one a link leads out of them; `data/get`
Expand Down
Original file line number Diff line number Diff line change
@@ -1,10 +1,12 @@
"""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."""
session, or on Hyprland for its Wayland and IPC sockets, 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 session's windows, X's with ``xprop`` or
Hyprland's with ``hyprctl``."""
from __future__ import annotations

import asyncio
import contextlib
import json
import os
import re
import signal
Expand All @@ -21,9 +23,13 @@


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():
"""Until the session's sockets are there: on Hyprland its Wayland display's and its IPC's, else the X display's."""
if signature := _hyprland():
runtime = Path(os.environ["XDG_RUNTIME_DIR"])
sockets = [runtime / os.environ["WAYLAND_DISPLAY"], runtime / "hypr" / signature / ".socket.sock"]
else:
sockets = [Path(f"/tmp/.X11-unix/X{os.environ['DISPLAY'].lstrip(':').split('.')[0]}")]
while not all(socket.exists() for socket in sockets):
await asyncio.sleep(POLL_S)


Expand Down Expand Up @@ -101,7 +107,11 @@ def add_launcher(name: str, folder: Path) -> Path:
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."""
read is left out. On Hyprland, its mapped clients as its IPC lists them, native Wayland and XWayland alike: its
``class``, a Wayland app ID or an X window's WM_CLASS class, and its ``title``, and as its ``instance``, which a
Wayland window hasn't, its program's file name, as on Windows."""
if _hyprland():
return await _clients()
listed = await _xprop("-root", "_NET_CLIENT_LIST")
found = []
for window in re.findall(r"0x[0-9a-f]+", listed.partition("#")[2]):
Expand All @@ -119,8 +129,37 @@ def _strings(value: str) -> list[str]:
return [re.sub(r"\\(.)", r"\1", text) for text in re.findall(r'"((?:[^"\\]|\\.)*)"', value)]


def _hyprland() -> str | None:
"""The Hyprland instance whose session this is, by its signature; None outside one."""
return os.environ.get("HYPRLAND_INSTANCE_SIGNATURE") or None


async def _clients() -> list[dict[str, str]]:
"""Hyprland's mapped clients, by their program, class and title; none when its IPC doesn't answer."""
try:
clients = json.loads(await _output("hyprctl", "-j", "clients") or "[]")
except ValueError:
return []
return [{"instance": _program(client.get("pid")), "class": client.get("class") or "",
"title": client.get("title") or ""}
for client in clients if isinstance(client, dict) and client.get("mapped")]


def _program(pid: object) -> str:
"""The file name of the program process ``pid`` runs, or "" when it can't be read."""
try:
return Path(os.readlink(f"/proc/{int(pid)}/exe")).name
except (OSError, TypeError, ValueError):
return ""


async def _xprop(*args: str) -> str:
process = await asyncio.create_subprocess_exec("xprop", *args, stdout=asyncio.subprocess.PIPE,
return await _output("xprop", *args)


async def _output(*argv: str) -> str:
"""What ``argv`` prints, or nothing when it fails; killed when the listing it's part of is cut short."""
process = await asyncio.create_subprocess_exec(*argv, stdout=asyncio.subprocess.PIPE,
stderr=asyncio.subprocess.DEVNULL)
try:
out, _ = await process.communicate()
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -187,7 +187,8 @@ class Launch(BaseModel):
at: Literal["boot", "demand"] = "boot"
command: list[str]
#: 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``.
#: instance; on Hyprland its class, a Wayland app ID or an X window's WM_CLASS class, and its program's file name;
#: 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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -80,14 +80,14 @@ def __init__(self, launch: Optional[Launch], ready_checks: dict[str, Callable[[]
self.checking: dict[str, asyncio.Future] = {}

async def start(self) -> None:
"""Once its X display is up, when it has one, add the app's menu launcher on a desktop and launch a boot app,
unless the computer has launched it since it booted, at boot or on demand, or its boot launch is held
(``boot_launch_held``): a server that restarts leaves the app be, or with ``relaunch_on_start``, for an app
only the server that launched it can talk to, stops it and launches it again, whether it was launched at boot
or on demand."""
"""Once its session is up, its X display or Hyprland, when it has one, add the app's menu launcher on a desktop
and launch a boot app, unless the computer has launched it since it booted, at boot or on demand, or its boot
launch is held (``boot_launch_held``): a server that restarts leaves the app be, or with ``relaunch_on_start``,
for an app only the server that launched it can talk to, stops it and launches it again, whether it was
launched at boot or on demand."""
if self.launch is None:
return
if os.environ.get("DISPLAY"):
if os.environ.get("DISPLAY") or os.environ.get("HYPRLAND_INSTANCE_SIGNATURE"):
await session.wait_until_up()
if self.desktop:
session.add_launcher(os.environ["ENVIRONMENT_NAME"], Path.cwd())
Expand Down
87 changes: 86 additions & 1 deletion packages/agentenv-protocol/tests/test_computer_app_server.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
import asyncio
import contextlib
import importlib.util
import json
import os
import shlex
import signal
Expand Down Expand Up @@ -443,6 +444,7 @@ def test_the_launcher_runs_the_app_through_its_own_server(tmp_path, monkeypatch)

@pytest.mark.asyncio
async def test_the_sessions_windows_are_listed_by_class_instance_and_title_from_either_name(monkeypatch):
monkeypatch.delenv("HYPRLAND_INSTANCE_SIGNATURE", raising=False)
replies = {("-root", "_NET_CLIENT_LIST"): "_NET_CLIENT_LIST(WINDOW): window id # 0x1e00004, 0x2000003, 0x2200001\n",
("-id", "0x1e00004", "WM_CLASS", "_NET_WM_NAME", "WM_NAME"):
'_NET_WM_NAME(UTF8_STRING) = "Inbox \\"work\\""\nWM_CLASS(STRING) = "mail", "Mail"\n'
Expand All @@ -460,7 +462,9 @@ async def xprop(*args):


@pytest.mark.asyncio
async def test_a_window_listing_cut_short_kills_its_xprop(monkeypatch):
@pytest.mark.parametrize("hyprland", ["", "sig"])
async def test_a_window_listing_cut_short_kills_its_xprop_or_hyprctl(hyprland, monkeypatch):
monkeypatch.setenv("HYPRLAND_INSTANCE_SIGNATURE", hyprland)
started, spawn = [], asyncio.create_subprocess_exec

async def hanging(*args, **kwargs):
Expand All @@ -474,6 +478,87 @@ async def hanging(*args, **kwargs):
assert await asyncio.wait_for(started[0].wait(), 5) == -signal.SIGKILL


@pytest.mark.asyncio
async def test_on_hyprland_the_sessions_windows_are_its_mapped_clients_by_program_class_and_title(monkeypatch):
clients = [{"address": "0x55d1", "mapped": True, "class": "org.gnome.Nautilus", "title": "Home", "pid": 41,
"xwayland": False},
{"address": "0x55d2", "mapped": True, "class": "BenchLab", "title": "Bench Lab", "pid": 42,
"xwayland": True},
{"address": "0x55d3", "mapped": False, "class": "closing", "title": "", "pid": 43},
{"address": "0x55d4", "mapped": True, "class": "gone", "title": "Gone", "pid": 44}]
programs = {"/proc/41/exe": "/usr/bin/nautilus", "/proc/42/exe": "/usr/bin/python3.14"}
asked = []

async def output(*argv):
asked.append(argv)
return json.dumps(clients)

def readlink(path):
if path not in programs:
raise FileNotFoundError(path)
return programs[path]

monkeypatch.setenv("HYPRLAND_INSTANCE_SIGNATURE", "sig")
monkeypatch.setattr(_session_posix, "_output", output)
monkeypatch.setattr(_session_posix.os, "readlink", readlink)

assert await session.windows() == [{"instance": "nautilus", "class": "org.gnome.Nautilus", "title": "Home"},
{"instance": "python3.14", "class": "BenchLab", "title": "Bench Lab"},
{"instance": "", "class": "gone", "title": "Gone"}]
assert asked == [("hyprctl", "-j", "clients")]


@pytest.mark.asyncio
async def test_on_hyprland_a_session_whose_ipc_doesnt_answer_has_no_windows(monkeypatch):
async def output(*argv):
return ""

monkeypatch.setenv("HYPRLAND_INSTANCE_SIGNATURE", "sig")
monkeypatch.setattr(_session_posix, "_output", output)
assert await session.windows() == []


@pytest.mark.asyncio
async def test_on_hyprland_the_session_is_up_once_its_wayland_and_ipc_sockets_are_there(tmp_path, monkeypatch):
monkeypatch.setenv("HYPRLAND_INSTANCE_SIGNATURE", "sig")
monkeypatch.setenv("XDG_RUNTIME_DIR", str(tmp_path))
monkeypatch.setenv("WAYLAND_DISPLAY", "wayland-1")
monkeypatch.setattr(_session_posix, "POLL_S", 0.01)
waiting = asyncio.ensure_future(session.wait_until_up())

(tmp_path / "wayland-1").touch()
await asyncio.sleep(0.05)
halfway = waiting.done()
(tmp_path / "hypr" / "sig").mkdir(parents=True)
(tmp_path / "hypr" / "sig" / ".socket.sock").touch()
await asyncio.wait_for(waiting, 5)

assert not halfway


@pytest.mark.asyncio
@pytest.mark.parametrize(("variables", "waits"), [({}, 0), ({"DISPLAY": ":0"}, 1),
({"HYPRLAND_INSTANCE_SIGNATURE": "sig"}, 1)])
async def test_a_boot_app_waits_for_its_x11_or_hyprland_session_and_for_none_without_one(
variables, waits, desktop, tmp_path, monkeypatch):
for name in ("DISPLAY", "HYPRLAND_INSTANCE_SIGNATURE"):
monkeypatch.delenv(name, raising=False)
for name, value in variables.items():
monkeypatch.setenv(name, value)
waited = []

async def up():
waited.append(True)

monkeypatch.setattr(session, "wait_until_up", up)
monkeypatch.setattr(session, "add_launcher", lambda name, folder: None)
monkeypatch.chdir(tmp_path)

await Mail()._computer_app.start()

assert len(waited) == waits


@contextlib.asynccontextmanager
async def _http(app: ComputerAppEnvironment):
asgi = app.create_app().streamable_http_app()
Expand Down
Loading