diff --git a/src/agent_env/a2a_agent/clock.py b/src/agent_env/a2a_agent/clock.py index f03f55579..59c844fdb 100644 --- a/src/agent_env/a2a_agent/clock.py +++ b/src/agent_env/a2a_agent/clock.py @@ -3,8 +3,9 @@ runs reads the env's time. ``follow`` declares it at the gateway as a follower with a read token of its own, then calls its ``sync_time`` with the follower's config: the gateway's watch URL as the agent's sandbox reaches it, the name the gateway knows it by and that token. From then on a clock write that waits for followers (``wait_followers_s``) waits -for the agent too. ``sync_env_clock`` has every agent registered with the env follow once it has armed the clock, and -``deploy_agent`` an agent it deploys while the clock is armed. An agent has one follower, so it follows one env's +for the agent too. Only a task that opts in (``sync_env_clock``'s ``agent_clock``, off by default) has agents follow: +``sync_env_clock`` has every agent registered with the env follow once it has armed the clock, and ``deploy_agent`` an +agent it deploys while that clock is armed. An agent has one follower, so it follows one env's clock: the first env it's registered with (``clock_env``), whatever order steps arm clocks in, even at once; another env's is reported and skipped (``follows_another_env``). When ``teardown_sandboxes`` takes the agent's sandbox down, ``retire_followers`` has the gateway it follows stop waiting for it. Which @@ -189,13 +190,16 @@ def _armed(context: TaskStepContext, env: DeployedEnv) -> Optional[dict]: async def follow_armed_clocks(context: TaskStepContext, agent: DeployedAgent, *, timeout: float = LATE_FOLLOW_TIMEOUT_S) -> list[dict]: """Have an agent ``deploy_agent`` just deployed follow the clock of each env registered with it that this run has - armed, as ``sync_env_clock`` has every agent then: one that can't is reported and skipped, or fails the step under - that step's ``require_agent_clock``.""" + armed with ``agent_clock``, as ``sync_env_clock`` has every agent then: one that can't is reported and skipped, or + fails the step under that step's ``require_agent_clock``. A clock armed without it, or by a run from before it, is + one agents don't follow.""" outcomes = [] for env_id in agent.env_ids: env = _agent_deployment(context, agent, env_id) if env is None or gateway_url_of(env) is None or (armed := _armed(context, env)) is None: continue + if not armed.get("agent_clock", False): + continue outcome = await follow_in(context, agent, env, env_get_time_url=armed.get("env_get_time_url"), timezone=armed.get("timezone"), timeout=timeout) if not outcome["synced"] and armed.get("require_agent_clock", False): diff --git a/src/agent_env/agents/README.md b/src/agent_env/agents/README.md index 10d858f57..75e3cb990 100644 --- a/src/agent_env/agents/README.md +++ b/src/agent_env/agents/README.md @@ -40,11 +40,15 @@ its own user under root's supervisord (`start-agent`, `root.conf`), with agent-e agent's user. The A2A server starts with the real-time marker, so it and its records stay on real time, and serves clock/v1's `sync_time`, which the protocol's framework serves on the card of any agent in an image with the follower -(`agentenv_protocol.a2a_agent.clock`). Once `sync_env_clock` has armed the clock, it declares the agent at the gateway -as a follower with a read token of its own and calls that `sync_time` with the follower's config, which the server -writes; `deploy_agent` does the same for an agent it deploys while the clock is armed. From then on the CLI, its own -"Today's date is" line included, and every command the model runs read the env's time, and a clock write that waits for -followers waits for the agent. While the clock is armed the CLI goes out through the egress proxy, which keeps TLS +(`agentenv_protocol.a2a_agent.clock`). An agent follows the env's clock only when the task opts in: once a +`sync_env_clock` with `agent_clock` (off by default; `require_agent_clock` implies it) has armed the clock, it declares +the agent at the gateway as a follower with a read token of its own and calls that `sync_time` with the follower's +config, which the server writes; `deploy_agent` does the same for an agent it deploys while that clock is armed. +From then on the CLI, its own "Today's date is" line included, and every command the model runs read the env's time, +and a clock write that waits for followers waits for the agent. Without `agent_clock` the agent keeps real time, as its +files' modification times do, and reads the env's time only from the gateway's `get_time`: a CLI that judges a file's +age by those times, as Claude Code's transcript cleanup does, would otherwise take a fresh file for one as old as the +env's date is ahead. While the clock is armed the CLI goes out through the egress proxy, which keeps TLS working at any date the clock shows, a live site's, an env MCP server's or the model endpoint's; only loopback hosts (the peer-agents MCP server's), `host.docker.internal`, the hosts the agent's `NO_PROXY` names and the hosts it reaches by plain HTTP alone, which have no certificate to check, go direct. `NO_PROXY` goes by host, not scheme, so a host the 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 53d6c1f70..f21128882 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 @@ -5,10 +5,11 @@ env card lists (``legacy_protocol.backing_servers``) whose own card advertises it, at the route that card gives. An env whose card offers no set_time has no gateway clock to arm, as a computer deployed alone, and is refused saying to deploy it in a multi env; a record that kept no card is refused saying so. -Then has every agent registered with the env whose card serves clock/v1 sync_time follow the clock as a computer does -(``agent_env.a2a_agent.clock``), so every program it runs reads the env's time and later clock writes can wait for it. -An agent that can't is skipped, as every agent is until its image runs the follower, or fails the step with -require_agent_clock. +With agent_clock (off by default), then has every agent registered with the env whose card serves clock/v1 sync_time +follow the clock as a computer does (``agent_env.a2a_agent.clock``), so every program it runs reads the env's time and +later clock writes can wait for it. An agent that can't is skipped, as every agent is until its image runs the follower, +or fails the step with require_agent_clock. Without it, agents keep real time: a CLI that judges its files' age by +their modification times, which stay real, would take a fresh file for one as old as the env's date is ahead. Non-advertisers are skipped when tolerate_missing_sync_time (default True), and websites always. Place right before prompt_agent so the virtual timeline starts at agent-start; when setup needs the clock armed, arm it at rate 0 and start it with set_env_clock_rate right before prompt_agent. @@ -82,6 +83,7 @@ def __init__( timeout_seconds: int = 30, timezone: Optional[str] = None, require_agent_clock: bool = False, + agent_clock: bool = False, ): """virtual_seconds_per_real_second = clock speed (1.0 real time, 0 frozen, 86400 cap = 1 real s -> 1 virtual day). For ~V virtual seconds over an ~R-real-second task, pass V/R. @@ -90,8 +92,11 @@ def __init__( 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). + agent_clock = have every agent registered with the env follow its clock, and an agent deploy_agent deploys + later on it too; off, they keep real time. + require_agent_clock = fail the step when an agent registered with the env can't follow its clock, rather than - skip it; apart from tolerate_missing_sync_time, which is about the env's servers.""" + skip it; apart from tolerate_missing_sync_time, which is about the env's servers. It implies agent_clock.""" 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") @@ -101,6 +106,7 @@ def __init__( self.virtual_seconds_per_real_second = virtual_seconds_per_real_second self.tolerate_missing_sync_time = tolerate_missing_sync_time self.require_agent_clock = require_agent_clock + self.agent_clock = agent_clock or require_agent_clock self.timeout_seconds = timeout_seconds self.timezone = timezone.strip() if isinstance(timezone, str) else timezone self.armed_virtual_time = resolve_virtual_time(virtual_time, self.timezone) @@ -117,6 +123,8 @@ def to_dict(self) -> dict: base["timezone"] = self.timezone if self.require_agent_clock: base["require_agent_clock"] = True + if self.agent_clock: + base["agent_clock"] = True return base @classmethod @@ -131,6 +139,7 @@ def from_dict(cls, data: dict) -> SyncEnvClockTaskStep: timeout_seconds=data.get("timeout_seconds", 30), timezone=data.get("timezone"), require_agent_clock=data.get("require_agent_clock", False), + agent_clock=data.get("agent_clock", False), ) async def _backing_servers(self, deployed) -> list[BackingServer]: @@ -177,13 +186,13 @@ async def execute(self, context: TaskStepContext) -> TaskStepContext: entry = {"service": service, "environment": service, **({} if server.mcp else {"website": True}), **outcome} (synced if outcome.get("synced") else skipped).append(entry) - agents = await self._follow_agents(context, deployed, env_get_time_url) + agents = await self._follow_agents(context, deployed, env_get_time_url) if self.agent_clock else [] configuration = { "step_id": self.id, "env_id": self.env_id, "deploy_step_id": (deployed.metadata or {}).get("deploy_step_id"), "virtual_time": self.virtual_time, "virtual_seconds_per_real_second": self.virtual_seconds_per_real_second, "env_get_time_url": env_get_time_url, "synced": synced, "skipped": skipped, "agents": agents, - "require_agent_clock": self.require_agent_clock, + "require_agent_clock": self.require_agent_clock, "agent_clock": self.agent_clock, } if self.timezone is not None: configuration.update(timezone=self.timezone, armed_at=self.armed_virtual_time, diff --git a/tst/unit/task_step/agent_clock_test.py b/tst/unit/task_step/agent_clock_test.py index 551ba0cd0..a5b92f2c6 100644 --- a/tst/unit/task_step/agent_clock_test.py +++ b/tst/unit/task_step/agent_clock_test.py @@ -1,8 +1,8 @@ -"""Agents on the env's clock: once sync_env_clock has armed it, every agent registered with the env whose card serves +"""Agents on the env's clock: once sync_env_clock has armed it with agent_clock, every agent registered with the env whose card serves clock/v1 sync_time is declared at the gateway as a follower with a token of its own and handed the follower's config; one that doesn't is reported and skipped, even when the env's servers must follow (tolerate_missing_sync_time false), or fails the step under require_agent_clock; and an agent -deploy_agent deploys while the clock is armed follows the same way.""" +deploy_agent deploys while the clock is armed follows the same way. Without agent_clock, the default, no agent follows.""" import dataclasses import json from types import SimpleNamespace @@ -15,7 +15,7 @@ from agent_env.a2a_agent import clock as agent_clock from agent_env.task_step.task_steps.sync_env_clock import SyncEnvClockTaskStep from tst.unit.task_step.sync_env_clock_test import (CLOCK_URL, T0, _CARD, _CLOCK_EXT, _ZONE_EXT, _carded, _composed_card, _mock_http, - _step) + _step as _sync_step) AGENT_URL = "http://solver:8000" AGENT_CONTROL_TOKEN = "the-agents-control-token" @@ -23,6 +23,11 @@ "request": {"required": ["env_get_time_url"], "optional": ["timezone", "watch_url", "name", "read_token"]}} +def _step(**kw) -> SyncEnvClockTaskStep: + """A sync_env_clock step that has agents follow (agent_clock), unless ``kw`` says otherwise.""" + return _sync_step(**{"agent_clock": True, **kw}) + + def _agent(name="solver", sync_time=SYNC_TIME, env_ids=("e1",), env_step_id=None) -> DeployedAgent: extensions = [{"uri": EXT_CLOCK_URI, "params": {"endpoint": "/ext/clock", "methods": {"sync_time": sync_time}}}] return DeployedAgent(agent_name=name, api_url=AGENT_URL, a2a_url=AGENT_URL, env_ids=list(env_ids), @@ -49,7 +54,7 @@ async def test_an_agent_is_declared_a_follower_then_handed_its_config_with_the_s context.deployed_envs = [_carded(await _composed_card({"mcp-email": [_ZONE_EXT]}))] await SyncEnvClockTaskStep(id="sync", version=1, env_id="e1", virtual_time="2026-01-01T06:00:00", - timezone="America/Chicago").execute(context) + timezone="America/Chicago", agent_clock=True).execute(context) declared, synced = sent[3], sent[4] assert (declared.method, str(declared.url)) == ("PUT", f"{_CARD}/clock/followers") @@ -148,7 +153,7 @@ async def test_an_agent_deployed_while_the_clock_is_armed_follows_it(monkeypatch sent = _mock_http(monkeypatch, state={"env_get_time_url": CLOCK_URL}) context = await _context() context.metadata["clock_configurations"] = [ - {"step_id": "sync", "env_id": "e1", "virtual_time": T0, "env_get_time_url": CLOCK_URL, "timezone": "Asia/Tokyo", + {"step_id": "sync", "env_id": "e1", "virtual_time": T0, "env_get_time_url": CLOCK_URL, "agent_clock": True, "timezone": "Asia/Tokyo", "require_agent_clock": False}, {"step_id": "rate", "env_id": "e1", "virtual_seconds_per_real_second": 60, "virtual_time": T0}, ] @@ -173,7 +178,7 @@ async def test_an_agent_deployed_before_any_clock_is_armed_is_left_alone(monkeyp async def test_a_late_agent_that_cant_follow_fails_a_deploy_only_under_require_agent_clock(monkeypatch): _mock_http(monkeypatch) context = await _context() - context.metadata["clock_configurations"] = [{"env_id": "e1", "env_get_time_url": CLOCK_URL}] + context.metadata["clock_configurations"] = [{"env_id": "e1", "env_get_time_url": CLOCK_URL, "agent_clock": True}] [skipped] = await agent_clock.follow_armed_clocks(context, _agent("late", sync_time=None), timeout=5) assert (skipped["synced"], skipped["reason"]) == (False, "not_advertised") context.metadata["clock_configurations"][0]["require_agent_clock"] = True @@ -181,6 +186,39 @@ async def test_a_late_agent_that_cant_follow_fails_a_deploy_only_under_require_a await agent_clock.follow_armed_clocks(context, _agent("late", sync_time=None), timeout=5) +@pytest.mark.asyncio +async def test_without_agent_clock_no_agent_follows_and_one_deployed_later_doesnt_either(monkeypatch): + """Off by default: an agent on the env's clock judges its files' age by real modification times (FD-6368).""" + sent = _mock_http(monkeypatch, state={"env_get_time_url": CLOCK_URL}) + _no_servers(monkeypatch) + context = await _context(_agent()) + + await _sync_step().execute(context) + + assert [r.url.path for r in sent][3:] == [] + [configuration] = context.metadata["clock_configurations"] + assert (configuration["agents"], configuration["agent_clock"]) == ([], False) + assert await agent_clock.follow_armed_clocks(context, _agent("late"), timeout=5) == [] + assert [r.url.path for r in sent][3:] == [] + + +@pytest.mark.asyncio +async def test_a_clock_armed_by_a_run_from_before_agent_clock_has_no_late_agent_follow(monkeypatch): + sent = _mock_http(monkeypatch) + context = await _context() + context.metadata["clock_configurations"] = [{"env_id": "e1", "env_get_time_url": CLOCK_URL}] + + assert await agent_clock.follow_armed_clocks(context, _agent("late"), timeout=5) == [] + assert sent == [] + + +def test_agent_clock_round_trips_is_left_out_when_off_and_require_agent_clock_implies_it(): + assert "agent_clock" not in _sync_step().to_dict() and _sync_step().agent_clock is False + on = _sync_step(agent_clock=True).to_dict() + assert on["agent_clock"] is True and SyncEnvClockTaskStep.from_dict(on).agent_clock is True + assert _sync_step(require_agent_clock=True).agent_clock is True + + def test_require_agent_clock_round_trips_and_is_left_out_when_off(): assert "require_agent_clock" not in _step().to_dict() strict = _step(require_agent_clock=True).to_dict() @@ -192,7 +230,7 @@ def test_require_agent_clock_round_trips_and_is_left_out_when_off(): async def test_an_agent_follows_the_first_envs_clock_and_another_envs_is_reported_and_skipped(monkeypatch): sent = _mock_http(monkeypatch) context = await _context() # e1 alone is deployed and armed: whether e0 has been armed yet doesn't matter - context.metadata["clock_configurations"] = [{"env_id": "e1", "env_get_time_url": CLOCK_URL}] + context.metadata["clock_configurations"] = [{"env_id": "e1", "env_get_time_url": CLOCK_URL, "agent_clock": True}] [outcome] = await agent_clock.follow_armed_clocks(context, _agent("late", env_ids=("e0", "e1")), timeout=5) @@ -252,7 +290,7 @@ async def test_late_agents_deployed_at_once_each_save_only_their_own_record(monk _mock_http(monkeypatch) pre = await _context() - pre.metadata["clock_configurations"] = [{"env_id": "e1", "env_get_time_url": CLOCK_URL}] + pre.metadata["clock_configurations"] = [{"env_id": "e1", "env_get_time_url": CLOCK_URL, "agent_clock": True}] saved = {} for name in ("first", "second"): # each from the same context, as two deploy_agent steps at once post = copy.deepcopy(pre) @@ -363,14 +401,14 @@ async def test_a_late_agent_follows_only_its_own_deployments_armed_clock(monkeyp sent = _mock_http(monkeypatch) context = await _two_deployments() context.metadata["clock_configurations"] = [ - {"env_id": "e1", "deploy_step_id": "deploy-b", "env_get_time_url": CLOCK_URL}] + {"env_id": "e1", "deploy_step_id": "deploy-b", "env_get_time_url": CLOCK_URL, "agent_clock": True}] late = _agent("late", env_step_id="deploy-a") assert await agent_clock.follow_armed_clocks(context, late, timeout=5) == [] assert sent == [] context.metadata["clock_configurations"].append({"env_id": "e1", "deploy_step_id": "deploy-a", - "env_get_time_url": CLOCK_URL}) + "env_get_time_url": CLOCK_URL, "agent_clock": True}) [outcome] = await agent_clock.follow_armed_clocks(context, late, timeout=5) assert outcome["synced"] is True assert str(sent[0].url) == "https://sandbox.example/sb-a/clock/followers"