agentenv-framework-protocol 0.1.493__tar.gz → 0.1.495__tar.gz

{agentenv_framework_protocol-0.1.493 → agentenv_framework_protocol-0.1.495}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.493
+Version: 0.1.495
 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
@@ -854,8 +854,13 @@ class MailApp(ComputerAppEnvironment):
   models whose fields add to the class's `Settings` and `BuildSettings` on that OS. What's on the
   class applies to every OS. `@install(os_type, spec, launch=..., ...)` is the generic form, for an
   OS type a plugin adds, with that OS type's own install model as `spec`; `@linux(...)` is
-  `@install("linux", Linux(...), ...)`. On the computer the class reads what's declared for the OS
-  it runs on (`platform.detect()`).
+  `@install("linux", Linux(...), ...)`. `@linux(distribution="omarchy", ...)`, or
+  `@install("linux/omarchy", ...)`, declares for one distribution, by its /etc/os-release ID, what
+  replaces the OS type's declaration there. On the computer the class reads what's declared for the
+  platform its computer was composed for, which the composer sets as `AGENTENV_PLATFORM` for an app
+  that declares anything for a distribution, else the one it runs on (`platform.detect()`): its
+  distribution's, else its OS type's. An install step or ready check's `os=` names OS types or
+  distributions, and one for an OS type runs on all of it.
 - **`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 (on Hyprland, a Wayland

{agentenv_framework_protocol-0.1.493 → agentenv_framework_protocol-0.1.495}/README.md

@@ -789,8 +789,13 @@ class MailApp(ComputerAppEnvironment):
   models whose fields add to the class's `Settings` and `BuildSettings` on that OS. What's on the
   class applies to every OS. `@install(os_type, spec, launch=..., ...)` is the generic form, for an
   OS type a plugin adds, with that OS type's own install model as `spec`; `@linux(...)` is
-  `@install("linux", Linux(...), ...)`. On the computer the class reads what's declared for the OS
-  it runs on (`platform.detect()`).
+  `@install("linux", Linux(...), ...)`. `@linux(distribution="omarchy", ...)`, or
+  `@install("linux/omarchy", ...)`, declares for one distribution, by its /etc/os-release ID, what
+  replaces the OS type's declaration there. On the computer the class reads what's declared for the
+  platform its computer was composed for, which the composer sets as `AGENTENV_PLATFORM` for an app
+  that declares anything for a distribution, else the one it runs on (`platform.detect()`): its
+  distribution's, else its OS type's. An install step or ready check's `os=` names OS types or
+  distributions, and one for an OS type runs on all of it.
 - **`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 (on Hyprland, a Wayland

{agentenv_framework_protocol-0.1.493 → agentenv_framework_protocol-0.1.495}/pyproject.toml

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

{agentenv_framework_protocol-0.1.493 → agentenv_framework_protocol-0.1.495}/src/agentenv_protocol/computer/app.py

@@ -29,7 +29,7 @@ from ..types import (METHOD_ADD, METHOD_GET, METHOD_RESET, SKILL_EXTENSION_URI,
 from .app_data import AppDataPlane
 from .app_runtime import AppRuntime
 from .errors import InvalidArgument
-from .platform import detect
+from .platform import PLATFORM_ENV, applies, detect, entry_for, platform_key
 
 #: 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"
@@ -327,7 +327,9 @@ def install(os_type: str, spec: BaseModel, *, launch: Optional[Launch] = None, p
     the app's own there: its ``launch``; the ``paths`` it keeps its data in, relative to the session user's home, which
     serve its data plane when it has no data hooks; its ``skill``, a file of its folder, instead of the class's; and
     ``settings`` and ``build_settings``, models whose fields add to the class's ``Settings`` and ``BuildSettings`` there.
-    ``@linux`` is this for Linux; an OS type a plugin adds is declared with it."""
+    ``os_type`` may name one of its distributions as ``<os>/<distribution>``, /etc/os-release's ID (``linux/omarchy``),
+    whose declaration replaces the OS type's there. ``@linux`` is this for Linux; an OS type a plugin adds is declared
+    with it."""
     try:
         owned = tuple(_PATHS.validate_python(list(paths or [])))
     except ValidationError:
@@ -344,16 +346,18 @@ def install(os_type: str, spec: BaseModel, *, launch: Optional[Launch] = None, p
     return deco
 
 
-def linux(*, files: str = ".", packages: Optional[Packages] = None, python: Optional[str] = None,
-          sources: Optional[list[AptSource]] = 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,
+def linux(*, distribution: Optional[str] = None, files: str = ".", packages: Optional[Packages] = None,
+          python: Optional[str] = None, sources: Optional[list[AptSource]] = 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 Linux: how a Linux computer installs the app, ``Linux``'s fields, and what is its own there."""
-    return install("linux", Linux(files=files, packages=packages, python=python, sources=sources, downloads=downloads,
-                                  run=run, services=services or [], ports=ports),
-                   launch=launch, paths=paths, skill=skill, settings=settings, build_settings=build_settings)
+    """``@install`` for Linux, or with ``distribution`` for that distribution alone: how such a computer installs the
+    app, ``Linux``'s fields, and what is its own there."""
+    spec = Linux(files=files, packages=packages, python=python, sources=sources, downloads=downloads, run=run,
+                 services=services or [], ports=ports)
+    return install(platform_key("linux", distribution), spec, 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,
@@ -459,18 +463,18 @@ class ComputerAppEnvironment(AgentEnvEnvironment):
         app declares its own, which its install steps read too. None is a secret, since the image keeps them."""
 
     def __init__(self) -> None:
-        cls, on = type(self), detect().os
+        cls, on = type(self), _here()
         values = json.loads(os.environ.get(APP_SETTINGS_ENV) or "{}").get(os.environ.get("ENVIRONMENT_NAME"), {})
         self.settings = cls.settings_on(on).model_validate(values)
         self.build_settings = _built_settings(cls, on)
-        declared = cls._installs.get(on)
+        declared = entry_for(cls._installs, on)
         launch = declared.launch if declared is not None else None
         self.launch = self._launch_for(launch) if launch is not None else None
         self.paths = list(declared.paths) if declared is not None else []
         ready = launch.ready if launch is not None else None
         self._computer_app = AppRuntime(
             self.launch, {fn.__name__: getattr(self, fn.__name__) for fn in _methods(cls)
-                          if hasattr(fn, _READY_CHECK_ATTR) and _runs_on(getattr(fn, _READY_CHECK_ATTR), on)},
+                          if hasattr(fn, _READY_CHECK_ATTR) and applies(getattr(fn, _READY_CHECK_ATTR), on)},
             ready.timeout_s if ready is not None else DEFAULT_TIMEOUT_S, desktop=self._on_desktop(),
             launch_fds=self._launch_fds, relaunch_on_start=self._relaunch_on_start(),
             launch_running=self._launch_running())
@@ -509,14 +513,15 @@ class ComputerAppEnvironment(AgentEnvEnvironment):
 
     @classmethod
     def settings_on(cls, os_type: Optional[str]) -> type[BaseModel]:
-        """Its ``Settings`` on ``os_type``, with the fields its OS adds."""
-        added = declared.settings if (declared := cls._installs.get(os_type)) is not None else None
+        """Its ``Settings`` on ``os_type``, an OS type or ``<os>/<distribution>``, with the fields it adds there."""
+        added = declared.settings if (declared := entry_for(cls._installs, os_type)) is not None else None
         return _added(added, cls.Settings) if added is not None else cls.Settings
 
     @classmethod
     def build_settings_on(cls, os_type: Optional[str]) -> type[BaseModel]:
-        """Its ``BuildSettings`` on ``os_type``, with the fields its OS adds."""
-        added = declared.build_settings if (declared := cls._installs.get(os_type)) is not None else None
+        """Its ``BuildSettings`` on ``os_type``, an OS type or ``<os>/<distribution>``, with the fields it adds
+        there."""
+        added = declared.build_settings if (declared := entry_for(cls._installs, os_type)) is not None else None
         return _added(added, cls.BuildSettings) if added is not None else cls.BuildSettings
 
     @extension(COMPUTER_APP, op="launch", description=(
@@ -588,7 +593,7 @@ class ComputerAppEnvironment(AgentEnvEnvironment):
 
     def _computer_app_skill_file(self) -> Optional[str]:
         """The file of the app's folder holding its skill on this OS, or the class's."""
-        declared = type(self)._installs.get(detect().os)
+        declared = entry_for(type(self)._installs, _here())
         return declared.skill if declared is not None and declared.skill is not None else type(self).skill
 
     @classmethod
@@ -618,8 +623,10 @@ class ComputerAppEnvironment(AgentEnvEnvironment):
                  if hasattr(fn, _INSTALL_STEP_ATTR) for scope, os_types in [getattr(fn, _INSTALL_STEP_ATTR)]]
         checks = [AppReadyCheck(name=fn.__name__, os=getattr(fn, _READY_CHECK_ATTR)) for fn in methods
                   if hasattr(fn, _READY_CHECK_ATTR)]
+        installed_os = {key.partition("/")[0] for key in cls._installs}
         for method in [*steps, *checks]:
-            if unknown := [os_type for os_type in method.os or [] if os_type not in cls._installs]:
+            if unknown := [os_type for os_type in method.os or []
+                           if entry_for(cls._installs, os_type) is None and os_type not in installed_os]:
                 raise ValueError(f"{cls.__name__}.{method.name} runs on {unknown[0]!r}, which {cls.__name__} declares "
                                  f"no install for; it declares {', '.join(cls._installs) or 'none'}")
         return AppDeclaration(
@@ -678,8 +685,13 @@ def _built_settings(cls: type[ComputerAppEnvironment], os_type: Optional[str]) -
     return cls.build_settings_on(os_type).model_validate(values)
 
 
-def _runs_on(os_types: Optional[list[str]], os_type: Optional[str]) -> bool:
-    return os_types is None or os_type in os_types
+def _here() -> Optional[str]:
+    """The platform this runs on, by the key an app's parts for it are under (``platform_key``): the one its computer
+    was composed for (``PLATFORM_ENV``), else what it detects."""
+    if composed := os.environ.get(PLATFORM_ENV):
+        return composed
+    running = detect()
+    return platform_key(running.os, running.distribution)
 
 
 @functools.cache

{agentenv_framework_protocol-0.1.493 → agentenv_framework_protocol-0.1.495}/src/agentenv_protocol/computer/app_data.py

@@ -1,7 +1,9 @@
 """An app's data plane as its own server serves it (``AppDataPlane``), by the app's data hooks or, with none, the
 defaults on the paths it keeps its data in, under the session user's home: a load writes the files it's given under
 them, an export returns the files there, and a reset puts back the copy its server kept when it first started on this
-boot, which is the app as installed, since every boot starts from the computer's image."""
+boot, which is the app as installed, since every boot starts from the computer's image. An export copies the files with
+the app paused, or, where the app holds one so that no other process may read it, as Windows lets an app hold a file
+and a pause doesn't release, with it stopped and relaunched after."""
 from __future__ import annotations
 
 import asyncio
@@ -17,7 +19,7 @@ from typing import TYPE_CHECKING, Any, Optional
 
 from ..agent_env_environment import OP_ADD_DATA, OP_GET_DATA, OP_RESET_DATA
 from ..transfers import WriteNamespaceGrant
-from ..types import METHOD_ADD, METHOD_RESET, FilePart, uploaded_object_path
+from ..types import METHOD_ADD, METHOD_GET, METHOD_RESET, FilePart, uploaded_object_path
 from .app_runtime import paused_app
 from .dataplane import data_files, file_parts, part_bytes
 
@@ -27,15 +29,24 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 #: The cause a launch after each data call logs.
-_CAUSES = {OP_ADD_DATA: METHOD_ADD, OP_RESET_DATA: METHOD_RESET}
+_CAUSES = {OP_ADD_DATA: METHOD_ADD, OP_GET_DATA: METHOD_GET, OP_RESET_DATA: METHOD_RESET}
 #: Where an app's server keeps its paths as installed, in the app's folder.
 INITIAL = Path(".agentenv/initial")
+#: Windows' errors for a file another process holds so that no other may read it: a sharing violation, and a lock on
+#: the part read.
+_HELD = (32, 33)
+
+
+class HeldByApp(OSError):
+    """A file under the app's paths that the running app holds so that no other process may read it, which stopping
+    the app releases and pausing it doesn't."""
 
 
 class AppDataPlane:
     """An app's data plane, served around its contract: one data call or launch at a time; a load and a reset stop the
     running app first and relaunch it after, but for those the app serves live, and a load that fails is followed by a
-    reset, when the app says so. A call fails once it runs
+    reset, when the app says so; an export the app holds a file of (``HeldByApp``) stops it and relaunches it too. A
+    call fails once it runs
     past ``timeout_s`` and is cancelled: what awaits stops at once, but a thread can't be stopped, so a sync hook's or
     a default's thread is waited for, as are the reset and relaunch after it and the next call."""
 
@@ -90,7 +101,7 @@ class AppDataPlane:
             running = op != OP_GET_DATA and op not in self.live and await self.runtime.stop_app()
             ran = op in self.live and self.runtime.running()
             try:
-                result = await self._within(op, served, args, answer)
+                result = await self._within_held(op, served, args, answer)
             except Exception:
                 if op == OP_ADD_DATA and self.resets_failed_add():
                     if op in self.live:
@@ -110,6 +121,24 @@ class AppDataPlane:
         else:
             answer.set_result(result)
 
+    async def _within_held(self, op: str, served: Callable, args: tuple, answer: asyncio.Future) -> Any:
+        """``served``'s result within ``timeout_s``; where the app holds a file of its paths (``HeldByApp``), again with
+        the app stopped, in what's left of it, and the app relaunched after, as a load's is."""
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + self.timeout_s
+        try:
+            return await self._within(op, served, args, answer)
+        except HeldByApp:
+            stopped = await self.runtime.stop_app()
+        try:
+            result = await self._within(op, served, args, answer, deadline - loop.time())
+        finally:
+            if stopped:
+                await self.runtime.launch_app(_CAUSES[op])
+        if stopped and self.relaunched is not None:
+            await self.relaunched(op)
+        return result
+
     async def _undo(self, answer: asyncio.Future) -> None:
         """Reset the app's data after a load that failed."""
         if (reset := self._served(OP_RESET_DATA)) is None:
@@ -140,12 +169,14 @@ class AppDataPlane:
                 OP_GET_DATA: functools.partial(get, self.paths),
                 OP_RESET_DATA: functools.partial(reset, self.paths)}[op]
 
-    async def _within(self, op: str, served: Callable, args: tuple, answer: asyncio.Future) -> Any:
-        """``served``'s result within ``timeout_s``; past it, ``answer`` fails at once and the call is cancelled, and
-        this raises the same once it has ended: at once for what awaits, after any thread it runs."""
+    async def _within(self, op: str, served: Callable, args: tuple, answer: asyncio.Future,
+                      left_s: Optional[float] = None) -> Any:
+        """``served``'s result within ``left_s``, ``timeout_s`` by default; past it, ``answer`` fails at once and the
+        call is cancelled, and this raises the same once it has ended: at once for what awaits, after any thread it
+        runs."""
         work = asyncio.ensure_future(_called(served, *args))
         try:
-            return await asyncio.wait_for(asyncio.shield(work), self.timeout_s)
+            return await asyncio.wait_for(asyncio.shield(work), max(0.0, self.timeout_s if left_s is None else left_s))
         except TimeoutError:
             late = TimeoutError(f"{op} ran past the app's data_timeout_s, {self.timeout_s:g} s")
             if not answer.done():
@@ -185,11 +216,17 @@ async def add(parts: list, paths: list[str]) -> None:
 
 async def get(paths: list[str], write_namespace: Optional[WriteNamespaceGrant]) -> list:
     """A part for each file under ``paths``, copied with the app this server launched paused (``paused_app``), so they
-    are of one moment, and sent from the copy once it runs again; an app's own data/get hook calls it so too."""
+    are of one moment, and sent from the copy once it runs again; an app's own data/get hook calls it so too. A file
+    the paused app holds raises ``HeldByApp``, for its data plane to copy them with it stopped."""
     INITIAL.parent.mkdir(parents=True, exist_ok=True)
     with tempfile.TemporaryDirectory(dir=INITIAL.parent) as staging:
-        with paused_app():
-            await in_thread(_stage, Path.home(), paths, Path(staging))
+        try:
+            with paused_app():
+                await in_thread(_stage, Path.home(), paths, Path(staging))
+        except OSError as e:
+            if getattr(e, "winerror", None) in _HELD:
+                raise HeldByApp(f"the running app holds {e.filename or 'a file'} so that nothing else may read it") from e
+            raise
         return await file_parts(Path(staging), paths, write_namespace)
 
 

{agentenv_framework_protocol-0.1.493 → agentenv_framework_protocol-0.1.495}/src/agentenv_protocol/computer/platform.py

@@ -7,10 +7,15 @@ import platform as _platform
 import sys
 from dataclasses import dataclass
 from pathlib import Path
+from typing import Iterable, Mapping, Optional, TypeVar
 
 PREDICATE_KEYS = ("os", "distribution", "version", "arch", "display")
 
 _ARCH = {"x86_64": "amd64", "amd64": "amd64", "aarch64": "arm64", "arm64": "arm64"}
+_Entry = TypeVar("_Entry")
+#: The platform (``platform_key``) the computer's composer built an app for, which its server and install steps read in
+#: place of what /etc/os-release says, so they act on the install the image holds; unset outside a composed computer.
+PLATFORM_ENV = "AGENTENV_PLATFORM"
 _OS = {"linux": "linux", "darwin": "macos", "win32": "windows"}
 
 
@@ -52,6 +57,30 @@ def detect(environ: dict | None = None, os_release: Path = Path("/etc/os-release
                     arch=_ARCH.get(machine, machine or None), display=display)
 
 
+def platform_key(os_type: Optional[str], distribution: Optional[str] = None) -> Optional[str]:
+    """What a platform's own install, launch or known failures are keyed by: ``<os>/<distribution>``, its distribution
+    being /etc/os-release's ID, or its OS type when it has none."""
+    if os_type is None:
+        return None
+    return f"{os_type}/{distribution}" if distribution else os_type
+
+
+def entry_for(by_platform: Mapping[str, _Entry], key: Optional[str]) -> Optional[_Entry]:
+    """``by_platform``'s entry for the platform ``key`` names: its distribution's, which replaces its OS type's there,
+    else its OS type's."""
+    if key is None:
+        return None
+    return by_platform[key] if key in by_platform else by_platform.get(key.partition("/")[0])
+
+
+def applies(keys: Optional[Iterable[str]], key: Optional[str]) -> bool:
+    """Whether what's declared for ``keys``, OS types or distributions, or for every OS when None, applies on the
+    platform ``key`` names: one names its OS type or its distribution."""
+    if keys is None:
+        return True
+    return key is not None and (key in keys or key.partition("/")[0] in keys)
+
+
 def supported(entry: dict) -> list[Platform]:
     """The platforms a ``supports`` entry names: its ``os`` type, with each of its displays and arches, and its
     distribution and version when it names one. ``{"os": {"type": "linux", "display": ["x11"]}, "arch": ["amd64"]}``

{agentenv_framework_protocol-0.1.493 → agentenv_framework_protocol-0.1.495}/src/agentenv_protocol/computer/run_install_step.py

@@ -11,8 +11,7 @@ from pathlib import Path
 from typing import NoReturn
 
 from ._load import load_class
-from .app import ComputerAppEnvironment, _built_settings
-from .platform import detect
+from .app import ComputerAppEnvironment, _built_settings, _here
 
 USAGE = "usage: python -m agentenv_protocol.computer.run_install_step <file>:<Class> <method>"
 
@@ -33,7 +32,7 @@ def main(argv: list[str]) -> None:
     if argv[1] not in {step.name for step in cls.declaration().install_steps}:
         raise SystemExit(f"{cls.__name__} has no @install_step method {argv[1]!r}")
     app = cls.__new__(cls)
-    app.settings, app.build_settings = _NoDeploy(), _built_settings(cls, detect().os)
+    app.settings, app.build_settings = _NoDeploy(), _built_settings(cls, _here())
     done = getattr(app, argv[1])()
     if inspect.isawaitable(done):
         asyncio.run(done)

{agentenv_framework_protocol-0.1.493 → agentenv_framework_protocol-0.1.495}/tests/test_computer_app_data.py

@@ -2,8 +2,9 @@
 the defaults: a load writes files under them, through no link out of them, an export returns them, and a reset puts back
 the copy its server kept before it served; its card declares a file tree. Hooks override paths, and read the parts they
 get with part_bytes. Around a load and a reset the app is stopped and relaunched, a failed load is followed by a reset,
-and data calls take turns; an app that loads live is left running through a load, and a failed one is reset with it
-stopped, or left as it is when the app says so; an app with hooks may keep its paths as installed. A call past
+and data calls take turns; an export of a file the paused app holds stops it, copies it in what's left of its
+timeout, and relaunches it after; an app that loads live is left running through a load, and a failed one is reset
+with it stopped, or left as it is when the app says so; an app with hooks may keep its paths as installed. A call past
 data_timeout_s fails then and is cancelled, but a sync hook runs in a thread, which its reset and relaunch, and the next
 call, wait for. The app serves its skill file."""
 from __future__ import annotations
@@ -20,7 +21,7 @@ pytest.importorskip("mcp.server.fastmcp")
 
 import httpx  # noqa: E402
 
-from agentenv_protocol import add_data, client, reset_data  # noqa: E402
+from agentenv_protocol import add_data, client, get_data, reset_data  # noqa: E402
 from agentenv_protocol.agent_env_environment import OP_ADD_DATA  # noqa: E402
 from agentenv_protocol.computer import ComputerAppEnvironment, Launch, linux, part_bytes  # noqa: E402
 from agentenv_protocol.computer import app, app_data, app_runtime, session  # noqa: E402
@@ -106,8 +107,10 @@ def desktop(monkeypatch):
     @contextlib.contextmanager
     def paused(pid):
         events.append(("pause", pid))
-        yield
-        events.append(("continue", pid))
+        try:
+            yield
+        finally:
+            events.append(("continue", pid))
 
     monkeypatch.setattr(session, "launch", launch)
     monkeypatch.setattr(session, "stop", stop)
@@ -210,6 +213,32 @@ async def test_a_load_and_a_reset_stop_the_running_app_and_relaunch_it_and_an_ex
                        ("stop", 4244), ("launch", 4248)]
 
 
+@pytest.mark.asyncio
+async def test_an_export_of_a_file_the_paused_app_holds_stops_the_app_copies_it_and_relaunches_it(home, desktop,
+                                                                                                 monkeypatch):
+    """As Windows lets an app hold a file that no other process may read, which a pause doesn't release."""
+    (home / "Mail").mkdir()
+    (home / "Mail/inbox.txt").write_text("held")
+    mail = PathsMail()
+    mail._computer_app_data_plane().keep_initial()
+    await mail._computer_app.launch_app()
+    stage = app_data._stage
+
+    def held_while_running(*args):
+        if desktop[-1][0] == "pause":
+            held = PermissionError(13, "The process cannot access the file", str(home / "Mail/inbox.txt"))
+            held.winerror = 32
+            raise held
+        stage(*args)
+
+    monkeypatch.setattr(app_data, "_stage", held_while_running)
+    async with _http(mail) as http:
+        exported = _files(await _rpc(http, "data/get", {}))
+
+    assert [event[0] for event in desktop] == ["launch", "pause", "continue", "stop", "launch"]
+    assert desktop[3] == ("stop", 4242) and exported["Mail/inbox.txt"] == b"held"
+
+
 @pytest.mark.asyncio
 async def test_an_export_copies_the_paths_with_the_app_paused_and_sends_the_copy_once_it_runs_again(home, desktop,
                                                                                                   monkeypatch):
@@ -414,6 +443,32 @@ async def test_calls_take_turns_and_one_past_its_timeout_fails_then_while_what_f
                        ("launch", 4248), ("stop", 4248), ("load", 1), ("loaded", 1), ("launch", 4252)]
 
 
+@pytest.mark.asyncio
+async def test_an_export_retried_with_the_app_stopped_gets_only_what_is_left_of_its_timeout(home, desktop):
+    @linux(launch=Launch(command=["held"]))
+    class Held(ComputerAppEnvironment):
+        data_timeout_s = 1.0
+
+        @get_data
+        async def export(self) -> list:
+            if desktop[-1][0] == "launch":
+                await asyncio.sleep(0.8)
+                raise app_data.HeldByApp("the running app holds a file")
+            await asyncio.Event().wait()
+
+    held = Held()
+    await held._computer_app.launch_app()
+    started = time.monotonic()
+    async with _http(held) as http:
+        late = await http.post(RPC_PATH, json=_call("data/get", {}))
+    answered = time.monotonic() - started
+    await asyncio.gather(*held._computer_app_data_plane().changing)
+
+    assert late.json()["error"]["message"] == "get_data ran past the app's data_timeout_s, 1 s"
+    assert answered < 1.5
+    assert desktop == [("launch", 4242), ("stop", 4242), ("launch", 4244)]
+
+
 @pytest.mark.asyncio
 async def test_it_serves_its_skill_file_and_no_skill_without_one(home, tmp_path):
     (tmp_path / "folder" / "SKILL.md").write_text("---\ndescription: Reading and sending mail.\n---\n\n# Mail\nUse it.\n")

{agentenv_framework_protocol-0.1.493 → agentenv_framework_protocol-0.1.495}/tests/test_computer_declare.py

@@ -18,11 +18,11 @@ pytest.importorskip("PIL")
 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
-                                        Windows, install, linux, windows)
+                                        Windows, install, install_step, linux, ready_check, 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
-from agentenv_protocol.computer.platform import Platform  # noqa: E402
+from agentenv_protocol.computer.platform import PLATFORM_ENV, Platform  # noqa: E402
 
 DRIVER = '''import not_installed_here
 from not_installed_here.input import Base, Keyboard
@@ -337,6 +337,106 @@ def test_an_app_reads_its_settings_build_settings_and_launch_as_declared_for_the
         assert (type(notes.settings), notes.build_settings.edition, notes.launch) == (Notes.Settings, "home", None)
 
 
+@pytest.mark.parametrize(("distribution", "launched", "checked"), [
+    ("omarchy", ["notes", "--wayland"], ["anywhere", "here"]), ("ubuntu", ["notes"], ["anywhere"]),
+    (None, ["notes"], ["anywhere"])])
+def test_an_app_on_a_distribution_it_declares_for_takes_that_part_and_elsewhere_its_os_types(
+        monkeypatch, tmp_path, distribution, launched, checked):
+    class WaylandSettings(BaseModel):
+        portal: bool = True
+
+    @linux(distribution="omarchy", launch=Launch(command=["notes", "--wayland"]), settings=WaylandSettings)
+    @linux(launch=Launch(command=["notes"]))
+    class Notes(ComputerAppEnvironment):
+        @ready_check(os="linux")
+        def anywhere(self):
+            return True
+
+        @ready_check(os="linux/omarchy")
+        def here(self):
+            return True
+
+    monkeypatch.setattr(app_module, "detect", lambda: Platform(os="linux", distribution=distribution))
+    monkeypatch.setenv("ENVIRONMENT_NAME", "notes")
+    monkeypatch.delenv(APP_SETTINGS_ENV, raising=False)
+    monkeypatch.chdir(tmp_path)
+
+    notes = Notes()
+
+    assert set(Notes.declaration().os) == {"linux", "linux/omarchy"}
+    assert notes.launch.command == launched and hasattr(notes.settings, "portal") == (distribution == "omarchy")
+    assert sorted(notes._computer_app.ready_checks) == checked
+
+
+def test_an_install_step_or_ready_check_on_no_os_type_the_app_installs_on_is_refused():
+    @linux(distribution="omarchy")
+    class Notes(ComputerAppEnvironment):
+        @ready_check(os="linux")
+        def anywhere(self):
+            return True
+
+        @ready_check(os="macos")
+        def mac(self):
+            return True
+
+    with pytest.raises(ValueError, match="Notes.mac runs on 'macos', which Notes declares no install for"):
+        Notes.declaration()
+
+
+@pytest.mark.parametrize(("distribution", "checked"), [("ubuntu", ["anywhere", "on_ubuntu"]),
+                                                     ("omarchy", ["anywhere"])])
+def test_an_install_step_or_ready_check_for_a_distribution_runs_there_on_its_os_types_install(
+        monkeypatch, tmp_path, distribution, checked):
+    @linux(launch=Launch(command=["notes"]))
+    class Notes(ComputerAppEnvironment):
+        @install_step(os="linux/ubuntu")
+        def fonts(self):
+            pass
+
+        @ready_check(os="linux")
+        def anywhere(self):
+            return True
+
+        @ready_check(os="linux/ubuntu")
+        def on_ubuntu(self):
+            return True
+
+    monkeypatch.setattr(app_module, "detect", lambda: Platform(os="linux", distribution=distribution))
+    monkeypatch.setenv("ENVIRONMENT_NAME", "notes")
+    monkeypatch.delenv(APP_SETTINGS_ENV, raising=False)
+    monkeypatch.chdir(tmp_path)
+
+    assert [step.os for step in Notes.declaration().install_steps] == [["linux/ubuntu"]]
+    assert sorted(Notes()._computer_app.ready_checks) == checked
+
+
+def test_an_app_reads_the_platform_its_computer_was_composed_for_over_what_it_detects(monkeypatch, tmp_path):
+    @linux(distribution="omarchy", launch=Launch(command=["notes", "--wayland"]))
+    @linux(launch=Launch(command=["notes"]))
+    class Notes(ComputerAppEnvironment):
+        pass
+
+    monkeypatch.setattr(app_module, "detect", lambda: Platform(os="linux", distribution="arch"))
+    monkeypatch.setenv("ENVIRONMENT_NAME", "notes")
+    monkeypatch.delenv(APP_SETTINGS_ENV, raising=False)
+    monkeypatch.chdir(tmp_path)
+    detected = Notes().launch.command
+    monkeypatch.setenv(PLATFORM_ENV, "linux/omarchy")
+
+    assert (detected, Notes().launch.command) == (["notes"], ["notes", "--wayland"])
+
+
+def test_an_install_step_or_ready_check_for_a_distribution_with_no_install_of_its_own_or_its_os_types_is_refused():
+    @linux(distribution="omarchy")
+    class Notes(ComputerAppEnvironment):
+        @install_step(os="linux/ubuntu")
+        def fonts(self):
+            pass
+
+    with pytest.raises(ValueError, match="Notes.fonts runs on 'linux/ubuntu', which Notes declares no install for"):
+        Notes.declaration()
+
+
 def test_a_declaration_stored_before_each_os_had_its_own_part_reads_as_its_linux_part():
     stored = {"supports": LINUX, "permissions": [], "settings": {"type": "object"}, "data": [], "install_steps": [],
               "install": {"linux": {"files": ".", "services": [{"name": "imap", "command": "bin/imap"}]}},
@@ -353,7 +453,7 @@ def test_a_declaration_stored_before_each_os_had_its_own_part_reads_as_its_linux
 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(linux).parameters) == set(Linux.model_fields) | added | {"distribution"}
     assert set(inspect.signature(windows).parameters) == set(Windows.model_fields) | added