Skip to content

[FD-5916] feat(agents): agents can follow the env's clock the way computers do - #714

Merged
earakely-scale merged 16 commits into
mainfrom
wloo/agent-env-clock-follower
Nov 18, 2026
Merged

earakely-scale merged 16 commits into
mainfrom
wloo/agent-env-clock-follower

Conversation

@williamloo-scale

@williamloo-scale williamloo-scale commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

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, date in 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, from CLOCK_FOLLOWER_TOKENS. Declaring the same name again replaces its token and resets what it last showed, as a redeploy does.
  • PUT /clock/followers (declare_follower on the card's clock/v1). It takes the env's control token.

Protocol (agentenv_protocol.a2a_agent)

  • CLOCK_V1 extension, with sync_time at POST /ext/clock/sync-time. It takes env_get_time_url, timezone, watch_url, name and read_token.
  • The framework serves it on every 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:
    • writes the follower's config (0640, written beside its place and renamed in);
    • sets TZ for the programs the server starts from then on;
    • waits until the follower shows the gateway's version.
    • saves the task's zone with the config, so a server restarted mid-run takes it back when it starts.
  • 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 follower agent-<name> with a fresh read token, then calls its sync_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 under clock_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 no sync_time;
    • no_follower_fields: its sync_time lacks the follower's fields;
    • gateway_takes_no_followers: the gateway's card has no declare_follower.

    tolerate_missing_sync_time stays about the env's servers. New require_agent_clock (off by default) fails the step for such an agent instead.

  • An agent that serves sync_time and 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

  • Agents not rebuilt yet (all of them, until [FD-5916] feat(agents): the Claude Code image follows the env's clock #726 and its successors) are skipped as not_advertised, strict tasks included.
  • Envs deployed with an older gateway are skipped as gateway_takes_no_followers.
  • Tasks that never set the clock see no change.
  • clock_configurations gains the keys agents and require_agent_clock.

Rollout

  1. Merge this.
  2. Release agentenv-protocol.
  3. Deploy to the hub.
  4. Rebuild agent images one at a time, starting with Claude Code ([FD-5916] feat(agents): the Claude Code image follows the env's clock #726). An image starts following when it's rebuilt; nothing else changes.

Tests

  • Gateway (clock_watch_test.py, control_token_test.py):
    • an agent declared after start is waited for;
    • a redeclare takes its new token, and the old one acknowledges nothing;
    • a declaration needs both fields and the control token.
  • Protocol (test_a2a_agent_clock.py):
    • only an image with the follower serves sync_time;
    • sync_time writes the config and sets the zone;
    • a follower that's behind is named, and incomplete config or a bad zone is refused.
  • Core (agent_clock_test.py):
    • declare-then-configure uses the same token, and only the env's own agents follow;
    • each skip reason: skipped by default and under a strict tolerate_missing_sync_time, failing under require_agent_clock;
    • an old gateway, and an agent that fails;
    • late agents through deploy_agent, and require_agent_clock's round trip.
  • Results: task-step and gateway (4,353), protocol (1,549) and agents (733) pass, and ruff is clean. The only errors are packages missing from my local environment (hypothesis, brotli, tomli_w, av).

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence 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.

  • Gateways can add and remove clock followers while running.
  • Programs started by an agent can follow the environment’s clock.
  • Clock setup now brings registered agents onto the environment’s time.
  • Agent checks now confirm commands follow clock changes.

Diagram

sequenceDiagram
  participant Core as Task step
  participant Gateway
  participant Agent as Agent server
  participant Follower as Clock follower
  Core->>Gateway: Declare agent follower and read token
  Core->>Agent: sync_time with clock settings and timezone
  Agent->>Follower: Write settings
  Follower->>Gateway: Watch clock and acknowledge version
  Agent-->>Core: Clock is following
  Core->>Gateway: Retire follower during teardown
Loading

Reviews (13) · Last reviewed commit: "chore: re-run review now that #726 impor..." · Reviewed by Greptile

williamloo-scale and others added 3 commits November 16, 2026 11:29
…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>
@williamloo-scale williamloo-scale changed the title [FD-5916] feat(agents): agents follow the env's clock the way computers do (draft, to size the change) [FD-5916] feat(agents): agents can follow the env's clock the way computers do Nov 17, 2026
@williamloo-scale
williamloo-scale marked this pull request as ready for review November 17, 2026 00:15
@williamloo-scale
williamloo-scale requested a review from a team as a code owner November 17, 2026 00:15
…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>
williamloo-scale and others added 2 commits November 16, 2026 16:48
… 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>
williamloo-scale added a commit that referenced this pull request Nov 17, 2026
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)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread src/agent_env/env/gateway/get_time.py Outdated
"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 "

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

williamloo-scale and others added 2 commits November 17, 2026 09:54
…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>
williamloo-scale added a commit that referenced this pull request Nov 17, 2026
… 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"}

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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/.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>
williamloo-scale added a commit that referenced this pull request Nov 17, 2026
@earakely-scale

Copy link
Copy Markdown
Collaborator

🤖 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 tolerate_missing_sync_time, agents skip-unless-required under require_agent_clock. Both end up in the step's serialized params (to_dict/from_dict), so it's cheaper to settle the shape now than after task JSONs carry either key.

Also worth knowing before either merges: git merge-tree 25af21a5 38151bc9 conflicts in src/agent_env/task_step/task_steps/sync_env_clock.py — the two branches edit the module docstring and _sync_one/execute region. Mechanical, but whoever is second owns it.


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>
Comment thread src/agent_env/a2a_agent/validator.py Resolved
williamloo-scale and others added 3 commits November 17, 2026 14:06
…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>
Comment thread src/agent_env/a2a_agent/clock.py Resolved
williamloo-scale added a commit that referenced this pull request Nov 18, 2026
williamloo-scale added a commit that referenced this pull request Nov 18, 2026
…t.clock, where #714 moved it

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@williamloo-scale

Copy link
Copy Markdown
Contributor Author

@greptileai review: the old-path import you flagged was the only caller, in #726, and #726 now imports from agent_env.a2a_agent.clock (686fdf1).

@greptile-apps

greptile-apps Bot commented Nov 18, 2026

Copy link
Copy Markdown

Confirmed. Commit 686fdf10 updates the only caller in #726 to import FOLLOWING_KEY from agent_env.a2a_agent.clock. The finding is resolved; a compatibility re-export isn’t needed.

…nt.clock

No changes: #726's 686fdf1 moved the only caller of the old agent_clock path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale merged commit d758053 into main Nov 18, 2026
63 of 65 checks passed
@earakely-scale
earakely-scale deleted the wloo/agent-env-clock-follower branch November 18, 2026 01:18
williamloo-scale added a commit that referenced this pull request Nov 18, 2026
earakely-scale added a commit that referenced this pull request Nov 18, 2026
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants