agentenv-framework-protocol 0.1.372__tar.gz → 0.1.373__tar.gz

{agentenv_framework_protocol-0.1.372 → agentenv_framework_protocol-0.1.373}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.372
+Version: 0.1.373
 Summary: Open data-plane protocol and server SDK for agent environments.
 Project-URL: Homepage, https://www.agentenvframework.com
 Project-URL: Documentation, https://www.agentenvframework.com/docs
@@ -759,20 +759,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`.
@@ -781,7 +788,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

{agentenv_framework_protocol-0.1.372 → agentenv_framework_protocol-0.1.373}/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

{agentenv_framework_protocol-0.1.372 → agentenv_framework_protocol-0.1.373}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentenv-framework-protocol"
-version = "0.1.372"
+version = "0.1.373"
 description = "Open data-plane protocol and server SDK for agent environments."
 readme = "README.md"
 license = "Apache-2.0"

{agentenv_framework_protocol-0.1.372 → agentenv_framework_protocol-0.1.373}/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

{agentenv_framework_protocol-0.1.372 → agentenv_framework_protocol-0.1.373}/src/agentenv_protocol/a2a_agent/proxy.py

@@ -64,6 +64,8 @@ from ..types import EnvironmentTool
 
 LONG_POLL_SECONDS = 25.0
 BASH_TIMEOUT_SECONDS = 3600
+OUTPUT_GRACE_SECONDS = 1.0  # how long a done command's output may still arrive, from what it left running
+EXIT_POLL_SECONDS = 0.05
 TOOL_TIMEOUT_SECONDS = 600
 SKILLS_DIR = Path.home() / "skills"
 TRAJECTORY_FORMAT = "agentenv-proxy/v1"
@@ -75,6 +77,11 @@ BASH_TOOL = ProxyTool(
     input_schema={"type": "object", "properties": {"command": {"type": "string", "description": "The command."}},
                   "required": ["command"]},
 )
+BASH_TOOL_ON_SH = BASH_TOOL.model_copy(update={
+    "description": "Run a command where the agent works, as its user, in its folder, with POSIX sh: this place has "
+                   "no bash, so bash-only syntax such as [[ ]], arrays or <(...) fails. Returns its stdout, then its "
+                   "stderr.",
+})
 
 
 class ProxyConfig(AgentConfig):
@@ -127,16 +134,19 @@ EXTENSIONS = (MCP_CONFIG_V1, enable(TRAJECTORY_V1, live=True), PROXY_V1)
 @a2a_agent(identity=IDENTITY, config=ProxyConfig, extensions=EXTENSIONS, lifespan=stopping_actions)
 class ProxyAgent(AgentEnvAgent):
     """``shell=False`` is a proxy for an agent that works in no sandbox: it offers no ``bash`` and keeps no skills.
+    Where there is no ``bash``, its ``bash`` runs commands with ``sh``, as the tool's description says.
     ``long_poll_seconds`` bounds how long ``next``, ``act`` and ``result`` wait for something to report."""
 
     def __init__(self, *, shell: bool = True, long_poll_seconds: float = LONG_POLL_SECONDS):
         self._shell = shell
+        self._program, self._bash_tool = ("bash", BASH_TOOL) if shutil.which("bash") else ("sh", BASH_TOOL_ON_SH)
         self._long_poll_seconds = long_poll_seconds
         self._token: bytes | None = None
         self._turns: dict[str, _Turn] = {}
         self._version = 0
         self._changed: asyncio.Future[None] | None = None
         self._actions: dict[str, tuple[_Turn, asyncio.Task[ProxyBashResult | ProxyToolResult]]] = {}
+        self._draining: set[asyncio.Task[None]] = set()
 
     async def run(self, request: TaskRequest[ProxyConfig]) -> TaskResult:
         if any(not isinstance(part, TextPart) for part in request.parts):
@@ -164,7 +174,7 @@ class ProxyAgent(AgentEnvAgent):
         prompt = {"prompt": "\n".join(part.text for part in turn.parts), "system_prompt": turn.system_prompt}
         if reply.error is not None:
             turn.trajectory.append(_span("turn", "chain", turn.started, turn.model, prompt=prompt,
-                                         completion={"error": reply.error}))
+                                         completion={"error": reply.error}, failed=True))
             return TaskResult.failure("proxy.driver_error", reply.error)
         turn.trajectory.append(_span("turn", "chain", turn.started, turn.model, prompt=prompt, completion={
             "content": [{"type": "text", "text": part.text} for part in reply.parts]}))
@@ -202,14 +212,14 @@ class ProxyAgent(AgentEnvAgent):
         if (known := self._actions.get(request.action_id)) is not None:
             if known[0].task_id != request.task_id:
                 raise HTTPException(status_code=409, detail=f"action {request.action_id!r} is another turn's")
-            return await self._state(known[1])
+            return await self._state(request.action_id, known[1])
         turn = self._open_turn(request.token, request.task_id)
         action = request.action
         if isinstance(action, ProxyBashAction) and not self._shell:
             raise HTTPException(status_code=409, detail="this proxy works in no sandbox, so it runs no commands")
         if turn.recorded:
-            call = (action.name, _canonical(action.arguments)) if isinstance(action, ProxyToolAction) else (
-                BASH, _canonical({"command": action.command}))
+            call = (_call(action.name, action.arguments) if isinstance(action, ProxyToolAction)
+                    else _call(BASH, {"command": action.command}, own_shell=True))
             if call not in turn.pending:
                 raise HTTPException(status_code=409, detail=f"the last recorded model call didn't make this call to "
                                                             f"{call[0]!r}")
@@ -217,14 +227,14 @@ class ProxyAgent(AgentEnvAgent):
         task = asyncio.create_task(self._perform(turn, action))
         turn.actions[request.action_id] = task
         self._actions[request.action_id] = (turn, task)
-        return await self._state(task)
+        return await self._state(request.action_id, task)
 
     @extension(PROXY_V1.result)
     async def result(self, request: ProxyResultRequest) -> ProxyActionState:
         self._check(request.token)
         if (known := self._actions.get(request.action_id)) is None:
             raise HTTPException(status_code=404, detail=f"no action {request.action_id!r}")
-        return await self._state(known[1])
+        return await self._state(request.action_id, known[1])
 
     @extension(PROXY_V1.record)
     async def record(self, request: ProxyRecordRequest) -> None:
@@ -233,7 +243,8 @@ class ProxyAgent(AgentEnvAgent):
         turn = self._open_turn(request.token, request.task_id)
         if turn.pending:
             raise HTTPException(status_code=409, detail=_unrun(turn))
-        turn.pending = [(name, _canonical(arguments)) for name, arguments in calls if name in offered]
+        turn.pending = [_call(name, arguments, own_shell=offered[name].server is None)
+                        for name, arguments in calls if name in offered]
         turn.recorded = True
         turn.model = request.model or turn.model
         span = _span("chat", "chat", turn.last_event, turn.model, completion={"content": content})
@@ -277,15 +288,17 @@ class ProxyAgent(AgentEnvAgent):
         return turn
 
     async def _tools(self, turn: _Turn) -> dict[str, ProxyTool]:
-        """What the turn can call, listed once: each registered env server's tools, and ``bash``. Two offering one
-        name are refused."""
+        """What the turn can call, listed once and all within ``TOOL_TIMEOUT_SECONDS``: each registered env server's
+        tools, and ``bash``. Two offering one name are refused."""
         async with turn.listing:
             if turn.tools is None:
-                offered = {BASH: BASH_TOOL} if self._shell else {}
+                offered = {BASH: self._bash_tool} if self._shell else {}
+                loop = asyncio.get_running_loop()
+                deadline = loop.time() + TOOL_TIMEOUT_SECONDS
                 for server in turn.servers:
                     try:
-                        listed = await asyncio.wait_for(self._listed(turn, server), TOOL_TIMEOUT_SECONDS)
-                    except TimeoutError:
+                        listed = await asyncio.wait_for(self._listed(turn, server), deadline - loop.time())
+                    except asyncio.TimeoutError:
                         raise HTTPException(status_code=502, detail=(
                             f"env server {server!r} didn't list its tools within {TOOL_TIMEOUT_SECONDS}s")) from None
                     except (ToolSessionError, httpx.HTTPError) as e:
@@ -327,33 +340,45 @@ class ProxyAgent(AgentEnvAgent):
     async def _perform(self, turn: _Turn, action: ProxyToolAction | ProxyBashAction) -> ProxyBashResult | ProxyToolResult:
         started = _now()
         if isinstance(action, ProxyBashAction):
-            timeout = action.timeout_seconds or BASH_TIMEOUT_SECONDS
-            result = await _run(action.command, timeout)
             name, arguments = BASH, {"command": action.command}
-            output = (f"error: the command timed out after {timeout:g}s" if result.timed_out
-                      else result.stdout + result.stderr)
-            completion = {"output": output, "exit_code": result.exit_code}
+            result, completion, failed = await self._bash(action)
         else:
-            timeout = action.timeout_seconds or TOOL_TIMEOUT_SECONDS
             name, arguments = action.name, action.arguments
-            try:
-                called = await asyncio.wait_for(self._called(turn, action), timeout)
-                result = ProxyToolResult(content=called.content, is_error=called.isError)
-            except TimeoutError:
-                result = _tool_error(f"the tool call timed out after {timeout:g}s")
-            except (ToolSessionError, httpx.HTTPError) as e:
-                result = _tool_error(f"{type(e).__name__}: {e}")
-            text = "\n".join(block["text"] for block in result.content if block.get("type") == "text")
-            completion = {"error": text} if result.is_error else {"output": text}
-        span = _span(name, "execute_tool", started, None, prompt={"input": arguments}, completion=completion)
+            result, completion, failed = await self._tool(turn, action)
+        span = _span(name, "execute_tool", started, None, prompt={"input": arguments}, completion=completion,
+                     failed=failed)
         turn.trajectory.append(span)
         turn.last_event = span["end_time"]
         return result
 
-    async def _state(self, task: asyncio.Task[ProxyBashResult | ProxyToolResult]) -> ProxyActionState:
+    async def _bash(self, action: ProxyBashAction) -> tuple[ProxyBashResult, dict[str, Any], bool]:
+        """Run a command; what it left reading output is drained until the proxy stops."""
+        timeout = action.timeout_seconds or BASH_TIMEOUT_SECONDS
+        result, draining = await _run(self._program, action.command, timeout)
+        for drain in draining:
+            self._draining.add(drain)
+            drain.add_done_callback(self._draining.discard)
+        output = f"error: the command timed out after {timeout:g}s" if result.timed_out else result.stdout + result.stderr
+        return result, {"output": output, "exit_code": result.exit_code}, result.timed_out or result.exit_code != 0
+
+    async def _tool(self, turn: _Turn, action: ProxyToolAction) -> tuple[ProxyToolResult, dict[str, Any], bool]:
+        timeout = action.timeout_seconds or TOOL_TIMEOUT_SECONDS
+        try:
+            called = await asyncio.wait_for(self._called(turn, action), timeout)
+            result = ProxyToolResult(content=called.content, is_error=called.isError)
+        except asyncio.TimeoutError:
+            result = _tool_error(f"the tool call timed out after {timeout:g}s")
+        except (ToolSessionError, httpx.HTTPError) as e:
+            result = _tool_error(f"{type(e).__name__}: {e}")
+        text = "\n".join(block["text"] for block in result.content if block.get("type") == "text")
+        return result, ({"error": text} if result.is_error else {"output": text}), result.is_error
+
+    async def _state(self, action_id: str, task: asyncio.Task[ProxyBashResult | ProxyToolResult]) -> ProxyActionState:
         await asyncio.wait((task,), timeout=self._long_poll_seconds)
         if not task.done():
             return ProxyActionState(done=False)
+        if task.cancelled():
+            raise HTTPException(status_code=404, detail=f"action {action_id!r} was stopped: its turn is over")
         return ProxyActionState(done=True, result=task.result())
 
     async def _close(self, turn: _Turn) -> None:
@@ -367,6 +392,8 @@ class ProxyAgent(AgentEnvAgent):
 
     async def _stop(self) -> None:
         await asyncio.gather(*(self._close(turn) for turn in list(self._turns.values())), return_exceptions=True)
+        for drain in list(self._draining):
+            drain.cancel()
 
     @contextlib.asynccontextmanager
     async def _skill_folder(self, name: str) -> AsyncIterator[Path]:
@@ -471,8 +498,22 @@ def _unrun(turn: _Turn) -> str:
     return f"the last recorded model call's calls to {sorted({name for name, _ in turn.pending})} haven't run"
 
 
-def _canonical(arguments: dict[str, Any]) -> str:
-    return json.dumps(arguments, sort_keys=True, separators=(",", ":"), default=str)
+def _call(name: str, arguments: dict[str, Any], *, own_shell: bool = False) -> tuple[str, str]:
+    """A call as recorded calls and actions are compared: the proxy's own ``bash`` by its command alone, since its
+    action carries nothing else, and a whole float equal to the int a driver may have written for it."""
+    if own_shell:
+        arguments = {"command": arguments.get("command")}
+    return name, json.dumps(_whole(arguments), sort_keys=True, separators=(",", ":"), default=str)
+
+
+def _whole(value: Any) -> Any:
+    if isinstance(value, float) and value.is_integer():
+        return int(value)
+    if isinstance(value, dict):
+        return {key: _whole(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_whole(item) for item in value]
+    return value
 
 
 def _tool_error(message: str) -> ProxyToolResult:
@@ -480,7 +521,7 @@ def _tool_error(message: str) -> ProxyToolResult:
 
 
 def _span(name: str, operation: str, started: str, model: str | None, *, prompt: Any = None,
-          completion: Any = None) -> dict[str, Any]:
+          completion: Any = None, failed: bool = False) -> dict[str, Any]:
     """An OTel GenAI span, the trajectory format rubrics and the explorer read."""
     attributes: dict[str, Any] = {"gen_ai.operation.name": operation}
     if model:
@@ -489,28 +530,67 @@ def _span(name: str, operation: str, started: str, model: str | None, *, prompt:
         attributes["gen_ai.prompt"] = json.dumps(prompt, default=str)
     if completion is not None:
         attributes["gen_ai.completion"] = json.dumps(completion, default=str)
-    return {"name": name, "start_time": started, "end_time": _now(), "attributes": attributes}
+    return {"name": name, "start_time": started, "end_time": _now(),
+            "status": {"status_code": "ERROR" if failed else "OK"}, "attributes": attributes}
 
 
 def _now() -> str:
     return datetime.now(timezone.utc).isoformat()
 
 
-async def _run(command: str, timeout: float) -> ProxyBashResult:
-    """Run ``command`` in a process group of its own, stopped with whatever it started if it isn't done within
-    ``timeout``, or if the call is cancelled, even when ``bash`` has exited and a child it left holds the output open."""
-    process = await asyncio.create_subprocess_exec(
-        "bash", "-c", command, stdin=asyncio.subprocess.DEVNULL, stdout=asyncio.subprocess.PIPE,
-        stderr=asyncio.subprocess.PIPE, start_new_session=True,
-    )
+async def _run(program: str, command: str, timeout: float) -> tuple[ProxyBashResult, list[asyncio.Task[None]]]:
+    """Run ``command`` in a process group of its own. It's done when its shell exits: what it started in the background
+    keeps running, and output that arrives after ``OUTPUT_GRACE_SECONDS`` is read and dropped by the readers returned
+    with the result, so a server it started never blocks on a full pipe. A command not done within ``timeout``, or
+    whose call is cancelled, is stopped with whatever it started."""
+    try:
+        process = await asyncio.create_subprocess_exec(
+            program, "-c", command, stdin=asyncio.subprocess.DEVNULL, stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE, start_new_session=True,
+        )
+    except OSError as e:
+        # As a shell reports a command it can't execute: an argument list too long, say.
+        return ProxyBashResult(exit_code=126, stdout="", stderr=f"error: the command couldn't start: {e}\n",
+                               timed_out=False), []
+    stdout, stderr = _Output(), _Output()
+    readers = [asyncio.create_task(_read(process.stdout, stdout)), asyncio.create_task(_read(process.stderr, stderr))]
     try:
-        stdout, stderr = await asyncio.wait_for(process.communicate(), timeout)
+        await asyncio.wait_for(_exited(process), timeout)
+        await asyncio.wait(readers, timeout=OUTPUT_GRACE_SECONDS)
     except BaseException as e:
         with contextlib.suppress(ProcessLookupError):
             os.killpg(process.pid, signal.SIGKILL)
-        await process.wait()
+        await _exited(process)
+        for reader in readers:
+            reader.cancel()
         if isinstance(e, asyncio.TimeoutError):
-            return ProxyBashResult(exit_code=None, stdout="", stderr="", timed_out=True)
+            return ProxyBashResult(exit_code=None, stdout="", stderr="", timed_out=True), []
         raise
-    return ProxyBashResult(exit_code=process.returncode, stdout=stdout.decode(errors="replace"),
-                           stderr=stderr.decode(errors="replace"), timed_out=False)
+    result = ProxyBashResult(exit_code=process.returncode, stdout=stdout.take(), stderr=stderr.take(), timed_out=False)
+    return result, [reader for reader in readers if not reader.done()]
+
+
+async def _exited(process: asyncio.subprocess.Process) -> None:
+    """Until the shell exits: ``Process.wait()`` also waits for everything still holding its output."""
+    while process.returncode is None:
+        await asyncio.sleep(EXIT_POLL_SECONDS)
+
+
+class _Output:
+    """What a command writes to one stream, kept until it's taken and dropped after."""
+
+    def __init__(self) -> None:
+        self._data: bytearray | None = bytearray()
+
+    def add(self, chunk: bytes) -> None:
+        if self._data is not None:
+            self._data.extend(chunk)
+
+    def take(self) -> str:
+        data, self._data = self._data or bytearray(), None
+        return data.decode(errors="replace")
+
+
+async def _read(stream: asyncio.StreamReader, output: _Output) -> None:
+    while chunk := await stream.read(65536):
+        output.add(chunk)

{agentenv_framework_protocol-0.1.372 → agentenv_framework_protocol-0.1.373}/tests/test_a2a_proxy.py

@@ -2,6 +2,9 @@ from __future__ import annotations
 
 import asyncio
 import json
+import os
+import shutil
+import signal
 import socket
 import subprocess
 import threading
@@ -13,7 +16,7 @@ import uvicorn
 from starlette.testclient import TestClient
 
 from agentenv_protocol import EnvironmentCard, ToolContext, ToolSession, create_fastmcp_app, tool
-from agentenv_protocol.a2a_agent import proxy
+from agentenv_protocol.a2a_agent import ProxyActionState, proxy
 from agentenv_protocol.a2a_agent.proxy import ProxyAgent
 
 TOKEN = "t" * 32
@@ -34,17 +37,38 @@ class _Items:
         """Always fails."""
         raise RuntimeError("the tool blew up")
 
+    @tool()
+    def count(self, n: int) -> str:
+        """Echo a number."""
+        return str(n)
+
     @tool()
     def whoami(self, ctx: ToolContext) -> str:
         """Who is calling."""
         return json.dumps({"role": ctx.caller.role})
 
 
+class _Terminal:
+    @tool()
+    def bash(self, command: str, cwd: str = "/") -> str:
+        """Run a command in the env's own terminal."""
+        return f"{cwd}$ {command}"
+
+
 @pytest.fixture(scope="module")
 def env():
     """An items env's MCP server on loopback, as a task's env serves one."""
-    handler = _Items()
-    app = create_fastmcp_app(handler, card=EnvironmentCard(name="items")).streamable_http_app()
+    yield from _served(_Items(), "items")
+
+
+@pytest.fixture(scope="module")
+def terminal():
+    """An env whose own tool is named ``bash``."""
+    yield from _served(_Terminal(), "terminal")
+
+
+def _served(handler: Any, name: str):
+    app = create_fastmcp_app(handler, card=EnvironmentCard(name=name)).streamable_http_app()
     sock = socket.socket()
     sock.bind(("127.0.0.1", 0))
     server = uvicorn.Server(uvicorn.Config(app, log_level="warning"))
@@ -198,6 +222,7 @@ def test_an_error_reply_fails_the_turn(client):
     task = _settled(client, task_id)
     assert task["status"]["state"] == "failed"
     assert "the driver gave up" in task["status"]["message"]["parts"][0]["text"]
+    assert _trajectory(client, task_id)[-1]["status"] == {"status_code": "ERROR"}
 
 
 def test_a_reply_names_exactly_one_open_turn_and_carries_parts_or_an_error(client):
@@ -237,8 +262,15 @@ def test_a_turn_offers_its_env_servers_tools_and_bash(client, env):
 
     tools = {item["name"]: item for item in _proxy(client, "tools", task_id=task_id).json()["tools"]}
 
-    assert set(tools) == {"add_item", "explode", "whoami", "bash"}
+    assert set(tools) == {"add_item", "count", "explode", "whoami", "bash"}
     assert (tools["add_item"]["server"], "server" in tools["bash"]) == ("items", False)
+    assert tools["bash"] == {
+        "name": "bash",
+        "description": "Run a bash command where the agent works, as its user, in its folder; returns its stdout, "
+                       "then its stderr.",
+        "input_schema": {"type": "object", "properties": {"command": {"type": "string", "description": "The command."}},
+                         "required": ["command"]},
+    }
     assert tools["add_item"]["input_schema"]["properties"]["item"]["type"] == "string"
 
 
@@ -283,6 +315,38 @@ def test_a_tool_actions_deadline_covers_connecting_to_its_server(client):
     assert time.monotonic() - started < 5
 
 
+def test_a_server_that_never_lists_its_tools_is_a_bad_gateway(client, monkeypatch):
+    monkeypatch.setattr(proxy, "TOOL_TIMEOUT_SECONDS", 0.5)
+    with socket.socket() as silent:
+        silent.bind(("127.0.0.1", 0))
+        silent.listen()
+        _register(client, f"http://127.0.0.1:{silent.getsockname()[1]}/mcp")
+        task_id = _send(client, "go")
+
+        response = _proxy(client, "tools", task_id=task_id)
+
+    assert response.status_code == 502
+    assert "didn't list its tools within 0.5s" in response.text
+
+
+def test_a_turns_servers_list_their_tools_within_one_deadline_for_them_all(client, monkeypatch):
+    monkeypatch.setattr(proxy, "TOOL_TIMEOUT_SECONDS", 1.0)
+
+    async def slowly(self, turn, server):
+        await asyncio.sleep(0.6)
+        return []
+
+    monkeypatch.setattr(proxy.ProxyAgent, "_listed", slowly)
+    _register(client, "http://127.0.0.1:9/mcp", name="items")
+    _register(client, "http://localhost:9/mcp", name="pantry")
+    task_id = _send(client, "go")
+
+    response = _proxy(client, "tools", task_id=task_id)
+
+    assert response.status_code == 502
+    assert "'pantry' didn't list its tools within 1.0s" in response.text
+
+
 def test_a_turns_actions_share_one_connection_to_each_env_server_which_closes_with_the_turn(client, env, monkeypatch):
     opened, closed, results = [], [], []
     open_session, close_session = ToolSession.open, ToolSession.close
@@ -319,9 +383,25 @@ def test_a_bash_action_runs_in_the_proxys_folder_and_returns_a_structured_result
     (tmp_path / "inputs").mkdir()
     task_id = _send(client, "go")
 
-    result = _done(client, task_id, "b1", _bash("ls; echo out; echo err >&2; exit 3"))
+    result = _done(client, task_id, "b1", _bash("ls; echo $0; echo out; echo err >&2; exit 3"))
 
-    assert result == {"kind": "bash", "exit_code": 3, "stdout": "inputs\nout\n", "stderr": "err\n", "timed_out": False}
+    assert result == {
+        "kind": "bash", "exit_code": 3, "stdout": "inputs\nbash\nout\n", "stderr": "err\n", "timed_out": False}
+
+
+def test_where_there_is_no_bash_the_bash_tool_runs_sh_and_says_so(monkeypatch, tmp_path):
+    which = shutil.which
+    monkeypatch.setattr(proxy.shutil, "which", lambda name, *args, **kwargs: None if name == "bash" else which(name, *args, **kwargs))
+    monkeypatch.chdir(tmp_path)
+    with TestClient(ProxyAgent(long_poll_seconds=0.2).create_app()) as client:
+        assert client.post("/ext/proxy/claim", json={"token": TOKEN}).status_code == 200
+        task_id = _send(client, "go")
+
+        tools = {item["name"]: item for item in _proxy(client, "tools", task_id=task_id).json()["tools"]}
+        result = _done(client, task_id, "s1", _bash("echo $0"))
+
+    assert "with POSIX sh: this place has no bash" in tools["bash"]["description"]
+    assert (result["exit_code"], result["stdout"]) == (0, "sh\n")
 
 
 def test_an_action_done_within_the_long_poll_answers_at_once_and_a_slow_one_is_polled(client):
@@ -349,11 +429,70 @@ def test_a_command_that_outlives_its_timeout_is_stopped_with_what_it_started(cli
     task_id = _send(client, "go")
 
     waited = _done(client, task_id, "w", _bash("sleep 60 & echo $! > waited; wait", timeout_seconds=0.5))
-    left = _done(client, task_id, "l", _bash("sleep 60 & echo $! > left", timeout_seconds=0.5))
 
-    assert waited == left == {"kind": "bash", "stdout": "", "stderr": "", "timed_out": True}
+    assert waited == {"kind": "bash", "stdout": "", "stderr": "", "timed_out": True}
+    assert ProxyActionState.model_validate({"done": True, "result": waited}).result.exit_code is None
     _stopped(int((tmp_path / "waited").read_text()))
-    _stopped(int((tmp_path / "left").read_text()))
+
+
+def test_a_command_is_done_when_its_shell_exits_and_what_it_left_in_the_background_runs_on(client, tmp_path):
+    task_id = _send(client, "go")
+
+    started = time.monotonic()
+    left = _done(client, task_id, "l", _bash("sleep 60 & echo $! > left; echo started"))
+
+    assert left == {"kind": "bash", "exit_code": 0, "stdout": "started\n", "stderr": "", "timed_out": False}
+    assert time.monotonic() - started < proxy.OUTPUT_GRACE_SECONDS + 2
+    pid = int((tmp_path / "left").read_text())
+    assert _state(pid) and not _state(pid).startswith("Z")
+    os.kill(pid, signal.SIGKILL)
+
+
+def test_what_a_background_process_writes_after_its_command_is_done_never_blocks_it(client, monkeypatch, tmp_path):
+    monkeypatch.setattr(proxy, "OUTPUT_GRACE_SECONDS", 0.1)
+    task_id = _send(client, "go")
+    writes = "import sys, time; time.sleep(0.5); sys.stdout.write('x' * 200_000); sys.stdout.flush(); open('done', 'w')"
+
+    result = _done(client, task_id, "b", _bash(f"python3 -c \"{writes}\" & echo started"))
+
+    assert (result["exit_code"], result["stdout"]) == (0, "started\n")
+    deadline = time.monotonic() + 10
+    while not (tmp_path / "done").exists():
+        assert time.monotonic() < deadline, "the background process blocked on its output"
+        time.sleep(0.05)
+
+
+def test_a_command_too_long_to_start_fails_as_a_shell_reports_it(client):
+    task_id = _send(client, "go")
+
+    result = _done(client, task_id, "huge", _bash("true " + "x" * 3_000_000))
+
+    assert (result["exit_code"], result["timed_out"], result["stdout"]) == (126, False, "")
+    assert "couldn't start" in result["stderr"]
+    _proxy(client, "reply", task_id=task_id, parts=[{"kind": "text", "text": "done"}])
+    _settled(client, task_id)
+    [action, _] = _trajectory(client, task_id)
+    assert (action["name"], action["status"]) == ("bash", {"status_code": "ERROR"})
+
+
+def test_an_action_polled_while_its_turn_closes_is_answered_404(monkeypatch, tmp_path):
+    monkeypatch.chdir(tmp_path)
+    agent = ProxyAgent(long_poll_seconds=10)
+    with TestClient(agent.create_app()) as client:
+        client.post("/ext/proxy/claim", json={"token": TOKEN})
+        task_id = _send(client, "go")
+        polled = {}
+        poll = threading.Thread(target=lambda: polled.update(response=_proxy(
+            client, "act", task_id=task_id, action_id="long", action=_bash("sleep 30"))))
+        poll.start()
+        while "long" not in agent._actions:
+            time.sleep(0.01)
+
+        _proxy(client, "reply", task_id=task_id, parts=[{"kind": "text", "text": "done"}])
+        poll.join(10)
+
+    assert polled["response"].status_code == 404
+    assert "'long' was stopped: its turn is over" in polled["response"].text
 
 
 def test_a_turn_that_closes_stops_its_running_actions_and_forgets_them(client, tmp_path):
@@ -369,6 +508,19 @@ def test_a_turn_that_closes_stops_its_running_actions_and_forgets_them(client, t
     assert _proxy(client, "act", task_id=task_id, action_id="new", action=_bash("true")).status_code == 404
 
 
+def test_a_turn_that_closes_while_a_done_commands_output_is_awaited_stops_what_it_left(client, monkeypatch, tmp_path):
+    monkeypatch.setattr(proxy, "OUTPUT_GRACE_SECONDS", 30)
+    task_id = _send(client, "go")
+    assert _proxy(client, "act", task_id=task_id, action_id="left",
+                  action=_bash("sleep 60 & echo $! > child")).json()["done"] is False
+
+    _proxy(client, "reply", task_id=task_id, parts=[{"kind": "text", "text": "done"}])
+    _settled(client, task_id)
+
+    _stopped(int((tmp_path / "child").read_text()))
+    assert _proxy(client, "result", action_id="left").status_code == 404
+
+
 def test_a_proxy_without_a_shell_offers_no_bash_and_keeps_no_skills():
     with TestClient(ProxyAgent(shell=False, long_poll_seconds=0.2).create_app()) as client:
         client.post("/ext/proxy/claim", json={"token": TOKEN})
@@ -386,8 +538,10 @@ def test_recorded_model_calls_are_checked_against_the_actions_that_run(client, e
     message = {"role": "assistant", "content": "Adding it.", "reasoning_content": "The user wants a crate.",
                "tool_calls": [
                    {"id": "c1", "type": "function", "function": {"name": "add_item", "arguments": '{"item": "crate"}'}},
-                   {"id": "c2", "type": "function", "function": {"name": "bash", "arguments": '{"command": "true"}'}},
-                   {"id": "c3", "type": "function", "function": {"name": "my_own_tool", "arguments": "{}"}}]}
+                   {"id": "c2", "type": "function", "function": {"name": "bash",
+                                                                 "arguments": '{"command": "true", "timeout": 30}'}},
+                   {"id": "c3", "type": "function", "function": {"name": "my_own_tool", "arguments": "{}"}},
+                   {"id": "c4", "type": "function", "function": {"name": "count", "arguments": '{"n": 2.0}'}}]}
 
     assert _proxy(client, "record", task_id=task_id, message=message, model="qwen",
                   usage={"prompt_tokens": 12, "completion_tokens": 7}).status_code == 200
@@ -398,22 +552,45 @@ def test_recorded_model_calls_are_checked_against_the_actions_that_run(client, e
     assert _proxy(client, "reply", task_id=task_id, parts=[{"kind": "text", "text": "x"}]).status_code == 409
     _done(client, task_id, "b", _bash("true"))
     _done(client, task_id, "a", {"kind": "tool", "server": "items", "name": "add_item", "arguments": {"item": "crate"}})
+    _done(client, task_id, "n", {"kind": "tool", "server": "items", "name": "count", "arguments": {"n": 2}})
     assert _proxy(client, "record", task_id=task_id, message="Done.").status_code == 200
     _proxy(client, "reply", task_id=task_id, parts=[{"kind": "text", "text": "Done."}])
 
     task = _settled(client, task_id)
     spans = _trajectory(client, task_id)
     assert [(span["name"], span["attributes"]["gen_ai.operation.name"]) for span in spans] == [
-        ("chat", "chat"), ("bash", "execute_tool"), ("add_item", "execute_tool"), ("chat", "chat"), ("turn", "chain")]
+        ("chat", "chat"), ("bash", "execute_tool"), ("add_item", "execute_tool"), ("count", "execute_tool"),
+        ("chat", "chat"), ("turn", "chain")]
+    assert {span["status"]["status_code"] for span in spans} == {"OK"}
     assert _attrs(spans[0], "gen_ai.completion")["content"] == [
         {"type": "thinking", "thinking": "The user wants a crate."}, {"type": "text", "text": "Adding it."},
         {"type": "tool_use", "id": "c1", "name": "add_item", "input": {"item": "crate"}},
-        {"type": "tool_use", "id": "c2", "name": "bash", "input": {"command": "true"}},
-        {"type": "tool_use", "id": "c3", "name": "my_own_tool", "input": {}}]
+        {"type": "tool_use", "id": "c2", "name": "bash", "input": {"command": "true", "timeout": 30}},
+        {"type": "tool_use", "id": "c3", "name": "my_own_tool", "input": {}},
+        {"type": "tool_use", "id": "c4", "name": "count", "input": {"n": 2.0}}]
     assert (spans[0]["attributes"]["gen_ai.request.model"], spans[0]["attributes"]["gen_ai.usage.input_tokens"],
             spans[0]["attributes"]["gen_ai.usage.output_tokens"]) == ("qwen", 12, 7)
     assert _attrs(spans[2], "gen_ai.prompt") == {"input": {"item": "crate"}}
-    assert task["status"]["message"]["parts"][1]["data"]["usage"]["tool_call_count"] == 2
+    assert task["status"]["message"]["parts"][1]["data"]["usage"]["tool_call_count"] == 3
+
+
+def test_an_env_tool_named_bash_is_held_to_all_its_recorded_arguments(terminal, monkeypatch, tmp_path):
+    monkeypatch.chdir(tmp_path)
+    with TestClient(ProxyAgent(shell=False, long_poll_seconds=0.2).create_app()) as client:
+        client.post("/ext/proxy/claim", json={"token": TOKEN})
+        _register(client, terminal[1], name="terminal")
+        task_id = _send(client, "go")
+        message = {"role": "assistant", "content": None, "tool_calls": [{"id": "c1", "type": "function", "function": {
+            "name": "bash", "arguments": '{"command": "ls", "cwd": "/a"}'}}]}
+
+        assert _proxy(client, "record", task_id=task_id, message=message).status_code == 200
+        moved = _proxy(client, "act", task_id=task_id, action_id="b", action={
+            "kind": "tool", "server": "terminal", "name": "bash", "arguments": {"command": "ls", "cwd": "/b"}})
+        ran = _done(client, task_id, "a", {"kind": "tool", "server": "terminal", "name": "bash",
+                                          "arguments": {"command": "ls", "cwd": "/a"}})
+
+    assert moved.status_code == 409
+    assert ran["content"][0]["text"] == "/a$ ls"
 
 
 def test_two_model_calls_recorded_at_once_are_held_one_after_the_other(client, monkeypatch):