From 4d0a21a812ffac5724a433800446d07e7fa8f514 Mon Sep 17 00:00:00 2001 From: Ubuntu Date: Mon, 16 Nov 2026 18:00:11 +0000 Subject: [PATCH 1/3] test(snapshot): expect the save's size, file count and phase durations in agent-env's logs Co-authored-by: Claude Opus 5.5 --- .../agentenv-protocol/tests/test_a2a_agent.py | 2 +- .../agents/claude_code/test_card_contract.py | 2 +- .../claude_code/test_workspace_snapshot.py | 2 +- tst/unit/agents/codex/test_card_contract.py | 2 +- tst/unit/agents/codex/test_object_transfer.py | 2 +- tst/unit/agents/gemini/test_card_contract.py | 2 +- .../task_step/test_agent_state_capture.py | 57 +++++++++++++++++++ 7 files changed, 63 insertions(+), 6 deletions(-) diff --git a/packages/agentenv-protocol/tests/test_a2a_agent.py b/packages/agentenv-protocol/tests/test_a2a_agent.py index 2dd336b7b..7c3076dcc 100644 --- a/packages/agentenv-protocol/tests/test_a2a_agent.py +++ b/packages/agentenv-protocol/tests/test_a2a_agent.py @@ -1481,7 +1481,7 @@ async def apply_changelog(self, request: ObjectChangelogApplyRequest): assert set(params) == {"endpoint", "methods"} methods = params["methods"] assert methods["save"]["request"] == {"required": ["context_id", "objects"]} - assert methods["save"]["response"] == {"required": ["context_id", "objects"]} + assert methods["save"]["response"] == {"required": ["context_id", "objects"], "optional": ["stats"]} assert methods["load"]["request"] == { "required": ["objects"], "optional": ["target_context_id"], diff --git a/tst/unit/agents/claude_code/test_card_contract.py b/tst/unit/agents/claude_code/test_card_contract.py index 1a7ec6690..97221ef97 100644 --- a/tst/unit/agents/claude_code/test_card_contract.py +++ b/tst/unit/agents/claude_code/test_card_contract.py @@ -102,7 +102,7 @@ def test_request_and_response_contracts(app): } assert methods["urn:agentenv:snapshot/v1"] == { "save": {"method": "POST", "request": {"required": ["context_id", "objects"]}, - "response": {"required": ["context_id", "objects"]}}, + "response": {"required": ["context_id", "objects"], "optional": ["stats"]}}, "load": {"method": "PUT", "request": {"required": ["objects"], "optional": ["target_context_id"]}, "response": {"required": ["context_id"]}}, } diff --git a/tst/unit/agents/claude_code/test_workspace_snapshot.py b/tst/unit/agents/claude_code/test_workspace_snapshot.py index ff0b29607..568d13bc7 100644 --- a/tst/unit/agents/claude_code/test_workspace_snapshot.py +++ b/tst/unit/agents/claude_code/test_workspace_snapshot.py @@ -36,7 +36,7 @@ def test_agent_card_advertises_unified_save_method(app): assert methods["save"] == { "method": "POST", "request": {"required": ["context_id", "objects"]}, - "response": {"required": ["context_id", "objects"]}, + "response": {"required": ["context_id", "objects"], "optional": ["stats"]}, } diff --git a/tst/unit/agents/codex/test_card_contract.py b/tst/unit/agents/codex/test_card_contract.py index be78054f6..783e555e5 100644 --- a/tst/unit/agents/codex/test_card_contract.py +++ b/tst/unit/agents/codex/test_card_contract.py @@ -147,7 +147,7 @@ def test_request_and_response_contracts(codex): "save": { "method": "POST", "request": {"required": ["context_id", "objects"]}, - "response": {"required": ["context_id", "objects"]}, + "response": {"required": ["context_id", "objects"], "optional": ["stats"]}, }, "load": { "method": "PUT", diff --git a/tst/unit/agents/codex/test_object_transfer.py b/tst/unit/agents/codex/test_object_transfer.py index ed6889118..46305e878 100644 --- a/tst/unit/agents/codex/test_object_transfer.py +++ b/tst/unit/agents/codex/test_object_transfer.py @@ -121,7 +121,7 @@ def test_card_offers_only_the_object_forms(codex): } snapshot = _methods(codex, "urn:agentenv:snapshot/v1") assert snapshot["save"]["request"] == {"required": ["context_id", "objects"]} - assert snapshot["save"]["response"] == {"required": ["context_id", "objects"]} + assert snapshot["save"]["response"] == {"required": ["context_id", "objects"], "optional": ["stats"]} assert snapshot["load"]["request"] == {"required": ["objects"], "optional": ["target_context_id"]} assert snapshot["load"]["response"] == {"required": ["context_id"]} assert "enable-changelog" not in snapshot and "apply-changelog" not in snapshot diff --git a/tst/unit/agents/gemini/test_card_contract.py b/tst/unit/agents/gemini/test_card_contract.py index 510fcc4b7..cdc388d84 100644 --- a/tst/unit/agents/gemini/test_card_contract.py +++ b/tst/unit/agents/gemini/test_card_contract.py @@ -167,7 +167,7 @@ def test_request_and_response_contracts(app): "save": { "method": "POST", "request": {"required": ["context_id", "objects"]}, - "response": {"required": ["context_id", "objects"]}, + "response": {"required": ["context_id", "objects"], "optional": ["stats"]}, }, "load": { "method": "PUT", diff --git a/tst/unit/task_step/test_agent_state_capture.py b/tst/unit/task_step/test_agent_state_capture.py index 5269e467e..3a2c1164b 100644 --- a/tst/unit/task_step/test_agent_state_capture.py +++ b/tst/unit/task_step/test_agent_state_capture.py @@ -372,3 +372,60 @@ def test_a_foreign_bucket_raises_rather_than_writing_to_the_configured_one(monke # silently writes to the configured bucket under the same key path. with pytest.raises(ValueError, match="not in the configured bucket"): mod.upload_trajectory([], "s3://someone-elses-bucket/traj/") + + +def _events(caplog, event: str) -> list: + return [record for record in caplog.records if getattr(record, "event", None) == event] + + +@pytest.mark.asyncio +async def test_a_completed_save_logs_the_workspace_size_and_where_its_time_went(monkeypatch, caplog): + rec = install_capture_stubs(monkeypatch) + rec.save_body = { + "context_id": "ctx-1", + "objects": {"trajectory": {"size_bytes": 10}, "workspace": {"size_bytes": 7_000_000}}, + "stats": {"file_count": 12, "archive_seconds": 3.5, "upload_seconds": 8.25}, + } + caplog.set_level("INFO", logger=mod.__name__) + + await _capture(timeout_seconds=45) + + (record,) = _events(caplog, "snapshot_save_completed") + assert (record.agent_name, record.context_id, record.timeout_seconds) == ("solver", "ctx-1", 45) + assert (record.workspace_archive_bytes, record.file_count) == (7_000_000, 12) + assert (record.archive_seconds, record.upload_seconds) == (3.5, 8.25) + assert record.elapsed_seconds >= 0 + + +@pytest.mark.asyncio +async def test_a_completed_save_from_an_agent_that_reports_no_stats_logs_its_size(monkeypatch, caplog): + rec = install_capture_stubs(monkeypatch) + rec.save_body = { + "context_id": "ctx-1", + "objects": {"trajectory": {"size_bytes": 10}, "workspace": {"size_bytes": 900}}, + } + caplog.set_level("INFO", logger=mod.__name__) + + await _capture() + + (record,) = _events(caplog, "snapshot_save_completed") + assert record.workspace_archive_bytes == 900 + assert (record.file_count, record.archive_seconds, record.upload_seconds) == (None, None, None) + + +@pytest.mark.asyncio +async def test_a_timed_out_save_logs_how_long_it_waited_and_still_raises(monkeypatch, caplog): + install_capture_stubs(monkeypatch) + + async def _stalled(self, method, url, **kwargs): + raise httpx.ReadTimeout("") + + monkeypatch.setattr(httpx.AsyncClient, "request", _stalled) + + with pytest.raises(httpx.ReadTimeout): + await _capture(timeout_seconds=45) + + (record,) = _events(caplog, "snapshot_save_timeout") + assert (record.agent_name, record.context_id, record.timeout_seconds) == ("solver", "ctx-1", 45) + assert record.elapsed_seconds >= 0 + assert record.workspace_max_bytes == 5 * 1024**3 From 0f29484dd9738f2f74475ca89930b3f54761acef Mon Sep 17 00:00:00 2001 From: Ubuntu Date: Mon, 16 Nov 2026 18:00:58 +0000 Subject: [PATCH 2/3] feat(snapshot): the save response takes optional stats, and agent-env logs each save ObjectSnapshotSaveResponse gains an optional stats field: the archived file count and the seconds the agent spent archiving and uploading. capture_workspace logs snapshot_save_completed with the workspace archive's size and those stats, or snapshot_save_timeout with how long it waited. An agent that sends no stats still logs its size, with the stats fields empty. Co-authored-by: Claude Opus 5.5 --- packages/agentenv-protocol/README.md | 6 +- .../agentenv_protocol/a2a_agent/__init__.py | 2 + .../agentenv_protocol/a2a_agent/extensions.py | 9 +++ .../snapshot_utils/agent_state_capture.py | 56 ++++++++++++++++--- 4 files changed, 62 insertions(+), 11 deletions(-) diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index c821ea5e3..18036b1a4 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1921,7 +1921,7 @@ optional field, `|` an alternative request): | trajectory `get` | `{task_id, format?}` \| `{context_id, format?}` | `{trajectory, format}` | | | `{task_id \| context_id, objects: {trajectory: WriteObject}, format?}` | `{objects: {trajectory: Uploaded}, format}` | | | `{task_id \| context_id, after, limit?, format?}` | `{context_id, task_id, state, format, events, next, has_more}` | -| snapshot `save` | `{context_id, objects: {trajectory: WriteObject, workspace?: WriteObject}}` | `{context_id, objects: {trajectory: Uploaded, workspace?: Uploaded}}` | +| snapshot `save` | `{context_id, objects: {trajectory: WriteObject, workspace?: WriteObject}}` | `{context_id, objects: {trajectory: Uploaded, workspace?: Uploaded}, stats?: {file_count, archive_seconds, upload_seconds}}` | | snapshot `load` | `{objects: {trajectory: ReadObject, workspace?: ReadObject}, target_context_id?}` | `{context_id}` | | `enable-changelog` | `{write_namespace: WriteNamespaceGrant, roots?}` | `{roots}` | | `apply-changelog` | `{increments: [{sequence, object: ReadObject}], resume_conversation?, target_context_id?}` | `{count, context_id?}` | @@ -1930,7 +1930,9 @@ A bundle contains a root `SKILL.md`; its paths are unique, normalized and relative, and their `max_bytes` sum to at most `max_total_bytes`. An uploaded trajectory is the JSON encoding of the trajectory value. Snapshot objects are opaque `application/octet-stream` in the runtime's own format; when AgentEnv -sends a workspace grant, the agent uploads the workspace. A changelog agent +sends a workspace grant, the agent uploads the workspace. A save may add +`stats`, the archived file count and the seconds it spent archiving and +uploading, so the caller can log them; it is optional. A changelog agent names each increment under the namespace root by its absolute zero-based tool-call position, six digits plus an optional extension (`000042.tar`); positions are unique but may be sparse, and apply receives them in increasing diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py index af2817887..b6d6436cb 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py @@ -70,6 +70,7 @@ SkillBundle, SkillBundleFile, SnapshotReadObjects, + SnapshotSaveStats, SnapshotUploadedObjects, SnapshotWriteObjects, TaskEventsTrajectoryRequest, @@ -229,6 +230,7 @@ "SkillBundle", "SkillBundleFile", "SnapshotReadObjects", + "SnapshotSaveStats", "SnapshotUploadedObjects", "SnapshotWriteObjects", "StagingStore", diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/extensions.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/extensions.py index eac35f346..6777aa677 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/extensions.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/extensions.py @@ -276,9 +276,18 @@ class SnapshotUploadedObjects(ExtensionResponse): workspace: Uploaded | None = None +class SnapshotSaveStats(ExtensionResponse): + """Where a save spent its time, so the caller can log it: the agent's own logs may never leave its sandbox.""" + + file_count: int = Field(ge=0) + archive_seconds: float = Field(ge=0) + upload_seconds: float = Field(ge=0) + + class ObjectSnapshotSaveResponse(ExtensionResponse): context_id: str objects: SnapshotUploadedObjects + stats: SnapshotSaveStats | None = None class ObjectSnapshotLoadResponse(ExtensionResponse): diff --git a/src/agent_env/task_step/snapshot_utils/agent_state_capture.py b/src/agent_env/task_step/snapshot_utils/agent_state_capture.py index 2694d8488..7d928c4a8 100644 --- a/src/agent_env/task_step/snapshot_utils/agent_state_capture.py +++ b/src/agent_env/task_step/snapshot_utils/agent_state_capture.py @@ -9,6 +9,7 @@ import asyncio import json import logging +import time import uuid from dataclasses import dataclass from collections.abc import Mapping @@ -19,6 +20,7 @@ from agent_env.a2a_agent import A2AAgent from agent_env.a2a_agent.object_transfer import ( + DEFAULT_SNAPSHOT_WORKSPACE_MAX_BYTES, SNAPSHOT_TRAJECTORY_OBJECT_NAME, SNAPSHOT_WORKSPACE_OBJECT_NAME, FetchedTrajectory, @@ -97,15 +99,51 @@ async def capture_workspace( capture_prefix=capture_prefix, sandbox_type=sandbox_type, ) - await invoke_transfer( - a2a_url + save_path, - call, - verb="POST", - operation="snapshot save", - timeout=timeout_seconds, - response_model=ObjectSnapshotSaveResponse, - store=store, - headers=headers, + started = time.monotonic() + try: + saved: ObjectSnapshotSaveResponse = await invoke_transfer( + a2a_url + save_path, + call, + verb="POST", + operation="snapshot save", + timeout=timeout_seconds, + response_model=ObjectSnapshotSaveResponse, + store=store, + headers=headers, + ) + except httpx.TimeoutException: + elapsed = time.monotonic() - started + logger.error( + "Snapshot save timed out: agent=%s context_id=%s after %.1fs (budget %ss)", + agent_name, a2a_context_id, elapsed, timeout_seconds, + extra={ + "event": "snapshot_save_timeout", + "agent_name": agent_name, + "context_id": a2a_context_id, + "elapsed_seconds": round(elapsed, 1), + "timeout_seconds": timeout_seconds, + # The agent hasn't answered, so the workspace's size is unknown; this is its cap. + "workspace_max_bytes": DEFAULT_SNAPSHOT_WORKSPACE_MAX_BYTES, + }, + ) + raise + elapsed = time.monotonic() - started + workspace_bytes = saved.objects.workspace.size_bytes if saved.objects.workspace else None + stats = saved.stats + logger.info( + "Snapshot save completed: agent=%s context_id=%s workspace_bytes=%s in %.1fs", + agent_name, a2a_context_id, workspace_bytes, elapsed, + extra={ + "event": "snapshot_save_completed", + "agent_name": agent_name, + "context_id": a2a_context_id, + "elapsed_seconds": round(elapsed, 1), + "timeout_seconds": timeout_seconds, + "workspace_archive_bytes": workspace_bytes, + "file_count": stats.file_count if stats else None, + "archive_seconds": stats.archive_seconds if stats else None, + "upload_seconds": stats.upload_seconds if stats else None, + }, ) # The agent's answer is only a claim: a snapshot missing either object cannot be restored. From bd5d05831281391d9ffe672a0516825dc12ce079 Mon Sep 17 00:00:00 2001 From: Ubuntu Date: Wed, 18 Nov 2026 18:53:36 +0000 Subject: [PATCH 3/3] fix(snapshot): log a save the caller's deadline cuts off A periodic capture's outer wait_for shares the save's budget and starts first, so a stalled save is cancelled before httpx times out and never logged snapshot_save_timeout. capture_workspace now logs snapshot_save_cancelled with the elapsed time and budget, then re-raises. --- .../snapshot_utils/agent_state_capture.py | 16 ++++++++++++++++ tst/unit/task_step/test_agent_state_capture.py | 18 ++++++++++++++++++ 2 files changed, 34 insertions(+) diff --git a/src/agent_env/task_step/snapshot_utils/agent_state_capture.py b/src/agent_env/task_step/snapshot_utils/agent_state_capture.py index 7d928c4a8..c3526311a 100644 --- a/src/agent_env/task_step/snapshot_utils/agent_state_capture.py +++ b/src/agent_env/task_step/snapshot_utils/agent_state_capture.py @@ -127,6 +127,22 @@ async def capture_workspace( }, ) raise + except asyncio.CancelledError: + # A periodic capture's outer `wait_for` shares this budget and starts first, so + # a stalled save usually ends here rather than in httpx's timeout. + elapsed = time.monotonic() - started + logger.warning( + "Snapshot save cancelled: agent=%s context_id=%s after %.1fs (budget %ss)", + agent_name, a2a_context_id, elapsed, timeout_seconds, + extra={ + "event": "snapshot_save_cancelled", + "agent_name": agent_name, + "context_id": a2a_context_id, + "elapsed_seconds": round(elapsed, 1), + "timeout_seconds": timeout_seconds, + }, + ) + raise elapsed = time.monotonic() - started workspace_bytes = saved.objects.workspace.size_bytes if saved.objects.workspace else None stats = saved.stats diff --git a/tst/unit/task_step/test_agent_state_capture.py b/tst/unit/task_step/test_agent_state_capture.py index 3a2c1164b..c938b382b 100644 --- a/tst/unit/task_step/test_agent_state_capture.py +++ b/tst/unit/task_step/test_agent_state_capture.py @@ -429,3 +429,21 @@ async def _stalled(self, method, url, **kwargs): assert (record.agent_name, record.context_id, record.timeout_seconds) == ("solver", "ctx-1", 45) assert record.elapsed_seconds >= 0 assert record.workspace_max_bytes == 5 * 1024**3 + + +@pytest.mark.asyncio +async def test_a_save_cut_off_by_the_callers_deadline_logs_how_long_it_ran(monkeypatch, caplog): + install_capture_stubs(monkeypatch) + + async def _stalled(self, method, url, **kwargs): + await asyncio.sleep(60) + + monkeypatch.setattr(httpx.AsyncClient, "request", _stalled) + + with pytest.raises(asyncio.TimeoutError): + await asyncio.wait_for(_capture(timeout_seconds=45), timeout=0.2) + + (record,) = _events(caplog, "snapshot_save_cancelled") + assert (record.agent_name, record.context_id, record.timeout_seconds) == ("solver", "ctx-1", 45) + assert record.elapsed_seconds >= 0 + assert not _events(caplog, "snapshot_save_timeout")