Skip to content
Merged
22 changes: 21 additions & 1 deletion packages/agentenv-protocol/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,7 @@
request_fields,
)
from .control_token import ControlTokenMiddleware
from ._snapshot_state import SNAPSHOT_STATE_PARAM
from .framework import (
A2AAgentApplication,
AgentEnvAgent,
Expand Down Expand Up @@ -153,6 +154,7 @@
"PEER_AGENTS_V1",
"REPORTED_USAGE_KEY",
"SKILL_CONFIG_V1",
"SNAPSHOT_STATE_PARAM",
"SNAPSHOT_V1",
"STAGING_ENDPOINT",
"STAGING_V1_URI",
Expand Down
Original file line number Diff line number Diff line change
@@ -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()
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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] = {}
Expand All @@ -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]
Expand All @@ -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)
Expand Down
Original file line number Diff line number Diff line change
@@ -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)
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand All @@ -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)

Expand All @@ -320,6 +329,7 @@ class ObjectSnapshotLoadRequest(ExtensionRequest):
class SnapshotUploadedObjects(ExtensionResponse):
trajectory: Uploaded
workspace: Uploaded | None = None
state: Uploaded | None = None


class ObjectSnapshotSaveResponse(ExtensionResponse):
Expand Down
Loading
Loading