agentenv-framework-protocol 0.1.428__tar.gz → 0.1.432__tar.gz

{agentenv_framework_protocol-0.1.428 → agentenv_framework_protocol-0.1.432}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.428
+Version: 0.1.432
 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
@@ -743,7 +743,7 @@ class MailApp(ComputerAppEnvironment):
 - **`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
+  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
   app installs on, or on those its `os=` names (`@install_step(os="linux")`, `@ready_check(os=[...])`);
@@ -772,9 +772,10 @@ 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 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
+the X display is up, when `DISPLAY` names one, 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.
@@ -795,6 +796,44 @@ requests to the app's server.
 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.
 
+### Website browsers
+
+`agentenv_protocol.website_browser.WebsiteBrowserEnvironment` is the computer app class for a Chromium
+website browser, run inside a computer or alone. A subclass declares its build as any app does, its
+`Launch` running the browser itself. It sets `version`, its build, and `policy_dir`, where that build
+reads managed policies; `policies` adds its own over agentenv's, and `profile` is its profile folder
+under the session user's home (`.config/chromium` by default), whose contents from its install steps
+are the profile's template. The base class adds:
+
+- **Its settings**, `BrowserSettings`, which a subclass's `Settings` extends: `start_urls`, opened in
+  tabs at launch, the first active (`["about:blank"]` by default; none may start with `-`), headless
+  the first from its command line and the rest over its pipe, since headless Chromium takes one; `window`,
+  1280 × 800, alone only; `locale`; and `time_zone`, set as `TZ` in its launch's `env`.
+- **The flags agentenv owns**, after the subclass's command and before the start tabs: its profile,
+  `--remote-debugging-pipe`, `--no-first-run`, `--no-default-browser-check` and `--lang`. With
+  `AGENTENV_SITE_PROXY` set, it goes out through that proxy, with WebRTC's non-proxied UDP off.
+  Alone it bypasses nothing, loopback included; in a computer it bypasses loopback (`127.0.0.1`,
+  `[::1]`, `localhost`), so the apps beside it stay reachable while `*.localhost` names still go
+  through. Alone (`AGENTENV_BROWSER_ALONE=1`) it also takes `--window-size` and `--headless=new`,
+  except on the open web (`AGENTENV_BROWSER_OPEN_WEB=1`), and refuses to start with no proxy.
+  `declaration()` refuses a subclass whose command carries any of these, or `--remote-allow-origins`, or
+  any other way to open a debugging port.
+- **Alone, no desktop**: its launch matches and waits on no window, its server adds no launcher and,
+  without `DISPLAY`, waits for no display, and its ready checks say when it's ready.
+- **`write_policies`**, an install step that writes agentenv's unattended-use policies (`POLICIES`)
+  and the subclass's to `agentenv.json` in `policy_dir`.
+- **A debugging pipe, not a port.** Its server launches it with a new pipe's ends as its fds 3 and 4
+  (`session.launch`'s `fds`, moved into place by `computer/_with_fds.py`, run alone with `-I -S`) and keeps the
+  other ends as `self.devtools`, a `DevToolsPipe`: `await self.devtools.call(method, params)` returns
+  the result or raises `DevToolsError`, and `ConnectionError` with no browser connected. No port
+  listens and no `DevToolsActivePort` is written, so nothing else in the computer can reach it over
+  CDP. Since only the server that launched it holds the pipe, a server that restarts stops it and
+  launches it again. The ready check `devtools_answers` asks `Browser.getVersion` over the pipe.
+- **`browser/v1`** on its card, params only: `chromium` (its `version`), `clock: "real"` and, alone,
+  `window`.
+- **Its skill**: sites by their real names, files to upload in `~/Uploads` and downloads in
+  `~/Downloads`, folders it makes.
+
 ## A2A agent framework
 
 The distribution exposes two unrelated decorators named `extension`:
@@ -909,7 +948,7 @@ protocol. `TaskRequest` and `TaskResult` are framework boundary types; the
 executor maps them to and from the wire-level `a2a.types.Task` lifecycle.
 
 `TaskRequest` is a frozen record whose nested JSON values are detached copies.
-Its `config`, `mcp_servers`, `skills`, `metadata`, and inbound `DataPart.data`
+Its `config`, `mcp_servers`, `cdp_endpoints`, `skills`, `metadata`, and inbound `DataPart.data`
 retain their declared `dict`/`list` types, so normal Pydantic serialization,
 copying, and `json.dumps(...)` work. `TaskRequest.trajectory` is the exception:
 it is the task's live trajectory log, described below. Within `tasks.v1`, new
@@ -1228,6 +1267,20 @@ tools with (agent-env relays the env card's name: the MultiEnv's declared name,
 `env` + 4 random digits, giving e.g. `mcp__env4821__<tool>`); when absent the agent mints
 `mcp_<8 hex>`.
 
+`CDP_CONFIG_V1` gives an agent the CDP endpoints it drives itself. `add` takes
+`name`, `http_url` (`http` or `https`, for clients that discover through
+`/json/version`) and `ws_url` (`ws` or `wss`, for clients that connect
+directly), with optional `headers` and `metadata`; adding a name again replaces
+it. `GET /ext/cdp-config` returns `{"cdp_endpoints": {name: {"has_headers",
+"metadata"}}}`: neither the URLs nor the header values, since either can carry
+the endpoint's credential. `DELETE /ext/cdp-config` with `{"name"}` removes one;
+removing a name that isn't there is not an error. Every task's
+`TaskRequest.cdp_endpoints` holds them in full. `TaskRequest.cdp_endpoint(name=None)`
+returns the named endpoint, or the only one, and otherwise fails the task as an
+`infra_error` with `cdp.no_endpoint` (none, or none by that name) or
+`cdp.ambiguous` (several and no name). It fails the task by raising, so call it
+before any handler of your own that catches every exception.
+
 `PEER_AGENTS_V1` lets an agent delegate to the other agents in its task. AgentEnv
 sets the routing table with `POST /ext/peer-agents` (`{"peers": [{"name", "url",
 "card", "description"}]}`; an empty list clears it, and names must be unique), and

{agentenv_framework_protocol-0.1.428 → agentenv_framework_protocol-0.1.432}/README.md

@@ -687,7 +687,7 @@ class MailApp(ComputerAppEnvironment):
 - **`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
