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/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/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/src/agent_env/agents/agents/claude-code/requirements.txt b/src/agent_env/agents/agents/claude-code/requirements.txt index 464574902..d154d2b60 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 that serves peer-agents/v1's tools, which -# the agent advertises without handlers of its own; raise it when the agent needs a newer protocol. -agentenv-framework-protocol[agent]>=0.1.351 +# image is built again only when this folder changes. The floor is the first whose snapshot save response takes the +# stats the agent reports; raise it when the agent needs a newer protocol. +agentenv-framework-protocol[agent]>=0.1.551 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. 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_image_contract.py b/tst/unit/agents/claude_code/test_image_contract.py index 6445b09d6..843feb5f8 100644 --- a/tst/unit/agents/claude_code/test_image_contract.py +++ b/tst/unit/agents/claude_code/test_image_contract.py @@ -23,7 +23,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.351"] + assert requirements == ["agentenv-framework-protocol[agent]>=0.1.551"] 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 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 ff0b29607..37e403808 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"]}, } @@ -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) 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