Skip to content

feat(a2a-agent): an atif/1 turn index survives a restart, an eviction and a snapshot restore - #817

Merged
earakely-scale merged 6 commits into
mainfrom
edgararakelyan/y2b-turn-index
Nov 19, 2026
Merged

earakely-scale merged 6 commits into
mainfrom
edgararakelyan/y2b-turn-index

Conversation

@earakely-scale

@earakely-scale earakely-scale commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

The second of Y2b's three PRs for FD-6076: an atif/1 copy'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

  • The SDK keeps each context's turn count on disk, one small file per context under agentenv/turns/ in the user's state folder ($XDG_STATE_HOME when 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.
    • A restarted server, or a context dropped from memory, starts a new document of the same session. The first user step of that document carries the continuing turn index, as PROFILE.md already said it would.
    • A home that can't be written keeps the counts in memory, with one warning. A count file that can't be read counts from 0, with a warning.
    • Only an agent that serves atif/1 keeps a count.
  • A snapshot carries the count in a new optional state object 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.py only routes a save or load there for an agent that serves atif/1.
    • On save, the SDK uploads state after the agent's handler returns, and adds it to the answer's objects.
    • On load, the SDK reads state before 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.
    • While a save or load that carries state is 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, so SnapshotSeries' 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.
    • Agents' handlers never touch state. A state grant that isn't application/json is a 400. A stored state that isn't the SDK's is a 400 with code snapshot_state_invalid.
  • The card says when the SDK keeps state: the snapshot extension's params gain "state": ["turns"] (SNAPSHOT_STATE_PARAM) on an agent that serves atif/1.
  • agent-env grants state only to an agent whose card has it (A2AAgent.keeps_snapshot_state). An SDK that serves atif/1 but predates the object (protocol 0.1.60x) refuses it, so it gets neither grant.
    • snapshot_agent_state grants it on save. deploy_agent grants it on load when the capture holds a state object.
    • The capture's universe picks the object up through put_existing, as it does the others.
    • The save request is now dumped without 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

  • The count lives in the agent's container, not in agent-env. A fresh container has no counts, so the snapshot is what carries them across containers. An agent installed on this machine (host-mode install_agent on a local sandbox) runs in the user's own home, so its counts outlast the run: a task that fixes context_id would go on counting in the next run. FD-6359 gives such installs a state folder per sandbox, which teardown removes.
  • A restore starts a new document even into a context the agent already holds, since the conversation is the snapshot's now; the count goes on from the snapshot's. A snapshot restored into a new context id starts a new session, as PROFILE.md says.
  • A changelog rewind (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.
  • A capture mid-task counts the running task. It started before the capture, so a restore of it numbers the next task after it, even though the conversation holds only part of that turn. Only task starts are held, and only when the SDK keeps state, so other agents' snapshots behave as before.
  • A load into a context whose task is running doesn't wait for it. The SDK holds only task starts. Restoring a conversation under a running turn is the agent's handler's concern, as it is today, and agent-env loads only into freshly deployed agents.
  • A failed state transfer fails the save or the load. agent-env grants state only 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):

    • a restarted server goes on counting in a new document of the same session;
    • an evicted context goes on counting;
    • a snapshot carries the count to a fresh agent, restored into a new context;
    • a restore into a held context starts a new document;
    • an agent without atif/1 writes no state;
    • a state grant must be JSON, and a stored state that isn't the SDK's is refused;
    • the counts live in $XDG_STATE_HOME, or ~/.local/state when it's unset or relative;
    • an unwritable folder keeps the counts in memory, with one warning; an unreadable count file counts from 0, with a warning;
    • two servers on one home share its counts;
    • the card names the state only on an agent that serves atif/1;
    • a task sent while a save handler is paused waits for the save, so the saved count is 2 and the task's turn is 2 (it fails without the hold);
    • a save while a task runs is answered without waiting for the task, and counts it;
    • a load into a context whose save is paused waits for the save, so the save keeps its count (it fails without the serialization).

    tests/conftest.py gives 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;
    • the save grants state only to an agent that keeps one, with no null anywhere in the request;
    • the load grants the stored state only 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.py runs deploy_agent → two prompts → snapshot_agent_state → deploy_agent from the snapshot into a new context → a prompt. It checks:

    • the capture's state is {"turns": 2};
    • the restored agent's atif/1 user 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):

    • On the vm host: 25 min on cfe13f4 (113,321 seeds, 425,121 tasks, 42,154 restarts, 42,481 restores) and 5 min on 8195785 (22,830 seeds, 8,460 restarts, 8,648 restores), no failures. The integration tests passed there on every commit.
    • 60 s locally: 4,461 seeds, 1,674 restarts and 1,601 restores, no failures; again on the review fixes: 3,943 seeds, 1,537 restarts, 1,437 restores, no failures.
    • It catches both planted bugs: counts not written to disk, and a restore that doesn't seed the count.
  • All 1,982 protocol tests and the 4,139 tst/unit/a2a_agent and tst/unit/task_step tests pass, and ruff check . passes.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence 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.

  • ATIF turn numbers keep going after a server restart or context eviction.
  • Restored ATIF documents continue from the snapshot's turn count.

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

… 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
earakely-scale marked this pull request as ready for review November 19, 2026 17:33
@earakely-scale
earakely-scale requested a review from a team as a code owner 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>
earakely-scale and others added 3 commits November 19, 2026 10:20
…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>
@earakely-scale
earakely-scale merged commit dfed7e5 into main Nov 19, 2026
36 of 37 checks passed
@earakely-scale
earakely-scale deleted the edgararakelyan/y2b-turn-index branch November 19, 2026 19:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant