From 085539b21ac457388e4a693eb0b0f8cbd1c6a667 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sat, 14 Nov 2026 21:52:42 -0800 Subject: [PATCH 1/4] fix(env): a step reaches a multi env's computer through its gateway with the computer's own token A multi env's gateway takes its own control token off a call and passes any other on, and each computer it fronts takes only its own. A step's grant and DeployedEnv.invoke gave a call to the gateway's /svc/ route the gateway's token, so the computer refused its framework-only routes: an env_outcome_verifier reading files in the computer with computer-exec, or start_computer_recording with an environment_name. A record's control_grants now add, for each child env a gateway fronts on a sandbox of its own, the gateway's route to it with the child's own token, and the protocol's granted_headers picks the longest address a call is under. Co-Authored-By: Claude Opus 5.5 --- .../src/agentenv_protocol/client.py | 8 ++-- .../tests/test_control_token.py | 13 ++++++ src/agent_env/env/env.py | 27 +++++++++--- src/agent_env/task/task.py | 3 +- tst/unit/env/test_env.py | 31 +++++++++++++ tst/unit/task/control_grant_test.py | 44 ++++++++++++++++++- 6 files changed, 115 insertions(+), 11 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/client.py b/packages/agentenv-protocol/src/agentenv_protocol/client.py index a895c8fed..2fb754a89 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/client.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/client.py @@ -72,9 +72,11 @@ def request_headers(url: str, headers: dict[str, str] | None = None) -> dict[str 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('/')}/"))), {}) + the longest address it is or is under, as a gateway's route to a child env it fronts, granted the child's own token, + is under the gateway's address, and none anywhere else.""" + under = [(len(base), sent) for base, sent in ((base.rstrip("/"), sent) for base, sent in grants.items() if base) + if url == base or url.startswith(f"{base}/")] + return max(under, key=lambda granted: granted[0])[1] if under else {} async def _rpc(base_url: str, method: str, params: dict, timeout: int, verify: bool, diff --git a/packages/agentenv-protocol/tests/test_control_token.py b/packages/agentenv-protocol/tests/test_control_token.py index a083ea4e1..9471f4c01 100644 --- a/packages/agentenv-protocol/tests/test_control_token.py +++ b/packages/agentenv-protocol/tests/test_control_token.py @@ -124,6 +124,19 @@ def test_a_call_sends_its_own_headers_or_else_the_ones_its_grant_gives_an_addres assert client.control_headers(None) == {} and client.control_headers("") == {} +def test_a_call_under_two_granted_addresses_sends_the_longer_ones_headers_whichever_was_granted_first(): + env = "http://gateway:8080" + desk, gateway = client.control_headers("desk"), client.control_headers("gateway") + + with client.authorized({f"{env}/svc/desk/": desk, env: gateway}): + child_first = [client.request_headers(url) for url in (f"{env}/svc/desk/agentenv/x", f"{env}/svc/desk", + f"{env}/svc/desktop/agentenv", f"{env}/agentenv")] + with client.authorized({env: gateway}), client.authorized({f"{env}/svc/desk": desk}): + nested = client.request_headers(f"{env}/svc/desk/agentenv/x") + + assert child_first == [desk, desk, gateway, gateway] and nested == desk + + @pytest.mark.asyncio async def test_invoke_extension_and_the_data_plane_send_the_token(monkeypatch): seen = [] diff --git a/src/agent_env/env/env.py b/src/agent_env/env/env.py index 76a1676a2..8ea631317 100644 --- a/src/agent_env/env/env.py +++ b/src/agent_env/env/env.py @@ -118,10 +118,16 @@ def control_headers(self) -> dict[str, str]: """What a call to the env's framework-only routes sends: its control token, when it has one.""" return protocol_v1.control_headers(self.control_token) + @property + def control_grants(self) -> dict[str, dict[str, str]]: + """The addresses the env's framework-only routes are at, each with the headers that carry the token they take, + as ``protocol_v1.authorized`` takes them: the env's own address.""" + return {self.environment_url: self.control_headers} if self.environment_url else {} + def control_headers_for(self, url: str) -> dict[str, str]: - """What a call to ``url`` sends of the env's control token: ``control_headers`` when ``url`` is the env's - address or under it, as a step's grant gives them, and none anywhere else, an override's address say.""" - return protocol_v1.granted_headers(url, {self.environment_url: self.control_headers}) + """What a call to ``url`` sends of the env's control tokens: those ``control_grants`` give the address it is or + is under, as a step's grant gives them, and none anywhere else, an override's address say.""" + return protocol_v1.granted_headers(url, self.control_grants) def supports(self, uri: str, method: str) -> bool: """Whether the stored env card offers `method` on the extension at `uri`; no network.""" @@ -166,10 +172,12 @@ async def invoke(self, uri: str, method: str, params: Optional[dict] = None, *, environment_name = child.name else: card = self.environment_card if environment_name is None else self.get_child_env_card(environment_name) - if card is None or not self.environment_url or protocol_v1.find_extension_method(card, uri, method) is None: + op = protocol_v1.find_extension_method(card, uri, method) if card is not None else None + if op is None or not self.environment_url: raise EnvCapabilityUnsupported(uri, method, self.env_id, self.instance_id, environment_name) + url = f"{self.environment_url.rstrip('/')}{op['endpoint'] or ''}" return await protocol_v1.invoke_extension(self.environment_url, card, uri, params, timeout, method=method, - headers=self.control_headers) + headers=self.control_headers_for(url)) async def readiness(self, timeout: float = READY_TIMEOUT_S) -> WebsiteReadiness: """Whether the env is ready, as the protocol determines a website env's health (``env_readiness``): every site @@ -254,6 +262,15 @@ def _fields_from(cls, data: dict) -> dict: "child_envs": data.get("child_envs") or {}, } + @property + def control_grants(self) -> dict[str, dict[str, str]]: + """The gateway's address with its token, and its route to each child env it fronts on a sandbox of its own with + that child's: the gateway takes its own token off a call and passes any other on.""" + return {**super().control_grants, **{ + f"{self.environment_url}/svc/{name}": child.control_headers + for name, child in ((name, DeployedEnv.from_dict(record)) for name, record in self.child_envs.items()) + if self.environment_url and child.control_token}} + @dataclass class LoadEnvironmentUniverseArtifactResult: diff --git a/src/agent_env/task/task.py b/src/agent_env/task/task.py index df78a58f4..51bb53ff0 100644 --- a/src/agent_env/task/task.py +++ b/src/agent_env/task/task.py @@ -674,7 +674,8 @@ async def _run_one(step: TaskStep, idx: int, dispatch_epoch: int) -> None: started_mono = time.monotonic() started_utc = datetime.now(timezone.utc).isoformat() try: - with protocol_v1.authorized({d.environment_url: d.control_headers for d in context.deployed_envs}): + grants = {url: sent for deployed in context.deployed_envs for url, sent in deployed.control_grants.items()} + with protocol_v1.authorized(grants): await step.execute(context) except asyncio.CancelledError: raise diff --git a/tst/unit/env/test_env.py b/tst/unit/env/test_env.py index a30119dba..0a8884f86 100644 --- a/tst/unit/env/test_env.py +++ b/tst/unit/env/test_env.py @@ -132,6 +132,37 @@ async def test_a_record_with_a_control_token_sends_it_on_each_extension_call_onl assert _record(composed).control_headers == {} and _record(composed).control_headers_for(env) == {} +@pytest.mark.asyncio +async def test_a_call_to_a_computer_the_gateway_fronts_sends_the_computers_own_token_and_one_to_the_gateway_its(sent): + """The gateway takes its own token off a call and passes any other on, so a multi env's computer, which takes only + its own, is reached through the gateway's route to it with the token its own record keeps.""" + gw = Gateway(host="127.0.0.1", port=0, server_name="env1234", internal_mcp_servers=[], + rest_proxy_urls={"mcp-slack": "http://slack:18765", "desk": "http://desk:18765"}) + desk_card = {"name": "desk", "url": "/agentenv", "capabilities": {"extensions": [ + _ext("urn:agentenv:computer-exec/v1", "/agentenv/ext/computer-exec", "run")]}} + + async def fetch(client, key, base_url): + return gw._rewrite_child_card(key, desk_card if key == "desk" else _SLACK) + + gw._fetch_child_card = fetch + deployed = _record(json.loads((await gw._serve_env_card()).body)) + deployed.control_token = "g4teway" + desk = DeployedSandboxEnv(env_id="desk-env", env_version=1, env_provider_type="computer", sandbox_id="sb-2", + environment_card_url=f"http://desk.example{WELL_KNOWN_PATH}", control_token="d3sk") + deployed.child_envs = {"desk": dataclasses.asdict(desk)} + env = deployed.environment_url + + await deployed.invoke("urn:agentenv:computer-exec/v1", "run", {"argv": ["true"]}, environment_name="desk") + await deployed.invoke("urn:agentenv:set-errors/v1", "set_errors", {}, environment_name="slack") + + assert [(request.url.path, request.headers.get("authorization")) for request in sent] == [ + ("/svc/desk/agentenv/ext/computer-exec", "Bearer d3sk"), ("/svc/mcp-slack/agentenv/ext/set_errors", "Bearer g4teway")] + assert [deployed.control_headers_for(url) for url in (f"{env}/svc/desk/agentenv", f"{env}/svc/mcp-slack/agentenv")] == [ + {"Authorization": "Bearer d3sk"}, {"Authorization": "Bearer g4teway"}] + deployed.child_envs = {"desk": dataclasses.asdict(dataclasses.replace(desk, control_token=None))} + assert deployed.control_grants == {env: {"Authorization": "Bearer g4teway"}} + + def test_child_env_cards_come_from_the_card_by_name(composed): deployed = _record(composed) assert deployed.get_child_env_card("slack")["url"] == "/svc/mcp-slack/agentenv" diff --git a/tst/unit/task/control_grant_test.py b/tst/unit/task/control_grant_test.py index 8e76ffbcc..5752dfdaa 100644 --- a/tst/unit/task/control_grant_test.py +++ b/tst/unit/task/control_grant_test.py @@ -1,13 +1,16 @@ """Every step runs under a grant of each deployed env's control token: a protocol-client call the step makes to an env's address carries that env's token unless the call names its own headers, an env without one is sent none, an env an -earlier step deployed is granted to the steps after it, and the grant ends with the step.""" +earlier step deployed is granted to the steps after it, the grant ends with the step, and a call through a multi env's +gateway to a computer it fronts carries the computer's own token.""" + +import dataclasses import pytest from agentenv_protocol import WELL_KNOWN_PATH from agentenv_protocol import client as protocol_v1 from agent_env.config.runtime import Config -from agent_env.env.env import DeployedEnv +from agent_env.env.env import DeployedEnv, DeployedGatewayEnv, DeployedSandboxEnv from agent_env.task import Task from agent_env.task_step.context import TaskStepContext from agent_env.task_step.task_step import TaskStep @@ -72,3 +75,40 @@ async def test_a_step_calls_each_deployed_env_with_its_own_token_and_the_grant_e assert _Calls.seen == [[{}, {}, {}, {"X-Own": "1"}], [{"Authorization": "Bearer s3cret"}, {}, {}, {"X-Own": "1"}]] assert protocol_v1.request_headers(f"{DESK}/agentenv") == {} + + +class _CallsTheDesktop(TaskStep): + """Records what its calls through the office's gateway send: to the desktop computer it fronts, and to the gateway.""" + + type = "control_grant_test_desktop_calls" + entity_refs = () + seen: list = [] + + @classmethod + def from_dict(cls, data): + return cls(**cls._base_from_dict(data)) + + async def execute(self, context): + _CallsTheDesktop.seen.append([protocol_v1.request_headers(f"{OFFICE}{path}") + for path in ("/svc/desktop/agentenv/ext/computer-exec", "/agentenv/ext/clock")]) + return context + + +OFFICE = "http://office:8080" + + +@pytest.mark.asyncio +async def test_a_step_calls_a_computer_a_multi_envs_gateway_fronts_with_the_computers_own_token(local_stores, monkeypatch): + steps = {**Config().task_step_registry(), _CallsTheDesktop.type: _CallsTheDesktop} + monkeypatch.setattr(Config, "task_step_registry", lambda self: steps) + monkeypatch.setattr(_CallsTheDesktop, "seen", []) + desktop = DeployedSandboxEnv(env_id="desktop", env_version=1, env_provider_type="computer", sandbox_id="sb-2", + environment_card_url=f"http://desktop:8000{WELL_KNOWN_PATH}", control_token="d3sk") + office = DeployedGatewayEnv(env_id="office", env_version=1, gateway_url=OFFICE, sandbox_id="sb-1", + environment_card_url=f"{OFFICE}{WELL_KNOWN_PATH}", control_token="g4teway", + child_envs={"desktop": dataclasses.asdict(desktop)}) + + await Task(id="t", version=None, steps=[_CallsTheDesktop(id="calls", version=None)]).run( + context=TaskStepContext(deployed_envs=[office])) + + assert _CallsTheDesktop.seen == [[{"Authorization": "Bearer d3sk"}, {"Authorization": "Bearer g4teway"}]] From 79e6f85dd5716ed154cf77baa6af8ef213217b7d Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sat, 14 Nov 2026 21:55:08 -0800 Subject: [PATCH 2/4] test(env): the multi env computers test runs a command in the computer through the gateway's route to it Co-Authored-By: Claude Opus 5.5 --- tst/integration/computer/multi_env_computers_test.py | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/tst/integration/computer/multi_env_computers_test.py b/tst/integration/computer/multi_env_computers_test.py index 9c4a5451c..ae8cccf0b 100644 --- a/tst/integration/computer/multi_env_computers_test.py +++ b/tst/integration/computer/multi_env_computers_test.py @@ -2,7 +2,8 @@ The deploy_env step deploys each computer on a sandbox of its own and the gateway in front of them all. Through the gateway's one /mcp an agent sees the server's tools and each computer's under its name, takes screenshots by those names, -and a role rule narrows them as it would a server's; /svc// reaches the computer. A later process reattaches the +and a role rule narrows them as it would a server's; /svc// reaches the computer, its framework-only routes +with its own token. A later process reattaches the computers from the multi env's record, and the run's teardown leaves nothing up. Two computers keep serving through a computer's restart and the gateway's, a failed redeploy leaves the earlier deployment serving, and a computer that fails mid-deploy, or an entry the multi env refuses, leaves nothing up. Needs Docker and the local registry on localhost:5000.""" @@ -18,6 +19,7 @@ import httpx import pytest from agentenv_protocol import client as protocol_v1 +from agentenv_protocol.computer import COMPUTER_EXEC from agentenv_protocol.tool_access import (DISABLE, DISABLE_TOOL_EXTENSION_URI, ENABLE, ENABLE_TOOL_EXTENSION_URI, WILDCARD) from agentenv_protocol.tool_context import DEFAULT_ROLE @@ -188,6 +190,10 @@ async def test_a_computer_in_a_multi_env_is_served_through_its_gateway_under_its world = _universe(uid, {"Documents/note.txt": b"from the universe"}) await LoadArtifactTaskStep(id="seed", version=None, env_id=office.id, artifact_id=world.id).execute(context) note = (await inside.run(own, ["cat", "Documents/note.txt"], timeout_s=30))["stdout"] + # A framework-only route of the computer's, through the gateway, takes the computer's own token. + through_gateway = (await deployed.invoke(COMPUTER_EXEC, "run", { + "argv": ["cat", "Documents/note.txt"], "request_id": uuid.uuid4().hex, "timeout_s": 30}, + environment_name="desktop"))["stdout"] listed_items = await _items(deployed) await SnapshotEnvTaskStep(id="snap", version=None, env_id=office.id, snapshot_id=f"office-snap-{uid}").execute(context) @@ -223,7 +229,7 @@ async def test_a_computer_in_a_multi_env_is_served_through_its_gateway_under_its assert [env._deployed.sandbox_id for env in reattached.computer_envs] == [computer["sandbox_id"]] assert _containers(computer["sandbox_id"]) == [] assert json.dumps(deployed.child_envs) # the record stores as JSON - assert note == "from the universe" and "snap-x" in listed_items + assert note == through_gateway == "from the universe" and "snap-x" in listed_items assert {"items", "desktop"} <= set(snapshot) and snapshot["desktop"]["Documents/note.txt"] == b"from the universe" # The gateway states each child's environment_name, which lookups, servers and snapshots go by: the shop # website's card is named webitems. From 07c772801fa305daa7e031b0fbf0586a428d6891 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sun, 15 Nov 2026 09:21:49 -0800 Subject: [PATCH 3/4] fix(env): a multi env and its computers share one control token, which its gateway passes on to them Replaces the per-computer grants: a multi env's gateway took its own token off every request and passed any other on, while each computer it fronts took a token of its own, so a step's call to a computer through the gateway, with the multi env's token, was refused (401). Now the gateway provider hands its token to the computers it starts (`children(reach, control_token)`), each boots with it, and the gateway keeps it on their /svc routes (`CONTROL_TOKEN_CHILDREN`) and on its clock watch, where they send it as their read token; every other request still goes on without it. The protocol's grants and DeployedEnv are back to main's. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 2 +- .../src/agentenv_protocol/client.py | 8 ++-- .../tests/test_control_token.py | 13 ------ src/agent_env/env/env.py | 27 +++--------- src/agent_env/env/envs/_multi_computers.py | 9 ++-- src/agent_env/env/envs/computer/env.py | 12 ++--- src/agent_env/env/gateway/constants.py | 6 ++- src/agent_env/env/gateway/entrypoint.py | 4 +- src/agent_env/env/gateway/gateway.py | 24 +++++++--- .../env_providers/env_computer_provider.py | 13 +++--- .../env_providers/env_gateway_provider.py | 27 +++++++++--- src/agent_env/task/task.py | 3 +- .../computer/multi_env_computers_test.py | 5 ++- tst/unit/env/envs/test_multi_env_computers.py | 14 +++--- tst/unit/env/gateway/clock_watch_test.py | 18 +++++++- tst/unit/env/gateway/control_token_test.py | 12 +++++ tst/unit/env/test_env.py | 31 ------------- .../env_gateway_provider_test.py | 37 ++++++++++++---- tst/unit/task/control_grant_test.py | 44 +------------------ 19 files changed, 147 insertions(+), 162 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d8f2bc98d..f079e10ff 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -125,7 +125,7 @@ and deserialized through a registry. |---|---| | `env/` | `Env` base class: a subclass declares `type`, implements `from_dict` and `async deploy(...) -> DeployedEnv`, and may override `reset`, `close` and `load_file_artifact_universe`; teardown closes each env a run deployed before terminating its sandboxes by id. Built-ins in `env/envs/`: `MCPServerEnv` (`mcp_server`), `MultiEnv` (`multi`, MCP servers plus websites and computers; its website browser is the one its `browser_envs` names, none for `[]`, else the run's when it has websites: an MCP server env such as `playwright-mcp` runs among the gateway's MCP servers, and a browser computer such as `chromium` on a sandbox of its own as one more computer child, sized by its `child_envs` entry, its tools under its name and `_`, routing the multi env's synthetic sites unless that entry's `site_routing` says, its network its own env's, as any computer child's; a website env deployed alone refuses a browser computer as the run's browser), `ServiceDBEnv` (`service_db`, PostgreSQL), `WebsiteEnv` (`website`, one site: a server image, `backend_image` in its env.toml, serving the pages and API, ready when its card's `website/v1` `ready` answers a `WebsiteReadiness` that says so, as `agentenv_protocol.website` (`website_readiness`, `env_readiness`) defines a website env's health for the deploy and `DeployedEnv.readiness()` alike, or, for a card without `ready`, when its `health` path answers 200, which is deprecated; its env.toml's `ready_timeout_s`, how long it may take from its server's container starting to ready, is that container's health check `start_period` and what the deploy waits, or its card's `ready` timeout if longer, and its `shm_mb` is the container's `shm_size`, each left to the gateway and Docker without them; the gateway container's `env/gateway/constants.py` mirrors the URI and op, a test keeping them equal; a separate frontend image is deprecated, warned of at put and optional in a bundle, and a stored `backend_docker_image_artifact` reads as the server image; a live one, `live = true`, is a real site whose server serves none of its pages, its `live`, `domains` and `allow_hosts` read at put from its server's `@website(...)` (`utils/card_naming.py` `WebsiteSource`) unless given, its `settings`' secrets only as references the gateway resolves as it writes the site's container (`WEBSITE_SETTINGS_ENV`); the gateway gives it no site route, a computer's site table leaves it out, a computer whose network is an allowlist is let reach its names (`MultiEnv.live_hosts`), a browser alone's forward port takes them straight to the real site (`site_proxy.py` `direct`), as the browser base's stand-in proxy takes any host, refusing nothing, each proxy logging each such connection as a JSON line, and a run that deploys one is marked live, `reproducible: false`), `GatewayEnv` (`gateway_server`), `ComputerDriverEnv` (`computer_driver`, `env/envs/computer/driver_env.py`: a computer driver's files and what its class declares for each platform it supports, read at put in a process of its own, `agentenv_protocol.computer._declare`, where the driver's own dependencies needn't be installed, with the `port` it serves on and its install by OS, `[install.]`, or for one distribution `[install."/"]`, which replaces its OS type's there, as its `known_failures` do (`env/envs/computer/utils/install.py`): files, apt `packages` with extra `sources`, a `python` requirements file for a venv, `downloads` by URL and sha256, `run` scripts, the services the base's init runs, and `ports`; it deploys only as a computer env's driver), `ComputerEnv` (`computer`, in `env/envs/computer/`: a base computer and a driver, matched at put by gate 1 before anything is stored, then composed by `composer.py` into an image for each form and arch on a builder of the put's sandbox provider, by default the env's (`utils/builder.py`; `--sandbox` on `env build`, `bundle register` and `run`): this machine's Docker for `local`, else a VM of the provider, which fetches the put's stored files by signed URL, takes the rest inline and pushes to the image store itself, so it builds only with stores a remote VM reaches; each arch goes to the first link that runs it natively, else one that emulates it (a VM registers QEMU; `--no-emulate` leaves it `skipped` instead, for a later put), and its pair records the provider that built it (`builder`); a run or register that reuses a computer env composes what it has left (`pending`), a run only the forms its sandbox's deploys boot (`booted_forms`: on each link, the first form it boots natively, by the deploy's own rule, `boot.first_native`; a compose of a disk adds its container), and a deploy composes first what it boots that no compose started, and a container it runs natively that was built but not probed, as one whose probe a setting that didn't resolve stopped, booting it only once ready (`ComputerEnv.compose_unstarted`); tagged `agentenv-computers:` in the image store by a key of the image's Dockerfile, build context and lock so any env with the same inputs reuses it; every layer's packages, requirements and downloads are resolved at put in a container of the base for each arch (`utils/packages.py`, `utils/resolve_in_base.py`), stored in the object store by sha256 under `agentenv-packages/`, and listed in a lock stored by a digest of its inputs, which any env with the same inputs reuses, and builds install only the lock's files, every install step `RUN --network=none`; each pair's status goes into its metadata, `composed`, the arches built are written as its computer, a `computer` artifact over one index, and `agent-env env build` resumes what a put left; gate 3 (`utils/probing.py`) then boots each native build on the put's sandbox provider and probes it at `full`, making it `ready` or `failed`, and a build no provider runs natively stays `unverified`. Its deploy, through the `computer` env provider (`providers/env_providers/env_computer_provider.py`), boots its first `ready` build on a sandbox provider that runs its arch natively (`native_platforms()`), with no gateway in front and the driver's card as the env card, its `/dev/shm` the most its apps' Linux installs ask for (`shm_mb`, in MiB, which its composed computer and the deploy record keep; `--shm-size` on a container, `AGENTENV_SHM_MB` read by a Linux disk's init, passed only to a provider whose `SHARED_MEMORY` says it gives that much, else the sandbox's default, which the deploy logs), then checks its `display`; `deploy_env` `env_params` take a `form`, `computer_settings` (deploy-phase values of the base's settings; a secret one, here or on the env, only as a bare `secret:`/`env:` reference) and `driver_settings` (the driver's `ComputerSettings`, such as its default coordinate space); a `network` that allows nothing runs it on local Docker's internal network behind a relay (`providers/sandbox_providers/local_docker/relay/`); `reset` and `close` have the driver end its recordings first (`computer-recording/v1` `end_all`, each uploading what's left and its manifest under the grant it started with), and `reset` then boots a fresh container in its place (`reset_container`), keeping the computer's address but not an agent's MCP session to the old driver; its `load_file_artifact_universe` writes files under the session user's home through the driver's `data/add`, `Downloads` by default, each file's bytes through a read grant when the store's grants reach it and its network allows everything, else inline (`env/envs/computer/utils/inside.py`)), `ComputerAppEnv` (`computer_app`, `env/envs/computer/app_env.py`: an app on a computer, a `ComputerAppEnvironment` class its env.toml's `module` names, read at put by the same `_declare`, which declares each OS with its own decorator (`@linux(...)`, or `@install(os_type, spec)` for any OS type; `@linux(distribution=...)` or `@install("/", spec)` for one distribution, which replaces its OS type's there) holding its install, its launch and, optionally, a skill and settings and build settings that add to the class's there, and install steps and ready checks for every OS or those their `os=` names; everything that reads its settings, launch or steps asks for the computer's OS type; deployed alone it is a one-app computer env, a `ComputerEnv` of the computer and driver its env.toml names, the composer installing it under `/opt/agentenv/apps//` with its services as supervisord programs beside its own server (`agentenv_protocol.computer.serve_app`, in a venv with the protocol's `app` extra, on `.agentenv/server.sock` in its folder), which adds its launcher, launches a `boot` app once per boot and says through `computer-app/v1` whether it's ready, as the driver's `computer-ready` asks, its card named after it, and `env_params` `app_settings` handing it values of its `Settings` in `AGENTENV_APP_SETTINGS`, a secret one only as a bare reference, over its env.toml's `[settings]` and a computer env's `settings` beside it in `apps`, each by top-level field (`params.app_settings`; checked at put, a required one left to the deploy; the deploy record keeps the merged values as `app_settings`, secrets withheld); its env.toml's `build_settings`, values of its `BuildSettings` checked at put, are written to `.agentenv/build_settings.json` in its folder, so they're part of the image's key, its install steps read them, and a deploy can't change them). An env type whose services take environment data defines `load_environment_artifact` and `load_environment_universe_artifact`; `load_artifact` refuses an environment artifact aimed at a type that doesn't, at save and before it loads. An env built on the protocol SDK can serve agents a skill (`@agent_skill`, `skill/v1`), which `add_skills` `env_ids` installs under its environment name (behind a gateway, each server's under that server's name); a skill with files beside its SKILL.md goes as a bundle stored once per content under `agentenv-env-skills/` in the object store. `env/gateway/gateway.py` is the env-side gateway server, container-only code. Its site route, `/website//`, never forwards a site's data plane or card (`/agentenv/…`, `/.well-known/agent-env.json`), which agentenv reaches through `/svc//`; a site with no frontend image is served by its server image there. Its CDP route, `/browser//cdp//` (`env/gateway/browser_proxy.py`), reaches the website browser behind the `/svc` child ``, found from that child's card (it, or an app among its children, offering `browser/v1` `cdp` with `/cdp/` in its `computer-app/v1` `agent_routes`): it relays the browser's discovery and WebSocket both ways, each leg pinged every 20 s, and every CDP address the browser hands out, in `json/version`, `json/list` and its `cdp` answer through `/svc//`, comes back at the gateway, everything before `/cdp//` becoming the address the caller reached the gateway at and `/browser/`, keeping the https or wss of an address the browser minted under an origin its caller named, as `browser_connect_cdp` names the agent's, since a tunnel that ends TLS, as Modal's, may send no `X-Forwarded-Proto`; each connection is a `browser_connection` trajectory event, without its token. Its clock (`env/gateway/clock.py`) has one opaque version, a per-boot id and a count, that every `set_time`, `advance` and `clear` changes; `set_rate` (`/clock/set-rate`) changes an armed clock's rate from its time at the write, keeping its `t0` and generation as `advance` does, so time triggers keep their marks. Every clock change goes through `Gateway._change_clock`, which wakes the triggers when the change kept the clock's generation, answers the held watches and waits for the followers. Its followers, the computers on it (`CLOCK_FOLLOWER_TOKENS`, each child whose card serves `clock/v1` `sync_time`, by its read token, its control token for now), long-poll `/clock/watch` naming the version they show, each watch held up to the card's `hold_s` (`env/gateway/clock_followers.py`), and a write given `wait_followers_s` waits for each, answering 504 naming those behind, but not for one that hasn't watched for longer than a hold and a reconnect (`ClockFollowers.QUIET_S`), which it names at once with when each last watched; a restarted gateway is unarmed. While its clock is armed it serves agents `get_time` (`env/gateway/get_time.py`), which answers in UTC and, given an IANA `time_zone`, also in that zone; executors' working `hours` (`env/gateway/triggers.py`) take a fixed `utc_offset` or an IANA `time_zone`. | | `artifact/` | Immutable versioned artifacts; every `put()` creates a new version. The document goes to the document store, binary payloads to the object store. Every artifact but an environment universe, whose `metadata` key holds its legacy metadata file ids, carries a `metadata` dict outside its versioned fields, changed by compare-and-swap (`merge_metadata`). Built-ins: `CliArtifact` (`cli`), `ComputerArtifact` (`computer`, a base computer: its architectures, OS, session user, settings and container form, whose image `put` reads from its registry into `metadata.validated_images`), `FileArtifact` (`file`), `FileArtifactUniverse` (`file_artifact_universe`), `DockerImageArtifact` (`docker_image`), `EnvironmentArtifact` (`environment`: its environment's files by path, stored as the one wrapped `file_artifact_ref` every environment artifact had when it has one file at its filename, else as `file_artifact_refs`; `get_file_artifacts()` reads either, and a load hands each file to the env's `data/add` with its path, which a pre-v1 load, taking one file, refuses), `EnvironmentUniverseArtifact` (`environment_universe`), `SkillArtifact` (`skill`); `[artifacts] type_aliases` maps another stored spelling of a type onto one of them. A `DockerImageArtifact` holds a tar.gz of its image, or, written by `put_ref` (`--image-ref` on `env mcp-server put` and `a2a-agent put`), only a registry reference with its tag pinned to a digest, which sandboxes pull, or a published image's tag with its `image_digest` and its build context, which sandboxes pull by the digest and build from the context when they can't (the infra images, and a bundle agent built from a shipped agent's sources, `Plan.published`), or, written by `put_context`, only its build context, which a VM sandbox builds before running it (`VmSandbox.load_docker_images`) and Modal builds before creating its container (`ModalSandboxProvider.prepare_image`, outside a fallback chain's deadline); anything else that runs images by name (a container on the local provider, a lone server on any provider but Modal) refuses such an image. A build context (`utils/docker/context.py`) is what `docker build` would send, `.dockerignore` applied, written so equal files give equal bytes and an equal `source_digest`. | -| `task/`, `task_step/` | A `Task` holds its `TaskStep`s inline; `Task.run()` executes them as a DAG. `depends_on` (None means all prior steps) gates a step, independent steps run concurrently, `fail_task_on_error` makes a failure fatal or tolerated, `retry_config` rolls a failed span back through the step journal and re-dispatches it. Built-in steps live in `task_step/task_steps/` (`deploy_env`, `deploy_agent`, `prompt_agent`, the verifiers under `verifiers/`, among them `start_computer_recording` and `end_computer_recording`, `start_browser_recording` and `end_browser_recording` (`browser-recording/v1`: one recording per context, a lease's or the default one's, with a video of the tab its agent is on, its context's log, the browser's network log as HAR and opt-in frames keyed to the action log, the contexts its agents make recorded with it, one universe per recording, anything missing failing the run), and more). On an env whose card serves computer-exec/v1 (a computer), `run_code` with `env_id` and `run_container_unit_tests_verifier` with `env_id` run inside it as its session user through the driver: files staged with `data/add` and read with `data/get`, commands run with `run`; `env_outcome_verifier` hands a `verify` that takes an `env_url` keyword the env's address. A computer's framework-only routes (everything but MCP and the card) take the per-deploy control token its provider boots it with (`DeployedEnv.control_token`, `AGENTENV_CONTROL_TOKEN`); framework calls send `deployed.control_headers`, `Task.run` runs every step under `protocol_v1.authorized` with each deployed env's (a `verify` included), and a `run_code` script inside the computer gets `input["env"]["headers"]`. `teardown_run` and the `teardown_sandboxes` step share one core (`task/teardown.py` `tear_down`): the recordings the run left open end with fresh grants, each env still up closes (`Env.close`; a computer env ends any recording still open), what stayed open is registered from its namespace, then every sandbox is terminated by id. `task/episode/` runs a task with some of its agents played from outside, as a training loop does (`EpisodeSpec`). | +| `task/`, `task_step/` | A `Task` holds its `TaskStep`s inline; `Task.run()` executes them as a DAG. `depends_on` (None means all prior steps) gates a step, independent steps run concurrently, `fail_task_on_error` makes a failure fatal or tolerated, `retry_config` rolls a failed span back through the step journal and re-dispatches it. Built-in steps live in `task_step/task_steps/` (`deploy_env`, `deploy_agent`, `prompt_agent`, the verifiers under `verifiers/`, among them `start_computer_recording` and `end_computer_recording`, `start_browser_recording` and `end_browser_recording` (`browser-recording/v1`: one recording per context, a lease's or the default one's, with a video of the tab its agent is on, its context's log, the browser's network log as HAR and opt-in frames keyed to the action log, the contexts its agents make recorded with it, one universe per recording, anything missing failing the run), and more). On an env whose card serves computer-exec/v1 (a computer), `run_code` with `env_id` and `run_container_unit_tests_verifier` with `env_id` run inside it as its session user through the driver: files staged with `data/add` and read with `data/get`, commands run with `run`; `env_outcome_verifier` hands a `verify` that takes an `env_url` keyword the env's address. A computer's framework-only routes (everything but MCP and the card) take the per-deploy control token its provider boots it with (`DeployedEnv.control_token`, `AGENTENV_CONTROL_TOKEN`), a multi env's computers the multi env's own, which its gateway passes on only on their `/svc` routes and its clock watch (`CONTROL_TOKEN_CHILDREN`); framework calls send `deployed.control_headers`, `Task.run` runs every step under `protocol_v1.authorized` with each deployed env's (a `verify` included), and a `run_code` script inside the computer gets `input["env"]["headers"]`. `teardown_run` and the `teardown_sandboxes` step share one core (`task/teardown.py` `tear_down`): the recordings the run left open end with fresh grants, each env still up closes (`Env.close`; a computer env ends any recording still open), what stayed open is registered from its namespace, then every sandbox is terminated by id. `task/episode/` runs a task with some of its agents played from outside, as a training loop does (`EpisodeSpec`). | | `store/` | Four store ABCs with local and cloud implementations: `DocumentStore` (SQLite, MongoDB, DynamoDB, Firestore with MongoDB compatibility), `ObjectStore` (filesystem, S3, Cloud Storage), `ImageStore` (local OCI registry, ECR), `SecretStore` (env vars or file, AWS Secrets Manager, Google Cloud Secret Manager). `VersionedEntityStore` implements the shared versioned get/put logic, `QueryBuilder` is the immutable chained query API, `store/base.py` holds the error types. `store/routing.py` is the local namespaces, `@local` and `@hf` (`is_local_id`), each with a documents file of its own: while the CLI or a `build_app` server runs, a local id and what a local task's run records go to local stores beside the configured ones, and that run's writes to the configured stores are refused. A new backend must pass the conformance kits in `tst/store/`. | | `config/` | The `Config` singleton (`get_config`, `configure`, `reset_config`) in `config/runtime.py`, file discovery in `config/loader.py`, and `load_impl`, which resolves `module:Class` pointers. `agent_env.store` re-exports the config names for compatibility. | | `providers/` | `providers/sandbox_providers/` holds the sandbox providers `local`, `modal`, `modal_vm`, `e2b`, `sail_vm` (the `sail` extra), `smol_vm` (the `smol` extra), `tensorlake` (the `tensorlake` extra), `tenki` (the `tenki` extra), `vercel` (the `vercel` extra), `boxd` (the `boxd` extra), `coreweave` (the `coreweave` extra), `daytona` (the `daytona` extra), `boat` (the `boat` extra), `agent37` (no extra); `[sandbox] default` and `agent_default` accept a comma-separated fallback chain, whose deploys skip a provider that can't run them. A sandbox provider declares what it runs (`ON_THIS_MACHINE`, and for VMs on this machine the address their requests to it arrive at, `REACHES_HOST_AT`; `CONTAINER_ACCEPTS`, `PRIVATE_NETWORK`, `WEBSOCKETS`; `SUPPORTED_SANDBOX_MODES`, derived from whether it implements `create_sandbox` and `create_vm`; and `SANDBOX_ACCEPTS`, the images an agent's sandbox runs, which defaults to those a VM loads when it implements `create_vm` and to `CONTAINER_ACCEPTS` otherwise, so only a provider that implements `create_vm` yet gives an agent a container, like the local one, declares it), each sandbox carries the `platform` of the images it runs (linux/amd64 unless its provider sets another when it creates it; None, any, unchecked, for a local sandbox), and code outside `providers/sandbox_providers/` reads those, never which provider it has. `providers/env_providers/` holds the environment providers: `EnvironmentProvider` (an env's containers and state store), `EnvironmentGatewayProvider` (`gateway`, an env's default), which renders a docker-compose for the gateway and its MCP servers inside the sandbox, and `EnvironmentServerProvider` (`server`), one MCP server in its own container with no gateway in front and no state store; `providers/env_state/` holds env-state providers (`local_postgres` built in). | diff --git a/packages/agentenv-protocol/src/agentenv_protocol/client.py b/packages/agentenv-protocol/src/agentenv_protocol/client.py index 2fb754a89..a895c8fed 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/client.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/client.py @@ -72,11 +72,9 @@ def request_headers(url: str, headers: dict[str, str] | None = None) -> dict[str 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 longest address it is or is under, as a gateway's route to a child env it fronts, granted the child's own token, - is under the gateway's address, and none anywhere else.""" - under = [(len(base), sent) for base, sent in ((base.rstrip("/"), sent) for base, sent in grants.items() if base) - if url == base or url.startswith(f"{base}/")] - return max(under, key=lambda granted: granted[0])[1] if under else {} + 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, diff --git a/packages/agentenv-protocol/tests/test_control_token.py b/packages/agentenv-protocol/tests/test_control_token.py index 9471f4c01..a083ea4e1 100644 --- a/packages/agentenv-protocol/tests/test_control_token.py +++ b/packages/agentenv-protocol/tests/test_control_token.py @@ -124,19 +124,6 @@ def test_a_call_sends_its_own_headers_or_else_the_ones_its_grant_gives_an_addres assert client.control_headers(None) == {} and client.control_headers("") == {} -def test_a_call_under_two_granted_addresses_sends_the_longer_ones_headers_whichever_was_granted_first(): - env = "http://gateway:8080" - desk, gateway = client.control_headers("desk"), client.control_headers("gateway") - - with client.authorized({f"{env}/svc/desk/": desk, env: gateway}): - child_first = [client.request_headers(url) for url in (f"{env}/svc/desk/agentenv/x", f"{env}/svc/desk", - f"{env}/svc/desktop/agentenv", f"{env}/agentenv")] - with client.authorized({env: gateway}), client.authorized({f"{env}/svc/desk": desk}): - nested = client.request_headers(f"{env}/svc/desk/agentenv/x") - - assert child_first == [desk, desk, gateway, gateway] and nested == desk - - @pytest.mark.asyncio async def test_invoke_extension_and_the_data_plane_send_the_token(monkeypatch): seen = [] diff --git a/src/agent_env/env/env.py b/src/agent_env/env/env.py index 8ea631317..76a1676a2 100644 --- a/src/agent_env/env/env.py +++ b/src/agent_env/env/env.py @@ -118,16 +118,10 @@ def control_headers(self) -> dict[str, str]: """What a call to the env's framework-only routes sends: its control token, when it has one.""" return protocol_v1.control_headers(self.control_token) - @property - def control_grants(self) -> dict[str, dict[str, str]]: - """The addresses the env's framework-only routes are at, each with the headers that carry the token they take, - as ``protocol_v1.authorized`` takes them: the env's own address.""" - return {self.environment_url: self.control_headers} if self.environment_url else {} - def control_headers_for(self, url: str) -> dict[str, str]: - """What a call to ``url`` sends of the env's control tokens: those ``control_grants`` give the address it is or - is under, as a step's grant gives them, and none anywhere else, an override's address say.""" - return protocol_v1.granted_headers(url, self.control_grants) + """What a call to ``url`` sends of the env's control token: ``control_headers`` when ``url`` is the env's + address or under it, as a step's grant gives them, and none anywhere else, an override's address say.""" + return protocol_v1.granted_headers(url, {self.environment_url: self.control_headers}) def supports(self, uri: str, method: str) -> bool: """Whether the stored env card offers `method` on the extension at `uri`; no network.""" @@ -172,12 +166,10 @@ async def invoke(self, uri: str, method: str, params: Optional[dict] = None, *, environment_name = child.name else: card = self.environment_card if environment_name is None else self.get_child_env_card(environment_name) - op = protocol_v1.find_extension_method(card, uri, method) if card is not None else None - if op is None or not self.environment_url: + if card is None or not self.environment_url or protocol_v1.find_extension_method(card, uri, method) is None: raise EnvCapabilityUnsupported(uri, method, self.env_id, self.instance_id, environment_name) - url = f"{self.environment_url.rstrip('/')}{op['endpoint'] or ''}" return await protocol_v1.invoke_extension(self.environment_url, card, uri, params, timeout, method=method, - headers=self.control_headers_for(url)) + headers=self.control_headers) async def readiness(self, timeout: float = READY_TIMEOUT_S) -> WebsiteReadiness: """Whether the env is ready, as the protocol determines a website env's health (``env_readiness``): every site @@ -262,15 +254,6 @@ def _fields_from(cls, data: dict) -> dict: "child_envs": data.get("child_envs") or {}, } - @property - def control_grants(self) -> dict[str, dict[str, str]]: - """The gateway's address with its token, and its route to each child env it fronts on a sandbox of its own with - that child's: the gateway takes its own token off a call and passes any other on.""" - return {**super().control_grants, **{ - f"{self.environment_url}/svc/{name}": child.control_headers - for name, child in ((name, DeployedEnv.from_dict(record)) for name, record in self.child_envs.items()) - if self.environment_url and child.control_token}} - @dataclass class LoadEnvironmentUniverseArtifactResult: diff --git a/src/agent_env/env/envs/_multi_computers.py b/src/agent_env/env/envs/_multi_computers.py index b6ec90e30..4503c3889 100644 --- a/src/agent_env/env/envs/_multi_computers.py +++ b/src/agent_env/env/envs/_multi_computers.py @@ -190,9 +190,10 @@ def _recorded_browser(self, records: Mapping[str, dict]) -> Optional[ComputerEnv def deployer(self, child_envs: Optional[dict], *, sandbox_type: str | None, ttl_seconds: int, attribution: Optional[Attribution], websites: Mapping[str, str], live_hosts: Iterable[str] = () - ) -> Callable[[Optional[str]], Awaitable[list[ExternalChild]]]: + ) -> Callable[[Optional[str], Optional[str]], Awaitable[list[ExternalChild]]]: """The gateway's ``children``: every computer deployed as its child_envs entry says, its tools served under its - name and ``_``, and its network allowing ``reach``, the gateway's address when the gateway has one yet, and the + name and ``_``, its framework-only routes taking ``control_token``, the gateway's, which the gateway passes on to + them, and its network allowing ``reach``, the gateway's address when the gateway has one yet, and the ``live_hosts`` of the multi env's live websites; then each as the gateway fronts it. A computer routing the multi env's ``websites`` (their environment names by env id) boots with its boot apps held, for ``finish`` to route them once the gateway is up. A gateway deploy tried again deploys them again, after closing the earlier try's.""" @@ -204,14 +205,14 @@ def deployer(self, child_envs: Optional[dict], *, sandbox_type: str | None, ttl_ routing = entry["env_params"]["site_routing"] self._routes[name] = None if routing is True else [websites[env_id] for env_id in routing] - async def deploy(reach: Optional[str]) -> list[ExternalChild]: + async def deploy(reach: Optional[str], control_token: Optional[str]) -> list[ExternalChild]: nonlocal tries if tries: await self.close() tries += 1 results = await asyncio.gather(*(env.deploy( ttl_seconds=ttl_seconds, attribution=attribution, tool_prefix=f"{env.environment_name}_", - reach=reach or "", sites_later=env.environment_name in self._routes, + reach=reach or "", sites_later=env.environment_name in self._routes, control_token=control_token, **({"live_hosts": live} if live else {}), **deploy_options((child_envs or {}).get(env.environment_name), sandbox_type)) for env in self.every), return_exceptions=True) diff --git a/src/agent_env/env/envs/computer/env.py b/src/agent_env/env/envs/computer/env.py index 5c0a06982..f84940eed 100644 --- a/src/agent_env/env/envs/computer/env.py +++ b/src/agent_env/env/envs/computer/env.py @@ -287,17 +287,19 @@ async def deploy(self, ttl_seconds: int = 10800, disk_size_gb: float = 10, memory_mb: int | None = None, sandbox_type: str | None = None, env_state_type: str | None = None, env_state_instance_id: str | None = None, *, attribution: Optional[Attribution] = None, env_params: Optional[dict] = None, tool_prefix: str = "", reach: str = "", - sites_later: bool = False, live_hosts: tuple[str, ...] = ()) -> DeployedEnv: + sites_later: bool = False, live_hosts: tuple[str, ...] = (), + control_token: Optional[str] = None) -> DeployedEnv: """With ``tool_prefix``, its driver serves its tools under it, with ``reach``, a network that restricts its - egress allows that URL's host too, and the ``live_hosts`` of the run's live websites, and with ``sites_later`` - it routes the sites ``env_params.site_routing`` reaches when ``route_sites`` gives them: what a multi env gives - each of its computers.""" + egress allows that URL's host too, and the ``live_hosts`` of the run's live websites, with ``sites_later`` + it routes the sites ``env_params.site_routing`` reaches when ``route_sites`` gives them, and with + ``control_token`` its framework-only routes take that token, not one of its own: what a multi env gives each + of its computers.""" return await deploy_through_provider( self, environment_name=self.environment_name, ttl_seconds=ttl_seconds, sandbox_type=sandbox_type, then=self._give_tools, disk_size_gb=disk_size_gb, gateway_mode=gateway_mode, cpu=cpu, memory_mb=memory_mb, env_state_type=env_state_type, env_state_instance_id=env_state_instance_id, attribution=attribution, env_params=env_params, tool_prefix=tool_prefix, reach=reach, sites_later=sites_later, - live_hosts=tuple(live_hosts)) + live_hosts=tuple(live_hosts), control_token=control_token) async def route_sites(self, sites: list[dict]) -> None: """Route ``sites`` on this computer, deployed with ``sites_later``, launch its held apps and finish its boot; diff --git a/src/agent_env/env/gateway/constants.py b/src/agent_env/env/gateway/constants.py index 06ecbcfd3..97da9de8e 100644 --- a/src/agent_env/env/gateway/constants.py +++ b/src/agent_env/env/gateway/constants.py @@ -72,6 +72,10 @@ def data_plane_load_timeout_s(size_bytes: int | None) -> int: # The computers that follow the gateway's clock, each as `name=read token`, comma-separated; TOKEN in the name keeps # it out of logged compose files. CLOCK_FOLLOWERS_ENV = "CLOCK_FOLLOWER_TOKENS" +# The children the gateway passes its control token on to, comma-separated: a multi env's computers, which boot with it. +CONTROL_TOKEN_CHILDREN_ENV = "CONTROL_TOKEN_CHILDREN" +# The route a clock follower long-polls, with its read token. +CLOCK_WATCH_PATH = "/clock/watch" # How long /clock/watch holds a watch naming the current version before answering it unchanged; a follower's request # timeout must be longer. The card's watch method advertises it as hold_s. CLOCK_WATCH_HOLD_S = 25.0 @@ -252,7 +256,7 @@ def random_mcp_server_name() -> str: "advance": {"method": "PUT", "endpoint": "/clock/advance", "request": {"type": "object", "properties": {"virtual_time": {"type": "string"}, **_WAIT_FOLLOWERS}, "required": ["virtual_time"]}}, "clear": {"method": "POST", "endpoint": "/clock/clear", "request": {"type": "object", "properties": {**_WAIT_FOLLOWERS}}}, "state": {"method": "GET", "endpoint": "/clock/state", "request": {"type": "object", "properties": {}}}, - "watch": {"method": "GET", "endpoint": "/clock/watch", "hold_s": CLOCK_WATCH_HOLD_S, "request": {"type": "object", "properties": {"after": {"type": "string"}, "follower": {"type": "string"}}}}}}, + "watch": {"method": "GET", "endpoint": CLOCK_WATCH_PATH, "hold_s": CLOCK_WATCH_HOLD_S, "request": {"type": "object", "properties": {"after": {"type": "string"}, "follower": {"type": "string"}}}}}}, "required": False, }, { diff --git a/src/agent_env/env/gateway/entrypoint.py b/src/agent_env/env/gateway/entrypoint.py index 81d3cad3c..83e59c128 100644 --- a/src/agent_env/env/gateway/entrypoint.py +++ b/src/agent_env/env/gateway/entrypoint.py @@ -8,7 +8,7 @@ import httpx from . import AGENT_ENV_GATEWAY_MCP_PORT, GatewayMode, InternalMCPServer -from .constants import (CLOCK_FOLLOWERS_ENV, CONTROL_TOKEN_ENV, DEFAULT_MCP_SERVER_NAME, +from .constants import (CLOCK_FOLLOWERS_ENV, CONTROL_TOKEN_CHILDREN_ENV, CONTROL_TOKEN_ENV, DEFAULT_MCP_SERVER_NAME, GATEWAY_PROVIDER_HEADERS_ENV, MCP_TRANSPORT, WEBSITE_LISTED_BY_NAME_ENV, WEBSITE_NAMES_ENV, WELL_KNOWN_PATH) from .gateway import Gateway, card_url @@ -242,6 +242,8 @@ def parse_site_names(env_str: str) -> dict[str, tuple[str, ...]]: gateway_mode=gateway_mode, service_db_url=service_db_url, control_token=os.environ.get(CONTROL_TOKEN_ENV), + control_token_children=[name.strip() for name in os.environ.get(CONTROL_TOKEN_CHILDREN_ENV, "").split(",") + if name.strip()], provider_headers=os.environ.get(GATEWAY_PROVIDER_HEADERS_ENV, "").split(","), clock_followers=parse_clock_followers(os.environ.get(CLOCK_FOLLOWERS_ENV, "")), site_names=parse_site_names(os.environ.get(WEBSITE_NAMES_ENV, "")), diff --git a/src/agent_env/env/gateway/gateway.py b/src/agent_env/env/gateway/gateway.py index a7322b676..0c891e4b7 100644 --- a/src/agent_env/env/gateway/gateway.py +++ b/src/agent_env/env/gateway/gateway.py @@ -46,6 +46,7 @@ AGENT_ENV_SESSION_META_KEY, # noqa: F401 CARD_FETCH_TIMEOUT_S, CHANGES_PAGE_DEFAULT, + CLOCK_WATCH_PATH, CHANGES_PAGE_MAX, CHILD_DISCOVERY_TIMEOUT_S, CONTROL_ROUTES, @@ -159,6 +160,7 @@ def __init__( gateway_mode: GatewayMode = GatewayMode.PERFORMANCE, service_db_url: str | None = None, control_token: str | None = None, + control_token_children: Iterable[str] = (), provider_headers: Iterable[str] = (), clock_followers: Mapping[str, str] | None = None, site_names: dict[str, Iterable[str]] | None = None, @@ -169,7 +171,8 @@ def __init__( followers of its clock, each with the read token its watch carries. `site_names` are each site's names as its env stores them, the names its card declares standing in for a site's that stores none: a site reached at one takes it as its ``Host``. ``list_website_urls`` gives each site `listed_by_name` at its first name, as a browser - computer opens it, and the others at their ``website_urls``.""" + computer opens it, and the others at their ``website_urls``. `control_token_children` are the children its + /svc routes pass its control token on to, a multi env's computers, which take it.""" self.host = host self.port = port self.server_name = server_name @@ -190,6 +193,7 @@ def __init__( self.gateway_mode = gateway_mode self._service_db_url = service_db_url self._control_bearer = f"Bearer {control_token}".encode() if control_token else None + self._control_token_children = frozenset(control_token_children) self._website_routes: dict[str, list[WebsiteRoute] | None] = {} self._db_conn: psycopg2.extensions.connection | None = None if service_db_url: @@ -370,7 +374,7 @@ def disarm(body: dict) -> dict: return await self._clock_write(request, disarm, body_optional=True) - @self._mcp.custom_route("/clock/watch", methods=["GET"]) + @self._mcp.custom_route(CLOCK_WATCH_PATH, methods=["GET"]) async def clock_watch(request: Request) -> Response: received = time.time() token = request.headers.get("authorization", "").removeprefix("Bearer ").strip() @@ -534,6 +538,14 @@ def run(self) -> None: # by every tools/call of that session (and the role is the one its initialize request carried, which that task # inherited). Process: child sessions and the time-trigger driver, outer to the MCP session manager's lifespan. + def _keeps_control_token(self, path: str) -> bool: + """Whether a request to ``path`` keeps the gateway's control token: its clock watch, where a computer it fronts + sends the token as its read token, and its /svc route to one of those computers, which takes the token.""" + if path == CLOCK_WATCH_PATH: + return True + child = path.removeprefix("/svc/").split("/", 1)[0] if path.startswith("/svc/") else None + return child in self._control_token_children + def _asgi_app(self): """The served app: FastMCP's Starlette app with the request's caller bound around it, the control routes behind the deploy's token when it has one, and the process lifespan wrapped around the MCP session manager's.""" @@ -550,9 +562,11 @@ async def app(scope, receive, send): response = self._json_response({"ok": False, "error": "this route takes the env's control token"}, 401) await response(scope, receive, send) return - # The token is the gateway's own: no route reads it, and no service a route proxies to receives it. - scope = {**scope, "headers": [(name, value) for name, value in headers if not ( - name == b"authorization" and hmac.compare_digest(value, self._control_bearer))]} + # Only the clock watch reads the token, which the computers the gateway fronts send it, and only they + # receive it, through their /svc routes; every other request goes on without it. + if not self._keeps_control_token(scope["path"]): + scope = {**scope, "headers": [(name, value) for name, value in headers if not ( + name == b"authorization" and hmac.compare_digest(value, self._control_bearer))]} if scope["type"] != "http": await inner(scope, receive, send) return diff --git a/src/agent_env/providers/env_providers/env_computer_provider.py b/src/agent_env/providers/env_providers/env_computer_provider.py index a4090fd43..e0467eb0c 100644 --- a/src/agent_env/providers/env_providers/env_computer_provider.py +++ b/src/agent_env/providers/env_providers/env_computer_provider.py @@ -29,7 +29,7 @@ app_settings_environment, boot, control_environment, - control_token, + control_token as new_control_token, discard, first_native, listed, @@ -85,6 +85,7 @@ async def deploy( reach: str = "", sites_later: bool = False, live_hosts: tuple[str, ...] = (), + control_token: Optional[str] = None, ) -> DeployedSandboxEnv: """The env's first ready build, in its base's order of forms and arches (or of ``env_params.form``), that the sandbox provider runs natively, booted, once what it boots that no compose started is composed; returns the record once @@ -92,7 +93,8 @@ async def deploy( a URL this process reaches, a network that restricts the computer's egress allows its host too, and the ``live_hosts`` of the run's live websites. With ``sites_later``, a computer routing sites, whose sites aren't up yet, boots with its boot apps held and returns - once its driver answers; ``route_sites`` routes them and finishes its boot.""" + once its driver answers; ``route_sites`` routes them and finishes its boot. With ``control_token``, its + framework-only routes take that token (a multi env's own) rather than one of the computer's own.""" from agent_env.env.envs.computer.env import ComputerEnv if not isinstance(env, ComputerEnv): @@ -125,7 +127,7 @@ async def deploy( attempt = functools.partial(self._boot, env, builds, params, values, ttl_seconds=ttl_seconds, disk_size_gb=disk_size_gb, cpu=cpu, memory_mb=memory_mb, attribution=attribution, tool_prefix=tool_prefix, reach=reach, sites_later=sites_later, - live_hosts=tuple(live_hosts)) + live_hosts=tuple(live_hosts), control_token=control_token) return await self._run(sandbox_provider, env.id, attempt) async def route_sites(self, env: ComputerEnv, record: DeployedSandboxEnv, sites: list[dict]) -> None: @@ -153,7 +155,8 @@ async def _boot(self, env: ComputerEnv, builds: list[tuple[str, str, dict]], par values: dict, sandbox_provider: SandboxProvider, *, ttl_seconds: int, disk_size_gb: float, cpu: float | None, memory_mb: int | None, attribution: Optional[Attribution], tool_prefix: str = "", reach: str = "", - sites_later: bool = False, live_hosts: tuple[str, ...] = ()) -> DeployedSandboxEnv: + sites_later: bool = False, live_hosts: tuple[str, ...] = (), + control_token: Optional[str] = None) -> DeployedSandboxEnv: """One attempt on one sandbox provider: the first build it runs natively, booted and readied; its record.""" from agent_env.env.envs.computer.env import ComputerEnv @@ -174,7 +177,7 @@ async def _boot(self, env: ComputerEnv, builds: list[tuple[str, str, dict]], par build = await probe_first_boot(env, form, arch, sandbox_provider) if build["status"] != "ready": raise RuntimeError(f"{env.id}'s {form}/{arch} failed its probe on its first boot: {build['reason']}") - computer, name, token = env.computer_artifact(), env.environment_name, control_token() + computer, name, token = env.computer_artifact(), env.environment_name, control_token or new_control_token() values = _values(computer, values) app_settings = recorded_app_settings(env.composed_apps(), computer_params.app_settings(env, params.app_settings), platform_of(env.computer.os)) diff --git a/src/agent_env/providers/env_providers/env_gateway_provider.py b/src/agent_env/providers/env_providers/env_gateway_provider.py index ec9747648..ad4ea32da 100644 --- a/src/agent_env/providers/env_providers/env_gateway_provider.py +++ b/src/agent_env/providers/env_providers/env_gateway_provider.py @@ -35,6 +35,7 @@ from agent_env.env.gateway import AGENT_ENV_GATEWAY_MCP_PORT, ExternalChild, GatewayMode from agent_env.env.gateway.constants import ( CLOCK_FOLLOWERS_ENV, + CONTROL_TOKEN_CHILDREN_ENV, DEFAULT_MCP_SERVER_NAME, GATEWAY_PROVIDER_HEADERS_ENV, STATE_TOOL_NAME_CLASHES_KEY, @@ -547,6 +548,8 @@ def create_docker_compose( gateway_env.append(f" - SERVICE_DB_URL={state_provider.base_url(state_instance)}") gateway_env.extend(f" - {key}={value}" for key, value in control_environment(control_token).items()) gateway_env.extend(f" - {key}={value}" for key, value in clock_followers_environment(external_children).items()) + gateway_env.extend(f" - {key}={value}" + for key, value in control_token_children_environment(external_children, control_token).items()) if provider_headers := sandbox_request_header_names(): gateway_env.append(f" - {GATEWAY_PROVIDER_HEADERS_ENV}={','.join(provider_headers)}") publish = host_port or (lambda port: port) @@ -658,13 +661,14 @@ async def deploy( attribution: Optional[Attribution] = None, artifact_id: str | None = None, artifact_version: int | None = None, - children: "Callable[[Optional[str]], Awaitable[list[ExternalChild]]] | None" = None, + children: "Callable[[Optional[str], Optional[str]], Awaitable[list[ExternalChild]]] | None" = None, ) -> DeployedGatewayEnv: """A gateway in front of the env, with the state store it acquires (local Postgres by default); returns the record. A MultiEnv's gateway fronts its MCP servers and websites, a WebsiteEnv's its website, and any other env's its one MCP server. ``children`` starts the env's children that run on sandboxes of their own, given the gateway's address where it's - known before the gateway starts, and returns them; the gateway starts once they have, fronting them too. + known before the gateway starts and the gateway's control token, which their framework-only routes take and the + gateway passes on to them alone, and returns them; the gateway starts once they have, fronting them too. """ from agent_env.config import get_config, service_db_env_id from agent_env.env.env import Env @@ -806,7 +810,7 @@ async def _deploy_via_vm( existing_sandbox: Sandbox | None = None, sidecars: list[SidecarConfig] | None = None, mcp_server_name: str | None = None, - children: "Callable[[Optional[str]], Awaitable[list[ExternalChild]]] | None" = None, + children: "Callable[[Optional[str], Optional[str]], Awaitable[list[ExternalChild]]] | None" = None, website_browser: "MCPServerEnv | None | object" = _THE_RUNS, control_token: str | None = None, ) -> DeployedGateway: @@ -921,7 +925,8 @@ async def _stand_up(_spec): # Everything but the gateway, beside the children; then the gateway, which waits for every child it fronts. # Both run to the end before either's failure is raised, so no child is still starting when the deploy closes. up, started = await asyncio.gather(self._compose_up(sandbox, f"--scale {GATEWAY_SERVICE_NAME}=0"), - children(sandbox.tunnel_urls.get(gateway_port)), return_exceptions=True) + children(sandbox.tunnel_urls.get(gateway_port), control_token), + return_exceptions=True) for result in (up, started): if isinstance(result, BaseException): raise result @@ -1016,7 +1021,7 @@ async def _deploy_via_containers( memory_mb: int | None = None, attribution: Optional[Attribution] = None, mcp_server_name: str | None = None, - children: "Callable[[Optional[str]], Awaitable[list[ExternalChild]]] | None" = None, + children: "Callable[[Optional[str], Optional[str]], Awaitable[list[ExternalChild]]] | None" = None, control_token: str | None = None, ) -> DeployedGateway: from agent_env.env.env import Env @@ -1073,7 +1078,7 @@ async def _deploy_via_containers( ] aux_coros = [self._provision_sidecar(deploy, spec) for spec in sidecar_specs] # The children start beside them; the gateway, created last, has no address to give them. - child_coros = [children(None)] if children is not None else [] + child_coros = [children(None, control_token)] if children is not None else [] all_results = await asyncio.gather(*mcp_coros, *aux_coros, *child_coros, return_exceptions=True) external: list[ExternalChild] = [] @@ -1123,6 +1128,7 @@ async def _deploy_via_containers( "MCP_SERVER_NAME": mcp_server_name or DEFAULT_MCP_SERVER_NAME, **control_environment(control_token), **clock_followers_environment(external), + **control_token_children_environment(external, control_token), **({GATEWAY_PROVIDER_HEADERS_ENV: ",".join(names)} if (names := sandbox_request_header_names()) else {}), } gateway_sb = await sandbox_provider.create_container( @@ -1457,7 +1463,7 @@ async def _deploy_gateway( mcp_server_name: str | None = None, control_token: str | None = None, attribution: Optional[Attribution] = None, - children: "Callable[[Optional[str]], Awaitable[list[ExternalChild]]] | None" = None, + children: "Callable[[Optional[str], Optional[str]], Awaitable[list[ExternalChild]]] | None" = None, website_browser: "MCPServerEnv | None | object" = _THE_RUNS, ) -> DeployedGateway: """One gateway deploy on one (unchained) sandbox provider: a VM on one that creates VMs, else a container per @@ -1767,6 +1773,13 @@ def clock_followers_environment(children: Iterable[ExternalChild]) -> dict[str, return {CLOCK_FOLLOWERS_ENV: followers} if followers else {} +def control_token_children_environment(children: Iterable[ExternalChild], control_token: str | None) -> dict[str, str]: + """The children the gateway passes its control token on to: every child it fronts on a sandbox of its own, each + deployed with that token (``children``).""" + names = ",".join(child.name for child in children) if control_token else "" + return {CONTROL_TOKEN_CHILDREN_ENV: names} if names else {} + + def _frontend_urls(gateway_url: str, website_configs: Optional[list[WebsiteConfig]]) -> Optional[dict[str, str]]: """Each synthetic site's page route through the gateway, by its environment name; None with none, as when every site is live.""" diff --git a/src/agent_env/task/task.py b/src/agent_env/task/task.py index 51bb53ff0..df78a58f4 100644 --- a/src/agent_env/task/task.py +++ b/src/agent_env/task/task.py @@ -674,8 +674,7 @@ async def _run_one(step: TaskStep, idx: int, dispatch_epoch: int) -> None: started_mono = time.monotonic() started_utc = datetime.now(timezone.utc).isoformat() try: - grants = {url: sent for deployed in context.deployed_envs for url, sent in deployed.control_grants.items()} - with protocol_v1.authorized(grants): + with protocol_v1.authorized({d.environment_url: d.control_headers for d in context.deployed_envs}): await step.execute(context) except asyncio.CancelledError: raise diff --git a/tst/integration/computer/multi_env_computers_test.py b/tst/integration/computer/multi_env_computers_test.py index ae8cccf0b..66139fbe2 100644 --- a/tst/integration/computer/multi_env_computers_test.py +++ b/tst/integration/computer/multi_env_computers_test.py @@ -2,8 +2,8 @@ The deploy_env step deploys each computer on a sandbox of its own and the gateway in front of them all. Through the gateway's one /mcp an agent sees the server's tools and each computer's under its name, takes screenshots by those names, -and a role rule narrows them as it would a server's; /svc// reaches the computer, its framework-only routes -with its own token. A later process reattaches the +and a role rule narrows them as it would a server's; /svc// reaches the computer, which boots with the +multi env's control token, its framework-only routes too. A later process reattaches the computers from the multi env's record, and the run's teardown leaves nothing up. Two computers keep serving through a computer's restart and the gateway's, a failed redeploy leaves the earlier deployment serving, and a computer that fails mid-deploy, or an entry the multi env refuses, leaves nothing up. Needs Docker and the local registry on localhost:5000.""" @@ -230,6 +230,7 @@ async def test_a_computer_in_a_multi_env_is_served_through_its_gateway_under_its assert _containers(computer["sandbox_id"]) == [] assert json.dumps(deployed.child_envs) # the record stores as JSON assert note == through_gateway == "from the universe" and "snap-x" in listed_items + assert computer["control_token"] == deployed.control_token # one token for the multi env, which the gateway passes on assert {"items", "desktop"} <= set(snapshot) and snapshot["desktop"]["Documents/note.txt"] == b"from the universe" # The gateway states each child's environment_name, which lookups, servers and snapshots go by: the shop # website's card is named webitems. diff --git a/tst/unit/env/envs/test_multi_env_computers.py b/tst/unit/env/envs/test_multi_env_computers.py index 1b49f38f6..93b1f0062 100644 --- a/tst/unit/env/envs/test_multi_env_computers.py +++ b/tst/unit/env/envs/test_multi_env_computers.py @@ -38,6 +38,8 @@ from tst.util.sandbox_providers import mock_provider GATEWAY = "https://gw.example" +#: The gateway's control token, which it hands the computers it fronts. +GATEWAY_TOKEN = "the-gateways" #: A computer's card whose driver serves clock/v1's sync_time: it follows the gateway's clock. @@ -286,7 +288,7 @@ def gateway(monkeypatch, local_stores): async def deploy(self, env, sandbox_provider, *, children=None, **options): made.options.append({**options, "children": children}) for _ in range(made.tries): - made.started.append(await children(GATEWAY) if children else None) + made.started.append(await children(GATEWAY, GATEWAY_TOKEN) if children else None) if made.fails: raise made.fails return DeployedGatewayEnv(env_id=env.id, env_version=env.version, gateway_url=GATEWAY, sandbox_id="gw", @@ -302,7 +304,8 @@ async def close(self): @pytest.mark.asyncio -async def test_deploy_hands_the_gateway_each_computer_deployed_under_its_name_and_records_it(gateway, providers): +async def test_deploy_hands_the_gateway_each_computer_deployed_under_its_name_with_its_token_and_records_it(gateway, + providers): desktop, laptop = FakeComputer("desktop"), FakeComputer("laptop") attribution = {"project_id": "6a6d2e30b2710a6cf93a6430"} @@ -311,9 +314,10 @@ async def test_deploy_hands_the_gateway_each_computer_deployed_under_its_name_an child_envs={"desktop": {"sandbox_type": "modal", "cpu": 4, "env_params": {"form": "container"}}}) assert desktop.deploys == [{"ttl_seconds": 600, "attribution": attribution, "tool_prefix": "desktop_", "reach": GATEWAY, - "sites_later": False, "sandbox_type": "modal", "cpu": 4, "env_params": {"form": "container"}}] + "sites_later": False, "control_token": GATEWAY_TOKEN, "sandbox_type": "modal", "cpu": 4, + "env_params": {"form": "container"}}] assert laptop.deploys == [{"ttl_seconds": 600, "attribution": attribution, "tool_prefix": "laptop_", "reach": GATEWAY, - "sites_later": False, "sandbox_type": "modal_vm"}] + "sites_later": False, "control_token": GATEWAY_TOKEN, "sandbox_type": "modal_vm"}] assert gateway.started == [[ExternalChild("desktop", "https://desktop.example/mcp", "https://desktop.example"), ExternalChild("laptop", "https://laptop.example/mcp", "https://laptop.example")]] assert deployed.child_envs == {name: dataclasses.asdict(_record(name)) for name in ("desktop", "laptop")} @@ -927,7 +931,7 @@ async def test_a_browser_computer_deploys_as_a_computer_child_routing_the_sites_ sandbox_type="modal_vm", child_envs={"chromium": {"sandbox_type": "modal", "cpu": 2, "memory_mb": 4096}}) assert chromium.deploys == [{"ttl_seconds": 10800, "attribution": None, "tool_prefix": "chromium_", - "reach": GATEWAY, "sites_later": True, + "reach": GATEWAY, "sites_later": True, "control_token": GATEWAY_TOKEN, "live_hosts": ("github.test", "api.github.test"), "sandbox_type": "modal", "cpu": 2, "memory_mb": 4096, "env_params": {"site_routing": True}}] diff --git a/tst/unit/env/gateway/clock_watch_test.py b/tst/unit/env/gateway/clock_watch_test.py index 018e5bee3..552a74f31 100644 --- a/tst/unit/env/gateway/clock_watch_test.py +++ b/tst/unit/env/gateway/clock_watch_test.py @@ -33,9 +33,9 @@ def gateway(tmp_path, monkeypatch): monkeypatch.setattr(ClockFollowers, "WATCH_S", HELD_S) made = [] - def make(followers=TOKENS) -> Gateway: + def make(followers=TOKENS, control_token=None) -> Gateway: made.append(Gateway(host="127.0.0.1", port=0, server_name="unit", internal_mcp_servers=[], - clock_followers=followers)) + clock_followers=followers, control_token=control_token)) return made[-1] yield make @@ -184,6 +184,20 @@ async def test_a_watch_acknowledges_only_with_its_computers_token(gateway, monke assert state["followers"] == {"laptop": {"version": None, "seen_s_ago": None}} +@pytest.mark.asyncio +async def test_a_computer_whose_token_is_the_gateways_own_acknowledges_with_it(gateway): + """A multi env's computers boot with its gateway's control token, which their watches carry as their read token.""" + gw = gateway({"desktop": "the-gateways"}, control_token="the-gateways") + async with _client(gw) as client: + follower = asyncio.create_task(_follow(client, "desktop", "the-gateways")) + try: + await _until_shown(gw, "desktop") + answer = await client.put("/clock/set-time", json={"virtual_time": T0, "wait_followers_s": 5}) + finally: + follower.cancel() + assert answer.status_code == 200, answer.json() + + @pytest.mark.asyncio @pytest.mark.parametrize("claim", ["later", "another-clocks"]) async def test_an_acknowledgement_cant_claim_a_version_the_clock_hasnt_had(gateway, claim): diff --git a/tst/unit/env/gateway/control_token_test.py b/tst/unit/env/gateway/control_token_test.py index b561ba1c9..35e3ead1e 100644 --- a/tst/unit/env/gateway/control_token_test.py +++ b/tst/unit/env/gateway/control_token_test.py @@ -82,6 +82,18 @@ async def echo(request): assert response.json() == {"authorization": seen} +@pytest.mark.parametrize("path, kept", [ + ("/svc/desktop/agentenv/ext/computer-exec", True), ("/svc/desktop", True), ("/clock/watch", True), + ("/svc/mcp-items/agentenv", False), ("/svc/desktop-2/agentenv", False), ("/website/desktop/", False), + ("/state", False)]) +def test_its_token_goes_on_only_to_the_computers_it_fronts_and_to_its_clock_watch(path, kept): + """A multi env's computers boot with the gateway's token and take it on their /svc routes, and send it to its clock + watch as their read token; every other request loses it.""" + gw = Gateway(host="127.0.0.1", port=0, server_name="unit", internal_mcp_servers=[], control_token=TOKEN, + control_token_children=["desktop"]) + assert gw._keeps_control_token(path) is kept + + @pytest.mark.asyncio @pytest.mark.parametrize("path", sorted(CONTROL)) async def test_a_gateway_started_without_a_token_checks_none(path): diff --git a/tst/unit/env/test_env.py b/tst/unit/env/test_env.py index 0a8884f86..a30119dba 100644 --- a/tst/unit/env/test_env.py +++ b/tst/unit/env/test_env.py @@ -132,37 +132,6 @@ async def test_a_record_with_a_control_token_sends_it_on_each_extension_call_onl assert _record(composed).control_headers == {} and _record(composed).control_headers_for(env) == {} -@pytest.mark.asyncio -async def test_a_call_to_a_computer_the_gateway_fronts_sends_the_computers_own_token_and_one_to_the_gateway_its(sent): - """The gateway takes its own token off a call and passes any other on, so a multi env's computer, which takes only - its own, is reached through the gateway's route to it with the token its own record keeps.""" - gw = Gateway(host="127.0.0.1", port=0, server_name="env1234", internal_mcp_servers=[], - rest_proxy_urls={"mcp-slack": "http://slack:18765", "desk": "http://desk:18765"}) - desk_card = {"name": "desk", "url": "/agentenv", "capabilities": {"extensions": [ - _ext("urn:agentenv:computer-exec/v1", "/agentenv/ext/computer-exec", "run")]}} - - async def fetch(client, key, base_url): - return gw._rewrite_child_card(key, desk_card if key == "desk" else _SLACK) - - gw._fetch_child_card = fetch - deployed = _record(json.loads((await gw._serve_env_card()).body)) - deployed.control_token = "g4teway" - desk = DeployedSandboxEnv(env_id="desk-env", env_version=1, env_provider_type="computer", sandbox_id="sb-2", - environment_card_url=f"http://desk.example{WELL_KNOWN_PATH}", control_token="d3sk") - deployed.child_envs = {"desk": dataclasses.asdict(desk)} - env = deployed.environment_url - - await deployed.invoke("urn:agentenv:computer-exec/v1", "run", {"argv": ["true"]}, environment_name="desk") - await deployed.invoke("urn:agentenv:set-errors/v1", "set_errors", {}, environment_name="slack") - - assert [(request.url.path, request.headers.get("authorization")) for request in sent] == [ - ("/svc/desk/agentenv/ext/computer-exec", "Bearer d3sk"), ("/svc/mcp-slack/agentenv/ext/set_errors", "Bearer g4teway")] - assert [deployed.control_headers_for(url) for url in (f"{env}/svc/desk/agentenv", f"{env}/svc/mcp-slack/agentenv")] == [ - {"Authorization": "Bearer d3sk"}, {"Authorization": "Bearer g4teway"}] - deployed.child_envs = {"desk": dataclasses.asdict(dataclasses.replace(desk, control_token=None))} - assert deployed.control_grants == {env: {"Authorization": "Bearer g4teway"}} - - def test_child_env_cards_come_from_the_card_by_name(composed): deployed = _record(composed) assert deployed.get_child_env_card("slack")["url"] == "/svc/mcp-slack/agentenv" diff --git a/tst/unit/providers/env_providers/env_gateway_provider_test.py b/tst/unit/providers/env_providers/env_gateway_provider_test.py index fdae4f3a0..5b0c0a117 100644 --- a/tst/unit/providers/env_providers/env_gateway_provider_test.py +++ b/tst/unit/providers/env_providers/env_gateway_provider_test.py @@ -2882,6 +2882,23 @@ def test_compose_fronts_each_external_child_as_an_mcp_server_and_a_rest_route_by assert "CLOCK_FOLLOWER_TOKENS" not in env +def test_compose_names_the_children_the_gateway_passes_its_token_on_to_only_when_it_has_one(): + from agent_env.env.envs.service_db import ServiceDBConfig + from agent_env.env.gateway import ExternalChild + + def gateway_env(control_token): + rendered = EnvironmentGatewayProvider().create_docker_compose( + mcp_servers=[MCPServerConfig(image="mcp-slack", environment_name="slack")], gateway_image="agent-gateway", + state_provider=LocalPostgresStateProvider(service_db_config=ServiceDBConfig()), + state_instance=LocalPostgresStateProvider.default_instance(), control_token=control_token, + external_children=(ExternalChild("desktop", "https://desk.example/mcp", "https://desk.example"), + ExternalChild("laptop", "https://lap.example/mcp", "https://lap.example"))) + return dict(line.split("=", 1) for line in yaml.safe_load(rendered)["services"][GATEWAY_SERVICE_NAME]["environment"]) + + assert gateway_env("gw-token")["CONTROL_TOKEN_CHILDREN"] == "desktop,laptop" + assert "CONTROL_TOKEN_CHILDREN" not in gateway_env(None) + + def test_compose_declares_the_children_that_follow_the_clock_by_their_read_tokens_and_logs_none_of_them(): from agent_env.env.envs.service_db import ServiceDBConfig from agent_env.env.gateway import ExternalChild @@ -2932,8 +2949,8 @@ async def test_a_vm_deploy_starts_its_children_beside_its_services_and_the_gatew sandbox.url_from_sandbox = MagicMock(side_effect=lambda url: url.replace("localhost", "host.docker.internal")) order, composes = [], [] - async def children(reach): - order.append(("children", reach)) + async def children(reach, control_token): + order.append(("children", reach, control_token)) return [ExternalChild("desktop", "http://localhost:20001/mcp", "http://localhost:20001", "read-desk")] def compose(**kwargs): @@ -2957,9 +2974,9 @@ async def up(sandbox, args=""): sandbox_provider=MagicMock(create_vm=AsyncMock(return_value=sandbox)), mcp_servers=[MCPServerConfig(image="mcp-slack", environment_name="slack")], mcp_server_images=[_loadable("mcp-slack")], gateway_port=18765, website_configs=None, website_images=None, gateway_mode=GatewayMode.PERFORMANCE, ttl_seconds=60, - disk_size_gb=10, children=children) + disk_size_gb=10, children=children, control_token="gw-token") - assert sorted(order[:2]) == [("children", "https://gw.example"), ("up", f"--scale {GATEWAY_SERVICE_NAME}=0")] + assert sorted(order[:2]) == [("children", "https://gw.example", "gw-token"), ("up", f"--scale {GATEWAY_SERVICE_NAME}=0")] assert order[2:] == [("up", "")] assert composes == [(), (ExternalChild("desktop", "http://host.docker.internal:20001/mcp", "http://host.docker.internal:20001", "read-desk"),)] @@ -2978,7 +2995,7 @@ async def test_a_vm_deploy_whose_children_or_services_fail_raises_once_both_have gp._state_instance = MagicMock() ended = [] - async def children(reach): + async def children(reach, control_token): await asyncio.sleep(0.05) ended.append("children") if failing == "children": @@ -3022,8 +3039,8 @@ async def fake_create_container(**kwargs): return _FakeSandbox(f"db-{port}", port, f"tcp://db.modal.host:{port}") return _FakeSandbox(f"sb-{kwargs['image_name']}-{port}", port, f"https://{kwargs['image_name']}.modal.host") - async def children(reach): - reaches.append(reach) + async def children(reach, control_token): + reaches.append((reach, control_token)) return [ExternalChild("desktop", "https://desk.example/mcp", "https://desk.example", "read-desk")] gateway_env = MagicMock(docker_image_artifact=_image("agent-gateway")) @@ -3038,13 +3055,15 @@ async def children(reach): await gp._deploy_via_containers( sandbox_provider=provider, mcp_servers=[MCPServerConfig(image="mcp-slack", environment_name="slack")], mcp_server_images=[_image("mcp-slack")], gateway_port=18765, website_configs=None, - gateway_mode=GatewayMode.PERFORMANCE, ttl_seconds=60, disk_size_gb=10, children=children) + gateway_mode=GatewayMode.PERFORMANCE, ttl_seconds=60, disk_size_gb=10, children=children, + control_token="gw-token") env = create_calls[-1]["env"] - assert reaches == [None] + assert reaches == [(None, "gw-token")] assert env["INTERNAL_MCP_SERVERS"].split(",")[-1] == "desktop=https://desk.example/mcp" assert env["REST_PROXY_URLS"].split(",")[-1] == "desktop=https://desk.example" assert env["CLOCK_FOLLOWER_TOKENS"] == "desktop=read-desk" + assert env["CONTROL_TOKEN_CHILDREN"] == "desktop" def _run_probe(tmp_path, statuses: dict[str, int]) -> int: diff --git a/tst/unit/task/control_grant_test.py b/tst/unit/task/control_grant_test.py index 5752dfdaa..8e76ffbcc 100644 --- a/tst/unit/task/control_grant_test.py +++ b/tst/unit/task/control_grant_test.py @@ -1,16 +1,13 @@ """Every step runs under a grant of each deployed env's control token: a protocol-client call the step makes to an env's address carries that env's token unless the call names its own headers, an env without one is sent none, an env an -earlier step deployed is granted to the steps after it, the grant ends with the step, and a call through a multi env's -gateway to a computer it fronts carries the computer's own token.""" - -import dataclasses +earlier step deployed is granted to the steps after it, and the grant ends with the step.""" import pytest from agentenv_protocol import WELL_KNOWN_PATH from agentenv_protocol import client as protocol_v1 from agent_env.config.runtime import Config -from agent_env.env.env import DeployedEnv, DeployedGatewayEnv, DeployedSandboxEnv +from agent_env.env.env import DeployedEnv from agent_env.task import Task from agent_env.task_step.context import TaskStepContext from agent_env.task_step.task_step import TaskStep @@ -75,40 +72,3 @@ async def test_a_step_calls_each_deployed_env_with_its_own_token_and_the_grant_e assert _Calls.seen == [[{}, {}, {}, {"X-Own": "1"}], [{"Authorization": "Bearer s3cret"}, {}, {}, {"X-Own": "1"}]] assert protocol_v1.request_headers(f"{DESK}/agentenv") == {} - - -class _CallsTheDesktop(TaskStep): - """Records what its calls through the office's gateway send: to the desktop computer it fronts, and to the gateway.""" - - type = "control_grant_test_desktop_calls" - entity_refs = () - seen: list = [] - - @classmethod - def from_dict(cls, data): - return cls(**cls._base_from_dict(data)) - - async def execute(self, context): - _CallsTheDesktop.seen.append([protocol_v1.request_headers(f"{OFFICE}{path}") - for path in ("/svc/desktop/agentenv/ext/computer-exec", "/agentenv/ext/clock")]) - return context - - -OFFICE = "http://office:8080" - - -@pytest.mark.asyncio -async def test_a_step_calls_a_computer_a_multi_envs_gateway_fronts_with_the_computers_own_token(local_stores, monkeypatch): - steps = {**Config().task_step_registry(), _CallsTheDesktop.type: _CallsTheDesktop} - monkeypatch.setattr(Config, "task_step_registry", lambda self: steps) - monkeypatch.setattr(_CallsTheDesktop, "seen", []) - desktop = DeployedSandboxEnv(env_id="desktop", env_version=1, env_provider_type="computer", sandbox_id="sb-2", - environment_card_url=f"http://desktop:8000{WELL_KNOWN_PATH}", control_token="d3sk") - office = DeployedGatewayEnv(env_id="office", env_version=1, gateway_url=OFFICE, sandbox_id="sb-1", - environment_card_url=f"{OFFICE}{WELL_KNOWN_PATH}", control_token="g4teway", - child_envs={"desktop": dataclasses.asdict(desktop)}) - - await Task(id="t", version=None, steps=[_CallsTheDesktop(id="calls", version=None)]).run( - context=TaskStepContext(deployed_envs=[office])) - - assert _CallsTheDesktop.seen == [[{"Authorization": "Bearer d3sk"}, {"Authorization": "Bearer g4teway"}]] From 8adbc4fa710d388680834b9aa2dc59f6d1f03eac Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sun, 15 Nov 2026 09:42:38 -0800 Subject: [PATCH 4/4] test(env): after a gateway restart both computers of a multi env still take its token through the gateway Co-Authored-By: Claude Opus 5.5 --- tst/integration/computer/multi_env_computers_test.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/tst/integration/computer/multi_env_computers_test.py b/tst/integration/computer/multi_env_computers_test.py index 66139fbe2..a9f4a0d0f 100644 --- a/tst/integration/computer/multi_env_computers_test.py +++ b/tst/integration/computer/multi_env_computers_test.py @@ -269,6 +269,10 @@ async def test_two_computers_keep_serving_through_restarts_and_a_failed_redeploy started = await _answers(deployed, every) _docker("restart", _gateway(deployed, made)) restarted = await _answers(deployed, every) + # The restarted gateway still passes the multi env's token on to each computer, which takes it. + reached = [(await deployed.invoke(COMPUTER_EXEC, "run", { + "argv": ["true"], "request_id": uuid.uuid4().hex, "timeout_s": 30}, environment_name=name))["exit_code"] + for name in ("desktop", "laptop")] deployed_before = _containers_made(made) real = EnvironmentGatewayProvider._compose_up @@ -292,6 +296,7 @@ async def no_gateway(self, sandbox, args=""): assert all(both.values()), both assert killed == {"list_items": True, "desktop_computer_screenshot": False, "laptop_computer_screenshot": True} assert all(started.values()) and all(restarted.values()), (started, restarted) + assert reached == [0, 0] assert after_failure == deployed_before and all(still.values()), (after_failure - deployed_before, still) assert kept == [deployed.child_envs[name]["sandbox_id"] for name in ("desktop", "laptop")] assert _containers_made(made) == set()