[earakely-scale]

Summary

This adds urn:agentenv:proxy/v1 and ProxyAgent, an A2A agent with no model. Another program, the driver, plays it. The proxy is deployed where the played agent would run, and every action the driver's model takes runs in it: a call to an env's tools, or a bash command. The proxy records the turn as the agent's trajectory.

This PR ships the protocol half. #270 uses it: it adds the proxy to the agents bundle as an agent folder, like claude-code and pi, and plays it from the Episode API. A bundled agent installs the protocol from PyPI, so #270's proxy needs this release (0.1.367).

proxy/v1

Every operation is a POST under /ext/proxy/ whose body carries the token.

Operation	Request	What it does
claim	{token}	The first caller sets the token (22 characters or more). Another token gets 409; a wrong one on any later call gets 401.
next	{token, after}	Waits up to 25 s for the turns' version to pass after, then returns {version, turns}. Each turn has its task id, context id, parts (text only for now), its system_prompt and its skills.
tools	{token, task_id}	What the turn can call: bash when the proxy has a shell, then each registered env server's tools, with server. Two servers offering one name get 409.
act	{token, task_id, action_id, action}	Runs a tool or bash action in the turn. It answers {done, result} if the action finishes within the long-poll, else {done: false}. A retry with the same action_id returns the action already started.
result	{token, action_id}	Waits up to 25 s for an action's result.
record	{token, task_id, message, model?, usage?}	Records one model call: an OpenAI chat message, an Anthropic message or a string; any other shape gets 400. From then on, each action must be one that call made (name and arguments), else 409. Calls to tools the turn doesn't offer aren't checked.
reply	{token, task_id, parts or error}	Ends the turn. The parts are the task's result, and an error fails it with proxy.driver_error. While a recorded call hasn't run, a reply with parts gets 409.

A bash result is {exit_code, stdout, stderr, timed_out}; a tool result is {content, is_error}.

ProxyAgent

• Turns. Each A2A message is an open turn until the driver replies. A sender's tasks/cancel withdraws it. A message with a part that isn't text fails as proxy.unsupported_part before the driver sees it.
• Env tools. The env servers come through mcp-config, as for any agent. The proxy calls each one at the URL, and with the headers, it was registered with, so a role header reaches the env and never the driver. A turn holds one connection per server, shared by its actions and closed with the turn.
• bash. It runs bash -c in the proxy's folder, as its user, in a process group of its own. On a timeout (3600 s by default), or when its turn closes, the whole group is killed. shell=False is a proxy for an agent that works in no sandbox: it offers no bash and keeps no skills.
• Deadlines. A tool action's timeout_seconds (600 s by default) covers connecting to the server and the call together. Listing a turn's tools is bounded the same way.
• Actions belong to their turn. When it closes, its running actions are cancelled and their results forgotten. The app's lifespan (stopping_actions) stops every turn's actions when the app stops; a subclass declaring its own definition passes it on.
• The record. The trajectory is format agentenv-proxy/v1, as OTel GenAI spans:
  • a chat span per recorded call, with its model and token usage when given;
  • an execute_tool span per action;
  • a chain span per turn, with the prompt, the system prompt and the model.
    It is served live through trajectory/v1.
• Skills from skill-config are written to ~/skills/<name>/, and a turn names each skill's folder. A write that fails leaves no folder, and a name already added gets 409.
• agent-config takes system_prompt.
• The token is claimed on first use, compared as bytes, and held in memory only, so a command can't read it.
• The README documents the extension and the agent.

Verification

• test_a2a_proxy.py, 31 tests, cover the proxy app in process. Each passed 3 times in a row:
  • the claim and the token, a non-ASCII one included;
  • the turn round trip, withdrawal, a non-text part, an error reply, and reply validation;
  • tool listing, a name clash, a tool call carrying the registered role, and a tool error;
  • bash's structured result, the fast path, an idempotent retry, a timeout with a background child, and a turn closing mid-action;
  • a tool's deadline covering a connect that never answers;
  • one connection per server under concurrent first actions, closed with the turn;
  • record: the call check, two calls recorded at once, the message shapes and refused ones, span order and usage;
  • skills, a failed bundle, shell=False, and the app stopping.
• Protocol suite: 526 passed. Ruff clean.
• End to end on feat(task): play an outside agent through a ProxyAgent in its place #270's branch: see feat(task): play an outside agent through a ProxyAgent in its place #270.

🤖 Generated with Claude Code

[greptile-apps]

Python 3.10 timeouts escape

On supported Python 3.10 installations, asyncio.wait_for raises asyncio.TimeoutError, which is distinct from built-in TimeoutError. The new catches in _perform and _tools miss it. A timed-out action then fails the act or result request instead of returning a tool-error result, and a timed-out listing skips its intended 502 response.

Catch asyncio.TimeoutError at both boundaries.

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/proxy.py
Line: 342

Comment:
**Python 3.10 timeouts escape**

On supported Python 3.10 installations, `asyncio.wait_for` raises `asyncio.TimeoutError`, which is distinct from built-in `TimeoutError`. The new catches in `_perform` and `_tools` miss it. A timed-out action then fails the `act` or `result` request instead of returning a tool-error result, and a timed-out listing skips its intended 502 response.

Catch `asyncio.TimeoutError` at both boundaries.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.