From 00ec7b24ffe0e0c0ec76c8a784079038e25c6ebc 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 5e82d5501..8424f869d 100644 --- a/packages/agentenv-protocol/tests/test_a2a_agent.py +++ b/packages/agentenv-protocol/tests/test_a2a_agent.py @@ -1474,7 +1474,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 0ace58b4f..59e7bd80e 100644 --- a/tst/unit/agents/claude_code/test_card_contract.py +++ b/tst/unit/agents/claude_code/test_card_contract.py @@ -101,7 +101,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 4150411d9..003a2fb51 100644 --- a/tst/unit/agents/codex/test_card_contract.py +++ b/tst/unit/agents/codex/test_card_contract.py @@ -146,7 +146,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 e7aa971cf..bee697b67 100644 --- a/tst/unit/agents/codex/test_object_transfer.py +++ b/tst/unit/agents/codex/test_object_transfer.py @@ -120,7 +120,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 eea71acca..5866ab2b5 100644 --- a/tst/unit/agents/gemini/test_card_contract.py +++ b/tst/unit/agents/gemini/test_card_contract.py @@ -166,7 +166,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 88e717b77..b011885e4 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 5515f7b8639211a0195f44b8eb3830633bd61780 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 | 54 ++++++++++++++++--- 4 files changed, 61 insertions(+), 10 deletions(-) diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index 94cd518fe..5883159f1 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1818,7 +1818,7 @@ optional field, `|` an alternative request): | trajectory `get` | `{task_id}` \| `{context_id}` | `{trajectory}` | | | `{task_id \| context_id, objects: {trajectory: WriteObject}}` | `{objects: {trajectory: Uploaded}}` | | | `{task_id \| context_id, after, limit?}` | `{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?}` | @@ -1827,7 +1827,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 5f17fed1e..d1ccb1604 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py @@ -69,6 +69,7 @@ SkillBundle, SkillBundleFile, SnapshotReadObjects, + SnapshotSaveStats, SnapshotUploadedObjects, SnapshotWriteObjects, TaskEventsTrajectoryRequest, @@ -225,6 +226,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 d48ff283b..49ab3aeaf 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/extensions.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/extensions.py @@ -252,9 +252,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 3630b9454..9b455ab2e 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 typing import Any, Optional @@ -18,6 +19,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, @@ -95,14 +97,50 @@ 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, + 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, + ) + 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 5b632ad5310428ad6b5a984663ca368b3ff16989 Mon Sep 17 00:00:00 2001 From: Ubuntu Date: Mon, 16 Nov 2026 18:02:03 +0000 Subject: [PATCH 3/3] feat(claude-code): report a snapshot save's file count and phase durations The save response's stats carry the archived file count and the seconds the agent spent archiving and uploading, so agent-env logs them, and the agent's own log line names both durations. Co-authored-by: Claude Opus 5.5 --- src/agent_env/agents/agents/claude-code/a2a_server.py | 10 ++++++++-- tst/unit/agents/claude_code/test_object_transfer.py | 2 +- tst/unit/agents/claude_code/test_workspace_snapshot.py | 4 ++++ 3 files changed, 13 insertions(+), 3 deletions(-) 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 7dc27625e..0c14d8ccf 100644 --- a/src/agent_env/agents/agents/claude-code/a2a_server.py +++ b/src/agent_env/agents/agents/claude-code/a2a_server.py @@ -16,6 +16,7 @@ import stat import tarfile import tempfile +import time import uuid from collections.abc import AsyncIterator, Iterable from contextlib import asynccontextmanager @@ -580,19 +581,24 @@ async def save_snapshot(self, request: ObjectSnapshotSaveRequest) -> ObjectSnaps os.close(jsonl_fd) archive_path, snapshot_jsonl_path = Path(raw_archive_path), Path(raw_jsonl_path) try: + started = time.monotonic() file_count, bytes_written = await asyncio.to_thread(_build_workspace_archive, archive_path) + archived = time.monotonic() await asyncio.to_thread(snapshot_jsonl_path.write_bytes, jsonl_bytes) uploaded = {"trajectory": _answer(await upload(request.objects.trajectory, snapshot_jsonl_path))} if request.objects.workspace is not None: uploaded["workspace"] = _answer(await upload(request.objects.workspace, archive_path)) + stats = {"file_count": file_count, "archive_seconds": round(archived - started, 3), + "upload_seconds": round(time.monotonic() - archived, 3)} except FileNotFoundError as exc: raise HTTPException(status_code=500, detail=str(exc)) from exc finally: archive_path.unlink(missing_ok=True) snapshot_jsonl_path.unlink(missing_ok=True) logger.info(f"Snapshot saved: context_id={context_id} session_id={session_id} files={file_count} " - f"bytes={bytes_written}") - return ObjectSnapshotSaveResponse.model_validate({"context_id": context_id, "objects": uploaded}) + f"bytes={bytes_written} archive_seconds={stats['archive_seconds']} " + f"upload_seconds={stats['upload_seconds']}") + return ObjectSnapshotSaveResponse.model_validate({"context_id": context_id, "objects": uploaded, "stats": stats}) @extension(SNAPSHOT_V1.load) async def load_snapshot(self, request: ObjectSnapshotLoadRequest) -> ObjectSnapshotLoadResponse: diff --git a/tst/unit/agents/claude_code/test_object_transfer.py b/tst/unit/agents/claude_code/test_object_transfer.py index c1ef005bc..b9cf80641 100644 --- a/tst/unit/agents/claude_code/test_object_transfer.py +++ b/tst/unit/agents/claude_code/test_object_transfer.py @@ -140,7 +140,7 @@ def test_a_snapshot_saves_and_loads_through_grants(monkeypatch, tmp_path, agent, json={"context_id": "ctx-1", "objects": {"trajectory": write_grant("snap/trajectory"), "workspace": write_grant("snap/workspace")}}, ).json() - assert set(saved) == {"context_id", "objects"} and saved["context_id"] == "ctx-1" + assert set(saved) == {"context_id", "objects", "stats"} and saved["context_id"] == "ctx-1" assert store.objects["snap/trajectory"] == conversation assert saved["objects"]["workspace"]["size_bytes"] == len(store.objects["snap/workspace"]) with tarfile.open(fileobj=io.BytesIO(store.objects["snap/workspace"]), mode="r:gz") as archive: diff --git a/tst/unit/agents/claude_code/test_workspace_snapshot.py b/tst/unit/agents/claude_code/test_workspace_snapshot.py index 568d13bc7..37e403808 100644 --- a/tst/unit/agents/claude_code/test_workspace_snapshot.py +++ b/tst/unit/agents/claude_code/test_workspace_snapshot.py @@ -144,13 +144,16 @@ def test_save_trims_an_incomplete_tail_takes_no_lock_and_uploads_the_bundle(monk monkeypatch.setattr(claude_bridge, "SESSION_JSONL_DIR", session_dir) agent.set_session_ref_for_context("ctx-1", session_id) uploads: list[dict] = [] + clock = [100.0] async def _upload(target, source): body = source.read_bytes() uploads.append({"target": target, "path": source, "body": body}) + clock[0] += 2.5 return Uploaded(size_bytes=len(body), sha256=hashlib.sha256(body).hexdigest()) monkeypatch.setattr(a2a_server, "upload", _upload) + monkeypatch.setattr(a2a_server.time, "monotonic", lambda: clock[0]) request = a2a_server.ObjectSnapshotSaveRequest.model_validate( {"context_id": "ctx-1", "objects": {"trajectory": write_grant("snap/trajectory"), "workspace": write_grant("snap/workspace")}} ) @@ -176,6 +179,7 @@ async def _save_while_a_turn_holds_the_lock(): "trajectory": {"size_bytes": len(uploads[0]["body"]), "sha256": hashlib.sha256(uploads[0]["body"]).hexdigest()}, "workspace": {"size_bytes": len(uploads[1]["body"]), "sha256": hashlib.sha256(uploads[1]["body"]).hexdigest()}, }, + "stats": {"file_count": 3, "archive_seconds": 0.0, "upload_seconds": 5.0}, } assert all(not upload["path"].exists() for upload in uploads)