Skip to content

[FD-5916] feat(agents): the pi image follows the env's clock - #771

Open
williamloo-scale wants to merge 52 commits into
mainfrom
wloo/pi-clock-image
Open

williamloo-scale wants to merge 52 commits into
mainfrom
wloo/pi-clock-image

Conversation

@williamloo-scale

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

Copy link
Copy Markdown
Contributor

What and why

The pi image gets the same env clock as the Claude Code image in #726, now merged, which this follows. Once a task sets the clock, its CLI and every command the model runs read the env's time, including date and datetime.now().

What changes

  • shared_sources.toml takes the clock library and the egress proxy from agent-env's one copy in utils (utils/faketime_clock, utils/egress_proxy, [FD-5700] refactor(computers): the clock library and the egress proxy live once, in utils, and each image takes them #763), as the Claude Code image and the computer bases do, libfaketime's init guard included. start-agent and root.conf are added: root's supervisord runs the follower, the proxy and the A2A server. The A2A server runs as agent with the real-time marker. Started as any other user, the image runs as before.
  • root.conf gives the egress proxy AGENTENV_EGRESS_PRIVATE="allow", as [FD-5916] feat(agents): the Claude Code image follows the env's clock #726 does, so a model endpoint over TLS at a private address goes through the proxy at any date. Only a plain-HTTP model endpoint is reached directly.
  • Dockerfile: the egress and clock build stages, the root setup block, no USER, and CMD ["/usr/local/bin/start-agent"].
  • requirements.txt: the protocol floor is 0.1.575, the first release whose agents offer sync_time.
  • pi_agent.cli_env: with the clock set, the pi CLI goes through the egress proxy. It reaches the env's MCP servers directly, since it connects to them itself, as it does the A2A server's peers MCP on loopback. A plain-HTTP model endpoint is direct too.
  • Ubuntu 24.04 base: libfaketime is built on the same ubuntu:24.04 image as the final stage. The follower runs on the system Python, and supervisord in the agent's venv, with setuptools for its pkg_resources. Without setuptools, supervisord exited at start and the server never came up; that's fixed in fef5804.
  • install.sh: Node goes from 22.19.0 to 22.23.3, the version codex uses. Node honors NODE_USE_ENV_PROXY only from 22.21.
  • Tests: test_env_clock.py for the routing. The shared test_agent_clock_images.py now covers this image too. The local end to end test has a row for it.

Testing

  • Unit tests: all agent tests pass (1014). pi has no image contract test.
  • The image builds. pi --version returns 1.1.0 under the preload.
  • Local end to end (54 s): the agent follows the clock; date and datetime.now() show the env's time; writes wait for it, and answer 504 naming it while it's paused; teardown removes its follower.
  • Not yet run: a real model turn and the A2A validator, including the clock/v1 check. They need a model endpoint. They're also what shows whether the CLI trusts the egress proxy's CA for HTTPS while the clock is set.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 5/5

The PR appears safe to merge based on the reviewed code.

Summary

The pi image now follows the environment’s clock while its A2A server stays on real time.

  • Pi and its commands now follow the task's clock.
  • Pi routes clocked HTTPS requests through the local proxy.

The previous shared-source finding is fixed. No new actionable issues were found. Real model and HTTPS MCP turns remain untested, as the PR description notes.

williamloo-scale acknowledged the host-only NO_PROXY limitation. The current shared helper keeps hosts explicitly used over HTTPS behind the proxy.

Reviews (5) · Last reviewed commit: "refactor(pi): take the shared egress rul..." · Reviewed by Greptile

williamloo-scale and others added 30 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>
The image half of the agent clock: the computer base's clock follower and egress proxy, copied in until FD-5700,
libfaketime preloaded for the agent's user, root's supervisord starting them and the A2A server, and the CLI sent
through the proxy. Needs #714 and an agentenv-protocol release with CLOCK_V1.

Not ready: on CI this image's CLI timed out reaching the integration tests' model endpoint, likely the proxy refusing
a private address; it should go through the proxy only once the clock is armed.

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>
…d on local Docker (FD-5916)

Deploys the image with an env, runs sync_env_clock with require_agent_clock, and checks that the agent's user reads
the env's time (date and datetime.now()) while the real-time marker opts out; that a write waiting for followers waits
for the agent, answering 504 naming it while its container is paused; and that after teardown_sandboxes writes no
longer wait for it. Skipped unless AGENTENV_E2E_CLAUDE_CODE_IMAGE names an image built from this branch.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…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>
…through the proxy only on an armed clock

- The agent's libfaketime takes Edgar's init guard: a clock call made while ftpl_really_init runs on that thread, as
  the CLI's allocator makes one when dlsym allocates, reads the kernel's clock instead of waiting on pthread_once, which
  deadlocked: claude --version never returned. The computer base's patch doesn't take it yet; the agent's copy is the
  base's, then the guard, which the drift test checks.
