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/cli/env/deploy.py b/src/agent_env/cli/env/deploy.py index 25e6f3749..708f05958 100644 --- a/src/agent_env/cli/env/deploy.py +++ b/src/agent_env/cli/env/deploy.py @@ -103,10 +103,11 @@ def deploy(env_id: str, env_version: int | None, ttl_seconds: int, gateway_mode: # A record without a gateway has none of the gateway's URLs. if isinstance(deployed_env, DeployedGatewayEnv): click.echo("Env Gateway Url: " + click.style(deployed_env.gateway_url, fg="yellow")) - if deployed_env.db_web_url: - click.echo("Env DB Web Url: " + click.style(deployed_env.db_web_url, fg="yellow")) - if deployed_env.db_mcp_url: - click.echo("Env DB MCP Url: " + click.style(deployed_env.db_mcp_url, fg="yellow")) + # The SQL consoles take the env's control token, as an Authorization: Bearer header. + if deployed_env.db_web_gateway_url: + click.echo("Env DB Web Url: " + click.style(deployed_env.db_web_gateway_url, fg="yellow")) + if deployed_env.db_mcp_gateway_url: + click.echo("Env DB MCP Url: " + click.style(deployed_env.db_mcp_gateway_url, fg="yellow")) if deployed_env.vnc_url: click.echo("VNC Url: " + click.style(deployed_env.vnc_url, fg="yellow")) for svc_name, url in (deployed_env.website_frontend_urls or {}).items(): diff --git a/src/agent_env/cli/env/get_instance.py b/src/agent_env/cli/env/get_instance.py index 4bcfd213b..3a4d05585 100644 --- a/src/agent_env/cli/env/get_instance.py +++ b/src/agent_env/cli/env/get_instance.py @@ -26,10 +26,10 @@ def get_instance(instance_id: str): if gateway: click.echo(f"Env Base Url: {gateway.gateway_url}") click.echo(f"Env MCP Url: {deployed_env.mcp_url}") - if gateway and gateway.db_web_url: - click.echo(f"Env DB Web Url: {gateway.db_web_url}") - if gateway and gateway.db_mcp_url: - click.echo(f"Env DB MCP Url: {gateway.db_mcp_url}") + if gateway and gateway.db_web_gateway_url: + click.echo(f"Env DB Web Url: {gateway.db_web_gateway_url}") + if gateway and gateway.db_mcp_gateway_url: + click.echo(f"Env DB MCP Url: {gateway.db_mcp_gateway_url}") for svc_name, url in ((gateway.website_frontend_urls if gateway else None) or {}).items(): click.echo(f"Website Frontend ({svc_name}): {url}") if isinstance(deployed_env, DeployedSandboxEnv): diff --git a/src/agent_env/cli/run.py b/src/agent_env/cli/run.py index fd1182662..294afaf30 100644 --- a/src/agent_env/cli/run.py +++ b/src/agent_env/cli/run.py @@ -26,7 +26,7 @@ _COLORS = {Outcome.PASSED: "green", Outcome.BELOW_ONE: "yellow", Outcome.UNSCORED: "yellow", Outcome.FAILED: "red", Outcome.CANCELLED: "yellow"} -_ENV_ENDPOINTS = (("mcp", "mcp_url"), ("gateway", "gateway_url"), ("pgweb", "db_web_url"), ("db-mcp", "db_mcp_url"), +_ENV_ENDPOINTS = (("mcp", "mcp_url"), ("gateway", "gateway_url"), ("pgweb", "db_web_gateway_url"), ("db-mcp", "db_mcp_gateway_url"), ("vnc", "vnc_url"), ("expires", "expires_at_utc")) _DRY_RUN = "Dry run: nothing is written or run." diff --git a/src/agent_env/cli/task/run.py b/src/agent_env/cli/task/run.py index feaba615b..64aff5183 100644 --- a/src/agent_env/cli/task/run.py +++ b/src/agent_env/cli/task/run.py @@ -49,7 +49,8 @@ def _format_env(env) -> str: f" env_version: {env.env_version}", *([f" gateway_url: {env.gateway_url}"] if fronted else []), f" mcp_url: {env.mcp_url}", - *([f" db_web_url: {env.db_web_url}", f" db_mcp_url: {env.db_mcp_url}"] if fronted else []), + *([f" db_web_gateway_url: {env.db_web_gateway_url}", f" db_mcp_gateway_url: {env.db_mcp_gateway_url}"] + if fronted else []), ] if isinstance(env, DeployedSandboxEnv): # an env outside our sandboxes has no sandbox to name lines.append(f" sandbox_id: {env.sandbox_id}") diff --git a/src/agent_env/env/env.py b/src/agent_env/env/env.py index bea7e06f4..c47de6478 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 @@ -230,6 +237,10 @@ class DeployedGatewayEnv(DeployedSandboxEnv): gateway_mode: str = GatewayMode.PERFORMANCE.value db_web_url: Optional[str] = None db_mcp_url: Optional[str] = None + # pgweb and db-mcp behind the gateway, which take the control token (``control_headers_for``); None when the deploy + # renders no such console, has no control token, or its gateway doesn't guard and reach the console. + db_web_gateway_url: Optional[str] = None + db_mcp_gateway_url: Optional[str] = None website_frontend_urls: Optional[dict[str, str]] = None vnc_url: Optional[str] = None # Ids of the EnvStateInstance record(s) this deploy's state was provisioned into @@ -239,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 { @@ -248,6 +268,8 @@ def _fields_from(cls, data: dict) -> dict: "gateway_mode": data.get("gateway_mode", GatewayMode.PERFORMANCE.value), "db_web_url": data.get("db_web_url"), "db_mcp_url": data.get("db_mcp_url"), + "db_web_gateway_url": data.get("db_web_gateway_url"), + "db_mcp_gateway_url": data.get("db_mcp_gateway_url"), "website_frontend_urls": data.get("website_frontend_urls"), "vnc_url": data.get("vnc_url"), "env_state_instance_ids": data.get("env_state_instance_ids") or [], @@ -583,5 +605,5 @@ def _record_class(data: dict) -> type[DeployedEnv]: # A record carrying any of these is a gateway's. Not gateway_mode: an older kernel writes its default into any record it round-trips. -_GATEWAY_ONLY_FIELDS = ("gateway_url", "db_web_url", "db_mcp_url", "website_frontend_urls", "vnc_url", "env_state_instance_ids", - "child_envs") +_GATEWAY_ONLY_FIELDS = ("gateway_url", "db_web_url", "db_mcp_url", "db_web_gateway_url", "db_mcp_gateway_url", + "website_frontend_urls", "vnc_url", "env_state_instance_ids", "child_envs") diff --git a/src/agent_env/env/envs/_multi_computers.py b/src/agent_env/env/envs/_multi_computers.py index 4503c3889..2a45df04c 100644 --- a/src/agent_env/env/envs/_multi_computers.py +++ b/src/agent_env/env/envs/_multi_computers.py @@ -15,6 +15,7 @@ from agent_env.env.env import DeployedEnv, DeployedGatewayEnv, Env, gateway_url_of from agent_env.env.envs.computer.utils import clock as computer_clock, sites +from agent_env.env.envs.service_db import DB_MCP_SERVICE_NAME, PGWEB_SERVICE_NAME from agent_env.env.gateway import ExternalChild from agent_env.providers.sandbox_providers.sandbox_provider import build_sandbox_provider, get_env_sandbox_provider @@ -29,8 +30,8 @@ def name_problems(computers: Iterable[str], *, mcp_servers: Iterable[str] = (), websites: Iterable[str] = ()) -> list[str]: """What's wrong with ``computers``, the environment names of a multi env's computers, beside the names of its ``mcp_servers`` and ``websites``: a computer serves its tools under its name and ``_``, which must make a tool prefix, - and the gateway knows a computer by its name alone, which no other child env and no route of the gateway's to an - MCP server (``mcp-``) may have.""" + and the gateway knows a computer by its name alone, which no other child env, no route of the gateway's to an MCP + server (``mcp-``) and no SQL console's /svc key may have.""" computers, mcp_servers = list(computers), list(dict.fromkeys(mcp_servers)) problems = [f"computer {name!r} serves its tools under its name and '_': {problem}" for name in dict.fromkeys(computers) if (problem := tool_prefix_problem(f"{name}_"))] @@ -40,6 +41,8 @@ def name_problems(computers: Iterable[str], *, mcp_servers: Iterable[str] = (), for name in dict.fromkeys(computers) if counts[name] > 1] problems += [f"{name!r} is the gateway's route to MCP server {routes[name]!r}, and the gateway knows a computer by its " "name alone" for name in dict.fromkeys(computers) if name in routes] + problems += [f"{name!r} is the gateway's route to a SQL console, and the gateway knows a computer by its name alone" + for name in dict.fromkeys(computers) if name in (PGWEB_SERVICE_NAME, DB_MCP_SERVICE_NAME)] return problems @@ -95,7 +98,7 @@ def routes_later(entry: Optional[dict]) -> bool: def _clock_read_token(record: DeployedEnv) -> str | None: """The read token a computer's clock watch carries when its card says it's a clock follower (``clock/v1``'s - ``sync_time``): for now its control token, which a token of its own can replace without the gateway knowing.""" + ``sync_time``): its own control token, which the gateway takes from it only at the watch.""" return record.control_token if computer_clock.follows(record) else None @@ -190,10 +193,10 @@ def _recorded_browser(self, records: Mapping[str, dict]) -> Optional[ComputerEnv def deployer(self, child_envs: Optional[dict], *, sandbox_type: str | None, ttl_seconds: int, attribution: Optional[Attribution], websites: Mapping[str, str], live_hosts: Iterable[str] = () - ) -> Callable[[Optional[str], Optional[str]], Awaitable[list[ExternalChild]]]: + ) -> Callable[[Optional[str]], Awaitable[list[ExternalChild]]]: """The gateway's ``children``: every computer deployed as its child_envs entry says, its tools served under its - name and ``_``, its framework-only routes taking ``control_token``, the gateway's, which the gateway passes on to - them, and its network allowing ``reach``, the gateway's address when the gateway has one yet, and the + name and ``_``, its framework-only routes taking a token of its own, which the gateway sends it in place of the + gateway's own on its /svc routes, so nothing in a computer holds the gateway's, and its network allowing ``reach``, the gateway's address when the gateway has one yet, and the ``live_hosts`` of the multi env's live websites; then each as the gateway fronts it. A computer routing the multi env's ``websites`` (their environment names by env id) boots with its boot apps held, for ``finish`` to route them once the gateway is up. A gateway deploy tried again deploys them again, after closing the earlier try's.""" @@ -205,14 +208,14 @@ def deployer(self, child_envs: Optional[dict], *, sandbox_type: str | None, ttl_ routing = entry["env_params"]["site_routing"] self._routes[name] = None if routing is True else [websites[env_id] for env_id in routing] - async def deploy(reach: Optional[str], control_token: Optional[str]) -> list[ExternalChild]: + async def deploy(reach: Optional[str]) -> list[ExternalChild]: nonlocal tries if tries: await self.close() tries += 1 results = await asyncio.gather(*(env.deploy( ttl_seconds=ttl_seconds, attribution=attribution, tool_prefix=f"{env.environment_name}_", - reach=reach or "", sites_later=env.environment_name in self._routes, control_token=control_token, + reach=reach or "", sites_later=env.environment_name in self._routes, **({"live_hosts": live} if live else {}), **deploy_options((child_envs or {}).get(env.environment_name), sandbox_type)) for env in self.every), return_exceptions=True) @@ -220,8 +223,8 @@ async def deploy(reach: Optional[str], control_token: Optional[str]) -> list[Ext for error in failed[1:]: logger.warning(f"multi env '{self._owner}': another computer failed to deploy too: {error!r}") raise failed[0] - return [ExternalChild(env.environment_name, record.mcp_url, record.environment_url, _clock_read_token(record)) - for env, record in zip(self.every, results)] + return [ExternalChild(env.environment_name, record.mcp_url, record.environment_url, _clock_read_token(record), + record.control_token) for env, record in zip(self.every, results)] return deploy async def finish(self, deployed: DeployedEnv) -> None: diff --git a/src/agent_env/env/envs/computer/env.py b/src/agent_env/env/envs/computer/env.py index dd79b4c67..972fe9542 100644 --- a/src/agent_env/env/envs/computer/env.py +++ b/src/agent_env/env/envs/computer/env.py @@ -301,19 +301,16 @@ async def deploy(self, ttl_seconds: int = 10800, disk_size_gb: float = 10, memory_mb: int | None = None, sandbox_type: str | None = None, env_state_type: str | None = None, env_state_instance_id: str | None = None, *, attribution: Optional[Attribution] = None, env_params: Optional[dict] = None, tool_prefix: str = "", reach: str = "", - sites_later: bool = False, live_hosts: tuple[str, ...] = (), - control_token: Optional[str] = None) -> DeployedEnv: + sites_later: bool = False, live_hosts: tuple[str, ...] = ()) -> DeployedEnv: """With ``tool_prefix``, its driver serves its tools under it, with ``reach``, a network that restricts its egress allows that URL's host too, and the ``live_hosts`` of the run's live websites, with ``sites_later`` - it routes the sites ``env_params.site_routing`` reaches when ``route_sites`` gives them, and with - ``control_token`` its framework-only routes take that token, not one of its own: what a multi env gives each - of its computers.""" + it routes the sites ``env_params.site_routing`` reaches when ``route_sites`` gives them.""" return await deploy_through_provider( self, environment_name=self.environment_name, ttl_seconds=ttl_seconds, sandbox_type=sandbox_type, then=self._give_tools, disk_size_gb=disk_size_gb, gateway_mode=gateway_mode, cpu=cpu, memory_mb=memory_mb, env_state_type=env_state_type, env_state_instance_id=env_state_instance_id, attribution=attribution, env_params=env_params, tool_prefix=tool_prefix, reach=reach, sites_later=sites_later, - live_hosts=tuple(live_hosts), control_token=control_token) + live_hosts=tuple(live_hosts)) async def route_sites(self, sites: list[dict]) -> None: """Route ``sites`` on this computer, deployed with ``sites_later``, launch its held apps and finish its boot; diff --git a/src/agent_env/env/envs/computer/utils/boot.py b/src/agent_env/env/envs/computer/utils/boot.py index 37f0188a5..b145805ef 100644 --- a/src/agent_env/env/envs/computer/utils/boot.py +++ b/src/agent_env/env/envs/computer/utils/boot.py @@ -6,6 +6,7 @@ import asyncio import contextlib +import hashlib import json import logging import re @@ -15,11 +16,12 @@ from dataclasses import dataclass from typing import TYPE_CHECKING, Any, Optional -from agentenv_protocol import CONTROL_TOKEN_ENV +from agentenv_protocol import CONTROL_TOKEN_ENV, CONTROL_TOKEN_SHA256_ENV from agentenv_protocol import client as protocol_v1 from agentenv_protocol.computer import APP_SETTINGS_ENV, COMPUTER_READY, SETTINGS_ENV, TOOL_PREFIX_ENV from agentenv_protocol.computer.app import COMPUTER_APP from agentenv_protocol.computer.apps import ANSWER_TIMEOUT_S +from agentenv_protocol.computer.card import COMPUTER, CONTROL_TOKEN_SHA256 from agentenv_protocol.computer.platform import entry_for from agent_env.config import get_config @@ -168,10 +170,19 @@ def control_token() -> str: return secrets.token_urlsafe(CONTROL_TOKEN_BYTES) -def control_environment(token: Optional[str]) -> dict[str, str]: - """What hands a computer its control ``token`` in its boot environment; nothing without one, as for a computer an - older agent-env booted.""" - return {CONTROL_TOKEN_ENV: token} if token else {} +def control_environment(token: Optional[str], card: Optional[dict] = None) -> dict[str, str]: + """What hands a computer its control ``token`` in its boot environment, by what ``card``, its driver's as a probe + read it, says the driver takes: only the token's sha256 for a driver that takes that (computer/v1's + ``control_token``), so nothing in the computer holds the token; the token for one an older protocol built; both for + a driver no card describes yet, as on its probe, where each takes what it knows. Nothing without a token, as for a + computer an older agent-env booted.""" + if not token: + return {} + verifier = {CONTROL_TOKEN_SHA256_ENV: hashlib.sha256(token.encode()).hexdigest()} + if card is None: + return {CONTROL_TOKEN_ENV: token, **verifier} + takes = protocol_v1.extension_params(card, COMPUTER).get("control_token") == CONTROL_TOKEN_SHA256 + return verifier if takes else {CONTROL_TOKEN_ENV: token} def shm_environment(form: str, os_type: str, shm_mb: Optional[int]) -> dict[str, str]: @@ -194,15 +205,17 @@ def shm_kwargs(sandbox_provider: SandboxProvider, shm_mb: Optional[int]) -> dict async def boot(sandbox_provider: SandboxProvider, *, image: str, port: int, environment: dict[str, str], token: str, + card: Optional[dict] = None, network_policy: Optional[NetworkPolicy], timeout: int, attribution: Optional[Attribution], disk_size_gb: float = 10, cpu: Optional[float] = None, memory_mb: Optional[int] = None, ready_s: float = READY_TIMEOUT_S, form: str = "container", held: bool = False, platform: str = "linux", shm_mb: Optional[int] = None) -> Booted: - """``image``, of ``form``, booted with ``environment`` and its control ``token`` on ``sandbox_provider``, which the + """``image``, of ``form``, booted with ``environment`` and its control ``token``, as ``card``, its driver's, says it + takes it (``control_environment``), on ``sandbox_provider``, which the caller chose to run its arch natively, its driver's ``port`` reached on the sandbox, its ``/dev/shm`` ``shm_mb`` MiB where the sandbox can size it, once the driver, asked with that token, says the computer is ready, or with ``held``, its boot apps' launch held, once it answers (``ready``); a boot that fails is torn down.""" - environment = {**environment, **control_environment(token), **shm_environment(form, platform.partition("/")[0], shm_mb)} + environment = {**environment, **control_environment(token, card), **shm_environment(form, platform.partition("/")[0], shm_mb)} if form == "vm_bundle": sandbox = await sandbox_provider.create_vm( image=image, env=environment, exposed_ports=[port], network_policy=network_policy, diff --git a/src/agent_env/env/gateway/__init__.py b/src/agent_env/env/gateway/__init__.py index 33a49e3df..b4935cb84 100644 --- a/src/agent_env/env/gateway/__init__.py +++ b/src/agent_env/env/gateway/__init__.py @@ -30,13 +30,15 @@ class InternalMCPServer: @dataclass(frozen=True) class ExternalChild: """A child env on a sandbox of its own, which the gateway fronts as it does an MCP server: its name, and its MCP - endpoint and base URL as the process holding it reaches them. A child that is a clock follower has the read token its - clock watch carries, and the gateway's clock writes wait for it.""" + endpoint and base URL as the process holding it reaches them, and the control token its framework-only routes take, + which the gateway sends it in place of its own. A child that is a clock follower has the read token its clock watch + carries, and the gateway's clock writes wait for it.""" name: str mcp_url: str base_url: str clock_read_token: str | None = None + control_token: str | None = None __all__ = [ diff --git a/src/agent_env/env/gateway/constants.py b/src/agent_env/env/gateway/constants.py index 26e3133d9..2e0ac0ee8 100644 --- a/src/agent_env/env/gateway/constants.py +++ b/src/agent_env/env/gateway/constants.py @@ -72,11 +72,19 @@ 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" +# The env's SQL consoles (pgweb, db-mcp), each as `key=url` on the env's network, comma-separated. The gateway serves +# each at /svc//, every path of it behind its control token, and none of them when it has no token. +CONSOLE_URLS_ENV = "CONSOLE_URLS" # The route a clock follower long-polls, with its read token. CLOCK_WATCH_PATH = "/clock/watch" CLOCK_FOLLOWERS_PATH = "/clock/followers" diff --git a/src/agent_env/env/gateway/entrypoint.py b/src/agent_env/env/gateway/entrypoint.py index ad7f3c833..636b061eb 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, 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 @@ -165,8 +165,9 @@ async def _site_card(client: httpx.AsyncClient, base: str, deadline: float) -> d await asyncio.sleep(_INTERNAL_SERVER_POLL_S) -def parse_name_url_map(env_str: str) -> dict[str, str]: - # Expected format: 'slack=http://slack-website-backend:8000,email=http://email-website-backend:8000' +def parse_name_url_map(variable: str) -> dict[str, str]: + """The environment variable ``variable`` as a name-to-URL map, from 'slack=http://slack-website-backend:8000,...'.""" + env_str = os.environ.get(variable, "") urls: dict[str, str] = {} if not env_str.strip(): return urls @@ -175,31 +176,32 @@ def parse_name_url_map(env_str: str) -> dict[str, str]: if not entry: continue if "=" not in entry: - raise ValueError(f"Invalid REST_PROXY_URLS entry: '{entry}' (expected 'name=url')") + raise ValueError(f"Invalid {variable} entry: '{entry}' (expected 'name=url')") name, url = entry.split("=", 1) name = name.strip() url = url.strip() if not name: - raise ValueError(f"Empty service name in REST_PROXY_URLS entry: '{entry}'") + raise ValueError(f"Empty service name in {variable} entry: '{entry}'") if not url.startswith(("http://", "https://")): - raise ValueError(f"Invalid URL in REST_PROXY_URLS: '{url}' (must start with http:// or https://)") + raise ValueError(f"Invalid URL in {variable}: '{url}' (must start with http:// or https://)") if name in urls: - raise ValueError(f"Duplicate service name in REST_PROXY_URLS: '{name}'") + raise ValueError(f"Duplicate service name in {variable}: '{name}'") urls[name] = url 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, ...]]: @@ -223,8 +225,8 @@ def parse_site_names(env_str: str) -> dict[str, tuple[str, ...]]: spec=os.environ.get("INTERNAL_MCP_SERVERS", ""), port=int(os.environ.get("INTERNAL_MCP_PORT", str(AGENT_ENV_GATEWAY_MCP_PORT))), ) - website_urls = parse_name_url_map(os.environ.get("WEBSITE_URLS", "")) - rest_proxy_urls = parse_name_url_map(os.environ.get("REST_PROXY_URLS", "")) + website_urls = parse_name_url_map("WEBSITE_URLS") + rest_proxy_urls = parse_name_url_map("REST_PROXY_URLS") internal_mcp_servers += asyncio.run(website_mcp_servers( {name: rest_proxy_urls.get(name, url) for name, url in website_urls.items()}, taken=frozenset(server.name for server in internal_mcp_servers))) @@ -239,11 +241,14 @@ def parse_site_names(env_str: str) -> dict[str, tuple[str, ...]]: internal_mcp_servers=internal_mcp_servers, website_urls=website_urls, rest_proxy_urls=rest_proxy_urls, + console_urls=parse_name_url_map(CONSOLE_URLS_ENV), gateway_mode=gateway_mode, service_db_url=service_db_url, control_token=os.environ.get(CONTROL_TOKEN_ENV), control_token_children=[name.strip() for name in os.environ.get(CONTROL_TOKEN_CHILDREN_ENV, "").split(",") if name.strip()], + 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 32021167f..d5473b9a3 100644 --- a/src/agent_env/env/gateway/gateway.py +++ b/src/agent_env/env/gateway/gateway.py @@ -177,21 +177,27 @@ 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, site_names: dict[str, Iterable[str]] | None = None, listed_by_name: Iterable[str] = (), + console_urls: Mapping[str, str] | None = None, ): """`provider_headers` names the headers the sandbox provider in front of the gateway is sent, its credentials, which the gateway takes off every request it forwards to a service behind it. `clock_followers` names the 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.""" + 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.""" self.host = host self.port = port self.server_name = server_name @@ -214,6 +220,10 @@ 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") self._computers = frozenset(computers) # The computer each computer tool is one of, the computer tools that take input rather than read, and the role # driving each computer now: the last to make an input call to its tools. @@ -267,14 +277,17 @@ async def list_website_urls() -> list[str]: self._env_get_time_url_cache: str | None = None self._install_role_filters() - if self.rest_proxy_urls: + if self.rest_proxy_urls or self._consoles: @self._mcp.custom_route( "/svc/{service_name}/{path:path}", methods=["GET", "POST", "PUT", "DELETE", "PATCH"], ) async def proxy_to_service(request: Request) -> Response: + if request.path_params["service_name"] in self._consoles: + return await self._proxy_console_request(request) return await self._proxy_rest_request(request) + if self.rest_proxy_urls: @self._mcp.custom_route(BROWSER_ROUTE, methods=["GET", "HEAD"]) async def browser_discovery(request: Request) -> Response: return await self._browsers.discovery(request) @@ -593,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 @@ -610,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 @@ -640,14 +659,17 @@ async def app(scope, receive, send): return app def _takes_control_token(self, scope: dict) -> bool: - """Whether a request takes the deploy's control token: a control route, the env's data plane, or one of - ``token_paths`` behind /svc, by the path as routed or by the one the backing server receives (``reaches``), - after dot-segment normalisation. A site's /website route never reaches its data plane.""" + """Whether a request takes the deploy's control token: a control route, the env's data plane, any path of a SQL + console behind /svc, or one of ``token_paths`` behind /svc, by the path as routed or by the one the backing + server receives (``reaches``), after dot-segment normalisation. A site's /website route never reaches its data + plane.""" path = scope["path"] if path in CONTROL_ROUTES or is_child_mcp_path(path, RPC_PATH): return True prefix, _, rest = path.lstrip("/").partition("/") service, _, rest = rest.partition("/") + if prefix == "svc" and service in self._consoles: + return True guarded = self._token_paths.get(service, ()) if prefix == "svc" else () raw, base = scope.get("raw_path") or path.encode(), self.rest_proxy_urls.get(service, "") return any(reaches(base, raw, path, rest, endpoint) for endpoint in guarded) @@ -905,6 +927,13 @@ async def log_write(status: int) -> None: on_done=log_write, withheld=self._withheld, mcp_endpoint=mcp_endpoint, site_names=site_names) + async def _proxy_console_request(self, request: Request) -> Response: + """Forward a request to one of the env's SQL consoles. Only a holder of the control token reaches one, and what + it writes there is no role's, so it opens no write window.""" + return await forward(request, self._consoles[request.path_params["service_name"]], + role=self._request_role(request), timeout=self.REST_PROXY_TIMEOUT, mcp_server=False, + withheld=self._withheld) + async def _proxy_website_request(self, request: Request) -> Response: """Proxy a website request; with a website or state trigger registered, feed it to the engine and hold barriers. A site's data plane and card, and every path its card advertises for agentenv (``site_reserved_paths``), are 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 2e993e8b8..0a8455d9e 100644 --- a/src/agent_env/providers/env_providers/env_gateway_provider.py +++ b/src/agent_env/providers/env_providers/env_gateway_provider.py @@ -37,7 +37,8 @@ from agent_env.env.gateway.constants import ( CLOCK_FOLLOWERS_ENV, COMPUTERS_ENV, - CONTROL_TOKEN_CHILDREN_ENV, + CONSOLE_URLS_ENV, + CHILD_CONTROL_TOKENS_ENV, DEFAULT_MCP_SERVER_NAME, GATEWAY_PROVIDER_HEADERS_ENV, STATE_TOOL_NAME_CLASHES_KEY, @@ -144,6 +145,8 @@ class DeployedGateway: mcp_url: str db_web_url: str db_mcp_url: str | None = None + db_web_gateway_url: str | None = None + db_mcp_gateway_url: str | None = None website_frontend_urls: dict[str, str] | None = None mcp_server_name: str | None = None # Ids of the EnvStateInstance record(s) this deploy acquired; the caller records them @@ -208,6 +211,25 @@ def image(self) -> str: return self.image_artifact.image_name +async def _console_answer(client: httpx.AsyncClient, url: str, headers: dict[str, str]) -> int | str: + """The status ``url`` answers, or the name of the error when it doesn't answer. A console still booting, or a + sandbox tunnel dropping a connection, leaves a timeout, a connection error or a 502-504, so such an answer is asked + again, ``_CONSOLE_ATTEMPTS`` times in all.""" + answer: int | str = "unasked" + for attempt in range(_CONSOLE_ATTEMPTS): + if attempt: + await asyncio.sleep(_CONSOLE_RETRY_PAUSE_S) + try: + answer = (await client.get(url, headers=headers)).status_code + if answer not in (502, 503, 504): + return answer + except httpx.TransportError as e: + answer = type(e).__name__ + except httpx.HTTPError as e: + return type(e).__name__ + return answer + + class EnvironmentGatewayProvider(_SandboxEnvironmentProvider): """Provider for creating gateway deployments.""" @@ -548,10 +570,12 @@ def create_docker_compose( gateway_env.append(f" - REST_PROXY_URLS={','.join(rest_proxy_urls)}") gateway_env.append(f" - GATEWAY_MODE={gateway_mode.value}") gateway_env.append(f" - SERVICE_DB_URL={state_provider.base_url(state_instance)}") + if consoles := state_provider.console_urls(): + gateway_env.append(f" - {CONSOLE_URLS_ENV}={','.join(f'{k}={v}' for k, v in consoles.items())}") 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)}") @@ -664,7 +688,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. @@ -702,6 +726,8 @@ async def deploy( sandbox_id=self._sandbox.sandbox_id, sandbox_type=self._sandbox.type, sandbox_ids=self._sandbox_ids(always_name_gateway=topology.names_gateway_on_vm), db_mcp_url=deployed.db_mcp_url, + db_web_gateway_url=deployed.db_web_gateway_url, + db_mcp_gateway_url=deployed.db_mcp_gateway_url, environment_card_url=f"{deployed.gateway_url}{WELL_KNOWN_PATH}", environment_card=deployed.environment_card, environment_card_read_at_utc=deployed.environment_card_read_at_utc, @@ -813,7 +839,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: @@ -928,7 +954,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): @@ -997,6 +1023,7 @@ async def _stand_up(_spec): await self._refuse_tool_name_clashes(gateway_url) mcp_url = _mcp_url(gateway_url, card) logger.info(f"MCP endpoint: {mcp_url}") + consoles = await self._served_consoles(gateway_url, sidecar_names, control_token) website_frontend_urls = _frontend_urls(gateway_url, website_configs) for svc_name, url in (website_frontend_urls or {}).items(): @@ -1005,6 +1032,7 @@ async def _stand_up(_spec): logger.info(f"Gateway URL: {gateway_url}") return DeployedGateway( gateway_url=gateway_url, mcp_url=mcp_url, db_web_url=db_web_url, db_mcp_url=db_mcp_url, + db_web_gateway_url=consoles.get(PGWEB_SERVICE_NAME), db_mcp_gateway_url=consoles.get(DB_MCP_SERVICE_NAME), website_frontend_urls=website_frontend_urls, mcp_server_name=mcp_server_name, env_state_instance_ids=[state_instance.instance_id], environment_card=card, environment_card_read_at_utc=card_read_at_utc, control_token=control_token, @@ -1024,7 +1052,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 @@ -1081,13 +1109,14 @@ 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] = [] mcp_results: list[tuple[str, "Sandbox"]] = [] pgweb_sb = None db_mcp_sb = None + consoles: dict[str, str] = {} errors: list[BaseException] = [] for i, r in enumerate(all_results): if isinstance(r, BaseException): @@ -1102,6 +1131,8 @@ async def _deploy_via_containers( external = r else: spec = sidecar_specs[i - len(mcp_coros)] + if r.private_host: + consoles[spec.name] = f"http://{r.private_host}:{spec.port}" if spec.name == PGWEB_SERVICE_NAME: pgweb_sb = r self._pgweb_sandbox = r @@ -1128,10 +1159,11 @@ async def _deploy_via_containers( *(f"{c.name}={sandbox_provider.url_from_sandbox(c.base_url)}" for c in external)]), "GATEWAY_MODE": gateway_mode.value, "SERVICE_DB_URL": self._state_provider.base_url(state_instance), + **({CONSOLE_URLS_ENV: ",".join(f"{k}={v}" for k, v in consoles.items())} if consoles else {}), "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 {}), } @@ -1157,11 +1189,14 @@ async def _deploy_via_containers( db_web_url = pgweb_sb.tunnel_urls[DB_WEB_PORT] + "/" if pgweb_sb else None db_mcp_url = db_mcp_sb.tunnel_urls[DB_MCP_CONTAINER_PORT] + "/mcp" if db_mcp_sb else None + served = await self._served_consoles(gateway_url, consoles, control_token) return DeployedGateway( gateway_url=gateway_url, mcp_url=_mcp_url(gateway_url, card), db_web_url=db_web_url, db_mcp_url=db_mcp_url, + db_web_gateway_url=served.get(PGWEB_SERVICE_NAME), + db_mcp_gateway_url=served.get(DB_MCP_SERVICE_NAME), website_frontend_urls=None, mcp_server_name=mcp_server_name, env_state_instance_ids=[state_instance.instance_id], @@ -1173,6 +1208,32 @@ async def _deploy_via_containers( await self.close() raise + async def _served_consoles(self, gateway_url: str, consoles: Iterable[str], + control_token: str | None) -> dict[str, str]: + """Each of ``consoles`` at the gateway, by key, that the gateway guards and reaches: it refuses a request without + its control token, and with the token it gets the console's answer rather than a 5xx. An older gateway image + answers 404, and a console the gateway can't reach (a server bound to an address family the private network + lacks) leaves it a 502, so the record names neither.""" + keys = list(consoles) + if not keys or not control_token: + return {} + + async def served(client: httpx.AsyncClient, key: str) -> bool: + url = f"{gateway_url}/svc/{key}/" + if (bare := await _console_answer(client, url, {})) != 401: + logger.warning(f"the gateway answered {bare}, not 401, at /svc/{key}/: the record names no {key}") + return False + if not isinstance(answer := await _console_answer(client, url, control_headers(control_token)), int) \ + or answer >= 500: + logger.warning(f"the gateway answered {answer} with its token at /svc/{key}/: it can't reach {key}, so " + f"the record names none") + return False + return True + + async with httpx.AsyncClient(timeout=_CONSOLE_PROBE_TIMEOUT_S) as client: + found = await asyncio.gather(*(served(client, key) for key in keys)) + return {key: f"{gateway_url}/svc/{key}{_CONSOLE_PATHS[key]}" for key, ok in zip(keys, found) if ok} + async def _refuse_tool_name_clashes(self, gateway_url: str) -> None: """Refuse the deploy when the gateway reports tool names more than one of its sources serves, which leaves it serving none of its servers' tools. A gateway whose /state can't be read, or that doesn't report clashes (an @@ -1467,7 +1528,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 @@ -1700,6 +1761,8 @@ def _compose_name_problems(mcp_servers: list[MCPServerConfig], website_configs: problems += [f"two of its services would both be named {name!r}" for name, count in services.items() if count > 1] problems += [f"environment name {name!r} is one a gateway deploy names its own containers " f"({', '.join(sorted(GATEWAY_SERVICE_NAMES))})" for name in services if name in GATEWAY_SERVICE_NAMES] + problems += [f"website name {w.environment_name!r} is the /svc key of a SQL console the gateway serves" + for w in website_configs or [] if w.environment_name in _CONSOLE_PATHS] return problems @@ -1759,6 +1822,10 @@ def _http_probe(port: int, *paths: str) -> str: return f"{pick}else exit 1; fi; for u in {urls}; do get \"$$u\" 2>/dev/null && exit 0; done; exit 1" +# Where each SQL console's users open it under its /svc// route: pgweb's UI, db-mcp's MCP endpoint. +_CONSOLE_PATHS = {PGWEB_SERVICE_NAME: "/", DB_MCP_SERVICE_NAME: "/mcp"} + + def _network_lines(*networks: str) -> list[str]: return [" networks:", *(f" - {network}" for network in networks)] @@ -1777,11 +1844,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]: @@ -1816,6 +1882,10 @@ def _seconds(seconds: float) -> str: # Budget for reading the gateway's /state once its card is served: answering it runs tool discovery, one server at a # time, if startup's didn't complete. _STATE_READ_TIMEOUT_S = 60.0 +# Asking the gateway for each SQL console at deploy: each request's budget, and how often and how far apart it asks. +_CONSOLE_PROBE_TIMEOUT_S = 30.0 +_CONSOLE_RETRY_PAUSE_S = 5.0 +_CONSOLE_ATTEMPTS = 4 # Cap on the post-readiness tools/list probe; it only logs, so a slow gateway costs deploy time, never the deploy. _TOOLS_PROBE_TIMEOUT_S = 10.0 diff --git a/src/agent_env/providers/env_state/env_state_provider.py b/src/agent_env/providers/env_state/env_state_provider.py index f0e1ff93d..ef031fc56 100644 --- a/src/agent_env/providers/env_state/env_state_provider.py +++ b/src/agent_env/providers/env_state/env_state_provider.py @@ -207,6 +207,11 @@ def render_sidecar_containers( UIs). Optional: a backend may have none, in which case this returns an empty list.""" return [] + def console_urls(self) -> dict[str, str]: + """The SQL consoles ``render_sidecar_containers`` emits, by service name, at their addresses on the env's + network; the gateway serves each behind its control token. Empty for a backend without sidecars.""" + return {} + def render_compose_containers( self, environment_names: list[str], diff --git a/src/agent_env/providers/env_state/local_postgres.py b/src/agent_env/providers/env_state/local_postgres.py index 154d1e120..21fa4e238 100644 --- a/src/agent_env/providers/env_state/local_postgres.py +++ b/src/agent_env/providers/env_state/local_postgres.py @@ -314,6 +314,10 @@ def rendered_sidecar_service_names(self) -> list[str]: names.append(DB_MCP_SERVICE_NAME) return names + def console_urls(self) -> dict[str, str]: + ports = {PGWEB_SERVICE_NAME: DB_WEB_PORT, DB_MCP_SERVICE_NAME: DB_MCP_CONTAINER_PORT} + return {name: f"http://{name}:{ports[name]}" for name in self.rendered_sidecar_service_names()} + @staticmethod def _in_image_store(image: str | None) -> bool: """Whether the image store serving ``image`` owns it: the container path pulls with that @@ -369,7 +373,9 @@ def sidecar_specs(self, *, instance: EnvStateInstance | None = None) -> list[Con specs.append(ContainerSpec( name=DB_MCP_SERVICE_NAME, image=cfg.db_mcp_image, port=DB_MCP_CONTAINER_PORT, env={"DATABASE_URI": db_mcp_uri}, - command=["--transport=streamable-http", "--streamable-http-host=0.0.0.0", "--access-mode=unrestricted"], + # An empty host binds every address family. The gateway reaches it over Modal's private network, which + # is IPv6 only, and 0.0.0.0 would serve IPv4 alone. + command=["--transport=streamable-http", "--streamable-http-host=", "--access-mode=unrestricted"], )) elif cfg.db_mcp_image: logger.warning(f"db-mcp image {cfg.db_mcp_image} is not in the image store; skipping db-mcp provisioning") 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/integration/env/gateway/gateway_test.py b/tst/integration/env/gateway/gateway_test.py index 86b1977c9..a3a86efb1 100644 --- a/tst/integration/env/gateway/gateway_test.py +++ b/tst/integration/env/gateway/gateway_test.py @@ -18,6 +18,7 @@ from typing import NamedTuple from mcp import ClientSession from mcp.client.streamable_http import streamable_http_client +from mcp.shared._httpx_utils import create_mcp_http_client # Each test deploys a real GatewayEnv + MCP servers on sandbox VMs # (~5-15 min per test). Mark the entire module as slow. @@ -643,8 +644,8 @@ async def assert_generated_data(session, tools_result, tool_names): assert looked_up.instance_id == result.instance_id assert looked_up.gateway_url == result.gateway_url assert looked_up.mcp_url == result.mcp_url - assert looked_up.db_web_url == result.db_web_url - assert looked_up.db_mcp_url == result.db_mcp_url + assert looked_up.db_web_gateway_url == result.db_web_gateway_url + assert looked_up.db_mcp_gateway_url == result.db_mcp_gateway_url assert looked_up.environment_card_url == result.environment_card_url assert looked_up.sandbox_id == result.sandbox_id assert looked_up.gateway_mode == GatewayMode.PERFORMANCE.value @@ -1243,7 +1244,9 @@ async def assert_changelog_empty(session, tools_result, tool_names): logger.info(f"Changelog count after load: {content_text}") assert content_text == "[{'cnt': 0}]", f"Expected empty changelog after load, got {content_text}" - await _verify_list_tools(mcp_url=result.db_mcp_url, tool_verifier_callback=assert_changelog_empty) + assert result.db_mcp_gateway_url, "the deploy recorded no db-mcp at the gateway" + await _verify_list_tools(mcp_url=result.db_mcp_gateway_url, headers=result.control_headers_for(result.db_mcp_gateway_url), + tool_verifier_callback=assert_changelog_empty) # Make a modification via MCP tool async def send_email_for_changelog(session, tools_result, tool_names): @@ -1266,7 +1269,9 @@ async def assert_changelog_has_entry(session, tools_result, tool_names): assert "email" in content_text, f"Expected schema_name 'email' in changelog, got {content_text}" assert "INSERT" in content_text, f"Expected INSERT operation in changelog, got {content_text}" - await _verify_list_tools(mcp_url=result.db_mcp_url, tool_verifier_callback=assert_changelog_has_entry) + assert result.db_mcp_gateway_url, "the deploy recorded no db-mcp at the gateway" + await _verify_list_tools(mcp_url=result.db_mcp_gateway_url, headers=result.control_headers_for(result.db_mcp_gateway_url), + tool_verifier_callback=assert_changelog_has_entry) rehydrated = await MultiEnv.from_deployed_env(result) assert rehydrated._env_provider is not None @@ -1309,7 +1314,9 @@ async def assert_probe_in_changelog(session, tools_result, tool_names): logger.info(f"Post-rehydrate changelog query: {content_text}") assert rehydrate_probe_subject in content_text, f"Expected probe subject in changelog (triggers re-installed via rehydrated provider), got {content_text}" - await _verify_list_tools(mcp_url=result.db_mcp_url, tool_verifier_callback=assert_probe_in_changelog) + assert result.db_mcp_gateway_url, "the deploy recorded no db-mcp at the gateway" + await _verify_list_tools(mcp_url=result.db_mcp_gateway_url, headers=result.control_headers_for(result.db_mcp_gateway_url), + tool_verifier_callback=assert_probe_in_changelog) finally: await multi_env.close() @@ -1673,7 +1680,7 @@ async def _verify_step_api(gateway_url: str, tool_verifier_callback: callable): logger.info("/step test passed!") -async def _verify_list_tools(mcp_url: str, tool_verifier_callback: callable): +async def _verify_list_tools(mcp_url: str, tool_verifier_callback: callable, headers: dict[str, str] | None = None): """Connect to gateway and verify tools are available. Args: @@ -1685,7 +1692,8 @@ async def _verify_list_tools(mcp_url: str, tool_verifier_callback: callable): logger.info(f"Testing gateway via tunnel (attempt {attempt + 1}/{max_retries})...") verified = False try: - async with streamable_http_client(mcp_url) as (read_stream, write_stream, _): + async with create_mcp_http_client(headers=headers) as http_client, \ + streamable_http_client(mcp_url, http_client=http_client) as (read_stream, write_stream, _): async with ClientSession(read_stream, write_stream) as session: await session.initialize() tools_result = await session.list_tools() diff --git a/tst/unit/bundle/run_teardown_test.py b/tst/unit/bundle/run_teardown_test.py index b5f1a501c..ef1b8e9f3 100644 --- a/tst/unit/bundle/run_teardown_test.py +++ b/tst/unit/bundle/run_teardown_test.py @@ -489,7 +489,7 @@ def test_the_keep_listing_names_every_sandbox_it_counts_with_the_records_behind_ deployed_sandboxes=[DeployedSandbox(sandbox_name="box", sandbox_id="sb-box", sandbox_mode="vm", sandbox_type="fake", tunnel_urls={"8080": "http://t"})], deployed_envs=[DeployedGatewayEnv(env_id="shop", env_version=1, gateway_url="http://g", mcp_url="http://m", - db_web_url="http://pgweb", sandbox_id="sb-gw", sandbox_type="fake", + db_web_gateway_url="http://gw/svc/pgweb/", sandbox_id="sb-gw", sandbox_type="fake", sandbox_ids={"service_db": {"orders": "sb-db"}})], deployed_agents=[DeployedAgent(agent_name="solver", api_url="http://a", a2a_url="http://a2a", sandbox_id="sb-box", sandbox_type="fake")], @@ -502,7 +502,7 @@ def test_the_keep_listing_names_every_sandbox_it_counts_with_the_records_behind_ "sb-gw fake env shop", " mcp http://m", " gateway http://g", - " pgweb http://pgweb", + " pgweb http://gw/svc/pgweb/", "sb-db fake env shop", ] diff --git a/tst/unit/cli/deployed_env_output_test.py b/tst/unit/cli/deployed_env_output_test.py index b3abb0748..05b7694ee 100644 --- a/tst/unit/cli/deployed_env_output_test.py +++ b/tst/unit/cli/deployed_env_output_test.py @@ -42,10 +42,33 @@ def test_env_get_instance_prints_the_gateway_url_only_for_a_gateway(deployed, ga def test_task_run_prints_a_gateway_record_as_before_and_omits_a_missing_gateway(): assert _format_env(_FRONTED).splitlines()[4:8] == [ - " gateway_url: https://gw.example", " mcp_url: https://gw.example/mcp", " db_web_url: None", " db_mcp_url: None"] + " gateway_url: https://gw.example", " mcp_url: https://gw.example/mcp", " db_web_gateway_url: None", + " db_mcp_gateway_url: None"] assert "gateway_url" not in _format_env(_BARE) and " mcp_url: https://srv.example/mcp" in _format_env(_BARE) +_CONSOLES = DeployedGatewayEnv(env_id="e1", env_version=1, gateway_url="https://gw.example", + mcp_url="https://gw.example/mcp", sandbox_id="gw", instance_id="i1", + db_web_url="https://tunnel-8081.example/", db_mcp_url="https://tunnel-18767.example/mcp", + db_web_gateway_url="https://gw.example/svc/pgweb/", + db_mcp_gateway_url="https://gw.example/svc/db-mcp/mcp") + + +def test_the_cli_prints_the_sql_consoles_at_the_gateway_and_never_their_tunnels(): + async def fake_deploy(**kwargs): + return _CONSOLES + + with patch("agent_env.cli.env.deploy.Env") as Env, patch("agent_env.providers.build_sandbox_provider"): + Env.get.return_value = MagicMock(id="e1", version=1, type="mcp_server", deploy=fake_deploy) + deployed = CliRunner().invoke(env_cli, ["deploy", "--id", "e1"]).output + with patch("agent_env.env.store.get_env_instance_store") as store: + store.return_value.get.return_value = _CONSOLES + got = CliRunner().invoke(env_cli, ["get-instance", "--id", "i1"]).output + for output in (deployed, got, _format_env(_CONSOLES)): + assert "https://gw.example/svc/pgweb/" in output and "https://gw.example/svc/db-mcp/mcp" in output + assert "tunnel-" not in output + + def test_a_record_outside_our_sandboxes_prints_no_sandbox(): with patch("agent_env.env.store.get_env_instance_store") as store: store.return_value.get.return_value = _HOSTED 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..d286b279f 100644 --- a/tst/unit/env/envs/test_multi_env_computers.py +++ b/tst/unit/env/envs/test_multi_env_computers.py @@ -38,7 +38,7 @@ from tst.util.sandbox_providers import mock_provider GATEWAY = "https://gw.example" -#: The gateway's control token, which it hands the computers it fronts. +#: The gateway's control token, which no computer it fronts is given. GATEWAY_TOKEN = "the-gateways" @@ -187,7 +187,11 @@ def test_a_computer_name_of_fifteen_characters_is_taken(): ["'mcp-slack' is the gateway's route to MCP server 'slack', and the gateway knows a computer by its name alone"]), (["mcp-slack"], {"websites": ["slack"]}, []), (["desktop"], {"mcp_servers": ["shop"], "websites": ["shop"]}, []), # an MCP server and a website may share a name -], ids=["two-computers", "a-server", "a-website", "a-servers-route", "a-websites-isnt", "server-and-website"]) + (["pgweb", "db-mcp"], {}, + ["'pgweb' is the gateway's route to a SQL console, and the gateway knows a computer by its name alone", + "'db-mcp' is the gateway's route to a SQL console, and the gateway knows a computer by its name alone"]), +], ids=["two-computers", "a-server", "a-website", "a-servers-route", "a-websites-isnt", "server-and-website", + "a-console"]) def test_a_computer_needs_a_name_no_other_child_env_or_route_of_the_gateways_has(computers, children, problems): assert _multi_computers.name_problems(computers, **children) == problems @@ -288,7 +292,7 @@ def gateway(monkeypatch, local_stores): async def deploy(self, env, sandbox_provider, *, children=None, **options): made.options.append({**options, "children": children}) for _ in range(made.tries): - made.started.append(await children(GATEWAY, GATEWAY_TOKEN) if children else None) + made.started.append(await children(GATEWAY) if children else None) if made.fails: raise made.fails return DeployedGatewayEnv(env_id=env.id, env_version=env.version, gateway_url=GATEWAY, sandbox_id="gw", @@ -304,8 +308,8 @@ async def close(self): @pytest.mark.asyncio -async def test_deploy_hands_the_gateway_each_computer_deployed_under_its_name_with_its_token_and_records_it(gateway, - providers): +async def test_deploy_hands_the_gateway_each_computer_deployed_under_its_name_with_its_own_token_and_records_it( + gateway, providers): desktop, laptop = FakeComputer("desktop"), FakeComputer("laptop") attribution = {"project_id": "6a6d2e30b2710a6cf93a6430"} @@ -314,12 +318,14 @@ async def test_deploy_hands_the_gateway_each_computer_deployed_under_its_name_wi child_envs={"desktop": {"sandbox_type": "modal", "cpu": 4, "env_params": {"form": "container"}}}) assert desktop.deploys == [{"ttl_seconds": 600, "attribution": attribution, "tool_prefix": "desktop_", "reach": GATEWAY, - "sites_later": False, "control_token": GATEWAY_TOKEN, "sandbox_type": "modal", "cpu": 4, + "sites_later": False, "sandbox_type": "modal", "cpu": 4, "env_params": {"form": "container"}}] assert laptop.deploys == [{"ttl_seconds": 600, "attribution": attribution, "tool_prefix": "laptop_", "reach": GATEWAY, - "sites_later": False, "control_token": GATEWAY_TOKEN, "sandbox_type": "modal_vm"}] - assert gateway.started == [[ExternalChild("desktop", "https://desktop.example/mcp", "https://desktop.example"), - ExternalChild("laptop", "https://laptop.example/mcp", "https://laptop.example")]] + "sites_later": False, "sandbox_type": "modal_vm"}] + assert gateway.started == [[ + ExternalChild("desktop", "https://desktop.example/mcp", "https://desktop.example", None, "token-desktop"), + ExternalChild("laptop", "https://laptop.example/mcp", "https://laptop.example", None, "token-laptop")]] + assert GATEWAY_TOKEN not in {child.control_token for child in gateway.started[0]} assert deployed.child_envs == {name: dataclasses.asdict(_record(name)) for name in ("desktop", "laptop")} assert DeployedEnv.from_dict(dataclasses.asdict(deployed)).child_envs == deployed.child_envs assert deployed.sandbox_ids == {"gateway_server": "gw", "modal_vm": {"desktop": "sb-desktop", "laptop": "sb-laptop"}} @@ -931,13 +937,14 @@ async def test_a_browser_computer_deploys_as_a_computer_child_routing_the_sites_ sandbox_type="modal_vm", child_envs={"chromium": {"sandbox_type": "modal", "cpu": 2, "memory_mb": 4096}}) assert chromium.deploys == [{"ttl_seconds": 10800, "attribution": None, "tool_prefix": "chromium_", - "reach": GATEWAY, "sites_later": True, "control_token": GATEWAY_TOKEN, + "reach": GATEWAY, "sites_later": True, "live_hosts": ("github.test", "api.github.test"), "sandbox_type": "modal", "cpu": 2, "memory_mb": 4096, "env_params": {"site_routing": True}}] assert desktop.deploys[0]["sites_later"] is False - assert gateway.started == [[ExternalChild("desktop", "https://desktop.example/mcp", "https://desktop.example"), - ExternalChild("chromium", "https://chromium.example/mcp", "https://chromium.example")]] + assert gateway.started == [[ + ExternalChild("desktop", "https://desktop.example/mcp", "https://desktop.example", None, "token-desktop"), + ExternalChild("chromium", "https://chromium.example/mcp", "https://chromium.example", None, "token-chromium")]] assert set(deployed.child_envs) == {"desktop", "chromium"} assert chromium.log[-1] == ("routed", "chromium", ["shop"]) diff --git a/tst/unit/env/envs/test_multi_env_name.py b/tst/unit/env/envs/test_multi_env_name.py index 35d78b764..125dc3eee 100644 --- a/tst/unit/env/envs/test_multi_env_name.py +++ b/tst/unit/env/envs/test_multi_env_name.py @@ -66,6 +66,8 @@ def test_deployed_env_records_the_gateway_name(): async def test_a_deploy_records_the_mcp_url_and_name_its_gateway_card_gives(): card = {"name": "crm", "additionalInterfaces": [{"url": "/mcp", "transport": "mcp"}]} result = SimpleNamespace(gateway_url="https://gw.example", mcp_url="https://gw.example/mcp", db_web_url=None, db_mcp_url=None, + db_web_gateway_url="https://gw.example/svc/pgweb/", + db_mcp_gateway_url="https://gw.example/svc/db-mcp/mcp", website_frontend_urls=None, environment_card=card, environment_card_read_at_utc="t", env_state_instance_ids=[], mcp_server_name="crm", control_token="t0k") @@ -82,3 +84,5 @@ async def deploy_gateway(self, sandbox_provider, **kwargs): record = await MultiEnv(id="e", version=1, mcp_server_envs=[], name="crm").deploy() assert (type(record), record.env_provider_type, record.mcp_url, record.mcp_server_name, record.control_token) == ( DeployedGatewayEnv, "gateway", "https://gw.example/mcp", "crm", "t0k") + assert (record.db_web_gateway_url, record.db_mcp_gateway_url) == ( + "https://gw.example/svc/pgweb/", "https://gw.example/svc/db-mcp/mcp") 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/console_routes_test.py b/tst/unit/env/gateway/console_routes_test.py new file mode 100644 index 000000000..30a0257c3 --- /dev/null +++ b/tst/unit/env/gateway/console_routes_test.py @@ -0,0 +1,180 @@ +"""The env's SQL consoles (pgweb, db-mcp) are served behind /svc// only with the deploy's control token, which never +reaches them, and not at all by a gateway started without one.""" +from __future__ import annotations + +import asyncio +from urllib.parse import unquote, urlsplit + +import httpx +import pytest + +from agent_env.env.gateway import rest_proxy as rest_proxy_module +from agent_env.env.gateway.constants import CONSOLE_URLS_ENV +from agent_env.env.gateway.entrypoint import parse_name_url_map +from agent_env.env.gateway.gateway import Gateway + +TOKEN = "s3cret" +CONSOLES = {"pgweb": "http://pgweb:8081", "db-mcp": "http://db-mcp:8000"} +BACKING = {"mcp-svc": "http://svc:18765", "shop": "http://shop-backend:8000"} +_RealAsyncClient = httpx.AsyncClient + +# Every spelling that reaches a console: its root, its query API, db-mcp's MCP endpoint, and the same paths with dot +# segments, percent-encoding, doubled slashes or no trailing slash. +CONSOLE_PATHS = [("GET", "/svc/pgweb/"), ("GET", "/svc/pgweb"), ("GET", "/svc/pgweb/api/query?query=SELECT%201"), + ("POST", "/svc/pgweb/api/query"), ("GET", "/svc/pgweb/static/js/app.js"), + ("GET", "/svc/pgweb/x/../api/query"), ("GET", "/svc/%70gweb/api/query"), + ("GET", "/svc/pgweb//api/query"), ("GET", "/svc/pgweb/public%2Fx/../api/query"), + ("POST", "/svc/db-mcp/mcp"), ("GET", "/svc/db-mcp/mcp"), ("DELETE", "/svc/db-mcp/mcp"), + ("POST", "/svc/db-mcp/./mcp"), ("POST", "/svc/db-%6dcp/mcp"), ("POST", "/svc/db-mcp/%6dcp")] + + +class _Upstream: + """Every service behind the gateway: answers each request as an MCP server would, and keeps what reached it.""" + + def __init__(self, monkeypatch): + self.requests: list[tuple[str, str, 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.requests.append((request.url.host, request.url.path, request.headers.get("authorization"))) + + async def body(): + yield b'event: message\ndata: {"jsonrpc": "2.0", "id": 1, "result": {}}\n\n' + + return httpx.Response(200, headers={"content-type": "text/event-stream", "mcp-session-id": "abc"}, content=body()) + + @property + def console_hosts(self) -> list[str]: + return [host for host, _, _ in self.requests if host in ("pgweb", "db-mcp")] + + +async def _send(gw: Gateway, method: str, path: str, headers: dict[str, str]) -> tuple[int, dict[bytes, bytes]]: + """One request through the gateway's served app with its path as uvicorn hands it: percent-decoded, its dot + segments and doubled slashes kept. Returns the status and the response headers.""" + url = urlsplit(path) + scope = {"type": "http", "asgi": {"version": "3.0", "spec_version": "2.3"}, "http_version": "1.1", "method": method, + "scheme": "http", "path": unquote(url.path), "raw_path": url.path.encode(), + "query_string": url.query.encode(), "root_path": "", "server": ("gateway", 80), "client": ("agent", 1), + "headers": [(b"content-type", b"application/json"), + *((name.lower().encode(), value.encode()) for name, value in headers.items())]} + received, started = False, [] + + async def receive(): + nonlocal received + if not received: + received = True + return {"type": "http.request", "body": b'{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}', + "more_body": False} + await asyncio.Event().wait() + + async def send(message): + if message["type"] == "http.response.start": + started.append((message["status"], dict(message.get("headers", ())))) + + await gw._asgi_app()(scope, receive, send) + return started[0] + + +def _gateway(token: str | None, consoles: dict[str, str] | None = None) -> Gateway: + return Gateway(host="127.0.0.1", port=0, server_name="unit", internal_mcp_servers=[], control_token=token, + rest_proxy_urls=dict(BACKING), website_urls={"shop": BACKING["shop"]}, + console_urls=CONSOLES if consoles is None else consoles) + + +@pytest.mark.asyncio +@pytest.mark.parametrize("method, path", CONSOLE_PATHS) +@pytest.mark.parametrize("headers", [{}, {"Authorization": "Bearer wrong"}, {"Authorization": TOKEN}], + ids=["none", "wrong", "not-bearer"]) +async def test_a_console_refuses_a_request_without_the_token(monkeypatch, method, path, headers): + upstream = _Upstream(monkeypatch) + status, _ = await _send(_gateway(TOKEN), method, path, headers) + assert status == 401 + assert upstream.requests == [] + + +@pytest.mark.asyncio +@pytest.mark.parametrize("method, path, host, sent", [ + ("GET", "/svc/pgweb/", "pgweb", "/"), ("GET", "/svc/pgweb/api/query", "pgweb", "/api/query"), + ("GET", "/svc/pgweb/static/js/app.js", "pgweb", "/static/js/app.js"), + ("GET", "/svc/pgweb/x/../api/query", "pgweb", "/api/query"), + ("POST", "/svc/db-mcp/mcp", "db-mcp", "/mcp"), ("DELETE", "/svc/db-mcp/mcp", "db-mcp", "/mcp")]) +async def test_a_console_answers_a_request_with_the_token_which_it_never_sees(monkeypatch, method, path, host, sent): + upstream = _Upstream(monkeypatch) + status, headers = await _send(_gateway(TOKEN), method, path, {"Authorization": f"Bearer {TOKEN}"}) + assert status == 200 + assert upstream.requests == [(host, sent, None)] + assert headers[b"mcp-session-id"] == b"abc" + + +@pytest.mark.asyncio +@pytest.mark.parametrize("path", ["/svc/mcp-svc/../pgweb/api/query", "/svc/shop/../db-mcp/mcp", + "/svc/mcp-svc/x%2F..%2F..%2Fpgweb/api/query", "/svc/PGWEB/api/query", + "/svc//pgweb/api/query", "/website/shop/../../svc/pgweb/api/query", + "/svc/pgweb%2Fapi/query"]) +@pytest.mark.parametrize("headers", [{}, {"Authorization": f"Bearer {TOKEN}"}], ids=["none", "token"]) +async def test_no_other_route_reaches_a_console(monkeypatch, path, headers): + upstream = _Upstream(monkeypatch) + await _send(_gateway(TOKEN), "POST", path, headers) + assert upstream.console_hosts == [] + + +@pytest.mark.asyncio +@pytest.mark.parametrize("method, path", CONSOLE_PATHS) +async def test_a_gateway_started_without_a_token_serves_no_console(monkeypatch, method, path): + upstream = _Upstream(monkeypatch) + status, _ = await _send(_gateway(None), method, path, {}) + assert status in (404, 307) # a bare /svc/pgweb is redirected to /svc/pgweb/, which is 404 too + assert upstream.requests == [] + + +@pytest.mark.asyncio +async def test_the_backing_servers_routes_are_unchanged_beside_the_consoles(monkeypatch): + upstream = _Upstream(monkeypatch) + status, _ = await _send(_gateway(TOKEN), "GET", "/svc/shop/api/orders", {}) + assert status == 200 + assert upstream.requests == [("shop-backend", "/api/orders", None)] + + +@pytest.mark.asyncio +async def test_consoles_alone_get_the_svc_route(monkeypatch): + upstream = _Upstream(monkeypatch) + gw = Gateway(host="127.0.0.1", port=0, server_name="unit", internal_mcp_servers=[], control_token=TOKEN, + console_urls=CONSOLES) + assert (await _send(gw, "POST", "/svc/db-mcp/mcp", {}))[0] == 401 + assert (await _send(gw, "POST", "/svc/db-mcp/mcp", {"Authorization": f"Bearer {TOKEN}"}))[0] == 200 + assert upstream.requests == [("db-mcp", "/mcp", None)] + + +def test_a_console_cannot_share_a_backing_servers_key(): + with pytest.raises(ValueError, match="shop"): + _gateway(TOKEN, {"shop": "http://pgweb:8081"}) + + +@pytest.mark.asyncio +async def test_a_write_through_a_console_opens_no_write_window(monkeypatch): + """Only a holder of the control token reaches a console, so what it writes there is credited to no role; a backing + server's write beside it still is.""" + upstream = _Upstream(monkeypatch) + gw = _gateway(TOKEN) + changelog, events = iter(range(1, 100)), [] + + async def log_event(event): + events.append(event) + return "event" + + monkeypatch.setattr(gw, "_query_changelog_id", lambda: next(changelog)) + monkeypatch.setattr(gw, "_log_event", log_event) + for path in ("/svc/db-mcp/mcp", "/svc/pgweb/api/query"): + assert (await _send(gw, "POST", path, {"Authorization": f"Bearer {TOKEN}"}))[0] == 200 + assert (await _send(gw, "POST", "/svc/shop/api/orders", {}))[0] == 200 + assert [(e["event_type"], e["service"]) for e in events] == [("http_request", "shop")] + assert upstream.console_hosts == ["db-mcp", "pgweb"] + + +@pytest.mark.parametrize("value, error", [("pgweb", "Invalid CONSOLE_URLS entry: 'pgweb'"), + ("pgweb=http://a:1,pgweb=http://b:2", "Duplicate service name in CONSOLE_URLS")]) +def test_a_bad_console_entry_names_its_own_variable(monkeypatch, value, error): + monkeypatch.setenv(CONSOLE_URLS_ENV, value) + with pytest.raises(ValueError, match=f"^{error}"): + parse_name_url_map(CONSOLE_URLS_ENV) 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 a30119dba..64802abf8 100644 --- a/tst/unit/env/test_env.py +++ b/tst/unit/env/test_env.py @@ -274,10 +274,13 @@ def test_a_card_without_a_name_leaves_the_server_name_unset(): ({"env_provider_type": "newer", "sandbox_id": "sb"}, DeployedSandboxEnv, "newer"), ({"sandbox_id": "sb"}, DeployedSandboxEnv, None), ({"gateway_url": None, "db_web_url": "https://pg/", "sandbox_id": "sb"}, DeployedGatewayEnv, "gateway"), + ({"gateway_url": None, "db_web_gateway_url": "https://gw/svc/pgweb/", "sandbox_id": "sb"}, DeployedGatewayEnv, + "gateway"), ({}, DeployedSandboxEnv, None), ({"env_provider_type": "newer"}, DeployedEnv, "newer"), ], ids=["gateway", "gateway-type-without-its-url", "before-the-type", "null-type", "newer-type-with-a-gateway", "newer-type-with-a-sandbox", - "sandbox-shape", "gateway-data-without-its-url", "untyped-without-a-sandbox", "newer-type-without-a-sandbox"]) + "sandbox-shape", "gateway-data-without-its-url", "gateway-console-without-its-url", + "untyped-without-a-sandbox", "newer-type-without-a-sandbox"]) def test_a_stored_record_loads_as_its_type_or_else_its_shape_keeping_every_field(doc, cls, provider_type): record = DeployedEnv.from_dict({"env_id": "e", "env_version": 1, "mcp_url": "https://m/mcp", "unknown_key": 1, **doc}) assert (type(record), record.env_provider_type, record.mcp_url) == (cls, provider_type, "https://m/mcp") @@ -296,6 +299,8 @@ def test_a_gateway_record_is_filled_the_way_it_always_was(): sandbox_ids={"mcp_server": {"slack": "srv"}}, environment_card_url=_CARD_URL, environment_card=_CARD), DeployedGatewayEnv(env_id="e", env_version=1, gateway_url="https://gw.example/sb/x", gateway_mode="consistent", sandbox_id="gw", sandbox_type="modal_vm", sandbox_ids={"gateway_server": "gw"}, db_web_url="https://pg/", db_mcp_url="https://dm/mcp", + db_web_gateway_url="https://gw.example/sb/x/svc/pgweb/", + db_mcp_gateway_url="https://gw.example/sb/x/svc/db-mcp/mcp", website_frontend_urls={"shop": "https://gw/shop/"}, vnc_url="https://vnc", env_state_instance_ids=["st-1"], environment_card_url=_CARD_URL, environment_card=_CARD, environment_card_read_at_utc="2026-09-28T00:00:00+00:00", metadata={"k": "v"}, instance_id="i1", created_at_utc="c", expires_at_utc="x"), @@ -409,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 ab9588196..bebefa2c4 100644 --- a/tst/unit/providers/env_providers/env_gateway_provider_test.py +++ b/tst/unit/providers/env_providers/env_gateway_provider_test.py @@ -344,6 +344,7 @@ async def _spy_acquire(self, ctx): # Patch _wait_for_tunnel to skip the real HTTP poll; it returns the card it read gp._wait_for_tunnel = AsyncMock(return_value=_CARD) gp._refuse_tool_name_clashes = AsyncMock() + gp._served_consoles = AsyncMock(return_value={}) # Patch Env.get and config to return mock envs with patch("agent_env.env.env.Env.get") as env_get, \ patch("agent_env.config.get_config") as get_cfg, \ @@ -462,6 +463,7 @@ async def fake_create_container(**kwargs): with patch.object(provider, "create_container", side_effect=fake_create_container): gp._wait_for_tunnel = AsyncMock(return_value=_CARD) gp._refuse_tool_name_clashes = AsyncMock() + gp._served_consoles = AsyncMock(return_value={}) with patch("agent_env.env.env.Env.get") as env_get, \ patch("agent_env.config.get_config") as get_cfg: gateway_env = MagicMock() @@ -521,6 +523,7 @@ async def fake_create_container(**kwargs): with patch.object(provider, "create_container", side_effect=fake_create_container): gp._wait_for_tunnel = AsyncMock(return_value=card) gp._refuse_tool_name_clashes = AsyncMock() + gp._served_consoles = AsyncMock(return_value={}) with patch("agent_env.env.env.Env.get") as env_get, patch("agent_env.config.get_config") as get_cfg: env_get.return_value.docker_image_artifact = _image("agent-gateway") get_cfg.return_value = MagicMock(default_gateway_env_id="gw-id") @@ -601,6 +604,7 @@ def _slack_in_containers(gp: EnvironmentGatewayProvider, provider: ModalSandboxP gp._init_service_db_via_exec = AsyncMock() gp._wait_for_tunnel = AsyncMock(return_value=_CARD) gp._refuse_tool_name_clashes = AsyncMock() + gp._served_consoles = AsyncMock(return_value={}) with patch("agent_env.env.env.Env.get") as env_get, \ patch("agent_env.config.get_config") as get_cfg: gateway_env = MagicMock() @@ -2884,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 @@ -2893,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(): @@ -2952,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): @@ -2979,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"),)] @@ -2998,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": @@ -3042,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() @@ -3052,6 +3061,7 @@ async def children(reach, control_token): gp._init_service_db_via_exec = AsyncMock() gp._wait_for_tunnel = AsyncMock(return_value=_CARD) gp._refuse_tool_name_clashes = AsyncMock() + gp._served_consoles = AsyncMock(return_value={}) with patch.object(provider, "create_container", side_effect=fake_create_container), \ patch("agent_env.env.env.Env.get", side_effect=lambda env_id, *a, **k: gateway_env if env_id == "gw-id" else db_env), \ patch("agent_env.config.get_config", return_value=MagicMock(default_gateway_env_id="gw-id", default_service_db_env_id="db-id")): @@ -3062,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" @@ -3111,3 +3122,107 @@ def test_a_site_image_without_curl_passes_its_health_probe_once_its_health_path_ def test_a_site_answering_only_errors_fails_its_health_probe(tmp_path): assert _run_probe(tmp_path, {"/.well-known/agent-env.json": 500, "/api/health": 503}) != 0 + + +_TIMEOUT = httpx.ReadTimeout("slow") +_REFUSED = httpx.ConnectError("refused") +_DROPPED = httpx.RemoteProtocolError("Server disconnected without sending a response.") +_GUARDED = {"pgweb": ([401], [200]), "db-mcp": ([401], [404])} +_BOTH = {"pgweb": "https://gw.example/svc/pgweb/", "db-mcp": "https://gw.example/svc/db-mcp/mcp"} + + +@pytest.mark.asyncio +@pytest.mark.parametrize("answers, recorded", [ + pytest.param(_GUARDED, _BOTH, id="both-guarded-and-reached"), + pytest.param({**_GUARDED, "db-mcp": ([401], [502] * 3)}, {"pgweb": _BOTH["pgweb"]}, id="db-mcp-unreachable"), + pytest.param({**_GUARDED, "db-mcp": ([401], [502, 404])}, _BOTH, id="db-mcp-up-on-the-second-ask"), + pytest.param({**_GUARDED, "pgweb": ([_TIMEOUT, 401], [200])}, _BOTH, id="pgweb-slow-once"), + pytest.param({**_GUARDED, "pgweb": ([_TIMEOUT] * 3, [])}, {"db-mcp": _BOTH["db-mcp"]}, id="pgweb-silent"), + pytest.param({**_GUARDED, "pgweb": ([_DROPPED, 401], [_REFUSED, 200])}, _BOTH, id="pgweb-tunnel-drops-once"), + pytest.param({"pgweb": ([404], []), "db-mcp": ([404], [])}, {}, id="older-gateway"), + pytest.param({"pgweb": ([200], []), "db-mcp": ([200], [])}, {}, id="open"), + pytest.param({"pgweb": ([_REFUSED] * 3, []), "db-mcp": ([_REFUSED] * 3, [])}, {}, id="unreachable-gateway"), +]) +async def test_the_record_names_each_console_the_gateway_guards_and_reaches(monkeypatch, answers, recorded): + """A console counts when the gateway refuses it without the control token and, with the token, answers for it + rather than with a 5xx: an older gateway image answers 404, and a console bound where the gateway can't reach it + leaves the gateway a 502. A timeout, a dropped connection or a 5xx is asked again, three times in all here.""" + queues = {(key, with_token): list(replies) for key, (bare, token) in answers.items() + for with_token, replies in ((False, bare), (True, token))} + + def reply(request: httpx.Request) -> httpx.Response: + key = request.url.path.split("/")[2] + with_token = request.headers.get("authorization") == "Bearer tok" + answer = queues[key, with_token].pop(0) + if isinstance(answer, Exception): + raise answer + return httpx.Response(answer) + + real = httpx.AsyncClient + monkeypatch.setattr(httpx, "AsyncClient", lambda **kw: real(transport=httpx.MockTransport(reply), **kw)) + monkeypatch.setattr(env_gateway_provider, "_CONSOLE_RETRY_PAUSE_S", 0) + monkeypatch.setattr(env_gateway_provider, "_CONSOLE_ATTEMPTS", 3) + served = await EnvironmentGatewayProvider()._served_consoles("https://gw.example", ["pgweb", "db-mcp"], "tok") + assert served == recorded + + +@pytest.mark.asyncio +@pytest.mark.parametrize("consoles, token", [([], "tok"), (["pgweb", "db-mcp"], None)]) +async def test_a_deploy_without_consoles_or_a_token_asks_the_gateway_nothing(monkeypatch, consoles, token): + monkeypatch.setattr(httpx, "AsyncClient", MagicMock(side_effect=AssertionError("asked the gateway"))) + assert await EnvironmentGatewayProvider()._served_consoles("https://gw.example", consoles, token) == {} + + +@pytest.mark.parametrize("images, consoles", [ + ({"db_web_image": "pgweb:1", "db_mcp_image": "db-mcp:1"}, "pgweb=http://pgweb:8081,db-mcp=http://db-mcp:8000"), + ({"db_web_image": "pgweb:1"}, "pgweb=http://pgweb:8081"), ({}, None)], ids=["both", "pgweb", "none"]) +def test_compose_hands_the_gateway_the_sql_consoles_it_renders_on_their_network(images, consoles): + from agent_env.env.envs.service_db import ServiceDBConfig + + compose = EnvironmentGatewayProvider().create_docker_compose( + mcp_servers=[MCPServerConfig(image="mcp-slack", environment_name="slack")], gateway_image="agent-gateway", + state_provider=LocalPostgresStateProvider(service_db_config=ServiceDBConfig(**images)), + state_instance=LocalPostgresStateProvider.default_instance(), control_token="t0k") + services = yaml.safe_load(compose)["services"] + gateway = dict(item.split("=", 1) for item in services[GATEWAY_SERVICE_NAME]["environment"]) + assert gateway.get("CONSOLE_URLS") == consoles + for console in (consoles or "").split(","): + if console: + name = console.split("=", 1)[0] + assert set(services[name]["networks"]) & set(services[GATEWAY_SERVICE_NAME]["networks"]) + + +@pytest.mark.asyncio +async def test_container_mode_hands_the_gateway_its_consoles_on_the_private_network_and_records_them_there(monkeypatch): + """The gateway reaches pgweb and db-mcp at their private hosts, and the record names them under the gateway's URL + once the gateway refuses them without the token and serves them with it.""" + provider, gp = ModalSandboxProvider(), EnvironmentGatewayProvider() + made: dict[str, tuple[_FakeSandbox, dict]] = {} + + async def create_container(**kwargs): + name = kwargs["image_name"].rsplit("/", 1)[-1] + sandbox = _FakeSandbox(name, kwargs["port"], f"https://{name}.modal.host") + made[name] = (sandbox, kwargs) + return sandbox + + real = httpx.AsyncClient + monkeypatch.setattr(httpx, "AsyncClient", lambda **kw: real(transport=httpx.MockTransport( + lambda request: httpx.Response(404 if not request.url.path.startswith("/svc/") + else 200 if request.headers.get("authorization") == "Bearer t0k" else 401)), + **kw)) + with _slack_in_containers(gp, provider, create_container) as args: + del gp._served_consoles # the real check, asking the gateway + deployed = await gp._deploy_via_containers(sandbox_provider=provider, control_token="t0k", **args) + pgweb, db_mcp = made["pgweb"][0], made["db-mcp"][0] + assert made["agent-gateway"][1]["env"]["CONSOLE_URLS"] == ( + f"pgweb=http://{pgweb.private_host}:8081,db-mcp=http://{db_mcp.private_host}:8000") + assert (deployed.db_web_gateway_url, deployed.db_mcp_gateway_url) == ( + "https://agent-gateway.modal.host/svc/pgweb/", "https://agent-gateway.modal.host/svc/db-mcp/mcp") + + +@pytest.mark.parametrize("name", ["pgweb", "db-mcp"]) +def test_a_website_cant_take_a_consoles_svc_key(name): + from agent_env.providers.env_providers.env_gateway_provider import _compose_name_problems + + site = WebsiteConfig(backend_image="be", frontend_image=None, environment_name=name) + assert any("SQL console" in problem for problem in _compose_name_problems([], [site])) diff --git a/tst/unit/providers/env_state/test_env_state_provider.py b/tst/unit/providers/env_state/test_env_state_provider.py index 995075473..b5afda781 100644 --- a/tst/unit/providers/env_state/test_env_state_provider.py +++ b/tst/unit/providers/env_state/test_env_state_provider.py @@ -278,6 +278,9 @@ def test_sidecar_specs_skip_images_the_image_store_does_not_own(image_store, cap # contributor can't tear down the shared session the changelog export relies on. pgweb_spec = next(s for s in both if s.name == "pgweb") assert pgweb_spec.env["PGWEB_LOCK_SESSION"] == "true" + # The gateway reaches db-mcp over Modal's private network, which is IPv6 only, so it listens on every family. + db_mcp_spec = next(s for s in both if s.name == "db-mcp") + assert "--streamable-http-host=" in db_mcp_spec.command # pgweb from Docker Hub + unset db-mcp → neither, and a warning for the configured one only. none = LocalPostgresStateProvider(