Skip to content
Open
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 @@ -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?}` |
Expand All @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,7 @@
SkillBundle,
SkillBundleFile,
SnapshotReadObjects,
SnapshotSaveStats,
SnapshotUploadedObjects,
SnapshotWriteObjects,
TaskEventsTrajectoryRequest,
Expand Down Expand Up @@ -229,6 +230,7 @@
"SkillBundle",
"SkillBundleFile",
"SnapshotReadObjects",
"SnapshotSaveStats",
"SnapshotUploadedObjects",
"SnapshotWriteObjects",
"StagingStore",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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):
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 @@ -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"],
Expand Down
72 changes: 63 additions & 9 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 collections.abc import Mapping
Expand All @@ -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,
Expand Down Expand Up @@ -97,15 +99,67 @@ 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",
Comment thread
andrewpark-scaleai marked this conversation as resolved.
Resolved
"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
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
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 @@ -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"]}},
}
Expand Down
2 changes: 1 addition & 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
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 @@ -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",
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 @@ -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
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 @@ -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",
Expand Down
75 changes: 75 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,78 @@ 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


@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")
Loading