- The CLI goes out through the egress proxy only while the follower follows an armed clock (clock_armed), and reaches a
  plain-HTTP model endpoint directly then: unarmed, it goes out as before, so a private endpoint keeps working.
- egress/ is the base's again after main moved it.
- The e2e test checks claude --version under the preload, and one turn of the real CLI against a stub Messages
  endpoint: its "Today's date is" line and a Bash date are the env's.

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>
…browser base's egress copy takes boot.go

- test_agent_env_clock_local skips as agentenv-capability-missing: agent_clock_image, which the slow integration job
  allows, as no CI job builds agent images.
- ubuntu-24.04-browser's egress/ is ubuntu-24.04's again, with this PR's AGENTENV_SESSION_USER and AGENTENV_EGRESS_NSS.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…tocol's tests write it

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…lag, not the follower's status

The page is what libfaketime reads, and it keeps the last armed clock while the follower reconnects to a restarted
gateway or restarts itself, when its status says connected false or armed false. A CLI started then reads the env's
time, so it must go through the proxy. Unit tests pin both windows.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…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>
…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>
… gateway refuses at once

A watch that fails fast (connection refused) answers before the follower's quarter-second poll sees a changed config,
and the retry backoff ends early on that change, so the follower kept retrying the old URL in a tight loop and never
followed the new one: an agent re-synced to another gateway after its first one went away stayed on the old clock,
burning a core, and every write that waited for it answered 504. It now checks the config after each failed watch.
The base's, the browser base's and the Claude Code image's copies stay identical.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ct; name the egress probe's error limit

- egress_env merges the hosts NO_PROXY and no_proxy already name with the direct ones, so a private registry the agent
  was deployed to reach directly isn't sent to the proxy, which refuses it, once the clock is armed.
- egress/upstream.go names its 200-character problem limit (problemChars), in the computer bases' copies too, which
  stay byte for byte the same.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…ge, not Claude Code's alone

- tst/unit/agents/test_agent_clock_images.py: every agent folder with clock/ copies the base's clock pieces with the
  init guard, runs the follower, the proxy and the server as their users, preloads libfaketime for the agent's user,
  starts as another user as before, and decides the CLI's proxy with the same clock_armed and egress_env as Claude Code.
- The local e2e runs over each image AGENTENV_E2E_AGENT_IMAGES names (claude-code=<tag>,...), with a CLI turn for an
  agent whose CLI the stub endpoint speaks to.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
williamloo-scale and others added 11 commits November 18, 2026 09:20
…urces.toml brings as in the build context

After the move to utils, clock/ and egress/ aren't in the image's folder but are in its build context; the test
resolved them in the folder alone and failed.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…ls (shared_sources.toml), as Claude Code's does

Drops the clock/ and egress/ copies now that #763 keeps one copy of each in utils; the Dockerfile still copies from
clock/ and egress/, which the build context takes from there.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
… armed clock; name the clock page's limits

- model_direct_hosts: the model endpoint's host is direct on an armed clock when it's plain HTTP or isn't a public
  address (an IP literal, or a name that resolves only to non-public ones), which the egress proxy refuses. Resolved
  only while the clock is armed. Shared, with _global_host, by every clocked bridge.
- clock_armed's retry count, delay and check salt are named (_PAGE_READ_TRIES, _PAGE_RETRY_S, _PAGE_CHECK_SALT).
- The e2e's cleanup finds a stopped or missing agent container without raising, and always closes the env.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
… armed clock; name the clock page's limits

The bridge takes #726's shared helpers (model_direct_hosts, _global_host, the named page limits).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…hout a lookup leaving the machine

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…esolver can't stall the A2A server

The lookup runs on a thread of its own and waits _RESOLVE_TIMEOUT_S (2 s) at most, once per host per process; a host
that doesn't resolve in time is left to the egress proxy. Shared by every clocked bridge.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Base automatically changed from wloo/claude-code-clock-image to main November 18, 2026 18:28
williamloo-scale and others added 2 commits November 18, 2026 10:44
# Conflicts:
#	src/agent_env/agents/README.md
#	src/agent_env/agents/agents/claude-code/claude_bridge.py
#	src/agent_env/agents/agents/claude-code/root.conf
#	tst/integration/task_step/test_agent_env_clock_local.py
#	tst/unit/agents/claude_code/test_env_clock_image.py
#	tst/unit/agents/test_agent_clock_images.py
…xy reaches private networks, a plain-HTTP model endpoint alone is direct

The bridge takes #726's final helpers (model_direct_hosts without a lookup), and root.conf gives the egress proxy
AGENTENV_EGRESS_PRIVATE=allow, so a model endpoint over TLS at a private address goes through it at any date.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@williamloo-scale
williamloo-scale marked this pull request as ready for review November 18, 2026 23:15
@williamloo-scale
williamloo-scale requested a review from a team as a code owner November 18, 2026 23:15
…servers through the egress proxy

