Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 27 additions & 12 deletions src/agent_env/a2a_agent/clock.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -186,23 +187,37 @@ def _armed(context: TaskStepContext, env: DeployedEnv) -> Optional[dict]:
and c.get("deploy_step_id", _deploy_step_of(env)) == _deploy_step_of(env)), None)


async def follow_agents(context: TaskStepContext, env: DeployedEnv, agents, *, env_get_time_url: Optional[str],
timezone: Optional[str], required: bool, timeout: float) -> list[dict]:
"""Have each of ``agents`` follow ``env``'s clock (``follow_in``), for ``sync_env_clock`` and a late
``deploy_agent`` alike: one that can't is reported and skipped, or fails the step when ``required``."""
outcomes = []
for agent in agents:
outcome = await follow_in(context, agent, env, env_get_time_url=env_get_time_url, timezone=timezone,
timeout=timeout)
if not outcome["synced"] and required:
raise StepContextError(f"agent '{agent.agent_name}' can't follow the clock of env '{env.env_id}': "
f"{outcome['reason']}")
logger.info(f"agent '{agent.agent_name}' on env {env.env_id}'s clock: {summary(outcome)}")
outcomes.append({"agent": agent.agent_name, **outcome})
return outcomes


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 (``follow_agents``). 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:
armed = _armed(context, env) if env is not None and gateway_url_of(env) is not None else None
if armed is None or 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):
raise StepContextError(f"agent '{agent.agent_name}' can't follow the clock of env '{env_id}': "
f"{outcome['reason']}")
logger.info(f"agent '{agent.agent_name}' on env {env_id}'s clock: {summary(outcome)}")
outcomes.append({"env_id": env_id, "agent": agent.agent_name, **outcome})
followed = await follow_agents(context, env, [agent], env_get_time_url=armed.get("env_get_time_url"),
timezone=armed.get("timezone"), required=armed.get("require_agent_clock", False),
timeout=timeout)
outcomes.extend({"env_id": env_id, **outcome} for outcome in followed)
return outcomes


Expand Down
47 changes: 28 additions & 19 deletions src/agent_env/agents/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,27 +34,36 @@ turn off becomes `--disallowedTools`, which keeps the CLI's defaults for the res
`claude_bridge.py`: every tool the pinned CLI has, though which it offers by default depends on the model. A test fails
when the Dockerfile's `CLAUDE_CODE_VERSION` moves, until `ClaudeCodeTool` and `TOOLS_CLI_VERSION` move with it.

The image follows a task env's clock the way a computer does (FD-5916): it runs the computer base's clock follower
and egress proxy, taken from `utils/faketime_clock` and `utils/egress_proxy` through its `shared_sources.toml`, each as
its own user under root's supervisord (`start-agent`, `root.conf`), with agent-env's libfaketime preloaded for the
agent's user.
The image can follow a task env's clock the way a computer does. It runs the computer base's clock follower and egress
proxy, taken from `utils/faketime_clock` and `utils/egress_proxy` through its `shared_sources.toml`, each as its own
user under root's supervisord (`start-agent`, `root.conf`), with agent-env's libfaketime preloaded for the 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
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
agent also reaches over TLS stays behind the proxy. The image's proxy reaches private networks too
(`AGENTENV_EGRESS_PRIVATE`), so a host over TLS at a private address works at any date as well. Unarmed, the page holds
real time and the CLI goes out directly, as before. That rule is `agent_egress.py` in `utils/agent_clock`, which only
agent images take (`agent_clock` in `shared_sources.toml`), so changing it rebuilds no computer base. The bridge
imports it, and the image and `install.sh` copy it beside the bridge with the clock's `clockpage.py`, whose layout and
check it reads the page by, so every agent put on the clock, OpenCode's too, goes out the same way. Started as a user
other than root, the image runs the A2A server alone, on real time, as before.
(`agentenv_protocol.a2a_agent.clock`).

- **Off by default.** Without `agent_clock` on `sync_env_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.
- **Opted in.** Once a `sync_env_clock` with `agent_clock` (`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 its `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.
- **For the rest of the run.** An agent that follows goes on following: a later `sync_env_clock` without `agent_clock`
re-arms the clock it follows, and only agents that never followed keep real time.
- **Through the egress proxy.** While the agent follows an armed clock, 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 agent also reaches over TLS stays behind the proxy. The image's proxy reaches private networks
too (`AGENTENV_EGRESS_PRIVATE`), so a host over TLS at a private address works at any date as well. Unarmed, the page
holds real time and the CLI goes out directly.
- **One rule for every clocked agent.** That rule is `agent_egress.py` in `utils/agent_clock`, which only agent images
take (`agent_clock = "utils/agent_clock"` in `shared_sources.toml`), so changing it rebuilds no computer base. The
bridge imports it, and the image and `install.sh` copy it beside the bridge with the clock's `clockpage.py`, whose
layout and check it reads the page by, so every agent put on the clock, OpenCode's too, goes out the same way.

Started as a user other than root, the image runs the A2A server alone, on real time, as before.

`install_agent` installs it too, into a container a task already runs or onto a `vm` sandbox's Linux host, with
`install.sh` from its folder: Claude Code's native build for the target's CPU and libc, uv, and the agent's requirements
Expand Down
55 changes: 24 additions & 31 deletions src/agent_env/task_step/task_steps/sync_env_clock.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -25,7 +26,8 @@
import tzdata # noqa: F401
from agentenv_protocol import client as protocol_v1

from agent_env.env.env import EnvCapabilityUnsupported
from agent_env.a2a_agent.clock import follow_agents, on_deployment, torn_down
from agent_env.env.env import Env, EnvCapabilityUnsupported, gateway_url_of
from agent_env.env.gateway.constants import EXT_CLOCK_URI
from agent_env.task_step.context import StepContextError, TaskStepContext
from agent_env.entity.refs import EntityRef
Expand Down Expand Up @@ -82,6 +84,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.
Expand All @@ -90,8 +93,12 @@ 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, agents that don't already follow keep real time, while one an earlier step had follow
goes on following, re-armed with the clock.

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")
Expand All @@ -101,6 +108,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)
Expand All @@ -117,6 +125,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
Expand All @@ -131,18 +141,17 @@ 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]:
"""The env's backing MCP servers and websites, as its card lists them (``legacy_protocol.backing_servers``):
a website sharing its name with an MCP server is a server of its own, at its own route."""
from agent_env.env import legacy_protocol
from agent_env.env.env import Env, gateway_url_of
return await legacy_protocol.backing_servers(deployed, gateway_url_of(deployed), Env.get(deployed.env_id, deployed.env_version),
timeout=self.timeout_seconds)

async def execute(self, context: TaskStepContext) -> TaskStepContext:
from agent_env.env.env import gateway_url_of

deployed = bound_deployment(context, self.env_id, env_step_id=self.env_step_id, step_id=self.id)
if deployed is None:
Expand Down Expand Up @@ -177,13 +186,18 @@ 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 follow_agents(
context, deployed, [agent for agent in context.deployed_agents
if self.env_id in (agent.env_ids or []) and on_deployment(agent, deployed)
and not torn_down(context, agent)],
env_get_time_url=env_get_time_url, timezone=self.timezone, required=self.require_agent_clock,
timeout=self.timeout_seconds) 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,
Expand All @@ -197,27 +211,6 @@ async def execute(self, context: TaskStepContext) -> TaskStepContext:
f"({[(s['service'], s.get('reason')) for s in skipped]}) — every tool still answers wall time")
return context

async def _follow_agents(self, context: TaskStepContext, deployed, env_get_time_url: Optional[str]) -> list[dict]:
"""Have every agent registered with the env follow its clock (``a2a_agent.clock.follow``): one that can't is
reported and skipped, or fails the step under ``require_agent_clock``."""
from agent_env.a2a_agent.clock import follow_in, on_deployment, torn_down

outcomes = []
for agent in context.deployed_agents:
mine = self.env_id in (agent.env_ids or []) and on_deployment(agent, deployed)
if not mine or torn_down(context, agent):
continue # not this deployment's, or taken down by teardown_sandboxes: nothing to follow
outcome = await follow_in(context, agent, deployed, env_get_time_url=env_get_time_url,
timezone=self.timezone, timeout=self.timeout_seconds)
if not outcome["synced"]:
if self.require_agent_clock:
raise StepContextError(f"agent '{agent.agent_name}' can't follow the clock of env "
f"'{self.env_id}': {outcome['reason']}")
logger.info(f"sync_env_clock: agent '{agent.agent_name}' doesn't follow the clock "
f"({outcome['reason']}); skipping")
outcomes.append({"agent": agent.agent_name, **outcome})
return outcomes

async def _sync_one(self, deployed, gateway_url: str, service: str, env_get_time_url: Optional[str], mcp: bool = True,
tolerate: Optional[bool] = None, server: Optional[BackingServer] = None) -> dict:
"""Invoke sync_time on one server, an MCP server or with ``mcp=False`` a website, if its card advertises
Expand Down
Loading
Loading