From 90b12fd322da8a7c4d80ee6ae7ebc481e2b04809 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sun, 15 Nov 2026 16:06:24 -0800 Subject: [PATCH 1/3] feat(gateway): get_time answers in the universe's zone, which sync_env_clock arms the clock in An agent asking get_time for the time got UTC alone unless it already knew its user's zone, and nothing in the environment told it: in the FD-5483 pilot, Sonnet took 00:32 UTC for Nora's time and scheduled its "morning" check for 00:32 in Denver, missing the 06:00 cancellation it was there to catch. sync_env_clock now arms the gateway's clock in its timezone (set_time's time_zone), which the clock keeps until a re-arm or a clear and shows in its state, and get_time answers with time_zone and local_time in it when the agent asks for no other zone. Tool dates stay UTC. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 2 +- src/agent_env/env/gateway/clock.py | 18 ++++++++-- src/agent_env/env/gateway/constants.py | 2 +- src/agent_env/env/gateway/gateway.py | 3 +- src/agent_env/env/gateway/get_time.py | 15 ++++---- .../task_step/task_steps/sync_env_clock.py | 6 ++-- tst/unit/env/gateway/get_time_test.py | 36 ++++++++++++++++--- tst/unit/task_step/sync_env_clock_test.py | 3 +- 8 files changed, 66 insertions(+), 19 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f079e10ff..aa27493f9 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, given an IANA `time_zone`, also in that zone; executors' working `hours` (`env/gateway/triggers.py`) take a fixed `utc_offset` or an IANA `time_zone`. | +| `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`. | | `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/gateway/clock.py b/src/agent_env/env/gateway/clock.py index 3126d4118..5f575c86e 100644 --- a/src/agent_env/env/gateway/clock.py +++ b/src/agent_env/env/gateway/clock.py @@ -134,6 +134,7 @@ def __init__(self, now_fn=time.monotonic): self._lock = threading.Lock() self._armed = False self._t0: datetime | None = None + self._time_zone: str | None = None # the universe's zone, its users', as the arm named it self._anchor = now_fn() # real time the current arm (or unarmed stretch) began self._rate = 1.0 self._generation = 0 @@ -181,10 +182,13 @@ def t0(self) -> datetime | None: with self._lock: return self._t0 - def set_time(self, virtual_time: str, rate=1.0) -> dict: - """Arm/re-arm: anchor t0=virtual_time to now, advancing at `rate` virtual s per real s.""" + def set_time(self, virtual_time: str, rate=1.0, time_zone: str | None = None) -> dict: + """Arm/re-arm: anchor t0=virtual_time to now, advancing at `rate` virtual s per real s, in the universe's + `time_zone` (its users' IANA zone), or none.""" t0 = _parse_rfc3339(virtual_time) r = _parse_rate(1.0 if rate is None else rate) + if time_zone is not None and _zone(time_zone) is None: + raise ClockError(f"unknown time zone {time_zone!r}: pass an IANA time zone name such as 'America/New_York'") if t0 > _MAX_T0 - timedelta(seconds=_OVERFLOW_HORIZON_S * r): raise ClockError(f"virtual_time {virtual_time!r} at rate {r:g} would overflow datetime near the max") with self._lock: @@ -193,6 +197,7 @@ def set_time(self, virtual_time: str, rate=1.0) -> dict: self._rate = r self._ahead = 0.0 self._armed = True + self._time_zone = time_zone self._generation += 1 self._count += 1 return self.state() @@ -239,6 +244,7 @@ def clear(self) -> dict: self._bank() self._armed = False self._t0 = None + self._time_zone = None self._rate = 1.0 self._ahead = 0.0 self._generation += 1 @@ -257,6 +263,12 @@ def now(self) -> datetime | None: elapsed = self._now() - self._anchor return _advance(self._t0, elapsed * self._rate + self._ahead) + @property + def time_zone(self) -> str | None: + """The universe's zone, its users', as the current arm named it; None unarmed or when it named none.""" + with self._lock: + return self._time_zone if self._armed else None + def at_elapsed(self, elapsed: float) -> datetime | None: """The virtual time at which elapsed() reaches `elapsed` on the current arm; None while unarmed.""" with self._lock: @@ -278,7 +290,7 @@ def state(self) -> dict: elapsed = self._now() - self._anchor return {"armed": True, "t0": _iso(self._t0), "virtual_seconds_per_real_second": self._rate, "virtual_time": _iso(_advance(self._t0, elapsed * self._rate + self._ahead)), - "version": self.version} + **({"time_zone": self._time_zone} if self._time_zone else {}), "version": self.version} def _bank(self, t0: datetime | None = None) -> None: """Fold the stretch since the last arm/clear into `_lived` at its rate, and start the next one now.""" diff --git a/src/agent_env/env/gateway/constants.py b/src/agent_env/env/gateway/constants.py index 97da9de8e..b39a9b8e3 100644 --- a/src/agent_env/env/gateway/constants.py +++ b/src/agent_env/env/gateway/constants.py @@ -251,7 +251,7 @@ def random_mcp_server_name() -> str: "description": "Virtual clock (urn:agentenv:clock/v1): read the gateway's virtual time (wall-clock-derived, rate-scaled) via get_time; set_time/set_rate/advance/clear are the harness control path, each changing the clock's opaque version and, given wait_followers_s, answering 504 naming the followers that don't show it in time (set_rate keeps t0, as advance does, so time triggers keep their marks; rate 0 freezes the clock); a follower follows it through watch, a long poll naming the version it shows and held up to hold_s; state's followers block is diagnostic, not part of the contract.", "params": {"endpoint": "/clock/time", "methods": { "get_time": {"method": "GET", "endpoint": "/clock/time"}, - "set_time": {"method": "PUT", "endpoint": "/clock/set-time", "request": {"type": "object", "properties": {"virtual_time": {"type": "string"}, "virtual_seconds_per_real_second": {"type": "number"}, **_WAIT_FOLLOWERS}, "required": ["virtual_time"]}}, + "set_time": {"method": "PUT", "endpoint": "/clock/set-time", "request": {"type": "object", "properties": {"virtual_time": {"type": "string"}, "virtual_seconds_per_real_second": {"type": "number"}, "time_zone": {"type": "string"}, **_WAIT_FOLLOWERS}, "required": ["virtual_time"]}}, "set_rate": {"method": "PUT", "endpoint": "/clock/set-rate", "request": {"type": "object", "properties": {"virtual_seconds_per_real_second": {"type": "number", "minimum": 0}, **_WAIT_FOLLOWERS}, "required": ["virtual_seconds_per_real_second"]}}, "advance": {"method": "PUT", "endpoint": "/clock/advance", "request": {"type": "object", "properties": {"virtual_time": {"type": "string"}, **_WAIT_FOLLOWERS}, "required": ["virtual_time"]}}, "clear": {"method": "POST", "endpoint": "/clock/clear", "request": {"type": "object", "properties": {**_WAIT_FOLLOWERS}}}, diff --git a/src/agent_env/env/gateway/gateway.py b/src/agent_env/env/gateway/gateway.py index 0c891e4b7..b48f25da2 100644 --- a/src/agent_env/env/gateway/gateway.py +++ b/src/agent_env/env/gateway/gateway.py @@ -351,7 +351,8 @@ async def clock_set_time(request: Request) -> Response: {"ok": False, "error": f"'{GET_TIME_TOOL_NAME}' is already registered by a backing server"}, 409) def arm(body: dict) -> dict: - state = self._clock.set_time(body.get("virtual_time"), body.get("virtual_seconds_per_real_second")) + state = self._clock.set_time(body.get("virtual_time"), body.get("virtual_seconds_per_real_second"), + body.get("time_zone")) self._register_get_time_tool() return state diff --git a/src/agent_env/env/gateway/get_time.py b/src/agent_env/env/gateway/get_time.py index 8d6ce7817..a44454868 100644 --- a/src/agent_env/env/gateway/get_time.py +++ b/src/agent_env/env/gateway/get_time.py @@ -22,10 +22,11 @@ "your own assumption about today's date. Call this tool and derive from its value every " "absolute date, time or timestamp you pass to another tool, and every relative phrase you " 'resolve ("today", "this week", "overdue", "the last 30 days"). current_time is in UTC, as ' - "are the dates and times the other tools here take, so derive those from current_time. If you " - "have been told your user's IANA time zone, you can pass it as time_zone to also get " - "local_time, the same instant in that zone, for telling your user the time in their own " - "terms; it does not change the dates you pass to tools. A date taken from any other " + "are the dates and times the other tools here take, so derive those from current_time. When " + "this environment has a home time zone, your user's, the result also has time_zone and " + "local_time, the same instant in that zone: what your user's own clock shows, for telling them " + "the time in their own terms. Pass time_zone to get local_time in another IANA zone instead. " + "Neither changes the dates you pass to tools. A date taken from any other " "source can silently match no records on a read, or file a record at the wrong time on a " "write. Time advances while you work, so re-read this before each write rather than reusing " "an earlier value. Inside a raw SQL or free-form query string, prefer the literal date this " @@ -36,8 +37,9 @@ "type": "object", "properties": {"time_zone": { "type": "string", - "description": "An IANA time zone name, such as \"America/New_York\" or \"Asia/Tokyo\". The result then " - "also has time_zone and local_time, the same instant with that zone's UTC offset.", + "description": "An IANA time zone name, such as \"America/New_York\" or \"Asia/Tokyo\", instead of the " + "environment's own: the result's time_zone and local_time are then the same instant with that " + "zone's UTC offset.", }}, "additionalProperties": False, } @@ -64,6 +66,7 @@ def build_get_time_tool(clock: Clock, make_arg_model: Callable[[str, dict], Any] """Built by hand: ToolManager.add_tool only warns on a collision and would silently shadow this.""" async def get_time(time_zone: str | None = None) -> dict[str, str] | CallToolResult: + time_zone = time_zone if time_zone is not None else clock.time_zone if time_zone is None: return read_time(clock) zone = _zone(time_zone) diff --git a/src/agent_env/task_step/task_steps/sync_env_clock.py b/src/agent_env/task_step/task_steps/sync_env_clock.py index 6f1ed4c3c..e2a006c1a 100644 --- a/src/agent_env/task_step/task_steps/sync_env_clock.py +++ b/src/agent_env/task_step/task_steps/sync_env_clock.py @@ -80,7 +80,8 @@ def __init__( 1 real s -> 1 virtual day). For ~V virtual seconds over an ~R-real-second task, pass V/R. timezone = optional IANA name. Unset keeps today's behaviour. Set, a wall-clock virtual_time is local time in - that zone, and every synced server is told the zone (a server that cannot take it fails the step).""" + that zone, the gateway's clock is armed in it, so its get_time answers in it too, and every synced server is + told the zone (a server that cannot take it fails the step).""" super().__init__(id, version, depends_on=depends_on, fail_task_on_error=fail_task_on_error) if not isinstance(virtual_time, str): raise ValueError("virtual_time must be an RFC3339 string") @@ -131,7 +132,8 @@ async def execute(self, context: TaskStepContext) -> TaskStepContext: raise StepContextError(f"Env '{self.env_id}' not found in context.deployed_envs") try: await deployed.invoke(EXT_CLOCK_URI, "set_time", - {"virtual_time": self.armed_virtual_time, "virtual_seconds_per_real_second": self.virtual_seconds_per_real_second}, + {"virtual_time": self.armed_virtual_time, "virtual_seconds_per_real_second": self.virtual_seconds_per_real_second, + **({"time_zone": self.timezone} if self.timezone else {})}, timeout=self.timeout_seconds) except httpx.HTTPStatusError as e: raise RuntimeError(f"clock arm failed (HTTP {e.response.status_code}): {e.response.text}") from e diff --git a/tst/unit/env/gateway/get_time_test.py b/tst/unit/env/gateway/get_time_test.py index f8536dbe3..51531878f 100644 --- a/tst/unit/env/gateway/get_time_test.py +++ b/tst/unit/env/gateway/get_time_test.py @@ -9,6 +9,7 @@ from datetime import datetime from types import SimpleNamespace +import httpx import pytest from mcp.shared.memory import create_connected_server_and_client_session from mcp.types import Tool as MCPTool @@ -289,15 +290,42 @@ async def test_a_time_the_zone_cannot_show_is_a_tool_error_naming_it(gw, now, zo 200, {"content": [{"type": "text", "text": message}], "isError": True, "changelog_id": None}) -def test_the_description_keeps_tool_dates_in_utc_and_offers_a_zone_only_to_an_agent_told_one(): +def test_the_description_keeps_tool_dates_in_utc_and_gives_the_users_own_clock_when_the_environment_has_one(): assert ("current_time is in UTC, as are the dates and times the other tools here take, so derive those from " "current_time.") in GET_TIME_TOOL_DESCRIPTION - assert ("If you have been told your user's IANA time zone, you can pass it as time_zone to also get " - "local_time") in GET_TIME_TOOL_DESCRIPTION - assert "it does not change the dates you pass to tools" in GET_TIME_TOOL_DESCRIPTION + assert ("When this environment has a home time zone, your user's, the result also has time_zone and local_time, " + "the same instant in that zone: what your user's own clock shows") in GET_TIME_TOOL_DESCRIPTION + assert "Neither changes the dates you pass to tools" in GET_TIME_TOOL_DESCRIPTION assert not re.search(r"[A-Z][a-z]+/[A-Z]", GET_TIME_TOOL_DESCRIPTION) +def test_a_clock_armed_in_a_zone_answers_in_it_with_no_argument_and_in_one_asked_for_instead(gw): + """A task's clock armed in its users' zone (sync_env_clock's timezone): an agent that asks no zone still learns the + time on its user's clock, which an agent once took UTC for, scheduling a "morning" check at 00:32 in Denver.""" + gw._clock.set_time("2027-02-06T00:32:00Z", 0, time_zone="America/Denver") + gw._register_get_time_tool() + + assert _call(gw) == {"current_time": "2027-02-06T00:32:00Z", "time_zone": "America/Denver", + "local_time": "2027-02-05T17:32:00-07:00"} + assert asyncio.run(_tools(gw)[GET_TIME_TOOL_NAME].fn(time_zone="Asia/Tokyo")) == { + "current_time": "2027-02-06T00:32:00Z", "time_zone": "Asia/Tokyo", "local_time": "2027-02-06T09:32:00+09:00"} + + +@pytest.mark.asyncio +async def test_the_arm_route_takes_the_zone_which_the_state_shows_and_a_re_arm_or_clear_drops(gw): + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=gw._asgi_app()), base_url="http://gw") as client: + armed = (await client.put("/clock/set-time", json={"virtual_time": T, "time_zone": "America/Denver"})).json() + unknown = await client.put("/clock/set-time", json={"virtual_time": T, "time_zone": "Mars/Olympus_Mons"}) + kept = (await client.get("/clock/state")).json() + rearmed = (await client.put("/clock/set-time", json={"virtual_time": T})).json() + await client.put("/clock/set-time", json={"virtual_time": T, "time_zone": "America/Denver"}) + await client.post("/clock/clear", json={}) + cleared = gw._clock.time_zone + + assert armed["time_zone"] == kept["time_zone"] == "America/Denver" and unknown.status_code == 400 + assert "time_zone" not in rearmed and cleared is None + + @pytest.mark.asyncio @pytest.mark.parametrize("zone", ["Mars/Olympus_Mons", "", 5], ids=["unknown", "empty", "not-a-string"]) async def test_an_unknown_zone_is_a_tool_error_naming_it(gw, zone): diff --git a/tst/unit/task_step/sync_env_clock_test.py b/tst/unit/task_step/sync_env_clock_test.py index 8c6d57b93..afe87a74b 100644 --- a/tst/unit/task_step/sync_env_clock_test.py +++ b/tst/unit/task_step/sync_env_clock_test.py @@ -356,7 +356,8 @@ async def test_execute_arms_the_gateway_at_the_local_instant_and_tells_every_ser await _zoned().execute(context) - assert json.loads(sent[0].content)["virtual_time"] == "2026-01-01T17:00:00Z" + assert json.loads(sent[0].content) == {"virtual_time": "2026-01-01T17:00:00Z", "virtual_seconds_per_real_second": 1.0, + "time_zone": "America/New_York"} # get_time answers in it too assert json.loads(sent[2].content) == {"env_get_time_url": CLOCK_URL, "timezone": "America/New_York"} cfg = context.metadata["clock_configurations"][0] assert (cfg["timezone"], cfg["virtual_time"], cfg["armed_at"]) == ("America/New_York", "2026-01-01T12:00:00", "2026-01-01T17:00:00Z") From fa93afa5898fb923d0c19485536f786ed7950d63 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sun, 15 Nov 2026 16:22:48 -0800 Subject: [PATCH 2/3] fix(sync_env_clock): a gateway that didn't take the zone is named in a warning and recorded, and the step goes on Co-Authored-By: Claude Opus 5.5 --- .../task_step/task_steps/sync_env_clock.py | 7 ++++++- tst/unit/task_step/sync_env_clock_test.py | 20 ++++++++++++++++++- 2 files changed, 25 insertions(+), 2 deletions(-) diff --git a/src/agent_env/task_step/task_steps/sync_env_clock.py b/src/agent_env/task_step/task_steps/sync_env_clock.py index e2a006c1a..8f574b058 100644 --- a/src/agent_env/task_step/task_steps/sync_env_clock.py +++ b/src/agent_env/task_step/task_steps/sync_env_clock.py @@ -146,6 +146,10 @@ async def execute(self, context: TaskStepContext) -> TaskStepContext: "deploy it in a multi env, whose gateway it follows") from e state = await deployed.invoke(EXT_CLOCK_URI, "state", timeout=self.timeout_seconds) env_get_time_url = state.get("env_get_time_url") + if self.timezone is not None and state.get("time_zone") != self.timezone: + logger.warning(f"sync_env_clock env={self.env_id}: its gateway's clock didn't take time zone " + f"{self.timezone!r}, so get_time answers agents in UTC alone; a gateway image from before " + "time_zone does that: put the gateway env again (agent-env env gateway put)") synced, skipped = [], [] for server in await self._backing_servers(deployed): @@ -162,7 +166,8 @@ async def execute(self, context: TaskStepContext) -> TaskStepContext: "env_get_time_url": env_get_time_url, "synced": synced, "skipped": skipped, } if self.timezone is not None: - configuration.update(timezone=self.timezone, armed_at=self.armed_virtual_time) + configuration.update(timezone=self.timezone, armed_at=self.armed_virtual_time, + get_time_zone=state.get("time_zone")) context.metadata.setdefault("clock_configurations", []).append(configuration) logger.info(f"sync_env_clock env={self.env_id}: armed rate={self.virtual_seconds_per_real_second}; " f"synced={[s['service'] for s in synced]} skipped={[s['service'] for s in skipped]}") diff --git a/tst/unit/task_step/sync_env_clock_test.py b/tst/unit/task_step/sync_env_clock_test.py index afe87a74b..a615101bc 100644 --- a/tst/unit/task_step/sync_env_clock_test.py +++ b/tst/unit/task_step/sync_env_clock_test.py @@ -350,7 +350,7 @@ def test_without_a_zone_virtual_time_is_passed_through_untouched(): @pytest.mark.asyncio async def test_execute_arms_the_gateway_at_the_local_instant_and_tells_every_server_the_zone(monkeypatch): - sent = _mock_http(monkeypatch, state={"env_get_time_url": CLOCK_URL}) + sent = _mock_http(monkeypatch, state={"env_get_time_url": CLOCK_URL, "time_zone": "America/New_York"}) monkeypatch.setattr("agent_env.env.env.Env.get", lambda *a, **k: SimpleNamespace(environment_name="email")) context = TaskStepContext(deployed_envs=[_carded(await _composed_card({"mcp-email": [_ZONE_EXT]}))]) @@ -361,6 +361,24 @@ async def test_execute_arms_the_gateway_at_the_local_instant_and_tells_every_ser assert json.loads(sent[2].content) == {"env_get_time_url": CLOCK_URL, "timezone": "America/New_York"} cfg = context.metadata["clock_configurations"][0] assert (cfg["timezone"], cfg["virtual_time"], cfg["armed_at"]) == ("America/New_York", "2026-01-01T12:00:00", "2026-01-01T17:00:00Z") + assert cfg["get_time_zone"] == "America/New_York" + + +@pytest.mark.asyncio +async def test_a_gateway_that_didnt_take_the_zone_is_named_in_a_warning_and_the_record_and_the_step_goes_on( + monkeypatch, caplog): + """An older gateway image answers the arm without keeping time_zone, so get_time answers in UTC alone: the step + still arms and syncs, as it did with that gateway before, and says why get_time won't give the user's clock.""" + _mock_http(monkeypatch, state={"env_get_time_url": CLOCK_URL}) + monkeypatch.setattr("agent_env.env.env.Env.get", lambda *a, **k: SimpleNamespace(environment_name="email")) + context = TaskStepContext(deployed_envs=[_carded(await _composed_card({"mcp-email": [_ZONE_EXT]}))]) + + with caplog.at_level("WARNING"): + await _zoned().execute(context) + + assert context.metadata["clock_configurations"][0]["get_time_zone"] is None + assert "its gateway's clock didn't take time zone 'America/New_York', so get_time answers agents in UTC alone" in ( + caplog.text) @pytest.mark.asyncio From 62b01da551c377a00a757ec72ce1ceb489d712a5 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Sun, 15 Nov 2026 17:15:54 -0800 Subject: [PATCH 3/3] fix(gateway): get_time says when your user's time zone is known, without the environment's setup words Co-Authored-By: Claude Opus 5.5 --- src/agent_env/env/gateway/get_time.py | 14 +++++++------- tst/unit/env/gateway/get_time_test.py | 7 ++++--- 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/src/agent_env/env/gateway/get_time.py b/src/agent_env/env/gateway/get_time.py index a44454868..24767249f 100644 --- a/src/agent_env/env/gateway/get_time.py +++ b/src/agent_env/env/gateway/get_time.py @@ -22,11 +22,11 @@ "your own assumption about today's date. Call this tool and derive from its value every " "absolute date, time or timestamp you pass to another tool, and every relative phrase you " 'resolve ("today", "this week", "overdue", "the last 30 days"). current_time is in UTC, as ' - "are the dates and times the other tools here take, so derive those from current_time. When " - "this environment has a home time zone, your user's, the result also has time_zone and " - "local_time, the same instant in that zone: what your user's own clock shows, for telling them " - "the time in their own terms. Pass time_zone to get local_time in another IANA zone instead. " - "Neither changes the dates you pass to tools. A date taken from any other " + "are the dates and times the other tools here take, so derive those from current_time. The " + "result also has time_zone and local_time when your user's time zone is known: the same " + "instant on their clock, for telling them the time in their own terms. Pass time_zone to get " + "local_time in another IANA zone instead. Neither changes the dates you pass to tools. A date " + "taken from any other " "source can silently match no records on a read, or file a record at the wrong time on a " "write. Time advances while you work, so re-read this before each write rather than reusing " "an earlier value. Inside a raw SQL or free-form query string, prefer the literal date this " @@ -37,8 +37,8 @@ "type": "object", "properties": {"time_zone": { "type": "string", - "description": "An IANA time zone name, such as \"America/New_York\" or \"Asia/Tokyo\", instead of the " - "environment's own: the result's time_zone and local_time are then the same instant with that " + "description": "An IANA time zone name, such as \"America/New_York\" or \"Asia/Tokyo\", for local_time in " + "that zone instead: the result's time_zone and local_time are then the same instant with that " "zone's UTC offset.", }}, "additionalProperties": False, diff --git a/tst/unit/env/gateway/get_time_test.py b/tst/unit/env/gateway/get_time_test.py index 51531878f..65be7d6c4 100644 --- a/tst/unit/env/gateway/get_time_test.py +++ b/tst/unit/env/gateway/get_time_test.py @@ -290,13 +290,14 @@ async def test_a_time_the_zone_cannot_show_is_a_tool_error_naming_it(gw, now, zo 200, {"content": [{"type": "text", "text": message}], "isError": True, "changelog_id": None}) -def test_the_description_keeps_tool_dates_in_utc_and_gives_the_users_own_clock_when_the_environment_has_one(): +def test_the_description_keeps_tool_dates_in_utc_and_gives_the_users_clock_when_their_zone_is_known(): assert ("current_time is in UTC, as are the dates and times the other tools here take, so derive those from " "current_time.") in GET_TIME_TOOL_DESCRIPTION - assert ("When this environment has a home time zone, your user's, the result also has time_zone and local_time, " - "the same instant in that zone: what your user's own clock shows") in GET_TIME_TOOL_DESCRIPTION + assert ("The result also has time_zone and local_time when your user's time zone is known: the same instant on " + "their clock") in GET_TIME_TOOL_DESCRIPTION assert "Neither changes the dates you pass to tools" in GET_TIME_TOOL_DESCRIPTION assert not re.search(r"[A-Z][a-z]+/[A-Z]", GET_TIME_TOOL_DESCRIPTION) + assert "home time zone" not in GET_TIME_TOOL_DESCRIPTION # no setup words: a clock tool says the time def test_a_clock_armed_in_a_zone_answers_in_it_with_no_argument_and_in_one_asked_for_instead(gw):