- start-agent adds the bundles SSL_CERT_FILE, REQUESTS_CA_BUNDLE, NODE_EXTRA_CA_CERTS and CURL_CA_BUNDLE name (Sail's,
  which it signs model requests under) to agent-env's bundles, which root.conf points the server at, and to the egress
  proxy's roots, which carry those requests once the clock is armed.
- Only plain-HTTP MCP hosts are reached directly on an armed clock: an HTTPS one goes through the proxy, which checks
  its certificate on real time, where the CLI's own TLS would check it against the env's date.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
# Conflicts:
#	src/agent_env/agents/agents/pi/requirements.txt
# Conflicts:
#	tst/integration/task_step/test_agent_env_clock_local.py
@earakely-scale

Copy link
Copy Markdown
Collaborator

Hi @williamloo-scale, this is Claude, working with Edgar. Please don't merge this yet. It needs main and a small migration first, or it will turn main red.

#818 merged a single egress rule for every clocked agent: src/agent_env/utils/agent_clock/agent_egress.py. With the clock armed, every TLS host goes through the egress proxy, the env's MCP servers included. Only loopback, host.docker.internal, the deploy's NO_PROXY hosts, and hosts reached only over plain HTTP go direct. NO_PROXY matches by host, so a host also reached over HTTPS stays behind the proxy.

tst/unit/agents/test_agent_clock_images.py on main now requires every clocked agent to:

  • take agent_clock = "utils/agent_clock" in its shared_sources.toml;
  • import clock_armed and egress_env from agent_egress, and define none of the rule itself;
  • have its Dockerfile, and install.sh if it has one, copy agent_clock/agent_egress.py and clock/clockpage.py beside the bridge.

This branch still has its own clock_armed / model_direct_hosts / egress_env. main doesn't require branches to be up to date before merging, so this PR's green checks predate #818, and merging it now would fail main's unit tier for this agent. OpenCode hit exactly this. In #818, commit ddb5993 moved it over, and it makes a short template: the bridge's change is the import plus egress_env(environ, [model_url, *mcp_urls], armed=...).

Why it matters beyond the test: on an armed clock, the CLI checks TLS certificates against the virtual date. An env on Modal whose *.modal.host certificate was issued after that date fails if its MCP host goes direct. We reproduced that on main before #818 (CERT_NOT_YET_VALID, no env tools). #818's PR description has the end-to-end results for Claude Code and OpenCode.

pi specifically: plain-HTTP MCP hosts go direct, but a host also reached over HTTPS would then bypass the proxy too. The shared rule handles that case.

If it helps, I can push the merge and migration commits to this branch and run the same armed-clock end-to-end check against a Modal env. Just say so here or on Slack.

williamloo-scale and others added 2 commits November 19, 2026 15:06
The bridge imports clock_armed and egress_env from agent_egress and hands
it the model endpoint's URL and every MCP server's, so on an armed clock a
host reached over HTTPS stays behind the proxy even when it's also reached
over plain HTTP. The image copies agent_egress.py and clockpage.py beside
the bridge; an install (install/v1), which unpacks the build context with
them in agent_clock/ and clock/, puts those folders on the server's path.

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

Copy link
Copy Markdown
Contributor Author

Thanks, done. I merged main (v0.9.1595, with #818) and moved this agent onto agent_egress. Its shared_sources.toml takes agent_clock, the image (and install, where it has one) copies agent_egress.py and clockpage.py beside the bridge, and the bridge hands egress_env the model endpoint's URL and every MCP server's, so an HTTPS MCP host stays behind the proxy. The unit tests pass, including test_agent_clock_images.py and test_agent_egress.py. I rebuilt the image and ran the local armed-clock e2e and the A2A validator against a real model through LiteLLM: clock/v1 is supported, synced and follows writes, and both readings (2031-03-03T23:06:07-0600, then a day later) match. (head a4e9b4b) pi's install unpacks the whole build context instead of copying files, so start.sh puts agent_clock/ and clock/ on PYTHONPATH; a test imports both from the unpacked context.

@earakely-scale

Copy link
Copy Markdown
Collaborator

Claude again, working with Edgar. I checked the update, and the migration onto the shared rule looks right:

  • agent_clock in shared_sources.toml;
  • clock_armed and egress_env imported from agent_egress, with no copies of the rule;
  • the Dockerfile copies agent_egress.py and clockpage.py beside the bridge;
  • the model URL and every MCP server's URL are passed in;
  • CI is green.

start.sh putting agent_clock/ and clock/ on PYTHONPATH covers the install/v1 path. pi's MCP client is Node, so it's worth confirming end to end that it honours HTTPS_PROXY and NO_PROXY.

One thing hasn't been done yet: a run with an armed clock against an env on Modal, whose certificate starts after the virtual date. That's the case #818 was about. I'm happy to run it for pi before this merges, if you'd like.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants