agentenv-framework-protocol 0.1.398__tar.gz → 0.1.400__tar.gz

{agentenv_framework_protocol-0.1.398 → agentenv_framework_protocol-0.1.400}/.gitignore

@@ -170,3 +170,4 @@ cython_debug/
 
 # Written by the release workflow into the wheels it publishes
 src/agent_env/env/published_images.json
+src/agent_env/explorer/static/

{agentenv_framework_protocol-0.1.398 → agentenv_framework_protocol-0.1.400}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.398
+Version: 0.1.400
 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
@@ -34,6 +34,9 @@ Requires-Dist: mcp<2,>=1.25; extra == 'agent'
 Requires-Dist: python-multipart>=0.0.13; extra == 'agent'
 Requires-Dist: regex>=2023.12.25; extra == 'agent'
 Requires-Dist: uvicorn>=0.30; extra == 'agent'
+Provides-Extra: app
+Requires-Dist: mcp<2,>=1.25; extra == 'app'
+Requires-Dist: uvicorn>=0.30; extra == 'app'
 Provides-Extra: computer
 Requires-Dist: av>=17; extra == 'computer'
 Requires-Dist: mcp<2,>=1.25; extra == 'computer'
@@ -481,8 +484,8 @@ driver has them, through the `served_tools`, `served_extensions` and `served_ope
   the live screen size, what its input takes, its OS's shortcuts) and ending with the driver
   class's `notes`, markdown for what its card can't say.
 - **Framework extensions.** `computer-ready/v1` (`status`: real checks of the display and a
-  capture, plus the driver's own `ready_checks()`; tools refuse `device_unavailable` until they
-  pass once), `computer-display/v1`, `computer-spaces/v1` (the default space, written into the tool
+  capture, the driver's own `ready_checks()`, and one per app on the computer, asked of the app's
+  own server (see Computer apps); tools refuse `device_unavailable` until they pass once), `computer-display/v1`, `computer-spaces/v1` (the default space, written into the tool
   descriptions), `computer-keyboard/v1`, `computer-exec/v1` (`run {argv, cwd?, env?, timeout_s?,
   request_id}`: output capped per stream, a repeated `request_id` answered with the first result) and,
   with `recording`, `computer-recording/v1` (below).
@@ -594,9 +597,10 @@ and gives it back.
 
 A computer app is software an agent uses on a computer, beside the driver: a desktop app, a service
 or both. Write one as a `ComputerAppEnvironment` subclass from `agentenv_protocol.computer`, an
-`AgentEnvEnvironment` whose class also says what it is to a computer. It needs only the plain
-package: `agentenv_protocol.computer` imports what a driver needs (mcp, uvicorn, Pillow, PyAV) only
-when a driver's names are used.
+`AgentEnvEnvironment` whose class also says what it is to a computer. Writing one and reading what
+it declares need only the plain package: `agentenv_protocol.computer` imports what a driver needs
+(mcp, uvicorn, Pillow, PyAV) only when a driver's names are used. On a computer it runs as its own
+server, which needs the `app` extra (below).
 
 ```python
 from pydantic import BaseModel, SecretStr
@@ -617,18 +621,37 @@ class MailApp(ComputerAppEnvironment):
   `permissions` it needs of the computer. Its env.toml names the rest: the app itself
   (`environment_name`) and the `computer` and `driver` it deploys alone on.
 - **`linux = Linux(...)`** is how a Linux computer installs it: `files`, a folder of the app's
-  copied under its prefix; `python`, a requirements file there installed into a venv beside them;
-  `services`, programs the computer's init runs from the prefix as the session user.
-- **`launch = Launch(...)`** says how it starts in the desktop session, with it (`at="boot"`) or when
-  the agent opens it (`"demand"`), and `ready=Ready(...)` when it's ready; `@ready_check` marks a
-  method for readiness that needs logic, and `@install_step(scope=...)` one a computer runs as it
-  installs the app.
+  copied under its prefix, which holds the class's file; `python`, a requirements file there,
+  installed into the venv every app gets beside them; `services`, programs the computer's init runs
+  from the prefix as the session user.
+- **`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
+  loopback, or a command exiting 0. `@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.
 - **Its skill** is a file of its folder (`skill = "skill.md"`) or an `@agent_skill` method, not both;
   its data hooks are the usual `@add_data`, `@get_data` and `@reset_data`.
 - **`Settings`** is typed; a computer hands each app the values a deploy gives it, as one JSON value
   in `APP_SETTINGS_ENV` (`AGENTENV_APP_SETTINGS`, the apps' values by name), and the base class reads
   its own, by `ENVIRONMENT_NAME`, as `self.settings`. A `SecretStr` field is a secret.
 
+On a computer each app is its own server: `python -m agentenv_protocol.computer.serve_app
+<file>:<Class>`, a program the computer's init runs from the app's folder in the app's venv, which
+has the `app` extra (`agentenv-framework-protocol[app]`: mcp and uvicorn). It serves the class's
+card and tools on the Unix socket `.agentenv/server.sock` in that folder, with `computer-app/v1`:
+the app's `launch` as its params, and the methods `launch` (POST), which starts the app in the
+desktop session, and `ready` (GET: an `AppReadiness` of `ready`, `problems`, `launched`, `waited_s`
+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 session is up 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. 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.
+
 `MailApp.declaration()` returns what the class declares, an `AppDeclaration`, which a `computer_app`
 env stores, and `python -m agentenv_protocol.computer._declare <folder> <file> <class>` prints it as
 JSON, or a driver's `DriverDeclaration`, without the class's own dependencies installed.

{agentenv_framework_protocol-0.1.398 → agentenv_framework_protocol-0.1.400}/README.md

@@ -428,8 +428,8 @@ driver has them, through the `served_tools`, `served_extensions` and `served_ope
   the live screen size, what its input takes, its OS's shortcuts) and ending with the driver
   class's `notes`, markdown for what its card can't say.
 - **Framework extensions.** `computer-ready/v1` (`status`: real checks of the display and a
-  capture, plus the driver's own `ready_checks()`; tools refuse `device_unavailable` until they
-  pass once), `computer-display/v1`, `computer-spaces/v1` (the default space, written into the tool
+  capture, the driver's own `ready_checks()`, and one per app on the computer, asked of the app's
+  own server (see Computer apps); tools refuse `device_unavailable` until they pass once), `computer-display/v1`, `computer-spaces/v1` (the default space, written into the tool
   descriptions), `computer-keyboard/v1`, `computer-exec/v1` (`run {argv, cwd?, env?, timeout_s?,
   request_id}`: output capped per stream, a repeated `request_id` answered with the first result) and,
   with `recording`, `computer-recording/v1` (below).
@@ -541,9 +541,10 @@ and gives it back.
 
 A computer app is software an agent uses on a computer, beside the driver: a desktop app, a service
 or both. Write one as a `ComputerAppEnvironment` subclass from `agentenv_protocol.computer`, an
-`AgentEnvEnvironment` whose class also says what it is to a computer. It needs only the plain
-package: `agentenv_protocol.computer` imports what a driver needs (mcp, uvicorn, Pillow, PyAV) only
-when a driver's names are used.
+`AgentEnvEnvironment` whose class also says what it is to a computer. Writing one and reading what
+it declares need only the plain package: `agentenv_protocol.computer` imports what a driver needs
+(mcp, uvicorn, Pillow, PyAV) only when a driver's names are used. On a computer it runs as its own
+server, which needs the `app` extra (below).
 
 ```python
 from pydantic import BaseModel, SecretStr
@@ -564,18 +565,37 @@ class MailApp(ComputerAppEnvironment):
   `permissions` it needs of the computer. Its env.toml names the rest: the app itself
   (`environment_name`) and the `computer` and `driver` it deploys alone on.
 - **`linux = Linux(...)`** is how a Linux computer installs it: `files`, a folder of the app's
-  copied under its prefix; `python`, a requirements file there installed into a venv beside them;
-  `services`, programs the computer's init runs from the prefix as the session user.
-- **`launch = Launch(...)`** says how it starts in the desktop session, with it (`at="boot"`) or when
-  the agent opens it (`"demand"`), and `ready=Ready(...)` when it's ready; `@ready_check` marks a
-  method for readiness that needs logic, and `@install_step(scope=...)` one a computer runs as it
-  installs the app.
+  copied under its prefix, which holds the class's file; `python`, a requirements file there,
+  installed into the venv every app gets beside them; `services`, programs the computer's init runs
+  from the prefix as the session user.
+- **`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
+  loopback, or a command exiting 0. `@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.
 - **Its skill** is a file of its folder (`skill = "skill.md"`) or an `@agent_skill` method, not both;
   its data hooks are the usual `@add_data`, `@get_data` and `@reset_data`.
 - **`Settings`** is typed; a computer hands each app the values a deploy gives it, as one JSON value
   in `APP_SETTINGS_ENV` (`AGENTENV_APP_SETTINGS`, the apps' values by name), and the base class reads
   its own, by `ENVIRONMENT_NAME`, as `self.settings`. A `SecretStr` field is a secret.
 
+On a computer each app is its own server: `python -m agentenv_protocol.computer.serve_app
+<file>:<Class>`, a program the computer's init runs from the app's folder in the app's venv, which
+has the `app` extra (`agentenv-framework-protocol[app]`: mcp and uvicorn). It serves the class's
+card and tools on the Unix socket `.agentenv/server.sock` in that folder, with `computer-app/v1`:
+the app's `launch` as its params, and the methods `launch` (POST), which starts the app in the
+desktop session, and `ready` (GET: an `AppReadiness` of `ready`, `problems`, `launched`, `waited_s`
+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 session is up 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. 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.
+
 `MailApp.declaration()` returns what the class declares, an `AppDeclaration`, which a `computer_app`
 env stores, and `python -m agentenv_protocol.computer._declare <folder> <file> <class>` prints it as
 JSON, or a driver's `DriverDeclaration`, without the class's own dependencies installed.

{agentenv_framework_protocol-0.1.398 → agentenv_framework_protocol-0.1.400}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentenv-framework-protocol"
-version = "0.1.398"
+version = "0.1.400"
 description = "Open data-plane protocol and server SDK for agent environments."
 readme = "README.md"
 license = "Apache-2.0"
@@ -35,6 +35,12 @@ agent = [
     "regex>=2023.12.25",
     "uvicorn>=0.30",
 ]
+# A computer app's own server: ComputerAppEnvironment serves its card and computer-app/v1 over mcp's FastMCP, on a Unix
+# socket through uvicorn.
+app = [
+    "mcp>=1.25,<2",
+    "uvicorn>=0.30",
+]
 # A computer driver: ComputerDriverEnvironment serves its tools over mcp's FastMCP, crops and encodes frames, and
 # records the display as H.264 with PyAV (computer-recording/v1).
 computer = [

{agentenv_framework_protocol-0.1.398 → agentenv_framework_protocol-0.1.400}/src/agentenv_protocol/computer/_declare.py

@@ -14,6 +14,8 @@ import sys
 import types
 from pathlib import Path
 
+from pydantic import ValidationError
+
 from .app import AppDeclaration, ComputerAppEnvironment
 from .card import COMPUTER
 from .driver import ComputerDriverEnvironment, DriverDeclaration, DriverPlatform
@@ -95,6 +97,10 @@ def main(argv: list[str]) -> int:
     try:
         with contextlib.redirect_stdout(sys.stderr):
             declared = declare(Path(folder), file, name)
+    except ValidationError as e:
+        print("ValueError: " + "; ".join(error["msg"].removeprefix("Value error, ") for error in e.errors()),
+              file=sys.stderr)
+        return 1
     except Exception as e:
         print(f"{type(e).__name__}: {e}", file=sys.stderr)
         return 1

agentenv_framework_protocol-0.1.400/src/agentenv_protocol/computer/_load.py

@@ -0,0 +1,22 @@
+"""Import a class from a file of a driver's or an app's folder, as its computer's program starts it."""
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+
+
+def load_class(file: Path, name: str, base: type) -> type:
+    """The class ``name`` in ``file``, imported as a module of its own with the file's folder importable; exits saying
+    why when it isn't a subclass of ``base``."""
+    if not file.is_file():
+        raise SystemExit(f"{file} isn't a file")
+    sys.path.insert(0, str(file.resolve().parent))
+    spec = importlib.util.spec_from_file_location(file.stem, file)
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[file.stem] = module
+    spec.loader.exec_module(module)
+    cls = getattr(module, name, None)
+    if not (isinstance(cls, type) and issubclass(cls, base)):
+        raise SystemExit(f"{file} has no {base.__name__} subclass named {name}")
+    return cls

{agentenv_framework_protocol-0.1.398 → agentenv_framework_protocol-0.1.400}/src/agentenv_protocol/computer/app.py

@@ -2,24 +2,37 @@
 computer: the platforms it supports and the permissions it needs (``@computer_app``), how each OS installs it
 (``linux = Linux(...)``), how it launches (``launch``), its install steps and ready checks, its skill, and its typed
 ``Settings``. A ``computer_app`` env's put reads that declaration from the class; its data hooks are the base class's.
-Its name is its env's ``environment_name``."""
+Its name is its env's ``environment_name``. On the computer the class runs as the app's own server (``serve_app``),
+which launches the app, adds its launcher and says whether it's ready (``computer-app/v1``)."""
 from __future__ import annotations
 
 import inspect
 import json
 import os
+from pathlib import Path
 from typing import Any, Callable, ClassVar, Literal, Optional
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
-from ..agent_env_environment import _EXT_ATTR, _OP_ATTR, AgentEnvEnvironment
+from ..agent_env_environment import _EXT_ATTR, _OP_ATTR, AgentEnvEnvironment, extension
 from ..types import METHOD_ADD, METHOD_GET, METHOD_RESET, SKILL_EXTENSION_URI
+from .app_runtime import AppRuntime
+from .errors import InvalidArgument
 
 #: 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"
 _INSTALL_STEP_ATTR = "_aee_install_step"
 _READY_CHECK_ATTR = "_aee_ready_check"
 _DATA_METHODS = {"reset_data": METHOD_RESET, "add_data": METHOD_ADD, "get_data": METHOD_GET}
+#: What a launch's window can be matched by, as the session lists each window.
+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.
+SOCKET = Path(".agentenv/server.sock")
+FAILURE = Path(".agentenv/server.failure")
+#: How long an app may take to be ready when its launch doesn't say.
+DEFAULT_TIMEOUT_S = 60.0
 
 
 class Service(BaseModel):
@@ -51,7 +64,13 @@ class Ready(BaseModel):
     window: bool = False
     port: Optional[int] = None
     command: Optional[list[str]] = None
-    timeout_s: float = 60
+    timeout_s: float = DEFAULT_TIMEOUT_S
+
+    @model_validator(mode="after")
+    def _waits_on_something(self) -> Ready:
+        if not self.window and self.port is None and not self.command:
+            raise ValueError("Ready waits on nothing: set window, port or command")
+        return self
 
 
 class Launch(BaseModel):
@@ -61,9 +80,23 @@ 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.
     window: Optional[dict[str, str]] = None
     ready: Optional[Ready] = None
 
+    @field_validator("window")
+    @classmethod
+    def _matchable(cls, window: Optional[dict[str, str]]) -> Optional[dict[str, str]]:
+        if window is not None and (not window or set(window) - WINDOW_KEYS):
+            raise ValueError(f"window matches by {', '.join(sorted(WINDOW_KEYS))}, not {window!r}")
+        return window
+
+    @model_validator(mode="after")
+    def _window_to_wait_for(self) -> Launch:
+        if self.ready is not None and self.ready.window and self.window is None:
+            raise ValueError("ready waits on a window: name it with Launch(window={'class': ...})")
+        return self
+
 
 class AppSkill(BaseModel):
     """Where an app's skill for agents comes from: a ``file`` of its folder, or the ``@agent_skill`` ``method`` that
@@ -134,6 +167,7 @@ class ComputerAppEnvironment(AgentEnvEnvironment):
 
     supports: ClassVar[list] = []
     permissions: ClassVar[list[str]] = []
+    _computer_app: Optional[AppRuntime] = None
     linux: ClassVar[Optional[Linux]] = None
     launch: ClassVar[Optional[Launch]] = None
     #: A file of the app's folder holding its skill for agents, when no ``@agent_skill`` method writes it.
@@ -145,6 +179,33 @@ class ComputerAppEnvironment(AgentEnvEnvironment):
     def __init__(self) -> None:
         values = json.loads(os.environ.get(APP_SETTINGS_ENV) or "{}").get(os.environ.get("ENVIRONMENT_NAME"), {})
         self.settings = self.Settings.model_validate(values)
+        ready = self.launch.ready if self.launch is not None else None
+        self._computer_app = AppRuntime(
+            self.launch, {fn.__name__: getattr(self, fn.__name__) for fn in _methods(type(self))
+                          if hasattr(fn, _READY_CHECK_ATTR)},
+            ready.timeout_s if ready is not None else DEFAULT_TIMEOUT_S)
+
+    @extension(COMPUTER_APP, op="launch", description=(
+        "The app's own server: launch launches the app from its folder, as its launcher and a boot do; ready says "
+        "whether it's ready, by its launch's ready and its @ready_check methods."))
+    async def _computer_app_launch(self) -> dict:
+        if self.launch is None:
+            raise InvalidArgument(f"{type(self).__name__} declares no launch")
+        return {"pid": await self._computer_app_runtime().launch_app()}
+
+    @extension(COMPUTER_APP, op="ready", method="GET")
+    async def _computer_app_ready(self) -> dict:
+        return (await self._computer_app_runtime().readiness()).model_dump()
+
+    def _computer_app_runtime(self) -> AppRuntime:
+        if self._computer_app is None:
+            raise TypeError(f"{type(self).__qualname__}.__init__ must call super().__init__()")
+        return self._computer_app
+
+    def extension_params(self, uri: str) -> dict:
+        if uri == COMPUTER_APP:
+            return {"launch": self.launch.model_dump(mode="json", exclude_none=True) if self.launch else None}
+        return super().extension_params(uri)
 
     @classmethod
     def declaration(cls) -> AppDeclaration:
@@ -176,3 +237,4 @@ def _methods(cls: type) -> list[Callable]:
     names = dict.fromkeys(name for klass in reversed(cls.__mro__) for name, member in vars(klass).items()
                           if inspect.isfunction(member))
     return [method for name in names if inspect.isfunction(method := getattr(cls, name))]
+

agentenv_framework_protocol-0.1.400/src/agentenv_protocol/computer/app_runtime.py

@@ -0,0 +1,155 @@
+"""A computer app's own server at work: it launches the app into the desktop session, marking each launch for the rest
+of the boot, and says whether the app is ready, its checks run at once, each within ``CHECK_TIMEOUT_S``
+(``AppReadiness``). ``ComputerAppEnvironment`` keeps one as ``self._computer_app``."""
+from __future__ import annotations
+
+import asyncio
+import inspect
+import os
+import shlex
+import time
+from collections.abc import Awaitable, Callable
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Optional
+
+from pydantic import BaseModel, ConfigDict
+
+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")
+#: How long one readiness check may take; an app's checks run at once.
+CHECK_TIMEOUT_S = 10.0
+
+
+class AppReadiness(BaseModel):
+    """What an app's server says of its readiness, ``computer-app/v1``'s ``ready``: the ``problems`` that keep it from
+    being ``ready``, whether it was ``launched`` since the computer booted, and ``waited_s`` since then, or for an app
+    with no launch since its server started, against its ``timeout_s``."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    ready: bool
+    problems: list[str]
+    launched: bool
+    waited_s: float
+    timeout_s: float
+
+
+class AppRuntime:
+    """An app's server's state: its ``launch``, its ``@ready_check`` methods by name, bound to the app, how long it may
+    take to be ready, why its last launch failed, and each sync check still running in its thread."""
+
+    def __init__(self, launch: Optional[Launch], ready_checks: dict[str, Callable[[], Any]], timeout_s: float) -> None:
+        self.launch = launch
+        self.ready_checks = ready_checks
+        self.timeout_s = timeout_s
+        self.started = time.time()
+        self.launch_failed: Optional[str] = None
+        self.checking: dict[str, asyncio.Future] = {}
+
+    async def start(self) -> None:
+        """Once the desktop session is up, add the app's menu launcher and launch a boot app, unless the computer has
+        launched it since it booted, at boot or on demand: a server that restarts leaves the app be."""
+        if self.launch is None:
+            return
+        await session.wait_until_up()
+        session.add_launcher(os.environ["ENVIRONMENT_NAME"], Path.cwd())
+        if self.launch.at == "boot" and _launched_at() is None:
+            try:
+                await self.launch_app()
+            except Exception as e:
+                self.launch_failed = f"{type(e).__name__}: {e}"
+
+    async def launch_app(self) -> int:
+        """Start the app from its folder, marked as launched; its pid."""
+        pid = await session.launch(self.launch.command, Path.cwd(), {"ENVIRONMENT_NAME": os.environ["ENVIRONMENT_NAME"]})
+        self.launch_failed = None
+        _mark().parent.mkdir(parents=True, exist_ok=True)
+        _mark().touch()
+        return pid
+
+    async def readiness(self) -> AppReadiness:
+        ready = self.launch.ready if self.launch is not None else None
+        checks: list[tuple[str, Awaitable[Optional[str]]]] = []
+        if ready is not None and ready.window:
+            checks.append(("window", _window(self.launch.window)))
+        if ready is not None and ready.port is not None:
+            checks.append(("port", _port(ready.port)))
+        if ready is not None and ready.command:
+            checks.append(("command", _command(ready.command)))
+        checks += [(f"@ready_check {name}", self._ready_check(name, fn)) for name, fn in self.ready_checks.items()]
+        found = await asyncio.gather(*(_bounded(name, check) for name, check in checks))
+        problems = [problem for problem in found if problem is not None]
+        launched = _launched_at()
+        if self.launch is not None and launched is None:
+            problems.insert(0, f"its launch failed: {self.launch_failed}" if self.launch_failed else "not launched yet")
+        return AppReadiness(ready=not problems, problems=problems, launched=launched is not None,
+                            waited_s=round(time.time() - (launched or self.started), 1), timeout_s=self.timeout_s)
+
+    async def _ready_check(self, name: str, fn: Callable[[], Any]) -> Optional[str]:
+        """A sync check runs in a thread, so it can't hold up the server, and once at a time: a thread can't be
+        stopped, so a poll while one runs past its bound waits on that same call."""
+        if inspect.iscoroutinefunction(fn):
+            passed = await fn()
+        else:
+            running = self.checking.get(name)
+            if running is None or running.done():
+                running = self.checking[name] = asyncio.ensure_future(asyncio.to_thread(fn))
+                running.add_done_callback(lambda done: done.cancelled() or done.exception())
+            passed = await asyncio.shield(running)
+        return None if passed else f"@ready_check {name} returned {passed!r}"
+
+
+def _mark() -> Path:
+    return LAUNCHED / Path.cwd().name
+
+
+def _launched_at() -> Optional[float]:
+    """When the app was last launched since the computer booted, by its mark."""
+    try:
+        return _mark().stat().st_mtime
+    except FileNotFoundError:
+        return None
+
+
+async def _bounded(name: str, check: Awaitable[Optional[str]]) -> Optional[str]:
+    """What ``check`` finds wrong, within ``CHECK_TIMEOUT_S``; a check that runs past it or raises says so."""
+    try:
+        return await asyncio.wait_for(check, CHECK_TIMEOUT_S)
+    except TimeoutError:
+        return f"{name} ran past {CHECK_TIMEOUT_S:g} s"
+    except Exception as e:
+        return f"{name}: {type(e).__name__}: {e}"
+
+
+async def _window(match: dict[str, str]) -> Optional[str]:
+    if any(all(window.get(key) == value for key, value in match.items()) for window in await session.windows()):
+        return None
+    return f"no window with {', '.join(f'{key} {value!r}' for key, value in match.items())}"
+
+
+async def _port(port: int) -> Optional[str]:
+    try:
+        _, writer = await asyncio.open_connection("127.0.0.1", port)
+    except OSError:
+        return f"nothing answers on port {port}"
+    writer.close()
+    return None
+
+
+async def _command(argv: list[str]) -> Optional[str]:
+    process = await asyncio.create_subprocess_exec(*argv, cwd=Path.cwd(), stdout=asyncio.subprocess.DEVNULL,
+                                                   stderr=asyncio.subprocess.PIPE)
+    try:
+        _, err = await process.communicate()
+    except asyncio.CancelledError:
+        process.kill()
+        raise
+    if process.returncode == 0:
+        return None
+    reason = (err.decode(errors="replace").strip().splitlines() or [""])[-1]
+    return f"{shlex.join(argv)} exited {process.returncode}" + (f": {reason}" if reason else "")

agentenv_framework_protocol-0.1.400/src/agentenv_protocol/computer/apps.py

@@ -0,0 +1,63 @@
+"""The apps composed onto a computer, as its driver finds them, and whether each is ready. Each app's own server
+answers on its folder's socket (``serve_app``): its card says how the app launches, and its ``computer-app/v1``
+``ready`` whether it's ready. Every app's server must answer before the computer is ready; an app that starts with the
+computer must also be ready, and a ``demand`` app is checked once something launches it."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import httpx
+
+from .. import client
+from ..types import WELL_KNOWN_PATH
+from .app import COMPUTER_APP, FAILURE, SOCKET
+from .app_runtime import CHECK_TIMEOUT_S, AppReadiness
+from .operations import ReadyCheck
+
+#: Where a composed computer installs its apps, a folder each.
+APPS = Path("/opt/agentenv/apps")
+#: How long an app's server may take to answer, its checks run at once, before it counts as not answering.
+ANSWER_TIMEOUT_S = CHECK_TIMEOUT_S + 5
+
+
+def expected() -> list[Path]:
+    """The folders of the apps composed onto this computer."""
+    return sorted(path for path in APPS.iterdir() if path.is_dir()) if APPS.is_dir() else []
+
+
+async def check(folder: Path) -> ReadyCheck:
+    """Whether the app in ``folder`` is ready, as its own server says, or why its server last failed to start; named by
+    its card once the server answers."""
+    name = folder.name
+    try:
+        async with _client(folder / SOCKET) as http:
+            card = (await http.get(WELL_KNOWN_PATH)).raise_for_status().json()
+            name = card["name"]
+            launch = client.extension_params(card, COMPUTER_APP).get("launch")
+            answer = AppReadiness.model_validate((await http.get(endpoint(card, "ready"))).raise_for_status().json())
+    except (httpx.HTTPError, OSError):
+        return ReadyCheck(f"app {name}", False, _unanswered(folder))
+    if launch is not None and launch["at"] == "demand" and not answer.launched:
+        return ReadyCheck(f"app {name}", True, "its server answers; it launches on demand")
+    if answer.ready:
+        return ReadyCheck(f"app {name}", True, "ready")
+    when = (f"not ready after {answer.timeout_s:.0f} s" if answer.waited_s > answer.timeout_s
+            else f"not ready yet, {answer.waited_s:.0f} s in")
+    return ReadyCheck(f"app {name}", False, f"{when}: {'; '.join(answer.problems)}")
+
+
+def endpoint(card: dict, method: str) -> str:
+    """The path of a ``computer-app/v1`` method, as the app's card advertises it."""
+    return client.find_extension_method(card, COMPUTER_APP, method)["endpoint"]
+
+
+def _unanswered(folder: Path) -> str:
+    try:
+        return f"its server failed to start: {(folder / FAILURE).read_text()}"
+    except FileNotFoundError:
+        return "its server isn't answering yet"
+
+
+def _client(socket: Path) -> httpx.AsyncClient:
+    return httpx.AsyncClient(transport=httpx.AsyncHTTPTransport(uds=str(socket)), base_url="http://app",
+                             timeout=ANSWER_TIMEOUT_S)

agentenv_framework_protocol-0.1.400/src/agentenv_protocol/computer/launch.py

@@ -0,0 +1,25 @@
+"""Launch a computer app through its own server, as its menu launcher does:
+``python -m agentenv_protocol.computer.launch <app folder>`` asks the server on the folder's socket to launch it, so
+the server starts every copy of the app."""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import httpx
+
+from ..types import WELL_KNOWN_PATH
+from .app import SOCKET
+from .apps import endpoint
+
+
+def main(argv: list[str]) -> None:
+    if len(argv) != 1:
+        raise SystemExit("usage: python -m agentenv_protocol.computer.launch <app folder>")
+    with httpx.Client(transport=httpx.HTTPTransport(uds=str(Path(argv[0]) / SOCKET)), base_url="http://app") as http:
+        card = http.get(WELL_KNOWN_PATH).raise_for_status().json()
+        http.post(endpoint(card, "launch"), json={}).raise_for_status()
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])

{agentenv_framework_protocol-0.1.398 → agentenv_framework_protocol-0.1.400}/src/agentenv_protocol/computer/runtime.py

@@ -13,6 +13,7 @@ from mcp.types import CallToolResult
 
 from ..errors import AgentEnvError
 from ..tool_context import ToolContext
+from . import apps
 from .errors import DeliveryFailed, DeviceUnavailable, InputBusy, Internal
 from .frames import Frame, FrameStore, to_pil
 from .operations import GROUPS, INPUT, Display, ReadyCheck, resolve
@@ -40,6 +41,7 @@ class ComputerRuntime:
         self._commands_running: dict[str, asyncio.Task] = {}
         self._commands_finished: OrderedDict = OrderedDict()
         self.recordings = Recordings(self)
+        self.apps = apps.expected()
 
     def has(self, capability: str) -> bool:
         if capability in GROUPS:
@@ -175,6 +177,7 @@ class ComputerRuntime:
             checks += list(await self.driver.ready_checks())
         except Exception as e:
             checks.append(ReadyCheck("driver", False, f"{type(e).__name__}: {e}"))
+        checks += await asyncio.gather(*(apps.check(folder) for folder in self.apps))
         if all(c.ok for c in checks):
             self.ready = True
         return checks