From 4a32efdf342713b8c474df304eba0b6c0640f153 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 18:10:26 -0800 Subject: [PATCH 1/4] feat(agents): every bundled agent declares its trajectory's native format Each bundled agent passes its existing format id to enable(TRAJECTORY_V1, native=...), so its card lists formats, native and default, the SDK holds its log and returned native trajectories to that format, and every read it serves names it; pi's final read now reports pi-json-events/v1. Each agent's protocol floor rises to 0.1.588, the first with native. Claude Code's own context reads, the records of the CLI's session file, name claude-code-session/1, never the native format; Codex's own context reads, its native events, name codex-exec-json/1. browser-use gets a TRAJECTORY_FORMAT constant. A test holds every bundled agent to its native format. Co-Authored-By: Claude Opus 5.5 --- .../agents/agents/browser-use/a2a_server.py | 7 ++- .../agents/browser-use/requirements.txt | 6 +- .../agents/agents/claude-code/a2a_server.py | 8 ++- .../agents/claude-code/requirements.txt | 6 +- .../agents/agents/codex/a2a_server.py | 5 +- .../agents/agents/codex/requirements.txt | 6 +- .../agents/agents/gemini/a2a_server.py | 1 + .../agents/agents/gemini/requirements.txt | 6 +- .../agents/agents/hermes/a2a_server.py | 2 +- .../agents/agents/hermes/requirements.txt | 6 +- .../agents/agents/letta-code/a2a_server.py | 2 +- .../agents/agents/letta-code/requirements.txt | 6 +- .../agents/agents/opencode/a2a_server.py | 2 +- .../agents/agents/opencode/requirements.txt | 6 +- .../agents/openhands/openhands_agent.py | 3 +- .../agents/agents/openhands/requirements.txt | 6 +- src/agent_env/agents/agents/pi/pi_agent.py | 3 +- .../agents/agents/pi/requirements.txt | 6 +- .../agents/agents/proxy/requirements.txt | 6 +- .../agents/pydantic-ai/pydantic_ai_agent.py | 3 +- .../agents/pydantic-ai/requirements.txt | 6 +- .../agents/claude_code/test_image_contract.py | 2 +- .../claude_code/test_object_transfer.py | 3 +- .../claude_code/test_partial_trajectory.py | 1 + .../codex/test_codex_snapshot_hardening.py | 1 + tst/unit/agents/codex/test_image_contract.py | 2 +- tst/unit/agents/codex/test_object_transfer.py | 2 +- tst/unit/agents/gemini/test_image_contract.py | 2 +- .../agents/opencode/test_image_contract.py | 2 +- tst/unit/agents/test_trajectory_formats.py | 60 +++++++++++++++++++ 30 files changed, 127 insertions(+), 50 deletions(-) create mode 100644 tst/unit/agents/test_trajectory_formats.py diff --git a/src/agent_env/agents/agents/browser-use/a2a_server.py b/src/agent_env/agents/agents/browser-use/a2a_server.py index 790a8bfdf..eaef8ea8f 100644 --- a/src/agent_env/agents/agents/browser-use/a2a_server.py +++ b/src/agent_env/agents/agents/browser-use/a2a_server.py @@ -33,6 +33,8 @@ #: How much of the turn's deadline browser-use's own run leaves: its forced delivery when it runs out, and its stop. DELIVERY_SECONDS = 100 STOP_SECONDS = 5 +#: The native trajectory: browser-use's messages, each turn's when it ends. +TRAJECTORY_FORMAT = "browser-use-messages/1" #: browser-use and its browser daemon report usage to their makers unless told not to. _PRIVATE_ENV = {"ANONYMIZED_TELEMETRY": "false", "BH_TELEMETRY": "0"} @@ -65,7 +67,8 @@ class BrowserUseConfig(AgentConfig): extensions=( MCP_CONFIG_V1, CDP_CONFIG_V1, - enable(TRAJECTORY_V1, live=False, description="browser-use's messages, each turn's when it ends."), + enable(TRAJECTORY_V1, live=False, native=TRAJECTORY_FORMAT, + description="browser-use's messages, each turn's when it ends."), ), ) class BrowserUseAgent(AgentEnvAgent): @@ -103,7 +106,7 @@ async def run(self, request: TaskRequest[BrowserUseConfig]) -> TaskResult: "historyFile": str(HOME / "sessions" / f"{session}-{hashlib.sha256(model.encode()).hexdigest()[:8]}.json"), } (HOME / "sessions").mkdir(parents=True, exist_ok=True) - request.trajectory.set_format("browser-use-messages/1") + request.trajectory.set_format(TRAJECTORY_FORMAT) process = await asyncio.create_subprocess_exec( *self.command, diff --git a/src/agent_env/agents/agents/browser-use/requirements.txt b/src/agent_env/agents/agents/browser-use/requirements.txt index 5d00eb18f..91e032ab6 100644 --- a/src/agent_env/agents/agents/browser-use/requirements.txt +++ b/src/agent_env/agents/agents/browser-use/requirements.txt @@ -1,4 +1,4 @@ # The image installs the newest agentenv-framework-protocol at or above this floor; a release doesn't pin it, so the -# image is built again only when this folder changes. The floor is the first whose extension routes take the agent's -# control token; raise it when the agent needs a newer protocol. -agentenv-framework-protocol[agent]>=0.1.582 +# image is built again only when this folder changes. The floor is the first that takes the native trajectory format +# the agent declares (enable(TRAJECTORY_V1, native=...)); raise it when the agent needs a newer protocol. +agentenv-framework-protocol[agent]>=0.1.588 diff --git a/src/agent_env/agents/agents/claude-code/a2a_server.py b/src/agent_env/agents/agents/claude-code/a2a_server.py index 77ab702f8..80db98f3b 100644 --- a/src/agent_env/agents/agents/claude-code/a2a_server.py +++ b/src/agent_env/agents/agents/claude-code/a2a_server.py @@ -98,6 +98,8 @@ HARNESS = "claude-code" # The versioned format of the stream-json events a turn's trajectory holds. TRAJECTORY_FORMAT = "claude-code-stream-json/1" +# A context read's format: the records of the CLI's session file, the conversation so far. Never the native format. +SESSION_TRAJECTORY_FORMAT = "claude-code-session/1" # The CLI loads skills from /skills//SKILL.md. SKILLS_DIR = CLAUDE_STATE_DIR / "skills" # FileParts are written here, one folder per task, and their paths appended to the prompt: the CLI reads a path in @@ -401,7 +403,7 @@ async def _turns_stop_with_the_server(app: Starlette) -> AsyncIterator[None]: config_description="Set or read agent configuration such as model, role, and allowed tools.", lifespan=_turns_stop_with_the_server, extensions=( - enable(TRAJECTORY_V1, live=True, description=( + enable(TRAJECTORY_V1, live=True, native=TRAJECTORY_FORMAT, description=( "Retrieve a task's Claude Code stream-json trajectory, also while it runs, " "or a context's cumulative trajectory including a live run.")), enable(MCP_CONFIG_V1, description="Register MCP servers the Claude Code CLI should connect to."), @@ -538,6 +540,7 @@ async def _context_trajectory(self, context_id: str) -> dict[str, Any]: raise HTTPException(status_code=404, detail=f"No transcript yet for context_id '{context_id}'") return { "trajectory": trajectory, + "format": SESSION_TRAJECTORY_FORMAT, "session_lines": session_lines, "is_live": context_id in self._active_contexts, "session_id": session_id, @@ -553,7 +556,8 @@ async def get_context_trajectory(self, request: ContextTrajectoryRequest) -> dic async def upload_context_trajectory(self, request: ContextObjectTrajectoryRequest) -> dict[str, Any]: trajectory = (await self._context_trajectory(request.context_id))["trajectory"] body = json.dumps(trajectory, separators=(",", ":"), default=str).encode() - return {"objects": {"trajectory": _answer(await upload(request.objects.trajectory, body))}} + return {"objects": {"trajectory": _answer(await upload(request.objects.trajectory, body))}, + "format": SESSION_TRAJECTORY_FORMAT} @extension(SKILL_CONFIG_V1.add.inline) async def add_inline_skill(self, request: InlineSkillRequest) -> SkillAddResponse: diff --git a/src/agent_env/agents/agents/claude-code/requirements.txt b/src/agent_env/agents/agents/claude-code/requirements.txt index 5d00eb18f..91e032ab6 100644 --- a/src/agent_env/agents/agents/claude-code/requirements.txt +++ b/src/agent_env/agents/agents/claude-code/requirements.txt @@ -1,4 +1,4 @@ # The image installs the newest agentenv-framework-protocol at or above this floor; a release doesn't pin it, so the -# image is built again only when this folder changes. The floor is the first whose extension routes take the agent's -# control token; raise it when the agent needs a newer protocol. -agentenv-framework-protocol[agent]>=0.1.582 +# image is built again only when this folder changes. The floor is the first that takes the native trajectory format +# the agent declares (enable(TRAJECTORY_V1, native=...)); raise it when the agent needs a newer protocol. +agentenv-framework-protocol[agent]>=0.1.588 diff --git a/src/agent_env/agents/agents/codex/a2a_server.py b/src/agent_env/agents/agents/codex/a2a_server.py index 44cf656d4..a29a7f9c4 100644 --- a/src/agent_env/agents/agents/codex/a2a_server.py +++ b/src/agent_env/agents/agents/codex/a2a_server.py @@ -592,6 +592,7 @@ async def _stage_granted_workspace(source: ReadObject | None) -> Path | None: enable( TRAJECTORY_V1, live=True, + native=TRAJECTORY_FORMAT, description="Retrieve a task's Codex --json trajectory, also while it runs.", ), enable( @@ -806,6 +807,7 @@ async def _context_trajectory(self, context_id: str) -> dict[str, Any]: ) return { "trajectory": trajectory, + "format": TRAJECTORY_FORMAT, "is_live": is_live, "session_id": self.session_ref_for_context(context_id), "harness": HARNESS, @@ -821,7 +823,8 @@ async def get_context_trajectory(self, request: ContextTrajectoryRequest) -> dic async def upload_context_trajectory(self, request: ContextObjectTrajectoryRequest) -> dict[str, Any]: trajectory = (await self._context_trajectory(request.context_id))["trajectory"] body = json.dumps(trajectory, separators=(",", ":"), default=str).encode() - return {"objects": {"trajectory": _answer(await upload(request.objects.trajectory, body))}} + return {"objects": {"trajectory": _answer(await upload(request.objects.trajectory, body))}, + "format": TRAJECTORY_FORMAT} @extension(SNAPSHOT_V1.save) async def save_snapshot(self, request: ObjectSnapshotSaveRequest) -> dict[str, Any]: diff --git a/src/agent_env/agents/agents/codex/requirements.txt b/src/agent_env/agents/agents/codex/requirements.txt index 1fbb1f06a..4bdf6c899 100644 --- a/src/agent_env/agents/agents/codex/requirements.txt +++ b/src/agent_env/agents/agents/codex/requirements.txt @@ -1,7 +1,7 @@ # The image installs the newest agentenv-framework-protocol at or above this floor; a release doesn't pin it, so the -# image is built again only when this folder changes. The floor is the first whose extension routes take the agent's -# control token; raise it when the agent needs a newer protocol. -agentenv-framework-protocol[agent]>=0.1.582 +# image is built again only when this folder changes. The floor is the first that takes the native trajectory format +# the agent declares (enable(TRAJECTORY_V1, native=...)); raise it when the agent needs a newer protocol. +agentenv-framework-protocol[agent]>=0.1.588 tomli-w==1.2.0 # The CA certificates an installed agent's CLI trusts on a target that has none of its own; unpinned, so each build # takes the newest. diff --git a/src/agent_env/agents/agents/gemini/a2a_server.py b/src/agent_env/agents/agents/gemini/a2a_server.py index a9a8fca05..fe4660edd 100644 --- a/src/agent_env/agents/agents/gemini/a2a_server.py +++ b/src/agent_env/agents/agents/gemini/a2a_server.py @@ -452,6 +452,7 @@ async def _vertex_openai_bridge( enable( TRAJECTORY_V1, live=True, + native=TRAJECTORY_FORMAT, description="Retrieve a task's Gemini stream-json trajectory, also while it runs.", ), enable(MCP_CONFIG_V1, description="Register MCP servers the Gemini CLI should connect to."), diff --git a/src/agent_env/agents/agents/gemini/requirements.txt b/src/agent_env/agents/agents/gemini/requirements.txt index 5d00eb18f..91e032ab6 100644 --- a/src/agent_env/agents/agents/gemini/requirements.txt +++ b/src/agent_env/agents/agents/gemini/requirements.txt @@ -1,4 +1,4 @@ # The image installs the newest agentenv-framework-protocol at or above this floor; a release doesn't pin it, so the -# image is built again only when this folder changes. The floor is the first whose extension routes take the agent's -# control token; raise it when the agent needs a newer protocol. -agentenv-framework-protocol[agent]>=0.1.582 +# image is built again only when this folder changes. The floor is the first that takes the native trajectory format +# the agent declares (enable(TRAJECTORY_V1, native=...)); raise it when the agent needs a newer protocol. +agentenv-framework-protocol[agent]>=0.1.588 diff --git a/src/agent_env/agents/agents/hermes/a2a_server.py b/src/agent_env/agents/agents/hermes/a2a_server.py index 54092f277..ee0565539 100644 --- a/src/agent_env/agents/agents/hermes/a2a_server.py +++ b/src/agent_env/agents/agents/hermes/a2a_server.py @@ -343,7 +343,7 @@ def _tar(*args: str) -> None: config=HermesConfig, extensions=( MCP_CONFIG_V1, - enable(TRAJECTORY_V1, live=True), + enable(TRAJECTORY_V1, live=True, native=TRAJECTORY_FORMAT), enable(ATTRIBUTION_PROBE_V1), # SDK default: Hermes reaches the task's other agents through the SDK's peer_agents MCP tools. PEER_AGENTS_V1, diff --git a/src/agent_env/agents/agents/hermes/requirements.txt b/src/agent_env/agents/agents/hermes/requirements.txt index 32d7191b3..b0dd0ae3f 100644 --- a/src/agent_env/agents/agents/hermes/requirements.txt +++ b/src/agent_env/agents/agents/hermes/requirements.txt @@ -1,5 +1,5 @@ # The image installs the newest agentenv-framework-protocol at or above this floor; a release doesn't pin it, so the -# image is built again only when this folder changes. The floor is the first whose extension routes take the agent's -# control token; raise it when the agent needs a newer protocol. -agentenv-framework-protocol[agent]>=0.1.582 +# image is built again only when this folder changes. The floor is the first that takes the native trajectory format +# the agent declares (enable(TRAJECTORY_V1, native=...)); raise it when the agent needs a newer protocol. +agentenv-framework-protocol[agent]>=0.1.588 jsonschema>=4.18,<5 diff --git a/src/agent_env/agents/agents/letta-code/a2a_server.py b/src/agent_env/agents/agents/letta-code/a2a_server.py index d11349b52..becad591e 100644 --- a/src/agent_env/agents/agents/letta-code/a2a_server.py +++ b/src/agent_env/agents/agents/letta-code/a2a_server.py @@ -287,7 +287,7 @@ async def lifespan(app: Starlette): config=LettaCodeConfig, extensions=( MCP_CONFIG_V1, - enable(TRAJECTORY_V1, live=True), + enable(TRAJECTORY_V1, live=True, native=TRAJECTORY_FORMAT), enable(ATTRIBUTION_PROBE_V1), enable( INSTALL_V1, diff --git a/src/agent_env/agents/agents/letta-code/requirements.txt b/src/agent_env/agents/agents/letta-code/requirements.txt index dbfbd05ae..6bbe3605a 100644 --- a/src/agent_env/agents/agents/letta-code/requirements.txt +++ b/src/agent_env/agents/agents/letta-code/requirements.txt @@ -1,6 +1,6 @@ # The image installs the newest agentenv-framework-protocol at or above this floor; a release doesn't pin it, so the -# image is built again only when this folder changes. The floor is the first whose extension routes take the agent's -# control token; raise it when the agent needs a newer protocol. -agentenv-framework-protocol[agent]>=0.1.582 +# image is built again only when this folder changes. The floor is the first that takes the native trajectory format +# the agent declares (enable(TRAJECTORY_V1, native=...)); raise it when the agent needs a newer protocol. +agentenv-framework-protocol[agent]>=0.1.588 jsonschema>=4.18,<5 aiohttp>=3.9,<4 diff --git a/src/agent_env/agents/agents/opencode/a2a_server.py b/src/agent_env/agents/agents/opencode/a2a_server.py index 456781eb5..5d1190a1c 100644 --- a/src/agent_env/agents/agents/opencode/a2a_server.py +++ b/src/agent_env/agents/agents/opencode/a2a_server.py @@ -310,7 +310,7 @@ def memory_mb(cgroup_limit: Path = Path("/sys/fs/cgroup/memory.max")) -> int: config=OpenCodeConfig, extensions=( MCP_CONFIG_V1, - enable(TRAJECTORY_V1, live=True), + enable(TRAJECTORY_V1, live=True, native=TRAJECTORY_FORMAT), enable(ATTRIBUTION_PROBE_V1), enable( INSTALL_V1, diff --git a/src/agent_env/agents/agents/opencode/requirements.txt b/src/agent_env/agents/agents/opencode/requirements.txt index 32d7191b3..b0dd0ae3f 100644 --- a/src/agent_env/agents/agents/opencode/requirements.txt +++ b/src/agent_env/agents/agents/opencode/requirements.txt @@ -1,5 +1,5 @@ # The image installs the newest agentenv-framework-protocol at or above this floor; a release doesn't pin it, so the -# image is built again only when this folder changes. The floor is the first whose extension routes take the agent's -# control token; raise it when the agent needs a newer protocol. -agentenv-framework-protocol[agent]>=0.1.582 +# image is built again only when this folder changes. The floor is the first that takes the native trajectory format +# the agent declares (enable(TRAJECTORY_V1, native=...)); raise it when the agent needs a newer protocol. +agentenv-framework-protocol[agent]>=0.1.588 jsonschema>=4.18,<5 diff --git a/src/agent_env/agents/agents/openhands/openhands_agent.py b/src/agent_env/agents/agents/openhands/openhands_agent.py index 9c8129f98..fecf02c4b 100644 --- a/src/agent_env/agents/agents/openhands/openhands_agent.py +++ b/src/agent_env/agents/agents/openhands/openhands_agent.py @@ -327,7 +327,8 @@ def _stage_conversation(archive: Path, conversations_dir: Path, target_id: str, lifespan=_turns_stop_with_the_server, extensions=( MCP_CONFIG_V1, - enable(TRAJECTORY_V1, live=True, description="The task's OpenHands SDK events, also while it runs."), + enable(TRAJECTORY_V1, live=True, native=TRAJECTORY_FORMAT, + description="The task's OpenHands SDK events, also while it runs."), enable( SNAPSHOT_V1, description=( diff --git a/src/agent_env/agents/agents/openhands/requirements.txt b/src/agent_env/agents/agents/openhands/requirements.txt index a6fc7be6e..de2a01407 100644 --- a/src/agent_env/agents/agents/openhands/requirements.txt +++ b/src/agent_env/agents/agents/openhands/requirements.txt @@ -1,6 +1,6 @@ # The image installs the newest agentenv-framework-protocol at or above this floor; a release doesn't pin it, so the -# image is built again only when this folder changes. The floor is the first whose extension routes take the agent's -# control token; raise it when the agent needs a newer protocol. -agentenv-framework-protocol[agent]>=0.1.582 +# image is built again only when this folder changes. The floor is the first that takes the native trajectory format +# the agent declares (enable(TRAJECTORY_V1, native=...)); raise it when the agent needs a newer protocol. +agentenv-framework-protocol[agent]>=0.1.588 openhands-sdk==1.58.2 openhands-tools==1.58.2 diff --git a/src/agent_env/agents/agents/pi/pi_agent.py b/src/agent_env/agents/agents/pi/pi_agent.py index 98e2fed54..46e550d8c 100644 --- a/src/agent_env/agents/agents/pi/pi_agent.py +++ b/src/agent_env/agents/agents/pi/pi_agent.py @@ -368,7 +368,8 @@ def _unpack(archive: Path, directory: Path) -> None: config_description="Configure the pi runtime: model, effort, system prompt and tool allowlist.", extensions=( MCP_CONFIG_V1, - enable(TRAJECTORY_V1, description="The pi JSON-mode event stream of a completed task."), + enable(TRAJECTORY_V1, native=TRAJECTORY_FORMAT, + description="The pi JSON-mode event stream of a completed task."), enable( SNAPSHOT_V1, description=( diff --git a/src/agent_env/agents/agents/pi/requirements.txt b/src/agent_env/agents/agents/pi/requirements.txt index 5d00eb18f..91e032ab6 100644 --- a/src/agent_env/agents/agents/pi/requirements.txt +++ b/src/agent_env/agents/agents/pi/requirements.txt @@ -1,4 +1,4 @@ # The image installs the newest agentenv-framework-protocol at or above this floor; a release doesn't pin it, so the -# image is built again only when this folder changes. The floor is the first whose extension routes take the agent's -# control token; raise it when the agent needs a newer protocol. -agentenv-framework-protocol[agent]>=0.1.582 +# image is built again only when this folder changes. The floor is the first that takes the native trajectory format +# the agent declares (enable(TRAJECTORY_V1, native=...)); raise it when the agent needs a newer protocol. +agentenv-framework-protocol[agent]>=0.1.588 diff --git a/src/agent_env/agents/agents/proxy/requirements.txt b/src/agent_env/agents/agents/proxy/requirements.txt index 5d00eb18f..91e032ab6 100644 --- a/src/agent_env/agents/agents/proxy/requirements.txt +++ b/src/agent_env/agents/agents/proxy/requirements.txt @@ -1,4 +1,4 @@ # The image installs the newest agentenv-framework-protocol at or above this floor; a release doesn't pin it, so the -# image is built again only when this folder changes. The floor is the first whose extension routes take the agent's -# control token; raise it when the agent needs a newer protocol. -agentenv-framework-protocol[agent]>=0.1.582 +# image is built again only when this folder changes. The floor is the first that takes the native trajectory format +# the agent declares (enable(TRAJECTORY_V1, native=...)); raise it when the agent needs a newer protocol. +agentenv-framework-protocol[agent]>=0.1.588 diff --git a/src/agent_env/agents/agents/pydantic-ai/pydantic_ai_agent.py b/src/agent_env/agents/agents/pydantic-ai/pydantic_ai_agent.py index bd88e824b..6596f606a 100644 --- a/src/agent_env/agents/agents/pydantic-ai/pydantic_ai_agent.py +++ b/src/agent_env/agents/agents/pydantic-ai/pydantic_ai_agent.py @@ -347,7 +347,8 @@ def _stage_conversation( lifespan=_turns_stop_with_the_server, extensions=( MCP_CONFIG_V1, - enable(TRAJECTORY_V1, live=True, description="The task's Pydantic AI messages, also while it runs."), + enable(TRAJECTORY_V1, live=True, native=TRAJECTORY_FORMAT, + description="The task's Pydantic AI messages, also while it runs."), enable( SNAPSHOT_V1, description=( diff --git a/src/agent_env/agents/agents/pydantic-ai/requirements.txt b/src/agent_env/agents/agents/pydantic-ai/requirements.txt index 43d2dac10..9d88ef579 100644 --- a/src/agent_env/agents/agents/pydantic-ai/requirements.txt +++ b/src/agent_env/agents/agents/pydantic-ai/requirements.txt @@ -1,6 +1,6 @@ # The image installs the newest agentenv-framework-protocol at or above this floor; a release doesn't pin it, so the -# image is built again only when this folder changes. The floor is the first whose extension routes take the agent's -# control token; raise it when the agent needs a newer protocol. -agentenv-framework-protocol[agent]>=0.1.582 +# image is built again only when this folder changes. The floor is the first that takes the native trajectory format +# the agent declares (enable(TRAJECTORY_V1, native=...)); raise it when the agent needs a newer protocol. +agentenv-framework-protocol[agent]>=0.1.588 pydantic-ai-slim[mcp,openai]==2.61.0 pydantic-ai-harness[coder,skills]==0.61.0 diff --git a/tst/unit/agents/claude_code/test_image_contract.py b/tst/unit/agents/claude_code/test_image_contract.py index 833e5775c..b0487da84 100644 --- a/tst/unit/agents/claude_code/test_image_contract.py +++ b/tst/unit/agents/claude_code/test_image_contract.py @@ -38,7 +38,7 @@ def test_the_image_installs_the_protocol_alone_from_its_requirements(): requirements = [line for line in (AGENT_DIR / "requirements.txt").read_text().splitlines() if line and not line.startswith("#")] - assert requirements == ["agentenv-framework-protocol[agent]>=0.1.582"] + assert requirements == ["agentenv-framework-protocol[agent]>=0.1.588"] def test_the_image_gives_the_model_node_alone_from_a_pinned_image(): diff --git a/tst/unit/agents/claude_code/test_object_transfer.py b/tst/unit/agents/claude_code/test_object_transfer.py index eaadf1168..ae99fb593 100644 --- a/tst/unit/agents/claude_code/test_object_transfer.py +++ b/tst/unit/agents/claude_code/test_object_transfer.py @@ -109,7 +109,8 @@ def test_a_context_trajectory_is_uploaded_through_its_grant(monkeypatch, tmp_pat body = store.objects["traj/ctx-1.json"] assert body == json.dumps([{"type": "assistant", "message": message, "session_id": "s-1"}], separators=(",", ":")).encode() - assert result == {"objects": {"trajectory": {"size_bytes": len(body), "sha256": hashlib.sha256(body).hexdigest()}}} + assert result == {"objects": {"trajectory": {"size_bytes": len(body), "sha256": hashlib.sha256(body).hexdigest()}}, + "format": a2a_server.SESSION_TRAJECTORY_FORMAT} # ── snapshot ───────────────────────────────────────────────────────────────────── diff --git a/tst/unit/agents/claude_code/test_partial_trajectory.py b/tst/unit/agents/claude_code/test_partial_trajectory.py index 0910bf849..2284b243a 100644 --- a/tst/unit/agents/claude_code/test_partial_trajectory.py +++ b/tst/unit/agents/claude_code/test_partial_trajectory.py @@ -175,6 +175,7 @@ def test_context_trajectory_endpoint_reports_complete_live_session(monkeypatch, "session_id": "session-1", } ], + "format": a2a_server.SESSION_TRAJECTORY_FORMAT, "session_lines": 2, "is_live": True, "session_id": "session-1", diff --git a/tst/unit/agents/codex/test_codex_snapshot_hardening.py b/tst/unit/agents/codex/test_codex_snapshot_hardening.py index 27bb57d08..651a2689c 100644 --- a/tst/unit/agents/codex/test_codex_snapshot_hardening.py +++ b/tst/unit/agents/codex/test_codex_snapshot_hardening.py @@ -310,6 +310,7 @@ async def exercise(): assert asyncio.run(exercise()) == { "trajectory": [THREAD_STARTED], + "format": a2a_server.TRAJECTORY_FORMAT, "is_live": True, "session_id": "thread-1", "harness": "codex-cli", diff --git a/tst/unit/agents/codex/test_image_contract.py b/tst/unit/agents/codex/test_image_contract.py index 350cfbf1e..f122eb24e 100644 --- a/tst/unit/agents/codex/test_image_contract.py +++ b/tst/unit/agents/codex/test_image_contract.py @@ -54,7 +54,7 @@ def test_the_requirements_are_the_protocol_floor_the_config_writer_and_the_ca_bu requirements = [line for line in (AGENT_DIR / "requirements.txt").read_text().splitlines() if line and not line.startswith("#")] - assert requirements == ["agentenv-framework-protocol[agent]>=0.1.582", "tomli-w==1.2.0", "certifi"] + assert requirements == ["agentenv-framework-protocol[agent]>=0.1.588", "tomli-w==1.2.0", "certifi"] def test_the_image_gives_the_models_python_the_document_libraries(): diff --git a/tst/unit/agents/codex/test_object_transfer.py b/tst/unit/agents/codex/test_object_transfer.py index ed6889118..e6b70c15b 100644 --- a/tst/unit/agents/codex/test_object_transfer.py +++ b/tst/unit/agents/codex/test_object_transfer.py @@ -268,7 +268,7 @@ async def exercise(): assert result == {"objects": {"trajectory": { "size_bytes": len(store.objects["traj/ctx.json"]), "sha256": hashlib.sha256(store.objects["traj/ctx.json"]).hexdigest(), - }}} + }}, "format": a2a_server.TRAJECTORY_FORMAT} assert (inline["trajectory"], inline["is_live"]) == (events, live) diff --git a/tst/unit/agents/gemini/test_image_contract.py b/tst/unit/agents/gemini/test_image_contract.py index df35bf148..021fab736 100644 --- a/tst/unit/agents/gemini/test_image_contract.py +++ b/tst/unit/agents/gemini/test_image_contract.py @@ -54,7 +54,7 @@ def test_the_image_installs_the_protocol_alone_from_its_requirements(): requirements = [line for line in (AGENT_DIR / "requirements.txt").read_text().splitlines() if line and not line.startswith("#")] - assert requirements == ["agentenv-framework-protocol[agent]>=0.1.582"] + assert requirements == ["agentenv-framework-protocol[agent]>=0.1.588"] def test_the_image_gives_the_models_python_the_document_libraries(): diff --git a/tst/unit/agents/opencode/test_image_contract.py b/tst/unit/agents/opencode/test_image_contract.py index 3c7d8c68b..180ef8939 100644 --- a/tst/unit/agents/opencode/test_image_contract.py +++ b/tst/unit/agents/opencode/test_image_contract.py @@ -50,7 +50,7 @@ def test_the_requirements_are_the_protocol_floor_and_the_output_format_validator requirements = [line for line in (AGENT_DIR / "requirements.txt").read_text().splitlines() if line and not line.startswith("#")] - assert requirements == ["agentenv-framework-protocol[agent]>=0.1.582", "jsonschema>=4.18,<5"] + assert requirements == ["agentenv-framework-protocol[agent]>=0.1.588", "jsonschema>=4.18,<5"] def test_node_is_pinned_by_version_and_checksum_for_the_image_and_an_install(): diff --git a/tst/unit/agents/test_trajectory_formats.py b/tst/unit/agents/test_trajectory_formats.py new file mode 100644 index 000000000..e912ae5fa --- /dev/null +++ b/tst/unit/agents/test_trajectory_formats.py @@ -0,0 +1,60 @@ +"""Every bundled agent declares its trajectory's native format, so its card offers it as ``formats``, ``native`` and +``default``, the SDK holds its log and returned native trajectories to it, and every read it serves names it. An agent +that left ``native`` out would keep serving trajectories its card can't describe.""" +import importlib +import importlib.util +import sys +from pathlib import Path + +import pytest +from agentenv_protocol.a2a_agent import TRAJECTORY_V1 + +import agent_env + +AGENTS_DIR = Path(agent_env.__file__).parent / "agents" / "agents" +#: Each bundled agent's native format, and where its tests import the module holding its agent class. +AGENTS = { + "claude-code": ("claude-code-stream-json/1", "tst.unit.agents.claude_code.agent", "a2a_server"), + "codex": ("codex-exec-json/1", "tst.unit.agents.codex.agent", "a2a_server"), + "gemini": ("gemini-stream-json/1", "tst.unit.agents.gemini.agent", "a2a_server"), + "hermes": ("hermes-hook-events/1", "tst.unit.agents.hermes.agent", "a2a_server"), + "letta-code": ("letta-code-events/1", "tst.unit.agents.letta_code.agent", "a2a_server"), + "opencode": ("opencode-events/1", "tst.unit.agents.opencode.agent", "a2a_server"), + "openhands": ("openhands-events/v1", "tst.unit.agents.openhands.agent", "openhands_agent"), + "pi": ("pi-json-events/v1", "tst.unit.agents.pi.agent", "pi_agent"), + "proxy": ("agentenv-proxy/v1", "tst.unit.agents.proxy.agent", "a2a_server"), + "pydantic-ai": ("pydantic-ai-messages/v1", "tst.unit.agents.pydantic_ai.agent", "pydantic_ai_agent"), +} + + +def _trajectory(module) -> object: + """The trajectory activation of the agent class the module itself declares.""" + (agent,) = [value for value in vars(module).values() if isinstance(value, type) + and value.__module__ == module.__name__ and "_agentenv_a2a_definition" in vars(value)] + (activation,) = [a for a in vars(agent)["_agentenv_a2a_definition"].extensions if a.definition is TRAJECTORY_V1] + return activation + + +def test_every_bundled_agent_is_listed(): + folders = sorted(path.parent.name for path in AGENTS_DIR.glob("*/requirements.txt")) + assert folders == sorted([*AGENTS, "browser-use"]) + + +@pytest.mark.parametrize("agent", sorted(AGENTS)) +def test_a_bundled_agent_declares_its_native_trajectory_format(agent): + native, loader, attribute = AGENTS[agent] + activation = _trajectory(getattr(importlib.import_module(loader), attribute)) + assert activation.options["native"] == native + assert dict(activation.wire_params) == {"formats": [native], "native": native, "default": native} + + +def test_browser_use_declares_its_native_trajectory_format(): + # browser-use's own test stubs its runtime before importing it, so the module is read here by its path. + name = "browser_use_a2a_server" + module = sys.modules.get(name) + if module is None: + spec = importlib.util.spec_from_file_location(name, AGENTS_DIR / "browser-use" / "a2a_server.py") + module = importlib.util.module_from_spec(spec) + sys.modules[name] = module + spec.loader.exec_module(module) + assert _trajectory(module).options["native"] == module.TRAJECTORY_FORMAT == "browser-use-messages/1" From 8745014262bcfe52dde0b2813761f95f7c84b5c4 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 18:10:26 -0800 Subject: [PATCH 2/4] test(codex): the catalog-read budget test measures the read instead of assuming it takes under a second It asserted the CLI got more than 29 of its 30 s after a read that sleeps 0.5 s, which failed under load (28.9 s). It now times the read in its stub and checks the CLI's budget lost at least that, within two seconds of scheduling. Co-Authored-By: Claude Opus 5.5 --- tst/unit/agents/codex/test_codex_builtin_tools.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/tst/unit/agents/codex/test_codex_builtin_tools.py b/tst/unit/agents/codex/test_codex_builtin_tools.py index 755f5512c..52e8d8a20 100644 --- a/tst/unit/agents/codex/test_codex_builtin_tools.py +++ b/tst/unit/agents/codex/test_codex_builtin_tools.py @@ -9,6 +9,7 @@ import asyncio import json import os +import time import tomllib from pathlib import Path from typing import Any @@ -233,13 +234,15 @@ async def cancel_mid_read(): def test_the_catalog_read_counts_against_the_turns_time_limit(codex, cli, monkeypatch): """The CLI gets what is left of `timeout_seconds` after the catalog read; without a read, all of it, as before.""" monkeypatch.setenv("A2A_PORT", "8000") - timeouts = [] + timeouts, reads = [], [] real_catalog_overrides = codex_config.catalog_overrides async def slow_catalog_overrides(builtin_tools, timeout_s): + started = time.monotonic() overrides = await real_catalog_overrides(builtin_tools, timeout_s) if overrides: await asyncio.sleep(0.5) + reads.append(time.monotonic() - started) return overrides async def fake_run_codex(**kwargs): @@ -259,8 +262,10 @@ async def exercise(): asyncio.run(exercise()) without_read, with_read = timeouts + (read,) = reads assert without_read == 30 - assert 29 < with_read <= 29.5 + # The CLI's budget lost at least the read's own time; the slack is the scheduling around it, which load stretches. + assert 30 - read - 2 < with_read <= 30 - read @pytest.mark.parametrize("selection, match", [ From dbd1cea9822c63fcac58516852e428dc979e7b80 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 18:11:19 -0800 Subject: [PATCH 3/4] test(agents): the installed proxy's card offers its native trajectory format, its reads name it and refuse another Co-Authored-By: Claude Opus 5.5 --- .../agent/proxy_container_install_test.py | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/tst/integration/agent/proxy_container_install_test.py b/tst/integration/agent/proxy_container_install_test.py index 60649635e..f9eb496ed 100644 --- a/tst/integration/agent/proxy_container_install_test.py +++ b/tst/integration/agent/proxy_container_install_test.py @@ -1,7 +1,8 @@ """The proxy's folder installed into a running container by its own install.sh, as install_agent installs it there. It brings its own Python and serves; its bash runs commands with bash, or with sh in a container that has only sh (Alpine, -musl), and says which. The container installs this checkout's protocol, so the test covers the code beside it, and its -extension routes take the control token the install was handed, as install_agent hands it.""" +musl), and says which. The container installs this checkout's protocol, so the test covers the code beside it; its +extension routes take the control token the install was handed, as install_agent hands it; and its card offers its +native trajectory format, which its reads name, refusing any other.""" import os import shutil @@ -23,6 +24,7 @@ AGENT_DIR = Path(agent_env.__file__).parent / "agents" / "agents" / "proxy" PROTOCOL_DIR = Path(agent_env.__file__).parents[2] / "packages" / "agentenv-protocol" PORT = 8000 +NATIVE = "agentenv-proxy/v1" TOKEN = "t" * 32 CONTROL_TOKEN = "c" * 32 @@ -57,17 +59,25 @@ def test_installed_into_a_container_the_proxy_serves_and_its_bash_runs_the_shell base_url = f"http://{_published(name)}" with httpx.Client(base_url=base_url, timeout=30, headers=control_token_headers(CONTROL_TOKEN)) as client: _serving(client) + card = client.get("/.well-known/agent.json").json() assert httpx.post(f"{base_url}/ext/proxy/claim", json={"token": TOKEN}, timeout=30).status_code == 401 assert client.post("/ext/proxy/claim", json={"token": TOKEN}).status_code == 200 task_id = _send(client, "go") tools = _proxy(client, "tools", task_id=task_id).json()["tools"] result = _done(client, task_id, {"kind": "bash", "command": "echo $0; echo out"}) + page = client.post("/ext/trajectory", json={"task_id": task_id, "after": 0, "format": NATIVE}) + refused = client.post("/ext/trajectory", json={"task_id": task_id, "after": 0, "format": "atif/1"}) assert [tool["name"] for tool in tools] == ["bash"] assert tools[0]["description"].startswith( "Run a bash command where" if shell == "bash" else "Run a command where the agent works, as its user, in its " "folder, with POSIX sh: this place has no bash") assert (result["exit_code"], result["stdout"]) == (0, f"{shell}\nout\n") + (trajectory,) = [e for e in card["capabilities"]["extensions"] if e["uri"] == "urn:agentenv:trajectory/v1"] + assert {k: trajectory["params"][k] for k in ("formats", "native", "default")} == { + "formats": [NATIVE], "native": NATIVE, "default": NATIVE} + assert (page.status_code, page.json()["format"]) == (200, NATIVE) + assert (refused.status_code, refused.json()["error"]["code"]) == (400, "format_not_offered") def _published(container: str) -> str: From d68fc5f2ae329453187c74ce795919095f4c9a76 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 20:40:06 -0800 Subject: [PATCH 4/4] test(agents): the catalog-read budget test names its scheduling slack Co-Authored-By: Claude Opus 5.5 --- tst/unit/agents/codex/test_codex_builtin_tools.py | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/tst/unit/agents/codex/test_codex_builtin_tools.py b/tst/unit/agents/codex/test_codex_builtin_tools.py index 52e8d8a20..db40fbbba 100644 --- a/tst/unit/agents/codex/test_codex_builtin_tools.py +++ b/tst/unit/agents/codex/test_codex_builtin_tools.py @@ -231,6 +231,11 @@ async def cancel_mid_read(): assert not _alive(int(pid_file.read_text())) +#: How much more than the catalog read's own time the CLI's budget may lose: the scheduling around the read, which +#: load stretches. +_SCHEDULING_SLACK_S = 2 + + def test_the_catalog_read_counts_against_the_turns_time_limit(codex, cli, monkeypatch): """The CLI gets what is left of `timeout_seconds` after the catalog read; without a read, all of it, as before.""" monkeypatch.setenv("A2A_PORT", "8000") @@ -264,8 +269,7 @@ async def exercise(): without_read, with_read = timeouts (read,) = reads assert without_read == 30 - # The CLI's budget lost at least the read's own time; the slack is the scheduling around it, which load stretches. - assert 30 - read - 2 < with_read <= 30 - read + assert 30 - read - _SCHEDULING_SLACK_S < with_read <= 30 - read @pytest.mark.parametrize("selection, match", [