agentenv-framework-protocol 0.1.420__tar.gz → 0.1.421__tar.gz

{agentenv_framework_protocol-0.1.420 → agentenv_framework_protocol-0.1.421}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.420
+Version: 0.1.421
 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
@@ -283,6 +283,23 @@ async def display_get(self) -> dict: ...
 async def display_set(self, width: int, height: int) -> dict: ...
 ```
 
+### Framework-only routes and the control token
+
+Everything an environment serves but its MCP endpoint and its card is agent-env's own: the data
+plane, every `@extension` route and the tool-access routes. When agent-env deploys an environment
+that takes one, it boots it with a per-deploy token in `AGENTENV_CONTROL_TOKEN`
+(`CONTROL_TOKEN_ENV`), and the SDK then refuses a call to those routes that doesn't carry it as
+`Authorization: Bearer <token>`, answering 401 with the code `unauthorized` before the route runs.
+The MCP endpoint and the card stay open, so an agent reaches the environment's tools as before and
+nothing else. Without the variable, as when the environment runs on its own, every route is open.
+`control_guard()` wraps a route an environment adds itself the same way, as a computer driver does
+its `/svc/<app>/` routes.
+
+On the client side each call takes `headers`, and `client.control_headers(token)` builds them.
+Code that names none runs under `client.authorized({env_url: client.control_headers(token)})`:
+within it, a call to an address under `env_url` sends those headers. agent-env runs every task
+step, a verifier's `verify` included, under such a grant for each environment it deployed.
+
 ### Tool access without a gateway
 
 An environment agents reach directly, with no gateway in front, can enforce per-role tool access
@@ -644,7 +661,10 @@ report = await run_probe("http://localhost:18765", "full")   # a ProbeReport
 failed = [c for c in report.checks if c.status == "failed"]
 ```
 
-The CLI exits 0 when no check failed, 1 when one did and 2 when it can't reach the driver.
+The CLI exits 0 when no check failed, 1 when one did and 2 when it can't reach the driver. A
+driver booted with a control token is probed with it: `--token`, by default
+`$AGENTENV_CONTROL_TOKEN`, or `run_probe(..., token=...)`. Given one, the probe also checks that
+`computer-ready`'s status refuses a call without it and with a wrong one.
 
 | Level | Checks | Needs on the computer |
 |---|---|---|

{agentenv_framework_protocol-0.1.420 → agentenv_framework_protocol-0.1.421}/README.md

@@ -227,6 +227,23 @@ async def display_get(self) -> dict: ...
 async def display_set(self, width: int, height: int) -> dict: ...
 ```
 
+### Framework-only routes and the control token
+
+Everything an environment serves but its MCP endpoint and its card is agent-env's own: the data
+plane, every `@extension` route and the tool-access routes. When agent-env deploys an environment
+that takes one, it boots it with a per-deploy token in `AGENTENV_CONTROL_TOKEN`
+(`CONTROL_TOKEN_ENV`), and the SDK then refuses a call to those routes that doesn't carry it as
+`Authorization: Bearer <token>`, answering 401 with the code `unauthorized` before the route runs.
+The MCP endpoint and the card stay open, so an agent reaches the environment's tools as before and
+nothing else. Without the variable, as when the environment runs on its own, every route is open.
+`control_guard()` wraps a route an environment adds itself the same way, as a computer driver does
+its `/svc/<app>/` routes.
+
+On the client side each call takes `headers`, and `client.control_headers(token)` builds them.
+Code that names none runs under `client.authorized({env_url: client.control_headers(token)})`:
+within it, a call to an address under `env_url` sends those headers. agent-env runs every task
+step, a verifier's `verify` included, under such a grant for each environment it deployed.
+
 ### Tool access without a gateway
 
 An environment agents reach directly, with no gateway in front, can enforce per-role tool access
@@ -588,7 +605,10 @@ report = await run_probe("http://localhost:18765", "full")   # a ProbeReport
 failed = [c for c in report.checks if c.status == "failed"]
 ```
 
-The CLI exits 0 when no check failed, 1 when one did and 2 when it can't reach the driver.
+The CLI exits 0 when no check failed, 1 when one did and 2 when it can't reach the driver. A
+driver booted with a control token is probed with it: `--token`, by default
+`$AGENTENV_CONTROL_TOKEN`, or `run_probe(..., token=...)`. Given one, the probe also checks that
+`computer-ready`'s status refuses a call without it and with a wrong one.
 
 | Level | Checks | Needs on the computer |
 |---|---|---|

{agentenv_framework_protocol-0.1.420 → agentenv_framework_protocol-0.1.421}/pyproject.toml

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

{agentenv_framework_protocol-0.1.420 → agentenv_framework_protocol-0.1.421}/src/agentenv_protocol/__init__.py

@@ -53,6 +53,7 @@ from .manifest import (
     manifest_compatible,
 )
 from .types import (
+    CONTROL_TOKEN_ENV,
     DATA_OBJECTS_EXTENSION_URI,
     INTAKE_EXTENSION_URI,
     MCP_PATH,
@@ -161,6 +162,7 @@ __all__ = [
     "ExtensionCallError",
     "PROTOCOL_VERSION",
     "RPC_PATH",
+    "CONTROL_TOKEN_ENV",
     "WELL_KNOWN_PATH",
     "METHOD_RESET",
     "METHOD_ADD",

{agentenv_framework_protocol-0.1.420 → agentenv_framework_protocol-0.1.421}/src/agentenv_protocol/agent_env_environment.py

@@ -5,6 +5,7 @@ import datetime
 import decimal
 import enum
 import functools
+import hmac
 import inspect
 import json
 import logging
@@ -28,7 +29,7 @@ from .tool_access import DISABLE as TOOL_DISABLE, ENABLE as TOOL_ENABLE, PATHS a
 from .tool_access import extensions as tool_access_extensions
 from .tool_context import EMPTY, ToolContext, bound, context_from_http, context_from_mcp
 from .transfers import WriteNamespaceGrant
-from .types import DATA_OBJECTS_EXTENSION_URI, MCP_TRANSPORT, SKILL_EXTENSION_URI, METHOD_ADD, METHOD_GET, METHOD_RESET, RPC_PATH, WELL_KNOWN_PATH, AddDataRequest, AddDataResponse, EnvironmentCapabilities, EnvironmentCard, EnvironmentExtension, EnvironmentInterface, EnvironmentTool, GetDataResponse, ResetDataResponse, error_body
+from .types import CONTROL_TOKEN_ENV, DATA_OBJECTS_EXTENSION_URI, MCP_TRANSPORT, SKILL_EXTENSION_URI, METHOD_ADD, METHOD_GET, METHOD_RESET, RPC_PATH, WELL_KNOWN_PATH, AddDataRequest, AddDataResponse, EnvironmentCapabilities, EnvironmentCard, EnvironmentExtension, EnvironmentInterface, EnvironmentTool, GetDataResponse, ResetDataResponse, error_body
 
 logger = logging.getLogger(__name__)
 
@@ -343,10 +344,11 @@ class AgentEnvApplication(ABC):
         if isinstance(self.handler, AgentEnvEnvironment):
             self.handler._application = self
         self.environment_card = self._card_for(app)
-        self._add_route(app, rpc_url, ["POST"], self._dispatch)
+        guard = control_guard()
+        self._add_route(app, rpc_url, ["POST"], guard(self._dispatch))
         self._add_route(app, card_url, ["GET"], self._serve_card)
         for path, method, handler in self._ext_routes:
-            self._add_route(app, path, [method], handler)
+            self._add_route(app, path, [method], guard(handler))
         for descriptor, fn in self._tools:
             self._register_tool(app, descriptor, fn)
         for resource in self._resources:
@@ -1544,6 +1546,25 @@ def _error_response(error: AgentEnvError) -> Response:
     return _json_response(error_body(**error.fields()), error.status)
 
 
+def control_guard() -> Callable[[Callable], Callable]:
+    """What wraps a framework-only route, everything an env serves but its MCP endpoint and its card: with
+    ``CONTROL_TOKEN_ENV`` set, a call that doesn't carry that token as its bearer is refused before the route runs;
+    without it, nothing."""
+    token = os.environ.get(CONTROL_TOKEN_ENV)
+    if not token:
+        return lambda handler: handler
+    expected = f"Bearer {token}".encode()
+
+    def guard(handler: Callable) -> Callable:
+        async def guarded(request: Request) -> Response:
+            if not hmac.compare_digest(request.headers.get("authorization", "").encode(), expected):
+                return _error_response(AgentEnvError(
+                    "unauthorized", "this route is agent-env's own: it takes the env's control token", status=401))
+            return await handler(request)
+        return guarded
+    return guard
+
+
 def _tool_access_handler(access: ToolAccess, action: str) -> Callable:
     async def handler(request: Request) -> Response:
         raw = await request.body()

{agentenv_framework_protocol-0.1.420 → agentenv_framework_protocol-0.1.421}/src/agentenv_protocol/client.py

@@ -1,7 +1,12 @@
-"""Data-plane wire protocol client (JSON-RPC) for servers implementing the AgentEnv protocol."""
+"""Data-plane wire protocol client (JSON-RPC) for servers implementing the AgentEnv protocol. A call to an env's
+framework-only routes carries its control token: as the call's ``headers`` (``control_headers``), or, for code that
+names none, from the grant it runs under (``authorized``)."""
 from __future__ import annotations
 
+import contextlib
 import logging
+from collections.abc import Iterator
+from contextvars import ContextVar
 
 import httpx
 
@@ -11,6 +16,9 @@ from .types import INTAKE_EXTENSION_URI, MCP_PATH, MCP_TRANSPORT, METHOD_ADD, ME
 
 logger = logging.getLogger(__name__)
 
+#: The headers that carry the control token of each env address the running code is granted, by address.
+_GRANTS: ContextVar[dict[str, dict[str, str]]] = ContextVar("agentenv_control_grants", default={})
+
 
 class ExtensionCallError(httpx.HTTPStatusError):
     """A non-2xx answer from an extension method, with the error fields the server sent. A body without them
@@ -35,10 +43,45 @@ def _error_fields(response: httpx.Response) -> dict:
     return error if isinstance(error, dict) else {}
 
 
-async def _rpc(base_url: str, method: str, params: dict, timeout: int, verify: bool) -> dict:
+def control_headers(token: str | None) -> dict[str, str]:
+    """The headers that carry an env's control token to its framework-only routes; none without one."""
+    return {"Authorization": f"Bearer {token}"} if token else {}
+
+
+@contextlib.contextmanager
+def authorized(grants: dict[str | None, dict[str, str]]) -> Iterator[None]:
+    """Within it, a call to an address under one of ``grants``, an env's address and the headers that carry its
+    control token (``control_headers``), sends those headers when the call names none of its own: how the steps
+    agent-env runs, and the verifiers they call, reach an env's framework-only routes as written."""
+    granted = _GRANTS.set({**_GRANTS.get(),
+                           **{url.rstrip("/"): sent for url, sent in grants.items() if url and sent}})
+    try:
+        yield
+    finally:
+        _GRANTS.reset(granted)
+
+
+def request_headers(url: str, headers: dict[str, str] | None = None) -> dict[str, str]:
+    """What a call to ``url`` sends: ``headers`` when it names them, else the headers its grant gives
+    (``authorized``), if any."""
+    if headers is not None:
+        return headers
+    return granted_headers(url, _GRANTS.get())
+
+
+def granted_headers(url: str, grants: dict[str | None, dict[str, str]]) -> dict[str, str]:
+    """What ``grants``, env addresses and the headers that carry their control tokens, give a call to ``url``: those of
+    the address it is or is under, and none anywhere else."""
+    return next((sent for base, sent in grants.items()
+                 if base and (url == base.rstrip("/") or url.startswith(f"{base.rstrip('/')}/"))), {})
+
+
+async def _rpc(base_url: str, method: str, params: dict, timeout: int, verify: bool,
+               headers: dict[str, str] | None) -> dict:
     request = {"jsonrpc": "2.0", "id": 1, "method": method, "params": params}
+    url = f"{base_url}{RPC_PATH}"
     async with httpx.AsyncClient(verify=verify) as client:
-        response = await client.post(f"{base_url}{RPC_PATH}", json=request, timeout=timeout)
+        response = await client.post(url, json=request, timeout=timeout, headers=request_headers(url, headers))
         response.raise_for_status()
         body = response.json()
     if "error" in body:
@@ -47,18 +90,20 @@ async def _rpc(base_url: str, method: str, params: dict, timeout: int, verify: b
     return body["result"]
 
 
-async def reset_data(base_url: str, timeout: int = 30, verify: bool = True) -> ResetDataResponse:
-    return ResetDataResponse.model_validate(await _rpc(base_url, METHOD_RESET, {}, timeout, verify))
+async def reset_data(base_url: str, timeout: int = 30, verify: bool = True, *,
+                     headers: dict[str, str] | None = None) -> ResetDataResponse:
+    return ResetDataResponse.model_validate(await _rpc(base_url, METHOD_RESET, {}, timeout, verify, headers))
 
 
-async def add_data(base_url: str, parts: list[Part], timeout: int = 120, verify: bool = True) -> AddDataResponse:
+async def add_data(base_url: str, parts: list[Part], timeout: int = 120, verify: bool = True, *,
+                   headers: dict[str, str] | None = None) -> AddDataResponse:
     params = {"parts": [p.model_dump(mode="json", exclude_none=True) for p in parts]}
-    return AddDataResponse.model_validate(await _rpc(base_url, METHOD_ADD, params, timeout, verify))
+    return AddDataResponse.model_validate(await _rpc(base_url, METHOD_ADD, params, timeout, verify, headers))
 
 
 async def get_data(
     base_url: str, timeout: int = 30, verify: bool = True, *, write_namespace: WriteNamespaceGrant | None = None,
-    paths: list[str] | None = None,
+    paths: list[str] | None = None, headers: dict[str, str] | None = None,
 ) -> GetDataResponse:
     """`data/get`. A server advertising `DATA_OBJECTS_EXTENSION_URI` may be handed `write_namespace` to upload
     its export under; `uploaded_object_path` reads from the answer where it did. `paths` names what a computer
@@ -66,7 +111,7 @@ async def get_data(
     params = {} if write_namespace is None else {"write_namespace": write_namespace.model_dump(mode="json", exclude_none=True)}
     if paths is not None:
         params["paths"] = paths
-    return GetDataResponse.model_validate(await _rpc(base_url, METHOD_GET, params, timeout, verify))
+    return GetDataResponse.model_validate(await _rpc(base_url, METHOD_GET, params, timeout, verify, headers))
 
 
 async def get_card(base_url: str, timeout: int = 10, verify: bool = True) -> dict:
@@ -180,7 +225,8 @@ def find_child(card: dict, name: str) -> dict | None:
     return None
 
 
-async def get_interface_manifest(base_url: str, interface: str, endpoint: str = INTERFACE_MANIFEST_PATH, timeout: int = 30, verify: bool = True):
+async def get_interface_manifest(base_url: str, interface: str, endpoint: str = INTERFACE_MANIFEST_PATH, timeout: int = 30, verify: bool = True, *,
+                                 headers: dict[str, str] | None = None):
     """Fetch one interface's manifest from a server's manifest index endpoint.
 
     ``endpoint`` is the index path — pass the one advertised on the card under
@@ -191,12 +237,13 @@ async def get_interface_manifest(base_url: str, interface: str, endpoint: str =
     """
     url = f"{base_url.rstrip('/')}{endpoint}/{interface}"
     async with httpx.AsyncClient(verify=verify) as client:
-        response = await client.get(url, timeout=timeout)
+        response = await client.get(url, timeout=timeout, headers=request_headers(url, headers))
         response.raise_for_status()
         return response.json()
 
 
-async def invoke_extension(base_url: str, card: dict, uri: str, params: dict | None = None, timeout: int = 30, verify: bool = True, *, method: str | None = None):
+async def invoke_extension(base_url: str, card: dict, uri: str, params: dict | None = None, timeout: int = 30, verify: bool = True, *, method: str | None = None,
+                           headers: dict[str, str] | None = None):
     """Invoke a card extension via its advertised REST endpoint.
 
     Reads the endpoint and HTTP verb of the extension method named `method` from the card, so the
@@ -215,11 +262,12 @@ async def invoke_extension(base_url: str, card: dict, uri: str, params: dict | N
     if not op["endpoint"]:
         raise ValueError(f"extension {uri} has no endpoint in params")
     url = f"{base_url}{op['endpoint']}"
+    sent = request_headers(url, headers)
     async with httpx.AsyncClient(verify=verify) as client:
         if op["method"] == "GET":
-            response = await client.get(url, params=params or {}, timeout=timeout)
+            response = await client.get(url, params=params or {}, timeout=timeout, headers=sent)
         else:
-            response = await client.request(op["method"], url, json=params or {}, timeout=timeout)
+            response = await client.request(op["method"], url, json=params or {}, timeout=timeout, headers=sent)
         if response.status_code >= 400:
             raise ExtensionCallError(response)
         return response.json()

{agentenv_framework_protocol-0.1.420 → agentenv_framework_protocol-0.1.421}/src/agentenv_protocol/computer/conformance/__init__.py

@@ -11,9 +11,11 @@ from .report import CheckResult, Level, ProbeReport, Status, Verdict
 __all__ = ["run_probe", "ProbeReport", "CheckResult", "Level", "Status", "Verdict"]
 
 
-async def run_probe(url: str, level: Level = "full", *, timeout_s: float = 60, ready_timeout_s: float = 60) -> ProbeReport:
-    """Probe the driver serving its card at ``url``. ``ready_timeout_s`` is how long it may take to report ready."""
-    driver = await Driver.connect(url, timeout_s)
+async def run_probe(url: str, level: Level = "full", *, timeout_s: float = 60, ready_timeout_s: float = 60,
+                    token: str | None = None) -> ProbeReport:
+    """Probe the driver serving its card at ``url``, sending ``token``, its control token, to its framework-only routes.
+    ``ready_timeout_s`` is how long it may take to report ready."""
+    driver = await Driver.connect(url, timeout_s, token)
     async with driver.session() as session:
         probe = Probe(driver, session, ready_timeout_s)
         await probe.basic()

{agentenv_framework_protocol-0.1.420 → agentenv_framework_protocol-0.1.421}/src/agentenv_protocol/computer/conformance/__main__.py

@@ -1,12 +1,15 @@
 """``python -m agentenv_protocol.computer.conformance <driver url>``: probe a running driver, print each check, and
-exit 1 when one failed or 2 when the driver couldn't be reached."""
+exit 1 when one failed or 2 when the driver couldn't be reached. ``--token`` is its control token, by default
+``CONTROL_TOKEN_ENV``'s."""
 from __future__ import annotations
 
 import argparse
 import asyncio
+import os
 import sys
 from pathlib import Path
 
+from ...types import CONTROL_TOKEN_ENV
 from . import run_probe
 
 _MARK = {"passed": "PASS", "failed": "FAIL", "unverified": "----", "not_applicable": "n/a "}
@@ -19,9 +22,12 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--level", choices=("basic", "full"), default="full")
     parser.add_argument("--json", type=Path, help="also write the report to this file")
     parser.add_argument("--timeout", type=float, default=60, help="seconds for each call, and to report ready")
+    parser.add_argument("--token", default=os.environ.get(CONTROL_TOKEN_ENV),
+                        help=f"the driver's control token, if it was given one (default: ${CONTROL_TOKEN_ENV})")
     args = parser.parse_args(argv)
     try:
-        report = asyncio.run(run_probe(args.url, args.level, timeout_s=args.timeout, ready_timeout_s=args.timeout))
+        report = asyncio.run(run_probe(args.url, args.level, timeout_s=args.timeout, ready_timeout_s=args.timeout,
+                                       token=args.token))
     except Exception as e:
         print(f"couldn't probe {args.url}: {type(e).__name__}: {e}", file=sys.stderr)
         return 2

{agentenv_framework_protocol-0.1.420 → agentenv_framework_protocol-0.1.421}/src/agentenv_protocol/computer/conformance/checks.py

@@ -88,7 +88,8 @@ class Probe:
         for check, section in (("P0", self._ready), ("P1", self._card), ("P2", self._frame), ("P5", self._refusals),
                                ("X", self._display), ("X", self._spaces), ("X", self._keyboard_settings),
                                ("X", self._exec), ("X", self._data_get), ("X", self._app_exports),
-                               ("X", self._tool_access), ("X", self._pointer), ("X", self._skill)):
+                               ("X", self._tool_access), ("X", self._pointer), ("X", self._skill),
+                               ("X", self._control)):
             await self._guarded(check, section)
         self._grants()
 
@@ -422,6 +423,24 @@ class Probe:
             await self.check("X", f"app {app.get('name')}'s data/get answers its parts through the driver", export,
                              *DATA_PLANE)
 
+    async def _control(self) -> None:
+        if not self.driver.headers:
+            return
+
+        async def refused() -> str | None:
+            for sent, without in (({}, "without"), (protocol.control_headers("not-its-token"), "with a wrong")):
+                try:
+                    await protocol.invoke_extension(self.driver.url, self.driver.card, COMPUTER_READY, method="status",
+                                                    timeout=int(self.driver.timeout_s), headers=sent)
+                except ExtensionCallError as e:
+                    if e.response.status_code != 401:
+                        return f"computer-ready status answered a call {without} control token {e.response.status_code}"
+                    continue
+                return f"computer-ready status answered a call {without} control token"
+            return None
+
+        await self.check("X", "a framework-only route refuses a call without the control token", refused)
+
     async def _tool_access(self) -> None:
         if not (self.driver.declares(DISABLE_TOOL_EXTENSION_URI) and self.driver.declares(ENABLE_TOOL_EXTENSION_URI)):
             return

{agentenv_framework_protocol-0.1.420 → agentenv_framework_protocol-0.1.421}/src/agentenv_protocol/computer/conformance/client.py

@@ -24,14 +24,15 @@ STREAM_READ_S = 300
 
 
 class Driver:
-    def __init__(self, url: str, card: dict, timeout_s: float) -> None:
+    def __init__(self, url: str, card: dict, timeout_s: float, token: str | None = None) -> None:
         self.url = url.rstrip("/")
         self.card = card
         self.timeout_s = timeout_s
+        self.headers = protocol.control_headers(token) if token else None
 
     @classmethod
-    async def connect(cls, url: str, timeout_s: float) -> Driver:
-        return cls(url, await protocol.get_card(url.rstrip("/"), timeout=int(timeout_s)), timeout_s)
+    async def connect(cls, url: str, timeout_s: float, token: str | None = None) -> Driver:
+        return cls(url, await protocol.get_card(url.rstrip("/"), timeout=int(timeout_s)), timeout_s, token)
 
     @property
     def name(self) -> str:
@@ -59,12 +60,13 @@ class Driver:
 
     async def invoke(self, uri: str, method: str, params: dict | None = None) -> Any:
         return await protocol.invoke_extension(self.url, self.card, uri, params or {}, method=method,
-                                               timeout=int(self.timeout_s))
+                                               timeout=int(self.timeout_s), headers=self.headers)
 
     async def rpc(self, method: str, params: dict | None = None, card: dict | None = None) -> dict:
         """``method``'s answer from the data plane of ``card``, the driver's own or a child's it fronts."""
         async with httpx.AsyncClient(timeout=self.timeout_s) as http:
-            response = await http.post(self.url + ((card or self.card).get("url") or "/agentenv"),
+            url = self.url + ((card or self.card).get("url") or "/agentenv")
+            response = await http.post(url, headers=protocol.request_headers(url, self.headers),
                                        json={"jsonrpc": "2.0", "id": 1, "method": method, "params": params or {}})
         return response.json()
 

{agentenv_framework_protocol-0.1.420 → agentenv_framework_protocol-0.1.421}/src/agentenv_protocol/computer/driver.py

@@ -12,7 +12,7 @@ from starlette.requests import Request
 from starlette.responses import Response
 
 from ..agent_env_environment import (_CARD_CONFIG_ATTR, AgentEnvEnvironment, AgentEnvFastMCPApplication,
-                                     _error_response, environment_card)
+                                     _error_response, control_guard, environment_card)
 from ..tool_context import ToolContext
 from ..types import EnvironmentCard, EnvironmentExtension, EnvironmentTool
 from . import _linux, apps, card
@@ -135,7 +135,7 @@ class ComputerDriverEnvironment(Tools, Extensions, DataPlane, AgentEnvEnvironmen
         return await apps.children(self._computer.apps) if self._computer.apps else None
 
     def _computer_front_apps(self, app: Any) -> Any:
-        app.custom_route("/svc/{name}/{path:path}", methods=["GET", "POST"])(self._computer_forward)
+        app.custom_route("/svc/{name}/{path:path}", methods=["GET", "POST"])(control_guard()(self._computer_forward))
         return app
 
     async def _computer_forward(self, request: Request) -> Response:

{agentenv_framework_protocol-0.1.420 → agentenv_framework_protocol-0.1.421}/src/agentenv_protocol/computer/serve_app.py

@@ -1,19 +1,22 @@
 """Serve a computer app's class from its file, as its computer's program starts it:
 ``python -m agentenv_protocol.computer.serve_app <file>:<Class>``, run in the app's folder, serves the class's card and
-``computer-app/v1`` on the Unix socket ``.agentenv/server.sock`` there. Before it serves, it keeps a copy of the app's
-data paths as installed, which a reset puts back; once it serves, it adds the app's launcher and launches a boot app
-(``AppRuntime.start``). A server that can't start, or whose start fails once it serves,
-writes why to ``.agentenv/server.failure``, which its computer's driver reports, and exits. Needs the ``app`` extra."""
+``computer-app/v1`` on the Unix socket ``.agentenv/server.sock`` there, which only the computer reaches, so it takes no
+control token (``CONTROL_TOKEN_ENV``): the driver checks it in front of the app. Before it serves, it keeps a copy of
+the app's data paths as installed, which a reset puts back; once it serves, it adds the app's launcher and launches a
+boot app (``AppRuntime.start``). A server that can't start, or whose start fails once it serves, writes why to
+``.agentenv/server.failure``, which its computer's driver reports, and exits. Needs the ``app`` extra."""
 from __future__ import annotations
 
 import asyncio
 import contextlib
+import os
 import sys
 import traceback
 from pathlib import Path
 
 import uvicorn
 
+from ..types import CONTROL_TOKEN_ENV
 from ._load import load_class
 from .app import FAILURE, SOCKET, ComputerAppEnvironment
 
@@ -35,6 +38,7 @@ def _serve(argv: list[str]) -> None:
     if len(argv) != 1 or ":" not in argv[0]:
         raise SystemExit(USAGE)
     file, _, name = argv[0].partition(":")
+    os.environ.pop(CONTROL_TOKEN_ENV, None)
     app = load_class(Path(file), name, ComputerAppEnvironment)()
     runtime = app._computer_app_runtime()
     app._computer_app_data_plane().keep_initial()

{agentenv_framework_protocol-0.1.420 → agentenv_framework_protocol-0.1.421}/src/agentenv_protocol/types.py

@@ -16,6 +16,9 @@ PROTOCOL_VERSION = "1.0"
 
 WELL_KNOWN_PATH = "/.well-known/agent-env.json"
 RPC_PATH = "/agentenv"
+#: The variable that hands an env the token its framework-only routes take as their bearer, everything it serves but
+#: its MCP endpoint and its card; agent-env sets it when it deploys the env, and without it those routes are open.
+CONTROL_TOKEN_ENV = "AGENTENV_CONTROL_TOKEN"
 
 # A card declares its MCP endpoint as an `additionalInterfaces` entry with this transport; a card
 # without one is reached at MCP_PATH by convention.

{agentenv_framework_protocol-0.1.420 → agentenv_framework_protocol-0.1.421}/tests/test_computer_app_server.py

@@ -1,6 +1,7 @@
 """A computer app's own server: it adds the app's launcher, launches a boot app once per boot and says whether the app
 is ready (``computer-app/v1``); its computer's driver finds it on the socket in the app's folder and asks it, lists it
-as a child environment and forwards its requests to it, and leaves the paths it owns out of its own data/get."""
+as a child environment and forwards its requests to it, only with the computer's control token when it has one, and
+leaves the paths it owns out of its own data/get."""
 from __future__ import annotations
 
 import asyncio
@@ -31,7 +32,7 @@ from agentenv_protocol.computer import (ComputerAppEnvironment, Launch, ReadyChe
 from agentenv_protocol.computer import app, app_runtime, apps, session  # noqa: E402
 from agentenv_protocol.computer.app import COMPUTER_APP, FAILURE, SOCKET  # noqa: E402
 from agentenv_protocol.computer.platform import Platform  # noqa: E402
-from agentenv_protocol.types import DATA_OBJECTS_EXTENSION_URI, WELL_KNOWN_PATH  # noqa: E402
+from agentenv_protocol.types import CONTROL_TOKEN_ENV, DATA_OBJECTS_EXTENSION_URI, WELL_KNOWN_PATH  # noqa: E402
 
 
 
@@ -311,6 +312,30 @@ async def test_the_driver_lists_its_apps_as_children_forwards_each_ones_requests
         "Documents/note.txt"]
 
 
+@pytest.mark.asyncio
+async def test_with_a_control_token_the_driver_lists_its_apps_and_forwards_to_one_only_with_it(tmp_path, monkeypatch):
+    from computer_fake import FakeDriver, http_client
+
+    monkeypatch.setenv("HOME", str(tmp_path))
+    (tmp_path / "Mail").mkdir()
+    (tmp_path / "Mail/inbox.txt").write_text("hi")
+    get = {"jsonrpc": "2.0", "id": 1, "method": "data/get", "params": {}}
+    with tempfile.TemporaryDirectory(dir="/tmp", prefix="apps-") as root:
+        monkeypatch.setattr(apps, "APPS", Path(root))
+        async with _serving(Inbox(), Path(root) / "mail", monkeypatch):
+            monkeypatch.setenv(CONTROL_TOKEN_ENV, "s3cret")
+            async with http_client(FakeDriver()) as http:
+                card = (await http.get(WELL_KNOWN_PATH)).json()
+                refused = [await http.post("/svc/mail/agentenv", json=get, headers=headers)
+                           for headers in ({}, client.control_headers("guess"))]
+                forwarded = await http.post("/svc/mail/agentenv", json=get, headers=client.control_headers("s3cret"))
+
+    assert [child["name"] for child in card["children_environments"]] == ["mail"]
+    assert [answer.status_code for answer in refused] == [401, 401]
+    assert [part["metadata"][DATA_OBJECTS_EXTENSION_URI]["path"] for part in forwarded.json()["result"]["parts"]] == [
+        "Mail/inbox.txt"]
+
+
 @pytest.mark.asyncio
 async def test_the_session_launches_an_app_in_a_session_of_its_own_from_its_folder(tmp_path, monkeypatch):
     monkeypatch.setenv("DISPLAY", ":99")

{agentenv_framework_protocol-0.1.420 → agentenv_framework_protocol-0.1.421}/tests/test_computer_conformance.py

@@ -1,6 +1,7 @@
 """The conformance probe against fake drivers on loopback: the fake driver with the fake fixture passes every check; a
-driver without what full needs gets those checks unverified; a driver broken one way fails the check for that way; each
-app a driver fronts that exports is asked for its export once; the report's verdicts and the CLI."""
+driver given a control token passes with it, refusing calls without it, and fails without it; a driver without what
+full needs gets those checks unverified; a driver broken one way fails the check for that way; each app a driver
+fronts that exports is asked for its export once; the report's verdicts and the CLI."""
 from __future__ import annotations
 
 import json
@@ -33,6 +34,7 @@ from agentenv_protocol.computer.conformance import CheckResult, ProbeReport, run
 from agentenv_protocol.computer.conformance import checks  # noqa: E402
 from agentenv_protocol.computer.conformance.client import Driver  # noqa: E402
 from agentenv_protocol.computer.conformance.__main__ import main  # noqa: E402
+from agentenv_protocol import CONTROL_TOKEN_ENV  # noqa: E402
 from agentenv_protocol.tool_access import DISABLE_TOOL_EXTENSION_URI  # noqa: E402
 from agentenv_protocol.types import EnvironmentCard  # noqa: E402
 
@@ -71,6 +73,18 @@ async def test_the_fake_driver_passes_every_check_at_full_and_cleans_up(home):
     assert ["kill", "4242"] in driver.commands
 
 
+@pytest.mark.asyncio
+async def test_a_driver_given_a_control_token_passes_with_it_and_refuses_calls_without_it(monkeypatch):
+    monkeypatch.setenv(CONTROL_TOKEN_ENV, "s3cret")
+
+    report = await _probe(FixtureDriver(), "basic", token="s3cret")
+    unauthorized = await _probe(FixtureDriver(), "basic")
+
+    assert report.passed, _failed(report)
+    assert _status(report, "a framework-only route refuses a call without the control token") == "passed"
+    assert not unauthorized.passed and "401 unauthorized" in _failed(unauthorized)[0]
+
+
 @pytest.mark.asyncio
 async def test_a_driver_whose_default_space_is_norm_passes_at_full():
     report = await _probe(FixtureDriver(settings=ComputerSettings(default_space="norm")))

{agentenv_framework_protocol-0.1.420 → agentenv_framework_protocol-0.1.421}/tests/test_computer_serve.py

@@ -3,6 +3,7 @@ that isn't such a class exits saying why, and an app's server that can't start s
 from __future__ import annotations
 
 import asyncio
+import os
 import sys
 
 import pytest
@@ -11,6 +12,7 @@ pytest.importorskip("mcp.server.fastmcp")
 pytest.importorskip("PIL")
 pytest.importorskip("uvicorn")
 
+from agentenv_protocol import CONTROL_TOKEN_ENV  # noqa: E402
 from agentenv_protocol.computer import ComputerDriverEnvironment, run_install_step, serve_app  # noqa: E402
 from agentenv_protocol.computer.app import BUILD_SETTINGS, FAILURE, SOCKET  # noqa: E402
 from agentenv_protocol.computer.app_runtime import AppRuntime  # noqa: E402
@@ -164,10 +166,11 @@ def app_folder(tmp_path, monkeypatch, isolated):
     return tmp_path, ran
 
 
-def test_an_apps_server_serves_on_the_socket_in_its_folder_and_starts_the_app_once_it_serves(app_folder,
-                                                                                             monkeypatch):
+def test_an_apps_server_serves_on_the_socket_in_its_folder_with_no_control_token_and_starts_the_app_once_it_serves(
+        app_folder, monkeypatch):
     folder, ran = app_folder
     started = []
+    monkeypatch.setenv(CONTROL_TOKEN_ENV, "s3cret")
 
     async def start(runtime):
         started.append(runtime)
@@ -177,6 +180,7 @@ def test_an_apps_server_serves_on_the_socket_in_its_folder_and_starts_the_app_on
     serve_app.main(["app.py:Notes"])
 
     (server,) = ran
+    assert CONTROL_TOKEN_ENV not in os.environ
     assert server.config.uds == str(SOCKET) and not server.should_exit
     assert not (folder / SOCKET).exists() and not (folder / FAILURE).exists()
     assert len(started) == 1 and isinstance(started[0], AppRuntime)

agentenv_framework_protocol-0.1.421/tests/test_control_token.py

@@ -0,0 +1,148 @@
+"""The control token: with CONTROL_TOKEN_ENV set when an env mounts, everything it serves but its MCP endpoint and its
+card refuses a call without that token, or with another, before the route runs, and answers one with it; the MCP
+endpoint and the card stay open, and without the variable every route is open. The client sends a call's own headers,
+or else the headers a grant gives the address it calls."""
+from __future__ import annotations
+
+import contextlib
+
+import anyio
+import httpx
+import pytest
+
+pytest.importorskip("mcp.server.fastmcp")
+
+from mcp import ClientSession  # noqa: E402
+from mcp.client import streamable_http as _streamable_http  # noqa: E402
+from mcp.server.fastmcp import FastMCP  # noqa: E402
+
+from agentenv_protocol import (  # noqa: E402
+    CONTROL_TOKEN_ENV,
+    RPC_PATH,
+    WELL_KNOWN_PATH,
+    AgentEnvEnvironment,
+    add_data,
+    client,
+    environment_card,
+    extension,
+    tool,
+)
+
+pytestmark = pytest.mark.skipif(not hasattr(_streamable_http, "streamable_http_client"),
+                                reason="mcp without streamable_http_client")
+
+_BASE = "http://127.0.0.1:8000"
+RAN: list[str] = []
+
+
+@environment_card(name="desk")
+class _Desk(AgentEnvEnvironment):
+    tool_access = True
+
+    @tool()
+    def read(self) -> str:
+        return "read"
+
+    @add_data
+    async def load(self, parts: list) -> None:
+        RAN.append("data/add")
+
+    @extension("urn:agentenv:test-exec/v1", op="run")
+    async def run(self, argv: list) -> dict:
+        RAN.append("run")
+        return {"ran": argv}
+
+
+@contextlib.asynccontextmanager
+async def _served():
+    """An ``_Desk`` mounted on mcp's FastMCP as the environment's variables stand, and its REST and MCP clients."""
+    app = FastMCP("desk", json_response=True)
+    _Desk().mount(app)
+    asgi = app.streamable_http_app()
+    async with app.session_manager.run():
+        async with httpx.AsyncClient(transport=httpx.ASGITransport(app=asgi), base_url=_BASE) as rest:
+            async with _streamable_http.streamable_http_client(f"{_BASE}/mcp", http_client=rest) as (read, write, _):
+                async with ClientSession(read, write) as mcp:
+                    await mcp.initialize()
+                    yield rest, mcp
+
+
+async def _calls(rest: httpx.AsyncClient, headers: dict) -> list[int]:
+    """The status of a call to each framework-only route with ``headers``: the data plane, an extension, tool access."""
+    load = {"jsonrpc": "2.0", "id": 1, "method": "data/add", "params": {"parts": [{"kind": "data", "data": {}}]}}
+    return [(await rest.post(RPC_PATH, json=load, headers=headers)).status_code,
+            (await rest.post("/agentenv/ext/test-exec/run", json={"argv": ["ls"]}, headers=headers)).status_code,
+            (await rest.post("/tools/disable", json={"role": "agent", "tools": ["read"]}, headers=headers)).status_code]
+
+
+@pytest.mark.asyncio
+async def test_with_a_token_every_framework_only_route_refuses_a_call_without_it_before_it_runs(monkeypatch):
+    monkeypatch.setenv(CONTROL_TOKEN_ENV, "s3cret")
+    RAN.clear()
+
+    with anyio.fail_after(30):
+        async with _served() as (rest, mcp):
+            without = await _calls(rest, {})
+            wrong = await _calls(rest, client.control_headers("guess"))
+            refusal = (await rest.post("/agentenv/ext/test-exec/run", json={"argv": ["ls"]})).json()
+            ran_before = list(RAN)
+            right = await _calls(rest, client.control_headers("s3cret"))
+            card = await rest.get(WELL_KNOWN_PATH)
+            tools = [t.name for t in (await mcp.list_tools()).tools]
+
+    assert without == wrong == [401, 401, 401] and ran_before == []
+    assert refusal["error"]["code"] == "unauthorized" and refusal["error"]["applied"] == "no"
+    assert right == [200, 200, 200] and RAN == ["data/add", "run"]
+    assert card.status_code == 200 and tools == ["read"]
+
+
+@pytest.mark.asyncio
+async def test_without_a_token_every_route_is_open(monkeypatch):
+    monkeypatch.delenv(CONTROL_TOKEN_ENV, raising=False)
+
+    with anyio.fail_after(30):
+        async with _served() as (rest, _):
+            assert await _calls(rest, {}) == [200, 200, 200]
+
+
+def test_a_call_sends_its_own_headers_or_else_the_ones_its_grant_gives_an_address_under_the_envs():
+    env = "http://desk:18765"
+
+    with client.authorized({env: client.control_headers("s3cret"), "http://other:1": {},
+                            None: client.control_headers("orphan")}):
+        granted = [client.request_headers(url) for url in (env, f"{env}/svc/mail/agentenv", f"{env}0/x",
+                                                            "http://other:1/x")]
+        own = client.request_headers(f"{env}/agentenv", {"X-Mine": "1"})
+        with client.authorized({env: client.control_headers("rotated")}):
+            inner = client.request_headers(f"{env}/agentenv")
+        outer = client.request_headers(f"{env}/agentenv")
+    after = client.request_headers(f"{env}/agentenv")
+
+    bearer = {"Authorization": "Bearer s3cret"}
+    assert granted == [bearer, bearer, {}, {}] and own == {"X-Mine": "1"}
+    assert inner == {"Authorization": "Bearer rotated"} and outer == bearer and after == {}
+    assert client.control_headers(None) == {} and client.control_headers("") == {}
+
+
+@pytest.mark.asyncio
+async def test_invoke_extension_and_the_data_plane_send_the_token(monkeypatch):
+    seen = []
+
+    def handle(request: httpx.Request) -> httpx.Response:
+        seen.append((request.url.path, request.headers.get("authorization")))
+        return httpx.Response(200, json={"jsonrpc": "2.0", "id": 1, "result": {"parts": []}})
+
+    real = httpx.AsyncClient
+    monkeypatch.setattr(httpx, "AsyncClient", lambda *a, **k: real(transport=httpx.MockTransport(handle)))
+    card = {"capabilities": {"extensions": [{"uri": "urn:agentenv:test-exec/v1", "params": {
+        "methods": {"run": {"endpoint": "/agentenv/ext/test-exec/run"}}}}]}}
+
+    await client.invoke_extension("http://desk", card, "urn:agentenv:test-exec/v1", {}, method="run",
+                                  headers=client.control_headers("own"))
+    await client.get_data("http://desk", headers=client.control_headers("own"))
+    with client.authorized({"http://desk": client.control_headers("granted")}):
+        await client.add_data("http://desk", [])
+        await client.reset_data("http://desk", headers={})
+
+    assert seen == [("/agentenv/ext/test-exec/run", "Bearer own"), ("/agentenv", "Bearer own"),
+                    ("/agentenv", "Bearer granted"), ("/agentenv", None)]