agentenv-framework-protocol 0.1.455__tar.gz → 0.1.458__tar.gz

{agentenv_framework_protocol-0.1.455 → agentenv_framework_protocol-0.1.458}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.455
+Version: 0.1.458
 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.455 → agentenv_framework_protocol-0.1.458}/pyproject.toml

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

{agentenv_framework_protocol-0.1.455 → agentenv_framework_protocol-0.1.458}/src/agentenv_protocol/computer/_linux.py

@@ -1,5 +1,6 @@
-"""The base class's Linux defaults for the OS operations. The driver runs as the session user inside the desktop
-session, so both act directly: a command inherits the session's environment, a file lands as that user."""
+"""The base class's defaults for the OS operations on Linux and macOS, which use POSIX alone. The driver runs as the
+session user inside the desktop session, so both act directly: a command inherits the session's environment, a file
+lands as that user."""
 from __future__ import annotations
 
 import asyncio

{agentenv_framework_protocol-0.1.455 → agentenv_framework_protocol-0.1.458}/src/agentenv_protocol/computer/app.py

@@ -251,6 +251,15 @@ class AppDeclaration(BaseModel):
     ready_checks: list[AppReadyCheck]
     browser: Optional[bool] = None
 
+    @model_validator(mode="after")
+    def _no_window_wait_on_macos(self) -> AppDeclaration:
+        """A window's readiness is read from X11's windows, which macOS hasn't."""
+        launch = self.os["macos"].launch if "macos" in self.os else None
+        if launch is not None and launch.ready is not None and launch.ready.window:
+            raise ValueError("on macos an app's launch can't wait on its window, which is read from X11; wait on a "
+                             "port, a command or a @ready_check")
+        return self
+
     @model_validator(mode="before")
     @classmethod
     def _stored_before_each_os(cls, data: Any) -> Any:

{agentenv_framework_protocol-0.1.455 → agentenv_framework_protocol-0.1.458}/src/agentenv_protocol/computer/app_runtime.py

@@ -9,6 +9,7 @@ import json
 import os
 import shlex
 import signal
+import sys
 import time
 from collections.abc import Awaitable, Callable
 from datetime import datetime, timezone
@@ -22,8 +23,9 @@ from . import session
 if TYPE_CHECKING:
     from .app import Launch
 
-#: Where an app's server marks that it launched the app since the computer booted, at boot or on demand.
-LAUNCHED = Path("/run/agentenv/apps")
+#: 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")
 #: 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

{agentenv_framework_protocol-0.1.455 → agentenv_framework_protocol-0.1.458}/src/agentenv_protocol/computer/conformance/checks.py

