From cfe13f41a120747cd9b7361d46f257381ab19761 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Thu, 19 Nov 2026 09:17:49 -0800 Subject: [PATCH 1/6] feat(a2a-agent): an atif/1 turn index survives a restart, an eviction 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 --- packages/agentenv-protocol/README.md | 16 +- .../a2a_agent/_trajectory_log.py | 21 +- .../a2a_agent/_turn_index.py | 73 ++++++ .../agentenv_protocol/a2a_agent/extensions.py | 10 + .../agentenv_protocol/a2a_agent/framework.py | 49 +++- .../src/agentenv_protocol/atif/PROFILE.md | 6 +- packages/agentenv-protocol/tests/conftest.py | 10 + .../tests/test_a2a_atif_serving.py | 5 +- .../tests/test_a2a_atif_turns.py | 209 ++++++++++++++++++ src/agent_env/a2a_agent/a2a_agent.py | 8 + src/agent_env/a2a_agent/object_transfer.py | 32 ++- .../snapshot_utils/agent_state_capture.py | 1 + .../task_step/task_steps/deploy_agent.py | 1 + tst/data/a2a_agent/agent.py | 26 +++ .../agent/a2a_agent/a2a_agent_test.py | 2 +- ...test_prompt_agent_live_trajectory_local.py | 57 ++++- tst/unit/a2a_agent/snapshot_state_test.py | 122 ++++++++++ 17 files changed, 630 insertions(+), 18 deletions(-) create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_turn_index.py create mode 100644 packages/agentenv-protocol/tests/conftest.py create mode 100644 packages/agentenv-protocol/tests/test_a2a_atif_turns.py create mode 100644 tst/unit/a2a_agent/snapshot_state_test.py diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index d359234ed..e5a9e32e8 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1648,6 +1648,18 @@ Every `atif/1` answer names `schema_version` and `profile_version` beside copy's reads then answer HTTP 409 with code `atif_unavailable`, and native reads are unaffected. +Each task's user step carries its turn index, the number of tasks its context +started before it. The SDK keeps each context's count on disk, under +`~/.local/state/agentenv/turns/`, so a restarted server, or a context it dropped +from memory, goes on counting in a new document of the same session; a home it +can't write keeps the counts in memory, with one warning. A snapshot carries the +count in its `state` object, a JSON object that is the SDK's own: on save the +SDK uploads it after the agent's handler returns and adds it to the answer, and +on load it reads it before the agent's handler runs and seeds the context the +handler restored into, whose next task goes on from the snapshot's count in a +new document. The agent's handlers leave `state` alone, and agent-env grants it +only to an agent whose card lists `atif/1`. + `enable(..., description="...")` is reserved for declarations carrying configuration or metadata. It preserves the agent-specific extension prose published in the Agent Card. The versioned SDK definition provides a generic @@ -1783,7 +1795,9 @@ counterpart. Without them, or `enable(TRAJECTORY_V1, live=True)`, the generated card advertises only the framework-owned completed-task variants: `{task_id}`, answered inline, and `{task_id, objects}`, answered by upload. Snapshot `save` and `load` are an atomic core contract, while its optional -changelog handlers are enabled as an atomic feature group. +changelog handlers are enabled as an atomic feature group. A snapshot's optional +`state` object is the SDK's own, which its handlers leave alone (see +[Serving ATIF](#serving-atif-atif1)). Each operation has at most one response model. The framework validates a handler's return value against it before serializing, so a response with a missing or unknown field is an HTTP 500. diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_trajectory_log.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_trajectory_log.py index ba107b17d..5a158262f 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_trajectory_log.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_trajectory_log.py @@ -10,6 +10,7 @@ from ..atif import Adapter, AuxEntry, ServedTurn from ._atif_copy import AtifCopy, AtifPage, TurnStart +from ._turn_index import TurnIndex from .extensions import TrajectoryState from .tasks.v1 import TaskError, TrajectoryLog @@ -86,12 +87,14 @@ def __init__( *, native: str | None = None, atif: type[Adapter] | None = None, + turns: TurnIndex | None = None, ) -> None: if max_contexts < 1: raise ValueError("max_contexts must be positive") self._max_contexts = max_contexts self._native = native self._atif = atif + self._turns = turns if turns is not None else TurnIndex() if atif is not None else None self._tasks: dict[str, _TaskRecord] = {} self._contexts: OrderedDict[str, list[str]] = OrderedDict() self._copies: dict[str, AtifCopy] = {} @@ -111,7 +114,8 @@ def register(self, task_id: str, context_id: str) -> TrajectoryLog: def start(self, task_id: str, turn: TurnStart | None = None) -> None: """Place the task after the context's started tasks, as it begins to run, and open it in - the context's atif/1 copy, its turn index the number of tasks that started before it. + the context's atif/1 copy, its turn index the number of tasks the context started before + it, which a restart, an eviction or a restore doesn't reset. Only tasks that have not started move; they have no events, so no position shifts.""" record = self._tasks[task_id] @@ -122,14 +126,25 @@ def start(self, task_id: str, turn: TurnStart | None = None) -> None: started = sum(1 for other in order if self._tasks[other].started) order.insert(started, task_id) record.started = True - if self._atif is not None and turn is not None: + if self._atif is not None and self._turns is not None and turn is not None: copy = self._copies.get(record.context_id) if copy is None: copy = self._copies[record.context_id] = AtifCopy(self._atif, record.context_id) - copy.start(task_id, started, turn) + copy.start(task_id, self._turns.next(record.context_id), turn) record.log._atif = _CopySink(copy, task_id) self._touch(record.context_id) + def turns(self, context_id: str) -> int: + """How many tasks the context has started, the count a snapshot of it carries.""" + return self._turns.count(context_id) if self._turns is not None else 0 + + def restored(self, context_id: str, turns: int) -> None: + """A snapshot was restored into the context: its count goes on from the snapshot's, and its next task starts a + new document, since the conversation is the snapshot's now.""" + if self._turns is not None: + self._turns.set(context_id, turns) + self._copies.pop(context_id, None) + def request_cancel(self, task_id: str) -> None: """Make ``canceled`` the outcome the task is sealed with, whatever ``run`` returns.""" record = self._tasks.get(task_id) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_turn_index.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_turn_index.py new file mode 100644 index 000000000..982835436 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_turn_index.py @@ -0,0 +1,73 @@ +"""Each A2A context's turn count, kept on disk by the SDK, so a restarted server, or a context evicted from memory, goes +on counting where it was, and a snapshot carries it to the context it is restored into. Only an agent that serves +atif/1 keeps one: the count is its ATIF copy's turn index.""" + +from __future__ import annotations + +import hashlib +import json +import logging +import os +from pathlib import Path + +from pydantic import BaseModel, ConfigDict, Field + +logger = logging.getLogger(__name__) + +#: Where the counts are kept, one small file per context, under the agent's user's home. +TURNS_DIR = Path.home() / ".local" / "state" / "agentenv" / "turns" + + +class SnapshotState(BaseModel): + """What the SDK keeps in a snapshot beside the agent's own objects: the context's turn count. A newer SDK may add + fields, which an older one reading the snapshot leaves alone.""" + + model_config = ConfigDict(extra="ignore", frozen=True) + + turns: int = Field(ge=0) + + +class TurnIndex: + """Each context's count of started tasks. A count that can't be written stays in memory, with a warning, so a + read-only home costs only the count's survival across a restart.""" + + def __init__(self, folder: Path | None = None) -> None: + self._folder = folder if folder is not None else TURNS_DIR + self._counts: dict[str, int] = {} + self._warned = False + + def next(self, context_id: str) -> int: + """The starting task's turn index, the number of tasks the context started before it, counting this one.""" + index = self.count(context_id) + self.set(context_id, index + 1) + return index + + def count(self, context_id: str) -> int: + if context_id not in self._counts: + try: + self._counts[context_id] = json.loads(self._path(context_id).read_text())["turns"] + except FileNotFoundError: + self._counts[context_id] = 0 + except OSError as exc: + self._warn(exc) + self._counts[context_id] = 0 + return self._counts[context_id] + + def set(self, context_id: str, count: int) -> None: + self._counts[context_id] = count + path = self._path(context_id) + try: + path.parent.mkdir(parents=True, exist_ok=True) + part = path.with_suffix(".part") + part.write_text(json.dumps({"context_id": context_id, "turns": count})) + os.replace(part, path) + except OSError as exc: + self._warn(exc) + + def _path(self, context_id: str) -> Path: + return self._folder / f"{hashlib.sha256(context_id.encode()).hexdigest()}.json" + + def _warn(self, exc: OSError) -> None: + if not self._warned: + self._warned = True + logger.warning("turn counts are kept in memory only, so a restart starts them again: %s", exc) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/extensions.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/extensions.py index 50deffab4..8de0a8f16 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/extensions.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/extensions.py @@ -290,12 +290,18 @@ def _opaque_snapshot_objects( descriptor = getattr(objects, name) if descriptor is not None and descriptor.media_type != "application/octet-stream": raise ValueError(f"snapshot {name} media_type must be application/octet-stream") + if objects.state is not None and objects.state.media_type != "application/json": + raise ValueError("snapshot state media_type must be application/json") return objects class SnapshotWriteObjects(ExtensionRequest): + """Where a snapshot is saved: the agent's ``trajectory`` and ``workspace``, and ``state``, the SDK's own (an agent + that serves atif/1 keeps its turn count there), which the SDK writes after the agent's handler.""" + trajectory: WriteObject workspace: WriteObject | None = None + state: WriteObject | None = None _opaque_media_types = model_validator(mode="after")(_opaque_snapshot_objects) @@ -306,8 +312,11 @@ class ObjectSnapshotSaveRequest(ExtensionRequest): class SnapshotReadObjects(ExtensionRequest): + """What a snapshot is loaded from; ``state`` is the SDK's, read before the agent's handler runs.""" + trajectory: ReadObject workspace: ReadObject | None = None + state: ReadObject | None = None _opaque_media_types = model_validator(mode="after")(_opaque_snapshot_objects) @@ -320,6 +329,7 @@ class ObjectSnapshotLoadRequest(ExtensionRequest): class SnapshotUploadedObjects(ExtensionResponse): trajectory: Uploaded workspace: Uploaded | None = None + state: Uploaded | None = None class ObjectSnapshotSaveResponse(ExtensionResponse): diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py index 032771f91..d81dbcbab 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py @@ -8,6 +8,7 @@ import json import logging import os +import tempfile import uuid from collections import OrderedDict from collections.abc import Callable, Iterable, Mapping @@ -34,6 +35,7 @@ from ..atif import PROFILE_VERSION as ATIF_PROFILE_VERSION from ..atif import SCHEMA_VERSION as ATIF_SCHEMA_VERSION from ._atif_copy import TurnStart +from ._turn_index import SnapshotState from ._trajectory_log import MAX_TRAJECTORY_READ_BYTES, TaskTrajectories from ._triggers import TriggerEngine, TriggerError from .extensions import ( @@ -43,6 +45,7 @@ MCP_CONFIG_V1, PEER_AGENTS_V1, SKILL_CONFIG_V1, + SNAPSHOT_V1, TRAJECTORY_V1, TRIGGERS_V1, CLOCK_V1, @@ -55,6 +58,8 @@ ExtensionActivation, ExtensionDefinition, ImplementationOwner, + ObjectSnapshotLoadRequest, + ObjectSnapshotSaveRequest, McpAddRequest, OperationReference, PeerAgentsSetRequest, @@ -98,7 +103,7 @@ from .tasks.v1 import ( TextPart as TaskTextPart, ) -from ..transfers import TransferError, serving_on, upload +from ..transfers import TransferError, download, serving_on, upload logger = logging.getLogger(__name__) @@ -942,6 +947,40 @@ async def _atif_document( ) return AtifObjectsResponse(objects=uploaded, **versions).model_dump(mode="json", exclude_none=True) + async def read_snapshot_state(self, request: Any) -> SnapshotState | None: + """Before an agent's snapshot load: the SDK's state the snapshot carries, read through + its ``state`` grant, which only an agent that serves atif/1 is sent.""" + if not (self.serves_atif and isinstance(request, ObjectSnapshotLoadRequest) + and request.objects.state is not None): + return None + with tempfile.TemporaryDirectory() as folder: + path = Path(folder) / "state.json" + await download(request.objects.state, path) + try: + return SnapshotState.model_validate_json(path.read_bytes()) + except ValidationError as exc: + raise AgentEnvError( + "snapshot_state_invalid", + f"the snapshot's state object isn't the SDK's snapshot state: {exc.errors()[0]['msg']}", + status=400, + ) from exc + + def restore_snapshot_state(self, state: SnapshotState | None, answer: Mapping[str, Any]) -> None: + """After the load: the context the agent restored into goes on counting from the + snapshot's turn count.""" + if state is not None: + self.task_trajectories.restored(str(answer["context_id"]), state.turns) + + async def write_snapshot_state(self, request: Any, answer: dict[str, Any]) -> dict[str, Any]: + """After an agent's snapshot save: the SDK's state, the context's turn count, uploaded + through the request's ``state`` grant and named among the answer's objects.""" + if not (self.serves_atif and isinstance(request, ObjectSnapshotSaveRequest) + and request.objects.state is not None): + return answer + state = SnapshotState(turns=self.task_trajectories.turns(request.context_id)) + uploaded = await upload(request.objects.state, state.model_dump_json().encode()) + return {**answer, "objects": {**answer["objects"], "state": uploaded.model_dump(mode="json", exclude_none=True)}} + def check_trajectory_format(self, format: str | None) -> None: """Refuse a trajectory read naming a format the card doesn't offer, before any handler runs, the agent's own included.""" @@ -1381,6 +1420,14 @@ async def invoke_and_validate() -> Any: ): async with self.services.skill_registration(input_payload): result = await invoke_and_validate() + elif extension_uri == SNAPSHOT_V1.uri and operation.definition.name == "load": + state = await self.services.read_snapshot_state(extension_request) + result = await invoke_and_validate() + self.services.restore_snapshot_state(state, result) + elif extension_uri == SNAPSHOT_V1.uri and operation.definition.name == "save": + result = await self.services.write_snapshot_state( + extension_request, await invoke_and_validate() + ) else: result = await invoke_and_validate() return JSONResponse(result) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md b/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md index 41fff3053..bab883ace 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md @@ -23,13 +23,13 @@ to native exactly. - One document per agent per A2A context. Each A2A task starts at a `source: user` step that holds the inbound message, with the task's ids in that step's profile. Steps number from 1 across the whole document. -- A context's record may span several documents: after an agent instance restarts, after a snapshot restore, and when - long runs are sealed into segments. They share `session_id`, the first user step of each carries the continuing turn +- A context's record may span several documents: after an agent instance restarts or drops the context from memory, + after a snapshot restore, and when long runs are sealed into segments. They share `session_id`, the first user step of each carries the continuing turn index, and each earlier document names the next in `continued_trajectory_ref`. The worker that stores the earlier document sets that link, since the agent that wrote it may be gone. - `session_id` is the A2A context id, and a served document's `trajectory_id` names that one document of the context's record. A snapshot restored into a new context id starts a new session, since one snapshot can be loaded - many times. + many times; its turn index goes on from the snapshot's. - A sub-agent is an embedded trajectory in `subagent_trajectories`, with its own steps, referenced from the spawning call's result by `subagent_trajectory_ref`. It belongs to the task of the call that spawned it. A sub-agent that wrote no step is left out, and so is the reference to it. A spawning call with no result when its task ends gets diff --git a/packages/agentenv-protocol/tests/conftest.py b/packages/agentenv-protocol/tests/conftest.py new file mode 100644 index 000000000..7aff4f960 --- /dev/null +++ b/packages/agentenv-protocol/tests/conftest.py @@ -0,0 +1,10 @@ +"""Each test keeps its agents' turn counts in its own folder: the SDK keeps them under the user's home, where one test's +contexts would go on counting from another's.""" +import pytest + +from agentenv_protocol.a2a_agent import _turn_index + + +@pytest.fixture(autouse=True) +def _own_turn_counts(tmp_path_factory, monkeypatch): + monkeypatch.setattr(_turn_index, "TURNS_DIR", tmp_path_factory.mktemp("turns")) diff --git a/packages/agentenv-protocol/tests/test_a2a_atif_serving.py b/packages/agentenv-protocol/tests/test_a2a_atif_serving.py index 2f7ba9715..873a76a9d 100644 --- a/packages/agentenv-protocol/tests/test_a2a_atif_serving.py +++ b/packages/agentenv-protocol/tests/test_a2a_atif_serving.py @@ -28,6 +28,7 @@ extension, framework, ) +from agentenv_protocol.a2a_agent import _turn_index from agentenv_protocol.a2a_agent import clock as agent_clock from agentenv_protocol.computer import clock as follower from agentenv_protocol.atif import ( @@ -332,7 +333,7 @@ def test_enable_refuses_an_adapter_that_doesnt_fit(arguments: dict[str, Any], er enable(TRAJECTORY_V1, **arguments) -def test_every_read_serves_both_formats_and_names_its_format(monkeypatch: pytest.MonkeyPatch) -> None: +def test_every_read_serves_both_formats_and_names_its_format(monkeypatch: pytest.MonkeyPatch, tmp_path) -> None: uploaded: list[bytes] = [] async def capture(_target: Any, body: bytes) -> Uploaded: @@ -349,6 +350,8 @@ async def capture(_target: Any, body: bytes) -> Uploaded: {"task_id": task_id}, {"context_id": "ctx-1"}, {"task_id": task_id, "after": 0}, {"context_id": "ctx-1", "after": 0}, {"task_id": task_id, "objects": {"trajectory": _grant()}})] native_bodies.append(json.loads(json.dumps(bodies).replace(task_id, "TASK"))) + # Another agent's container, whose turn counts aren't the first one's. + monkeypatch.setattr(_turn_index, "TURNS_DIR", tmp_path / "another-container") with TestClient(_toy().create_app()) as client: task_id = _send(client, "work t1", "m-1") _ended(client, task_id) diff --git a/packages/agentenv-protocol/tests/test_a2a_atif_turns.py b/packages/agentenv-protocol/tests/test_a2a_atif_turns.py new file mode 100644 index 000000000..79e051aba --- /dev/null +++ b/packages/agentenv-protocol/tests/test_a2a_atif_turns.py @@ -0,0 +1,209 @@ +"""An atif/1 copy's turn index survives what the copy doesn't: a restarted server, a context evicted from memory, and a +snapshot restored into a fresh agent, each of which starts a new document that goes on counting.""" +from __future__ import annotations + +import json +import logging +from datetime import datetime, timedelta, timezone +from pathlib import Path +from typing import Any + +import pytest +from starlette.testclient import TestClient +from test_a2a_atif_serving import NATIVE, Hooks, _atif, _ended, _Hold, _send, _turn + +from agentenv_protocol.a2a_agent import ( + SNAPSHOT_V1, + TRAJECTORY_V1, + AgentEnvAgent, + AgentIdentity, + ObjectSnapshotLoadRequest, + ObjectSnapshotLoadResponse, + ObjectSnapshotSaveRequest, + ObjectSnapshotSaveResponse, + SnapshotUploadedObjects, + TaskRequest, + TaskResult, + TextPart, + TrajectoryState, + Uploaded, + a2a_agent, + enable, + extension, + framework, +) +from agentenv_protocol.a2a_agent import _turn_index +from agentenv_protocol.a2a_agent._atif_copy import TurnStart +from agentenv_protocol.a2a_agent._trajectory_log import TaskTrajectories +from agentenv_protocol.atif import errors_in, validate + +_IDENTITY = AgentIdentity(name="toy-agent", description="test", version="2.0") + + +def _snapshotting(*, atif: Any = Hooks) -> AgentEnvAgent: + """The toy agent with a snapshot extension of its own, whose save and load the SDK's state rides beside.""" + extensions = (enable(TRAJECTORY_V1, live=True, native=NATIVE, **({"atif": atif} if atif else {})),) + + @a2a_agent(identity=_IDENTITY, extensions=extensions) + class Snapshotting(AgentEnvAgent): + async def run(self, request: TaskRequest) -> TaskResult: + return await _turn(request, _Hold()) + + @extension(SNAPSHOT_V1.save) + async def save(self, request: ObjectSnapshotSaveRequest) -> ObjectSnapshotSaveResponse: + return ObjectSnapshotSaveResponse(context_id=request.context_id, + objects=SnapshotUploadedObjects(trajectory=Uploaded(size_bytes=12))) + + @extension(SNAPSHOT_V1.load) + async def load(self, request: ObjectSnapshotLoadRequest) -> ObjectSnapshotLoadResponse: + return ObjectSnapshotLoadResponse(context_id=request.target_context_id or "fork-1") + + return Snapshotting() + + +def _grant(kind: str, name: str, media_type: str) -> dict[str, Any]: + expires = (datetime.now(timezone.utc) + timedelta(hours=1)).isoformat(timespec="seconds").replace("+00:00", "Z") + access = "write" if kind == "http-put" else "read" + return {"media_type": media_type, "max_bytes": 100_000, + access: {"kind": kind, "url": f"https://objects.example.test/{name}", "expires_at": expires}} + + +def _users(document: dict[str, Any]) -> list[dict[str, Any]]: + return [step["extra"]["agentenv"] for step in document["steps"] if step["source"] == "user"] + + +@pytest.fixture +def objects(monkeypatch: pytest.MonkeyPatch) -> dict[str, bytes]: + """The object store the snapshot's grants name: uploads land here by name, and downloads read from it.""" + stored: dict[str, bytes] = {} + + async def upload(target, body: bytes) -> Uploaded: + stored[target.write.url.rsplit("/", 1)[-1]] = body + return Uploaded(size_bytes=len(body)) + + async def download(source, destination: Path) -> None: + destination.write_bytes(stored[source.read.url.rsplit("/", 1)[-1]]) + + monkeypatch.setattr(framework, "upload", upload) + monkeypatch.setattr(framework, "download", download) + return stored + + +def test_a_restarted_server_goes_on_counting_in_a_new_document_of_the_same_session() -> None: + with TestClient(_snapshotting().create_app()) as client: + for tag in ("t1", "t2"): + task_id = _send(client, f"work {tag}", f"m-{tag}") + _ended(client, task_id) + before = _atif(client, task_id=task_id)["trajectory"] + # The same container's home, a new process. + with TestClient(_snapshotting().create_app()) as client: + task_id = _send(client, "work t3", "m-t3") + _ended(client, task_id) + after = _atif(client, task_id=task_id)["trajectory"] + assert errors_in(validate(after)) == [] + assert [user["turn"] for user in _users(before)] == [0, 1] + assert [user["turn"] for user in _users(after)] == [2] + assert after["session_id"] == before["session_id"] == "ctx-1" + assert after["trajectory_id"] != before["trajectory_id"] + + +def test_a_context_evicted_from_memory_goes_on_counting() -> None: + trajectories = TaskTrajectories(max_contexts=1, native=NATIVE, atif=Hooks) + + def play(task_id: str, context_id: str) -> None: + log = trajectories.register(task_id, context_id) + trajectories.start(task_id, TurnStart(message_id=None, parts=(TextPart(text="hi"),), agent_name="toy", + agent_version="1", agent_model=None)) + log.append({"type": "say", "step": f"{task_id}-1", "text": "done"}) + trajectories.seal(task_id, TrajectoryState.COMPLETED, final=(TextPart(text="done"),)) + + play("a1", "context-a") + first = trajectories.atif_task("a1").document + play("b1", "context-b") + assert trajectories.atif_task("a1") is None + play("a2", "context-a") + second = trajectories.atif_task("a2").document + assert [user["turn"] for user in _users(second)] == [1] + assert second["trajectory_id"] != first["trajectory_id"] + + +def test_a_snapshot_carries_the_turn_count_to_the_fresh_agent_it_is_restored_into( + objects: dict[str, bytes], monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None: + with TestClient(_snapshotting().create_app()) as client: + for tag in ("t1", "t2"): + _ended(client, _send(client, f"work {tag}", f"m-{tag}")) + saved = client.post("/ext/snapshot", json={"context_id": "ctx-1", "objects": { + "trajectory": _grant("http-put", "trajectory", "application/octet-stream"), + "state": _grant("http-put", "state", "application/json")}}) + assert saved.status_code == 200, saved.text + assert saved.json()["objects"]["state"]["size_bytes"] == len(objects["state"]) + assert json.loads(objects["state"]) == {"turns": 2} + # Another container: none of the first one's counts. + monkeypatch.setattr(_turn_index, "TURNS_DIR", tmp_path / "fresh-agent") + with TestClient(_snapshotting().create_app()) as client: + loaded = client.put("/ext/snapshot", json={"target_context_id": "ctx-restored", "objects": { + "trajectory": _grant("http-get", "trajectory", "application/octet-stream"), + "state": _grant("http-get", "state", "application/json")}}) + assert loaded.status_code == 200, loaded.text + task_id = _send(client, "work t3", "m-t3", context_id="ctx-restored") + _ended(client, task_id) + document = _atif(client, task_id=task_id)["trajectory"] + assert errors_in(validate(document)) == [] + assert [(user["turn"], user["context_id"]) for user in _users(document)] == [(2, "ctx-restored")] + assert document["session_id"] == "ctx-restored" + + +def test_a_restore_into_a_context_the_agent_holds_starts_a_new_document(objects: dict[str, bytes]) -> None: + with TestClient(_snapshotting().create_app()) as client: + _ended(client, _send(client, "work t1", "m-t1")) + client.post("/ext/snapshot", json={"context_id": "ctx-1", "objects": { + "trajectory": _grant("http-put", "trajectory", "application/octet-stream"), + "state": _grant("http-put", "state", "application/json")}}) + task_id = _send(client, "work t2", "m-t2") + _ended(client, task_id) + before = _atif(client, task_id=task_id)["trajectory"] + client.put("/ext/snapshot", json={"target_context_id": "ctx-1", "objects": { + "trajectory": _grant("http-get", "trajectory", "application/octet-stream"), + "state": _grant("http-get", "state", "application/json")}}) + task_id = _send(client, "work t3", "m-t3") + _ended(client, task_id) + after = _atif(client, task_id=task_id)["trajectory"] + # The conversation is the snapshot's again, taken after one turn: the count goes on from there. + assert [user["turn"] for user in _users(before)] == [0, 1] + assert [user["turn"] for user in _users(after)] == [1] + assert after["trajectory_id"] != before["trajectory_id"] and after["session_id"] == "ctx-1" + + +def test_a_snapshot_state_that_isnt_the_sdks_is_refused(objects: dict[str, bytes]) -> None: + objects["trajectory"], objects["state"] = b"conversation", b'{"turns": -1}' + with TestClient(_snapshotting().create_app()) as client: + refused = client.put("/ext/snapshot", json={"target_context_id": "ctx-restored", "objects": { + "trajectory": _grant("http-get", "trajectory", "application/octet-stream"), + "state": _grant("http-get", "state", "application/json")}}) + assert refused.status_code == 400 and refused.json()["error"]["code"] == "snapshot_state_invalid", refused.text + + +def test_an_agent_that_serves_no_atif_writes_no_state(objects: dict[str, bytes]) -> None: + with TestClient(_snapshotting(atif=None).create_app()) as client: + saved = client.post("/ext/snapshot", json={"context_id": "ctx-1", "objects": { + "trajectory": _grant("http-put", "trajectory", "application/octet-stream"), + "state": _grant("http-put", "state", "application/json")}}) + assert saved.status_code == 200, saved.text + assert "state" not in saved.json()["objects"] and "state" not in objects + + +def test_a_snapshot_state_grant_names_json() -> None: + with TestClient(_snapshotting().create_app()) as client: + refused = client.post("/ext/snapshot", json={"context_id": "ctx-1", "objects": { + "trajectory": _grant("http-put", "trajectory", "application/octet-stream"), + "state": _grant("http-put", "state", "application/octet-stream")}}) + assert refused.status_code == 400 and "state media_type" in refused.text + + +def test_a_count_that_cant_be_written_is_kept_in_memory(tmp_path: Path, caplog: pytest.LogCaptureFixture) -> None: + blocked = tmp_path / "a-file" + blocked.write_text("not a folder") + turns = _turn_index.TurnIndex(blocked) + with caplog.at_level(logging.WARNING): + assert [turns.next("ctx"), turns.next("ctx"), turns.next("other")] == [0, 1, 0] + assert sum("kept in memory only" in record.message for record in caplog.records) == 1 diff --git a/src/agent_env/a2a_agent/a2a_agent.py b/src/agent_env/a2a_agent/a2a_agent.py index b9139a6af..af60b7af4 100644 --- a/src/agent_env/a2a_agent/a2a_agent.py +++ b/src/agent_env/a2a_agent/a2a_agent.py @@ -12,6 +12,7 @@ from agentenv_protocol import client as protocol_v1 from agentenv_protocol.a2a_agent import STANDARD_EXTENSIONS +from agentenv_protocol.atif import FORMAT as ATIF_FORMAT from agentenv_protocol.types import CONTROL_TOKEN_ENV from agent_env.config import get_config @@ -181,6 +182,13 @@ def find_extension(card: dict, uri: str) -> dict | None: return ext return None + @staticmethod + def serves_atif(card: dict) -> bool: + """Whether the agent's card offers atif/1 among its trajectory formats: such an agent's SDK keeps its own state, + its turn counts, in each snapshot beside the agent's objects.""" + trajectory = A2AAgent.find_extension(card, A2AAgent.EXT_TRAJECTORY) or {} + return ATIF_FORMAT in (trajectory.get("params") or {}).get("formats", ()) + @staticmethod def extension_method(card: dict, uri: str, method: str) -> dict | None: """Return an advertised extension method, or ``None`` if absent.""" diff --git a/src/agent_env/a2a_agent/object_transfer.py b/src/agent_env/a2a_agent/object_transfer.py index 6905ed47c..727f662ee 100644 --- a/src/agent_env/a2a_agent/object_transfer.py +++ b/src/agent_env/a2a_agent/object_transfer.py @@ -91,12 +91,16 @@ class ObjectLimits: SNAPSHOT_TRAJECTORY_OBJECT_NAME = "trajectory" SNAPSHOT_WORKSPACE_OBJECT_NAME = "workspace" +#: The SDK's own object of a snapshot, its turn counts as JSON, which only an agent that serves atif/1 is granted. +SNAPSHOT_STATE_OBJECT_NAME = "state" +SNAPSHOT_STATE_MAX_BYTES = 64 * 1024 # A portable snapshot's objects, each opaque bytes, and the most each may hold. _SNAPSHOT_OBJECTS = { SNAPSHOT_TRAJECTORY_OBJECT_NAME: DEFAULT_SNAPSHOT_TRAJECTORY_MAX_BYTES, SNAPSHOT_WORKSPACE_OBJECT_NAME: DEFAULT_SNAPSHOT_WORKSPACE_MAX_BYTES, } _OPAQUE = "application/octet-stream" +_JSON = "application/json" def _fields(model: type[BaseModel]) -> tuple[str, ...]: return request_fields(model).required @@ -445,8 +449,10 @@ def snapshot_save_call( context_id: str, capture_prefix: str, sandbox_type: str | None, + state: bool = False, ) -> TransferCall: - """The snapshot ``save`` call that writes one capture below ``capture_prefix``.""" + """The snapshot ``save`` call that writes one capture below ``capture_prefix``, granting the + SDK's ``state`` object too when the agent keeps one (``A2AAgent.serves_atif``).""" _require_object_form( method, ObjectSnapshotSaveRequest, @@ -458,10 +464,16 @@ def snapshot_save_call( name: write_object(store, url, media_type=_OPAQUE, max_bytes=max_bytes) for name, url, max_bytes in _snapshot_objects(store, capture_prefix) } + if state: + objects[SNAPSHOT_STATE_OBJECT_NAME] = write_object( + store, _snapshot_url(store, capture_prefix, SNAPSHOT_STATE_OBJECT_NAME), + media_type=_JSON, max_bytes=SNAPSHOT_STATE_MAX_BYTES, + ) request = ObjectSnapshotSaveRequest( context_id=context_id, objects=SnapshotWriteObjects(**objects) ) - return TransferCall("objects", request.model_dump(mode="json")) + # Only the grants given: a pinned agent's request model forbids the optional ones newer SDKs take. + return TransferCall("objects", request.model_dump(mode="json", exclude_none=True)) def snapshot_load_call( @@ -473,8 +485,10 @@ def snapshot_load_call( file_names: Collection[str], target_context_id: str | None, sandbox_type: str | None, + state: bool = False, ) -> TransferCall: - """The snapshot ``load`` call that restores the capture at ``bundle_url``. Only a portable + """The snapshot ``load`` call that restores the capture at ``bundle_url``, granting the SDK's + ``state`` object too when the capture has one and the agent keeps one. Only a portable capture can be restored; an older one holds the runtime's own files.""" operation = f"snapshot load on agent '{agent_name}'" if not is_portable_snapshot(file_names): @@ -489,6 +503,11 @@ def snapshot_load_call( for name, url, max_bytes in _snapshot_objects(store, bundle_url) if name in file_names } + if state and SNAPSHOT_STATE_OBJECT_NAME in file_names: + objects[SNAPSHOT_STATE_OBJECT_NAME] = read_object( + store, _snapshot_url(store, bundle_url, SNAPSHOT_STATE_OBJECT_NAME), + media_type=_JSON, max_bytes=SNAPSHOT_STATE_MAX_BYTES, + ) request = ObjectSnapshotLoadRequest( objects=SnapshotReadObjects(**objects), target_context_id=target_context_id ) @@ -496,13 +515,16 @@ def snapshot_load_call( def _snapshot_objects(store: ObjectStore, prefix_url: str) -> list[tuple[str, str, int]]: - prefix_key = store.get_object_key(prefix_url).rstrip("/") + "/" return [ - (name, store.object_url(prefix_key + name), max_bytes) + (name, _snapshot_url(store, prefix_url, name), max_bytes) for name, max_bytes in _SNAPSHOT_OBJECTS.items() ] +def _snapshot_url(store: ObjectStore, prefix_url: str, name: str) -> str: + return store.object_url(store.get_object_key(prefix_url).rstrip("/") + "/" + name) + + def changelog_enable_call( method: Mapping[str, Any] | None, store: ObjectStore, diff --git a/src/agent_env/task_step/snapshot_utils/agent_state_capture.py b/src/agent_env/task_step/snapshot_utils/agent_state_capture.py index 2694d8488..8ca43f4af 100644 --- a/src/agent_env/task_step/snapshot_utils/agent_state_capture.py +++ b/src/agent_env/task_step/snapshot_utils/agent_state_capture.py @@ -96,6 +96,7 @@ async def capture_workspace( context_id=a2a_context_id, capture_prefix=capture_prefix, sandbox_type=sandbox_type, + state=A2AAgent.serves_atif(a2a_card or {}), ) await invoke_transfer( a2a_url + save_path, diff --git a/src/agent_env/task_step/task_steps/deploy_agent.py b/src/agent_env/task_step/task_steps/deploy_agent.py index 6e7b513c5..eba3ec718 100644 --- a/src/agent_env/task_step/task_steps/deploy_agent.py +++ b/src/agent_env/task_step/task_steps/deploy_agent.py @@ -726,6 +726,7 @@ async def _load_snapshot( file_names=set((universe.file_artifact_refs or universe.file_artifact_ids or {}).keys()), target_context_id=self.agent_snapshot_target_context_id, sandbox_type=sandbox_type, + state=A2AAgent.serves_atif(card), ) answer = await invoke_transfer( a2a_url + load_path, diff --git a/tst/data/a2a_agent/agent.py b/tst/data/a2a_agent/agent.py index bf1596177..194bfb0f2 100644 --- a/tst/data/a2a_agent/agent.py +++ b/tst/data/a2a_agent/agent.py @@ -15,6 +15,9 @@ ``list-skills`` line in its prompt adds a ``skill : =, ...`` line for each one. A ``run `` line has it run that command in its container and add a ``ran : `` line. +Its snapshot holds the context's id as its trajectory and a fixed workspace, and a load restores into the context it is +asked for, so the SDK's own snapshot state, the atif/1 copy's turn count, is what a restore carries. + A ``cdp `` line has it open the URL in a new tab of the browser its cdp-config names so, over raw CDP, and add a ``cdp : `` line, ``<digest>`` the first 12 hex digits of its address's sha256, so a reader can tell one address from another without the address. With no endpoint by that name the turn fails. @@ -39,6 +42,7 @@ CDP_CONFIG_V1, MCP_CONFIG_V1, SKILL_CONFIG_V1, + SNAPSHOT_V1, TRAJECTORY_V1, TRIGGERS_V1, AgentConfig, @@ -47,6 +51,11 @@ BundleSkillRequest, FilePart, InlineSkillRequest, + ObjectSnapshotLoadRequest, + ObjectSnapshotLoadResponse, + ObjectSnapshotSaveRequest, + ObjectSnapshotSaveResponse, + SnapshotUploadedObjects, TaskRequest, TaskResult, TextPart, @@ -56,6 +65,7 @@ download, enable, extension, + upload, ) from agentenv_protocol.atif import Adapter, atif_adapter, native from websockets.asyncio.client import connect @@ -67,6 +77,8 @@ CDP_LOAD_SECONDS = 30 RUN_TIMEOUT_SECONDS = 60 SKILLS_DIR = Path.home() / "skills" +SNAPSHOT_DIR = Path.home() / "snapshot" +WORKSPACE = b"echo agent workspace" LIVE_STEPS = re.compile(r"live-steps (\d+)") LIVE_STEP_SECONDS = 1 # Bounds how long a prompt can hold up a turn. @@ -230,6 +242,20 @@ async def add_bundle_skill(self, request: BundleSkillRequest) -> dict[str, str]: await download(item.object, SKILLS_DIR / request.name / item.path) return {"name": request.name} + @extension(SNAPSHOT_V1.save) + async def save_snapshot(self, request: ObjectSnapshotSaveRequest) -> ObjectSnapshotSaveResponse: + trajectory = await upload(request.objects.trajectory, json.dumps({"context_id": request.context_id}).encode()) + workspace = await upload(request.objects.workspace, WORKSPACE) if request.objects.workspace else None + return ObjectSnapshotSaveResponse( + context_id=request.context_id, objects=SnapshotUploadedObjects(trajectory=trajectory, workspace=workspace) + ) + + @extension(SNAPSHOT_V1.load) + async def load_snapshot(self, request: ObjectSnapshotLoadRequest) -> ObjectSnapshotLoadResponse: + await download(request.objects.trajectory, SNAPSHOT_DIR / "trajectory") + saved = json.loads((SNAPSHOT_DIR / "trajectory").read_text())["context_id"] + return ObjectSnapshotLoadResponse(context_id=request.target_context_id or saved) + if __name__ == "__main__": EchoAgent().serve() diff --git a/tst/integration/agent/a2a_agent/a2a_agent_test.py b/tst/integration/agent/a2a_agent/a2a_agent_test.py index 4f0839956..f3d9c7c1b 100644 --- a/tst/integration/agent/a2a_agent/a2a_agent_test.py +++ b/tst/integration/agent/a2a_agent/a2a_agent_test.py @@ -32,7 +32,7 @@ def a2a_agent() -> A2AAgent: @pytest.mark.xfail( reason=( "The echo agent has no model or tools: the MCP check needs a tool call and " - "the snapshot extension is not implemented." + "the snapshot check a model that recalls what it was told." ), strict=False, ) diff --git a/tst/integration/task_step/test_prompt_agent_live_trajectory_local.py b/tst/integration/task_step/test_prompt_agent_live_trajectory_local.py index 1d0a3dede..04d115a30 100644 --- a/tst/integration/task_step/test_prompt_agent_live_trajectory_local.py +++ b/tst/integration/task_step/test_prompt_agent_live_trajectory_local.py @@ -4,7 +4,8 @@ in more than one chunk, and its chunks join to that turn's final trajectory; each turn names the one after it, and the last none. The echo agent declares its native format and an ATIF adapter, so its card offers both; its native reads name their format, its atif/1 reads are valid ATIF, and a read naming another format is refused with a code agent-env -reads. Needs Docker and a throwaway local registry.""" +reads. A snapshot of it carries its atif/1 copy's turn count to the fresh agent it is restored into. Needs Docker and a +throwaway local registry.""" import json import re @@ -21,6 +22,7 @@ from agent_env.a2a_agent import A2AAgent from agent_env.a2a_agent.protocol import raise_for_extension_status +from agent_env.artifact.artifacts.file_artifact_universe import FileArtifactUniverse from agent_env.artifact.store import reset_artifact_store from agent_env.config import configure, get_config, reset_config, set_image_store from agent_env.store.image_store import LocalRegistryImageStore @@ -28,6 +30,7 @@ from agent_env.task import Task from agent_env.task_step.task_steps.deploy_agent import DeployAgentTaskStep from agent_env.task_step.task_steps.prompt_agent import PromptAgentTaskStep +from agent_env.task_step.task_steps.snapshot_agent_state import SnapshotAgentStateTaskStep from tst.integration.utils.registry import REGISTRY_IMAGE from tst.util.a2a_test_agent import put_test_agent @@ -90,13 +93,30 @@ def local_registry(monkeypatch, tmp_path): reset_config() -def _deploy(agent, name: str) -> DeployAgentTaskStep: +def _deploy(agent, name: str, **snapshot) -> DeployAgentTaskStep: return DeployAgentTaskStep( id=f"deploy-{name}", version=None, env_ids=[], a2a_agent_id=agent.id, a2a_agent_version=agent.version, - agent_name=name, sandbox_type="local", + agent_name=name, sandbox_type="local", **snapshot, ) +def _prompt(step_id: str, agent_name: str, context_id: str) -> PromptAgentTaskStep: + return PromptAgentTaskStep( + id=step_id, version=None, prompt_id=step_id, agent_name=agent_name, prompt=step_id, context_id=context_id, + ) + + +async def _atif_users(deployed, context_id: str) -> tuple[dict, list[dict]]: + """The atif/1 document of the context's latest task, and its user steps' profile records.""" + url = deployed.a2a_url + A2AAgent.find_extension(deployed.a2a_card, A2AAgent.EXT_TRAJECTORY)["params"]["endpoint"] + async with httpx.AsyncClient(timeout=30, headers=deployed.control_headers) as client: + page = (await client.post(url, json={"context_id": context_id, "after": 0})).json() + read = (await client.post(url, json={"task_id": page["task_id"], "format": ATIF})).json() + document = read["trajectory"] + assert errors_in(validate(document)) == [] + return document, [step["extra"]["agentenv"] for step in document["steps"] if step["source"] == "user"] + + def _json_lines(store, key: str) -> list: return [json.loads(line) for line in store.get(store.object_url(key)).decode().splitlines()] @@ -175,3 +195,34 @@ async def test_a_deployed_agent_serves_its_native_format_and_atif_and_refuses_an with pytest.raises(httpx.HTTPStatusError, match="HTTP 400: format_not_offered"): raise_for_extension_status(refused, operation="trajectory read") + +@pytest.mark.asyncio +async def test_a_snapshot_carries_the_turn_count_to_the_fresh_agent_it_is_restored_into(local_registry): + suffix = uuid.uuid4().hex[:8] + source, restored, snapshot_id = f"turns-{suffix}", f"restored-{suffix}", f"turns-snapshot-{suffix}" + agent = put_test_agent(f"turn-count-agent-{suffix}") + task = Task.put(id=f"turn-count-{suffix}", steps=[ + _deploy(agent, "solver"), + _prompt("one", "solver", source), + _prompt("two", "solver", source), + SnapshotAgentStateTaskStep(id="snapshot", version=None, artifact_id=snapshot_id, prompt_id="two", + agent_name="solver"), + _deploy(agent, "restored", agent_snapshot_files_artifact_id=snapshot_id, + agent_snapshot_target_context_id=restored), + _prompt("three", "restored", restored), + ]) + + context = await task.run() + + assert not context.metadata.get("failed_steps"), context.metadata.get("failed_steps") + store = get_config().get_object_store() + universe = FileArtifactUniverse.get(snapshot_id) + state = store.get(store.object_url(store.get_object_key(universe.bundle_object_url).rstrip("/") + "/state")) + assert json.loads(state) == {"turns": 2} + agents = {deployed.agent_name: deployed for deployed in context.deployed_agents} + before, before_users = await _atif_users(agents["solver"], source) + after, after_users = await _atif_users(agents["restored"], restored) + assert [(user["turn"], user["context_id"]) for user in before_users] == [(0, source), (1, source)] + assert [(user["turn"], user["context_id"]) for user in after_users] == [(2, restored)] + assert (after["session_id"], [step["message"] for step in after["steps"]]) == (restored, ["three", "Echo: three"]) + assert after["trajectory_id"] != before["trajectory_id"] diff --git a/tst/unit/a2a_agent/snapshot_state_test.py b/tst/unit/a2a_agent/snapshot_state_test.py new file mode 100644 index 000000000..50a90b48a --- /dev/null +++ b/tst/unit/a2a_agent/snapshot_state_test.py @@ -0,0 +1,122 @@ +"""A snapshot of an agent that serves atif/1 carries its SDK's own state, the context's turn count, as a JSON object +beside the agent's: its save is granted the object, and its load the stored one. An agent that doesn't keep one is +granted none, and nothing it would refuse.""" + +from __future__ import annotations + +from typing import Any + +import pytest +from agentenv_protocol.a2a_agent import ( + SNAPSHOT_V1, + TRAJECTORY_V1, + AgentEnvAgent, + AgentIdentity, + ObjectSnapshotLoadRequest, + ObjectSnapshotSaveRequest, + TaskRequest, + TaskResult, + a2a_agent, + enable, + extension, +) +from agentenv_protocol.atif import Adapter, atif_adapter, native +from starlette.testclient import TestClient + +from agent_env.a2a_agent.a2a_agent import A2AAgent +from agent_env.a2a_agent.object_transfer import ( + SNAPSHOT_STATE_MAX_BYTES, + snapshot_load_call, + snapshot_save_call, +) +from tst.util.granting_object_store import GrantingObjectStore + + +@atif_adapter(native_format="toy/1", version="1.0.0", input_includes_cache=None) +class _ToyAtif(Adapter): + @native(type="say") + def say(self, record: dict[str, Any], turn: Any) -> None: + turn.message(step="say", text=record["text"]) + turn.step(key="say", llm_call_count=0) + + +def _card(*, atif: bool) -> dict[str, Any]: + trajectory = enable(TRAJECTORY_V1, native="toy/1", **({"atif": _ToyAtif} if atif else {})) + + @a2a_agent(identity=AgentIdentity(name="toy", description="test", version="1"), extensions=(trajectory,)) + class _Toy(AgentEnvAgent): + async def run(self, request: TaskRequest) -> TaskResult: + return TaskResult.text("ok") + + @extension(SNAPSHOT_V1.save) + async def save(self, request: ObjectSnapshotSaveRequest): + return {"context_id": request.context_id, "objects": {}} + + @extension(SNAPSHOT_V1.load) + async def load(self, request: ObjectSnapshotLoadRequest): + return {"context_id": "restored"} + + return TestClient(_Toy().create_app()).get("/.well-known/agent-card.json").json() + + +def _method(card: dict[str, Any], name: str) -> dict[str, Any] | None: + return A2AAgent.operation(A2AAgent.find_extension(card, SNAPSHOT_V1.uri), name)[0] + + +def _nulls(value: Any) -> list[Any]: + if isinstance(value, dict): + return [None for item in value.values() if item is None] + [n for item in value.values() for n in _nulls(item)] + if isinstance(value, list): + return [n for item in value for n in _nulls(item)] + return [] + + +@pytest.fixture +def store(tmp_path) -> GrantingObjectStore: + return GrantingObjectStore(str(tmp_path)) + + +def test_an_agents_card_says_whether_it_serves_atif() -> None: + assert A2AAgent.serves_atif(_card(atif=True)) + assert not A2AAgent.serves_atif(_card(atif=False)) + assert not A2AAgent.serves_atif({}) + + +@pytest.mark.parametrize("atif", [True, False], ids=["serves-atif", "native-only"]) +def test_a_snapshot_save_grants_the_state_only_to_an_agent_that_keeps_one(store, atif) -> None: + card = _card(atif=atif) + + call = snapshot_save_call( + _method(card, "save"), store, agent_name="toy", context_id="ctx", + capture_prefix=store.object_url("snap/"), sandbox_type="local", state=A2AAgent.serves_atif(card), + ) + + objects = call.payload["objects"] + assert set(objects) == {"trajectory", "workspace", *(["state"] if atif else [])} + if atif: + assert (objects["state"]["media_type"], objects["state"]["max_bytes"]) == ( + "application/json", SNAPSHOT_STATE_MAX_BYTES) + # A pinned agent's request model forbids a field it doesn't know, a null one included. + assert _nulls(call.payload) == [] + + +@pytest.mark.parametrize( + "atif, stored, granted", + [(True, True, True), (True, False, False), (False, True, False)], + ids=["serves-atif", "capture-without-state", "native-only"], +) +def test_a_snapshot_load_grants_the_stored_state_to_an_agent_that_keeps_one(store, atif, stored, granted) -> None: + card = _card(atif=atif) + names = {"trajectory", "workspace", *(["state"] if stored else [])} + for name in names: + store.put(f"snap/{name}", b'{"turns": 2}' if name == "state" else b"bytes") + + call = snapshot_load_call( + _method(card, "load"), store, agent_name="toy", bundle_url=store.object_url("snap/"), file_names=names, + target_context_id=None, sandbox_type="local", state=A2AAgent.serves_atif(card), + ) + + objects = call.payload["objects"] + assert ("state" in objects) is granted + if granted: + assert (objects["state"]["media_type"], objects["state"]["size_bytes"]) == ("application/json", 12) From ef6999bede6dc4f5ac49b542a8d8b9de23456621 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan <edgar.arakelyan@scale.com> Date: Thu, 19 Nov 2026 09:46:21 -0800 Subject: [PATCH 2/6] fix(a2a-agent): grant snapshot state only to an SDK whose card names 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> --- packages/agentenv-protocol/README.md | 8 +- .../agentenv_protocol/a2a_agent/__init__.py | 2 + .../a2a_agent/_turn_index.py | 44 +++++---- .../agentenv_protocol/a2a_agent/framework.py | 95 ++++++++++--------- .../tests/test_a2a_atif_turns.py | 59 +++++++++++- src/agent_env/a2a_agent/a2a_agent.py | 13 ++- src/agent_env/a2a_agent/object_transfer.py | 5 +- .../snapshot_utils/agent_state_capture.py | 2 +- .../task_step/task_steps/deploy_agent.py | 2 +- tst/unit/a2a_agent/snapshot_state_test.py | 56 +++++++---- 10 files changed, 186 insertions(+), 100 deletions(-) diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index e5a9e32e8..3e72f22c3 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1657,8 +1657,12 @@ count in its `state` object, a JSON object that is the SDK's own: on save the SDK uploads it after the agent's handler returns and adds it to the answer, and on load it reads it before the agent's handler runs and seeds the context the handler restored into, whose next task goes on from the snapshot's count in a -new document. The agent's handlers leave `state` alone, and agent-env grants it -only to an agent whose card lists `atif/1`. +new document. The SDK takes its state between turns: a save or load holds the +context, so a task of it that would start meanwhile waits until the agent's +handler returns. The agent's handlers leave `state` alone. The card's snapshot +extension names the state the SDK keeps (`"state": ["turns"]` in its params, +`SNAPSHOT_STATE_PARAM`), and agent-env grants the object only to an agent whose +card has it, since an SDK from before it refuses the object. `enable(..., description="...")` is reserved for declarations carrying configuration or metadata. It preserves the agent-specific extension prose diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py index 2c47dc6ad..69c8b8a67 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py @@ -93,6 +93,7 @@ request_fields, ) from .control_token import ControlTokenMiddleware +from ._turn_index import SNAPSHOT_STATE_PARAM from .framework import ( A2AAgentApplication, AgentEnvAgent, @@ -153,6 +154,7 @@ "PEER_AGENTS_V1", "REPORTED_USAGE_KEY", "SKILL_CONFIG_V1", + "SNAPSHOT_STATE_PARAM", "SNAPSHOT_V1", "STAGING_ENDPOINT", "STAGING_V1_URI", diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_turn_index.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_turn_index.py index 982835436..9dde7e492 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_turn_index.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_turn_index.py @@ -16,6 +16,9 @@ #: Where the counts are kept, one small file per context, under the agent's user's home. TURNS_DIR = Path.home() / ".local" / "state" / "agentenv" / "turns" +#: The snapshot extension's card param naming the fields of the state an SDK keeps in each snapshot: a caller grants +#: the ``state`` object only to an agent whose card has it, since an SDK from before it refuses the object. +SNAPSHOT_STATE_PARAM = "state" class SnapshotState(BaseModel): @@ -28,13 +31,14 @@ class SnapshotState(BaseModel): class TurnIndex: - """Each context's count of started tasks. A count that can't be written stays in memory, with a warning, so a - read-only home costs only the count's survival across a restart.""" + """Each context's count of started tasks, read from its file each time, so two servers on one home agree and memory + holds nothing per context. A count that can't be written stays in memory, with a warning, so a read-only home costs + only the count's survival across a restart.""" def __init__(self, folder: Path | None = None) -> None: self._folder = folder if folder is not None else TURNS_DIR - self._counts: dict[str, int] = {} - self._warned = False + self._unwritten: dict[str, int] = {} + self._warned: set[str] = set() def next(self, context_id: str) -> int: """The starting task's turn index, the number of tasks the context started before it, counting this one.""" @@ -43,18 +47,17 @@ def next(self, context_id: str) -> int: return index def count(self, context_id: str) -> int: - if context_id not in self._counts: - try: - self._counts[context_id] = json.loads(self._path(context_id).read_text())["turns"] - except FileNotFoundError: - self._counts[context_id] = 0 - except OSError as exc: - self._warn(exc) - self._counts[context_id] = 0 - return self._counts[context_id] + if context_id in self._unwritten: + return self._unwritten[context_id] + try: + return SnapshotState.model_validate_json(self._path(context_id).read_bytes()).turns + except FileNotFoundError: + return 0 + except (OSError, ValueError) as exc: + self._warn("a turn count can't be read, so its context counts from 0 again: %s", exc) + return 0 def set(self, context_id: str, count: int) -> None: - self._counts[context_id] = count path = self._path(context_id) try: path.parent.mkdir(parents=True, exist_ok=True) @@ -62,12 +65,15 @@ def set(self, context_id: str, count: int) -> None: part.write_text(json.dumps({"context_id": context_id, "turns": count})) os.replace(part, path) except OSError as exc: - self._warn(exc) + self._warn("turn counts are kept in memory only, so a restart starts them again: %s", exc) + self._unwritten[context_id] = count + else: + self._unwritten.pop(context_id, None) def _path(self, context_id: str) -> Path: return self._folder / f"{hashlib.sha256(context_id.encode()).hexdigest()}.json" - def _warn(self, exc: OSError) -> None: - if not self._warned: - self._warned = True - logger.warning("turn counts are kept in memory only, so a restart starts them again: %s", exc) + def _warn(self, message: str, exc: Exception) -> None: + if message not in self._warned: + self._warned.add(message) + logger.warning(message, exc) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py index d81dbcbab..3e6c815e3 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py @@ -11,8 +11,8 @@ import tempfile import uuid from collections import OrderedDict -from collections.abc import Callable, Iterable, Mapping -from contextlib import AbstractAsyncContextManager, asynccontextmanager +from collections.abc import Awaitable, Callable, Iterable, Mapping +from contextlib import AbstractAsyncContextManager, asynccontextmanager, nullcontext from dataclasses import dataclass, field from pathlib import Path from typing import Any, AsyncIterator, TypeVar, get_args, get_origin, get_type_hints @@ -35,7 +35,7 @@ from ..atif import PROFILE_VERSION as ATIF_PROFILE_VERSION from ..atif import SCHEMA_VERSION as ATIF_SCHEMA_VERSION from ._atif_copy import TurnStart -from ._turn_index import SnapshotState +from ._turn_index import SNAPSHOT_STATE_PARAM, SnapshotState from ._trajectory_log import MAX_TRAJECTORY_READ_BYTES, TaskTrajectories from ._triggers import TriggerEngine, TriggerError from .extensions import ( @@ -58,8 +58,6 @@ ExtensionActivation, ExtensionDefinition, ImplementationOwner, - ObjectSnapshotLoadRequest, - ObjectSnapshotSaveRequest, McpAddRequest, OperationReference, PeerAgentsSetRequest, @@ -148,6 +146,21 @@ def _config_wire_names(config: type[AgentConfig]) -> dict[str, str]: return result +async def _read_snapshot_state(grant: Any) -> SnapshotState: + """The SDK's state a snapshot carries, read through its ``state`` grant.""" + with tempfile.TemporaryDirectory() as folder: + path = Path(folder) / "state.json" + await download(grant, path) + try: + return SnapshotState.model_validate_json(path.read_bytes()) + except ValidationError as exc: + raise AgentEnvError( + "snapshot_state_invalid", + f"the snapshot's state object isn't the SDK's snapshot state: {exc.errors()[0]['msg']}", + status=400, + ) from exc + + def _config_write_only_wire_names(config: type[AgentConfig]) -> set[str]: """Return wire names explicitly marked as write-only in the config schema.""" wire_names = _config_wire_names(config) @@ -584,6 +597,8 @@ def __init__( self.task_trajectories = TaskTrajectories(native=native, atif=atif) #: Whether the card offers atif/1, served from the copy an adapter builds. self.serves_atif = atif is not None + #: Each context's lock, held while a task of it runs, and while its snapshot state is taken. + self.context_locks = _BoundedContextLocks() self._context_sessions = _BoundedContextSessions() self.skills: list[Mapping[str, Any]] = [] self.identity_skills: dict[str, str] = {} @@ -947,39 +962,32 @@ async def _atif_document( ) return AtifObjectsResponse(objects=uploaded, **versions).model_dump(mode="json", exclude_none=True) - async def read_snapshot_state(self, request: Any) -> SnapshotState | None: - """Before an agent's snapshot load: the SDK's state the snapshot carries, read through - its ``state`` grant, which only an agent that serves atif/1 is sent.""" - if not (self.serves_atif and isinstance(request, ObjectSnapshotLoadRequest) - and request.objects.state is not None): - return None - with tempfile.TemporaryDirectory() as folder: - path = Path(folder) / "state.json" - await download(request.objects.state, path) - try: - return SnapshotState.model_validate_json(path.read_bytes()) - except ValidationError as exc: - raise AgentEnvError( - "snapshot_state_invalid", - f"the snapshot's state object isn't the SDK's snapshot state: {exc.errors()[0]['msg']}", - status=400, - ) from exc - - def restore_snapshot_state(self, state: SnapshotState | None, answer: Mapping[str, Any]) -> None: - """After the load: the context the agent restored into goes on counting from the - snapshot's turn count.""" - if state is not None: + def card_extension(self, item: dict[str, Any]) -> dict[str, Any]: + """An extension's card entry, with what the SDK adds: an agent that serves atif/1 names the state its SDK + keeps in each snapshot, so a caller grants the object only to an SDK that takes it.""" + if self.serves_atif and item.get("uri") == SNAPSHOT_V1.uri: + return {**item, "params": {**item.get("params", {}), SNAPSHOT_STATE_PARAM: list(SnapshotState.model_fields)}} + return item + + async def snapshot(self, name: str, request: Any, invoke: Callable[[], Awaitable[Any]]) -> Any: + """An agent's snapshot ``save`` or ``load``, with the SDK's state, the context's turn count, uploaded after a + save and read before a load through the request's ``state`` grant. The SDK's state is taken between turns: + under the context's lock, so no task of it starts while the agent captures or restores it.""" + grant = getattr(getattr(request, "objects", None), "state", None) + if not self.serves_atif or grant is None: + return await invoke() + context_id = request.context_id if name == "save" else request.target_context_id + async with self.context_locks.acquire(context_id) if context_id else nullcontext(): + if name == "save": + answer = await invoke() + state = SnapshotState(turns=self.task_trajectories.turns(request.context_id)) + uploaded = await upload(grant, state.model_dump_json().encode()) + return {**answer, "objects": {**answer["objects"], + "state": uploaded.model_dump(mode="json", exclude_none=True)}} + state = await _read_snapshot_state(grant) + answer = await invoke() self.task_trajectories.restored(str(answer["context_id"]), state.turns) - - async def write_snapshot_state(self, request: Any, answer: dict[str, Any]) -> dict[str, Any]: - """After an agent's snapshot save: the SDK's state, the context's turn count, uploaded - through the request's ``state`` grant and named among the answer's objects.""" - if not (self.serves_atif and isinstance(request, ObjectSnapshotSaveRequest) - and request.objects.state is not None): return answer - state = SnapshotState(turns=self.task_trajectories.turns(request.context_id)) - uploaded = await upload(request.objects.state, state.model_dump_json().encode()) - return {**answer, "objects": {**answer["objects"], "state": uploaded.model_dump(mode="json", exclude_none=True)}} def check_trajectory_format(self, format: str | None) -> None: """Refuse a trajectory read naming a format the card doesn't offer, before any handler @@ -1316,7 +1324,7 @@ def _build_card(self) -> Any: for skill in identity.skills ] extensions = [ - AgentExtension.model_validate(item) + AgentExtension.model_validate(self.services.card_extension(item)) for item in self.registry.card_extensions() ] if self.staging.max_bytes: @@ -1420,13 +1428,9 @@ async def invoke_and_validate() -> Any: ): async with self.services.skill_registration(input_payload): result = await invoke_and_validate() - elif extension_uri == SNAPSHOT_V1.uri and operation.definition.name == "load": - state = await self.services.read_snapshot_state(extension_request) - result = await invoke_and_validate() - self.services.restore_snapshot_state(state, result) - elif extension_uri == SNAPSHOT_V1.uri and operation.definition.name == "save": - result = await self.services.write_snapshot_state( - extension_request, await invoke_and_validate() + elif extension_uri == SNAPSHOT_V1.uri and operation.definition.name in ("save", "load"): + result = await self.services.snapshot( + operation.definition.name, extension_request, invoke_and_validate ) else: result = await invoke_and_validate() @@ -1462,7 +1466,6 @@ def __init__( self._services = services self._workspace = workspace self._streaming = streaming - self._context_locks = _BoundedContextLocks() async def execute(self, context: Any, event_queue: Any) -> None: from a2a.server.tasks import TaskUpdater @@ -1489,7 +1492,7 @@ async def execute(self, context: Any, event_queue: Any) -> None: **_thaw(getattr(context.message, "metadata", None) or {}), **({"role": task_config.role} if task_config.role is not None else {}), } - async with self._context_locks.acquire(task.context_id): + async with self._services.context_locks.acquire(task.context_id): parts = tuple(_from_a2a_part(part) for part in (context.message.parts or [])) turn = None if self._services.serves_atif: diff --git a/packages/agentenv-protocol/tests/test_a2a_atif_turns.py b/packages/agentenv-protocol/tests/test_a2a_atif_turns.py index 79e051aba..f0292cbf8 100644 --- a/packages/agentenv-protocol/tests/test_a2a_atif_turns.py +++ b/packages/agentenv-protocol/tests/test_a2a_atif_turns.py @@ -2,17 +2,20 @@ snapshot restored into a fresh agent, each of which starts a new document that goes on counting.""" from __future__ import annotations +import concurrent.futures import json import logging +import time from datetime import datetime, timedelta, timezone from pathlib import Path from typing import Any import pytest from starlette.testclient import TestClient -from test_a2a_atif_serving import NATIVE, Hooks, _atif, _ended, _Hold, _send, _turn +from test_a2a_atif_serving import NATIVE, Hooks, _atif, _ended, _Hold, _send, _state, _turn from agentenv_protocol.a2a_agent import ( + SNAPSHOT_STATE_PARAM, SNAPSHOT_V1, TRAJECTORY_V1, AgentEnvAgent, @@ -40,8 +43,9 @@ _IDENTITY = AgentIdentity(name="toy-agent", description="test", version="2.0") -def _snapshotting(*, atif: Any = Hooks) -> AgentEnvAgent: - """The toy agent with a snapshot extension of its own, whose save and load the SDK's state rides beside.""" +def _snapshotting(*, atif: Any = Hooks, save_hold: _Hold | None = None) -> AgentEnvAgent: + """The toy agent with a snapshot extension of its own, whose save and load the SDK's state rides beside; a save + waits at ``save_hold``, as one uploading the conversation it captured would.""" extensions = (enable(TRAJECTORY_V1, live=True, native=NATIVE, **({"atif": atif} if atif else {})),) @a2a_agent(identity=_IDENTITY, extensions=extensions) @@ -51,6 +55,8 @@ async def run(self, request: TaskRequest) -> TaskResult: @extension(SNAPSHOT_V1.save) async def save(self, request: ObjectSnapshotSaveRequest) -> ObjectSnapshotSaveResponse: + if save_hold is not None: + await save_hold.wait() return ObjectSnapshotSaveResponse(context_id=request.context_id, objects=SnapshotUploadedObjects(trajectory=Uploaded(size_bytes=12))) @@ -192,6 +198,53 @@ def test_an_agent_that_serves_no_atif_writes_no_state(objects: dict[str, bytes]) assert "state" not in saved.json()["objects"] and "state" not in objects +def test_the_card_names_the_state_only_an_sdk_serving_atif_keeps() -> None: + def snapshot_params(agent: AgentEnvAgent) -> dict[str, Any]: + card = TestClient(agent.create_app()).get("/.well-known/agent-card.json").json() + [snapshot] = [ext for ext in card["capabilities"]["extensions"] if ext["uri"] == SNAPSHOT_V1.uri] + return snapshot["params"] + + assert snapshot_params(_snapshotting())[SNAPSHOT_STATE_PARAM] == ["turns"] + assert SNAPSHOT_STATE_PARAM not in snapshot_params(_snapshotting(atif=None)) + + +def test_a_task_waits_for_its_contexts_save_so_the_saved_count_is_its_captures(objects: dict[str, bytes]) -> None: + paused = _Hold() + with TestClient(_snapshotting(save_hold=paused).create_app()) as client: + for tag in ("t1", "t2"): + _ended(client, _send(client, f"work {tag}", f"m-{tag}")) + with concurrent.futures.ThreadPoolExecutor(1) as pool: + saving = pool.submit(client.post, "/ext/snapshot", json={"context_id": "ctx-1", "objects": { + "trajectory": _grant("http-put", "trajectory", "application/octet-stream"), + "state": _grant("http-put", "state", "application/json")}}) + paused.reached() + task_id = _send(client, "work t3", "m-t3") + time.sleep(0.3) + waiting = _state(client, task_id) + paused.resume.set() + saved = saving.result(timeout=10) + _ended(client, task_id) + document = _atif(client, task_id=task_id)["trajectory"] + assert waiting not in ("completed", "failed", "canceled") + assert saved.status_code == 200, saved.text + assert json.loads(objects["state"]) == {"turns": 2} + assert [user["turn"] for user in _users(document)] == [0, 1, 2] + + +def test_two_servers_on_one_home_share_its_counts(tmp_path: Path) -> None: + first, second = _turn_index.TurnIndex(tmp_path), _turn_index.TurnIndex(tmp_path) + assert [first.next("ctx"), second.next("ctx"), first.next("ctx")] == [0, 1, 2] + + +def test_a_count_that_cant_be_read_starts_again_with_a_warning(tmp_path: Path, caplog: pytest.LogCaptureFixture) -> None: + turns = _turn_index.TurnIndex(tmp_path) + turns.set("ctx", 3) + next(tmp_path.glob("*.json")).write_text("not a count") + with caplog.at_level(logging.WARNING): + assert turns.next("ctx") == 0 + assert turns.count("ctx") == 1 and "can't be read" in caplog.text + + def test_a_snapshot_state_grant_names_json() -> None: with TestClient(_snapshotting().create_app()) as client: refused = client.post("/ext/snapshot", json={"context_id": "ctx-1", "objects": { diff --git a/src/agent_env/a2a_agent/a2a_agent.py b/src/agent_env/a2a_agent/a2a_agent.py index af60b7af4..915375304 100644 --- a/src/agent_env/a2a_agent/a2a_agent.py +++ b/src/agent_env/a2a_agent/a2a_agent.py @@ -11,8 +11,7 @@ from typing import TYPE_CHECKING, Any, Callable, ClassVar, Optional from agentenv_protocol import client as protocol_v1 -from agentenv_protocol.a2a_agent import STANDARD_EXTENSIONS -from agentenv_protocol.atif import FORMAT as ATIF_FORMAT +from agentenv_protocol.a2a_agent import SNAPSHOT_STATE_PARAM, STANDARD_EXTENSIONS from agentenv_protocol.types import CONTROL_TOKEN_ENV from agent_env.config import get_config @@ -183,11 +182,11 @@ def find_extension(card: dict, uri: str) -> dict | None: return None @staticmethod - def serves_atif(card: dict) -> bool: - """Whether the agent's card offers atif/1 among its trajectory formats: such an agent's SDK keeps its own state, - its turn counts, in each snapshot beside the agent's objects.""" - trajectory = A2AAgent.find_extension(card, A2AAgent.EXT_TRAJECTORY) or {} - return ATIF_FORMAT in (trajectory.get("params") or {}).get("formats", ()) + def keeps_snapshot_state(card: dict) -> bool: + """Whether the agent's SDK keeps its own state, its atif/1 copy's turn counts, in each snapshot beside the + agent's objects, as its card's snapshot extension says: an SDK from before it refuses the object.""" + snapshot = A2AAgent.find_extension(card, A2AAgent.EXT_SNAPSHOT) or {} + return SNAPSHOT_STATE_PARAM in (snapshot.get("params") or {}) @staticmethod def extension_method(card: dict, uri: str, method: str) -> dict | None: diff --git a/src/agent_env/a2a_agent/object_transfer.py b/src/agent_env/a2a_agent/object_transfer.py index 727f662ee..c1a2aea34 100644 --- a/src/agent_env/a2a_agent/object_transfer.py +++ b/src/agent_env/a2a_agent/object_transfer.py @@ -91,7 +91,8 @@ class ObjectLimits: SNAPSHOT_TRAJECTORY_OBJECT_NAME = "trajectory" SNAPSHOT_WORKSPACE_OBJECT_NAME = "workspace" -#: The SDK's own object of a snapshot, its turn counts as JSON, which only an agent that serves atif/1 is granted. +#: The SDK's own object of a snapshot, its turn counts as JSON, granted only to an agent whose card says its SDK keeps +#: one (``A2AAgent.keeps_snapshot_state``). SNAPSHOT_STATE_OBJECT_NAME = "state" SNAPSHOT_STATE_MAX_BYTES = 64 * 1024 # A portable snapshot's objects, each opaque bytes, and the most each may hold. @@ -452,7 +453,7 @@ def snapshot_save_call( state: bool = False, ) -> TransferCall: """The snapshot ``save`` call that writes one capture below ``capture_prefix``, granting the - SDK's ``state`` object too when the agent keeps one (``A2AAgent.serves_atif``).""" + SDK's ``state`` object too when the agent's SDK keeps one (``A2AAgent.keeps_snapshot_state``).""" _require_object_form( method, ObjectSnapshotSaveRequest, diff --git a/src/agent_env/task_step/snapshot_utils/agent_state_capture.py b/src/agent_env/task_step/snapshot_utils/agent_state_capture.py index 8ca43f4af..e9b1597f5 100644 --- a/src/agent_env/task_step/snapshot_utils/agent_state_capture.py +++ b/src/agent_env/task_step/snapshot_utils/agent_state_capture.py @@ -96,7 +96,7 @@ async def capture_workspace( context_id=a2a_context_id, capture_prefix=capture_prefix, sandbox_type=sandbox_type, - state=A2AAgent.serves_atif(a2a_card or {}), + state=A2AAgent.keeps_snapshot_state(a2a_card or {}), ) await invoke_transfer( a2a_url + save_path, diff --git a/src/agent_env/task_step/task_steps/deploy_agent.py b/src/agent_env/task_step/task_steps/deploy_agent.py index eba3ec718..95ae1b95d 100644 --- a/src/agent_env/task_step/task_steps/deploy_agent.py +++ b/src/agent_env/task_step/task_steps/deploy_agent.py @@ -726,7 +726,7 @@ async def _load_snapshot( file_names=set((universe.file_artifact_refs or universe.file_artifact_ids or {}).keys()), target_context_id=self.agent_snapshot_target_context_id, sandbox_type=sandbox_type, - state=A2AAgent.serves_atif(card), + state=A2AAgent.keeps_snapshot_state(card), ) answer = await invoke_transfer( a2a_url + load_path, diff --git a/tst/unit/a2a_agent/snapshot_state_test.py b/tst/unit/a2a_agent/snapshot_state_test.py index 50a90b48a..30fb16d52 100644 --- a/tst/unit/a2a_agent/snapshot_state_test.py +++ b/tst/unit/a2a_agent/snapshot_state_test.py @@ -1,13 +1,15 @@ -"""A snapshot of an agent that serves atif/1 carries its SDK's own state, the context's turn count, as a JSON object -beside the agent's: its save is granted the object, and its load the stored one. An agent that doesn't keep one is -granted none, and nothing it would refuse.""" +"""A snapshot of an agent whose SDK keeps its own state, the context's atif/1 turn count, carries it as a JSON object +beside the agent's: its save is granted the object, and its load the stored one. An agent that doesn't keep one, or +whose SDK predates the object though it serves atif/1, is granted none, and nothing it would refuse.""" from __future__ import annotations +import copy from typing import Any import pytest from agentenv_protocol.a2a_agent import ( + SNAPSHOT_STATE_PARAM, SNAPSHOT_V1, TRAJECTORY_V1, AgentEnvAgent, @@ -59,6 +61,17 @@ async def load(self, request: ObjectSnapshotLoadRequest): return TestClient(_Toy().create_app()).get("/.well-known/agent-card.json").json() +def _before_snapshot_state(card: dict[str, Any]) -> dict[str, Any]: + """The card of an SDK that serves atif/1 but predates the snapshot's state object, which it refuses.""" + older = copy.deepcopy(card) + del A2AAgent.find_extension(older, SNAPSHOT_V1.uri)["params"][SNAPSHOT_STATE_PARAM] + return older + + +CARDS = {"keeps-state": lambda: _card(atif=True), "native-only": lambda: _card(atif=False), + "serves-atif-before-state": lambda: _before_snapshot_state(_card(atif=True))} + + def _method(card: dict[str, Any], name: str) -> dict[str, Any] | None: return A2AAgent.operation(A2AAgent.find_extension(card, SNAPSHOT_V1.uri), name)[0] @@ -76,24 +89,28 @@ def store(tmp_path) -> GrantingObjectStore: return GrantingObjectStore(str(tmp_path)) -def test_an_agents_card_says_whether_it_serves_atif() -> None: - assert A2AAgent.serves_atif(_card(atif=True)) - assert not A2AAgent.serves_atif(_card(atif=False)) - assert not A2AAgent.serves_atif({}) +def test_an_agents_card_says_whether_its_sdk_keeps_snapshot_state() -> None: + card = _card(atif=True) + assert A2AAgent.find_extension(card, SNAPSHOT_V1.uri)["params"][SNAPSHOT_STATE_PARAM] == ["turns"] + assert A2AAgent.keeps_snapshot_state(card) + assert not A2AAgent.keeps_snapshot_state(_card(atif=False)) + assert not A2AAgent.keeps_snapshot_state(_before_snapshot_state(card)) + assert not A2AAgent.keeps_snapshot_state({}) -@pytest.mark.parametrize("atif", [True, False], ids=["serves-atif", "native-only"]) -def test_a_snapshot_save_grants_the_state_only_to_an_agent_that_keeps_one(store, atif) -> None: - card = _card(atif=atif) +@pytest.mark.parametrize("kind", list(CARDS)) +def test_a_snapshot_save_grants_the_state_only_to_an_agent_that_keeps_one(store, kind) -> None: + card = CARDS[kind]() + keeps = kind == "keeps-state" call = snapshot_save_call( _method(card, "save"), store, agent_name="toy", context_id="ctx", - capture_prefix=store.object_url("snap/"), sandbox_type="local", state=A2AAgent.serves_atif(card), + capture_prefix=store.object_url("snap/"), sandbox_type="local", state=A2AAgent.keeps_snapshot_state(card), ) objects = call.payload["objects"] - assert set(objects) == {"trajectory", "workspace", *(["state"] if atif else [])} - if atif: + assert set(objects) == {"trajectory", "workspace", *(["state"] if keeps else [])} + if keeps: assert (objects["state"]["media_type"], objects["state"]["max_bytes"]) == ( "application/json", SNAPSHOT_STATE_MAX_BYTES) # A pinned agent's request model forbids a field it doesn't know, a null one included. @@ -101,19 +118,20 @@ def test_a_snapshot_save_grants_the_state_only_to_an_agent_that_keeps_one(store, @pytest.mark.parametrize( - "atif, stored, granted", - [(True, True, True), (True, False, False), (False, True, False)], - ids=["serves-atif", "capture-without-state", "native-only"], + "kind, stored, granted", + [("keeps-state", True, True), ("keeps-state", False, False), ("native-only", True, False), + ("serves-atif-before-state", True, False)], + ids=["keeps-state", "capture-without-state", "native-only", "serves-atif-before-state"], ) -def test_a_snapshot_load_grants_the_stored_state_to_an_agent_that_keeps_one(store, atif, stored, granted) -> None: - card = _card(atif=atif) +def test_a_snapshot_load_grants_the_stored_state_to_an_agent_that_keeps_one(store, kind, stored, granted) -> None: + card = CARDS[kind]() names = {"trajectory", "workspace", *(["state"] if stored else [])} for name in names: store.put(f"snap/{name}", b'{"turns": 2}' if name == "state" else b"bytes") call = snapshot_load_call( _method(card, "load"), store, agent_name="toy", bundle_url=store.object_url("snap/"), file_names=names, - target_context_id=None, sandbox_type="local", state=A2AAgent.serves_atif(card), + target_context_id=None, sandbox_type="local", state=A2AAgent.keeps_snapshot_state(card), ) objects = call.payload["objects"] From 8195785a33a25a234eaee24cebeb99e9ddb61492 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan <edgar.arakelyan@scale.com> Date: Thu, 19 Nov 2026 10:03:59 -0800 Subject: [PATCH 3/6] fix(a2a-agent): a snapshot with SDK state holds only its context's task 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> --- packages/agentenv-protocol/README.md | 7 ++- .../agentenv_protocol/a2a_agent/framework.py | 63 ++++++++++++++----- .../tests/test_a2a_atif_turns.py | 28 ++++++++- 3 files changed, 78 insertions(+), 20 deletions(-) diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index 3e72f22c3..94d480de8 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1657,9 +1657,10 @@ count in its `state` object, a JSON object that is the SDK's own: on save the SDK uploads it after the agent's handler returns and adds it to the answer, and on load it reads it before the agent's handler runs and seeds the context the handler restored into, whose next task goes on from the snapshot's count in a -new document. The SDK takes its state between turns: a save or load holds the -context, so a task of it that would start meanwhile waits until the agent's -handler returns. The agent's handlers leave `state` alone. The card's snapshot +new document. While such a save or load 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, as a capture +mid-task expects. The agent's handlers leave `state` alone. The card's snapshot extension names the state the SDK keeps (`"state": ["turns"]` in its params, `SNAPSHOT_STATE_PARAM`), and agent-env grants the object only to an agent whose card has it, since an SDK from before it refuses the object. diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py index 3e6c815e3..d83a4654a 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py @@ -12,7 +12,7 @@ import uuid from collections import OrderedDict from collections.abc import Awaitable, Callable, Iterable, Mapping -from contextlib import AbstractAsyncContextManager, asynccontextmanager, nullcontext +from contextlib import AbstractAsyncContextManager, asynccontextmanager from dataclasses import dataclass, field from pathlib import Path from typing import Any, AsyncIterator, TypeVar, get_args, get_origin, get_type_hints @@ -249,6 +249,39 @@ def _trim_idle(self) -> None: return +@dataclass(slots=True) +class _InFlight: + count: int = 0 + done: asyncio.Event = field(default_factory=asyncio.Event) + + +class _SnapshotsInFlight: + """Each context's snapshots in flight that carry the SDK's state: a task of the context waits to start until none + is, so the turn count a snapshot saves or restores is its conversation's. A running task isn't held.""" + + def __init__(self) -> None: + self._contexts: dict[str, _InFlight] = {} + + @asynccontextmanager + async def holding(self, context_id: str | None) -> AsyncIterator[None]: + if context_id is None: + yield + return + entry = self._contexts.setdefault(context_id, _InFlight()) + entry.count += 1 + try: + yield + finally: + entry.count -= 1 + if not entry.count: + del self._contexts[context_id] + entry.done.set() + + async def wait(self, context_id: str) -> None: + while (entry := self._contexts.get(context_id)) is not None: + await entry.done.wait() + + class AgentEnvAgent: """Typed base class for AgentEnv-compatible A2A agents.""" @@ -597,8 +630,7 @@ def __init__( self.task_trajectories = TaskTrajectories(native=native, atif=atif) #: Whether the card offers atif/1, served from the copy an adapter builds. self.serves_atif = atif is not None - #: Each context's lock, held while a task of it runs, and while its snapshot state is taken. - self.context_locks = _BoundedContextLocks() + self.snapshots_in_flight = _SnapshotsInFlight() self._context_sessions = _BoundedContextSessions() self.skills: list[Mapping[str, Any]] = [] self.identity_skills: dict[str, str] = {} @@ -971,23 +1003,24 @@ def card_extension(self, item: dict[str, Any]) -> dict[str, Any]: async def snapshot(self, name: str, request: Any, invoke: Callable[[], Awaitable[Any]]) -> Any: """An agent's snapshot ``save`` or ``load``, with the SDK's state, the context's turn count, uploaded after a - save and read before a load through the request's ``state`` grant. The SDK's state is taken between turns: - under the context's lock, so no task of it starts while the agent captures or restores it.""" + save and read before a load through the request's ``state`` grant. While one is in flight no task of its + context starts, so the count is the conversation's the agent captured; a running task goes on, as a capture + mid-task expects.""" grant = getattr(getattr(request, "objects", None), "state", None) if not self.serves_atif or grant is None: return await invoke() - context_id = request.context_id if name == "save" else request.target_context_id - async with self.context_locks.acquire(context_id) if context_id else nullcontext(): - if name == "save": + if name == "save": + async with self.snapshots_in_flight.holding(request.context_id): answer = await invoke() state = SnapshotState(turns=self.task_trajectories.turns(request.context_id)) - uploaded = await upload(grant, state.model_dump_json().encode()) - return {**answer, "objects": {**answer["objects"], - "state": uploaded.model_dump(mode="json", exclude_none=True)}} - state = await _read_snapshot_state(grant) + uploaded = await upload(grant, state.model_dump_json().encode()) + return {**answer, "objects": {**answer["objects"], + "state": uploaded.model_dump(mode="json", exclude_none=True)}} + state = await _read_snapshot_state(grant) + async with self.snapshots_in_flight.holding(request.target_context_id): answer = await invoke() self.task_trajectories.restored(str(answer["context_id"]), state.turns) - return answer + return answer def check_trajectory_format(self, format: str | None) -> None: """Refuse a trajectory read naming a format the card doesn't offer, before any handler @@ -1466,6 +1499,7 @@ def __init__( self._services = services self._workspace = workspace self._streaming = streaming + self._context_locks = _BoundedContextLocks() async def execute(self, context: Any, event_queue: Any) -> None: from a2a.server.tasks import TaskUpdater @@ -1492,7 +1526,7 @@ async def execute(self, context: Any, event_queue: Any) -> None: **_thaw(getattr(context.message, "metadata", None) or {}), **({"role": task_config.role} if task_config.role is not None else {}), } - async with self._services.context_locks.acquire(task.context_id): + async with self._context_locks.acquire(task.context_id): parts = tuple(_from_a2a_part(part) for part in (context.message.parts or [])) turn = None if self._services.serves_atif: @@ -1504,6 +1538,7 @@ async def execute(self, context: Any, event_queue: Any) -> None: agent_version=card.version, agent_model=_config_model(task_config), ) + await self._services.snapshots_in_flight.wait(task.context_id) trajectories.start(task.id, turn) request = TaskRequest( task_id=task.id, diff --git a/packages/agentenv-protocol/tests/test_a2a_atif_turns.py b/packages/agentenv-protocol/tests/test_a2a_atif_turns.py index f0292cbf8..ee812c6f2 100644 --- a/packages/agentenv-protocol/tests/test_a2a_atif_turns.py +++ b/packages/agentenv-protocol/tests/test_a2a_atif_turns.py @@ -43,15 +43,15 @@ _IDENTITY = AgentIdentity(name="toy-agent", description="test", version="2.0") -def _snapshotting(*, atif: Any = Hooks, save_hold: _Hold | None = None) -> AgentEnvAgent: +def _snapshotting(*, atif: Any = Hooks, save_hold: _Hold | None = None, run_hold: _Hold | None = None) -> AgentEnvAgent: """The toy agent with a snapshot extension of its own, whose save and load the SDK's state rides beside; a save - waits at ``save_hold``, as one uploading the conversation it captured would.""" + waits at ``save_hold``, as one uploading the conversation it captured would, and a turn holds at ``run_hold``.""" extensions = (enable(TRAJECTORY_V1, live=True, native=NATIVE, **({"atif": atif} if atif else {})),) @a2a_agent(identity=_IDENTITY, extensions=extensions) class Snapshotting(AgentEnvAgent): async def run(self, request: TaskRequest) -> TaskResult: - return await _turn(request, _Hold()) + return await _turn(request, run_hold or _Hold()) @extension(SNAPSHOT_V1.save) async def save(self, request: ObjectSnapshotSaveRequest) -> ObjectSnapshotSaveResponse: @@ -231,6 +231,28 @@ def test_a_task_waits_for_its_contexts_save_so_the_saved_count_is_its_captures(o assert [user["turn"] for user in _users(document)] == [0, 1, 2] +def test_a_save_while_a_task_runs_is_answered_without_waiting_for_it(objects: dict[str, bytes]) -> None: + running = _Hold() + with TestClient(_snapshotting(run_hold=running).create_app()) as client: + _ended(client, _send(client, "work t1", "m-t1")) + task_id = _send(client, "late t2", "m-t2") + running.reached() + with concurrent.futures.ThreadPoolExecutor(1) as pool: + saving = pool.submit(client.post, "/ext/snapshot", json={"context_id": "ctx-1", "objects": { + "trajectory": _grant("http-put", "trajectory", "application/octet-stream"), + "state": _grant("http-put", "state", "application/json")}}) + try: + saved = saving.result(timeout=5) + finally: + running.resume.set() + running.reached(2) + running.resume.set() + _ended(client, task_id) + assert saved.status_code == 200, saved.text + # The running task started before the capture, so the count has it. + assert json.loads(objects["state"]) == {"turns": 2} + + def test_two_servers_on_one_home_share_its_counts(tmp_path: Path) -> None: first, second = _turn_index.TurnIndex(tmp_path), _turn_index.TurnIndex(tmp_path) assert [first.next("ctx"), second.next("ctx"), first.next("ctx")] == [0, 1, 2] From 07fb16ddc70c405fa2e8fef77655f3ab084ffce5 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan <edgar.arakelyan@scale.com> Date: Thu, 19 Nov 2026 10:20:10 -0800 Subject: [PATCH 4/6] fix(a2a-agent): snapshots with SDK state of one context run one at a 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> --- .../agentenv_protocol/a2a_agent/framework.py | 9 ++++--- .../tests/test_a2a_atif_turns.py | 26 +++++++++++++++++++ 2 files changed, 32 insertions(+), 3 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py index d83a4654a..29baa4d43 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py @@ -252,12 +252,14 @@ def _trim_idle(self) -> None: @dataclass(slots=True) class _InFlight: count: int = 0 + turn: asyncio.Lock = field(default_factory=asyncio.Lock) done: asyncio.Event = field(default_factory=asyncio.Event) class _SnapshotsInFlight: - """Each context's snapshots in flight that carry the SDK's state: a task of the context waits to start until none - is, so the turn count a snapshot saves or restores is its conversation's. A running task isn't held.""" + """Each context's snapshots in flight that carry the SDK's state, taken one at a time: a task of the context waits + to start until none is, so the turn count a snapshot saves or restores is its conversation's, and a load can't + change the count a save is about to read. A running task isn't held.""" def __init__(self) -> None: self._contexts: dict[str, _InFlight] = {} @@ -270,7 +272,8 @@ async def holding(self, context_id: str | None) -> AsyncIterator[None]: entry = self._contexts.setdefault(context_id, _InFlight()) entry.count += 1 try: - yield + async with entry.turn: + yield finally: entry.count -= 1 if not entry.count: diff --git a/packages/agentenv-protocol/tests/test_a2a_atif_turns.py b/packages/agentenv-protocol/tests/test_a2a_atif_turns.py index ee812c6f2..e0bc19551 100644 --- a/packages/agentenv-protocol/tests/test_a2a_atif_turns.py +++ b/packages/agentenv-protocol/tests/test_a2a_atif_turns.py @@ -231,6 +231,32 @@ def test_a_task_waits_for_its_contexts_save_so_the_saved_count_is_its_captures(o assert [user["turn"] for user in _users(document)] == [0, 1, 2] +def test_a_load_into_a_context_waits_for_its_save_so_the_save_keeps_its_count(objects: dict[str, bytes]) -> None: + objects["trajectory"], objects["older-state"] = b"conversation", b'{"turns": 0}' + paused = _Hold() + with TestClient(_snapshotting(save_hold=paused).create_app()) as client: + for tag in ("t1", "t2"): + _ended(client, _send(client, f"work {tag}", f"m-{tag}")) + with concurrent.futures.ThreadPoolExecutor(2) as pool: + saving = pool.submit(client.post, "/ext/snapshot", json={"context_id": "ctx-1", "objects": { + "trajectory": _grant("http-put", "saved-trajectory", "application/octet-stream"), + "state": _grant("http-put", "state", "application/json")}}) + paused.reached() + loading = pool.submit(client.put, "/ext/snapshot", json={"target_context_id": "ctx-1", "objects": { + "trajectory": _grant("http-get", "trajectory", "application/octet-stream"), + "state": _grant("http-get", "older-state", "application/json")}}) + time.sleep(0.3) + paused.resume.set() + saved, loaded = saving.result(timeout=10), loading.result(timeout=10) + task_id = _send(client, "work t3", "m-t3") + _ended(client, task_id) + document = _atif(client, task_id=task_id)["trajectory"] + assert (saved.status_code, loaded.status_code) == (200, 200), (saved.text, loaded.text) + # The save ran first and kept its count; the load then restored the older snapshot's. + assert json.loads(objects["state"]) == {"turns": 2} + assert [user["turn"] for user in _users(document)] == [0] + + def test_a_save_while_a_task_runs_is_answered_without_waiting_for_it(objects: dict[str, bytes]) -> None: running = _Hold() with TestClient(_snapshotting(run_hold=running).create_app()) as client: From 090b824860f870eb0e5a811be0a2dd2781cb2be2 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan <edgar.arakelyan@scale.com> Date: Thu, 19 Nov 2026 10:43:07 -0800 Subject: [PATCH 5/6] fix(a2a-agent): turn counts live in the user's XDG state folder 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> --- packages/agentenv-protocol/README.md | 3 ++- .../src/agentenv_protocol/a2a_agent/_turn_index.py | 11 ++++++++--- packages/agentenv-protocol/tests/conftest.py | 6 ++---- .../tests/test_a2a_atif_serving.py | 3 +-- .../agentenv-protocol/tests/test_a2a_atif_turns.py | 14 +++++++++++++- 5 files changed, 26 insertions(+), 11 deletions(-) diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index 94d480de8..8f0e3a4c7 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1650,7 +1650,8 @@ are unaffected. Each task's user step carries its turn index, the number of tasks its context started before it. The SDK keeps each context's count on disk, under -`~/.local/state/agentenv/turns/`, so a restarted server, or a context it dropped +`agentenv/turns/` in the user's state folder (`$XDG_STATE_HOME`, else +`~/.local/state`), so a restarted server, or a context it dropped from memory, goes on counting in a new document of the same session; a home it can't write keeps the counts in memory, with one warning. A snapshot carries the count in its `state` object, a JSON object that is the SDK's own: on save the diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_turn_index.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_turn_index.py index 9dde7e492..eb822fc23 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_turn_index.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_turn_index.py @@ -14,8 +14,6 @@ logger = logging.getLogger(__name__) -#: Where the counts are kept, one small file per context, under the agent's user's home. -TURNS_DIR = Path.home() / ".local" / "state" / "agentenv" / "turns" #: The snapshot extension's card param naming the fields of the state an SDK keeps in each snapshot: a caller grants #: the ``state`` object only to an agent whose card has it, since an SDK from before it refuses the object. SNAPSHOT_STATE_PARAM = "state" @@ -30,13 +28,20 @@ class SnapshotState(BaseModel): turns: int = Field(ge=0) +def turns_folder() -> Path: + """Where the counts are kept, one small file per context: ``agentenv/turns`` in the user's state folder, + ``$XDG_STATE_HOME`` when it's an absolute path, as the XDG spec has it, else ``~/.local/state``.""" + state = os.environ.get("XDG_STATE_HOME", "") + return (Path(state) if os.path.isabs(state) else Path.home() / ".local" / "state") / "agentenv" / "turns" + + class TurnIndex: """Each context's count of started tasks, read from its file each time, so two servers on one home agree and memory holds nothing per context. A count that can't be written stays in memory, with a warning, so a read-only home costs only the count's survival across a restart.""" def __init__(self, folder: Path | None = None) -> None: - self._folder = folder if folder is not None else TURNS_DIR + self._folder = folder if folder is not None else turns_folder() self._unwritten: dict[str, int] = {} self._warned: set[str] = set() diff --git a/packages/agentenv-protocol/tests/conftest.py b/packages/agentenv-protocol/tests/conftest.py index 7aff4f960..31c1bd806 100644 --- a/packages/agentenv-protocol/tests/conftest.py +++ b/packages/agentenv-protocol/tests/conftest.py @@ -1,10 +1,8 @@ -"""Each test keeps its agents' turn counts in its own folder: the SDK keeps them under the user's home, where one test's +"""Each test keeps its agents' turn counts in its own state folder: the SDK keeps them in the user's, where one test's contexts would go on counting from another's.""" import pytest -from agentenv_protocol.a2a_agent import _turn_index - @pytest.fixture(autouse=True) def _own_turn_counts(tmp_path_factory, monkeypatch): - monkeypatch.setattr(_turn_index, "TURNS_DIR", tmp_path_factory.mktemp("turns")) + monkeypatch.setenv("XDG_STATE_HOME", str(tmp_path_factory.mktemp("state"))) diff --git a/packages/agentenv-protocol/tests/test_a2a_atif_serving.py b/packages/agentenv-protocol/tests/test_a2a_atif_serving.py index 873a76a9d..a79b9fc02 100644 --- a/packages/agentenv-protocol/tests/test_a2a_atif_serving.py +++ b/packages/agentenv-protocol/tests/test_a2a_atif_serving.py @@ -28,7 +28,6 @@ extension, framework, ) -from agentenv_protocol.a2a_agent import _turn_index from agentenv_protocol.a2a_agent import clock as agent_clock from agentenv_protocol.computer import clock as follower from agentenv_protocol.atif import ( @@ -351,7 +350,7 @@ async def capture(_target: Any, body: bytes) -> Uploaded: {"context_id": "ctx-1", "after": 0}, {"task_id": task_id, "objects": {"trajectory": _grant()}})] native_bodies.append(json.loads(json.dumps(bodies).replace(task_id, "TASK"))) # Another agent's container, whose turn counts aren't the first one's. - monkeypatch.setattr(_turn_index, "TURNS_DIR", tmp_path / "another-container") + monkeypatch.setenv("XDG_STATE_HOME", str(tmp_path / "another-container")) with TestClient(_toy().create_app()) as client: task_id = _send(client, "work t1", "m-1") _ended(client, task_id) diff --git a/packages/agentenv-protocol/tests/test_a2a_atif_turns.py b/packages/agentenv-protocol/tests/test_a2a_atif_turns.py index e0bc19551..28f66c5e8 100644 --- a/packages/agentenv-protocol/tests/test_a2a_atif_turns.py +++ b/packages/agentenv-protocol/tests/test_a2a_atif_turns.py @@ -145,7 +145,7 @@ def test_a_snapshot_carries_the_turn_count_to_the_fresh_agent_it_is_restored_int assert saved.json()["objects"]["state"]["size_bytes"] == len(objects["state"]) assert json.loads(objects["state"]) == {"turns": 2} # Another container: none of the first one's counts. - monkeypatch.setattr(_turn_index, "TURNS_DIR", tmp_path / "fresh-agent") + monkeypatch.setenv("XDG_STATE_HOME", str(tmp_path / "fresh-agent")) with TestClient(_snapshotting().create_app()) as client: loaded = client.put("/ext/snapshot", json={"target_context_id": "ctx-restored", "objects": { "trajectory": _grant("http-get", "trajectory", "application/octet-stream"), @@ -279,6 +279,18 @@ def test_a_save_while_a_task_runs_is_answered_without_waiting_for_it(objects: di assert json.loads(objects["state"]) == {"turns": 2} +@pytest.mark.parametrize("state_home, folder", [ + ("{tmp}/state", "{tmp}/state/agentenv/turns"), + ("", "{home}/.local/state/agentenv/turns"), + ("relative/state", "{home}/.local/state/agentenv/turns"), +], ids=["xdg-state-home", "unset", "relative-is-ignored"]) +def test_the_counts_live_in_the_users_state_folder(monkeypatch: pytest.MonkeyPatch, tmp_path: Path, state_home: str, + folder: str) -> None: + monkeypatch.setenv("HOME", str(tmp_path / "home")) + monkeypatch.setenv("XDG_STATE_HOME", state_home.format(tmp=tmp_path)) + assert _turn_index.turns_folder() == Path(folder.format(tmp=tmp_path, home=tmp_path / "home")) + + def test_two_servers_on_one_home_share_its_counts(tmp_path: Path) -> None: first, second = _turn_index.TurnIndex(tmp_path), _turn_index.TurnIndex(tmp_path) assert [first.next("ctx"), second.next("ctx"), first.next("ctx")] == [0, 1, 2] From e9c79c6ae3a3c18fb871b6e02a44d3bd54738808 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan <edgar.arakelyan@scale.com> Date: Thu, 19 Nov 2026 10:57:40 -0800 Subject: [PATCH 6/6] refactor(a2a-agent): the SDK's snapshot state in a module of its own _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> --- .../agentenv_protocol/a2a_agent/__init__.py | 2 +- .../a2a_agent/_snapshot_state.py | 124 ++++++++++++++++++ .../a2a_agent/_trajectory_log.py | 18 +-- .../a2a_agent/_turn_index.py | 20 +-- .../agentenv_protocol/a2a_agent/framework.py | 106 +++------------ .../tests/test_a2a_atif_turns.py | 69 +++++----- 6 files changed, 187 insertions(+), 152 deletions(-) create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_snapshot_state.py diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py index 69c8b8a67..3c0f2c28c 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py @@ -93,7 +93,7 @@ request_fields, ) from .control_token import ControlTokenMiddleware -from ._turn_index import SNAPSHOT_STATE_PARAM +from ._snapshot_state import SNAPSHOT_STATE_PARAM from .framework import ( A2AAgentApplication, AgentEnvAgent, diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_snapshot_state.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_snapshot_state.py new file mode 100644 index 000000000..d9333e39a --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_snapshot_state.py @@ -0,0 +1,124 @@ +"""The SDK's own state in an agent's snapshots: each context's atif/1 turn count. The SDK uploads it after the agent's +save handler and reads it before its load handler, through the request's ``state`` grant, and the card names it, so a +caller grants the object only to an SDK that takes it. While such a snapshot is in flight no task of its context +starts, so the count is the conversation's the agent captured; a running task goes on, as a capture mid-task expects.""" + +from __future__ import annotations + +import asyncio +import tempfile +from collections.abc import AsyncIterator, Awaitable, Callable +from contextlib import asynccontextmanager +from dataclasses import dataclass, field +from pathlib import Path +from typing import Any + +from pydantic import BaseModel, ConfigDict, Field, ValidationError + +from ..errors import AgentEnvError +from ..transfers import download, upload +from ._trajectory_log import TaskTrajectories +from .extensions import SNAPSHOT_V1, ObjectSnapshotLoadRequest, ObjectSnapshotSaveRequest + +#: The snapshot extension's card param naming the fields of the state an SDK keeps in each snapshot: a caller grants +#: the ``state`` object only to an agent whose card has it, since an SDK from before it refuses the object. +SNAPSHOT_STATE_PARAM = "state" + + +class SnapshotState(BaseModel): + """What the SDK keeps in a snapshot beside the agent's own objects: the context's turn count. A newer SDK may add + fields, which an older one reading the snapshot leaves alone.""" + + model_config = ConfigDict(extra="ignore", frozen=True) + + turns: int = Field(ge=0) + + +class SnapshotStates: + """The SDK's state in the snapshots of an agent that serves atif/1.""" + + def __init__(self, trajectories: TaskTrajectories) -> None: + self._trajectories = trajectories + self._in_flight = _InFlightSnapshots() + + @staticmethod + def card_extension(item: dict[str, Any]) -> dict[str, Any]: + """An extension's card entry; the snapshot extension's names the state the SDK keeps.""" + if item.get("uri") != SNAPSHOT_V1.uri: + return item + return {**item, "params": {**item.get("params", {}), SNAPSHOT_STATE_PARAM: list(SnapshotState.model_fields)}} + + async def save(self, request: Any, invoke: Callable[[], Awaitable[dict[str, Any]]]) -> dict[str, Any]: + """The agent's save, then the context's count uploaded through the ``state`` grant and named in the answer. A + request that grants no state is the agent's alone.""" + if not isinstance(request, ObjectSnapshotSaveRequest) or request.objects.state is None: + return await invoke() + async with self._in_flight.holding(request.context_id): + answer = await invoke() + state = SnapshotState(turns=self._trajectories.turns(request.context_id)) + uploaded = await upload(request.objects.state, state.model_dump_json().encode()) + return {**answer, "objects": {**answer["objects"], "state": uploaded.model_dump(mode="json", exclude_none=True)}} + + async def load(self, request: Any, invoke: Callable[[], Awaitable[dict[str, Any]]]) -> dict[str, Any]: + """The state the snapshot carries, read before the agent's load, then the context the agent restored into + seeded with its count. A request that grants no state is the agent's alone.""" + if not isinstance(request, ObjectSnapshotLoadRequest) or request.objects.state is None: + return await invoke() + state = await _read(request.objects.state) + async with self._in_flight.holding(request.target_context_id): + answer = await invoke() + self._trajectories.restored(str(answer["context_id"]), state.turns) + return answer + + async def task_may_start(self, context_id: str) -> None: + """Wait until no snapshot of the context is in flight.""" + await self._in_flight.wait(context_id) + + +async def _read(grant: Any) -> SnapshotState: + with tempfile.TemporaryDirectory() as folder: + path = Path(folder) / "state.json" + await download(grant, path) + try: + return SnapshotState.model_validate_json(path.read_bytes()) + except ValidationError as exc: + raise AgentEnvError( + "snapshot_state_invalid", + f"the snapshot's state object isn't the SDK's snapshot state: {exc.errors()[0]['msg']}", + status=400, + ) from exc + + +@dataclass(slots=True) +class _InFlight: + count: int = 0 + turn: asyncio.Lock = field(default_factory=asyncio.Lock) + done: asyncio.Event = field(default_factory=asyncio.Event) + + +class _InFlightSnapshots: + """Each context's snapshots in flight, taken one at a time, so a load can't change the count a save is about to + read, and a task of the context waits to start until none is.""" + + def __init__(self) -> None: + self._contexts: dict[str, _InFlight] = {} + + @asynccontextmanager + async def holding(self, context_id: str | None) -> AsyncIterator[None]: + if context_id is None: + yield + return + entry = self._contexts.setdefault(context_id, _InFlight()) + entry.count += 1 + try: + async with entry.turn: + yield + finally: + entry.count -= 1 + if not entry.count: + del self._contexts[context_id] + entry.done.set() + + async def wait(self, context_id: str) -> None: + while (entry := self._contexts.get(context_id)) is not None: + await entry.done.wait() diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_trajectory_log.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_trajectory_log.py index 5a158262f..4d108b918 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_trajectory_log.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_trajectory_log.py @@ -87,14 +87,14 @@ def __init__( *, native: str | None = None, atif: type[Adapter] | None = None, - turns: TurnIndex | None = None, ) -> None: if max_contexts < 1: raise ValueError("max_contexts must be positive") self._max_contexts = max_contexts self._native = native self._atif = atif - self._turns = turns if turns is not None else TurnIndex() if atif is not None else None + #: Each context's count of started tasks, kept only for an agent that serves atif/1. + self._turns = TurnIndex() if atif is not None else None self._tasks: dict[str, _TaskRecord] = {} self._contexts: OrderedDict[str, list[str]] = OrderedDict() self._copies: dict[str, AtifCopy] = {} @@ -126,7 +126,7 @@ def start(self, task_id: str, turn: TurnStart | None = None) -> None: started = sum(1 for other in order if self._tasks[other].started) order.insert(started, task_id) record.started = True - if self._atif is not None and self._turns is not None and turn is not None: + if self._atif is not None and turn is not None: copy = self._copies.get(record.context_id) if copy is None: copy = self._copies[record.context_id] = AtifCopy(self._atif, record.context_id) @@ -135,15 +135,15 @@ def start(self, task_id: str, turn: TurnStart | None = None) -> None: self._touch(record.context_id) def turns(self, context_id: str) -> int: - """How many tasks the context has started, the count a snapshot of it carries.""" - return self._turns.count(context_id) if self._turns is not None else 0 + """How many tasks the context has started, the count a snapshot of it carries; an agent that serves atif/1 + only.""" + return self._turns.count(context_id) def restored(self, context_id: str, turns: int) -> None: """A snapshot was restored into the context: its count goes on from the snapshot's, and its next task starts a - new document, since the conversation is the snapshot's now.""" - if self._turns is not None: - self._turns.set(context_id, turns) - self._copies.pop(context_id, None) + new document, since the conversation is the snapshot's now; an agent that serves atif/1 only.""" + self._turns.set(context_id, turns) + self._copies.pop(context_id, None) def request_cancel(self, task_id: str) -> None: """Make ``canceled`` the outcome the task is sealed with, whatever ``run`` returns.""" diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_turn_index.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_turn_index.py index eb822fc23..c167d8b06 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_turn_index.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_turn_index.py @@ -1,11 +1,10 @@ """Each A2A context's turn count, kept on disk by the SDK, so a restarted server, or a context evicted from memory, goes -on counting where it was, and a snapshot carries it to the context it is restored into. Only an agent that serves -atif/1 keeps one: the count is its ATIF copy's turn index.""" +on counting where it was. Only an agent that serves atif/1 keeps one: the count is its ATIF copy's turn index, which a +snapshot carries too (``_snapshot_state``).""" from __future__ import annotations import hashlib -import json import logging import os from pathlib import Path @@ -14,17 +13,12 @@ logger = logging.getLogger(__name__) -#: The snapshot extension's card param naming the fields of the state an SDK keeps in each snapshot: a caller grants -#: the ``state`` object only to an agent whose card has it, since an SDK from before it refuses the object. -SNAPSHOT_STATE_PARAM = "state" - - -class SnapshotState(BaseModel): - """What the SDK keeps in a snapshot beside the agent's own objects: the context's turn count. A newer SDK may add - fields, which an older one reading the snapshot leaves alone.""" +class _CountFile(BaseModel): + """One context's count on disk, named by the context id's sha256; the id is kept for whoever reads the folder.""" model_config = ConfigDict(extra="ignore", frozen=True) + context_id: str turns: int = Field(ge=0) @@ -55,7 +49,7 @@ def count(self, context_id: str) -> int: if context_id in self._unwritten: return self._unwritten[context_id] try: - return SnapshotState.model_validate_json(self._path(context_id).read_bytes()).turns + return _CountFile.model_validate_json(self._path(context_id).read_bytes()).turns except FileNotFoundError: return 0 except (OSError, ValueError) as exc: @@ -67,7 +61,7 @@ def set(self, context_id: str, count: int) -> None: try: path.parent.mkdir(parents=True, exist_ok=True) part = path.with_suffix(".part") - part.write_text(json.dumps({"context_id": context_id, "turns": count})) + part.write_text(_CountFile(context_id=context_id, turns=count).model_dump_json()) os.replace(part, path) except OSError as exc: self._warn("turn counts are kept in memory only, so a restart starts them again: %s", exc) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py index 29baa4d43..cb311637d 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py @@ -8,10 +8,9 @@ import json import logging import os -import tempfile import uuid from collections import OrderedDict -from collections.abc import Awaitable, Callable, Iterable, Mapping +from collections.abc import Callable, Iterable, Mapping from contextlib import AbstractAsyncContextManager, asynccontextmanager from dataclasses import dataclass, field from pathlib import Path @@ -35,7 +34,7 @@ from ..atif import PROFILE_VERSION as ATIF_PROFILE_VERSION from ..atif import SCHEMA_VERSION as ATIF_SCHEMA_VERSION from ._atif_copy import TurnStart -from ._turn_index import SNAPSHOT_STATE_PARAM, SnapshotState +from ._snapshot_state import SnapshotStates from ._trajectory_log import MAX_TRAJECTORY_READ_BYTES, TaskTrajectories from ._triggers import TriggerEngine, TriggerError from .extensions import ( @@ -101,7 +100,7 @@ from .tasks.v1 import ( TextPart as TaskTextPart, ) -from ..transfers import TransferError, download, serving_on, upload +from ..transfers import TransferError, serving_on, upload logger = logging.getLogger(__name__) @@ -146,21 +145,6 @@ def _config_wire_names(config: type[AgentConfig]) -> dict[str, str]: return result -async def _read_snapshot_state(grant: Any) -> SnapshotState: - """The SDK's state a snapshot carries, read through its ``state`` grant.""" - with tempfile.TemporaryDirectory() as folder: - path = Path(folder) / "state.json" - await download(grant, path) - try: - return SnapshotState.model_validate_json(path.read_bytes()) - except ValidationError as exc: - raise AgentEnvError( - "snapshot_state_invalid", - f"the snapshot's state object isn't the SDK's snapshot state: {exc.errors()[0]['msg']}", - status=400, - ) from exc - - def _config_write_only_wire_names(config: type[AgentConfig]) -> set[str]: """Return wire names explicitly marked as write-only in the config schema.""" wire_names = _config_wire_names(config) @@ -249,42 +233,6 @@ def _trim_idle(self) -> None: return -@dataclass(slots=True) -class _InFlight: - count: int = 0 - turn: asyncio.Lock = field(default_factory=asyncio.Lock) - done: asyncio.Event = field(default_factory=asyncio.Event) - - -class _SnapshotsInFlight: - """Each context's snapshots in flight that carry the SDK's state, taken one at a time: a task of the context waits - to start until none is, so the turn count a snapshot saves or restores is its conversation's, and a load can't - change the count a save is about to read. A running task isn't held.""" - - def __init__(self) -> None: - self._contexts: dict[str, _InFlight] = {} - - @asynccontextmanager - async def holding(self, context_id: str | None) -> AsyncIterator[None]: - if context_id is None: - yield - return - entry = self._contexts.setdefault(context_id, _InFlight()) - entry.count += 1 - try: - async with entry.turn: - yield - finally: - entry.count -= 1 - if not entry.count: - del self._contexts[context_id] - entry.done.set() - - async def wait(self, context_id: str) -> None: - while (entry := self._contexts.get(context_id)) is not None: - await entry.done.wait() - - class AgentEnvAgent: """Typed base class for AgentEnv-compatible A2A agents.""" @@ -633,7 +581,8 @@ def __init__( self.task_trajectories = TaskTrajectories(native=native, atif=atif) #: Whether the card offers atif/1, served from the copy an adapter builds. self.serves_atif = atif is not None - self.snapshots_in_flight = _SnapshotsInFlight() + #: The SDK's state in the agent's snapshots, which only an agent that serves atif/1 keeps. + self.snapshot_states = SnapshotStates(self.task_trajectories) if atif is not None else None self._context_sessions = _BoundedContextSessions() self.skills: list[Mapping[str, Any]] = [] self.identity_skills: dict[str, str] = {} @@ -997,34 +946,6 @@ async def _atif_document( ) return AtifObjectsResponse(objects=uploaded, **versions).model_dump(mode="json", exclude_none=True) - def card_extension(self, item: dict[str, Any]) -> dict[str, Any]: - """An extension's card entry, with what the SDK adds: an agent that serves atif/1 names the state its SDK - keeps in each snapshot, so a caller grants the object only to an SDK that takes it.""" - if self.serves_atif and item.get("uri") == SNAPSHOT_V1.uri: - return {**item, "params": {**item.get("params", {}), SNAPSHOT_STATE_PARAM: list(SnapshotState.model_fields)}} - return item - - async def snapshot(self, name: str, request: Any, invoke: Callable[[], Awaitable[Any]]) -> Any: - """An agent's snapshot ``save`` or ``load``, with the SDK's state, the context's turn count, uploaded after a - save and read before a load through the request's ``state`` grant. While one is in flight no task of its - context starts, so the count is the conversation's the agent captured; a running task goes on, as a capture - mid-task expects.""" - grant = getattr(getattr(request, "objects", None), "state", None) - if not self.serves_atif or grant is None: - return await invoke() - if name == "save": - async with self.snapshots_in_flight.holding(request.context_id): - answer = await invoke() - state = SnapshotState(turns=self.task_trajectories.turns(request.context_id)) - uploaded = await upload(grant, state.model_dump_json().encode()) - return {**answer, "objects": {**answer["objects"], - "state": uploaded.model_dump(mode="json", exclude_none=True)}} - state = await _read_snapshot_state(grant) - async with self.snapshots_in_flight.holding(request.target_context_id): - answer = await invoke() - self.task_trajectories.restored(str(answer["context_id"]), state.turns) - return answer - def check_trajectory_format(self, format: str | None) -> None: """Refuse a trajectory read naming a format the card doesn't offer, before any handler runs, the agent's own included.""" @@ -1359,8 +1280,9 @@ def _build_card(self) -> Any: skill if isinstance(skill, AgentSkill) else AgentSkill.model_validate(skill) for skill in identity.skills ] + states = self.services.snapshot_states extensions = [ - AgentExtension.model_validate(self.services.card_extension(item)) + AgentExtension.model_validate(states.card_extension(item) if states is not None else item) for item in self.registry.card_extensions() ] if self.staging.max_bytes: @@ -1464,10 +1386,13 @@ async def invoke_and_validate() -> Any: ): async with self.services.skill_registration(input_payload): result = await invoke_and_validate() - elif extension_uri == SNAPSHOT_V1.uri and operation.definition.name in ("save", "load"): - result = await self.services.snapshot( - operation.definition.name, extension_request, invoke_and_validate - ) + elif ( + (states := self.services.snapshot_states) is not None + and extension_uri == SNAPSHOT_V1.uri + and operation.definition.name in ("save", "load") + ): + take = states.save if operation.definition.name == "save" else states.load + result = await take(extension_request, invoke_and_validate) else: result = await invoke_and_validate() return JSONResponse(result) @@ -1541,7 +1466,8 @@ async def execute(self, context: Any, event_queue: Any) -> None: agent_version=card.version, agent_model=_config_model(task_config), ) - await self._services.snapshots_in_flight.wait(task.context_id) + if self._services.snapshot_states is not None: + await self._services.snapshot_states.task_may_start(task.context_id) trajectories.start(task.id, turn) request = TaskRequest( task_id=task.id, diff --git a/packages/agentenv-protocol/tests/test_a2a_atif_turns.py b/packages/agentenv-protocol/tests/test_a2a_atif_turns.py index 28f66c5e8..5645ff1e4 100644 --- a/packages/agentenv-protocol/tests/test_a2a_atif_turns.py +++ b/packages/agentenv-protocol/tests/test_a2a_atif_turns.py @@ -33,9 +33,8 @@ a2a_agent, enable, extension, - framework, ) -from agentenv_protocol.a2a_agent import _turn_index +from agentenv_protocol.a2a_agent import _snapshot_state, _turn_index from agentenv_protocol.a2a_agent._atif_copy import TurnStart from agentenv_protocol.a2a_agent._trajectory_log import TaskTrajectories from agentenv_protocol.atif import errors_in, validate @@ -74,6 +73,20 @@ def _grant(kind: str, name: str, media_type: str) -> dict[str, Any]: access: {"kind": kind, "url": f"https://objects.example.test/{name}", "expires_at": expires}} +def _save(client: TestClient, *, state_type: str = "application/json") -> Any: + """A snapshot save of ``ctx-1`` granting its trajectory and the SDK's state, which lands at ``state``.""" + return client.post("/ext/snapshot", json={"context_id": "ctx-1", "objects": { + "trajectory": _grant("http-put", "trajectory", "application/octet-stream"), + "state": _grant("http-put", "state", state_type)}}) + + +def _load(client: TestClient, target: str, *, state: str = "state") -> Any: + """A snapshot load into ``target`` from the stored trajectory and the SDK's state stored at ``state``.""" + return client.put("/ext/snapshot", json={"target_context_id": target, "objects": { + "trajectory": _grant("http-get", "trajectory", "application/octet-stream"), + "state": _grant("http-get", state, "application/json")}}) + + def _users(document: dict[str, Any]) -> list[dict[str, Any]]: return [step["extra"]["agentenv"] for step in document["steps"] if step["source"] == "user"] @@ -90,8 +103,8 @@ async def upload(target, body: bytes) -> Uploaded: async def download(source, destination: Path) -> None: destination.write_bytes(stored[source.read.url.rsplit("/", 1)[-1]]) - monkeypatch.setattr(framework, "upload", upload) - monkeypatch.setattr(framework, "download", download) + monkeypatch.setattr(_snapshot_state, "upload", upload) + monkeypatch.setattr(_snapshot_state, "download", download) return stored @@ -138,18 +151,14 @@ def test_a_snapshot_carries_the_turn_count_to_the_fresh_agent_it_is_restored_int with TestClient(_snapshotting().create_app()) as client: for tag in ("t1", "t2"): _ended(client, _send(client, f"work {tag}", f"m-{tag}")) - saved = client.post("/ext/snapshot", json={"context_id": "ctx-1", "objects": { - "trajectory": _grant("http-put", "trajectory", "application/octet-stream"), - "state": _grant("http-put", "state", "application/json")}}) + saved = _save(client) assert saved.status_code == 200, saved.text assert saved.json()["objects"]["state"]["size_bytes"] == len(objects["state"]) assert json.loads(objects["state"]) == {"turns": 2} # Another container: none of the first one's counts. monkeypatch.setenv("XDG_STATE_HOME", str(tmp_path / "fresh-agent")) with TestClient(_snapshotting().create_app()) as client: - loaded = client.put("/ext/snapshot", json={"target_context_id": "ctx-restored", "objects": { - "trajectory": _grant("http-get", "trajectory", "application/octet-stream"), - "state": _grant("http-get", "state", "application/json")}}) + loaded = _load(client, "ctx-restored") assert loaded.status_code == 200, loaded.text task_id = _send(client, "work t3", "m-t3", context_id="ctx-restored") _ended(client, task_id) @@ -162,15 +171,11 @@ def test_a_snapshot_carries_the_turn_count_to_the_fresh_agent_it_is_restored_int def test_a_restore_into_a_context_the_agent_holds_starts_a_new_document(objects: dict[str, bytes]) -> None: with TestClient(_snapshotting().create_app()) as client: _ended(client, _send(client, "work t1", "m-t1")) - client.post("/ext/snapshot", json={"context_id": "ctx-1", "objects": { - "trajectory": _grant("http-put", "trajectory", "application/octet-stream"), - "state": _grant("http-put", "state", "application/json")}}) + _save(client) task_id = _send(client, "work t2", "m-t2") _ended(client, task_id) before = _atif(client, task_id=task_id)["trajectory"] - client.put("/ext/snapshot", json={"target_context_id": "ctx-1", "objects": { - "trajectory": _grant("http-get", "trajectory", "application/octet-stream"), - "state": _grant("http-get", "state", "application/json")}}) + _load(client, "ctx-1") task_id = _send(client, "work t3", "m-t3") _ended(client, task_id) after = _atif(client, task_id=task_id)["trajectory"] @@ -181,19 +186,15 @@ def test_a_restore_into_a_context_the_agent_holds_starts_a_new_document(objects: def test_a_snapshot_state_that_isnt_the_sdks_is_refused(objects: dict[str, bytes]) -> None: - objects["trajectory"], objects["state"] = b"conversation", b'{"turns": -1}' + objects["state"] = b'{"turns": -1}' with TestClient(_snapshotting().create_app()) as client: - refused = client.put("/ext/snapshot", json={"target_context_id": "ctx-restored", "objects": { - "trajectory": _grant("http-get", "trajectory", "application/octet-stream"), - "state": _grant("http-get", "state", "application/json")}}) + refused = _load(client, "ctx-restored") assert refused.status_code == 400 and refused.json()["error"]["code"] == "snapshot_state_invalid", refused.text def test_an_agent_that_serves_no_atif_writes_no_state(objects: dict[str, bytes]) -> None: with TestClient(_snapshotting(atif=None).create_app()) as client: - saved = client.post("/ext/snapshot", json={"context_id": "ctx-1", "objects": { - "trajectory": _grant("http-put", "trajectory", "application/octet-stream"), - "state": _grant("http-put", "state", "application/json")}}) + saved = _save(client) assert saved.status_code == 200, saved.text assert "state" not in saved.json()["objects"] and "state" not in objects @@ -214,9 +215,7 @@ def test_a_task_waits_for_its_contexts_save_so_the_saved_count_is_its_captures(o for tag in ("t1", "t2"): _ended(client, _send(client, f"work {tag}", f"m-{tag}")) with concurrent.futures.ThreadPoolExecutor(1) as pool: - saving = pool.submit(client.post, "/ext/snapshot", json={"context_id": "ctx-1", "objects": { - "trajectory": _grant("http-put", "trajectory", "application/octet-stream"), - "state": _grant("http-put", "state", "application/json")}}) + saving = pool.submit(_save, client) paused.reached() task_id = _send(client, "work t3", "m-t3") time.sleep(0.3) @@ -232,19 +231,15 @@ def test_a_task_waits_for_its_contexts_save_so_the_saved_count_is_its_captures(o def test_a_load_into_a_context_waits_for_its_save_so_the_save_keeps_its_count(objects: dict[str, bytes]) -> None: - objects["trajectory"], objects["older-state"] = b"conversation", b'{"turns": 0}' + objects["older-state"] = b'{"turns": 0}' paused = _Hold() with TestClient(_snapshotting(save_hold=paused).create_app()) as client: for tag in ("t1", "t2"): _ended(client, _send(client, f"work {tag}", f"m-{tag}")) with concurrent.futures.ThreadPoolExecutor(2) as pool: - saving = pool.submit(client.post, "/ext/snapshot", json={"context_id": "ctx-1", "objects": { - "trajectory": _grant("http-put", "saved-trajectory", "application/octet-stream"), - "state": _grant("http-put", "state", "application/json")}}) + saving = pool.submit(_save, client) paused.reached() - loading = pool.submit(client.put, "/ext/snapshot", json={"target_context_id": "ctx-1", "objects": { - "trajectory": _grant("http-get", "trajectory", "application/octet-stream"), - "state": _grant("http-get", "older-state", "application/json")}}) + loading = pool.submit(_load, client, "ctx-1", state="older-state") time.sleep(0.3) paused.resume.set() saved, loaded = saving.result(timeout=10), loading.result(timeout=10) @@ -264,9 +259,7 @@ def test_a_save_while_a_task_runs_is_answered_without_waiting_for_it(objects: di task_id = _send(client, "late t2", "m-t2") running.reached() with concurrent.futures.ThreadPoolExecutor(1) as pool: - saving = pool.submit(client.post, "/ext/snapshot", json={"context_id": "ctx-1", "objects": { - "trajectory": _grant("http-put", "trajectory", "application/octet-stream"), - "state": _grant("http-put", "state", "application/json")}}) + saving = pool.submit(_save, client) try: saved = saving.result(timeout=5) finally: @@ -307,9 +300,7 @@ def test_a_count_that_cant_be_read_starts_again_with_a_warning(tmp_path: Path, c def test_a_snapshot_state_grant_names_json() -> None: with TestClient(_snapshotting().create_app()) as client: - refused = client.post("/ext/snapshot", json={"context_id": "ctx-1", "objects": { - "trajectory": _grant("http-put", "trajectory", "application/octet-stream"), - "state": _grant("http-put", "state", "application/octet-stream")}}) + refused = _save(client, state_type="application/octet-stream") assert refused.status_code == 400 and "state media_type" in refused.text