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
16 changes: 11 additions & 5 deletions src/agent_env/agents/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,11 +44,17 @@ The A2A server starts with the real-time marker, so it and its records stay on r
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 a live
site's TLS working at any date the clock shows, and to the env's MCP servers and a plain-HTTP model endpoint directly.
The image's proxy reaches private networks too (`AGENTENV_EGRESS_PRIVATE`), so a model endpoint 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. Started
as a user other than root, the image runs the A2A server alone, on real time, as before.
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.

`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
2 changes: 2 additions & 0 deletions src/agent_env/agents/agents/claude-code/Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,8 @@ COPY requirements.txt model-requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt -r model-requirements.txt
# install.sh and run.sh are install/v1's: in the image, so they stay in its build context.
COPY a2a_server.py claude_bridge.py kit.py tar_changelog.py entrypoint.sh install.sh run.sh ./
# Every clocked agent's egress rule, which the bridge imports, and the clock page's format it reads (shared_sources.toml).
COPY agent_clock/agent_egress.py clock/clockpage.py ./
# The CLI's cwd, /app, and its state, fixed so neither follows the uid.
RUN useradd --create-home --uid 10001 agent && mkdir -p /app /home/agent/.claude \
&& chown agent:agent /app /home/agent/.claude && chmod 0755 entrypoint.sh
Expand Down
76 changes: 4 additions & 72 deletions src/agent_env/agents/agents/claude-code/claude_bridge.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,17 +11,16 @@
import re
import signal
import stat
import struct
import time
from collections.abc import Callable, Iterable, Mapping
from dataclasses import dataclass, field, replace
from functools import partial
from pathlib import Path
from typing import Literal
from urllib.parse import urlsplit

from pydantic import BaseModel, ConfigDict, model_validator

from agent_egress import clock_armed, egress_env
from kit import in_thread_to_its_end

logger = logging.getLogger(__name__)
Expand Down Expand Up @@ -175,74 +174,9 @@ def _model_headers(raw: str | None) -> dict[str, str]:
return {str(name): str(value) for name, value in headers.items()}


#: Set by the image (root.conf) where the egress proxy runs: the CLI and the model's commands go out through it
#: while the agent follows an armed clock.
EGRESS_PROXY_ENV = "AGENTENV_EGRESS_PROXY"
#: The clock page agent-env's libfaketime reads the CLI's time from (clock/clockpage.py, version 2): it keeps the last
#: armed clock while the follower reconnects or restarts, which the follower's status doesn't say.
CLOCK_PAGE = "/dev/shm/agentenv-clock"
_PAGE = struct.Struct("<IIQqqdIIQQqq") # magic version seq universe_ns anchor_ns rate armed reserved generation check ...
_PAGE_MAGIC, _PAGE_VERSION, _MASK = 0x4B434541, 2, 0xFFFFFFFFFFFFFFFF
#: The constant every page's check is salted with (clockpage.check).
_PAGE_CHECK_SALT = 0x9E3779B97F4A7C15
#: How often, and how far apart, a read retries a page a write is under way on: 50 ms in all, far longer than a write.
_PAGE_READ_TRIES, _PAGE_RETRY_S = 50, 0.001
_DIRECT_HOSTS = ("localhost", "127.0.0.1", "::1", "host.docker.internal")


def clock_armed(page_path: str | None = None) -> bool:
"""Whether the clock page holds an armed clock, so the CLI started now reads the env's time: the page itself,
as libfaketime reads it, retried while a write is under way (seq odd) or its check doesn't match."""
try:
with open(page_path or CLOCK_PAGE, "rb") as page:
for _ in range(_PAGE_READ_TRIES):
page.seek(0)
raw = page.read(_PAGE.size)
if len(raw) < _PAGE.size:
return False
magic, version, seq, universe, anchor, rate, armed, _, generation, checked, mono_u, mono_a = \
_PAGE.unpack(raw)
if magic != _PAGE_MAGIC or version != _PAGE_VERSION:
return False
rate_bits = struct.unpack("<Q", struct.pack("<d", rate))[0]
expected = (seq ^ (universe & _MASK) ^ (anchor & _MASK) ^ rate_bits ^ armed ^ generation
^ (mono_u & _MASK) ^ (mono_a & _MASK) ^ _PAGE_CHECK_SALT) & _MASK
if seq % 2 == 0 and checked == expected:
return bool(armed)
time.sleep(_PAGE_RETRY_S)
except OSError:
return False
return bool(armed) # a writer that died mid-write: the next write takes the page up; its armed flag says the most


def model_direct_hosts(base_url: str | None) -> list[str]:
"""The model endpoint's host when the CLI reaches it directly on an armed clock: over plain HTTP, which has no
certificate to check at the env's date. Over TLS it goes through the egress proxy, which checks the certificate on
real time and, in an agent's image, reaches a private network's address too (``AGENTENV_EGRESS_PRIVATE``)."""
endpoint = urlsplit(base_url or "")
return [endpoint.hostname] if endpoint.hostname and endpoint.scheme == "http" else []


def egress_env(environ: Mapping[str, str], direct: Iterable[str] = (), *, armed: bool = False) -> dict[str, str]:
"""The egress proxy for the CLI and what it starts, where the image runs one (FD-5916) and the clock is ``armed``:
they read the env's time, so a client checking a live site's certificate against it would refuse the site once
the clock is months off, and the proxy, on real time, hands it a certificate that holds then. The env's MCP servers
(``direct``) are reached directly: the proxy refuses an address that isn't global, as a local or private gateway's
is. Unarmed, the CLI reads real time and goes out directly, as an image without the proxy does, so a model endpoint
or mirror at a private address keeps working. Hosts the agent was deployed to reach directly (``NO_PROXY``,
``no_proxy``) stay direct."""
proxy = environ.get(EGRESS_PROXY_ENV)
if not proxy or not armed:
return {}
configured = [host.strip() for name in ("NO_PROXY", "no_proxy") for host in (environ.get(name) or "").split(",")]
hosts = ",".join(dict.fromkeys([*_DIRECT_HOSTS, *filter(None, configured), *filter(None, direct)]))
return {**{name: proxy for base in ("HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY") for name in (base, base.lower())},
"NO_PROXY": hosts, "no_proxy": hosts, "NODE_USE_ENV_PROXY": "1"}


def cli_env(environ: Mapping[str, str], *, model: str | None = None, project_id: str | None = None,
task_id: str | None = None, max_thinking_tokens: int | None = None,
direct_hosts: Iterable[str] = (), clock_armed: bool = False) -> dict[str, str]:
clock_armed: bool = False, mcp_urls: Iterable[str] = ()) -> dict[str, str]:
"""The CLI's environment: this process's, pointed at the endpoint agent-env configured (its key as a bearer
token, so an API key too would conflict), with the endpoint's headers and the run's attribution, and the model's
aliases pinned to ``model`` on that endpoint. A variable already set is kept, LITELLM_* too, so a script the model
Expand Down Expand Up @@ -271,8 +205,7 @@ def cli_env(environ: Mapping[str, str], *, model: str | None = None, project_id:
# Older CLIs prepend a changing attribution block to the system prompt on custom base URLs, which defeats the
# provider's prefix cache.
env["CLAUDE_CODE_ATTRIBUTION_HEADER"] = "0"
model_hosts = model_direct_hosts(env.get("ANTHROPIC_BASE_URL")) if clock_armed else []
env.update(egress_env(environ, [*direct_hosts, *model_hosts], armed=clock_armed))
env.update(egress_env(environ, [env.get("ANTHROPIC_BASE_URL", ""), *mcp_urls], armed=clock_armed))
return env


Expand Down Expand Up @@ -753,8 +686,7 @@ async def _spawn_claude(
stderr=asyncio.subprocess.PIPE,
env=cli_env(os.environ, model=model, project_id=project_id, task_id=task_id,
max_thinking_tokens=max_thinking_tokens, clock_armed=clock_armed(),
direct_hosts=[urlsplit(str(entry.get("url") or "")).hostname or ""
for entry in (mcp_servers or {}).values()]),
mcp_urls=[info["url"] for info in (mcp_servers or {}).values()]),
cwd=WORKSPACE_DIR,
start_new_session=True,
))
Expand Down
4 changes: 2 additions & 2 deletions src/agent_env/agents/agents/claude-code/install.sh
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ PYTHON_VERSION=3.12
START_TIMEOUT_S=120
STOP_TIMEOUT_S=10
CLAUDE_CODE_VERSION=$(sed -n 's/^ARG CLAUDE_CODE_VERSION=//p' "$here/Dockerfile")
AGENT_FILES="a2a_server.py claude_bridge.py kit.py requirements.txt run.sh tar_changelog.py"
AGENT_FILES="a2a_server.py claude_bridge.py kit.py requirements.txt run.sh tar_changelog.py agent_clock/agent_egress.py clock/clockpage.py"

# put SRC DEST replaces DEST by a rename, so a binary an earlier install's agent still runs can be replaced.
case $mode in
Expand Down Expand Up @@ -123,7 +123,7 @@ put "$stage/claude" "$root/bin/claude"
put "$stage/uv-$uv_cpu-unknown-linux-musl/uv" "$root/bin/uv"
put "$stage/agent.env" "$root/agent.env"
for file in $AGENT_FILES; do
put "$here/$file" "$root/app/$file"
put "$here/$file" "$root/app/${file##*/}"
done
on "chmod 0600 $r/agent.env && chmod 0755 $r/bin/claude $r/bin/uv $r/app/run.sh"

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,4 @@
# copy of each, shared with the other images that take it (utils/docker/context.py). Paths are under src/agent_env.
clock = "utils/faketime_clock"
egress = "utils/egress_proxy"
agent_clock = "utils/agent_clock"
2 changes: 2 additions & 0 deletions src/agent_env/agents/agents/opencode/Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,8 @@ COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
# install.sh and run.sh are install/v1's: in the image, so they stay in its build context.
COPY a2a_server.py opencode_bridge.py opencode_kit.py entrypoint.sh install.sh run.sh ./
# Every clocked agent's egress rule, which the bridge imports, and the clock page's format it reads (shared_sources.toml).
COPY agent_clock/agent_egress.py clock/clockpage.py ./
# The CLI's cwd, /app, and its state under /data, fixed so neither follows the uid.
RUN useradd --create-home --uid 10001 agent && mkdir -p /app /data \
&& chown agent:agent /app /data && chmod 0755 entrypoint.sh
Expand Down
4 changes: 2 additions & 2 deletions src/agent_env/agents/agents/opencode/install.sh
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ START_TIMEOUT_S=120
STOP_TIMEOUT_S=10
dockerfile_arg() { sed -n "s/^ARG $1=//p" "$here/Dockerfile"; }
NODE_VERSION=$(dockerfile_arg NODE_VERSION)
AGENT_FILES="a2a_server.py opencode_bridge.py opencode_kit.py requirements.txt run.sh"
AGENT_FILES="a2a_server.py opencode_bridge.py opencode_kit.py requirements.txt run.sh agent_clock/agent_egress.py clock/clockpage.py"

# put SRC DEST replaces DEST by a rename, so a binary an earlier install's agent still runs can be replaced; put_dir SRC
# DEST copies a folder to DEST, which isn't there.
Expand Down Expand Up @@ -135,7 +135,7 @@ put "$stage/agent.env" "$root/agent.env"
put "$here/package.json" "$root/npm/package.json"
put "$here/package-lock.json" "$root/npm/package-lock.json"
for file in $AGENT_FILES; do
put "$here/$file" "$root/app/$file"
put "$here/$file" "$root/app/${file##*/}"
done
on "chmod 0600 $r/agent.env && chmod 0755 $r/bin/uv $r/bin/opencode $r/app/run.sh"

Expand Down
84 changes: 8 additions & 76 deletions src/agent_env/agents/agents/opencode/opencode_bridge.py
Original file line number Diff line number Diff line change
Expand Up @@ -22,19 +22,18 @@
import os
import re
import signal
import struct
import threading
import time
from collections.abc import Callable, Iterable, Mapping
from collections.abc import Callable, Mapping
from dataclasses import dataclass, field
from datetime import datetime, timezone
from pathlib import Path
from typing import Literal
from urllib.parse import urlsplit

from jsonschema import Draft202012Validator, SchemaError, ValidationError
from pydantic import BaseModel, ConfigDict, model_validator

from agent_egress import clock_armed, egress_env

logger = logging.getLogger(__name__)

# The model a run uses when neither the task nor the agent-config names one; the
Expand Down Expand Up @@ -99,80 +98,13 @@ def _context_xdg(context_id: str) -> dict[str, str]:
return {"XDG_DATA_HOME": str(data_dir / "share"), "XDG_STATE_HOME": str(data_dir / "state")}


#: Set by the image (root.conf) where the egress proxy runs: the CLI and the model's commands go out through it
#: while the agent follows an armed clock.
EGRESS_PROXY_ENV = "AGENTENV_EGRESS_PROXY"
#: The clock page agent-env's libfaketime reads the CLI's time from (clock/clockpage.py, version 2): it keeps the last
#: armed clock while the follower reconnects or restarts, which the follower's status doesn't say.
CLOCK_PAGE = "/dev/shm/agentenv-clock"
_PAGE = struct.Struct("<IIQqqdIIQQqq") # magic version seq universe_ns anchor_ns rate armed reserved generation check ...
_PAGE_MAGIC, _PAGE_VERSION, _MASK = 0x4B434541, 2, 0xFFFFFFFFFFFFFFFF
#: The constant every page's check is salted with (clockpage.check).
_PAGE_CHECK_SALT = 0x9E3779B97F4A7C15
#: How often, and how far apart, a read retries a page a write is under way on: 50 ms in all, far longer than a write.
_PAGE_READ_TRIES, _PAGE_RETRY_S = 50, 0.001
_DIRECT_HOSTS = ("localhost", "127.0.0.1", "::1", "host.docker.internal")


def clock_armed(page_path: str | None = None) -> bool:
"""Whether the clock page holds an armed clock, so the CLI started now reads the env's time: the page itself,
as libfaketime reads it, retried while a write is under way (seq odd) or its check doesn't match."""
try:
with open(page_path or CLOCK_PAGE, "rb") as page:
for _ in range(_PAGE_READ_TRIES):
page.seek(0)
raw = page.read(_PAGE.size)
if len(raw) < _PAGE.size:
return False
magic, version, seq, universe, anchor, rate, armed, _, generation, checked, mono_u, mono_a = \
_PAGE.unpack(raw)
if magic != _PAGE_MAGIC or version != _PAGE_VERSION:
return False
rate_bits = struct.unpack("<Q", struct.pack("<d", rate))[0]
expected = (seq ^ (universe & _MASK) ^ (anchor & _MASK) ^ rate_bits ^ armed ^ generation
^ (mono_u & _MASK) ^ (mono_a & _MASK) ^ _PAGE_CHECK_SALT) & _MASK
if seq % 2 == 0 and checked == expected:
return bool(armed)
time.sleep(_PAGE_RETRY_S)
except OSError:
return False
return bool(armed) # a writer that died mid-write: the next write takes the page up; its armed flag says the most


def model_direct_hosts(base_url: str | None) -> list[str]:
"""The model endpoint's host when the CLI reaches it directly on an armed clock: over plain HTTP, which has no
certificate to check at the env's date. Over TLS it goes through the egress proxy, which checks the certificate on
real time and, in an agent's image, reaches a private network's address too (``AGENTENV_EGRESS_PRIVATE``)."""
endpoint = urlsplit(base_url or "")
return [endpoint.hostname] if endpoint.hostname and endpoint.scheme == "http" else []


def egress_env(environ: Mapping[str, str], direct: Iterable[str] = (), *, armed: bool = False) -> dict[str, str]:
"""The egress proxy for the CLI and what it starts, where the image runs one (FD-5916) and the clock is ``armed``:
they read the env's time, so a client checking a live site's certificate against it would refuse the site once
the clock is months off, and the proxy, on real time, hands it a certificate that holds then. The env's MCP servers
(``direct``) are reached directly: the proxy refuses an address that isn't global, as a local or private gateway's
is. Unarmed, the CLI reads real time and goes out directly, as an image without the proxy does, so a model endpoint
or mirror at a private address keeps working. Hosts the agent was deployed to reach directly (``NO_PROXY``,
``no_proxy``) stay direct."""
proxy = environ.get(EGRESS_PROXY_ENV)
if not proxy or not armed:
return {}
configured = [host.strip() for name in ("NO_PROXY", "no_proxy") for host in (environ.get(name) or "").split(",")]
hosts = ",".join(dict.fromkeys([*_DIRECT_HOSTS, *filter(None, configured), *filter(None, direct)]))
return {**{name: proxy for base in ("HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY") for name in (base, base.lower())},
"NO_PROXY": hosts, "no_proxy": hosts, "NODE_USE_ENV_PROXY": "1"}


def cli_env(context_id: str, environ: Mapping[str, str] = os.environ, *, mcp_servers: dict[str, dict] | None = None,
clock_armed: bool = False) -> dict[str, str]:
"""The CLI's environment for ``context_id``: this process's, with the context's own data and state dirs. On an
armed clock (``clock_armed``) the CLI goes out through the egress proxy (``egress_env``), reaching the env's MCP
servers (``mcp_servers``), which it connects to itself, and a plain-HTTP model endpoint directly."""
model_host = model_direct_hosts(environ.get("LITELLM_BASE_URL")) if clock_armed else []
mcp_hosts = [url.hostname for url in (urlsplit(str(info.get("url") or "")) for info in (mcp_servers or {}).values()) if url.hostname and url.scheme == "http"]
return {**environ, **_context_xdg(context_id),
**egress_env(environ, [*mcp_hosts, *model_host], armed=clock_armed)}
"""The CLI's environment for ``context_id``: this process's, with the context's own data and state dirs, and on an
armed clock the egress proxy (``egress_env``) for the model endpoint and the env's MCP servers, which the CLI
connects to itself."""
urls = [environ.get("LITELLM_BASE_URL", ""), *(info["url"] for info in (mcp_servers or {}).values())]
return {**environ, **_context_xdg(context_id), **egress_env(environ, urls, armed=clock_armed)}


async def _communicate(*cmd: str, env: Mapping[str, str], timeout_s: int) -> tuple[int, bytes, bytes]:
Expand Down
1 change: 1 addition & 0 deletions src/agent_env/agents/agents/opencode/shared_sources.toml
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,4 @@
# copy of each, shared with the other images that take it (utils/docker/context.py). Paths are under src/agent_env.
clock = "utils/faketime_clock"
egress = "utils/egress_proxy"
agent_clock = "utils/agent_clock"
Loading
Loading