@@ -48,6 +48,8 @@ MINIMUM_TOOLS = ("computer_screenshot", "computer_click", "computer_drag", "comp
 DATA_PLANE = (INTAKE_EXTENSION_URI, DATA_OBJECTS_EXTENSION_URI)
 #: Where the fixture is staged and keeps its state, relative to the session user's home.
 STAGE = ".agentenv-probe"
+#: How the probe reads a staged file's owner: through the python3 the fixture runs on, the same on every OS.
+OWNER = ("python3", "-c", "import os, sys; print(os.stat(sys.argv[1]).st_uid)")
 #: Where a page driver's computer_upload takes files from, relative to the session user's home.
 UPLOADS = "Uploads"
 #: What the probe answers the page fixture's prompt with.
@@ -605,7 +607,7 @@ class Probe:
     async def _security(self) -> None:
         async def one_user() -> str | None:
             uid = (await self.driver.run("id", "-u"))["stdout"].strip()
-            owner = (await self.driver.run("stat", "-c", "%u", f"{STAGE}/{self.fixture}"))["stdout"].strip()
+            owner = (await self.driver.run(*OWNER, f"{STAGE}/{self.fixture}"))["stdout"].strip()
             if uid == "0":
                 return "commands run as root"
             return None if owner == uid else f"data/add wrote as uid {owner}, commands run as uid {uid}"

{agentenv_framework_protocol-0.1.455 → agentenv_framework_protocol-0.1.458}/src/agentenv_protocol/computer/driver.py

@@ -205,13 +205,13 @@ class ComputerDriverEnvironment(Tools, Extensions, DataPlane, AgentEnvEnvironmen
         if self._computer is None:
             raise TypeError(f"{type(self).__qualname__}.__init__ must call super().__init__()")
 
-    # The Linux defaults for the OS operations.
+    # The defaults for the OS operations on Linux and macOS, POSIX alike.
 
-    @default_for("run_in_session", os="linux")
+    @default_for("run_in_session", os=["linux", "macos"])
     async def _computer_linux_run_in_session(self, argv: list, cwd: str | None, env: dict | None, timeout_s: float):
         return await _linux.run_in_session(argv, cwd, env, timeout_s, output_bytes=self.settings.exec_output_bytes)
 
-    @default_for("write_files", os="linux")
+    @default_for("write_files", os=["linux", "macos"])
     async def _computer_linux_write_files(self, files: dict) -> None:
         await asyncio.to_thread(_linux.write_files, files)
 

{agentenv_framework_protocol-0.1.455 → agentenv_framework_protocol-0.1.458}/src/agentenv_protocol/computer/platform.py

@@ -27,13 +27,15 @@ class Platform:
 
 
 def detect(environ: dict | None = None, os_release: Path = Path("/etc/os-release")) -> Platform:
-    """The running platform: the OS, ``/etc/os-release``'s ID and VERSION_ID on Linux, the machine, and the
-    display from ``XDG_SESSION_TYPE``, ``none`` for a computer with no display, else ``DISPLAY`` (x11) or
-    ``WAYLAND_DISPLAY`` (wayland)."""
+    """The running platform: the OS, ``/etc/os-release``'s ID and VERSION_ID on Linux and the macOS version on macOS,
+    the machine, and the display: on Linux from ``XDG_SESSION_TYPE``, ``none`` for a computer with no display, else
+    ``DISPLAY`` (x11) or ``WAYLAND_DISPLAY`` (wayland); on macOS Aqua."""
     environ = os.environ if environ is None else environ
     name = _OS.get(sys.platform, sys.platform)
     release = _os_release(os_release) if name == "linux" else {}
-    display = None
+    if name == "macos":
+        release = {"VERSION_ID": _platform.mac_ver()[0] or None}
+    display = "aqua" if name == "macos" else None
     if name == "linux":
         session = (environ.get("XDG_SESSION_TYPE") or "").strip().lower()
         if session in ("x11", "wayland", "none"):

{agentenv_framework_protocol-0.1.455 → agentenv_framework_protocol-0.1.458}/src/agentenv_protocol/computer/recording.py

@@ -52,6 +52,8 @@ FAILING_S = 60.0
 GAP_S = 2.0
 #: How long a stream that stopped or failed waits before it is started again.
 RETRY_S = 1.0
+#: How long a recording's start waits for its first frame, so a recording a start answered for is recording.
+FIRST_FRAME_S = 5.0
 #: How often free disk is checked while frames arrive.
 DISK_CHECK_S = 5.0
 KEEP_ENDED = 64
@@ -127,8 +129,9 @@ def recording_params(recording: Recording, streams: bool) -> dict:
 
 
 class Recordings:
-    """The recordings of one driver: started by request id, open ones counted against ``max_concurrent``, ended
-    ones kept with their manifests so a repeated ``end`` answers the same."""
+    """The recordings of one driver: started by request id, each start answering once its recording is recording, open
+    ones counted against ``max_concurrent``, ended ones kept with their manifests so a repeated ``end`` answers the
+    same."""
 
     def __init__(self, runtime: ComputerRuntime) -> None:
         self.runtime = runtime
@@ -144,7 +147,9 @@ class Recordings:
             raise InvalidArgument("request_id is a non-empty string")
         async with self._lock:
             if request_id in self.started:
-                return self.started[request_id]
+                answer = self.started[request_id]
+                await self._live(self.running.get(answer["recording_id"]))
+                return answer
             hints, grant = self._hints(features, scope, window, fps, max_edge, cursor, upload)
             stopped = [rid for rid, r in self.running.items() if r.done]
             for rid in stopped[:max(0, len(stopped) - KEEP_ENDED)]:  # stopped by itself and never ended
@@ -164,8 +169,16 @@ class Recordings:
             self.started[request_id] = answer
             while len(self.started) > KEEP_STARTED:
                 self.started.popitem(last=False)
+            await self._live(recording)
             return answer
 
+    @staticmethod
+    async def _live(recording: Optional[_Recording]) -> None:
+        """Wait up to FIRST_FRAME_S for ``recording``, one still running, to have its first frame."""
+        if recording is not None:
+            with contextlib.suppress(TimeoutError):
+                await asyncio.wait_for(recording.live.wait(), FIRST_FRAME_S)
+
     async def end(self, recording_id: str, upload: Optional[dict], reason: str) -> dict:
         if reason not in REASONS:
             raise InvalidArgument(f"reason is one of {list(REASONS)}, got {reason!r}")
@@ -219,6 +232,7 @@ class _Recording:
         self.ended_by: Optional[str] = None
         self.error: Optional[str] = None
         self.done = False
+        self.live = asyncio.Event()
         self.task: Optional[asyncio.Task] = None
         self.timer: Optional[asyncio.TimerHandle] = None
         self.released: Optional[asyncio.Future] = None
@@ -228,7 +242,11 @@ class _Recording:
         self._last_disk_check = 0.0
 
     async def run(self) -> None:
+        """Frames or segments from the source, recorded until the recording ends; ``live`` once it's recording: a
+        stream from its start, the fallback's polling from its first frame, which a busy computer is slow to take."""
         failing_since: Optional[float] = None
+        if self.streams:
+            self.live.set()
         try:
             while True:
                 try:
@@ -255,6 +273,7 @@ class _Recording:
                 await self._close()
             finally:
                 self.done = True
+                self.live.set()
                 self.released = asyncio.ensure_future(self._release())
 
     def expire(self) -> None:
@@ -315,6 +334,7 @@ class _Recording:
             path = self.hints.directory / f"{len(self.segments):04d}.mp4"
             self.encoder = await self._in_thread(_Encoder, path, frame.width, frame.height, self.hints.fps, at)
         await self._in_thread(self.encoder.add, frame, at)
+        self.live.set()
         self._check_disk()
 
     async def _add_segment(self, item: RecordedSegment) -> None:

{agentenv_framework_protocol-0.1.455 → agentenv_framework_protocol-0.1.458}/tests/probe_fake.py

@@ -39,7 +39,7 @@ from agentenv_protocol.computer import (
     upload,
 )
 from agentenv_protocol.computer import _linux as linux
-from agentenv_protocol.computer.conformance.checks import STAGE
+from agentenv_protocol.computer.conformance.checks import OWNER, STAGE
 from agentenv_protocol.computer.conformance.page_fixture import QUESTION, TITLE, TWO, TWO_TITLE
 
 CLIPBOARD = "agentenv-probe clipboard"
@@ -56,6 +56,7 @@ DESK_URL = "http://127.0.0.1:4343/"
 TITLES = {DESK_URL: TITLE, DESK_URL + TWO.lstrip("/"): TWO_TITLE}
 
 
+
 class FakeDesk:
     """What the Fixture Desk would record of the input the fake screen gets."""
 
@@ -202,7 +203,7 @@ class FixtureDriver(FakeDriver):
         if f"python3 {STAGE}/fixture.py" in text:
             self.desk.start()
             return ExecResult(0, b"4242\n")
-        if argv in (["id", "-u"], ["stat", "-c", "%u", f"{STAGE}/fixture.py"]):
+        if argv in (["id", "-u"], [*OWNER, f"{STAGE}/fixture.py"]):
             return ExecResult(0, b"1000\n")
         if argv[:1] in (["kill"], ["tail"]) or f"rm -rf {STAGE}/state" in text:
             return ExecResult(0)
@@ -320,10 +321,10 @@ class PageFixtureDriver(FixtureDriver):
             return ExecResult(0, b"4343") if self.desk.started else ExecResult(1)
         if argv[:1] == ["cat"] and argv[1].endswith("layout.json") and self.desk.started:
             return ExecResult(0, json.dumps(PAGE_LAYOUT).encode())
-        if argv == ["stat", "-c", "%u", f"{STAGE}/page_fixture.py"]:
+        if argv == [*OWNER, f"{STAGE}/page_fixture.py"]:
             return ExecResult(0, b"1000\n")
-        if argv == ["stat", "-c", "%u", f"{STAGE}/fixture.py"]:
-            return ExecResult(1, b"", b"stat: cannot statx: No such file or directory")
+        if argv == [*OWNER, f"{STAGE}/fixture.py"]:
+            return ExecResult(1, b"", b"FileNotFoundError: [Errno 2] No such file or directory")
         return super()._fixture(argv)
 
 

{agentenv_framework_protocol-0.1.455 → agentenv_framework_protocol-0.1.458}/tests/test_computer_app_server.py

@@ -6,6 +6,7 @@ from __future__ import annotations
 
 import asyncio
 import contextlib
+import importlib.util
 import os
 import shlex
 import signal
@@ -109,6 +110,16 @@ async def test_an_apps_server_is_ready_once_it_launched_the_app_and_each_check_p
     assert after["ready"] is True and after["problems"] == []
 
 
+
+@pytest.mark.parametrize("platform, folder", [("linux", "/run/agentenv/apps"), ("darwin", "/tmp/agentenv/apps")])
+def test_a_launch_is_marked_in_a_folder_a_boot_clears_and_the_session_user_writes(monkeypatch, platform, folder):
+    monkeypatch.setattr(sys, "platform", platform)
+    spec = importlib.util.spec_from_file_location(f"agentenv_protocol.computer._app_runtime_on_{platform}",
+                                                  app_runtime.__file__)
+    loaded = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(loaded)
+    assert loaded.LAUNCHED == Path(folder)
+
 @pytest.mark.asyncio
 async def test_checks_that_fail_hang_or_raise_say_so_at_once_without_holding_up_the_server(desktop, monkeypatch):
     monkeypatch.setattr(app_runtime, "CHECK_TIMEOUT_S", 1.0)

{agentenv_framework_protocol-0.1.455 → agentenv_framework_protocol-0.1.458}/tests/test_computer_conformance.py

@@ -167,7 +167,7 @@ async def test_each_app_a_driver_fronts_that_exports_is_asked_for_its_export_onc
 
 @pytest.mark.asyncio
 async def test_a_driver_without_exec_or_data_add_passes_basic_and_leaves_full_unverified():
-    report = await _probe(MinimalDriver(FakeScreen(640, 400), platform=Platform(os="macos")))
+    report = await _probe(MinimalDriver(FakeScreen(640, 400), platform=Platform(os="windows")))
     assert report.passed, _failed(report)
     unverified = [c for c in report.checks if c.status == "unverified"]
     assert {c.check for c in unverified} == {"P3", "P4", "P5", "P6", "P7", "P9"}

{agentenv_framework_protocol-0.1.455 → agentenv_framework_protocol-0.1.458}/tests/test_computer_declare.py

@@ -264,6 +264,9 @@ def test_an_app_declaring_its_skill_twice_is_refused(folder):
      "Changed.fonts runs on 'windows', which Changed declares no install for; it declares freebsd, linux"),
     ('@ready_check(os="macos")\n    def window_shown(self): return True',
      "Changed.window_shown runs on 'macos', which Changed declares no install for"),
+    ('@install("macos", FreeBSD(), launch=Launch(command=["mail"], window={"class": "Mail"}, '
+     'ready=Ready(window=True)))',
+     "on macos an app's launch can't wait on its window, which is read from X11"),
     ('class BuildSettings(BaseModel): key: SecretStr = SecretStr("")',
      "Changed.BuildSettings holds a secret at properties.key, which its computer's image would keep; declare it in "
      "Settings"),
@@ -273,9 +276,9 @@ def test_an_app_declaring_its_skill_twice_is_refused(folder):
      "Changed.BuildSettings holds a secret at $defs.Settings.properties.password, which"),
 ], ids=["no-wait", "no-window", "window-key", "download-sha", "script-escape", "os-skill-twice", "os-build-secret",
         "step-os",
-        "check-os", "build-secret", "build-secrets-listed", "build-secret-nested"])
+        "check-os", "macos-window-wait", "build-secret", "build-secrets-listed", "build-secret-nested"])
 def test_an_app_whose_declaration_cant_be_checked_is_refused_saying_why(folder, capsys, change, problem):
