diff --git a/AGENTS.md b/AGENTS.md index f44d3129a..e3f78a8bb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -123,7 +123,7 @@ and deserialized through a registry. | Package | Contents | |---|---| -| `env/` | `Env` base class: a subclass declares `type`, implements `from_dict` and `async deploy(...) -> DeployedEnv`, and may override `reset`, `close` and `load_file_artifact_universe`; teardown closes each env a run deployed before terminating its sandboxes by id. Built-ins in `env/envs/`: `MCPServerEnv` (`mcp_server`), `MultiEnv` (`multi`, MCP servers plus websites and computers; its website browser is the one its `browser_envs` names, none for `[]`, else the run's when it has websites: an MCP server env such as `playwright-mcp` runs among the gateway's MCP servers, and a browser computer such as `chromium` on a sandbox of its own as one more computer child, sized by its `child_envs` entry, its tools under its name and `_`, routing the multi env's synthetic sites unless that entry's `site_routing` says, its network its own env's, as any computer child's; a website env deployed alone refuses a browser computer as the run's browser), `ServiceDBEnv` (`service_db`, PostgreSQL), `WebsiteEnv` (`website`, one site: a server image, `backend_image` in its env.toml, serving the pages and API, ready when its card's `website/v1` `ready` answers a `WebsiteReadiness` that says so, as `agentenv_protocol.website` (`website_readiness`, `env_readiness`) defines a website env's health for the deploy and `DeployedEnv.readiness()` alike, or, for a card without `ready`, when its `health` path answers 200, which is deprecated; its env.toml's `ready_timeout_s`, how long it may take from its server's container starting to ready, is that container's health check `start_period` and what the deploy waits, or its card's `ready` timeout if longer, and its `shm_mb` is the container's `shm_size`, each left to the gateway and Docker without them; the gateway container's `env/gateway/constants.py` mirrors the URI and op, a test keeping them equal; a separate frontend image is deprecated, warned of at put and optional in a bundle, and a stored `backend_docker_image_artifact` reads as the server image; a live one, `live = true`, is a real site whose server serves none of its pages, its `live`, `domains` and `allow_hosts` read at put from its server's `@website(...)` (`utils/card_naming.py` `WebsiteSource`) unless given, its `settings`' secrets only as references the gateway resolves as it writes the site's container (`WEBSITE_SETTINGS_ENV`); the gateway gives it no site route, a computer's site table leaves it out, a computer whose network is an allowlist is let reach its names (`MultiEnv.live_hosts`), a browser alone's forward port takes them straight to the real site (`site_proxy.py` `direct`), as the browser base's stand-in proxy takes any host, refusing nothing, each proxy logging each such connection as a JSON line, and a run that deploys one is marked live, `reproducible: false`), `GatewayEnv` (`gateway_server`), `ComputerDriverEnv` (`computer_driver`, `env/envs/computer/driver_env.py`: a computer driver's files and what its class declares for each platform it supports, read at put in a process of its own, `agentenv_protocol.computer._declare`, where the driver's own dependencies needn't be installed, with the `port` it serves on and its install by OS, `[install.]`, or for one distribution `[install."/"]`, which replaces its OS type's there, as its `known_failures` do (`env/envs/computer/utils/install.py`): files, apt `packages` with extra `sources`, a `python` requirements file for a venv, `downloads` by URL and sha256, `run` scripts, the services the base's init runs, and `ports`; it deploys only as a computer env's driver), `ComputerEnv` (`computer`, in `env/envs/computer/`: a base computer and a driver, matched at put by gate 1 before anything is stored, then composed by `composer.py` into an image for each form and arch on a builder of the put's sandbox provider, by default the env's (`utils/builder.py`; `--sandbox` on `env build`, `bundle register` and `run`): this machine's Docker for `local`, else a VM of the provider, which fetches the put's stored files by signed URL, takes the rest inline and pushes to the image store itself, so it builds only with stores a remote VM reaches; each arch goes to the first link that runs it natively, else one that emulates it (a VM registers QEMU; `--no-emulate` leaves it `skipped` instead, for a later put), and its pair records the provider that built it (`builder`); a run or register that reuses a computer env composes what it has left (`pending`), a run only the forms its sandbox's deploys boot (`booted_forms`: on each link, the first form it boots natively, by the deploy's own rule, `boot.first_native`; a compose of a disk adds its container), and a deploy composes first what it boots that no compose started, and a container it runs natively that was built but not probed, as one whose probe a setting that didn't resolve stopped, booting it only once ready (`ComputerEnv.compose_unstarted`); tagged `agentenv-computers:` in the image store by a key of the image's Dockerfile, build context and lock so any env with the same inputs reuses it; every layer's packages, requirements and downloads are resolved at put in a container of the base for each arch (`utils/packages.py`, `utils/resolve_in_base.py`), stored in the object store by sha256 under `agentenv-packages/`, and listed in a lock stored by a digest of its inputs, which any env with the same inputs reuses, and builds install only the lock's files, every install step `RUN --network=none`; each pair's status goes into its metadata, `composed`, the arches built are written as its computer, a `computer` artifact over one index, and `agent-env env build` resumes what a put left; gate 3 (`utils/probing.py`) then boots each native build on the put's sandbox provider and probes it at `full`, making it `ready` or `failed`, and a build no provider runs natively stays `unverified`. Its deploy, through the `computer` env provider (`providers/env_providers/env_computer_provider.py`), boots its first `ready` build on a sandbox provider that runs its arch natively (`native_platforms()`), with no gateway in front and the driver's card as the env card, its `/dev/shm` the most its apps' Linux installs ask for (`shm_mb`, in MiB, which its composed computer and the deploy record keep; `--shm-size` on a container, `AGENTENV_SHM_MB` read by a Linux disk's init, passed only to a provider whose `SHARED_MEMORY` says it gives that much, else the sandbox's default, which the deploy logs), then checks its `display`; `deploy_env` `env_params` take a `form`, `computer_settings` (deploy-phase values of the base's settings; a secret one, here or on the env, only as a bare `secret:`/`env:` reference) and `driver_settings` (the driver's `ComputerSettings`, such as its default coordinate space); a `network` that allows nothing runs it on local Docker's internal network behind a relay (`providers/sandbox_providers/local_docker/relay/`); `reset` and `close` have the driver end its recordings first (`computer-recording/v1` `end_all`, each uploading what's left and its manifest under the grant it started with), and `reset` then boots a fresh container in its place (`reset_container`), keeping the computer's address but not an agent's MCP session to the old driver; its `load_file_artifact_universe` writes files under the session user's home through the driver's `data/add`, `Downloads` by default, each file's bytes through a read grant when the store's grants reach it and its network allows everything, else inline (`env/envs/computer/utils/inside.py`)), `ComputerAppEnv` (`computer_app`, `env/envs/computer/app_env.py`: an app on a computer, a `ComputerAppEnvironment` class its env.toml's `module` names, read at put by the same `_declare`, which declares each OS with its own decorator (`@linux(...)`, or `@install(os_type, spec)` for any OS type; `@linux(distribution=...)` or `@install("/", spec)` for one distribution, which replaces its OS type's there) holding its install, its launch and, optionally, a skill and settings and build settings that add to the class's there, and install steps and ready checks for every OS or those their `os=` names; everything that reads its settings, launch or steps asks for the computer's OS type; deployed alone it is a one-app computer env, a `ComputerEnv` of the computer and driver its env.toml names, the composer installing it under `/opt/agentenv/apps//` with its services as supervisord programs beside its own server (`agentenv_protocol.computer.serve_app`, in a venv with the protocol's `app` extra, on `.agentenv/server.sock` in its folder), which adds its launcher, launches a `boot` app once per boot and says through `computer-app/v1` whether it's ready, as the driver's `computer-ready` asks, its card named after it, and `env_params` `app_settings` handing it values of its `Settings` in `AGENTENV_APP_SETTINGS`, a secret one only as a bare reference, over its env.toml's `[settings]` and a computer env's `settings` beside it in `apps`, each by top-level field (`params.app_settings`; checked at put, a required one left to the deploy; the deploy record keeps the merged values as `app_settings`, secrets withheld); its env.toml's `build_settings`, values of its `BuildSettings` checked at put, are written to `.agentenv/build_settings.json` in its folder, so they're part of the image's key, its install steps read them, and a deploy can't change them). An env type whose services take environment data defines `load_environment_artifact` and `load_environment_universe_artifact`; `load_artifact` refuses an environment artifact aimed at a type that doesn't, at save and before it loads. An env built on the protocol SDK can serve agents a skill (`@agent_skill`, `skill/v1`), which `add_skills` `env_ids` installs under its environment name (behind a gateway, each server's under that server's name); a skill with files beside its SKILL.md goes as a bundle stored once per content under `agentenv-env-skills/` in the object store. `env/gateway/gateway.py` is the env-side gateway server, container-only code. Its site route, `/website//`, never forwards a site's data plane or card (`/agentenv/…`, `/.well-known/agent-env.json`), which agentenv reaches through `/svc//`; a site with no frontend image is served by its server image there. Its CDP route, `/browser//cdp//` (`env/gateway/browser_proxy.py`), reaches the website browser behind the `/svc` child ``, found from that child's card (it, or an app among its children, offering `browser/v1` `cdp` with `/cdp/` in its `computer-app/v1` `agent_routes`): it relays the browser's discovery and WebSocket both ways, each leg pinged every 20 s, and every CDP address the browser hands out, in `json/version`, `json/list` and its `cdp` answer through `/svc//`, comes back at the gateway, everything before `/cdp//` becoming the address the caller reached the gateway at and `/browser/`, keeping the https or wss of an address the browser minted under an origin its caller named, as `browser_connect_cdp` names the agent's, since a tunnel that ends TLS, as Modal's, may send no `X-Forwarded-Proto`; each connection is a `browser_connection` trajectory event, without its token. Its clock (`env/gateway/clock.py`) has one opaque version, a per-boot id and a count, that every `set_time`, `advance` and `clear` changes; `set_rate` (`/clock/set-rate`) changes an armed clock's rate from its time at the write, keeping its `t0` and generation as `advance` does, so time triggers keep their marks. Every clock change goes through `Gateway._change_clock`, which wakes the triggers when the change kept the clock's generation, answers the held watches and waits for the followers. Its followers, the computers on it (`CLOCK_FOLLOWER_TOKENS`, each child whose card serves `clock/v1` `sync_time`, by its read token, its control token for now), long-poll `/clock/watch` naming the version they show, each watch held up to the card's `hold_s` (`env/gateway/clock_followers.py`), and a write given `wait_followers_s` waits for each, answering 504 naming those behind, but not for one that hasn't watched for longer than a hold and a reconnect (`ClockFollowers.QUIET_S`), which it names at once with when each last watched; a restarted gateway is unarmed. While its clock is armed it serves agents `get_time` (`env/gateway/get_time.py`), which answers in UTC and 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`. | +| `env/` | `Env` base class: a subclass declares `type`, implements `from_dict` and `async deploy(...) -> DeployedEnv`, and may override `reset`, `close` and `load_file_artifact_universe`; teardown closes each env a run deployed before terminating its sandboxes by id. Built-ins in `env/envs/`: `MCPServerEnv` (`mcp_server`), `MultiEnv` (`multi`, MCP servers plus websites and computers; its website browser is the one its `browser_envs` names, none for `[]`, else the run's when it has websites: an MCP server env such as `playwright-mcp` runs among the gateway's MCP servers, and a browser computer such as `chromium` on a sandbox of its own as one more computer child, sized by its `child_envs` entry, its tools under its name and `_`, routing the multi env's synthetic sites unless that entry's `site_routing` says, its network its own env's, as any computer child's; a website env deployed alone refuses a browser computer as the run's browser), `ServiceDBEnv` (`service_db`, PostgreSQL), `WebsiteEnv` (`website`, one site: a server image, `backend_image` in its env.toml, serving the pages and API, ready when its card's `website/v1` `ready` answers a `WebsiteReadiness` that says so, as `agentenv_protocol.website` (`website_readiness`, `env_readiness`) defines a website env's health for the deploy and `DeployedEnv.readiness()` alike, or, for a card without `ready`, when its `health` path answers 200, which is deprecated; its env.toml's `ready_timeout_s`, how long it may take from its server's container starting to ready, is that container's health check `start_period` and what the deploy waits, or its card's `ready` timeout if longer, and its `shm_mb` is the container's `shm_size`, each left to the gateway and Docker without them; the gateway container's `env/gateway/constants.py` mirrors the URI and op, a test keeping them equal; a separate frontend image is deprecated, warned of at put and optional in a bundle, and a stored `backend_docker_image_artifact` reads as the server image; a live one, `live = true`, is a real site whose server serves none of its pages, its `live`, `domains` and `allow_hosts` read at put from its server's `@website(...)` (`utils/card_naming.py` `WebsiteSource`) unless given, its `settings`' secrets only as references the gateway resolves as it writes the site's container (`WEBSITE_SETTINGS_ENV`); the gateway gives it no site route, a computer's site table leaves it out, a computer whose network is an allowlist is let reach its names (`MultiEnv.live_hosts`), a browser alone's forward port takes them straight to the real site (`site_proxy.py` `direct`), as the browser base's stand-in proxy takes any host, refusing nothing, each proxy logging each such connection as a JSON line, and a run that deploys one is marked live, `reproducible: false`), `GatewayEnv` (`gateway_server`), `ComputerDriverEnv` (`computer_driver`, `env/envs/computer/driver_env.py`: a computer driver's files and what its class declares for each platform it supports, read at put in a process of its own, `agentenv_protocol.computer._declare`, where the driver's own dependencies needn't be installed, with the `port` it serves on and its install by OS, `[install.]`, or for one distribution `[install."/"]`, which replaces its OS type's there, as its `known_failures` do (`env/envs/computer/utils/install.py`): files, apt `packages` with extra `sources`, a `python` requirements file for a venv, `downloads` by URL and sha256, `run` scripts, the services the base's init runs, and `ports`; it deploys only as a computer env's driver), `ComputerEnv` (`computer`, in `env/envs/computer/`: a base computer and a driver, matched at put by gate 1 before anything is stored, then composed by `composer.py` into an image for each form and arch on a builder of the put's sandbox provider, by default the env's (`utils/builder.py`; `--sandbox` on `env build`, `bundle register` and `run`): this machine's Docker for `local`, else a VM of the provider, which fetches the put's stored files by signed URL, takes the rest inline and pushes to the image store itself, so it builds only with stores a remote VM reaches; each arch goes to the first link that runs it natively, else one that emulates it (a VM registers QEMU; `--no-emulate` leaves it `skipped` instead, for a later put), and its pair records the provider that built it (`builder`); a run or register that reuses a computer env composes what it has left (`pending`), a run only the forms its sandbox's deploys boot (`booted_forms`: on each link, the first form it boots natively, by the deploy's own rule, `boot.first_native`; a compose of a disk adds its container), and a deploy composes first what it boots that no compose started, and a container it runs natively that was built but not probed, as one whose probe a setting that didn't resolve stopped, booting it only once ready (`ComputerEnv.compose_unstarted`); tagged `agentenv-computers:` in the image store by a key of the image's Dockerfile, build context and lock so any env with the same inputs reuses it; every layer's packages, requirements and downloads are resolved at put in a container of the base for each arch (`utils/packages.py`, `utils/resolve_in_base.py`), stored in the object store by sha256 under `agentenv-packages/`, and listed in a lock stored by a digest of its inputs, which any env with the same inputs reuses, and builds install only the lock's files, every install step `RUN --network=none`; each pair's status goes into its metadata, `composed`, the arches built are written as its computer, a `computer` artifact over one index, and `agent-env env build` resumes what a put left; gate 3 (`utils/probing.py`) then boots each native build on the put's sandbox provider and probes it at `full`, making it `ready` or `failed`, and a build no provider runs natively stays `unverified`. Its deploy, through the `computer` env provider (`providers/env_providers/env_computer_provider.py`), boots its first `ready` build on a sandbox provider that runs its arch natively (`native_platforms()`), with no gateway in front and the driver's card as the env card, its `/dev/shm` the most its apps' Linux installs ask for (`shm_mb`, in MiB, which its composed computer and the deploy record keep; `--shm-size` on a container, `AGENTENV_SHM_MB` read by a Linux disk's init, passed only to a provider whose `SHARED_MEMORY` says it gives that much, else the sandbox's default, which the deploy logs), then checks its `display`; `deploy_env` `env_params` take a `form`, `computer_settings` (deploy-phase values of the base's settings; a secret one, here or on the env, only as a bare `secret:`/`env:` reference) and `driver_settings` (the driver's `ComputerSettings`, such as its default coordinate space); a `network` that allows nothing runs it on local Docker's internal network behind a relay (`providers/sandbox_providers/local_docker/relay/`); `reset` and `close` have the driver end its recordings first (`computer-recording/v1` `end_all`, each uploading what's left and its manifest under the grant it started with), and `reset` then boots a fresh container in its place (`reset_container`), keeping the computer's address but not an agent's MCP session to the old driver; its `load_file_artifact_universe` writes files under the session user's home through the driver's `data/add`, `Downloads` by default, each file's bytes through a read grant when the store's grants reach it and its network allows everything, else inline (`env/envs/computer/utils/inside.py`)), `ComputerAppEnv` (`computer_app`, `env/envs/computer/app_env.py`: an app on a computer, a `ComputerAppEnvironment` class its env.toml's `module` names, read at put by the same `_declare`, which declares each OS with its own decorator (`@linux(...)`, or `@install(os_type, spec)` for any OS type; `@linux(distribution=...)` or `@install("/", spec)` for one distribution, which replaces its OS type's there) holding its install, its launch and, optionally, a skill and settings and build settings that add to the class's there, and install steps and ready checks for every OS or those their `os=` names; everything that reads its settings, launch or steps asks for the computer's OS type; deployed alone it is a one-app computer env, a `ComputerEnv` of the computer and driver its env.toml names, the composer installing it under `/opt/agentenv/apps//` with its services as supervisord programs beside its own server (`agentenv_protocol.computer.serve_app`, in a venv with the protocol's `app` extra, on `.agentenv/server.sock` in its folder), which adds its launcher, launches a `boot` app once per boot and says through `computer-app/v1` whether it's ready, as the driver's `computer-ready` asks, its card named after it, and `env_params` `app_settings` handing it values of its `Settings` in `AGENTENV_APP_SETTINGS`, a secret one only as a bare reference, over its env.toml's `[settings]` and a computer env's `settings` beside it in `apps`, each by top-level field (`params.app_settings`; checked at put, a required one left to the deploy; the deploy record keeps the merged values as `app_settings`, secrets withheld); its env.toml's `build_settings`, values of its `BuildSettings` checked at put, are written to `.agentenv/build_settings.json` in its folder, so they're part of the image's key, its install steps read them, and a deploy can't change them). An env type whose services take environment data defines `load_environment_artifact` and `load_environment_universe_artifact`; `load_artifact` refuses an environment artifact aimed at a type that doesn't, at save and before it loads. An env built on the protocol SDK can serve agents a skill (`@agent_skill`, `skill/v1`), which `add_skills` `env_ids` installs under its environment name (behind a gateway, each server's under that server's name); a skill with files beside its SKILL.md goes as a bundle stored once per content under `agentenv-env-skills/` in the object store. `env/gateway/gateway.py` is the env-side gateway server, container-only code. Its site route, `/website//`, never forwards a site's data plane or card (`/agentenv/…`, `/.well-known/agent-env.json`), which agentenv reaches through `/svc//`; a site with no frontend image is served by its server image there. 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. `depends_on` (None means all prior steps) gates a step, independent steps run concurrently, `fail_task_on_error` makes a failure fatal or tolerated, `retry_config` rolls a failed span back through the step journal and re-dispatches it. Built-in steps live in `task_step/task_steps/` (`deploy_env`, `deploy_agent`, `prompt_agent`, the verifiers under `verifiers/`, among them `start_computer_recording` and `end_computer_recording`, `start_browser_recording` and `end_browser_recording` (`browser-recording/v1`: one recording per context, a lease's or the default one's, with a video of the tab its agent is on, its context's log, the browser's network log as HAR and opt-in frames keyed to the action log, the contexts its agents make recorded with it, one universe per recording, anything missing failing the run), and more). On an env whose card serves computer-exec/v1 (a computer), `run_code` with `env_id` and `run_container_unit_tests_verifier` with `env_id` run inside it as its session user through the driver: files staged with `data/add` and read with `data/get`, commands run with `run`; `env_outcome_verifier` hands a `verify` that takes an `env_url` keyword the env's address. A computer's framework-only routes (everything but MCP and the card) take the per-deploy control token its provider boots it with (`DeployedEnv.control_token`, `AGENTENV_CONTROL_TOKEN`), a multi env's computers the multi env's own, which its gateway passes on only on their `/svc` routes and its clock watch (`CONTROL_TOKEN_CHILDREN`); framework calls send `deployed.control_headers`, `Task.run` runs every step under `protocol_v1.authorized` with each deployed env's (a `verify` included), and a `run_code` script inside the computer gets `input["env"]["headers"]`. `teardown_run` and the `teardown_sandboxes` step share one core (`task/teardown.py` `tear_down`): the recordings the run left open end with fresh grants, each env still up closes (`Env.close`; a computer env ends any recording still open), what stayed open is registered from its namespace, then every sandbox is terminated by id. `task/episode/` runs a task with some of its agents played from outside, as a training loop does (`EpisodeSpec`). | | `store/` | Four store ABCs with local and cloud implementations: `DocumentStore` (SQLite, MongoDB, DynamoDB, Firestore with MongoDB compatibility), `ObjectStore` (filesystem, S3, Cloud Storage), `ImageStore` (local OCI registry, ECR), `SecretStore` (env vars or file, AWS Secrets Manager, Google Cloud Secret Manager). `VersionedEntityStore` implements the shared versioned get/put logic, `QueryBuilder` is the immutable chained query API, `store/base.py` holds the error types. `store/routing.py` is the local namespaces, `@local` and `@hf` (`is_local_id`), each with a documents file of its own: while the CLI or a `build_app` server runs, a local id and what a local task's run records go to local stores beside the configured ones, and that run's writes to the configured stores are refused. A new backend must pass the conformance kits in `tst/store/`. | diff --git a/src/agent_env/env/envs/computer/utils/site_proxy.py b/src/agent_env/env/envs/computer/utils/site_proxy.py index 6c37054ee..6bc2eab79 100644 --- a/src/agent_env/env/envs/computer/utils/site_proxy.py +++ b/src/agent_env/env/envs/computer/utils/site_proxy.py @@ -58,6 +58,10 @@ SITE_ROOT_HEADER = "AgentEnv-Site-Root" FORWARDED = frozenset({"x-forwarded-host", "x-forwarded-proto", "x-forwarded-for", "x-forwarded-port", "x-forwarded-prefix", "forwarded", SITE_ROOT_HEADER.lower()}) +#: Who a request is the gateway's to say: the computer it came from goes upstream from the config alone, and no page +#: names a role, so its request takes the role driving the computer. +ROLE_HEADER, COMPUTER_HEADER = "AgentEnv-Role", "AgentEnv-Computer" +AGENTENV_IDENTITY = frozenset({ROLE_HEADER.lower(), COMPUTER_HEADER.lower()}) RESPONSE_DROP = frozenset({"connection", "keep-alive", "proxy-connection", "alt-svc"}) UPSTREAM_HEADERS_FILE = "upstream_headers.json" HEAD_LIMIT = 1 << 20 @@ -442,7 +446,8 @@ def upstream_request(method: str, target: str, headers: list[tuple[str, str]], s parts = urlsplit(target) target = urlunsplit(("", "", parts.path or "/", parts.query, "")) provided = {key.lower() for key in site.upstream_headers} - kept = [(key, value) for key, value in headers if key.lower() not in HOP_BY_HOP | FORWARDED | provided] + kept = [(key, value) for key, value in headers + if key.lower() not in HOP_BY_HOP | FORWARDED | AGENTENV_IDENTITY | provided] kept += [("Host", site.netloc), ("X-Forwarded-Host", host), ("X-Forwarded-Proto", scheme), ("X-Forwarded-For", peer), (SITE_ROOT_HEADER, f"{scheme}://{host}"), *site.upstream_headers.items()] kept += [("Connection", "Upgrade"), ("Upgrade", upgrade)] if upgrade else [("Connection", "close")] diff --git a/src/agent_env/env/envs/computer/utils/sites.py b/src/agent_env/env/envs/computer/utils/sites.py index 8ac1d1389..e529c5fb8 100644 --- a/src/agent_env/env/envs/computer/utils/sites.py +++ b/src/agent_env/env/envs/computer/utils/sites.py @@ -44,6 +44,7 @@ from agent_env.env.env import Env, EnvCapabilityUnsupported, gateway_url_of from agent_env.env.envs.computer.utils.site_proxy import is_local, matches +from agent_env.env.gateway.constants import AGENT_ENV_COMPUTER_HEADER from agent_env.providers.sandbox_providers.local_docker.provider import LOCAL_TRUST_ENV from agent_env.providers.sandbox_providers.sandbox import NetworkPolicy, VmSandbox from agent_env.store.base import NotFoundError @@ -457,7 +458,9 @@ async def route(sandbox: Sandbox, sites: list[Site], *, user: Optional[str], net from agent_env.providers.sandbox_providers.sandbox_provider import sandbox_request_headers_for_url issued = issue(table.routes, label=label) - upstream_headers = {r.site: sandbox_request_headers_for_url(r.url) for r in table.routes} + # Each request names the computer it came from, so the gateway gives it the role driving that computer now. + upstream_headers = {r.site: {**sandbox_request_headers_for_url(r.url), AGENT_ENV_COMPUTER_HEADER: label} + for r in table.routes} channel = RootChannel(sandbox) await channel.private_folder(FOLDER) await channel.write(PROXY, _PROXY_SOURCE.read_text()) diff --git a/src/agent_env/env/gateway/changes.py b/src/agent_env/env/gateway/changes.py index 38609bd77..a3e860a00 100644 --- a/src/agent_env/env/gateway/changes.py +++ b/src/agent_env/env/gateway/changes.py @@ -2,15 +2,18 @@ from __future__ import annotations import heapq -from typing import Any +from typing import Any, Callable, Container class ChangeAttribution: - """The write windows (changelog ids before and after a call) of the trajectory events logged since start.""" + """The write windows (changelog ids before and after a call) of the trajectory events logged since start. A call + to a tool `unwindowed` names, a computer's, claims none: a computer writes the env's data only through its + browser's requests, which carry windows of their own, while its calls may run for seconds as others write.""" - def __init__(self) -> None: + def __init__(self, unwindowed: Callable[[], Container[str]] = frozenset) -> None: self._calls: dict[str, dict] = {} self._windows: list[tuple[int, int, int, dict]] = [] # (before, after, order, actor) + self._unwindowed = unwindowed def observe(self, event: dict) -> None: """Take one trajectory event as `_log_event` writes it.""" @@ -21,10 +24,11 @@ def observe(self, event: dict) -> None: **_who(event)} elif kind in ("tool_call_result", "tool_call_failed"): actor = self._calls.pop(event.get("tool_call_event_id"), None) - if actor is not None and "changelog_id_before" in event: # a gateway-native tool's result has no window + if (actor is not None and "changelog_id_before" in event # a gateway-native tool's result has no window + and actor["tool"] not in self._unwindowed()): failed = {"failed": True} if kind == "tool_call_failed" else {} self._add(event["changelog_id_before"], event.get("changelog_id"), {**actor, **failed}) - elif kind == "internal_tool_call": + elif kind == "internal_tool_call" and event.get("tool") not in self._unwindowed(): self._add(event.get("changelog_id_before"), event.get("changelog_id_after"), { "kind": "trigger_action", "event_id": event["event_id"], "trigger_id": event.get("trigger_id"), "action_index": event.get("action_index"), "tool": event.get("tool"), "role": event.get("as")}) diff --git a/src/agent_env/env/gateway/constants.py b/src/agent_env/env/gateway/constants.py index 31264e87f..58be95af0 100644 --- a/src/agent_env/env/gateway/constants.py +++ b/src/agent_env/env/gateway/constants.py @@ -74,6 +74,9 @@ def data_plane_load_timeout_s(size_bytes: int | None) -> int: CLOCK_FOLLOWERS_ENV = "CLOCK_FOLLOWER_TOKENS" # The children the gateway passes its control token on to, comma-separated: a multi env's computers, which boot with it. CONTROL_TOKEN_CHILDREN_ENV = "CONTROL_TOKEN_CHILDREN" +# The 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 route a clock follower long-polls, with its read token. CLOCK_WATCH_PATH = "/clock/watch" # How long /clock/watch holds a watch naming the current version before answering it unchanged; a follower's request @@ -162,6 +165,8 @@ def sources(names: list[str]) -> str: ) AGENT_ENV_ROLE_HEADER = "AgentEnv-Role" +# Sent by a computer's site proxy: the computer whose browser made the request, which takes the role driving it now. +AGENT_ENV_COMPUTER_HEADER = "AgentEnv-Computer" # Sent by a computer's site proxy, which serves a website's route at the root of the site's own name. AGENT_ENV_SITE_ROOT_HEADER = "AgentEnv-Site-Root" GATEWAY_PROVIDER_HEADERS_ENV = "AGENTENV_PROVIDER_REQUEST_HEADERS" diff --git a/src/agent_env/env/gateway/entrypoint.py b/src/agent_env/env/gateway/entrypoint.py index 83e59c128..ad7f3c833 100644 --- a/src/agent_env/env/gateway/entrypoint.py +++ b/src/agent_env/env/gateway/entrypoint.py @@ -8,7 +8,7 @@ import httpx from . import AGENT_ENV_GATEWAY_MCP_PORT, GatewayMode, InternalMCPServer -from .constants import (CLOCK_FOLLOWERS_ENV, CONTROL_TOKEN_CHILDREN_ENV, CONTROL_TOKEN_ENV, DEFAULT_MCP_SERVER_NAME, +from .constants import (CLOCK_FOLLOWERS_ENV, COMPUTERS_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 @@ -244,6 +244,7 @@ def parse_site_names(env_str: str) -> dict[str, tuple[str, ...]]: control_token=os.environ.get(CONTROL_TOKEN_ENV), control_token_children=[name.strip() for name in os.environ.get(CONTROL_TOKEN_CHILDREN_ENV, "").split(",") if name.strip()], + 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, "")), site_names=parse_site_names(os.environ.get(WEBSITE_NAMES_ENV, "")), diff --git a/src/agent_env/env/gateway/gateway.py b/src/agent_env/env/gateway/gateway.py index cd8e180fe..1fd29608c 100644 --- a/src/agent_env/env/gateway/gateway.py +++ b/src/agent_env/env/gateway/gateway.py @@ -40,6 +40,7 @@ # Relative import — gateway runs as a standalone container with no agent_env.* from .constants import ( + AGENT_ENV_COMPUTER_HEADER, AGENT_ENV_HIDDEN_BY_DEFAULT_META_KEY, AGENT_ENV_ROLE_HEADER, AGENT_ENV_ROLE_META_KEY, # noqa: F401 (the server module serves the whole vocabulary, used in this file or not) @@ -135,6 +136,12 @@ def __init__(self, clashes: dict[str, list[str]]): super().__init__(f"Duplicate tool name{'s' if len(clashes) > 1 else ''} {tool_name_clashes_text(clashes)}") + +def _read_only(tool: MCPTool) -> bool: + """Whether a tool says it only reads (``readOnlyHint``), as a computer's screenshots and waits do.""" + annotations = getattr(tool, "annotations", None) + return annotations is not None and getattr(annotations, "readOnlyHint", None) is True + class Gateway: """Gateway that aggregates MCP tools and REST proxies for website backends.""" @@ -163,6 +170,7 @@ def __init__( service_db_url: str | None = None, control_token: str | None = None, control_token_children: Iterable[str] = (), + computers: Iterable[str] = (), provider_headers: Iterable[str] = (), clock_followers: Mapping[str, str] | None = None, site_names: dict[str, Iterable[str]] | None = None, @@ -174,7 +182,9 @@ def __init__( 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.""" + /svc routes pass its control token on to, a multi env's computers, which take 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.""" self.host = host self.port = port self.server_name = server_name @@ -197,6 +207,12 @@ 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._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. + self._computer_of: dict[str, str] = {} + self._input_tools: frozenset[str] = frozenset() + self._drivers: dict[str, str] = {} self._website_routes: dict[str, list[WebsiteRoute] | None] = {} self._db_conn: psycopg2.extensions.connection | None = None if service_db_url: @@ -216,7 +232,7 @@ def __init__( self._event_counter = 0 self._event_lock = asyncio.Lock() - self._changes = ChangeAttribution() + self._changes = ChangeAttribution(lambda: self._computer_of) Path(GATEWAY_TRAJECTORY_FILE).parent.mkdir(parents=True, exist_ok=True) self._trajectory_file = open(GATEWAY_TRAJECTORY_FILE, "a") atexit.register(self._close_trajectory_file) @@ -912,10 +928,24 @@ async def _fire_website_triggers(self, request: Request, app: str, logger.exception("Trigger evaluation failed (fail-open)") return [], None - @staticmethod - def _request_role(request: HTTPConnection) -> str: - """The role the gateway attributes a REST request to: the first AgentEnv-Role header, else the default role.""" - return request.headers.get(AGENT_ENV_ROLE_HEADER, "").strip() or DEFAULT_ROLE + def _request_role(self, request: HTTPConnection) -> str: + """The role the gateway attributes a REST request to: the first AgentEnv-Role header; else, from a computer's + site proxy (AgentEnv-Computer), the role driving that computer as the request arrived; else the default role. + Read once per request, so its forwarding, its write and its triggers name one role, whoever drives after.""" + known = getattr(request.state, "agentenv_role", None) + if known is None: + role = request.headers.get(AGENT_ENV_ROLE_HEADER, "").strip() + computer = request.headers.get(AGENT_ENV_COMPUTER_HEADER, "").strip() + known = role or self._drivers.get(computer) or DEFAULT_ROLE + request.state.agentenv_role = known + return known + + def _drive(self, role: str, tool_name: str) -> None: + """An input call to a computer's tools makes its caller that computer's driver as it starts, so a request the + page sends before the call returns is the caller's too. A read (a screenshot, a wait) changes nothing.""" + if tool_name in self._input_tools: + self._drivers[self._computer_of[tool_name]] = role + async def _read_trigger_website_routes(self, body: Any) -> None: """Read the routes of each website a website trigger in a register `body` names an `op` of, so registration @@ -1092,6 +1122,7 @@ async def _call_child_tool(self, server_url: str, tool_name: str, arguments: dic unattributed trigger action), on its child's session (see child_sessions). Discovery is not redone on a reconnect; the registered proxies look their child up by URL.""" meta = caller.meta() if caller is not None else None + self._drive(caller.role if caller is not None else DEFAULT_ROLE, tool_name) return await self._sessions.call(server_url, tool_name, arguments, meta, timeout=self.TOOL_CALL_TIMEOUT_S) async def _ensure_tools_discovered(self) -> None: @@ -1154,6 +1185,10 @@ async def _discover_and_register_tools(self, sessions: dict[str, ClientSession]) logger.debug(f"Registered proxy tool: {tool.name}") for server, tools in listed: self._server_tools[server.name] = tools + computer_tools = [(server.name, tool) for server, tools in listed if server.name in self._computers + for tool in tools] + self._computer_of = {tool.name: computer for computer, tool in computer_tools} + self._input_tools = frozenset(tool.name for _, tool in computer_tools if not _read_only(tool)) self._hidden_by_default = { tool.name for _, tools in listed for tool in tools if (tool.meta or {}).get(AGENT_ENV_HIDDEN_BY_DEFAULT_META_KEY) is True} 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 e70ecf7cc..2e993e8b8 100644 --- a/src/agent_env/providers/env_providers/env_gateway_provider.py +++ b/src/agent_env/providers/env_providers/env_gateway_provider.py @@ -36,6 +36,7 @@ from agent_env.env.gateway import AGENT_ENV_GATEWAY_MCP_PORT, ExternalChild, GatewayMode from agent_env.env.gateway.constants import ( CLOCK_FOLLOWERS_ENV, + COMPUTERS_ENV, CONTROL_TOKEN_CHILDREN_ENV, DEFAULT_MCP_SERVER_NAME, GATEWAY_PROVIDER_HEADERS_ENV, @@ -551,6 +552,7 @@ def create_docker_compose( 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()) + 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)}") publish = host_port or (lambda port: port) @@ -1130,6 +1132,7 @@ async def _deploy_via_containers( **control_environment(control_token), **clock_followers_environment(external), **control_token_children_environment(external, control_token), + **computers_environment(external), **({GATEWAY_PROVIDER_HEADERS_ENV: ",".join(names)} if (names := sandbox_request_header_names()) else {}), } gateway_sb = await sandbox_provider.create_container( @@ -1781,6 +1784,13 @@ def control_token_children_environment(children: Iterable[ExternalChild], contro return {CONTROL_TOKEN_CHILDREN_ENV: names} if names else {} +def computers_environment(children: Iterable[ExternalChild]) -> dict[str, str]: + """The gateway's computers: every child it fronts on a sandbox of its own (``children``), a multi env's computers, + with or without a control token.""" + names = ",".join(child.name for child in children) + return {COMPUTERS_ENV: names} if names else {} + + def _frontend_urls(gateway_url: str, website_configs: Optional[list[WebsiteConfig]]) -> Optional[dict[str, str]]: """Each synthetic site's page route through the gateway, by its environment name; None with none, as when every site is live.""" diff --git a/tst/integration/computer/computer_triggers_test.py b/tst/integration/computer/computer_triggers_test.py index 80387e2ea..995680f15 100644 --- a/tst/integration/computer/computer_triggers_test.py +++ b/tst/integration/computer/computer_triggers_test.py @@ -23,6 +23,7 @@ from agent_env.task_step.task_steps.configure_scheduled_checks import ConfigureScheduledChecksTaskStep from agent_env.task_step.task_steps.register_env_triggers import RegisterEnvTriggersStep from tst.integration.computer.conftest import CONTAINER, multi_env +from tst.integration.computer.multi_env_computers_test import _reaches, shop # noqa: F401 shop is a fixture from tst.integration.task_step.test_register_env_triggers_local import _Executor pytestmark = [pytest.mark.integration, pytest.mark.int_test_slow] @@ -187,3 +188,36 @@ async def _computer_shows(computer: DeployedEnv, virtual_time: str) -> bool: if time.monotonic() > deadline: return False await asyncio.sleep(0.5) + + +@pytest.mark.asyncio +async def test_a_computers_browser_requests_take_the_role_driving_it_now(desktop, items, shop): # noqa: F811 + routed = {**CONTAINER, "env_params": {"form": "container", "site_routing": True}} + health = {"id": "health", "actions": [], "when": {"type": "website", "app": "shop", "method": "GET", + "path": {"regex": "^/?api/health$"}, "repeat": True}} + with namespace_routing(): + office = multi_env(items, Env.get(desktop.id), websites=[shop]) + context = TaskStepContext() + try: + deployed = await office.deploy(sandbox_type="local", ttl_seconds=1800, child_envs={"desktop": routed}) + context = TaskStepContext(deployed_envs=[deployed], metadata={}) + computer = DeployedEnv.from_dict(deployed.child_envs["desktop"]) + await RegisterEnvTriggersStep(id="seen", version=None, env_id=office.id, triggers=[health], + watch_roles=["person", "helper"]).execute(context) + async with httpx.AsyncClient(base_url=deployed.gateway_url, timeout=120, + headers=deployed.control_headers) as client: + loads = [] + for role in ("person", "helper"): + moved = await client.post("/step", json={"action": "call_tool", "arguments": {"x": 10, "y": 10}, + "tool_name": "desktop_computer_pointer_move"}, + headers={AGENT_ENV_ROLE_HEADER: role}) + assert moved.status_code == 200, moved.text + loads.append(await _reaches(computer, "https://shop.test/api/health")) + await _quiet(client) + state = await _triggers(client) + finally: + report = await teardown_run(context) + + assert not report.failed and loads == ["200", "200"] + assert [e["provoking"]["role"] for e in state["events"] if e["kind"] == "detected"] == ["person", "helper"] + diff --git a/tst/unit/env/envs/test_computer_site_proxy.py b/tst/unit/env/envs/test_computer_site_proxy.py index 48b886ffb..4136dbe88 100644 --- a/tst/unit/env/envs/test_computer_site_proxy.py +++ b/tst/unit/env/envs/test_computer_site_proxy.py @@ -31,7 +31,8 @@ from agent_env.env.envs.computer.utils import site_proxy, sites from agent_env.env.envs.computer.utils.params import Site as SiteParams from agent_env.env.envs.computer.utils.site_proxy import Config, Site, SiteProxy -from agent_env.env.gateway.constants import AGENT_ENV_SITE_ROOT_HEADER +from agent_env.env.gateway.constants import (AGENT_ENV_COMPUTER_HEADER, AGENT_ENV_ROLE_HEADER, + AGENT_ENV_SITE_ROOT_HEADER) from agent_env.env.gateway.gateway import Gateway from tst.unit.env.envs.test_computer_stand_in_proxy import _ask, _logged from tst.unit.env.envs.test_computer_stand_in_proxy import _serving as _stand_in_serving @@ -180,6 +181,22 @@ async def test_the_providers_headers_go_upstream_in_place_of_the_browsers_and_ne assert "s3cret" not in json.dumps(headers) and body == b"hello" +@pytest.mark.asyncio +async def test_a_request_names_its_computer_and_no_page_names_a_role_or_another_computer(tmp_path): + async with Upstream() as upstream: + config, issued = _config(tmp_path, upstream.port) + config.sites[0].upstream_headers = {"AgentEnv-Computer": "desktop"} + async with _proxy(config) as port: + _, _, body, conn = await _exchange( + port, b"GET / HTTP/1.1\r\nHost: notes.test\r\nAgentEnv-Role: admin\r\nAgentEnv-Computer: laptop\r\n\r\n", + server_hostname="notes.test", cadata=issued.ca_pem) + conn[1].close() + + ((_, sent, _),) = upstream.requests + assert sent["agentenv-computer"] == "desktop" and "agentenv-role" not in sent and body == b"hello" + assert (site_proxy.ROLE_HEADER, site_proxy.COMPUTER_HEADER) == (AGENT_ENV_ROLE_HEADER, AGENT_ENV_COMPUTER_HEADER) + + async def _serve(app) -> tuple[uvicorn.Server, int]: sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) sock.bind(("127.0.0.1", 0)) diff --git a/tst/unit/env/envs/test_computer_sites.py b/tst/unit/env/envs/test_computer_sites.py index 932e6db10..a2528d9ae 100644 --- a/tst/unit/env/envs/test_computer_sites.py +++ b/tst/unit/env/envs/test_computer_sites.py @@ -211,7 +211,7 @@ async def test_route_installs_the_proxy_as_root_with_each_sites_route_as_the_com "docker exec -u 0 computer-1 chmod 0600 /etc/agentenv/sites/config.json", "docker exec -u 0 computer-1 python3 /etc/agentenv/sites/site_proxy.py install " "/etc/agentenv/sites/config.json"] - assert "upstream_headers" not in site and "proxy_port" not in config + assert site["upstream_headers"] == {"AgentEnv-Computer": "desktop"} and "proxy_port" not in config assert routed["checks"] == _REPORT["checks"] and routed["names"]["routes"] == {"notes": ["notes.test"]} assert "PRIVATE KEY" not in json.dumps(routed) @@ -272,7 +272,7 @@ async def test_the_headers_the_gateways_provider_asks_for_go_in_the_private_conf label="desktop", os_type="linux", display="x11") (site,) = json.loads(sandbox.written["/etc/agentenv/sites/config.json"])["sites"] - assert site["upstream_headers"] == {"CF-Access-Client-Secret": "s3cret"} + assert site["upstream_headers"] == {"CF-Access-Client-Secret": "s3cret", "AgentEnv-Computer": "desktop"} private = sandbox.events.index("docker exec -u 0 computer-1 chmod 0600 /etc/agentenv/sites/config.json") copied = ("cp", "/tmp/secret-1/config.json", "computer-1:/etc/agentenv/sites/config.json") assert sandbox.events.index(copied) < private < len(sandbox.events) - 1 diff --git a/tst/unit/env/gateway/computer_driver_test.py b/tst/unit/env/gateway/computer_driver_test.py new file mode 100644 index 000000000..63bf23ed1 --- /dev/null +++ b/tst/unit/env/gateway/computer_driver_test.py @@ -0,0 +1,165 @@ +"""A computer's browser requests take the role of whoever drives the computer now, the last to make an input call to its +tools, and a computer's own calls claim none of the writes others make while they run.""" +from __future__ import annotations + +import asyncio +import contextvars +import json +from types import SimpleNamespace + +import httpx +import pytest +from mcp.types import CallToolResult, TextContent, Tool as MCPTool, ToolAnnotations + +from agent_env.env.gateway import InternalMCPServer +from agent_env.env.gateway import rest_proxy as rest_proxy_module +from agent_env.env.gateway.caller import Caller +from agent_env.env.gateway.constants import AGENT_ENV_COMPUTER_HEADER, AGENT_ENV_ROLE_HEADER +from agent_env.env.gateway.gateway import Gateway +from tst.unit.env.gateway.changes_test import _Changelog, _http, _RealAsyncClient, _site + +MAIL, DESKTOP = "http://mail/mcp", "http://desktop/mcp" +_SCHEMA = {"type": "object", "properties": {}} +SEND = MCPTool(name="mail_send_message", inputSchema=_SCHEMA) +CLICK, TYPE, SCREENSHOT = ( + MCPTool(name=f"desktop_computer_{op}", inputSchema=_SCHEMA, annotations=ToolAnnotations(readOnlyHint=read)) + for op, read in (("click", False), ("type", False), ("screenshot", True))) +FROM_DESKTOP = {AGENT_ENV_COMPUTER_HEADER: "desktop"} + + +class _Child: + """A child server whose every call runs `effect` with the tool's name first.""" + + def __init__(self, tools: list[MCPTool], effect=lambda name: None): + self.tools, self.effect = tools, effect + + async def list_tools(self): + return SimpleNamespace(tools=self.tools) + + async def call_tool(self, name, arguments, *args, meta=None, **kwargs): + self.effect(name) + return CallToolResult(content=[TextContent(type="text", text="ok")], isError=False) + + +async def _office(changelog: _Changelog, monkeypatch, desktop_effect=lambda name: None) -> Gateway: + """A gateway in front of a mail server, its site, and the computer `desktop`, whose site route writes a draft on + every POST.""" + async def ok(): + yield b'{"ok": true}' + + def website(request: httpx.Request) -> httpx.Response: + changelog.write("drafts", f"d{len(changelog.rows) + 1}") + return httpx.Response(201, content=ok()) + + transport = _site(website) + monkeypatch.setattr(rest_proxy_module.httpx, "AsyncClient", lambda **kw: _RealAsyncClient(transport=transport, **kw)) + gw = Gateway(host="127.0.0.1", port=0, server_name="t", + internal_mcp_servers=[InternalMCPServer("mail", MAIL), InternalMCPServer("desktop", DESKTOP)], + website_urls={"mail": "http://mail-frontend"}, computers=["desktop"]) + children = {MAIL: _Child([SEND], lambda name: changelog.write("messages", f"m{len(changelog.rows) + 1}")), + DESKTOP: _Child([CLICK, TYPE, SCREENSHOT], desktop_effect)} + + async def _open(server, stack, report): + return children[server.mcp_url] + + gw._sessions.open_session = _open # type: ignore[method-assign] + gw._query_changelog_id = changelog.max_id # type: ignore[method-assign] + gw._db_conn = changelog + await gw._ensure_tools_discovered() + return gw + + +async def _step(gw: Gateway, tool: MCPTool, role: str) -> None: + response = await gw._step_call_tool({"tool_name": tool.name, "arguments": {}}, role) + assert response.status_code == 200, response.body + + +async def _post(gw: Gateway, headers: dict) -> None: + status, _ = await _http(gw, "POST", "/website/mail/api/drafts", headers=headers) + assert status == 201 + + +async def _actors(gw: Gateway) -> dict[str, list[tuple[str, str]]]: + _, body = await _http(gw, "GET", "/changes") + return {c["row_id"]: [(a["kind"], a["role"]) for a in c["actors"]] for c in json.loads(body)["changes"]} + + +@pytest.mark.asyncio +async def test_a_computers_browser_writes_are_its_drivers_and_its_calls_claim_no_one_elses(monkeypatch): + changelog = _Changelog() + gw = await _office(changelog, monkeypatch, desktop_effect=lambda name: changelog.write( + "messages", f"world{len(changelog.rows) + 1}") if name == CLICK.name else None) + try: + await _step(gw, CLICK, "person") + await _post(gw, FROM_DESKTOP) + await _step(gw, SCREENSHOT, "helper") + await _post(gw, FROM_DESKTOP) + await _step(gw, TYPE, "helper") + await _post(gw, FROM_DESKTOP) + ctx = contextvars.copy_context() + ctx.run(Caller(role="carol").bind) + await ctx.run(asyncio.create_task, gw._mcp._tool_manager.call_tool(CLICK.name, {})) + await _post(gw, FROM_DESKTOP) + await _post(gw, {}) + await _post(gw, {AGENT_ENV_COMPUTER_HEADER: "laptop"}) + await _post(gw, {**FROM_DESKTOP, AGENT_ENV_ROLE_HEADER: "auditor"}) + actors = await _actors(gw) + finally: + await gw._close_child_sessions() + + assert actors == {"world1": [], "d2": [("request", "person")], "d3": [("request", "person")], + "d4": [("request", "helper")], "world5": [], "d6": [("request", "carol")], + "d7": [("request", "default")], "d8": [("request", "default")], "d9": [("request", "auditor")]} + + +@pytest.mark.asyncio +async def test_a_trigger_actions_input_on_a_computer_drives_it_as_the_role_it_acts_as(monkeypatch): + changelog = _Changelog() + gw = await _office(changelog, monkeypatch, desktop_effect=lambda name: changelog.write( + "messages", f"world{len(changelog.rows) + 1}") if name == TYPE.name else None) + gw._trigger_engine.register({"watch_roles": ["default"], "triggers": [ + {"id": "nora-types", "when": {"type": "action", "tool": SEND.name}, + "actions": [{"type": "tool", "tool": TYPE.name, "as": "nora", "args": {}}]}]}) + try: + await _step(gw, SEND, "default") + for _ in range(100): + if gw._trigger_engine.state()["triggers"][0]["status"] == "fired": + break + await asyncio.sleep(0.02) + await _post(gw, FROM_DESKTOP) + actors = await _actors(gw) + finally: + await gw._close_child_sessions() + + assert actors == {"m1": [("tool_call", "default")], "world2": [], "d3": [("request", "nora")]} + + +@pytest.mark.asyncio +async def test_a_request_keeps_the_role_it_arrived_with_when_someone_else_drives_before_it_ends(monkeypatch): + changelog = _Changelog() + gw = await _office(changelog, monkeypatch) + + async def ok(): + yield b'{"ok": true}' + + def website(request: httpx.Request) -> httpx.Response: + changelog.write("drafts", f"d{len(changelog.rows) + 1}") + gw._drive("helper", TYPE.name) + return httpx.Response(201, content=ok()) + + transport = _site(website) + monkeypatch.setattr(rest_proxy_module.httpx, "AsyncClient", lambda **kw: _RealAsyncClient(transport=transport, **kw)) + gw._trigger_engine.register({"watch_roles": ["person", "helper"], "triggers": [ + {"id": "drafted", "actions": [], "when": {"type": "website", "app": "mail", "method": "POST", + "path": {"regex": "^/?api/drafts$"}, "repeat": True}}]}) + try: + await _step(gw, CLICK, "person") + await _post(gw, FROM_DESKTOP) + await _post(gw, FROM_DESKTOP) + actors = await _actors(gw) + finally: + await gw._close_child_sessions() + + detected = [e["provoking"]["role"] for e in gw._trigger_engine.state()["events"] if e["kind"] == "detected"] + assert detected == ["person", "helper"] + assert actors == {"d1": [("request", "person")], "d2": [("request", "helper")]} 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 14b2a5106..ab9588196 100644 --- a/tst/unit/providers/env_providers/env_gateway_provider_test.py +++ b/tst/unit/providers/env_providers/env_gateway_provider_test.py @@ -2884,7 +2884,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_children_the_gateway_passes_its_token_on_to_only_when_it_has_one(): +def test_compose_names_the_gateways_computers_and_passes_its_token_on_to_them_only_when_it_has_one(): from agent_env.env.envs.service_db import ServiceDBConfig from agent_env.env.gateway import ExternalChild @@ -2899,6 +2899,7 @@ def gateway_env(control_token): assert gateway_env("gw-token")["CONTROL_TOKEN_CHILDREN"] == "desktop,laptop" assert "CONTROL_TOKEN_CHILDREN" not in gateway_env(None) + assert gateway_env("gw-token")["COMPUTERS"] == gateway_env(None)["COMPUTERS"] == "desktop,laptop" def test_compose_declares_the_children_that_follow_the_clock_by_their_read_tokens_and_logs_none_of_them(): @@ -3066,6 +3067,7 @@ async def children(reach, control_token): 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["COMPUTERS"] == "desktop" def _run_probe(tmp_path, statuses: dict[str, int]) -> int: