Repository navigation
[FD-5916] feat(agents): agents can follow the env's clock the way computers do - #714
Conversation
…5916) Prototype of the Agents on the Env Clock design, to size the change. The gateway takes followers declared after it starts; every AgentEnvAgent in an image that runs the clock follower serves clock/v1 sync_time; sync_env_clock and deploy_agent declare each agent as a follower and hand it its config; the Claude Code image runs the computer base's follower, egress proxy and libfaketime, copied in until FD-5700; get_time no longer calls the machine's clock unsynced. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…kip unless require_agent_clock The image's changes move to wloo/claude-code-clock-image, along with the computer base's egress options only it uses: on CI the image's Claude Code timed out reaching the test's model endpoint. What stays serves sync_time for an agent whose image runs the follower and is otherwise inert. An agent that can't follow is now skipped even when tolerate_missing_sync_time is false, which stays about the env's servers; require_agent_clock fails the step instead. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…gent, retire on teardown - An agent's sync_time takes only a status of the config it just wrote (its URL and name, written after it), so what the follower showed of an earlier gateway or token never passes for success. - An agent follows one env's clock; another env's is skipped as follows_another_env, as its one follower can't watch two gateways. deploy_agent's late follows are recorded with the sync's, so both see it. - teardown_sandboxes retires a torn-down agent's follower (DELETE /clock/followers, retire_follower), so later writes don't wait for it or answer 504 naming it. A declaration no longer replaces a follower the gateway started with. - Logs say an outcome's synced, reason and follower, never the agent's answer; the timeouts, token size and error length are named constants. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…tirement wakes waiting writes - Which env an agent follows moves from clock_configurations' items to metadata.agent_clock_following, one key per agent, so late deploy_agent steps that save at once never overwrite each other's record and teardown still finds it. - Retiring a follower notifies writes waiting for it, and a watch by a follower retired meanwhile acknowledges nothing. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
… retire however its sandbox goes - Agent names are percent-encoded into their metadata keys, so team.solver and team_solver never share a record. - An agent follows the clock of the first env it's registered with, fixed by the agent alone, so two steps arming two of its envs at once never both take its one follower. - teardown_sandboxes retires the follower of every agent whose sandbox it takes down, by agent, sandbox or env name. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
| f"rebuild its image or drop timezone={timezone!r} from the task") | ||
| name, token = follower_name(agent), secrets.token_urlsafe(READ_TOKEN_BYTES) | ||
| try: | ||
| await env.invoke(EXT_CLOCK_URI, "declare_follower", {"name": name, "read_token": token}, timeout=timeout) |
There was a problem hiding this comment.
If sync_time fails after declare_follower, the gateway keeps a follower that never watches. That covers an HTTP error, a connect error, or the follower not connecting in time.
In an e2e run I made one agent's sync_time return 500 after the declare. Every later clock write with wait_followers_s=8 then waited the full 8 s and returned 504 stale: ["agent-helper"]. teardown_sandboxes didn't clear it, because follow_in only records a follower that synced, so the env stayed stuck for the rest of the run.
Suggest calling retire_follower before re-raising, and wrapping httpx transport errors so they take the same path. A unit test could check that after a 500 from sync_time the gateway has no follower left.
There was a problem hiding this comment.
Good catch, thanks. Fixed in cecc686. When sync_time fails after the declare, follow now calls retire_follower before raising. That covers an HTTP error status, including the agent's 404 when its follower doesn't connect in time, and httpx transport errors, which take the same path. Test: test_an_agent_that_serves_sync_time_and_fails_fails_the_step_and_its_follower_is_retired, for a 404, a 500 and a connect error. Each checks the requests end with PUT /clock/followers, POST sync-time and DELETE /clock/followers, and that nothing is recorded as followed.
| ZoneInfo(zone) | ||
| except (ZoneInfoNotFoundError, ValueError) as e: | ||
| raise InvalidArgument(f"timezone must be an IANA name such as 'America/Chicago', got {timezone!r}") from e | ||
| os.environ["TZ"] = zone |
There was a problem hiding this comment.
set_zone only changes this process's TZ. In an e2e run I killed the A2A server with kill -9 and supervisord restarted it. The clock kept following, since the follower reads its config from disk, but the zone was gone. The next turn's date printed +00:00 and TZ= instead of -05:00 and America/Chicago.
Could the zone be saved with the follower's config and re-applied when the server starts, so a restart brings back both?
There was a problem hiding this comment.
Fixed in cecc686. sync_time now saves the task's zone in the follower's config (timezone, which the follower ignores), and restore_zone runs when the A2A application is built on an image with the follower, so the server supervisord restarts takes the zone back. A missing, malformed or invalid saved zone leaves the server's own TZ. Tests: test_a_server_restarted_mid_run_takes_back_the_tasks_zone (sync with America/Chicago, reset TZ to UTC, start the app again, TZ is America/Chicago) and test_a_server_starting_without_a_saved_zone_keeps_its_own.
| "Returns the current date and time for this environment. The clock on the machine you are " | ||
| "running on is not synchronized with this environment, so do not use it and do not rely on " | ||
| "your own assumption about today's date. Call this tool and derive from its value every " | ||
| "Returns the current date and time for this environment. Do not rely on your own assumption " |
There was a problem hiding this comment.
This drops "the clock on the machine you are running on is not synchronized" for every agent. But no agent follows the clock until #726 ships, and agents outside our images and install_agent targets never will, so for most runs the sentence is still true.
Suggest moving this change to #726, or keeping the sentence until the agents a gateway serves actually follow.
There was a problem hiding this comment.
Agreed. Reverted in cecc686: get_time's description is back to main's, sentence included. I didn't move the change to #726 either, since agents outside our images and install_agent targets still won't follow. Dropping the sentence can wait until the gateway knows whether the agent it serves follows.
…e survives a server restart; get_time keeps its sentence - follow retires the follower it declared when the agent's sync_time fails, by an HTTP error or a transport one, so the gateway isn't left waiting on every later write for a follower that never watches. - sync_time saves the task's zone in the follower's config, and the A2A server takes it back when it starts, so a server supervisord restarts mid-run keeps the zone as the follower keeps the clock. - get_time's description keeps "the clock on the machine you are running on is not synchronized": most agents won't follow the clock for a while yet. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
… down alone Their records stay in deployed_agents after teardown, and calling their gone servers failed the step. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
| @@ -0,0 +1,4 @@ | |||
| {"at": "2026-11-17T17:52:21.848022+00:00", "event": "launch", "pid": 4242, "cause": "launch"} | |||
There was a problem hiding this comment.
This file and browser-chromium.jsonl beside it are test-run output: launch events, and tabs on shop.test from 2026-11-17 17:52. They were added in cecc686, the same kind of files c726743 removed. Neither is on main, and #726 carries them through the same commit.
Suggest removing both. Also have the test that writes .agentenv/ into the working directory write to a temp dir instead, or ignore packages/agentenv-protocol/.agentenv/.
There was a problem hiding this comment.
You're right, sorry: git add -A swept them in again. Removed both in 25af21a, and .gitignore now ignores /packages/agentenv-protocol/.agentenv/, next to the existing /.agentenv/, so a protocol test run from that folder can't add them again. I checked that a file created there no longer shows as untracked. #726 drops them on its next merge of #714.
…tocol's tests write it Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
|
🤖 Automated Claude routine — Env Pod PR Context Review. This is a bot, not Edgar Arakelyan; not a human review. Context from outside this diff, not a review finding: #736 is open against the same file and the same idea, from the other side.
So after both land the one step has two knobs for "a participant that can't follow the clock", with opposite polarity and opposite strictness: computers refuse-unless-tolerated under Also worth knowing before either merges: Generated by Claude Code |
…ds show An agent whose card serves clock/v1 sync_time is now checked end to end after the validation DAG: the validation env's clock is armed frozen in America/Chicago with require_agent_clock, the agent runs `date` through its harness and must show that instant and zone, a write that waits for followers must be acknowledged, and `date` must show the time it moved to. A synced follower alone doesn't pass: an image whose preload is missing, or whose harness can't run under it, follows and still fails. An agent whose card serves no sync_time is skipped. The result is recorded under validated_a2a_extensions[urn:agentenv:clock/v1] and verifications["a2a_clock"]. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ength Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…ed with the env An agent in an image that follows the env's clock reads the env's time, so "is not synchronized, so do not use it" is false for it. "May not be" holds for every agent, following or not, and get_time answers what a following agent's clock already shows. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…he other agent extension clients It drives an agent's clock/v1 sync_time and the gateway's follower declarations for the steps that call it (sync_env_clock, deploy_agent, teardown_sandboxes), as object_transfer does for snapshot transfers; it defines no step. The name mirrors agentenv_protocol.a2a_agent.clock, the agent's side of the same extension. The persisted metadata key agent_clock_following is unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…t.clock, where #714 moved it Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
|
@greptileai review: the old-path import you flagged was the only caller, in #726, and #726 now imports from |
…st with an agent's clock/v1 sync_time 0.1.575 is the release that carries #714 (agentenv_protocol.a2a_agent.clock): before it, the image's protocol serves no clock/v1, so the agent advertises none and sync_env_clock skips it as not_advertised. The image is built again only when this folder changes, so the floor is what makes it take the release. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Why
While a task env's clock is set, an agent's machine clock isn't the env's, and neither is the date its harness gives the model (Claude Code's "Today's date is …" line,
datein Bash,datetime.now()in a script). This is the framework half of the "Agents on the Env Clock" design (FD-5916). It lets an agent's sandbox follow the env's clock the way a computer does: once an agent's image runs the clock follower, every program the agent's user runs reads the env's time.This PR changes nothing for any agent until its image is rebuilt. The Claude Code image is #726, stacked on this. Other images can follow one at a time.
What
Gateway (
env/gateway/)ClockFollowers.declare: a follower can be declared after the gateway starts. Until now followers were fixed at start, fromCLOCK_FOLLOWER_TOKENS. Declaring the same name again replaces its token and resets what it last showed, as a redeploy does.PUT /clock/followers(declare_followeron the card's clock/v1). It takes the env's control token.Protocol (
agentenv_protocol.a2a_agent)CLOCK_V1extension, withsync_timeatPOST /ext/clock/sync-time. It takesenv_get_time_url,timezone,watch_url,nameandread_token.AgentEnvAgent's card automatically, but only in an image that runs the clock follower (computer.clock.follows()). Agents need no code of their own.a2a_agent/clock.py: before answering,sync_time:TZfor the programs the server starts from then on;computer/clock.py: the wait-for-follower loop is now shared (following). The computer's own messages are unchanged.Core steps (
task_step/task_steps/)agent_clock.follow: declares the agent as followeragent-<name>with a fresh read token, then calls itssync_time. The watch URL is the gateway's as the agent's sandbox reaches it, as the MCP URL is.sync_env_clock: after syncing servers, it has every agent registered with the env follow, and records them underclock_configurations[].agents.deploy_agent: an agent deployed while a clock is set follows it (follow_armed_clocks).An agent that can't follow is reported and skipped:
not_advertised: its card serves nosync_time;no_follower_fields: itssync_timelacks the follower's fields;gateway_takes_no_followers: the gateway's card has nodeclare_follower.tolerate_missing_sync_timestays about the env's servers. Newrequire_agent_clock(off by default) fails the step for such an agent instead.An agent that serves
sync_timeand fails, by an HTTP error or a transport one, fails the step, as a server does. The follower it declared is retired first, so the gateway isn't left waiting for it.Compatibility
not_advertised, strict tasks included.gateway_takes_no_followers.clock_configurationsgains the keysagentsandrequire_agent_clock.Rollout
Tests
clock_watch_test.py,control_token_test.py):test_a2a_agent_clock.py):sync_time;sync_timewrites the config and sets the zone;agent_clock_test.py):tolerate_missing_sync_time, failing underrequire_agent_clock;deploy_agent, andrequire_agent_clock's round trip.hypothesis,brotli,tomli_w,av).🤖 Generated with Claude Code


Confidence Score: 5/5
The PR appears safe to merge with the verified import fix in dependent PR #726.Summary
Adds clock following for agents whose images run the follower.
Diagram
Reviews (13) · Last reviewed commit: "chore: re-run review now that #726 impor..." · Reviewed by Greptile