feat(task): play an outside agent through a ProxyAgent in its place

.github/dependabot.yml

@@ -46,6 +46,7 @@ updates:
       - "/src/agent_env/agents/agents/opencode"
       - "/src/agent_env/agents/agents/openhands"
       - "/src/agent_env/agents/agents/pi"
+      - "/src/agent_env/agents/agents/proxy"
     schedule:
       interval: "weekly"
     open-pull-requests-limit: 5

.github/scripts/infra_build.py

@@ -37,6 +37,7 @@
     "agentenv-opencode": "src/agent_env/agents/agents/opencode/Dockerfile",
     "agentenv-openhands": "src/agent_env/agents/agents/openhands/Dockerfile",
     "agentenv-pi": "src/agent_env/agents/agents/pi/Dockerfile",
+    "agentenv-proxy": "src/agent_env/agents/agents/proxy/Dockerfile",
 }
 _TAG = re.compile(r"^src-[0-9a-f]{64}$")
 _DIGEST = re.compile(r"^sha256:[0-9a-f]{64}$")
@@ -55,7 +56,7 @@
 
 # Each image's check, beyond its build: the gateway imports its server, Postgres turns healthy, the sidecars and the
 # browser answer their own commands, Claude Code's, Codex's, Gemini's, OpenCode's and pi's agents run their CLIs and
-# import their servers, and OpenHands' imports its server, which loads the OpenHands SDK.
+# import their servers, OpenHands' imports its server, which loads the OpenHands SDK, and the proxy imports its server.
 _SMOKES = {
     "agentenv-gateway": ["docker", "run", "--rm", "--entrypoint", "python", "{image}", "-c", "import gateway.entrypoint"],
     "agentenv-db-web": ["docker", "run", "--rm", "--entrypoint", "/usr/bin/pgweb", "{image}", "--version"],
@@ -74,6 +75,7 @@
     "agentenv-openhands": ["docker", "run", "--rm", "--entrypoint", "sh", "{image}", "-c", 'python -c "import a2a_server"'],
     "agentenv-pi": ["docker", "run", "--rm", "--entrypoint", "sh", "{image}", "-c",
                     'pi --version && python3 -c "import a2a_server"'],
+    "agentenv-proxy": ["docker", "run", "--rm", "--entrypoint", "sh", "{image}", "-c", 'python -c "import a2a_server"'],
 }
 
 

AGENTS.md

@@ -223,9 +223,15 @@ orchestrators call it the same way. What callers rely on:
 - A runner that must hear from a long step puts a zero-argument callable at
   `context.metadata[HEARTBEAT_KEY]` (`task_step/context.py`); a step that blocks for long calls
   `context.heartbeat()`, a no-op without one. The key is in `_REDACTED_KEYS`, so it is never persisted.
-- An episode (`EpisodeSpec`, `task/episode/`) is one `Task.run()` of a copy of the task in which
-  the `deploy_agent` and `prompt_agent` steps of each of its `trainer_agents` are the plain-data
-  `episode_agent` and `episode_turn`, which wait for the caller instead of deploying or prompting. Its
+- An episode (`EpisodeSpec`, `task/episode/`) is one `Task.run()` of a copy of the task, with
+  namespace routing on, in which each of its `trainer_agents` is played through a proxy agent
+  (the `agents` bundle's `proxy`, `@local/agentenv-framework/agents/proxy`, which the episode writes
+  from its folder as a bundle run would).
+  The agent's `deploy_agent` or `install_agent`, wrapped as `episode_agent`, deploys the proxy in the
+  agent's place when the task uses the agent's sandbox and serves it in this process when it doesn't;
+  the agent's `prompt_agent` steps message it as they would the agent, and the caller plays each
+  message as a `Turn` through its `urn:agentenv:proxy/v1`: every env tool call and `bash` command runs
+  in the proxy, which records the turn and checks it against the model calls the caller records. Its
   record is tagged `context.metadata["episode"]` and names the original task, so it isn't resumable
   with `start_step`. The episode tears down what its run deployed, and an abandoned one is recorded
   `cancelled`.