+  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
   app installs on, or on those its `os=` names (`@install_step(os="linux")`, `@ready_check(os=[...])`);
@@ -716,9 +716,10 @@ 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 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
+the X display is up, when `DISPLAY` names one, 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.
@@ -739,6 +740,44 @@ requests to the app's server.
 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.
 
+### Website browsers
+
+`agentenv_protocol.website_browser.WebsiteBrowserEnvironment` is the computer app class for a Chromium
+website browser, run inside a computer or alone. A subclass declares its build as any app does, its
+`Launch` running the browser itself. It sets `version`, its build, and `policy_dir`, where that build
+reads managed policies; `policies` adds its own over agentenv's, and `profile` is its profile folder
+under the session user's home (`.config/chromium` by default), whose contents from its install steps
+are the profile's template. The base class adds:
+
+- **Its settings**, `BrowserSettings`, which a subclass's `Settings` extends: `start_urls`, opened in
+  tabs at launch, the first active (`["about:blank"]` by default; none may start with `-`), headless
+  the first from its command line and the rest over its pipe, since headless Chromium takes one; `window`,
+  1280 × 800, alone only; `locale`; and `time_zone`, set as `TZ` in its launch's `env`.
+- **The flags agentenv owns**, after the subclass's command and before the start tabs: its profile,
+  `--remote-debugging-pipe`, `--no-first-run`, `--no-default-browser-check` and `--lang`. With
+  `AGENTENV_SITE_PROXY` set, it goes out through that proxy, with WebRTC's non-proxied UDP off.
+  Alone it bypasses nothing, loopback included; in a computer it bypasses loopback (`127.0.0.1`,
+  `[::1]`, `localhost`), so the apps beside it stay reachable while `*.localhost` names still go
+  through. Alone (`AGENTENV_BROWSER_ALONE=1`) it also takes `--window-size` and `--headless=new`,
+  except on the open web (`AGENTENV_BROWSER_OPEN_WEB=1`), and refuses to start with no proxy.
+  `declaration()` refuses a subclass whose command carries any of these, or `--remote-allow-origins`, or
+  any other way to open a debugging port.
+- **Alone, no desktop**: its launch matches and waits on no window, its server adds no launcher and,
+  without `DISPLAY`, waits for no display, and its ready checks say when it's ready.
+- **`write_policies`**, an install step that writes agentenv's unattended-use policies (`POLICIES`)
+  and the subclass's to `agentenv.json` in `policy_dir`.
+- **A debugging pipe, not a port.** Its server launches it with a new pipe's ends as its fds 3 and 4
+  (`session.launch`'s `fds`, moved into place by `computer/_with_fds.py`, run alone with `-I -S`) and keeps the
+  other ends as `self.devtools`, a `DevToolsPipe`: `await self.devtools.call(method, params)` returns
+  the result or raises `DevToolsError`, and `ConnectionError` with no browser connected. No port
+  listens and no `DevToolsActivePort` is written, so nothing else in the computer can reach it over
+  CDP. Since only the server that launched it holds the pipe, a server that restarts stops it and
+  launches it again. The ready check `devtools_answers` asks `Browser.getVersion` over the pipe.
+- **`browser/v1`** on its card, params only: `chromium` (its `version`), `clock: "real"` and, alone,
+  `window`.
+- **Its skill**: sites by their real names, files to upload in `~/Uploads` and downloads in
+  `~/Downloads`, folders it makes.
+
 ## A2A agent framework
 
 The distribution exposes two unrelated decorators named `extension`:
@@ -853,7 +892,7 @@ protocol. `TaskRequest` and `TaskResult` are framework boundary types; the
 executor maps them to and from the wire-level `a2a.types.Task` lifecycle.
 
 `TaskRequest` is a frozen record whose nested JSON values are detached copies.
-Its `config`, `mcp_servers`, `skills`, `metadata`, and inbound `DataPart.data`
+Its `config`, `mcp_servers`, `cdp_endpoints`, `skills`, `metadata`, and inbound `DataPart.data`
 retain their declared `dict`/`list` types, so normal Pydantic serialization,
 copying, and `json.dumps(...)` work. `TaskRequest.trajectory` is the exception:
 it is the task's live trajectory log, described below. Within `tasks.v1`, new
@@ -1172,6 +1211,20 @@ tools with (agent-env relays the env card's name: the MultiEnv's declared name,
 `env` + 4 random digits, giving e.g. `mcp__env4821__<tool>`); when absent the agent mints
 `mcp_<8 hex>`.
 
+`CDP_CONFIG_V1` gives an agent the CDP endpoints it drives itself. `add` takes
+`name`, `http_url` (`http` or `https`, for clients that discover through
+`/json/version`) and `ws_url` (`ws` or `wss`, for clients that connect
+directly), with optional `headers` and `metadata`; adding a name again replaces
+it. `GET /ext/cdp-config` returns `{"cdp_endpoints": {name: {"has_headers",
+"metadata"}}}`: neither the URLs nor the header values, since either can carry
+the endpoint's credential. `DELETE /ext/cdp-config` with `{"name"}` removes one;
+removing a name that isn't there is not an error. Every task's
+`TaskRequest.cdp_endpoints` holds them in full. `TaskRequest.cdp_endpoint(name=None)`
+returns the named endpoint, or the only one, and otherwise fails the task as an
+`infra_error` with `cdp.no_endpoint` (none, or none by that name) or
+`cdp.ambiguous` (several and no name). It fails the task by raising, so call it
+before any handler of your own that catches every exception.
+
 `PEER_AGENTS_V1` lets an agent delegate to the other agents in its task. AgentEnv
 sets the routing table with `POST /ext/peer-agents` (`{"peers": [{"name", "url",
 "card", "description"}]}`; an empty list clears it, and names must be unique), and

{agentenv_framework_protocol-0.1.428 → agentenv_framework_protocol-0.1.432}/pyproject.toml

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

{agentenv_framework_protocol-0.1.428 → agentenv_framework_protocol-0.1.432}/src/agentenv_protocol/a2a_agent/__init__.py

@@ -5,6 +5,7 @@ from a2a.types import AgentCapabilities
 from .extensions import (
     AGENT_CONFIG_V1,
     ATTRIBUTION_PROBE_V1,
+    CDP_CONFIG_V1,
     PROXY_V1,
     INSTALL_V1,
     MCP_CONFIG_V1,
@@ -16,6 +17,8 @@ from .extensions import (
     TRIGGERS_V1,
     AttributionProbeResponse,
     BundleSkillRequest,
+    CdpAddRequest,
+    CdpRemoveRequest,
     ChangelogIncrement,
     ContextEventsTrajectoryRequest,
     ContextObjectTrajectoryRequest,
@@ -137,6 +140,7 @@ from ..transfers import (
 __all__ = [
     "AGENT_CONFIG_V1",
     "ATTRIBUTION_PROBE_V1",
+    "CDP_CONFIG_V1",
     "PROXY_V1",
     "INSTALL_V1",
     "MCP_CONFIG_V1",
@@ -157,6 +161,8 @@ __all__ = [
     "AttributionProbeResponse",
     "BuiltinTools",
     "BundleSkillRequest",
+    "CdpAddRequest",
+    "CdpRemoveRequest",
     "ChangelogIncrement",
     "ContextEventsTrajectoryRequest",
     "ContextObjectTrajectoryRequest",

{agentenv_framework_protocol-0.1.428 → agentenv_framework_protocol-0.1.432}/src/agentenv_protocol/a2a_agent/extensions.py

@@ -11,6 +11,7 @@ from dataclasses import dataclass, field
 from enum import Enum
 from types import MappingProxyType
 from typing import Annotated, Any, Literal
+from urllib.parse import urlsplit
 
 from pydantic import (
     BaseModel,
@@ -19,6 +20,7 @@ from pydantic import (
     PositiveInt,
     StrictInt,
     ValidationError,
+    field_validator,
     model_validator,
 )
 
@@ -50,7 +52,9 @@ class ExtensionResponse(BaseModel):
     model_config = ConfigDict(extra="forbid", frozen=True)
 
 
-_SkillName = Annotated[str, Field(pattern=r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")]
+_NAME_PATTERN = r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+_SkillName = Annotated[str, Field(pattern=_NAME_PATTERN)]
+_CdpEndpointName = Annotated[str, Field(pattern=_NAME_PATTERN)]
 
 
 class McpAddRequest(ExtensionRequest):
@@ -59,6 +63,43 @@ class McpAddRequest(ExtensionRequest):
     name: str | None = None
 
 
+def _absolute_url(url: str, schemes: tuple[str, ...]) -> str:
+    """``url``, once it names one of ``schemes``, a host and, if it has one, a valid port."""
+    parts = urlsplit(url)
+    try:
+        valid = parts.scheme in schemes and bool(parts.hostname) and (parts.port is None or parts.port >= 0)
+    except ValueError:
+        valid = False
+    if not valid:
+        raise ValueError(f"must be an absolute {' or '.join(schemes)} URL with a host and a valid port")
+    return url
+
+
+class CdpAddRequest(ExtensionRequest):
+    """A CDP endpoint: ``http_url`` for clients that discover through ``/json/version``, ``ws_url`` for clients
+    that connect to the browser directly."""
+
+    name: _CdpEndpointName
+    http_url: str
+    ws_url: str
+    headers: dict[str, str] | None = None
+    metadata: dict[str, Any] | None = None
+
+    @field_validator("http_url")
+    @classmethod
+    def _http_url(cls, url: str) -> str:
+        return _absolute_url(url, ("http", "https"))
+
+    @field_validator("ws_url")
+    @classmethod
+    def _ws_url(cls, url: str) -> str:
+        return _absolute_url(url, ("ws", "wss"))
+
+
+class CdpRemoveRequest(ExtensionRequest):
+    name: _CdpEndpointName
+
+
 class InlineSkillRequest(ExtensionRequest):
     name: _SkillName
     description: str
@@ -1101,6 +1142,31 @@ MCP_CONFIG_V1 = ExtensionDefinition(
     },
 )
 
+CDP_CONFIG_V1 = ExtensionDefinition(
+    uri="urn:agentenv:cdp-config/v1",
+    description="Register CDP endpoints the agent drives itself.",
+    endpoint="/ext/cdp-config",
+    core_operations={
+        "add": _op(
+            "add",
+            "POST",
+            "/ext/cdp-config",
+            SDK,
+            request_model=CdpAddRequest,
+        ),
+        "list": _op(
+            "list", "GET", "/ext/cdp-config", SDK, response_required=("cdp_endpoints",)
+        ),
+        "remove": _op(
+            "remove",
+            "DELETE",
+            "/ext/cdp-config",
+            SDK,
+            request_model=CdpRemoveRequest,
+        ),
+    },
+)
+
 SKILL_CONFIG_V1 = ExtensionDefinition(
     uri="urn:agentenv:skill-config/v1",
     description="Register skills made available to the agent.",
@@ -1319,6 +1385,7 @@ STANDARD_EXTENSIONS: Mapping[str, ExtensionDefinition] = MappingProxyType(
         for extension in (
             AGENT_CONFIG_V1,
             MCP_CONFIG_V1,
+            CDP_CONFIG_V1,
             SKILL_CONFIG_V1,
             TRAJECTORY_V1,
             SNAPSHOT_V1,

{agentenv_framework_protocol-0.1.428 → agentenv_framework_protocol-0.1.432}/src/agentenv_protocol/a2a_agent/framework.py

@@ -32,6 +32,7 @@ from ._trajectory_log import MAX_TRAJECTORY_READ_BYTES, TaskTrajectories
 from ._triggers import TriggerEngine, TriggerError
 from .extensions import (
     AGENT_CONFIG_V1,
+    CDP_CONFIG_V1,
     MAX_TRAJECTORY_READ_EVENTS,
     MCP_CONFIG_V1,
     PEER_AGENTS_V1,
@@ -41,6 +42,8 @@ from .extensions import (
     ContextEventsTrajectoryRequest,
     ContextObjectTrajectoryRequest,
     ContextTrajectoryRequest,
+    CdpAddRequest,
+    CdpRemoveRequest,
     ExtensionActivation,
     ExtensionDefinition,
     ImplementationOwner,
@@ -66,6 +69,7 @@ from .tasks.v1 import (
     TaskProgress,
     TaskRequest,
     TaskResult,
+    _TaskFailed,
 )
 from .tasks.v1 import (
     DataPart as TaskDataPart,
@@ -541,6 +545,7 @@ class _SdkServices:
             self.config_model
         )
         self.mcp_servers: dict[str, dict[str, Any]] = {}
+        self.cdp_endpoints: dict[str, dict[str, Any]] = {}
         self.task_trajectories = TaskTrajectories()
         self._context_sessions = _BoundedContextSessions()
         self.skills: list[Mapping[str, Any]] = []
@@ -616,6 +621,9 @@ class _SdkServices:
             (AGENT_CONFIG_V1.uri, "get"): self.agent_config_get,
             (MCP_CONFIG_V1.uri, "add"): self.mcp_add,
             (MCP_CONFIG_V1.uri, "list"): self.mcp_list,
+            (CDP_CONFIG_V1.uri, "add"): self.cdp_add,
+            (CDP_CONFIG_V1.uri, "list"): self.cdp_list,
+            (CDP_CONFIG_V1.uri, "remove"): self.cdp_remove,
             (PEER_AGENTS_V1.uri, "set"): self.peer_agents_set,
             (PEER_AGENTS_V1.uri, "list"): self.peer_agents_list,
             (SKILL_CONFIG_V1.uri, "list"): self.skill_list,
@@ -721,6 +729,32 @@ class _SdkServices:
             }
         }
 
+    async def cdp_add(self, request: CdpAddRequest) -> dict[str, Any]:
+        """Adding a name again replaces its endpoint."""
+        self.cdp_endpoints[request.name] = {
+            "http_url": request.http_url,
+            "ws_url": request.ws_url,
+            "headers": dict(request.headers) if request.headers else None,
+            "metadata": dict(request.metadata or {}),
+        }
+        return {"status": "added", "name": request.name}
+
+    async def cdp_list(self) -> dict[str, Any]:
+        """Names and metadata only: an endpoint's URLs can carry its credential, as its headers can."""
+        return {
+            "cdp_endpoints": {
+                name: {
+                    "has_headers": bool(endpoint["headers"]),
+                    "metadata": endpoint["metadata"],
+                }
+                for name, endpoint in self.cdp_endpoints.items()
+            }
+        }
+
+    async def cdp_remove(self, request: CdpRemoveRequest) -> dict[str, Any]:
+        removed = self.cdp_endpoints.pop(request.name, None) is not None
+        return {"status": "removed" if removed else "absent", "name": request.name}
+
     def task_mcp_servers(self) -> dict[str, dict[str, Any]]:
         """The MCP servers a task gets: those registered, and the SDK's peer-agents server when it serves one."""
         peer_tools = self.peers.registration() if self.peers is not None else None
@@ -1238,16 +1272,22 @@ class _StandardExecutor:
                     ),
                     config=task_config,
                     mcp_servers=self._services.task_mcp_servers(),
+                    cdp_endpoints=self._services.cdp_endpoints,
                     skills=tuple(self._services.skills),
                     metadata=metadata,
                     session_ref=self._services.session_ref_for_context(task.context_id),
                     workspace=self._workspace,
                     trajectory=trajectory,
                 )
-                if self._streaming:
-                    result = await self._run_streaming(request, updater, event_queue)
-                else:
-                    result = await self._handler(request)
+                try:
+                    if self._streaming:
+                        result = await self._run_streaming(request, updater, event_queue)
+                    else:
+                        result = await self._handler(request)
+                except _TaskFailed as failed:
+                    result = TaskResult.failure(
+                        failed.error.code, failed.error.message, error_type=failed.error.error_type
+                    )
                 if not isinstance(result, TaskResult):
                     raise TypeError("agent.run must return TaskResult")
                 if result.session_ref is not None:

{agentenv_framework_protocol-0.1.428 → agentenv_framework_protocol-0.1.432}/src/agentenv_protocol/a2a_agent/tasks/v1.py

@@ -217,6 +217,7 @@ class TaskRequest(Generic[ConfigT]):
     parts: tuple[TaskPart, ...]
     config: ConfigT
     mcp_servers: Mapping[str, Any] = field(default_factory=dict)
+    cdp_endpoints: Mapping[str, Any] = field(default_factory=dict)
     skills: tuple[Mapping[str, Any], ...] = ()
     metadata: Mapping[str, Any] = field(default_factory=dict)
     session_ref: str | None = None
@@ -233,11 +234,31 @@ class TaskRequest(Generic[ConfigT]):
         # JSON-native types declared by the config model and request contract.
         object.__setattr__(self, "config", self.config.model_copy(deep=True))
         object.__setattr__(self, "mcp_servers", _copy_json_value(self.mcp_servers))
+        object.__setattr__(self, "cdp_endpoints", _copy_json_value(self.cdp_endpoints))
         object.__setattr__(
             self, "skills", tuple(_copy_json_value(skill) for skill in self.skills)
         )
         object.__setattr__(self, "metadata", _copy_json_value(self.metadata))
 
+    def cdp_endpoint(self, name: str | None = None) -> Mapping[str, Any]:
+        """The CDP endpoint named ``name``, or the turn's only one. Anything else fails the turn, so an agent
+        never falls back to a browser of its own."""
+        if name is not None:
+            if name in self.cdp_endpoints:
+                return self.cdp_endpoints[name]
+            raise _TaskFailed(
+                "cdp.no_endpoint", f"the task gave no browser named {name!r}", error_type="infra_error"
+            )
+        if len(self.cdp_endpoints) == 1:
+            return next(iter(self.cdp_endpoints.values()))
+        if not self.cdp_endpoints:
+            raise _TaskFailed("cdp.no_endpoint", "the task gave no browser", error_type="infra_error")
+        raise _TaskFailed(
+            "cdp.ambiguous",
+            f"the task gave several browsers; name one of {', '.join(sorted(self.cdp_endpoints))}",
+            error_type="infra_error",
+        )
+
 
 class TaskOutcome(str, Enum):
     SUCCEEDED = "succeeded"
@@ -255,6 +276,20 @@ class TaskError:
             raise ValueError("error_type must be 'agent_error' or 'infra_error'")
 
 
+class _TaskFailed(Exception):
+    """Ends the turn as ``TaskResult.failure(code, message, error_type=error_type)``; ``cdp_endpoint`` raises it."""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        *,
+        error_type: Literal["agent_error", "infra_error"] = "agent_error",
+    ) -> None:
+        super().__init__(message)
+        self.error = TaskError(code=code, message=message, error_type=error_type)
+
+
 @dataclass(frozen=True, slots=True, kw_only=True)
 class NativeTrajectory:
     format: str

agentenv_framework_protocol-0.1.432/src/agentenv_protocol/computer/_with_fds.py

@@ -0,0 +1,26 @@
+"""Run a program with fds it inherits moved to the numbers it expects: ``python -I -S _with_fds.py <from>=<to> ... --
+<argv>``. ``session.launch`` runs an app launched with ``fds`` through it, by path, so its server runs no Python between
+its fork and its exec and this loads nothing but the standard library."""
+from __future__ import annotations
+
+import fcntl
+import os
+import sys
+
+
+def main(argv: list[str]) -> None:
+    split = argv.index("--")
+    moves = [tuple(int(number) for number in pair.split("=")) for pair in argv[:split]]
+    # Each source copied above every number named first, so no copy, source or target is another.
+    above = max((number for move in moves for number in move), default=2) + 1
+    copies = [(fcntl.fcntl(source, fcntl.F_DUPFD_CLOEXEC, above), target) for source, target in moves]
+    for source, _ in moves:
+        os.close(source)
+    for copy, target in copies:
+        os.dup2(copy, target)
+        os.close(copy)
+    os.execvp(argv[split + 1], argv[split + 1:])
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])

{agentenv_framework_protocol-0.1.428 → agentenv_framework_protocol-0.1.432}/src/agentenv_protocol/computer/app.py

@@ -169,6 +169,8 @@ class Launch(BaseModel):
     #: 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
+    #: Variables set in the app's environment, over its server's.
+    env: Optional[dict[str, str]] = None
 
     @field_validator("window")
     @classmethod
@@ -399,17 +401,36 @@ class ComputerAppEnvironment(AgentEnvEnvironment):
         self.settings = cls.settings_on(on).model_validate(values)
         self.build_settings = _built_settings(cls, on)
         declared = cls._installs.get(on)
-        self.launch = declared.launch if declared is not None else None
+        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 = self.launch.ready if self.launch is not None else None
+        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)},
-            ready.timeout_s if ready is not None else DEFAULT_TIMEOUT_S)
+            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())
         self._computer_app_data = AppDataPlane(
             self._computer_app, {op: getattr(self, name) for op, name in cls._data_hooks.items()}, self.paths,
             cls.data_timeout_s)
 
+    def _launch_for(self, launch: Launch) -> Launch:
+        """The launch its server uses, from the one declared for its OS, whose ``ready`` timeout it keeps: as
+        declared."""
+        return launch
+
+    def _on_desktop(self) -> bool:
+        """Whether it runs in a computer's desktop session, which lists it in its menu."""
+        return True
+
+    async def _launch_fds(self) -> dict[int, int]:
+        """The fds each launch hands it, by the number each gets in it, made new for that launch: none."""
+        return {}
+
+    def _relaunch_on_start(self) -> bool:
+        """Whether only the server that launched it can talk to it, so a server that restarts launches it again."""
+        return False
+
     @classmethod
     def settings_on(cls, os_type: Optional[str]) -> type[BaseModel]:
         """Its ``Settings`` on ``os_type``, with the fields its OS adds."""

{agentenv_framework_protocol-0.1.428 → agentenv_framework_protocol-0.1.432}/src/agentenv_protocol/computer/app_runtime.py

@@ -48,30 +48,51 @@ 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:
+    def __init__(self, launch: Optional[Launch], ready_checks: dict[str, Callable[[], Any]], timeout_s: float, *,
+                 desktop: bool = True, launch_fds: Optional[Callable[[], Awaitable[dict[int, int]]]] = None,
+                 relaunch_on_start: bool = False) -> None:
         self.launch = launch
         self.ready_checks = ready_checks
         self.timeout_s = timeout_s
+        self.desktop = desktop
+        self.launch_fds = launch_fds
+        self.relaunch_on_start = relaunch_on_start
         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."""
+        """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: 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
-        await session.wait_until_up()
-        session.add_launcher(os.environ["ENVIRONMENT_NAME"], Path.cwd())
-        if self.launch.at == "boot" and _launched_at() is None:
+        if os.environ.get("DISPLAY"):
+            await session.wait_until_up()
+        if self.desktop:
+            session.add_launcher(os.environ["ENVIRONMENT_NAME"], Path.cwd())
+        launched = _launched_at() is not None
+        relaunch = self.relaunch_on_start and launched
+        if relaunch or (self.launch.at == "boot" and not launched):
             try:
+                if relaunch:
+                    await self.stop_app()
                 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"]})
+        """Start the app from its folder, marked as launched, with the fds the app gives it, whose copies here are
+        closed once it has them; its pid."""
+        fds = await self.launch_fds() if self.launch_fds is not None else {}
+        try:
+            pid = await session.launch(self.launch.command, Path.cwd(),
+                                       {**(self.launch.env or {}), "ENVIRONMENT_NAME": os.environ["ENVIRONMENT_NAME"]},
+                                       **({"fds": fds} if fds else {}))
+        finally:
+            for fd in fds.values():
+                os.close(fd)
         self.launch_failed = None
         PID.parent.mkdir(parents=True, exist_ok=True)
         PID.write_text(str(pid))