-    decorator, body = (change, "pass") if change.startswith("@linux") else ("", change)
+    decorator, body = (change, "pass") if change.startswith(("@linux", "@install(")) else ("", change)
     (folder / "app.py").write_text(APP.format(supports=LINUX, sha='a' * 64) + f"""
 
 @computer_app(supports={LINUX})

{agentenv_framework_protocol-0.1.455 → agentenv_framework_protocol-0.1.458}/tests/test_computer_driver.py

@@ -45,6 +45,8 @@ from agentenv_protocol.computer.settings import load_settings  # noqa: E402
 from agentenv_protocol.computer.tools import _modifiers  # noqa: E402
 
 MACOS = Platform(os="macos", arch="arm64")
+#: A platform the base class has no OS defaults for.
+WINDOWS = Platform(os="windows", arch="amd64")
 
 
 def _required(namespace: dict) -> dict:
@@ -130,7 +132,8 @@ def test_set_display_without_modes_is_refused():
 def test_a_driver_method_replaces_the_linux_default():
     Driver = _define({"run": run_in_session(lambda self, *a: None)})
     assert declared(Driver)["run_in_session"] == [("run", {})]
-    assert declared(MinimalDriver)["run_in_session"] == [("_computer_linux_run_in_session", {"os": frozenset({"linux"})})]
+    assert declared(MinimalDriver)["run_in_session"] == [("_computer_linux_run_in_session",
+                                                         {"os": frozenset({"linux", "macos"})})]
 
 
 def test_the_platform_is_detected(tmp_path, monkeypatch):
@@ -143,7 +146,8 @@ def test_the_platform_is_detected(tmp_path, monkeypatch):
     assert detect({"WAYLAND_DISPLAY": "wayland-0"}, release).display == "wayland"
     assert detect({}, tmp_path / "missing").as_dict() == {"os": "linux", "arch": "arm64"}
     monkeypatch.setattr("agentenv_protocol.computer.platform.sys.platform", "darwin")
-    assert detect({"DISPLAY": ":0"}, release) == Platform("macos", None, None, "arm64", None)
+    monkeypatch.setattr("agentenv_protocol.computer.platform._platform.mac_ver", lambda: ("26.5.2", ("", "", ""), ""))
+    assert detect({"DISPLAY": ":0"}, release) == Platform("macos", None, "26.5.2", "arm64", "aqua")
 
 
 def test_settings_come_from_one_json_value():
@@ -222,7 +226,7 @@ async def test_a_driver_whose_software_ships_a_skill_leads_with_it_and_the_compu
 
 @pytest.mark.asyncio
 async def test_a_minimal_driver_declares_only_what_it_has():
-    async with http_client(MinimalDriver(platform=MACOS)) as http:
+    async with http_client(MinimalDriver(platform=WINDOWS)) as http:
         card = (await http.get("/.well-known/agent-env.json")).json()
         display_set = await http.post("/agentenv/ext/computer-display/set", json={"width": 1, "height": 1})
         exec_run = await http.post("/agentenv/ext/computer-exec/run", json={"argv": ["true"], "request_id": "r"})
@@ -449,14 +453,14 @@ def test_a_driver_class_declares_what_it_serves_on_each_platform(monkeypatch):
             raise AssertionError("declaration builds the card without the subclass's __init__")
 
     linux = Declared.declaration(LINUX)
-    elsewhere = MinimalDriver.declaration(Platform(os="macos"))
+    elsewhere = MinimalDriver.declaration(Platform(os="windows"))
     uris = lambda card: {e.uri for e in card.capabilities.extensions}  # noqa: E731
     assert linux.name == "declared" and len(linux.capabilities.tools) == 14
     assert {"urn:agentenv:computer-pointer/v1", "urn:agentenv:computer-exec/v1"} <= uris(linux)
     assert elsewhere.name == "MinimalDriver" and len(elsewhere.capabilities.tools) == 7
     assert "urn:agentenv:computer-exec/v1" not in uris(elsewhere)
     computer = next(e for e in elsewhere.capabilities.extensions if e.uri == "urn:agentenv:computer/v1")
-    assert computer.params["platform"] == {"os": "macos"}
+    assert computer.params["platform"] == {"os": "windows"}
 
 
 def test_a_supports_entry_names_each_platform_it_covers():

{agentenv_framework_protocol-0.1.455 → agentenv_framework_protocol-0.1.458}/tests/test_computer_recording.py

@@ -176,6 +176,27 @@ async def test_the_fallback_polls_capture_and_draws_the_pointer(home):
     assert _at(manifest["started_at"]) <= _at(manifest["ended_at"])
 
 
+@pytest.mark.asyncio
+async def test_a_start_answers_once_its_recording_has_its_first_frame_however_slow_the_capture(home):
+    driver = Recorded()
+    driver.slow["capture"] = 0.5
+    async with http_client(driver) as http:
+        began = time.monotonic()
+        started = (await http.post(START, json={"request_id": "r", "fps": 10})).json()
+        took = time.monotonic() - began
+        recording = driver._computer.recordings.running[started["recording_id"]]
+        assert took >= 0.5 and recording.encoder is not None and recording.encoder.frames >= 1
+        await http.post(END, json={"recording_id": started["recording_id"]})
+
+        recordings = driver._computer.recordings
+        with pytest.raises(TimeoutError):
+            await asyncio.wait_for(recordings.start("cancelled", "display", None, 10, None, True, None), 0.1)
+        retried = await recordings.start("cancelled", "display", None, 10, None, True, None)
+        running = [r for r in recordings.running.values() if not r.done]
+        assert [r.id for r in running] == [retried["recording_id"]] and running[0].encoder.frames >= 1
+        await http.post(END, json={"recording_id": retried["recording_id"]})
+
+
 @pytest.mark.asyncio
 async def test_a_driver_without_the_pointer_group_records_without_a_cursor(home):
     _, manifest = await _record(MinimalDriver(), 0.4)