Repository navigation
feat(snapshot): the save response takes optional stats, and agent-env logs each save - #697
Open
andrewpark-scaleai wants to merge 3 commits into
Open
andrewpark-scaleai wants to merge 3 commits into
andrewpark-scaleai wants to merge 3 commits into
Conversation
andrewpark-scaleai
force-pushed
the
andrew-park/rel-snapshot-save-telemetry
branch
from
November 16, 2026 18:05
0081850 to
5515f7b
Compare
andrewpark-scaleai
force-pushed
the
andrew-park/rel-snapshot-save-telemetry
branch
from
November 18, 2026 18:20
5515f7b to
c98261a
Compare
andrewpark-scaleai
marked this pull request as ready for review
November 18, 2026 18:37
andrewpark-scaleai
force-pushed
the
andrew-park/rel-snapshot-save-telemetry
branch
from
November 18, 2026 18:53
c98261a to
35f6dc0
Compare
…s in agent-env's logs Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
… 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 <noreply@anthropic.com>
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.
andrewpark-scaleai
force-pushed
the
andrew-park/rel-snapshot-save-telemetry
branch
from
November 18, 2026 23:11
35f6dc0 to
bd5d058
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The goal is that every failure of an agent run leaves enough in the logs to debug it, and that code heals what it can. When a
snapshot_agent_statesave is slow, agent-env's logs cannot say why. The agent logs its archive's file count and size, but that line stays in the sandbox. agent-env logs nothing about the save on success, and only the exception on a timeout. So a slow save cannot be told apart as "the workspace is big", "archiving is slow" or "the upload is slow" without reaching into a live sandbox.What changed
ObjectSnapshotSaveResponsegains an optionalstatsfield:file_count,archive_secondsandupload_seconds(SnapshotSaveStats).capture_workspacelogsevent=snapshot_save_completedwithagent_name,context_id,elapsed_seconds,timeout_seconds,workspace_archive_bytes(from the uploaded object) and the three stats.event=snapshot_save_timeoutwith the elapsed time, the budget and the workspace grant's cap, then re-raises.event=snapshot_save_cancelledwith the elapsed time and the budget, then re-raises. A periodic capture's outerwait_forshares the save's budget and starts first, so a stalled periodic save ends here, not in httpx's timeout.statsunder the save response's optional fields, so the card tests for claude-code, codex and gemini expect it.Design decisions
statsin the claude-code agent and raised its floor in the same change, so the image could not find a protocol with the field and every claude-code integration test errored. The agent validates its own answer against its installed protocol, which rejects an unknown field, so the agent change cannot work against a published protocol without a shim. This PR now ships the protocol field and agent-env's logging. The tradeoff is one release of lag: until the follow-up merges, claude-code saves log their size and elapsed time withnullstats.stats, which is every agent image until the follow-up, logs them asnull.test_a_completed_save_from_an_agent_that_reports_no_stats_logs_its_sizepins that.Scope
statsyet. Does not change any timeout or retry.Blast Radius
Adds one log line per save, or one on a timeout or cancel, and one optional response field. It changes the advertised snapshot/v1 card (an added optional field). No control flow changes.
Verification
uv run --extra dev pytest tst/unit/task_step/test_agent_state_capture.py tst/unit/agents/claude_code/test_card_contract.py tst/unit/agents/claude_code/test_workspace_snapshot.py tst/unit/agents/claude_code/test_object_transfer.py tst/unit/agents/claude_code/test_image_contract.py tst/unit/agents/codex/test_card_contract.py tst/unit/agents/codex/test_object_transfer.py tst/unit/agents/gemini/test_card_contract.py packages/agentenv-protocol/tests/test_a2a_agent.py -q: 224 passed.tst/unit/task_step/test_agent_state_capture.py, thetst/unit/task_step/*snapshot*.pyfiles, the three card tests andtest_a2a_agent.py: 399 passed.tst/unit/agents/: 1023 passed.@event:snapshot_save_completed,@event:snapshot_save_timeoutand@event:snapshot_save_cancelled.

Confidence Score: 5/5
This PR appears safe to merge.Summary
Adds optional snapshot-save statistics and logs save completion, HTTP timeouts, and caller cancellation without changing the save budget or retries.
The earlier missing cancellation-log issue is addressed. No new actionable issues found. Agents in this PR do not report statistics yet; Claude Code reporting remains in follow-up PR #711.
Reviews (5) · Last reviewed commit: "fix(snapshot): log a save the caller's d..." · Reviewed by Greptile