diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index d359234ed..8f0e3a4c7 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1648,6 +1648,24 @@ 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 +`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 +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. 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. + `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 +1801,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/__init__.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py index 2c47dc6ad..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,6 +93,7 @@ request_fields, ) from .control_token import ControlTokenMiddleware +from ._snapshot_state 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/_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 ba107b17d..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 @@ -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 @@ -92,6 +93,8 @@ def __init__( self._max_contexts = max_contexts self._native = native self._atif = atif + #: 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] = {} @@ -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] @@ -126,10 +130,21 @@ def start(self, task_id: str, turn: TurnStart | None = None) -> 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; 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; 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.""" 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..c167d8b06 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_turn_index.py @@ -0,0 +1,78 @@ +"""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. 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 logging +import os +from pathlib import Path + +from pydantic import BaseModel, ConfigDict, Field + +logger = logging.getLogger(__name__) + +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) + + +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_folder() + 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.""" + index = self.count(context_id) + self.set(context_id, index + 1) + return index + + def count(self, context_id: str) -> int: + if context_id in self._unwritten: + return self._unwritten[context_id] + try: + return _CountFile.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: + path = self._path(context_id) + try: + path.parent.mkdir(parents=True, exist_ok=True) + part = path.with_suffix(".part") + 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) + 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, 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/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..cb311637d 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py @@ -34,6 +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 ._snapshot_state import SnapshotStates from ._trajectory_log import MAX_TRAJECTORY_READ_BYTES, TaskTrajectories from ._triggers import TriggerEngine, TriggerError from .extensions import ( @@ -43,6 +44,7 @@ MCP_CONFIG_V1, PEER_AGENTS_V1, SKILL_CONFIG_V1, + SNAPSHOT_V1, TRAJECTORY_V1, TRIGGERS_V1, CLOCK_V1, @@ -579,6 +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 + #: 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] = {} @@ -1276,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(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: @@ -1381,6 +1386,13 @@ async def invoke_and_validate() -> Any: ): async with self.services.skill_registration(input_payload): result = await 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) @@ -1454,6 +1466,8 @@ async def execute(self, context: Any, event_queue: Any) -> None: agent_version=card.version, agent_model=_config_model(task_config), ) + 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/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..31c1bd806 --- /dev/null +++ b/packages/agentenv-protocol/tests/conftest.py @@ -0,0 +1,8 @@ +"""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 + + +@pytest.fixture(autouse=True) +def _own_turn_counts(tmp_path_factory, monkeypatch): + 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 2f7ba9715..a79b9fc02 100644 --- a/packages/agentenv-protocol/tests/test_a2a_atif_serving.py +++ b/packages/agentenv-protocol/tests/test_a2a_atif_serving.py @@ -332,7 +332,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 +349,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.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 new file mode 100644 index 000000000..5645ff1e4 --- /dev/null +++ b/packages/agentenv-protocol/tests/test_a2a_atif_turns.py @@ -0,0 +1,313 @@ +"""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 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, _state, _turn + +from agentenv_protocol.a2a_agent import ( + SNAPSHOT_STATE_PARAM, + SNAPSHOT_V1, + TRAJECTORY_V1, + AgentEnvAgent, + AgentIdentity, + ObjectSnapshotLoadRequest, + ObjectSnapshotLoadResponse, + ObjectSnapshotSaveRequest, + ObjectSnapshotSaveResponse, + SnapshotUploadedObjects, + TaskRequest, + TaskResult, + TextPart, + TrajectoryState, + Uploaded, + a2a_agent, + enable, + extension, +) +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 + +_IDENTITY = AgentIdentity(name="toy-agent", description="test", version="2.0") + + +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, 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, run_hold or _Hold()) + + @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))) + + @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 _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"] + + +@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(_snapshot_state, "upload", upload) + monkeypatch.setattr(_snapshot_state, "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 = _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 = _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) + 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")) + _save(client) + task_id = _send(client, "work t2", "m-t2") + _ended(client, task_id) + before = _atif(client, task_id=task_id)["trajectory"] + _load(client, "ctx-1") + 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["state"] = b'{"turns": -1}' + with TestClient(_snapshotting().create_app()) as client: + 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 = _save(client) + assert saved.status_code == 200, saved.text + 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(_save, client) + 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_a_load_into_a_context_waits_for_its_save_so_the_save_keeps_its_count(objects: dict[str, bytes]) -> None: + 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(_save, client) + paused.reached() + 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) + 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: + _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(_save, client) + 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} + + +@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] + + +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 = _save(client, state_type="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..915375304 100644 --- a/src/agent_env/a2a_agent/a2a_agent.py +++ b/src/agent_env/a2a_agent/a2a_agent.py @@ -11,7 +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.a2a_agent import SNAPSHOT_STATE_PARAM, STANDARD_EXTENSIONS from agentenv_protocol.types import CONTROL_TOKEN_ENV from agent_env.config import get_config @@ -181,6 +181,13 @@ def find_extension(card: dict, uri: str) -> dict | None: return ext return None + @staticmethod + 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: """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..c1a2aea34 100644 --- a/src/agent_env/a2a_agent/object_transfer.py +++ b/src/agent_env/a2a_agent/object_transfer.py @@ -91,12 +91,17 @@ 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, 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. _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 +450,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's SDK keeps one (``A2AAgent.keeps_snapshot_state``).""" _require_object_form( method, ObjectSnapshotSaveRequest, @@ -458,10 +465,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 +486,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 +504,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 +516,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..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,6 +96,7 @@ async def capture_workspace( context_id=a2a_context_id, capture_prefix=capture_prefix, sandbox_type=sandbox_type, + 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 6e7b513c5..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,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.keeps_snapshot_state(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..30fb16d52 --- /dev/null +++ b/tst/unit/a2a_agent/snapshot_state_test.py @@ -0,0 +1,140 @@ +"""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, + 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 _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] + + +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_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("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.keeps_snapshot_state(card), + ) + + objects = call.payload["objects"] + 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. + assert _nulls(call.payload) == [] + + +@pytest.mark.parametrize( + "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, 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.keeps_snapshot_state(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)