Repository navigation
feat(a2a-agent): an atif/1 turn index survives a restart, an eviction and a snapshot restore - #817
Merged
Merged
Conversation
… and a snapshot restore The SDK keeps each context's count of started tasks on disk, under ~/.local/state/agentenv/turns/, so a restarted server or a context dropped from memory goes on counting in a new document of the same session. A snapshot carries the count in an optional `state` object, JSON and the SDK's own: uploaded after the agent's save handler, read before its load handler, seeding the context it restored into. agent-env grants it only to an agent whose card lists atif/1, and dumps the save request without nulls, so a pinned agent's request model still accepts it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
earakely-scale
marked this pull request as ready for review
November 19, 2026 17:33
…it, and take it between turns
An SDK that serves atif/1 but predates the snapshot's state object refuses it, so the
card's snapshot extension now names the state the SDK keeps ("state": ["turns"]), and
agent-env grants the object only then (A2AAgent.keeps_snapshot_state). A save or load
that carries the state holds the context's lock, the one a task holds while it runs, so
no task starts between the agent's capture and the count. TurnIndex keeps no cache of
written counts: each read is the context's file, so memory holds nothing per context and
two servers on one home agree; an unreadable file counts from 0 with a warning.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…sk starts Holding the context's lock made a capture mid-task (SnapshotSeries) wait for the running task to end. A save or load that carries the SDK's state now holds only task starts in its context while the agent's handler runs (_SnapshotsInFlight); a running task goes on, and the count it saves includes it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…time A load into a context could restore an older count while a save of it waited on its upload, and the save then stored that count beside its newer conversation. Snapshots that carry the SDK's state now take a per-context turn in _SnapshotsInFlight, still holding only task starts. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The SDK kept its turn counts under ~/.local/state whatever XDG_STATE_HOME said. They now go in agentenv/turns of $XDG_STATE_HOME when it's an absolute path, as the XDG spec has it, else ~/.local/state, resolved when an app's TurnIndex is made, so a host that gives an agent its own state folder keeps its counts there. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
_snapshot_state.SnapshotStates holds what the SDK adds to an agent's snapshots: the wire model and its card param, save and load as typed methods, and the gate that holds a context's task starts while one is in flight. framework.py only routes to it, and only for an agent that serves atif/1. _turn_index keeps its own count-file model instead of reading the snapshot wire model, and TaskTrajectories drops a parameter nothing passed. The turn tests share save and load helpers. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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.
The second of Y2b's three PRs for FD-6076: an
atif/1copy's turn index survives what the copy doesn't, so a context's documents go on counting across a restarted agent server, a context evicted from memory, and a snapshot restored into a fresh agent (Y2b-2). Part of FD-6076. Scrubbing (Y2b-4) follows in its own PR.What changes
agentenv/turns/in the user's state folder ($XDG_STATE_HOMEwhen it's absolute, as the XDG spec has it, else~/.local/state), named by the context id's sha256 (_turn_index.TurnIndex). Every read goes to the file, so memory holds nothing per context and two servers on one home agree.atif/1keeps a count.stateobject on snapshot save and load. It is JSON ({"turns": n},SnapshotState) and belongs to the SDK. Y2b-2 chose B: no caller has to pass the count. All of it is in_snapshot_state.py(SnapshotStates);framework.pyonly routes a save or load there for an agent that servesatif/1.stateafter the agent's handler returns, and adds it to the answer'sobjects.statebefore the agent's handler runs. Once the handler has restored a context, the SDK seeds that context with the count, and drops its in-memory copy, so the context's next task starts a new document.stateis in flight, a task of its context waits to start until the agent's handler returns, so the count is the conversation's the agent captured. A task already running goes on, soSnapshotSeries' captures mid-task are answered as before. Such snapshots of one context run one at a time, so a load can't change the count a save is about to read.state. Astategrant that isn'tapplication/jsonis a 400. A stored state that isn't the SDK's is a 400 with codesnapshot_state_invalid."state": ["turns"](SNAPSHOT_STATE_PARAM) on an agent that servesatif/1.stateonly to an agent whose card has it (A2AAgent.keeps_snapshot_state). An SDK that servesatif/1but predates the object (protocol 0.1.60x) refuses it, so it gets neither grant.snapshot_agent_stategrants it on save.deploy_agentgrants it on load when the capture holds astateobject.put_existing, as it does the others.Nones, as the load request already was, so an agent on an older protocol, whose request models forbid unknown fields, still accepts it.Choices to review
install_agenton a local sandbox) runs in the user's own home, so its counts outlast the run: a task that fixescontext_idwould go on counting in the next run. FD-6359 gives such installs a state folder per sandbox, which teardown removes.apply-changelog) doesn't carry a count. It isn't a snapshot load, and nothing in Y2b asks for it; the rewound context keeps the count of the container it lands in.statetransfer fails the save or the load. agent-env grantsstateonly when it exists, so a failure there is a broken transfer, which should be loud.Testing
tests/test_a2a_atif_turns.py(17 tests, new):atif/1writes no state;stategrant must be JSON, and a stored state that isn't the SDK's is refused;$XDG_STATE_HOME, or~/.local/statewhen it's unset or relative;atif/1;tests/conftest.pygives each test its own turns folder.tst/unit/a2a_agent/snapshot_state_test.py(8 cases, new), against real SDK cards and one with the state param removed, as an SDK from before it has:keeps_snapshot_state;stateonly to an agent that keeps one, with nonullanywhere in the request;stateonly when the capture has one and the agent keeps one.Integration: the echo agent gains snapshot save and load handlers. The file's 3 tests passed on the vm host (x86; the echo image is amd64-only). A new test in
test_prompt_agent_live_trajectory_local.pyrunsdeploy_agent→ two prompts →snapshot_agent_state→deploy_agentfrom the snapshot into a new context → a prompt. It checks:stateis{"turns": 2};atif/1user step carries turn 2, in a new document of the new session.Serving chaos (the PR 1 harness, now also restarting the server or restoring a snapshot after each context, each seed in its own turns folder):
All 1,982 protocol tests and the 4,139
tst/unit/a2a_agentandtst/unit/task_steptests pass, andruff check .passes.🤖 Generated with Claude Code


Confidence Score: 5/5
The reviewed changes appear safe to merge; no new blocking issues were found.Summary
This PR keeps ATIF turn counts across server restarts, memory eviction, and snapshot restores.
The previous findings are addressed. No new actionable issues were found in the changes since the last review.
Reviews (10) · Last reviewed commit: "refactor(a2a-agent): the SDK's snapshot ..." · Reviewed by Greptile