From 2dac27306b9837db3e596b3816175dd992a39a2e Mon Sep 17 00:00:00 2001 From: Ubuntu Date: Thu, 19 Nov 2026 18:38:10 +0000 Subject: [PATCH 1/2] feat(env): give each computer in a multi env a control token of its own Each computer mints its own control token at deploy. The gateway receives them in CHILD_CONTROL_TOKENS and sends each computer's token on that computer's /svc routes. A driver whose card advertises control_token "sha256" boots with only the token's digest (AGENTENV_CONTROL_TOKEN_SHA256). granted_headers picks the longest matching grant. CONTROL_TOKEN_CHILDREN stays for computers an older agent-env booted. --- AGENTS.md | 2 +- .../src/agentenv_protocol/__init__.py | 2 + .../agent_env_environment.py | 19 ++- .../src/agentenv_protocol/client.py | 7 +- .../src/agentenv_protocol/computer/card.py | 8 +- .../agentenv_protocol/computer/serve_app.py | 5 +- .../src/agentenv_protocol/types.py | 3 + .../tests/test_computer_driver.py | 1 + .../tests/test_control_token.py | 35 ++++++ src/agent_env/env/env.py | 28 ++++- src/agent_env/env/envs/_multi_computers.py | 16 +-- src/agent_env/env/envs/computer/env.py | 9 +- src/agent_env/env/envs/computer/utils/boot.py | 27 +++-- src/agent_env/env/gateway/__init__.py | 6 +- src/agent_env/env/gateway/constants.py | 7 +- src/agent_env/env/gateway/entrypoint.py | 21 ++-- src/agent_env/env/gateway/gateway.py | 47 +++++--- .../env_providers/env_computer_provider.py | 14 +-- .../env_providers/env_gateway_provider.py | 27 ++--- src/agent_env/task/task.py | 2 +- .../computer/multi_env_computers_test.py | 3 +- tst/unit/env/envs/test_computer_env.py | 26 +++- tst/unit/env/envs/test_multi_env_computers.py | 25 ++-- tst/unit/env/gateway/clock_watch_test.py | 22 +++- tst/unit/env/gateway/control_token_test.py | 111 ++++++++++++++++-- tst/unit/env/test_env.py | 15 +++ .../env_gateway_provider_test.py | 34 +++--- 27 files changed, 388 insertions(+), 134 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 48174a839..580c0c581 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -140,7 +140,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`): 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 composes only the computer envs its tasks deploy (`materialize._composed_envs`: each env a task's steps name, and each env those hold but a computer env's own apps and driver, which run inside it) and those it pulls in from an installed bundle, whose one write every bundle shares, every one for a plan with no tasks, any other composing at its first deploy; one that reuses a computer env composes what it has left (`pending`), a run, and a register given a `--sandbox`, 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. A request from a computer's site proxy names its computer (`AgentEnv-Computer`, sent from the proxy's private upstream headers, a page's own copy and any `AgentEnv-Role` it sends dropped) and takes the role driving that computer now (the gateway's computers being those `COMPUTERS` names, a multi env's, with or without a control token): the last to make an input call to its tools, as the call starts, through `/mcp`, `/step` or a trigger action under its `as` (`Gateway._drive`); without one, or from a computer the gateway doesn't front, it is `default`, the role read once per request. `changes/v1` (`ChangeAttribution`) counts no write window for a call to a computer's tools, a trigger action's included, so a write the computer's browser made goes to its request and one another party made during the call to that party. 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 also in the universe's zone, the one `sync_env_clock`'s `timezone` armed it in, or in an IANA `time_zone` it's given; 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. Its `headline_verifiers`, step ids saved only when set, name the grades that are its reward: one is the reward, several a multi-reward over them, none a multi-reward over every grade; it refuses one that names no step of the task, or one named twice. `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. `task/lint.py` is `agent-env task lint` (a bundle folder, a task file or a stored task): an error is what a task gets wrong before it runs (a field its step doesn't read, a step's own `config_problems`, a headline that grades nothing, an aggregate source no verifier writes) and refuses `agent-env run`, `bundle register`, `task create`, `task validate` and `eval run`, and the bundle plans `openenv`'s `build_app` and the trainers make (`run`, `register`, `build_app`, `prepare_bundle` and the trainers take `--skip-lint`/`skip_lint`, which lifts lint's own rules but not a step's `config_problems`, which refused a bundle before lint; `eval run`'s lifts every error, since it checked none before); a warning is what may be wrong (a step's `config_warnings`, a store entity read with no version, no verifier, several and no headline) and is only printed, each kind once by a run (`task.lint.said`), an eval run's unpinned references as one count (`unpinned_summary`), every one by `task lint`. Built-in steps live in `task_step/task_steps/` (`deploy_env`, `deploy_agent`, `prompt_agent`, the verifiers under `verifiers/`, among them `start_computer_recording` (its driver draws each input over the frames in its caller's colour, and a pointer per role where the frames lack one, unless `annotation_settings` says `is_enabled: false`; a driver whose card lists no `annotate` records it plain, with a warning, and the run's recording entry says `annotated`) 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). Every built-in verifier is on the `VerifierTaskStep` base (`verifiers/verifier.py`): it implements `verify` and returns a `Verification`, and the base writes the step's named grade to `context.metadata["grades"][]` (score, `min_passing_score`, `passed`, `verifier_status` graded, skipped or failed, criteria rows, type, version, and `verifier_settings`, the values the run graded with, its overrides applied and named in `overridden`, with `scoring_rules`) beside the legacy `verifications` entries every reader still takes; an exception from `verify` or a `Verification` with an `error`, as a timed-out `run_container_unit_tests_verifier`, is a failed grade, and `rubrics_verifier` still writes its `-trajectory-mistakes` entry itself. 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`; `computer_exec` runs one command there through `run` (a program and its arguments, or a string through `sh -c`; in a multi env, the computer it names), recorded under `computer_exec` in the run's metadata, a non-zero exit or a timeout failing it unless `check` is off, or with `background` starts it and leaves it running, as an app launched for the agent, a program that isn't there exiting 127; with `scope: "system"` it runs as root instead, through the computer's sandbox (`RootChannel`, `docker exec -u 0`), in the session user's folder and `HOME`, its output capped in the computer, never with `background` and not on a computer booted from a disk; on a Windows computer, which has no `sh`, a string or `background` command is refused; on a multi env, `load_artifact` with `env_id` puts an environment artifact named after one of its computers, or after an app of one, into that computer, the computer's own as files at their paths under the session user's home; `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. A run whose teardown leaves sandboxes up, stopped by a second signal or failing, keeps on its instance the context it ended with (`record_teardown`), and `agent-env run` and `task run --keep` name `agent-env task teardown --instance `, which tears down what that context still records up, a running one only with `--force`. `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. Its `headline_verifiers`, step ids saved only when set, name the grades that are its reward: one is the reward, several a multi-reward over them, none a multi-reward over every grade; it refuses one that names no step of the task, or one named twice. `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. `task/lint.py` is `agent-env task lint` (a bundle folder, a task file or a stored task): an error is what a task gets wrong before it runs (a field its step doesn't read, a step's own `config_problems`, a headline that grades nothing, an aggregate source no verifier writes) and refuses `agent-env run`, `bundle register`, `task create`, `task validate` and `eval run`, and the bundle plans `openenv`'s `build_app` and the trainers make (`run`, `register`, `build_app`, `prepare_bundle` and the trainers take `--skip-lint`/`skip_lint`, which lifts lint's own rules but not a step's `config_problems`, which refused a bundle before lint; `eval run`'s lifts every error, since it checked none before); a warning is what may be wrong (a step's `config_warnings`, a store entity read with no version, no verifier, several and no headline) and is only printed, each kind once by a run (`task.lint.said`), an eval run's unpinned references as one count (`unpinned_summary`), every one by `task lint`. Built-in steps live in `task_step/task_steps/` (`deploy_env`, `deploy_agent`, `prompt_agent`, the verifiers under `verifiers/`, among them `start_computer_recording` (its driver draws each input over the frames in its caller's colour, and a pointer per role where the frames lack one, unless `annotation_settings` says `is_enabled: false`; a driver whose card lists no `annotate` records it plain, with a warning, and the run's recording entry says `annotated`) 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). Every built-in verifier is on the `VerifierTaskStep` base (`verifiers/verifier.py`): it implements `verify` and returns a `Verification`, and the base writes the step's named grade to `context.metadata["grades"][]` (score, `min_passing_score`, `passed`, `verifier_status` graded, skipped or failed, criteria rows, type, version, and `verifier_settings`, the values the run graded with, its overrides applied and named in `overridden`, with `scoring_rules`) beside the legacy `verifications` entries every reader still takes; an exception from `verify` or a `Verification` with an `error`, as a timed-out `run_container_unit_tests_verifier`, is a failed grade, and `rubrics_verifier` still writes its `-trajectory-mistakes` entry itself. 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`; `computer_exec` runs one command there through `run` (a program and its arguments, or a string through `sh -c`; in a multi env, the computer it names), recorded under `computer_exec` in the run's metadata, a non-zero exit or a timeout failing it unless `check` is off, or with `background` starts it and leaves it running, as an app launched for the agent, a program that isn't there exiting 127; with `scope: "system"` it runs as root instead, through the computer's sandbox (`RootChannel`, `docker exec -u 0`), in the session user's folder and `HOME`, its output capped in the computer, never with `background` and not on a computer booted from a disk; on a Windows computer, which has no `sh`, a string or `background` command is refused; on a multi env, `load_artifact` with `env_id` puts an environment artifact named after one of its computers, or after an app of one, into that computer, the computer's own as files at their paths under the session user's home; `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`), each computer its own, a multi env's included, never the gateway's: its boot environment holds only the token's sha256 (`AGENTENV_CONTROL_TOKEN_SHA256`) when its probed card's computer/v1 says `control_token = "sha256"`, else, for a driver an older protocol built, the token itself (`AGENTENV_CONTROL_TOKEN`); the gateway learns each computer's (`CHILD_CONTROL_TOKENS`), puts it in place of its own on that computer's `/svc` routes, and lets a computer's token through only to that computer and its clock watch; a multi env's record grants each computer's `/svc` route its own token (`DeployedGatewayEnv.control_grants`, the longest granted address winning), and `CONTROL_TOKEN_CHILDREN`, the computers an older agent-env booted with the gateway's token, is kept for them; 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. A run whose teardown leaves sandboxes up, stopped by a second signal or failing, keeps on its instance the context it ended with (`record_teardown`), and `agent-env run` and `task run --keep` name `agent-env task teardown --instance `, which tears down what that context still records up, a running one only with `--force`. `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), `kosa8` (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/__init__.py b/packages/agentenv-protocol/src/agentenv_protocol/__init__.py index 6ec86820f..4bc0253a7 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/__init__.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/__init__.py @@ -56,6 +56,7 @@ from .types import ( CONTROL_TOKEN_ENV, CONTROL_TOKEN_HEADER, + CONTROL_TOKEN_SHA256_ENV, DATA_OBJECTS_EXTENSION_URI, INTAKE_EXTENSION_URI, MCP_PATH, @@ -167,6 +168,7 @@ "RPC_PATH", "CONTROL_TOKEN_ENV", "CONTROL_TOKEN_HEADER", + "CONTROL_TOKEN_SHA256_ENV", "WELL_KNOWN_PATH", "METHOD_RESET", "METHOD_ADD", diff --git a/packages/agentenv-protocol/src/agentenv_protocol/agent_env_environment.py b/packages/agentenv-protocol/src/agentenv_protocol/agent_env_environment.py index c57a6ad77..8a9b21718 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/agent_env_environment.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/agent_env_environment.py @@ -5,6 +5,7 @@ import decimal import enum import functools +import hashlib import hmac import inspect import json @@ -29,7 +30,7 @@ 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 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 +from .types import CONTROL_TOKEN_ENV, CONTROL_TOKEN_SHA256_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__) @@ -1622,8 +1623,14 @@ def _error_response(error: AgentEnvError) -> Response: def control_check() -> Callable[[Any], bool]: - """Whether a call's headers carry the env's control token as their bearer, with ``CONTROL_TOKEN_ENV`` set; without - it, any do.""" + """Whether a call's headers carry the env's control token as their bearer: one whose sha256 is + ``CONTROL_TOKEN_SHA256_ENV`` when that is set, else ``CONTROL_TOKEN_ENV``; with neither set, any do.""" + if digest := os.environ.get(CONTROL_TOKEN_SHA256_ENV, "").strip().lower(): + def verified(headers: Any) -> bool: + scheme, _, token = headers.get("authorization", "").partition(" ") + sent = hashlib.sha256(token.encode()).hexdigest() if scheme == "Bearer" and token else "" + return hmac.compare_digest(sent, digest) + return verified token = os.environ.get(CONTROL_TOKEN_ENV) if not token: return lambda headers: True @@ -1633,9 +1640,9 @@ def control_check() -> Callable[[Any], bool]: 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.""" - if not os.environ.get(CONTROL_TOKEN_ENV): + ``CONTROL_TOKEN_SHA256_ENV`` or ``CONTROL_TOKEN_ENV`` set, a call that doesn't carry the token as its bearer is + refused before the route runs (``control_check``); without either, nothing.""" + if not (os.environ.get(CONTROL_TOKEN_SHA256_ENV) or os.environ.get(CONTROL_TOKEN_ENV)): return lambda handler: handler allowed = control_check() diff --git a/packages/agentenv-protocol/src/agentenv_protocol/client.py b/packages/agentenv-protocol/src/agentenv_protocol/client.py index 0d76ad4aa..dbe590837 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/client.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/client.py @@ -77,9 +77,10 @@ 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 child's route under its gateway's, and none anywhere else.""" + under = [(len(base.rstrip("/")), sent) for base, sent in grants.items() + if base and (url == base.rstrip("/") or url.startswith(f"{base.rstrip('/')}/"))] + return max(under, key=lambda found: found[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/src/agentenv_protocol/computer/card.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/card.py index 2f99ca982..b52a0f5bd 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/card.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/card.py @@ -23,6 +23,8 @@ COMPUTER_EXEC = "urn:agentenv:computer-exec/v1" COMPUTER_RECORDING = "urn:agentenv:computer-recording/v1" +#: What computer/v1's ``control_token`` says of a driver that takes its control token's sha256. +CONTROL_TOKEN_SHA256 = "sha256" MAX_EXEC_TIMEOUT_S = 3600 KEYBOARD_RANGES = {"tap_hold_ms": (0, 1000), "type_delay_ms": (0, 1000), "max_hold_ms": (0, 600_000)} @@ -86,8 +88,9 @@ def extension_params(driver: ComputerDriverEnvironment, uri: str) -> dict: def computer_features(driver: ComputerDriverEnvironment) -> dict: - """computer/v1's params: what the seven tools take, how input is delivered, the platform and the default data - paths.""" + """computer/v1's params: what the seven tools take, how input is delivered, the platform, the default data paths, + and that the driver takes its control token's sha256 (``CONTROL_TOKEN_SHA256_ENV``), so agent-env boots it with + that and not the token.""" return { "buttons": list(driver.buttons), "max_click_count": driver.max_click_count, "keys": driver.keys if driver.keys == "all" else list(driver.keys), "max_text_length": driver.max_text_length, @@ -95,6 +98,7 @@ def computer_features(driver: ComputerDriverEnvironment) -> dict: "max_duration_ms": driver.max_duration_ms, "max_key_repeat": driver.max_key_repeat, "max_scroll_amount": driver.max_scroll_amount, "delivery": "foreground", "platform": driver.platform.as_dict(), "supports": list(driver.supports), "default_data_paths": list(DEFAULT_DATA_PATHS), "screen": driver.screen_kind, + "control_token": CONTROL_TOKEN_SHA256, } diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/serve_app.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/serve_app.py index fb58ec48e..962cc8126 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/serve_app.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/serve_app.py @@ -2,7 +2,7 @@ ``python -m agentenv_protocol.computer.serve_app :``, run in the app's folder, serves the class's card and ``computer-app/v1`` where only the computer reaches it (``served``): on Linux and macOS the Unix socket ``.agentenv/server.sock`` there, on Windows a loopback port it writes there with a token. 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 +(``CONTROL_TOKEN_ENV``, ``CONTROL_TOKEN_SHA256_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. It runs on real time, so its own @@ -20,7 +20,7 @@ import uvicorn from .. import transfers -from ..types import CONTROL_TOKEN_ENV +from ..types import CONTROL_TOKEN_ENV, CONTROL_TOKEN_SHA256_ENV from ._load import load_class from .app import FAILURE, ComputerAppEnvironment from .served import LOOPBACK, SOCKET, bind, guarded @@ -45,6 +45,7 @@ def _serve(argv: list[str]) -> None: raise SystemExit(USAGE) file, _, name = argv[0].partition(":") os.environ.pop(CONTROL_TOKEN_ENV, None) + os.environ.pop(CONTROL_TOKEN_SHA256_ENV, None) app = load_class(Path(file), name, ComputerAppEnvironment)() runtime = app._computer_app_runtime() app._computer_app_data_plane().keep_initial() diff --git a/packages/agentenv-protocol/src/agentenv_protocol/types.py b/packages/agentenv-protocol/src/agentenv_protocol/types.py index dff8e0f45..de5d2b77a 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/types.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/types.py @@ -19,6 +19,9 @@ def error_body(code: str, message: str, **fields: Any) -> dict: #: 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" +#: The variable that hands an env only the hex sha256 of that token, which those routes then take in its place: a +#: process that can read the env's environment learns nothing it could send. Set, it is checked and the token isn't. +CONTROL_TOKEN_SHA256_ENV = "AGENTENV_CONTROL_TOKEN_SHA256" #: The header a control token travels in where it must not collide with a front door's own ``Authorization``. CONTROL_TOKEN_HEADER = "AgentEnv-Control-Token" diff --git a/packages/agentenv-protocol/tests/test_computer_driver.py b/packages/agentenv-protocol/tests/test_computer_driver.py index 680c738f3..8bc1dfe06 100644 --- a/packages/agentenv-protocol/tests/test_computer_driver.py +++ b/packages/agentenv-protocol/tests/test_computer_driver.py @@ -192,6 +192,7 @@ async def test_the_card_declares_the_contract_the_driver_implements(): assert computer["buttons"] == ["left", "right", "middle"] and computer["max_click_count"] == 3 assert computer["keys"] == "all" and computer["platform"] == LINUX.as_dict() and computer["delivery"] == "foreground" assert computer["default_data_paths"] == ["Desktop", "Documents", "Downloads"] and computer["screen"] == "desktop" + assert computer["control_token"] == "sha256" # agent-env boots it with the token's digest, not the token assert "methods" not in computer and extensions["urn:agentenv:skill/v1"]["params"]["methods"]["get"]["method"] == "GET" assert extensions["urn:agentenv:computer-pointer/v1"]["params"]["buttons"] == ["left", "right", "middle"] assert set(extensions["urn:agentenv:computer-keyboard/v1"]["params"]["methods"]) == {"get", "set"} diff --git a/packages/agentenv-protocol/tests/test_control_token.py b/packages/agentenv-protocol/tests/test_control_token.py index 88f42ffbd..e79dd397d 100644 --- a/packages/agentenv-protocol/tests/test_control_token.py +++ b/packages/agentenv-protocol/tests/test_control_token.py @@ -5,6 +5,7 @@ from __future__ import annotations import contextlib +import hashlib import anyio import httpx @@ -18,6 +19,7 @@ from agentenv_protocol import ( # noqa: E402 CONTROL_TOKEN_ENV, + CONTROL_TOKEN_SHA256_ENV, RPC_PATH, WELL_KNOWN_PATH, AgentEnvEnvironment, @@ -96,9 +98,42 @@ async def test_with_a_token_every_framework_only_route_refuses_a_call_without_it assert card.status_code == 200 and tools == ["read"] +@pytest.mark.asyncio +@pytest.mark.parametrize("plain", [None, "a-different-token"], ids=["alone", "beside-a-token"]) +async def test_given_only_the_tokens_sha256_every_framework_only_route_takes_the_token_itself(monkeypatch, plain): + """An env handed the token's sha256 holds nothing a caller could send: the digest itself is refused, the token + answers, and a plain token beside the digest is ignored.""" + digest = hashlib.sha256(b"s3cret").hexdigest() + monkeypatch.setenv(CONTROL_TOKEN_SHA256_ENV, digest) + if plain is None: + monkeypatch.delenv(CONTROL_TOKEN_ENV, raising=False) + else: + monkeypatch.setenv(CONTROL_TOKEN_ENV, plain) + + with anyio.fail_after(30): + async with _served() as (rest, _): + without = await _calls(rest, {}) + the_digest = await _calls(rest, client.control_headers(digest)) + not_bearer = await _calls(rest, {"Authorization": "s3cret"}) + beside = await _calls(rest, client.control_headers(plain)) if plain else [401, 401, 401] + right = await _calls(rest, client.control_headers("s3cret")) + + assert without == the_digest == not_bearer == beside == [401, 401, 401] + assert right == [200, 200, 200] + + +def test_a_grant_for_a_route_under_an_address_wins_over_the_address(): + gateway = "http://gw:18765" + with client.authorized({gateway: client.control_headers("env"), f"{gateway}/svc/desk": client.control_headers("desk")}): + sent = [client.request_headers(url) for url in (f"{gateway}/svc/desk/agentenv", f"{gateway}/svc/desk", + f"{gateway}/svc/desk-2/agentenv", f"{gateway}/state")] + assert sent == [{"Authorization": "Bearer desk"}] * 2 + [{"Authorization": "Bearer env"}] * 2 + + @pytest.mark.asyncio async def test_without_a_token_every_route_is_open(monkeypatch): monkeypatch.delenv(CONTROL_TOKEN_ENV, raising=False) + monkeypatch.delenv(CONTROL_TOKEN_SHA256_ENV, raising=False) with anyio.fail_after(30): async with _served() as (rest, _): diff --git a/src/agent_env/env/env.py b/src/agent_env/env/env.py index 831f9c691..2df4f70ad 100644 --- a/src/agent_env/env/env.py +++ b/src/agent_env/env/env.py @@ -119,10 +119,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[Optional[str], dict[str, str]]: + """The addresses under the env's that take a control token, each with the headers that carry it + (``protocol_v1.authorized``): the env's own address, with ``control_headers``.""" + return {self.environment_url: self.control_headers} + 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 a control token: the headers of the longest of ``control_grants`` that + ``url`` 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.""" @@ -167,10 +173,11 @@ 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: + if card is None or not self.environment_url or (op := protocol_v1.find_extension_method(card, uri, method)) is None: raise EnvCapabilityUnsupported(uri, method, self.env_id, self.instance_id, environment_name) - return await protocol_v1.invoke_extension(self.environment_url, card, uri, params, timeout, method=method, - headers=self.control_headers) + return await protocol_v1.invoke_extension( + self.environment_url, card, uri, params, timeout, method=method, + headers=self.control_headers_for(f"{self.environment_url.rstrip('/')}{op.get('endpoint') or ''}")) 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 @@ -247,6 +254,15 @@ class DeployedGatewayEnv(DeployedSandboxEnv): # the default stack, which has the VM to itself. stack_layout: Optional[dict] = None + @property + def control_grants(self) -> dict[Optional[str], dict[str, str]]: + """The gateway's address with its control token, and under it each child's /svc route with the child's own, + which reaches the child through any gateway, one that would put a child's in place of its own or not.""" + return {**super().control_grants, + **{f"{self.environment_url.rstrip('/')}/svc/{name}": protocol_v1.control_headers(token) + for name, record in self.child_envs.items() + if self.environment_url and (token := (record or {}).get("control_token"))}} + @classmethod def _fields_from(cls, data: dict) -> dict: return { diff --git a/src/agent_env/env/envs/_multi_computers.py b/src/agent_env/env/envs/_multi_computers.py index 86f17f731..463f8b979 100644 --- a/src/agent_env/env/envs/_multi_computers.py +++ b/src/agent_env/env/envs/_multi_computers.py @@ -98,7 +98,7 @@ def routes_later(entry: Optional[dict]) -> bool: def _clock_read_token(record: DeployedEnv) -> str | None: """The read token a computer's clock watch carries when its card says it's a clock follower (``clock/v1``'s - ``sync_time``): for now its control token, which a token of its own can replace without the gateway knowing.""" + ``sync_time``): its own control token, which the gateway takes from it only at the watch.""" return record.control_token if computer_clock.follows(record) else None @@ -193,10 +193,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], Optional[str]], Awaitable[list[ExternalChild]]]: + ) -> Callable[[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 ``_``, 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 + name and ``_``, its framework-only routes taking a token of its own, which the gateway sends it in place of the + gateway's own on its /svc routes, so nothing in a computer holds the gateway's, 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.""" @@ -208,14 +208,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], control_token: Optional[str]) -> list[ExternalChild]: + async def deploy(reach: 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, control_token=control_token, + reach=reach or "", sites_later=env.environment_name in self._routes, **({"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) @@ -223,8 +223,8 @@ async def deploy(reach: Optional[str], control_token: Optional[str]) -> list[Ext for error in failed[1:]: logger.warning(f"multi env '{self._owner}': another computer failed to deploy too: {error!r}") raise failed[0] - return [ExternalChild(env.environment_name, record.mcp_url, record.environment_url, _clock_read_token(record)) - for env, record in zip(self.every, results)] + return [ExternalChild(env.environment_name, record.mcp_url, record.environment_url, _clock_read_token(record), + record.control_token) for env, record in zip(self.every, results)] return deploy async def finish(self, deployed: DeployedEnv) -> None: diff --git a/src/agent_env/env/envs/computer/env.py b/src/agent_env/env/envs/computer/env.py index dd79b4c67..972fe9542 100644 --- a/src/agent_env/env/envs/computer/env.py +++ b/src/agent_env/env/envs/computer/env.py @@ -301,19 +301,16 @@ 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, ...] = (), - control_token: Optional[str] = None) -> DeployedEnv: + sites_later: bool = False, live_hosts: tuple[str, ...] = ()) -> 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, 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.""" + it routes the sites ``env_params.site_routing`` reaches when ``route_sites`` gives them.""" 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), control_token=control_token) + live_hosts=tuple(live_hosts)) 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/envs/computer/utils/boot.py b/src/agent_env/env/envs/computer/utils/boot.py index 37f0188a5..b145805ef 100644 --- a/src/agent_env/env/envs/computer/utils/boot.py +++ b/src/agent_env/env/envs/computer/utils/boot.py @@ -6,6 +6,7 @@ import asyncio import contextlib +import hashlib import json import logging import re @@ -15,11 +16,12 @@ from dataclasses import dataclass from typing import TYPE_CHECKING, Any, Optional -from agentenv_protocol import CONTROL_TOKEN_ENV +from agentenv_protocol import CONTROL_TOKEN_ENV, CONTROL_TOKEN_SHA256_ENV from agentenv_protocol import client as protocol_v1 from agentenv_protocol.computer import APP_SETTINGS_ENV, COMPUTER_READY, SETTINGS_ENV, TOOL_PREFIX_ENV from agentenv_protocol.computer.app import COMPUTER_APP from agentenv_protocol.computer.apps import ANSWER_TIMEOUT_S +from agentenv_protocol.computer.card import COMPUTER, CONTROL_TOKEN_SHA256 from agentenv_protocol.computer.platform import entry_for from agent_env.config import get_config @@ -168,10 +170,19 @@ def control_token() -> str: return secrets.token_urlsafe(CONTROL_TOKEN_BYTES) -def control_environment(token: Optional[str]) -> dict[str, str]: - """What hands a computer its control ``token`` in its boot environment; nothing without one, as for a computer an - older agent-env booted.""" - return {CONTROL_TOKEN_ENV: token} if token else {} +def control_environment(token: Optional[str], card: Optional[dict] = None) -> dict[str, str]: + """What hands a computer its control ``token`` in its boot environment, by what ``card``, its driver's as a probe + read it, says the driver takes: only the token's sha256 for a driver that takes that (computer/v1's + ``control_token``), so nothing in the computer holds the token; the token for one an older protocol built; both for + a driver no card describes yet, as on its probe, where each takes what it knows. Nothing without a token, as for a + computer an older agent-env booted.""" + if not token: + return {} + verifier = {CONTROL_TOKEN_SHA256_ENV: hashlib.sha256(token.encode()).hexdigest()} + if card is None: + return {CONTROL_TOKEN_ENV: token, **verifier} + takes = protocol_v1.extension_params(card, COMPUTER).get("control_token") == CONTROL_TOKEN_SHA256 + return verifier if takes else {CONTROL_TOKEN_ENV: token} def shm_environment(form: str, os_type: str, shm_mb: Optional[int]) -> dict[str, str]: @@ -194,15 +205,17 @@ def shm_kwargs(sandbox_provider: SandboxProvider, shm_mb: Optional[int]) -> dict async def boot(sandbox_provider: SandboxProvider, *, image: str, port: int, environment: dict[str, str], token: str, + card: Optional[dict] = None, network_policy: Optional[NetworkPolicy], timeout: int, attribution: Optional[Attribution], disk_size_gb: float = 10, cpu: Optional[float] = None, memory_mb: Optional[int] = None, ready_s: float = READY_TIMEOUT_S, form: str = "container", held: bool = False, platform: str = "linux", shm_mb: Optional[int] = None) -> Booted: - """``image``, of ``form``, booted with ``environment`` and its control ``token`` on ``sandbox_provider``, which the + """``image``, of ``form``, booted with ``environment`` and its control ``token``, as ``card``, its driver's, says it + takes it (``control_environment``), on ``sandbox_provider``, which the caller chose to run its arch natively, its driver's ``port`` reached on the sandbox, its ``/dev/shm`` ``shm_mb`` MiB where the sandbox can size it, once the driver, asked with that token, says the computer is ready, or with ``held``, its boot apps' launch held, once it answers (``ready``); a boot that fails is torn down.""" - environment = {**environment, **control_environment(token), **shm_environment(form, platform.partition("/")[0], shm_mb)} + environment = {**environment, **control_environment(token, card), **shm_environment(form, platform.partition("/")[0], shm_mb)} if form == "vm_bundle": sandbox = await sandbox_provider.create_vm( image=image, env=environment, exposed_ports=[port], network_policy=network_policy, diff --git a/src/agent_env/env/gateway/__init__.py b/src/agent_env/env/gateway/__init__.py index 33a49e3df..b4935cb84 100644 --- a/src/agent_env/env/gateway/__init__.py +++ b/src/agent_env/env/gateway/__init__.py @@ -30,13 +30,15 @@ class InternalMCPServer: @dataclass(frozen=True) class ExternalChild: """A child env on a sandbox of its own, which the gateway fronts as it does an MCP server: its name, and its MCP - endpoint and base URL as the process holding it reaches them. A child that is a clock follower has the read token its - clock watch carries, and the gateway's clock writes wait for it.""" + endpoint and base URL as the process holding it reaches them, and the control token its framework-only routes take, + which the gateway sends it in place of its own. A child that is a clock follower has the read token its clock watch + carries, and the gateway's clock writes wait for it.""" name: str mcp_url: str base_url: str clock_read_token: str | None = None + control_token: str | None = None __all__ = [ diff --git a/src/agent_env/env/gateway/constants.py b/src/agent_env/env/gateway/constants.py index 35e4d6957..abde3c045 100644 --- a/src/agent_env/env/gateway/constants.py +++ b/src/agent_env/env/gateway/constants.py @@ -72,8 +72,13 @@ 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. +# The children the gateway passes its control token on to, comma-separated: a multi env's computers that an older +# agent-env booted with it. Delete once no deploy sets it. CONTROL_TOKEN_CHILDREN_ENV = "CONTROL_TOKEN_CHILDREN" +# Each child's own control token, as `name=token`, comma-separated: a multi env's computers, each booted with a token +# of its own, which the gateway puts in place of its own on that child's /svc routes; TOKEN in the name keeps it out of +# logged compose files. +CHILD_CONTROL_TOKENS_ENV = "CHILD_CONTROL_TOKENS" # The gateway's computers, comma-separated: a multi env's, each a child on a sandbox of its own, whose input calls set # who drives it, the role its browser's requests take. COMPUTERS_ENV = "COMPUTERS" diff --git a/src/agent_env/env/gateway/entrypoint.py b/src/agent_env/env/gateway/entrypoint.py index e2b402cbc..d13934fdd 100644 --- a/src/agent_env/env/gateway/entrypoint.py +++ b/src/agent_env/env/gateway/entrypoint.py @@ -9,7 +9,7 @@ from . import AGENT_ENV_GATEWAY_MCP_PORT, GatewayMode, InternalMCPServer from .console_session import frame_ancestor_problem -from .constants import (CLOCK_FOLLOWERS_ENV, COMPUTERS_ENV, CONSOLE_FRAME_ANCESTORS_ENV, CONSOLE_URLS_ENV, CONTROL_TOKEN_CHILDREN_ENV, CONTROL_TOKEN_ENV, DEFAULT_MCP_SERVER_NAME, +from .constants import (CHILD_CONTROL_TOKENS_ENV, CLOCK_FOLLOWERS_ENV, COMPUTERS_ENV, CONSOLE_FRAME_ANCESTORS_ENV, CONSOLE_URLS_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 @@ -199,17 +199,18 @@ def parse_frame_ancestors(spec: str) -> tuple[str, ...]: return origins -def parse_clock_followers(spec: str) -> dict[str, str]: - """``CLOCK_FOLLOWER_TOKENS``: each computer that follows the clock as ``name=read token``, comma-separated.""" - followers: dict[str, str] = {} +def parse_clock_followers(spec: str, variable: str = CLOCK_FOLLOWERS_ENV) -> dict[str, str]: + """``CLOCK_FOLLOWER_TOKENS``, each computer that follows the clock as ``name=read token``, or another ``variable`` + of the same form, ``CHILD_CONTROL_TOKENS``; comma-separated.""" + tokens: dict[str, str] = {} for entry in filter(None, (part.strip() for part in spec.split(","))): name, _, token = (part.strip() for part in entry.partition("=")) if not name or not token: - raise ValueError(f"invalid {CLOCK_FOLLOWERS_ENV} entry for {name or '?'!r}: expected 'name=read token'") - if name in followers: - raise ValueError(f"{CLOCK_FOLLOWERS_ENV} names {name!r} twice") - followers[name] = token - return followers + raise ValueError(f"invalid {variable} entry for {name or '?'!r}: expected 'name=token'") + if name in tokens: + raise ValueError(f"{variable} names {name!r} twice") + tokens[name] = token + return tokens def parse_site_names(env_str: str) -> dict[str, tuple[str, ...]]: @@ -256,6 +257,8 @@ def parse_site_names(env_str: str) -> dict[str, tuple[str, ...]]: 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()], + child_control_tokens=parse_clock_followers(os.environ.get(CHILD_CONTROL_TOKENS_ENV, ""), + CHILD_CONTROL_TOKENS_ENV), computers=[name.strip() for name in os.environ.get(COMPUTERS_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, "")), diff --git a/src/agent_env/env/gateway/gateway.py b/src/agent_env/env/gateway/gateway.py index ae2af8ed6..287982c3e 100644 --- a/src/agent_env/env/gateway/gateway.py +++ b/src/agent_env/env/gateway/gateway.py @@ -179,6 +179,7 @@ def __init__( service_db_url: str | None = None, control_token: str | None = None, control_token_children: Iterable[str] = (), + child_control_tokens: Mapping[str, str] | None = None, computers: Iterable[str] = (), provider_headers: Iterable[str] = (), clock_followers: Mapping[str, str] | None = None, @@ -192,8 +193,11 @@ 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``. `control_token_children` are the children its - /svc routes pass its control token on to, a multi env's computers, which take it. `computers` are its children + computer opens it, and the others at their ``website_urls``. `child_control_tokens` are its children's own + control tokens, a multi env's computers', by name: a request to one's /svc routes with the gateway's token goes + on with the child's instead, and a child's token goes on only to that child and to the clock watch, where the + child sends it as its read token. `control_token_children` are the children its /svc routes pass its own token on + to unchanged, the computers an older agent-env booted with it. `computers` are its children that are computers, a multi env's: an input call to one's tools makes its caller the role driving it, which the requests its browser sends take. `console_urls` are the env's SQL consoles by key, each served at /svc// only with the control token or, on pgweb, a session minted from it, and not at all without one; @@ -221,6 +225,7 @@ def __init__( 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._child_bearers = {name: f"Bearer {token}".encode() for name, token in (child_control_tokens or {}).items()} self._consoles = dict(console_urls or {}) if control_token else {} self._console_session = ConsoleSession(control_token) if PGWEB_CONSOLE in self._consoles else None self._console_csp = " ".join(["frame-ancestors 'self'", *console_frame_ancestors]).encode() @@ -608,13 +613,21 @@ def _server_config(self) -> uvicorn.Config: # 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 + def _passed_authorization(self, path: str, value: bytes) -> bytes | None: + """The ``Authorization`` a request to ``path`` that carries ``value`` goes on with, None for none. The gateway's + token goes on as a child's own token to that child's /svc routes, as itself to the clock watch, which reads it, + and to an older agent-env's computers (``control_token_children``), and nowhere else. A child's token goes on + only to that child's /svc routes and to the clock watch, where the child sends it as its read token. Any other + value goes on as it came.""" child = path.removeprefix("/svc/").split("/", 1)[0] if path.startswith("/svc/") else None - return child in self._control_token_children + if self._control_bearer is not None and hmac.compare_digest(value, self._control_bearer): + if child in self._child_bearers: + return self._child_bearers[child] + return value if path == CLOCK_WATCH_PATH or child in self._control_token_children else None + owner = next((name for name, bearer in self._child_bearers.items() if hmac.compare_digest(value, bearer)), None) + if owner is None: + return value + return value if path == CLOCK_WATCH_PATH or child == owner else None def _asgi_app(self): """The served app: FastMCP's Starlette app with the request's caller bound around it, the control routes behind @@ -625,30 +638,30 @@ def _asgi_app(self): inner.router.routes.append(WebSocketRoute(BROWSER_ROUTE, self._browsers.relay)) async def app(scope, receive, send): - if self._control_bearer and scope["type"] in ("http", "websocket"): + if (self._control_bearer or self._child_bearers) and scope["type"] in ("http", "websocket"): headers = scope.get("headers", ()) pgweb = scope["type"] == "http" and self._console_session is not None and self._is_pgweb(scope) link = self._console_session.opening_link(scope) if pgweb else None - bearer = hmac.compare_digest(dict(headers).get(b"authorization", b""), self._control_bearer) + bearer = self._control_bearer is not None and hmac.compare_digest( + dict(headers).get(b"authorization", b""), self._control_bearer) session = pgweb and not bearer and self._console_session.admits(scope) if pgweb: send = self._pgweb_send(send, renew=session and self._console_session.renews(scope)) if link is not None and self._console_session.opens(link): await self._console_opened(scope)(scope, receive, send) return - if scope["type"] == "http" and self._takes_control_token(scope) and not bearer and not session: + if self._control_bearer and scope["type"] == "http" and self._takes_control_token(scope) and \ + not bearer and not session: reason, error = (("its pgweb link is spent, expired or not this env's", "this link is not valid for this env") if link is not None else ("it takes the env's control token", "this route takes the env's control token")) logger.warning("refused %s %s: %s", scope["method"], scope["path"], reason) await self._json_response({"ok": False, "error": error}, 401)(scope, receive, send) return - # 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"]): - headers = [(name, value) for name, value in headers if not ( - name == b"authorization" and hmac.compare_digest(value, self._control_bearer))] - scope = {**scope, "headers": without_session_cookie(headers)} + passed = [(name, self._passed_authorization(scope["path"], value) if name == b"authorization" else value) + for name, value in headers] + scope = {**scope, "headers": without_session_cookie( + [(name, value) for name, value in passed if value is not None])} 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 e0467eb0c..5d9d1ccce 100644 --- a/src/agent_env/providers/env_providers/env_computer_provider.py +++ b/src/agent_env/providers/env_providers/env_computer_provider.py @@ -85,7 +85,6 @@ 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 @@ -93,8 +92,7 @@ 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. With ``control_token``, its - framework-only routes take that token (a multi env's own) rather than one of the computer's own.""" + once its driver answers; ``route_sites`` routes them and finishes its boot.""" from agent_env.env.envs.computer.env import ComputerEnv if not isinstance(env, ComputerEnv): @@ -127,7 +125,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), control_token=control_token) + live_hosts=tuple(live_hosts)) return await self._run(sandbox_provider, env.id, attempt) async def route_sites(self, env: ComputerEnv, record: DeployedSandboxEnv, sites: list[dict]) -> None: @@ -155,8 +153,7 @@ 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, ...] = (), - control_token: Optional[str] = None) -> DeployedSandboxEnv: + sites_later: bool = False, live_hosts: tuple[str, ...] = ()) -> 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 @@ -177,7 +174,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 or new_control_token() + computer, name, token = env.computer_artifact(), env.environment_name, 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)) @@ -186,6 +183,7 @@ async def _boot(self, env: ComputerEnv, builds: list[tuple[str, str, dict]], par shm_mb = env.shm_mb() booted = await boot( sandbox_provider, image=build["image"], port=env.driver.port, network_policy=policy, token=token, + card=build.get("card"), environment=_environment(env, computer, values, params, tool_prefix, sites_later=sites_later), timeout=ttl_seconds, attribution=attribution, @@ -235,7 +233,7 @@ async def reboot(self, env: ComputerEnv, deployed: DeployedSandboxEnv) -> None: sandbox = await sandbox_provider.get_sandbox(deployed.sandbox_id) shm_mb = record.get("shm_mb") environment = {**_environment(env, computer, values, params, record.get("tool_prefix", "")), - **control_environment(deployed.control_token), + **control_environment(deployed.control_token, deployed.environment_card), **shm_environment(record.get("form", "container"), env.computer.os.type, shm_mb)} try: if record.get("form") in ("disk", "vm_bundle"): 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 b05f9d2a5..381c29870 100644 --- a/src/agent_env/providers/env_providers/env_gateway_provider.py +++ b/src/agent_env/providers/env_providers/env_gateway_provider.py @@ -41,7 +41,7 @@ COMPUTERS_ENV, CONSOLE_FRAME_ANCESTORS_ENV, CONSOLE_URLS_ENV, - CONTROL_TOKEN_CHILDREN_ENV, + CHILD_CONTROL_TOKENS_ENV, DEFAULT_MCP_SERVER_NAME, GATEWAY_PROVIDER_HEADERS_ENV, STATE_TOOL_NAME_CLASHES_KEY, @@ -577,7 +577,7 @@ def create_docker_compose( 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()) + for key, value in child_control_tokens_environment(external_children).items()) gateway_env.extend(f" - {key}={value}" for key, value in computers_environment(external_children).items()) if provider_headers := sandbox_request_header_names(): gateway_env.append(f" - {GATEWAY_PROVIDER_HEADERS_ENV}={','.join(provider_headers)}") @@ -690,7 +690,7 @@ async def deploy( attribution: Optional[Attribution] = None, artifact_id: str | None = None, artifact_version: int | None = None, - children: "Callable[[Optional[str], Optional[str]], Awaitable[list[ExternalChild]]] | None" = None, + children: "Callable[[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. @@ -842,7 +842,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], Optional[str]], Awaitable[list[ExternalChild]]] | None" = None, + children: "Callable[[Optional[str]], Awaitable[list[ExternalChild]]] | None" = None, website_browser: "MCPServerEnv | None | object" = _THE_RUNS, control_token: str | None = None, ) -> DeployedGateway: @@ -971,7 +971,7 @@ 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(tunnel_url(gateway_port), control_token), + children(tunnel_url(gateway_port)), return_exceptions=True) for result in (up, started): if isinstance(result, BaseException): @@ -1068,7 +1068,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], Optional[str]], Awaitable[list[ExternalChild]]] | None" = None, + children: "Callable[[Optional[str]], Awaitable[list[ExternalChild]]] | None" = None, control_token: str | None = None, ) -> DeployedGateway: from agent_env.env.env import Env @@ -1125,7 +1125,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, control_token)] if children is not None else [] + child_coros = [children(None)] if children is not None else [] all_results = await asyncio.gather(*mcp_coros, *aux_coros, *child_coros, return_exceptions=True) external: list[ExternalChild] = [] @@ -1179,7 +1179,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), + **child_control_tokens_environment(external), **computers_environment(external), **({GATEWAY_PROVIDER_HEADERS_ENV: ",".join(names)} if (names := sandbox_request_header_names()) else {}), } @@ -1562,7 +1562,7 @@ async def _deploy_gateway( mcp_server_name: str | None = None, control_token: str | None = None, attribution: Optional[Attribution] = None, - children: "Callable[[Optional[str], Optional[str]], Awaitable[list[ExternalChild]]] | None" = None, + children: "Callable[[Optional[str]], Awaitable[list[ExternalChild]]] | None" = None, website_browser: "MCPServerEnv | None | object" = _THE_RUNS, stack_layout: StackLayout = DEFAULT_STACK_LAYOUT, ) -> DeployedGateway: @@ -1888,11 +1888,10 @@ 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 child_control_tokens_environment(children: Iterable[ExternalChild]) -> dict[str, str]: + """Each child's own control token, by name, which the gateway sends it in place of its own on its /svc routes.""" + tokens = ",".join(f"{child.name}={child.control_token}" for child in children if child.control_token) + return {CHILD_CONTROL_TOKENS_ENV: tokens} if tokens else {} def computers_environment(children: Iterable[ExternalChild]) -> dict[str, str]: diff --git a/src/agent_env/task/task.py b/src/agent_env/task/task.py index 506886890..2836eb4e9 100644 --- a/src/agent_env/task/task.py +++ b/src/agent_env/task/task.py @@ -708,7 +708,7 @@ async def _run_one(step: TaskStep, idx: int, dispatch_epoch: int) -> None: # This step's own asyncio task, so a sibling dispatched alongside it doesn't see it. ATTEMPT_EPOCH.set(dispatch_epoch) try: - with protocol_v1.authorized({d.environment_url: d.control_headers for d in context.deployed_envs}): + with protocol_v1.authorized({url: sent for d in context.deployed_envs for url, sent in d.control_grants.items()}): 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 a9f4a0d0f..9a150dd75 100644 --- a/tst/integration/computer/multi_env_computers_test.py +++ b/tst/integration/computer/multi_env_computers_test.py @@ -230,7 +230,8 @@ 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 + # Each computer holds a token of its own, never the multi env's, which opens the consoles and guarded routes. + assert computer["control_token"] and computer["control_token"] != deployed.control_token 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_computer_env.py b/tst/unit/env/envs/test_computer_env.py index de6aca215..8d776525e 100644 --- a/tst/unit/env/envs/test_computer_env.py +++ b/tst/unit/env/envs/test_computer_env.py @@ -21,7 +21,7 @@ import httpx import pytest -from agentenv_protocol import CONTROL_TOKEN_ENV +from agentenv_protocol import CONTROL_TOKEN_ENV, CONTROL_TOKEN_SHA256_ENV from agentenv_protocol.computer import COMPUTER_DISPLAY, COMPUTER_READY, COMPUTER_RECORDING, TOOL_PREFIX_ENV from agentenv_protocol.computer.app import COMPUTER_APP from agentenv_protocol.computer.app_runtime import HOLD_BOOT_LAUNCH_ENV @@ -1765,7 +1765,8 @@ async def test_a_boot_hands_the_computer_its_token_and_one_never_ready_takes_its environment={"ENVIRONMENT_NAME": "desk"}, token="t0ken", network_policy=None, timeout=60, attribution=None) - assert create.await_args.kwargs["env"] == {"ENVIRONMENT_NAME": "desk", CONTROL_TOKEN_ENV: "t0ken"} + assert create.await_args.kwargs["env"] == {"ENVIRONMENT_NAME": "desk", CONTROL_TOKEN_ENV: "t0ken", + CONTROL_TOKEN_SHA256_ENV: hashlib.sha256(b"t0ken").hexdigest()} assert boot.ready.await_args.args[2] == "t0ken" and boot.ready.await_args.kwargs["sandbox"] is sandbox sandbox.terminate.assert_awaited_once() assert local_sandbox.LocalSandbox.find_work_dir("local-unready") is None @@ -2520,3 +2521,24 @@ def test_a_required_setting_may_be_left_to_each_deploy_and_one_an_env_gives_sati (missing,) = DeployEnvTaskStep(id="d", version=None, env_id=left.id).preflight() assert "env_params.app_settings.mail: 'signature' is a required property" in missing assert DeployEnvTaskStep(id="d", version=None, env_id=given.id).preflight() == [] + + + +def _driver_card(control_token: str | None) -> dict: + params = {"control_token": control_token} if control_token else {} + return {"name": "desk", "capabilities": {"extensions": [{"uri": "urn:agentenv:computer/v1", "params": params}]}} + + +@pytest.mark.parametrize("card, held", [ + (_driver_card("sha256"), {CONTROL_TOKEN_SHA256_ENV}), + (_driver_card(None), {CONTROL_TOKEN_ENV}), + (None, {CONTROL_TOKEN_ENV, CONTROL_TOKEN_SHA256_ENV})], ids=["takes-a-digest", "older-driver", "on-its-probe"]) +def test_a_computer_whose_driver_takes_a_digest_boots_holding_no_token(card, held): + """A driver whose probed card says it takes the token's sha256 boots with only that, so no process in the computer + holds a token it could send; an older driver still gets the token.""" + environment = boot.control_environment("t0ken", card) + assert set(environment) == held + assert environment.get(CONTROL_TOKEN_SHA256_ENV, hashlib.sha256(b"t0ken").hexdigest()) == \ + hashlib.sha256(b"t0ken").hexdigest() + assert ("t0ken" in environment.values()) is (CONTROL_TOKEN_ENV in held) + assert boot.control_environment(None, card) == {} diff --git a/tst/unit/env/envs/test_multi_env_computers.py b/tst/unit/env/envs/test_multi_env_computers.py index 817dd1c63..d286b279f 100644 --- a/tst/unit/env/envs/test_multi_env_computers.py +++ b/tst/unit/env/envs/test_multi_env_computers.py @@ -38,7 +38,7 @@ from tst.util.sandbox_providers import mock_provider GATEWAY = "https://gw.example" -#: The gateway's control token, which it hands the computers it fronts. +#: The gateway's control token, which no computer it fronts is given. GATEWAY_TOKEN = "the-gateways" @@ -292,7 +292,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, GATEWAY_TOKEN) if children else None) + made.started.append(await children(GATEWAY) 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", @@ -308,8 +308,8 @@ async def close(self): @pytest.mark.asyncio -async def test_deploy_hands_the_gateway_each_computer_deployed_under_its_name_with_its_token_and_records_it(gateway, - providers): +async def test_deploy_hands_the_gateway_each_computer_deployed_under_its_name_with_its_own_token_and_records_it( + gateway, providers): desktop, laptop = FakeComputer("desktop"), FakeComputer("laptop") attribution = {"project_id": "6a6d2e30b2710a6cf93a6430"} @@ -318,12 +318,14 @@ async def test_deploy_hands_the_gateway_each_computer_deployed_under_its_name_wi 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, "control_token": GATEWAY_TOKEN, "sandbox_type": "modal", "cpu": 4, + "sites_later": False, "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, "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")]] + "sites_later": False, "sandbox_type": "modal_vm"}] + assert gateway.started == [[ + ExternalChild("desktop", "https://desktop.example/mcp", "https://desktop.example", None, "token-desktop"), + ExternalChild("laptop", "https://laptop.example/mcp", "https://laptop.example", None, "token-laptop")]] + assert GATEWAY_TOKEN not in {child.control_token for child in gateway.started[0]} assert deployed.child_envs == {name: dataclasses.asdict(_record(name)) for name in ("desktop", "laptop")} assert DeployedEnv.from_dict(dataclasses.asdict(deployed)).child_envs == deployed.child_envs assert deployed.sandbox_ids == {"gateway_server": "gw", "modal_vm": {"desktop": "sb-desktop", "laptop": "sb-laptop"}} @@ -935,13 +937,14 @@ 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, "control_token": GATEWAY_TOKEN, + "reach": GATEWAY, "sites_later": True, "live_hosts": ("github.test", "api.github.test"), "sandbox_type": "modal", "cpu": 2, "memory_mb": 4096, "env_params": {"site_routing": True}}] assert desktop.deploys[0]["sites_later"] is False - assert gateway.started == [[ExternalChild("desktop", "https://desktop.example/mcp", "https://desktop.example"), - ExternalChild("chromium", "https://chromium.example/mcp", "https://chromium.example")]] + assert gateway.started == [[ + ExternalChild("desktop", "https://desktop.example/mcp", "https://desktop.example", None, "token-desktop"), + ExternalChild("chromium", "https://chromium.example/mcp", "https://chromium.example", None, "token-chromium")]] assert set(deployed.child_envs) == {"desktop", "chromium"} assert chromium.log[-1] == ("routed", "chromium", ["shop"]) diff --git a/tst/unit/env/gateway/clock_watch_test.py b/tst/unit/env/gateway/clock_watch_test.py index e18caa897..4f286ddd3 100644 --- a/tst/unit/env/gateway/clock_watch_test.py +++ b/tst/unit/env/gateway/clock_watch_test.py @@ -33,9 +33,10 @@ def gateway(tmp_path, monkeypatch): monkeypatch.setattr(ClockFollowers, "WATCH_S", HELD_S) made = [] - def make(followers=TOKENS, control_token=None) -> Gateway: + def make(followers=TOKENS, control_token=None, child_control_tokens=None) -> Gateway: made.append(Gateway(host="127.0.0.1", port=0, server_name="unit", internal_mcp_servers=[], - clock_followers=followers, control_token=control_token)) + clock_followers=followers, control_token=control_token, + child_control_tokens=child_control_tokens)) return made[-1] yield make @@ -201,6 +202,21 @@ async def test_a_computer_whose_token_is_the_gateways_own_acknowledges_with_it(g assert answer.status_code == 200, answer.json() +@pytest.mark.asyncio +async def test_a_computer_acknowledges_with_its_own_token(gateway): + """A multi env's computer boots with a token of its own, which its watch carries as its read token.""" + gw = gateway({"desktop": "the-desktops"}, control_token="the-gateways", + child_control_tokens={"desktop": "the-desktops"}) + async with _client(gw) as client: + follower = asyncio.create_task(_follow(client, "desktop", "the-desktops")) + 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): @@ -367,7 +383,7 @@ async def test_a_hundred_advances_are_each_acknowledged_in_order(gateway): def test_the_gateway_reads_its_declared_computers_from_its_environment(): assert parse_clock_followers("") == {} assert parse_clock_followers(" desktop=read-d ,laptop=read-l,") == {"desktop": "read-d", "laptop": "read-l"} - for spec, fragment in (("desktop", "expected 'name=read token'"), ("=tok", "expected"), ("desktop=", "expected"), + for spec, fragment in (("desktop", "expected 'name=token'"), ("=tok", "expected"), ("desktop=", "expected"), ("desktop=a,desktop=b", "twice")): with pytest.raises(ValueError, match=fragment): parse_clock_followers(spec) diff --git a/tst/unit/env/gateway/control_token_test.py b/tst/unit/env/gateway/control_token_test.py index 6a9a22771..975befbe2 100644 --- a/tst/unit/env/gateway/control_token_test.py +++ b/tst/unit/env/gateway/control_token_test.py @@ -16,6 +16,9 @@ from agent_env.env.gateway.gateway import Gateway TOKEN = "s3cret" +# A multi env's computers' own tokens, by name, as the gateway is started with them (CHILD_CONTROL_TOKENS). +DESK, LAPTOP = "the-desks-own", "the-laptops-own" +COMPUTERS = {"desk": DESK, "laptop": LAPTOP} CONTROL = { "/tools/disable": "POST", "/tools/enable": "POST", "/triggers/register": "POST", "/triggers/remove": "POST", "/triggers/clear": "POST", @@ -104,17 +107,19 @@ 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(OPEN)) +async def test_a_gateway_started_without_a_token_lets_a_childs_through_nowhere_but_the_child(path): + gw = Gateway(host="127.0.0.1", port=0, server_name="unit", internal_mcp_servers=[], control_token=None, + child_control_tokens={"desk": DESK}) + + @gw._mcp.custom_route("/echo", methods=["GET"]) + async def echo(request): + return JSONResponse({"authorization": request.headers.get("authorization")}) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=gw._asgi_app()), base_url="http://gateway") as client: + response = await client.get("/echo", headers={"Authorization": f"Bearer {DESK}"}) + assert response.json() == {"authorization": None} @pytest.mark.asyncio @pytest.mark.parametrize("path", sorted(CONTROL)) @@ -129,12 +134,14 @@ class _Backing: def __init__(self, monkeypatch): self.paths: list[str] = [] + self.hosts: list[str] = [] self.authorization: list[str | None] = [] transport = httpx.MockTransport(self._answer) monkeypatch.setattr(rest_proxy_module.httpx, "AsyncClient", lambda **kw: _RealAsyncClient(transport=transport, **kw)) def _answer(self, request: httpx.Request) -> httpx.Response: self.paths.append(request.url.path) + self.hosts.append(request.url.host) self.authorization.append(request.headers.get("authorization")) async def body(): @@ -259,3 +266,87 @@ async def test_a_server_behind_a_base_path_is_guarded_however_a_path_climbs_into "rest_proxy_urls": {"mcp-x": base}, "website_urls": {}} assert await _proxied(TOKEN, "POST", path, {}, **prefixed) == 401 assert backing.paths == [] + + +def _computers(**extra) -> dict: + """A multi env's two computers behind the gateway, each with its own token, beside an MCP server, a website and + the SQL consoles.""" + return {"internal_mcp_servers": [InternalMCPServer(name="desk", mcp_url="http://desk:18765/mcp"), + InternalMCPServer(name="laptop", mcp_url="http://laptop:18765/mcp")], + "rest_proxy_urls": {"mcp-svc": "http://svc", "shop": "http://shop-backend", "desk": "http://desk:18765", + "laptop": "http://laptop:18765"}, + "website_urls": {"shop": "http://shop-backend"}, + "console_urls": {"pgweb": "http://pgweb:8081", "db-mcp": "http://db-mcp:8000"}, + "child_control_tokens": COMPUTERS, **extra} + + +def _reached(backing: _Backing) -> list[tuple[str, str | None]]: + return [(at, sent) for at, sent in zip(backing.paths, backing.authorization) if at != WELL_KNOWN_PATH] + + +@pytest.mark.asyncio +@pytest.mark.parametrize("path", ["/svc/desk/agentenv", "/svc/desk/agentenv/ext/computer-exec", "/svc/desk/mcp", + "/svc/desk/svc/notes/api"]) +async def test_the_gateways_token_reaches_a_computer_as_that_computers_own(monkeypatch, path): + """A harness caller holding the multi env's token reaches its computer's framework-only routes; the computer + receives its own token, never the gateway's.""" + backing = _Backing(monkeypatch) + assert await _proxied(TOKEN, "POST", path, {"Authorization": f"Bearer {TOKEN}"}, **_computers()) != 401 + assert _reached(backing) == [(path.removeprefix("/svc/desk"), f"Bearer {DESK}")] + + +@pytest.mark.asyncio +@pytest.mark.parametrize("path, reached", [ + ("/svc/desk/agentenv", ("/agentenv", f"Bearer {DESK}")), + ("/svc/laptop/agentenv", ("/agentenv", None)), + ("/svc/laptop/agentenv/ext/computer-exec", ("/agentenv/ext/computer-exec", None)), + ("/svc/mcp-svc/export-state", ("/export-state", None)), + ("/svc/shop/api/orders", ("/api/orders", None)), + ("/website/shop/index.html", ("/index.html", None))]) +async def test_a_computers_token_goes_on_only_to_that_computer(monkeypatch, path, reached): + """A computer's token, read from it, carries to no other computer, server or site behind the gateway.""" + backing = _Backing(monkeypatch) + await _proxied(TOKEN, "POST", path, {"Authorization": f"Bearer {DESK}"}, **_computers()) + assert _reached(backing) == [reached] + + +@pytest.mark.asyncio +@pytest.mark.parametrize("method, path", [ + ("GET", "/svc/pgweb/"), ("POST", "/svc/pgweb/api/query"), ("POST", "/svc/db-mcp/mcp"), + *GUARDED]) +async def test_a_computers_token_opens_no_route_that_takes_the_gateways(monkeypatch, method, path): + """A computer's token is no key to the SQL consoles, the data plane or an MCP server's endpoint.""" + backing = _Backing(monkeypatch) + assert await _proxied(TOKEN, method, path, {"Authorization": f"Bearer {DESK}"}, **_computers()) == 401 + assert backing.paths == [] + + +@pytest.mark.asyncio +@pytest.mark.parametrize("path", sorted(CONTROL)) +async def test_a_computers_token_opens_none_of_the_gateways_control_routes(path): + gw = Gateway(host="127.0.0.1", port=0, server_name="unit", control_token=TOKEN, **_computers()) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=gw._asgi_app()), base_url="http://gateway") as client: + response = await client.request(CONTROL[path], path, json={}, headers={"Authorization": f"Bearer {DESK}"}) + assert response.status_code == 401 + + +@pytest.mark.asyncio +@pytest.mark.parametrize("path", ["/svc/desktop/agentenv/ext/computer-exec", "/svc/desktop/mcp"]) +async def test_a_computer_an_older_agent_env_booted_with_the_gateways_token_still_takes_it(monkeypatch, path): + """An older agent-env names its computers in CONTROL_TOKEN_CHILDREN, each booted with the gateway's own token.""" + backing = _Backing(monkeypatch) + older = {"internal_mcp_servers": [], "rest_proxy_urls": {"desktop": "http://desktop:18765"}, "website_urls": {}, + "control_token_children": ["desktop"]} + await _proxied(TOKEN, "POST", path, {"Authorization": f"Bearer {TOKEN}"}, **older) + assert [sent for _, sent in _reached(backing)] == [f"Bearer {TOKEN}"] + + +@pytest.mark.asyncio +@pytest.mark.parametrize("path", ["/svc/desk/../pgweb/api/query", "/svc/desk/%2E%2E/pgweb/api/query", + "/svc/desk/..%2Fpgweb/api/query"]) +async def test_a_computers_route_that_climbs_out_of_it_reaches_only_that_computer(monkeypatch, path): + """Whatever a path under a computer's route spells, its token goes only to that computer, never to a console.""" + backing = _Backing(monkeypatch) + await _proxied(TOKEN, "GET", path, {"Authorization": f"Bearer {TOKEN}"}, **_computers()) + assert set(backing.hosts) <= {"desk"} + assert set(backing.authorization) <= {f"Bearer {DESK}"} diff --git a/tst/unit/env/test_env.py b/tst/unit/env/test_env.py index 03414a75f..61f1795c7 100644 --- a/tst/unit/env/test_env.py +++ b/tst/unit/env/test_env.py @@ -431,3 +431,18 @@ def test_a_pgweb_link_opens_the_gateways_pgweb_once_and_carries_no_token(): ids=["no-pgweb", "no-token"]) def test_a_record_without_pgweb_at_its_gateway_or_a_token_has_no_pgweb_link(changes): assert dataclasses.replace(_record(None), **changes).pgweb_link() is None + + +def test_a_gateway_record_grants_each_childs_route_its_own_token_and_everything_else_the_gateways(): + """A step reaching a multi env's computer through any gateway sends the computer's own token, not the env's.""" + gateway = DeployedGatewayEnv(env_id="multi", env_version=1, gateway_url="https://gw.example", sandbox_id="gw", + environment_card_url=f"https://gw.example{WELL_KNOWN_PATH}", control_token="env-token", + child_envs={"desktop": {"control_token": "desk-own"}, "laptop": {}}) + urls = ["https://gw.example/svc/desktop/agentenv/ext/computer-exec", "https://gw.example/svc/desktop", + "https://gw.example/svc/desktop-2/agentenv", "https://gw.example/svc/laptop/agentenv", + "https://gw.example/svc/pgweb/", "https://elsewhere/svc/desktop/agentenv"] + assert [gateway.control_headers_for(url) for url in urls] == [ + {"Authorization": "Bearer desk-own"}] * 2 + [{"Authorization": "Bearer env-token"}] * 3 + [{}] + with protocol_v1.authorized(gateway.control_grants): + assert protocol_v1.request_headers(urls[0]) == {"Authorization": "Bearer desk-own"} + assert protocol_v1.request_headers(urls[4]) == {"Authorization": "Bearer env-token"} 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 c211d28db..1a34914c9 100644 --- a/tst/unit/providers/env_providers/env_gateway_provider_test.py +++ b/tst/unit/providers/env_providers/env_gateway_provider_test.py @@ -2891,7 +2891,7 @@ 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_gateways_computers_and_passes_its_token_on_to_them_only_when_it_has_one(): +def test_compose_names_the_gateways_computers_with_their_own_tokens_and_logs_none_of_them(caplog): from agent_env.env.envs.service_db import ServiceDBConfig from agent_env.env.gateway import ExternalChild @@ -2900,13 +2900,18 @@ def gateway_env(control_token): 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"))) + external_children=(ExternalChild("desktop", "https://desk.example/mcp", "https://desk.example", + control_token="desk-own"), + ExternalChild("laptop", "https://lap.example/mcp", "https://lap.example", + control_token="lap-own"))) 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) + caplog.set_level(logging.DEBUG) + assert gateway_env("gw-token")["CHILD_CONTROL_TOKENS"] == gateway_env(None)["CHILD_CONTROL_TOKENS"] == \ + "desktop=desk-own,laptop=lap-own" + assert "CONTROL_TOKEN_CHILDREN" not in gateway_env("gw-token") assert gateway_env("gw-token")["COMPUTERS"] == gateway_env(None)["COMPUTERS"] == "desktop,laptop" + assert "desk-own" not in caplog.text and "lap-own" not in caplog.text def test_compose_declares_the_children_that_follow_the_clock_by_their_read_tokens_and_logs_none_of_them(): @@ -2959,8 +2964,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, control_token): - order.append(("children", reach, control_token)) + async def children(reach): + order.append(("children", reach)) return [ExternalChild("desktop", "http://localhost:20001/mcp", "http://localhost:20001", "read-desk")] def compose(**kwargs): @@ -2986,7 +2991,7 @@ async def up(sandbox, args=""): gateway_port=18765, website_configs=None, website_images=None, gateway_mode=GatewayMode.PERFORMANCE, ttl_seconds=60, disk_size_gb=10, children=children, control_token="gw-token") - assert sorted(order[:2]) == [("children", "https://gw.example", "gw-token"), ("up", f"--scale {GATEWAY_SERVICE_NAME}=0")] + assert sorted(order[:2]) == [("children", "https://gw.example"), ("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"),)] @@ -3005,7 +3010,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, control_token): + async def children(reach): await asyncio.sleep(0.05) ended.append("children") if failing == "children": @@ -3049,9 +3054,9 @@ 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, control_token): - reaches.append((reach, control_token)) - return [ExternalChild("desktop", "https://desk.example/mcp", "https://desk.example", "read-desk")] + async def children(reach): + reaches.append(reach) + return [ExternalChild("desktop", "https://desk.example/mcp", "https://desk.example", "read-desk", "desk-own")] gateway_env = MagicMock(docker_image_artifact=_image("agent-gateway")) db_env = MagicMock() @@ -3070,11 +3075,12 @@ async def children(reach, control_token): control_token="gw-token") env = create_calls[-1]["env"] - assert reaches == [(None, "gw-token")] + assert reaches == [None] 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" + assert env["CHILD_CONTROL_TOKENS"] == "desktop=desk-own" + assert "CONTROL_TOKEN_CHILDREN" not in env assert env["COMPUTERS"] == "desktop" From 2a441491f86b0dfe85d023d3082e11ef4c573d2e Mon Sep 17 00:00:00 2001 From: Ubuntu Date: Sat, 21 Nov 2026 01:00:28 +0000 Subject: [PATCH 2/2] feat(cli): print a pgweb link a browser can open env deploy and env get-instance print pgweb's gateway URL, which takes the control token as a header a browser doesn't send. They now also print a link that opens pgweb once within five minutes and carries no token. --- src/agent_env/cli/env/deploy.py | 6 +++++- src/agent_env/cli/env/get_instance.py | 3 +++ tst/unit/cli/deployed_env_output_test.py | 23 +++++++++++++++++++++++ 3 files changed, 31 insertions(+), 1 deletion(-) diff --git a/src/agent_env/cli/env/deploy.py b/src/agent_env/cli/env/deploy.py index 708f05958..b2768f942 100644 --- a/src/agent_env/cli/env/deploy.py +++ b/src/agent_env/cli/env/deploy.py @@ -4,6 +4,7 @@ from agent_env.env import DeployedGatewayEnv, Env from agent_env.env.gateway import GatewayMode +from agent_env.env.gateway.console_session import LINK_MAX_SECONDS from agent_env.store.routing import run_scope MIN_TTL_SECONDS = 60 # 1 minute @@ -103,9 +104,12 @@ def deploy(env_id: str, env_version: int | None, ttl_seconds: int, gateway_mode: # A record without a gateway has none of the gateway's URLs. if isinstance(deployed_env, DeployedGatewayEnv): click.echo("Env Gateway Url: " + click.style(deployed_env.gateway_url, fg="yellow")) - # The SQL consoles take the env's control token, as an Authorization: Bearer header. + # The SQL consoles take the env's control token, as an Authorization: Bearer header; a browser opens pgweb + # through a link that carries no token. if deployed_env.db_web_gateway_url: click.echo("Env DB Web Url: " + click.style(deployed_env.db_web_gateway_url, fg="yellow")) + if link := deployed_env.pgweb_link(LINK_MAX_SECONDS): + click.echo(f"Env DB Web Link (opens once, within {LINK_MAX_SECONDS // 60} min): " + click.style(link, fg="yellow")) if deployed_env.db_mcp_gateway_url: click.echo("Env DB MCP Url: " + click.style(deployed_env.db_mcp_gateway_url, fg="yellow")) if deployed_env.vnc_url: diff --git a/src/agent_env/cli/env/get_instance.py b/src/agent_env/cli/env/get_instance.py index 3a4d05585..1e2613685 100644 --- a/src/agent_env/cli/env/get_instance.py +++ b/src/agent_env/cli/env/get_instance.py @@ -10,6 +10,7 @@ def get_instance(instance_id: str): from agent_env.store.base import NotFoundError from agent_env.env.env import DeployedGatewayEnv, DeployedSandboxEnv + from agent_env.env.gateway.console_session import LINK_MAX_SECONDS from agent_env.env.store import get_env_instance_store try: @@ -28,6 +29,8 @@ def get_instance(instance_id: str): click.echo(f"Env MCP Url: {deployed_env.mcp_url}") if gateway and gateway.db_web_gateway_url: click.echo(f"Env DB Web Url: {gateway.db_web_gateway_url}") + if gateway and (link := gateway.pgweb_link(LINK_MAX_SECONDS)): + click.echo(f"Env DB Web Link (opens once, within {LINK_MAX_SECONDS // 60} min): {link}") if gateway and gateway.db_mcp_gateway_url: click.echo(f"Env DB MCP Url: {gateway.db_mcp_gateway_url}") for svc_name, url in ((gateway.website_frontend_urls if gateway else None) or {}).items(): diff --git a/tst/unit/cli/deployed_env_output_test.py b/tst/unit/cli/deployed_env_output_test.py index 05b7694ee..4030d00f5 100644 --- a/tst/unit/cli/deployed_env_output_test.py +++ b/tst/unit/cli/deployed_env_output_test.py @@ -10,6 +10,7 @@ from agent_env.cli.env import env as env_cli from agent_env.cli.task.run import _format_env from agent_env.env.env import DeployedEnv, DeployedGatewayEnv, DeployedSandboxEnv +from agent_env.env.gateway.console_session import LINK_PARAM, ConsoleSession _FRONTED = DeployedGatewayEnv(env_id="e1", env_version=1, gateway_url="https://gw.example", mcp_url="https://gw.example/mcp", sandbox_id="gw", instance_id="i1") @@ -69,6 +70,28 @@ async def fake_deploy(**kwargs): assert "tunnel-" not in output + +def test_the_cli_prints_a_pgweb_link_a_browser_can_open_and_never_the_token(): + token = "s3cret-token" + record = DeployedGatewayEnv(env_id="e1", env_version=1, gateway_url="https://gw.example", + mcp_url="https://gw.example/mcp", sandbox_id="gw", instance_id="i1", + db_web_gateway_url="https://gw.example/svc/pgweb/", control_token=token) + + async def fake_deploy(**kwargs): + return record + + with patch("agent_env.cli.env.deploy.Env") as Env, patch("agent_env.providers.build_sandbox_provider"): + Env.get.return_value = MagicMock(id="e1", version=1, type="mcp_server", deploy=fake_deploy) + deployed = CliRunner().invoke(env_cli, ["deploy", "--id", "e1"]).output + with patch("agent_env.env.store.get_env_instance_store") as store: + store.return_value.get.return_value = record + got = CliRunner().invoke(env_cli, ["get-instance", "--id", "i1"]).output + for output in (deployed, got): + assert token not in output + links = [w for w in output.split() if w.startswith(f"https://gw.example/svc/pgweb/?{LINK_PARAM}=")] + assert len(links) == 1, output + assert ConsoleSession(token).opens(links[0].split(f"{LINK_PARAM}=", 1)[1]) + def test_a_record_outside_our_sandboxes_prints_no_sandbox(): with patch("agent_env.env.store.get_env_instance_store") as store: store.return_value.get.return_value = _HOSTED