Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions packages/agentenv-protocol/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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?}` |
Expand All @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@
SkillBundle,
SkillBundleFile,
SnapshotReadObjects,
SnapshotSaveStats,
SnapshotUploadedObjects,
SnapshotWriteObjects,
TaskEventsTrajectoryRequest,
Expand Down Expand Up @@ -225,6 +226,7 @@
"SkillBundle",
"SkillBundleFile",
"SnapshotReadObjects",
"SnapshotSaveStats",
"SnapshotUploadedObjects",
"SnapshotWriteObjects",
"StagingStore",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down
2 changes: 1 addition & 1 deletion packages/agentenv-protocol/tests/test_a2a_agent.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"],
Expand Down
10 changes: 8 additions & 2 deletions src/agent_env/agents/agents/claude-code/a2a_server.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
import stat
import tarfile
import tempfile
import time
import uuid
from collections.abc import AsyncIterator, Iterable
from contextlib import asynccontextmanager
Expand Down Expand Up @@ -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:
Expand Down
6 changes: 3 additions & 3 deletions src/agent_env/agents/agents/claude-code/requirements.txt
Original file line number Diff line number Diff line change
@@ -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
54 changes: 46 additions & 8 deletions src/agent_env/task_step/snapshot_utils/agent_state_capture.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
import asyncio
import json
import logging
import time
import uuid
from dataclasses import dataclass
from typing import Any, Optional
Expand All @@ -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,
Expand Down Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion tst/unit/agents/claude_code/test_card_contract.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"]}},
}
Expand Down
2 changes: 1 addition & 1 deletion tst/unit/agents/claude_code/test_image_contract.py
Original file line number Diff line number Diff line change
Expand Up @@ -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():
Expand Down
2 changes: 1 addition & 1 deletion tst/unit/agents/claude_code/test_object_transfer.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
6 changes: 5 additions & 1 deletion tst/unit/agents/claude_code/test_workspace_snapshot.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"]},
}


Expand Down Expand Up @@ -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")}}
)
Expand All @@ -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)

Expand Down
2 changes: 1 addition & 1 deletion tst/unit/agents/codex/test_card_contract.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
2 changes: 1 addition & 1 deletion tst/unit/agents/codex/test_object_transfer.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion tst/unit/agents/gemini/test_card_contract.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
57 changes: 57 additions & 0 deletions tst/unit/task_step/test_agent_state_capture.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading