diff --git a/AGENTS.md b/AGENTS.md index d6bbf6649..3449af796 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -125,7 +125,7 @@ and deserialized through a registry. |---|---| | `env/` | `Env` base class: a subclass declares `type`, implements `from_dict` and `async deploy(...) -> DeployedEnv`, and may override `reset`, `close` and `load_file_artifact_universe`; teardown closes each env a run deployed before terminating its sandboxes by id. Built-ins in `env/envs/`: `MCPServerEnv` (`mcp_server`), `MultiEnv` (`multi`, MCP servers plus websites and computers; its website browser is the one its `browser_envs` names, none for `[]`, else the run's when it has websites: an MCP server env such as `playwright-mcp` runs among the gateway's MCP servers, and a browser computer such as `chromium` on a sandbox of its own as one more computer child, sized by its `child_envs` entry, its tools under its name and `_`, routing the multi env's synthetic sites unless that entry's `site_routing` says, its network its own env's, as any computer child's; a website env deployed alone refuses a browser computer as the run's browser), `ServiceDBEnv` (`service_db`, PostgreSQL), `WebsiteEnv` (`website`, one site: a server image, `backend_image` in its env.toml, serving the pages and API, ready when its card's `website/v1` `ready` answers a `WebsiteReadiness` that says so, as `agentenv_protocol.website` (`website_readiness`, `env_readiness`) defines a website env's health for the deploy and `DeployedEnv.readiness()` alike, or, for a card without `ready`, when its `health` path answers 200, which is deprecated; its env.toml's `ready_timeout_s`, how long it may take from its server's container starting to ready, is that container's health check `start_period` and what the deploy waits, or its card's `ready` timeout if longer, and its `shm_mb` is the container's `shm_size`, each left to the gateway and Docker without them; the gateway container's `env/gateway/constants.py` mirrors the URI and op, a test keeping them equal; a separate frontend image is deprecated, warned of at put and optional in a bundle, and a stored `backend_docker_image_artifact` reads as the server image; a live one, `live = true`, is a real site whose server serves none of its pages, its `live`, `domains` and `allow_hosts` read at put from its server's `@website(...)` (`utils/card_naming.py` `WebsiteSource`) unless given, its `settings`' secrets only as references the gateway resolves as it writes the site's container (`WEBSITE_SETTINGS_ENV`); the gateway gives it no site route, a computer's site table leaves it out, a computer whose network is an allowlist is let reach its names (`MultiEnv.live_hosts`), a browser alone's forward port takes them straight to the real site (`site_proxy.py` `direct`), as the browser base's stand-in proxy takes any host, refusing nothing, each proxy logging each such connection as a JSON line, and a run that deploys one is marked live, `reproducible: false`), `GatewayEnv` (`gateway_server`), `ComputerDriverEnv` (`computer_driver`, `env/envs/computer/driver_env.py`: a computer driver's files and what its class declares for each platform it supports, read at put in a process of its own, `agentenv_protocol.computer._declare`, where the driver's own dependencies needn't be installed, with the `port` it serves on and its install by OS, `[install.]`, or for one distribution `[install."/"]`, which replaces its OS type's there, as its `known_failures` do (`env/envs/computer/utils/install.py`): files, apt `packages` with extra `sources`, a `python` requirements file for a venv, `downloads` by URL and sha256, `run` scripts, the services the base's init runs, and `ports`; it deploys only as a computer env's driver), `ComputerEnv` (`computer`, in `env/envs/computer/`: a base computer and a driver, matched at put by gate 1 before anything is stored, then composed by `composer.py` into an image for each form and arch on a builder of the put's sandbox provider, by default the env's (`utils/builder.py`; `--sandbox` on `env build`): 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. Built-in steps live in `task_step/task_steps/` (`deploy_env`, `deploy_agent`, `prompt_agent`, the verifiers under `verifiers/`, among them `start_computer_recording` and `end_computer_recording`, `start_browser_recording` and `end_browser_recording` (`browser-recording/v1`: one recording per context, a lease's or the default one's, with a video of the tab its agent is on, its context's log, the browser's network log as HAR and opt-in frames keyed to the action log, the contexts its agents make recorded with it, one universe per recording, anything missing failing the run), and more). 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`; `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. Built-in steps live in `task_step/task_steps/` (`deploy_env`, `deploy_agent`, `prompt_agent`, the verifiers under `verifiers/`, among them `start_computer_recording` and `end_computer_recording`, `start_browser_recording` and `end_browser_recording` (`browser-recording/v1`: one recording per context, a lease's or the default one's, with a video of the tab its agent is on, its context's log, the browser's network log as HAR and opt-in frames keyed to the action log, the contexts its agents make recorded with it, one universe per recording, anything missing failing the run), and more). 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`; `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 778974d26..d2a377f09 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__) @@ -1598,8 +1599,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 @@ -1609,9 +1616,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 c447ff478..d2ac02ea9 100644 --- a/packages/agentenv-protocol/tests/test_computer_driver.py +++ b/packages/agentenv-protocol/tests/test_computer_driver.py @@ -190,6 +190,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 4cd8ba555..c2f52f637 100644 --- a/src/agent_env/env/env.py +++ b/src/agent_env/env/env.py @@ -118,10 +118,16 @@ def control_headers(self) -> dict[str, str]: """What a call to the env's framework-only routes sends: its control token, when it has one.""" return protocol_v1.control_headers(self.control_token) + @property + def control_grants(self) -> dict[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.""" @@ -166,10 +172,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 @@ -243,6 +250,15 @@ class DeployedGatewayEnv(DeployedSandboxEnv): # by its environment name. child_envs: dict[str, dict] = field(default_factory=dict) + @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 4503c3889..9a77a3633 100644 --- a/src/agent_env/env/envs/_multi_computers.py +++ b/src/agent_env/env/envs/_multi_computers.py @@ -95,7 +95,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 @@ -190,10 +190,10 @@ def _recorded_browser(self, records: Mapping[str, dict]) -> Optional[ComputerEnv def deployer(self, child_envs: Optional[dict], *, sandbox_type: str | None, ttl_seconds: int, attribution: Optional[Attribution], websites: Mapping[str, str], live_hosts: Iterable[str] = () - ) -> Callable[[Optional[str], 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.""" @@ -205,14 +205,14 @@ def deployer(self, child_envs: Optional[dict], *, sandbox_type: str | None, ttl_ routing = entry["env_params"]["site_routing"] self._routes[name] = None if routing is True else [websites[env_id] for env_id in routing] - async def deploy(reach: Optional[str], 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) @@ -220,8 +220,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 01ea981c2..2e0ac0ee8 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 dcb965ada..712a46e9d 100644 --- a/src/agent_env/env/gateway/entrypoint.py +++ b/src/agent_env/env/gateway/entrypoint.py @@ -8,7 +8,7 @@ import httpx from . import AGENT_ENV_GATEWAY_MCP_PORT, GatewayMode, InternalMCPServer -from .constants import (CLOCK_FOLLOWERS_ENV, COMPUTERS_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_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 @@ -189,17 +189,18 @@ def parse_name_url_map(env_str: str) -> dict[str, str]: return urls -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, ...]]: @@ -245,6 +246,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 31e3460da..85f978cf6 100644 --- a/src/agent_env/env/gateway/gateway.py +++ b/src/agent_env/env/gateway/gateway.py @@ -177,6 +177,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, @@ -189,8 +190,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, and not at all without one.""" @@ -216,6 +220,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 {} if clashes := sorted(self._consoles.keys() & self.rest_proxy_urls.keys()): raise ValueError(f"console keys {clashes} are also backing servers' /svc keys") @@ -601,13 +606,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 @@ -618,19 +631,17 @@ 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", ()) - if scope["type"] == "http" and self._takes_control_token(scope) and not hmac.compare_digest( - dict(headers).get(b"authorization", b""), self._control_bearer): + if self._control_bearer and scope["type"] == "http" and self._takes_control_token(scope) and \ + not hmac.compare_digest(dict(headers).get(b"authorization", b""), self._control_bearer): logger.warning("refused %s %s: it takes the env's control token", scope["method"], scope["path"]) response = self._json_response({"ok": False, "error": "this route takes the env's control token"}, 401) await response(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"]): - scope = {**scope, "headers": [(name, value) for name, value in headers if not ( - name == b"authorization" and hmac.compare_digest(value, self._control_bearer))]} + passed = [(name, self._passed_authorization(scope["path"], value) if name == b"authorization" else value) + for name, value in headers] + scope = {**scope, "headers": [(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 6446555aa..f5b432d2c 100644 --- a/src/agent_env/providers/env_providers/env_gateway_provider.py +++ b/src/agent_env/providers/env_providers/env_gateway_provider.py @@ -38,7 +38,7 @@ CLOCK_FOLLOWERS_ENV, COMPUTERS_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, @@ -574,7 +574,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)}") @@ -687,7 +687,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. @@ -838,7 +838,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: @@ -953,7 +953,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(sandbox.tunnel_urls.get(gateway_port), control_token), + children(sandbox.tunnel_urls.get(gateway_port)), return_exceptions=True) for result in (up, started): if isinstance(result, BaseException): @@ -1051,7 +1051,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 @@ -1108,7 +1108,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] = [] @@ -1162,7 +1162,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 {}), } @@ -1527,7 +1527,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, ) -> DeployedGateway: """One gateway deploy on one (unchained) sandbox provider: a VM on one that creates VMs, else a container per @@ -1843,11 +1843,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 8b761d893..9ed0751df 100644 --- a/src/agent_env/task/task.py +++ b/src/agent_env/task/task.py @@ -700,7 +700,7 @@ async def _run_one(step: TaskStep, idx: int, dispatch_epoch: int) -> None: started_mono = time.monotonic() started_utc = datetime.now(timezone.utc).isoformat() try: - 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 93b1f0062..8b56b7e05 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" @@ -288,7 +288,7 @@ def gateway(monkeypatch, local_stores): async def deploy(self, env, sandbox_provider, *, children=None, **options): made.options.append({**options, "children": children}) for _ in range(made.tries): - made.started.append(await children(GATEWAY, 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", @@ -304,8 +304,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"} @@ -314,12 +314,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"}} @@ -931,13 +933,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 d94ba0eb1..64802abf8 100644 --- a/tst/unit/env/test_env.py +++ b/tst/unit/env/test_env.py @@ -414,3 +414,18 @@ async def test_readiness_of_a_record_with_no_card_url_cannot_be_asked(sent, site with pytest.raises(EnvCapabilityUnsupported, match="does not offer 'ready' on urn:agentenv:website/v1"): await dataclasses.replace(_record(sites), environment_card_url=None).readiness() assert sent == [] + + +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 cc8be6e51..2596a451f 100644 --- a/tst/unit/providers/env_providers/env_gateway_provider_test.py +++ b/tst/unit/providers/env_providers/env_gateway_provider_test.py @@ -2888,7 +2888,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 @@ -2897,13 +2897,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(): @@ -2956,8 +2961,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): @@ -2983,7 +2988,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"),)] @@ -3002,7 +3007,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": @@ -3046,9 +3051,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() @@ -3067,11 +3072,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"