packages/agentenv-protocol/README.md

@@ -713,20 +713,27 @@ operations:
   "skills"}]}`. A turn its sender cancels drops out of the list.
 - `tools` (`{"token", "task_id"}`) lists what the turn can call, with input schemas: the
   tools of each env server registered through mcp-config, and `bash`. Two servers offering
-  one name are refused with 409.
+  one name are refused with 409, and servers that haven't all listed their tools within
+  600 s get 502. `record` waits for the same listing.
 - `act` (`{"token", "task_id", "action_id", "action"}`) runs one action: `{"kind": "tool",
   "server", "name", "arguments"}` calls an env server through `ToolSession`, with the URL
   and headers registered for it, and `{"kind": "bash", "command"}` runs `bash -c` in the
-  proxy's folder, as its user, in a process group of its own; either takes
+  proxy's folder, as its user, in a process group of its own. Where there is no `bash`, as
+  in a minimal image, it runs `sh -c`, and the `bash` tool's description says so. A command
+  is done when its shell exits: what it started in the background keeps running, and output
+  that arrives more than a second later is read and dropped. Either takes
   `"timeout_seconds"` (3600 for `bash`, 600 for a tool by default). The driver picks
-  `action_id`, so a retried `act` returns the action it already started. It answers
-  `{"done", "result"}` at once when the action ends within the long-poll; `result`
-  (`{"token", "action_id"}`) long-polls one that doesn't. A `bash` result is
-  `{"exit_code", "stdout", "stderr", "timed_out"}`, a tool's `{"content", "is_error"}`.
+  `action_id`, unique for the proxy, so a retried `act` returns the action it already
+  started. It answers `{"done", "result"}` at once when the action ends within the long-poll;
+  `result` (`{"token", "action_id"}`) long-polls one that doesn't, and gets 404 once the
+  action's turn has closed. A `bash` result is `{"exit_code", "stdout", "stderr",
+  "timed_out"}`, with no `exit_code` when the command was stopped and 126 when it couldn't
+  start; a tool's is `{"content", "is_error"}`.
 - `record` (`{"token", "task_id", "message", "model", "usage"}`) records one model call: an
   OpenAI chat message, an Anthropic message or a string; anything else gets 400. Once a turn
   records a call, each action must be one the last recorded call made, by name and
-  arguments, and all of them must run before the next `record` or the `reply`, else 409.
+  arguments (a `bash` call by its command alone, a whole float equal to its int), and all of
+  them must run before the next `record` or the `reply`, else 409.
   Calls to tools the turn doesn't offer aren't checked.
 - `reply` (`{"token", "task_id", "parts"}`, or `"error"` in place of `"parts"`) ends the
   turn: parts complete the task, and an error fails it as `proxy.driver_error`.
@@ -735,7 +742,9 @@ A turn's actions belong to it: when it closes, by reply or withdrawal, those sti
 are stopped, their whole process groups killed, and its results forgotten; the app's
 lifespan stops what runs when it shuts down. The proxy writes the turn's trajectory as it
 goes, readable live, as OTel GenAI spans in format `agentenv-proxy/v1`: `chat` for each
-recorded call, `execute_tool` for each action, and `chain` for the turn. Skills it is given
+recorded call, `execute_tool` for each action, and `chain` for the turn, each with an
+OTel status: `ERROR` for an action that failed, a command that exited nonzero or timed out,
+and a turn that ended in an error. Skills it is given
 are written to `~/skills/<name>/`, once each, and a turn names each one's folder.
 `ProxyAgent(shell=False)` is a proxy for an agent that works in no sandbox: it offers no
 `bash` and keeps no skills. It holds the env servers' headers as any agent does, so run it

packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/extensions.py

@@ -367,7 +367,7 @@ class ProxyResultRequest(ExtensionRequest):
 
 class ProxyBashResult(ExtensionResponse):
     kind: Literal["bash"] = "bash"
-    exit_code: int | None  # none when the command was stopped
+    exit_code: int | None = None  # none when the command was stopped
     stdout: str
     stderr: str
     timed_out: bool