diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index 09e21129b..d359234ed 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1598,6 +1598,56 @@ the most recent format its tasks set. Readers trust a response's `format` over the card. An agent that binds its own context reads should name, in their responses, the format it serves. +#### Serving ATIF (`atif/1`) + +`atif` names the agent's ATIF adapter, an `@atif_adapter` class from +`agentenv_protocol.atif` that reads the `native` format: + +```python +enable(TRAJECTORY_V1, live=True, native="my-cli-events/1", atif=MyCliAtif) +``` + +The card then lists `atif/1` in `formats` too; `default` stays `native`. The +SDK keeps one ATIF document per A2A context, run through one adapter instance, +and feeds it every event the agent appends, as it appends it. A native +trajectory returned at task end runs through the adapter then. The agent's own +code feeds the adapter's aux files, records that aren't in the native log such +as a hook's notes, with `request.trajectory.aux(name, record)`, where they +happened among the events. An agent with an adapter that both appends events and +returns a native trajectory fails the turn with code +`framework.trajectory_appended_and_returned`, since its ATIF copy would come +from one of them and its native record from the other. + +The SDK writes each task's user step from the inbound message and its final +response from the result, both as [PROFILE.md](src/agentenv_protocol/atif/PROFILE.md) +says, stamped on the clock the agent's programs read: the universe's when the +agent follows the env's clock, though the server itself stays on real time. `session_id` is the A2A context id, and `trajectory_id` names the document. +Reads naming `atif/1` are served by the SDK, context reads an agent binds +included: + +- A task read returns the context's document as it stood when the task ended, + with `aux`, the task's aux log (each record with `after`, the number of events + before it), and `turn_context`, its TurnContext and how it ended: an + `AuxEntry` each and a `ServedTurn`, both in `agentenv_protocol.atif`. With + those and the native events, `RecordedTask.from_served` and `replay` rebuild + the document offline. In the objects form, `aux` and `turn_context` are optional + grants beside `trajectory`, uploaded only when given; other reads refuse them. +- A context read returns the live page: every step that has closed and whose + calls are all answered, up to the first that isn't. +- A cursor read pages those closed steps by `step_id`: `after` is the last + `step_id` read, and `next` is the last one served. Each page carries `header`, + the document's root without its steps (with `final_metrics` once no task is + open), and `subagents`, the embedded + sub-agent trajectories of the tasks its steps belong to, as far as each is + served. A sub-agent can gain steps while its task runs, so keep each one's + latest copy; the page that serves a task's last step, which closes only as the + task ends, carries them whole. + +Every `atif/1` answer names `schema_version` and `profile_version` beside +`format`. An adapter that raises stops its context's copy, never the turn: the +copy's reads then answer HTTP 409 with code `atif_unavailable`, and native reads +are unaffected. + `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 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 d679c4085..2c47dc6ad 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py @@ -78,6 +78,9 @@ TaskTrajectoryRequest, TrajectoryEventsResponse, TrajectoryObjectsResponse, + AtifEventsResponse, + AtifObjectsResponse, + AtifUploadedObjects, TrajectoryState, TrajectoryUploadedObjects, TrajectoryWriteObjects, @@ -247,6 +250,9 @@ "TaskTrajectoryRequest", "TextPart", "TrajectoryEventsResponse", + "AtifEventsResponse", + "AtifObjectsResponse", + "AtifUploadedObjects", "TrajectoryLog", "TrajectoryObjectsResponse", "TrajectoryState", diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_atif_copy.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_atif_copy.py new file mode 100644 index 000000000..47f3e4749 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_atif_copy.py @@ -0,0 +1,267 @@ +"""The SDK's atif/1 copy of an A2A context: one adapter run per context, fed every native and aux record as the agent +writes it, and read as a task's document, the context's live page or a cursor page. An adapter that fails stops that +context's copy, never the agent's turn.""" + +from __future__ import annotations + +import base64 +import binascii +import json +import logging +import threading +import uuid +from contextlib import contextmanager +from dataclasses import dataclass, field +from datetime import datetime, timezone +from typing import Any, Iterable, Iterator, Sequence +from urllib.parse import urlsplit, urlunsplit + +from ..atif import FORMAT, Adapter, AdapterRun, AuxEntry, Media, ServedTurn, TurnContext +from ..computer import clock as follower +from ..errors import AgentEnvError +from . import clock as agent_clock +from .tasks.v1 import DataPart, FilePart, TaskError, TextPart, _thaw + +logger = logging.getLogger(__name__) + +#: The DataPart key ``add_structured_output`` writes: its value is the task's answer, so it is written as text. +STRUCTURED_OUTPUT = "structured_output" +#: How a context's copy answers once its adapter failed: the request was fine, the copy can't be served. +UNAVAILABLE_STATUS = 409 + + +@dataclass(frozen=True, slots=True, kw_only=True) +class TurnStart: + """What the SDK knows of a task as it starts, beside its ids: the inbound message and the agent.""" + + message_id: str | None + parts: Sequence[Any] + agent_name: str | None + agent_version: str | None + agent_model: str | None + + +@dataclass(slots=True) +class _Task: + place: int + context: TurnContext + natives: int = 0 + aux: list[AuxEntry] = field(default_factory=list) + turn: ServedTurn | None = None + ended: bool = False + + +@dataclass(frozen=True, slots=True) +class AtifPage: + """A cursor page of a copy: the closed steps after ``after``, ``next`` the last one's ``step_id``, and the + sub-agents of their tasks.""" + + header: dict[str, Any] | None + subagents: list[dict[str, Any]] + steps: list[dict[str, Any]] + next: int + has_more: bool + + +class AtifCopy: + """One A2A context's atif/1 document. Safe to feed from the agent's thread while the loop reads it.""" + + def __init__(self, adapter: type[Adapter], context_id: str) -> None: + self._run = AdapterRun(adapter, trajectory_id=uuid.uuid4().hex) + self._adapter = adapter.__name__ + self._context_id = context_id + self._lock = threading.Lock() + self._tasks: dict[str, _Task] = {} + self._failed: str | None = None + # The steps the SDK writes keep the clock the adapter's steps come from: an agent that follows the env's clock + # runs its programs on the universe's time, while this server stays on real time. + self._now = _session_now if agent_clock.follows() else _real_now + + def start(self, task_id: str, index: int, turn: TurnStart) -> None: + with self._lock: + if self._failed is not None: + return + with self._guarded(): + context = TurnContext( + index=index, context_id=self._context_id, task_id=task_id, message_id=turn.message_id, + inbound=tuple(_inbound(turn.parts, self._run)), agent_name=turn.agent_name, + agent_version=turn.agent_version, agent_model=turn.agent_model, started_at=self._now()) + self._run.start_task(context) + self._tasks[task_id] = _Task(place=len(self._tasks), context=context) + + def native(self, task_id: str, record: Any) -> None: + with self._lock: + task = self._open(task_id) + if task is not None: + with self._guarded(): + self._feed(task, record) + + def aux(self, task_id: str, name: str, record: Any) -> None: + with self._lock: + task = self._open(task_id) + if task is None: + return + # A copy: an adapter may change the record it's handed, and the log is replay's input. + task.aux.append(AuxEntry(name=name, record=json.loads(json.dumps(record)), after=task.natives)) + with self._guarded(): + self._run.aux(name, record) + + def end(self, task_id: str, *, state: str, final: Sequence[Any] = (), error: TaskError | None = None, + native: Any = None) -> None: + """Close the task: a native trajectory it returned instead of appending runs through the adapter first.""" + with self._lock: + task = self._open(task_id) + if task is None: + return + with self._guarded(): + for record in (native if isinstance(native, list) else [native]) if native is not None else (): + self._feed(task, record) + content, data = _final(final, self._run) + ending = { + "state": state, "final": content or None, "ended_at": self._now(), "data": data or None, + "error": None if error is None else {"kind": error.error_type, "message": error.message, + "code": error.code}, + } + self._run.end_task(**ending) + task.turn = ServedTurn.of(task.context, **ending) + task.ended = True + + def task_read(self, task_id: str) -> tuple[dict[str, Any], list[AuxEntry], ServedTurn] | None: + """An ended task's document as it stood when the task ended, its aux log and its served turn context.""" + with self._lock: + self._check() + task = self._tasks.get(task_id) + if task is None or task.turn is None: + return None + document = self._run.document(through=task.place) + assert document is not None + return document, list(task.aux), task.turn + + def context_read(self) -> dict[str, Any] | None: + """The context's live page: every closed step a reader may be served, or None before the first.""" + with self._lock: + self._check() + return self._run.page() + + def page(self, after: int, max_steps: int, max_bytes: int, *, task_id: str | None = None) -> AtifPage: + """The closed steps after step ``after``, of the whole context or of task ``task_id``, within both budgets; the + first is always returned, so one larger than ``max_bytes`` can't stall a reader. With them, the sub-agents of + every task they belong to, as far as each is served: a sub-agent can gain steps while its task runs, and the + page that serves a task's last step, which closes only as the task ends, carries them whole.""" + with self._lock: + self._check() + document = self._run.page() + by_place = {task.place: task_id for task_id, task in self._tasks.items()} + step_tasks = [by_place.get(place) for place in self._run.step_tasks()] + sub_tasks = {agent_id: by_place.get(place) for agent_id, place in self._run.subagent_tasks().items()} + steps = document["steps"] if document is not None else [] + if after > len(steps): + raise ValueError(f"after={after} is past the document's {len(steps)} closed steps") + pending = [(step, owner) for step, owner in zip(steps, step_tasks) + if (task_id is None or owner == task_id) and step["step_id"] > after] + served: list[dict[str, Any]] = [] + tasks: set[str | None] = set() + used = 0 + for step, owner in pending[:max_steps]: + size = len(json.dumps(step)) + if served and used + size > max_bytes: + break + served.append(step) + tasks.add(owner) + used += size + header = None + subagents: list[dict[str, Any]] = [] + if document is not None: + header = {key: value for key, value in document.items() if key not in ("steps", "subagent_trajectories")} + subagents = [sub for sub in document.get("subagent_trajectories", []) + if sub_tasks.get(sub["trajectory_id"]) in tasks] + return AtifPage(header=header, subagents=subagents, steps=served, + next=served[-1]["step_id"] if served else after, has_more=len(served) < len(pending)) + + def _open(self, task_id: str) -> _Task | None: + if self._failed is not None: + return None + task = self._tasks.get(task_id) + return task if task is not None and not task.ended else None + + def _feed(self, task: _Task, record: Any) -> None: + self._run.native(record) + task.natives += 1 + + @contextmanager + def _guarded(self) -> Iterator[None]: + """Run a step of the copy: an error there stops the copy, and never reaches the agent's turn.""" + try: + yield + except Exception as exc: + self._failed = f"{type(exc).__name__}: {exc}" + logger.warning("the atif/1 copy of context %s stopped at an error in %s: %s", self._context_id, + self._adapter, self._failed) + + def _check(self) -> None: + if self._failed is not None: + raise AgentEnvError( + "atif_unavailable", + f"the {FORMAT} copy of context {self._context_id!r} stopped at an error in its adapter " + f"{self._adapter}: {self._failed}; its native trajectory is unaffected", + status=UNAVAILABLE_STATUS, + ) + + +def _real_now() -> datetime: + return datetime.now(timezone.utc) + + +def _session_now() -> datetime: + return datetime.fromtimestamp(follower.session_time(), timezone.utc) + + +def _inbound(parts: Iterable[Any], run: AdapterRun) -> list[Any]: + """An inbound message as ATIF content: text as text, a DataPart as its compact JSON, a file's bytes as media and a + file by URI as a note naming it.""" + content: list[Any] = [] + for part in parts: + if isinstance(part, TextPart): + content.append(part.text) + elif isinstance(part, DataPart): + content.append(_compact(_thaw(part.data))) + elif isinstance(part, FilePart): + content.append(_file(part, run)) + return content + + +def _final(parts: Iterable[Any], run: AdapterRun) -> tuple[list[Any], list[dict[str, Any]]]: + """A final response as ATIF content and its diagnostics: text, files and a structured output (the task's answer, + as compact JSON) are content; any other DataPart is the harness's diagnostics, for the last step's ``data``.""" + content: list[Any] = [] + data: list[dict[str, Any]] = [] + for part in parts: + if isinstance(part, TextPart): + content.append(part.text) + elif isinstance(part, DataPart): + value = _thaw(part.data) + if set(value) == {STRUCTURED_OUTPUT}: + content.append(_compact(value[STRUCTURED_OUTPUT])) + else: + data.append({"data": value, **({"metadata": _thaw(part.metadata)} if part.metadata else {})}) + elif isinstance(part, FilePart): + content.append(_file(part, run)) + return content, data + + +def _file(part: FilePart, run: AdapterRun) -> Media | str: + media_type = part.mime_type or "application/octet-stream" + if part.bytes is not None: + try: + data = base64.b64decode(part.bytes, validate=True) + except (binascii.Error, ValueError): + return f"[file: {part.name or 'unnamed'}, {media_type}, bytes that aren't base64]" + return run.media(data, media_type, name=part.name) + assert part.uri is not None + where = urlsplit(part.uri) + # The query and fragment are dropped: a signed URL's signature is a grant. + return f"[file: {part.name or 'unnamed'}, {media_type}, {urlunsplit((*where[:3], '', ''))}]" + + +def _compact(value: Any) -> str: + return json.dumps(value, separators=(",", ":"), ensure_ascii=False, allow_nan=False) 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 05a75e757..ba107b17d 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 @@ -2,12 +2,16 @@ from __future__ import annotations +import json import logging from collections import OrderedDict from dataclasses import dataclass +from typing import Any, Sequence +from ..atif import Adapter, AuxEntry, ServedTurn +from ._atif_copy import AtifCopy, AtifPage, TurnStart from .extensions import TrajectoryState -from .tasks.v1 import TrajectoryLog +from .tasks.v1 import TaskError, TrajectoryLog logger = logging.getLogger(__name__) @@ -50,6 +54,25 @@ class TrajectoryPage: total: int +@dataclass(frozen=True, slots=True) +class AtifTaskRead: + """An ended task's atif/1 document as it stood when the task ended, its aux log and its served turn context.""" + + document: dict[str, Any] + aux: list[AuxEntry] + turn: ServedTurn + + +@dataclass(frozen=True, slots=True) +class AtifCursor: + """A cursor page of a context's atif/1 copy, with the context, the task a read of it is on and its state.""" + + page: AtifPage + context_id: str + task_id: str + state: TrajectoryState + + class TaskTrajectories: """Each task's log and final record, grouped by context in execution order. @@ -57,27 +80,38 @@ class TaskTrajectories: positions in a context read never shift. A context with a task pending or running is never evicted, nor is the one whose task just ended, so its final record is readable.""" - def __init__(self, max_contexts: int = MAX_CACHED_CONTEXTS, *, native: str | None = None) -> None: + def __init__( + self, + max_contexts: int = MAX_CACHED_CONTEXTS, + *, + native: str | None = None, + atif: type[Adapter] | 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._tasks: dict[str, _TaskRecord] = {} self._contexts: OrderedDict[str, list[str]] = OrderedDict() + self._copies: dict[str, AtifCopy] = {} def register(self, task_id: str, context_id: str) -> TrajectoryLog: """The task's log, created ``pending`` the first time the task is seen.""" record = self._tasks.get(task_id) if record is None: - log = TrajectoryLog(native=self._native) + log = TrajectoryLog( + native=self._native, adapter=self._atif.spec if self._atif is not None else None + ) log._task_id = task_id record = self._tasks[task_id] = _TaskRecord(context_id=context_id, log=log) self._contexts.setdefault(context_id, []).append(task_id) self._touch(record.context_id) return record.log - def start(self, task_id: str) -> None: - """Place the task after the context's started tasks, as it begins to run. + 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. Only tasks that have not started move; they have no events, so no position shifts.""" record = self._tasks[task_id] @@ -88,6 +122,12 @@ def start(self, task_id: str) -> 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: + 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) + record.log._atif = _CopySink(copy, task_id) self._touch(record.context_id) def request_cancel(self, task_id: str) -> None: @@ -103,8 +143,11 @@ def seal( *, native: bytes | None = None, native_format: str | None = None, + final: Sequence[Any] = (), + error: TaskError | None = None, ) -> None: - """End the task's trajectory; the first seal wins.""" + """End the task's trajectory, and close it in the context's atif/1 copy with its final + response's parts and its error; the first seal wins.""" record = self._tasks[task_id] if record.final_state is not None: return @@ -119,6 +162,15 @@ def seal( record.native_format = native_format record.log._sealed = True record.final_state = TrajectoryState.CANCELED if record.cancel_requested else state + copy = self._copies.get(record.context_id) + if copy is not None: + copy.end( + task_id, + state=record.final_state.value, + final=final, + error=error, + native=None if native is None else json.loads(native), + ) self._touch(record.context_id) self._evict(keep=record.context_id) @@ -171,19 +223,8 @@ def context_page( records = self._context_records(context_id) if records is None: return None - task_ids = self._contexts[context_id] - states = [record.state for record in records] + task_id, state = self._context_progress(context_id, records) lengths = [len(record.log) for record in records] - current = next( - (index for index, record in enumerate(records) if record.final_state is None), - len(records) - 1, - ) - if TrajectoryState.RUNNING in states: - state = TrajectoryState.RUNNING - elif TrajectoryState.PENDING in states: - state = TrajectoryState.PENDING - else: - state = states[-1] page: list[bytes] = [] offset = 0 for record, length in zip(records, lengths): @@ -204,13 +245,76 @@ def context_page( offset += length return TrajectoryPage( context_id=context_id, - task_id=task_ids[current], + task_id=task_id, state=state, format=_context_format(records), events=page, total=sum(lengths), ) + def atif_task(self, task_id: str) -> AtifTaskRead | None: + """The ended task's atif/1 document as it stood when it ended, with its aux log and served + turn context, or None when there is none.""" + record = self._tasks.get(task_id) + copy = self._copies.get(record.context_id) if record is not None else None + if copy is None: + return None + self._touch(record.context_id) + read = copy.task_read(task_id) + return None if read is None else AtifTaskRead(*read) + + def atif_context(self, context_id: str) -> dict[str, Any] | None: + """The context's atif/1 live page, or None when it has no closed step yet.""" + copy = self._copies.get(context_id) + if copy is None: + return None + self._touch(context_id) + return copy.context_read() + + def atif_task_page( + self, task_id: str, after: int, max_steps: int, max_bytes: int + ) -> AtifCursor | None: + """A cursor page of the task's closed atif/1 steps, in the task's state.""" + record = self._tasks.get(task_id) + copy = self._copies.get(record.context_id) if record is not None else None + if copy is None: + return None + self._touch(record.context_id) + state = record.state + page = copy.page(after, max_steps, max_bytes, task_id=task_id) + return AtifCursor(page=page, context_id=record.context_id, task_id=task_id, state=state) + + def atif_context_page( + self, context_id: str, after: int, max_steps: int, max_bytes: int + ) -> AtifCursor | None: + """A cursor page of the context's closed atif/1 steps, on the task the context is on and in + the context's state.""" + copy = self._copies.get(context_id) + records = self._context_records(context_id) if copy is not None else None + if copy is None or records is None: + return None + task_id, state = self._context_progress(context_id, records) + page = copy.page(after, max_steps, max_bytes) + return AtifCursor(page=page, context_id=context_id, task_id=task_id, state=state) + + def _context_progress( + self, context_id: str, records: list[_TaskRecord] + ) -> tuple[str, TrajectoryState]: + """The task a context read is on, the first that hasn't ended, and the context's state.""" + task_ids = self._contexts[context_id] + states = [record.state for record in records] + current = next( + (index for index, record in enumerate(records) if record.final_state is None), + len(records) - 1, + ) + if TrajectoryState.RUNNING in states: + state = TrajectoryState.RUNNING + elif TrajectoryState.PENDING in states: + state = TrajectoryState.PENDING + else: + state = states[-1] + return task_ids[current], state + def _context_records(self, context_id: str) -> list[_TaskRecord] | None: task_ids = self._contexts.get(context_id) if not task_ids: @@ -232,10 +336,25 @@ def _evict(self, *, keep: str) -> None: ): continue del self._contexts[context_id] + self._copies.pop(context_id, None) for task_id in task_ids: del self._tasks[task_id] +@dataclass(frozen=True, slots=True) +class _CopySink: + """Where a task's log feeds its records: the context's atif/1 copy, under the task's id.""" + + copy: AtifCopy + task_id: str + + def native(self, record: Any) -> None: + self.copy.native(self.task_id, record) + + def aux(self, name: str, record: Any) -> None: + self.copy.aux(self.task_id, name, record) + + def _context_format(records: list[_TaskRecord]) -> str | None: """The most recent format any of the context's tasks set.""" return next((record.log.format for record in reversed(records) if record.log.format), None) 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 06c91aba5..50deffab4 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/extensions.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/extensions.py @@ -24,6 +24,8 @@ model_validator, ) +from ..atif import FORMAT as ATIF_FORMAT +from ..atif import Adapter, AdapterSpec from ._triggers import MAX_SOLVER_MESSAGE_LENGTH from .tasks.v1 import AgentConfig from ..transfers import ( @@ -166,12 +168,19 @@ class ContextTrajectoryRequest(ExtensionRequest): class TrajectoryWriteObjects(ExtensionRequest): + """Where the agent uploads what it serves. An atif/1 task read may also grant ``aux``, the task's aux log, and + ``turn_context``, its TurnContext and how it ended, so the turn can be replayed offline.""" + trajectory: WriteObject + aux: WriteObject | None = None + turn_context: WriteObject | None = None @model_validator(mode="after") def _json_trajectory(self) -> TrajectoryWriteObjects: - if self.trajectory.media_type != "application/json": - raise ValueError("trajectory object media_type must be application/json") + for name in ("trajectory", "aux", "turn_context"): + granted = getattr(self, name) + if granted is not None and granted.media_type != "application/json": + raise ValueError(f"{name} object media_type must be application/json") return self @@ -196,6 +205,22 @@ class TrajectoryObjectsResponse(ExtensionResponse): format: str | None = None +class AtifUploadedObjects(ExtensionResponse): + trajectory: Uploaded + aux: Uploaded | None = None + turn_context: Uploaded | None = None + + +class AtifObjectsResponse(ExtensionResponse): + """An atif/1 read's answer in objects form: what it uploaded, the format, and the ATIF and profile versions of the + document it uploaded.""" + + objects: AtifUploadedObjects + format: Literal["atif/1"] = ATIF_FORMAT + schema_version: str + profile_version: str + + class TrajectoryState(str, Enum): """Where a trajectory stands: ``pending`` has no events yet, ``running`` is still gaining them, and the terminal states gain no more.""" @@ -237,6 +262,27 @@ class TrajectoryEventsResponse(ExtensionResponse): has_more: bool +class AtifEventsResponse(ExtensionResponse): + """An atif/1 cursor page: the document's closed steps after step ``after``, ``next`` the last one's ``step_id``. + ``header`` is the document's root without its steps and sub-agents (``final_metrics`` once no task is open), and + ``subagents`` the embedded sub-agent trajectories of the + tasks these steps belong to, as far as each is served, so the page stands alone. A sub-agent can gain steps while + its task runs; a reader keeps each sub-agent's latest copy, and the page that serves a task's last step carries + them whole. The last page's header with every page's steps and the latest sub-agents is the document.""" + + context_id: str + task_id: str + state: TrajectoryState + format: Literal["atif/1"] = ATIF_FORMAT + schema_version: str + profile_version: str + header: dict[str, Any] | None = None + subagents: list[dict[str, Any]] = Field(default_factory=list) + events: list[Any] + next: int + has_more: bool + + def _opaque_snapshot_objects( objects: SnapshotWriteObjects | SnapshotReadObjects, ) -> SnapshotWriteObjects | SnapshotReadObjects: @@ -1111,20 +1157,33 @@ def _configure_install(**declaration: Any) -> ExtensionConfiguration: return ExtensionConfiguration(wire_params=declaration) -def _configure_trajectory(*, live: bool = False, native: str | None = None) -> ExtensionConfiguration: +def _configure_trajectory( + *, live: bool = False, native: str | None = None, atif: type[Adapter] | None = None +) -> ExtensionConfiguration: """``live=True`` advertises the cursor reads, which serve the framework's log while a task runs, and the context reads the framework answers when the agent binds none. ``native`` names the native log's format: the card offers it as ``formats``, ``native`` and - ``default``, and the log, a returned native trajectory and every read hold to it.""" + ``default``, and the log, a returned native trajectory and every read hold to it. ``atif`` + names the ``@atif_adapter`` class for that format: the card then offers atif/1 too, and the + SDK serves it from one document per context, built as the agent writes its log.""" if not isinstance(live, bool): raise TypeError("live must be a boolean") if native is not None and not isinstance(native, str): raise TypeError("native must be a format id string") if native is not None and (not native.strip() or len(native) > MAX_TRAJECTORY_FORMAT_LENGTH): raise ValueError(f"native must be a format id of 1 to {MAX_TRAJECTORY_FORMAT_LENGTH} characters") + if atif is not None: + spec = vars(atif).get("spec") if isinstance(atif, type) and issubclass(atif, Adapter) else None + if not isinstance(spec, AdapterSpec): + raise TypeError("atif must be an Adapter subclass declared with @atif_adapter") + if native is None: + raise ValueError("atif needs native, the format the adapter reads") + if spec.native_format != native: + raise ValueError(f"{atif.__name__} reads {spec.native_format!r}, not {native!r}, the native format") + formats = [native, ATIF_FORMAT] if atif is not None else [native] return ExtensionConfiguration( - wire_params={"formats": [native], "native": native, "default": native} if native else {}, - options={"native": native} if native else {}, + wire_params={"formats": formats, "native": native, "default": native} if native else {}, + options={"native": native, **({"atif": atif} if atif is not None else {})} if native else {}, variants=( {"get": {"task_events", "context_events", "context", "context_objects"}} if live else {} ), 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 1906e8c6a..032771f91 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py @@ -29,6 +29,11 @@ from starlette.routing import Route from starlette.types import ASGIApp, Receive, Scope, Send +from ..atif import FORMAT as ATIF_FORMAT +from ..atif import PROFILE_KEY as ATIF_PROFILE_KEY +from ..atif import PROFILE_VERSION as ATIF_PROFILE_VERSION +from ..atif import SCHEMA_VERSION as ATIF_SCHEMA_VERSION +from ._atif_copy import TurnStart from ._trajectory_log import MAX_TRAJECTORY_READ_BYTES, TaskTrajectories from ._triggers import TriggerEngine, TriggerError from .extensions import ( @@ -56,6 +61,9 @@ TaskEventsTrajectoryRequest, TaskObjectTrajectoryRequest, TaskTrajectoryRequest, + AtifEventsResponse, + AtifObjectsResponse, + AtifUploadedObjects, TrajectoryEventsResponse, TrajectoryObjectsResponse, TrajectoryState, @@ -563,9 +571,14 @@ def __init__( self.cdp_endpoints: dict[str, dict[str, Any]] = {} trajectory = self._activations.get(TRAJECTORY_V1.uri) native = trajectory.options.get("native") if trajectory is not None else None + atif = trajectory.options.get("atif") if trajectory is not None else None #: What a trajectory read may name, as the card's trajectory ``formats`` lists them. - self.trajectory_formats: tuple[str, ...] = (native,) if native else () - self.task_trajectories = TaskTrajectories(native=native) + self.trajectory_formats: tuple[str, ...] = ( + (native, ATIF_FORMAT) if atif is not None else (native,) if native else () + ) + 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._context_sessions = _BoundedContextSessions() self.skills: list[Mapping[str, Any]] = [] self.identity_skills: dict[str, str] = {} @@ -819,10 +832,16 @@ async def trajectory_get( | ContextObjectTrajectoryRequest | ContextEventsTrajectoryRequest, ) -> Any: + if request.format == ATIF_FORMAT: + if isinstance(request, (TaskEventsTrajectoryRequest, ContextEventsTrajectoryRequest)): + return self._atif_events(request) + return await self._atif_document(request) if isinstance( request, (TaskEventsTrajectoryRequest, ContextEventsTrajectoryRequest) ): return self._trajectory_events(request) + if isinstance(request, (TaskObjectTrajectoryRequest, ContextObjectTrajectoryRequest)): + _refuse_turn_objects(request) if isinstance(request, (TaskTrajectoryRequest, TaskObjectTrajectoryRequest)): trajectory = self.task_trajectories.final(request.task_id) if trajectory is None: @@ -845,6 +864,84 @@ async def trajectory_get( objects=TrajectoryUploadedObjects(trajectory=uploaded), format=trajectory.format ) + def _atif_events( + self, request: TaskEventsTrajectoryRequest | ContextEventsTrajectoryRequest + ) -> dict[str, Any]: + """An atif/1 cursor page: the copy's closed steps after step ``after``, of the task or of + the whole context.""" + max_steps = request.limit or MAX_TRAJECTORY_READ_EVENTS + try: + if isinstance(request, TaskEventsTrajectoryRequest): + cursor = self.task_trajectories.atif_task_page( + request.task_id, request.after, max_steps, MAX_TRAJECTORY_READ_BYTES + ) + unknown = f"Unknown task '{request.task_id}'" + else: + cursor = self.task_trajectories.atif_context_page( + request.context_id, request.after, max_steps, MAX_TRAJECTORY_READ_BYTES + ) + unknown = f"Unknown context '{request.context_id}'" + except ValueError as exc: + raise HTTPException(status_code=400, detail=str(exc)) from exc + if cursor is None: + raise HTTPException(status_code=404, detail=unknown) + page = cursor.page + return AtifEventsResponse( + context_id=cursor.context_id, + task_id=cursor.task_id, + state=cursor.state, + **_atif_versions(page.header), + header=page.header, + subagents=page.subagents, + events=page.steps, + next=page.next, + has_more=page.has_more, + ).model_dump(mode="json", exclude_none=True) + + async def _atif_document( + self, + request: TaskTrajectoryRequest + | TaskObjectTrajectoryRequest + | ContextTrajectoryRequest + | ContextObjectTrajectoryRequest, + ) -> dict[str, Any]: + """A whole atif/1 document: a task read's as it stood when the task ended, with the + task's aux log and turn context, or a context read's live page; inline, or uploaded + through the request's grants.""" + served: dict[str, Any] = {} + if isinstance(request, (TaskTrajectoryRequest, TaskObjectTrajectoryRequest)): + read = self.task_trajectories.atif_task(request.task_id) + if read is None: + raise HTTPException( + status_code=404, + detail=f"No completed trajectory available for task '{request.task_id}'", + ) + document = read.document + served = {"aux": [entry.wire() for entry in read.aux], "turn_context": read.turn.wire()} + else: + if isinstance(request, ContextObjectTrajectoryRequest): + _refuse_turn_objects(request) + document = self.task_trajectories.atif_context(request.context_id) + if document is None: + raise HTTPException( + status_code=404, + detail=f"Context '{request.context_id}' has no {ATIF_FORMAT} step to serve yet", + ) + versions = _atif_versions(document) + if isinstance(request, (TaskTrajectoryRequest, ContextTrajectoryRequest)): + return {"trajectory": document, "format": ATIF_FORMAT, **versions, **served} + objects = request.objects + uploaded = AtifUploadedObjects( + trajectory=await upload(objects.trajectory, _json_bytes(document)), + aux=None if objects.aux is None else await upload(objects.aux, _json_bytes(served["aux"])), + turn_context=( + None + if objects.turn_context is None + else await upload(objects.turn_context, _json_bytes(served["turn_context"])) + ), + ) + return AtifObjectsResponse(objects=uploaded, **versions).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.""" @@ -1232,6 +1329,9 @@ async def invoke(request: Request) -> JSONResponse: extension_request = request_model.model_validate(payload) if extension_uri == TRAJECTORY_V1.uri: self.services.check_trajectory_format(extension_request.format) + if extension_request.format == ATIF_FORMAT: + # The SDK serves atif/1 from its own copy, context reads an agent binds included. + handler = self.services.trajectory_get except HTTPException: raise except AgentEnvError as exc: @@ -1343,13 +1443,22 @@ async def execute(self, context: Any, event_queue: Any) -> None: **({"role": task_config.role} if task_config.role is not None else {}), } async with self._context_locks.acquire(task.context_id): - trajectories.start(task.id) + parts = tuple(_from_a2a_part(part) for part in (context.message.parts or [])) + turn = None + if self._services.serves_atif: + card = self._services.card + turn = TurnStart( + message_id=getattr(context.message, "message_id", None), + parts=parts, + agent_name=card.name, + agent_version=card.version, + agent_model=_config_model(task_config), + ) + trajectories.start(task.id, turn) request = TaskRequest( task_id=task.id, context_id=task.context_id, - parts=tuple( - _from_a2a_part(part) for part in (context.message.parts or []) - ), + parts=parts, config=task_config, mcp_servers=self._services.task_mcp_servers(), cdp_endpoints=self._services.cdp_endpoints, @@ -1365,7 +1474,7 @@ async def execute(self, context: Any, event_queue: Any) -> None: else: result = await self._handler(request) if isinstance(result, TaskResult) and result.native_trajectory is not None: - trajectory._hold_to_native(result.native_trajectory.format) + trajectory._hold_returned(result.native_trajectory.format) except _TaskFailed as failed: result = TaskResult.failure( failed.error.code, failed.error.message, error_type=failed.error.error_type @@ -1387,6 +1496,8 @@ async def execute(self, context: Any, event_queue: Any) -> None: else TrajectoryState.COMPLETED, native=None if native is None else _encode_trajectory(native.payload), native_format=None if native is None else native.format, + final=result.parts, + error=result.error, ) message = updater.new_agent_message(parts=parts) if result.outcome is TaskOutcome.FAILED: @@ -1397,18 +1508,18 @@ async def execute(self, context: Any, event_queue: Any) -> None: trajectories.seal(task.id, TrajectoryState.CANCELED) raise except Exception: - trajectories.seal(task.id, TrajectoryState.FAILED) correlation_id = uuid.uuid4().hex - logger.exception( - "unhandled task execution error (correlation_id=%s)", - correlation_id, - ) failure = TaskResult.failure( "framework.unhandled_exception", "An unexpected framework error occurred. " f"Correlation ID: {correlation_id}", error_type="infra_error", ) + trajectories.seal(task.id, TrajectoryState.FAILED, error=failure.error) + logger.exception( + "unhandled task execution error (correlation_id=%s)", + correlation_id, + ) await updater.failed( message=updater.new_agent_message(parts=_to_a2a_parts(failure)) ) @@ -1487,6 +1598,39 @@ async def cancel(self, context: Any, event_queue: Any) -> None: await TaskUpdater(event_queue, context.task_id, context.context_id).cancel() +def _refuse_turn_objects( + request: TaskObjectTrajectoryRequest | ContextObjectTrajectoryRequest, +) -> None: + """``aux`` and ``turn_context`` grants ride only an atif/1 task read, which has them to upload.""" + if request.objects.aux is not None or request.objects.turn_context is not None: + raise HTTPException( + status_code=400, + detail=f"aux and turn_context objects go with an {ATIF_FORMAT} task read only", + ) + + +def _atif_versions(document: Mapping[str, Any] | None) -> dict[str, Any]: + """What every atif/1 answer names beside its format: the served document's ATIF and profile + versions.""" + if document is None: + return {"schema_version": ATIF_SCHEMA_VERSION, "profile_version": ATIF_PROFILE_VERSION} + profile = (document.get("extra") or {}).get(ATIF_PROFILE_KEY) or {} + return { + "schema_version": document.get("schema_version", ATIF_SCHEMA_VERSION), + "profile_version": profile.get("version", ATIF_PROFILE_VERSION), + } + + +def _config_model(config: AgentConfig) -> str | None: + """The model an agent's own config names, for the atif/1 copy's agent; the base config has none.""" + model = getattr(config, "model", None) + return model if isinstance(model, str) and model else None + + +def _json_bytes(value: Any) -> bytes: + return json.dumps(value, separators=(",", ":"), allow_nan=False).encode() + + def _from_a2a_part(part: Any) -> Any: root = part.root kind = getattr(root, "kind", None) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/tasks/v1.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/tasks/v1.py index 1a0a2ab64..2993fce8a 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/tasks/v1.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/tasks/v1.py @@ -19,6 +19,8 @@ from a2a.types import TaskStatusUpdateEvent from pydantic import BaseModel, ConfigDict, Field, model_validator +from ...atif import AdapterSpec + logger = logging.getLogger(__name__) _LARGE_LIVE_TRAJECTORY_BYTES = 100 * 1024 * 1024 @@ -156,11 +158,14 @@ class TrajectoryLog: Each event is serialized as it is appended, so an event once read never changes; append from one thread at a time. Unless the result carries a ``native_trajectory``, the log is the task's final trajectory. An agent whose card declares a ``native`` format starts with - that format, and setting or returning another fails the turn.""" + that format, and setting or returning another fails the turn. With an ATIF adapter + (``adapter``, its spec), every event and aux record also feeds the context's atif/1 copy.""" - __slots__ = ("_events", "_size_bytes", "_format", "_native", "_sealed", "_task_id", "_warned") + __slots__ = ( + "_events", "_size_bytes", "_format", "_native", "_sealed", "_task_id", "_warned", "_adapter", "_atif", + ) - def __init__(self, *, native: str | None = None) -> None: + def __init__(self, *, native: str | None = None, adapter: AdapterSpec | None = None) -> None: self._events: list[bytes] = [] self._size_bytes = 0 self._format: str | None = native @@ -168,6 +173,8 @@ def __init__(self, *, native: str | None = None) -> None: self._sealed = False self._task_id: str | None = None self._warned = False + self._adapter = adapter + self._atif: Any = None @property def format(self) -> str | None: @@ -195,6 +202,8 @@ def append(self, event: Mapping[str, Any]) -> None: encoded = json.dumps(dict(event), separators=(",", ":"), allow_nan=False).encode() self._events.append(encoded) self._size_bytes += len(encoded) + if self._atif is not None: + self._atif.native(json.loads(encoded)) if not self._warned and self._size_bytes > _LARGE_LIVE_TRAJECTORY_BYTES: self._warned = True logger.warning( @@ -203,9 +212,34 @@ def append(self, event: Mapping[str, Any]) -> None: _LARGE_LIVE_TRAJECTORY_BYTES, ) + def aux(self, name: str, record: Any) -> None: + """Feed a record of aux file ``name``, one the agent's ATIF adapter declares, such as a + hook's note, where it happened among the native events. It reaches the adapter and the + turn's atif/1 final read; the native log doesn't change.""" + if self._adapter is None: + raise RuntimeError("aux records feed an ATIF adapter: enable(TRAJECTORY_V1, native=..., atif=...)") + if name not in self._adapter.aux: + raise ValueError(f"the ATIF adapter declares no aux file {name!r}") + self._ensure_open() + encoded = json.dumps(record, separators=(",", ":"), allow_nan=False) + if self._atif is not None: + self._atif.aux(name, json.loads(encoded)) + def __len__(self) -> int: return len(self._events) + def _hold_returned(self, format: str) -> None: + """Fail the turn when a returned native trajectory breaks the card: its format isn't the + native one, or the task also appended events while an ATIF adapter builds the atif/1 copy + from them, so the copy and the native record would come from different sources.""" + self._hold_to_native(format) + if self._adapter is not None and self._events: + raise _TaskFailed( + "framework.trajectory_appended_and_returned", + "the task appended trajectory events and returned a native trajectory; with an ATIF adapter, " + "append the events or return the trajectory, not both", + ) + def _hold_to_native(self, format: str) -> None: """Fail the turn as the agent's error when ``format``, set or returned, isn't the native format the card declares; a retry would fail the same way.""" diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md b/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md index 35cd851cf..41fff3053 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md @@ -27,9 +27,13 @@ to native exactly. 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. - 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. + wrote no step is left out, and so is the reference to it. A spawning call with no result when its task ends gets + one, with no content and `status: canceled`, so its sub-agent stays referenced. - `schema_version` is the oldest ATIF version that holds the document's fields: `ATIF-v1.8` for profile 1.0. - Format id: `atif/1`. The profile's own version is the root's `extra.agentenv.version`. @@ -46,13 +50,20 @@ to native exactly. of every later read, and every reference it is served resolves. - The final response is written once. When the task's last agent step already holds the same text, nothing is added; otherwise one step is appended, `source: agent` and `llm_call_count` 0. The task's terminal state goes on the task's - last step, which closes only when the task ends, so it is never served before the state is known. + last step, which closes only when the task ends, so it is never served before the state is known, and so does the + task's error, unless the adapter wrote one there. +- A2A DataParts: what the conversation says is text, and what describes the run is profile. An inbound DataPart is a + text part holding its compact JSON, and so is a final response's `structured_output`, the task's answer. The final + response's other DataParts, a harness's diagnostics, go in its last step's `data`. The SDK's own usage and error + part is left out: `final_metrics` and the last step's `state` and `error` hold it. - An agent message whose parts are all text is one string, the parts joined by a blank line; Harbor's tools read only strings there. Text output always goes in whole: there is no reference part and no cap. - `reasoning_content` joins a step's reasoning blocks' texts with a blank line. The profile's `reasoning` lists every block, in native order, with its share of that text, so a reader that knows the profile can rebuild exact blocks. - Timestamps are UTC, written `YYYY-MM-DDTHH:MM:SS(.fff|.ffffff)Z`. Other precisions are normalized: ATIF's Step - validator on Python 3.10 reads no other. + validator on Python 3.10 reads no other. A document keeps one clock: the steps the SDK writes, each task's user step + and final response, are on the clock the agent's programs read, the universe's when the agent follows the env's + clock. - Usage follows ATIF: `prompt_tokens` includes cache reads and writes, and `cached_tokens` is the cache reads. Each adapter's `input_includes_cache` constant says whether its native input count already includes the cache. Cache writes go in `Metrics.extra.agentenv.cache_write_tokens`. An adapter may give a step's counts over several @@ -109,6 +120,7 @@ One vocabulary, in three places: | Step | `state` | On a task's last step: its terminal state | the explorer, the hub's turns view | | Step | `attempt` | The harness attempt the step belongs to; absent means 1 | the explorer | | Step | `error` | A step-level error: `kind`, `message`, `code` | the explorer | +| Step | `data` | On a task's last step: its final response's diagnostic DataParts, in order, each `data` and its `metadata` | the explorer | | Step | `reasoning` | Each reasoning block: `chars`, `visibility`, `signature`, `data` | resuming a session; RL replay | | Step | `media` | Details of the media the message names, by path | media transfer; the explorer | | ObservationResult | `status` | The result's status; absent means `ok` | the explorer, judges' turn events | diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/__init__.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/__init__.py index c8c2fb340..b66f06e58 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/__init__.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/__init__.py @@ -35,6 +35,7 @@ MetricsProfile, ObservationResultProfile, ReasoningBlock, + StepData, StepError, StepProfile, SubagentTrajectoryRefProfile, @@ -47,16 +48,18 @@ from .kit import KIT_RULES, KitResult, check_adapter from .reader import Task, check, is_prefix, load, media_paths, strip_profile, tasks from .runner import AdapterRun, Fed, RecordedTask, replay +from .served import AuxEntry, ContentItem, MediaItem, ServedData, ServedError, ServedMedia, ServedTurn from .validator import RULES, Finding, Rule, errors_in, validate, validate_live __all__ = [ "Adapter", "AdapterRef", "AdapterRun", "AdapterSpec", "Agent", "AgentProfile", "Arrival", "atif_adapter", - "AtifError", "AtifTurn", "AudioSource", "aux", "check", "check_adapter", "ContentPart", "Document", "dump_profile", - "errors_in", "Fed", "FinalMetrics", "FinalMetricsProfile", "Finding", "finish", "FORMAT", "ImageSource", - "is_prefix", "KIT_RULES", "KitResult", "load", "Media", "media_paths", "MediaInfo", "Metrics", "MetricsProfile", - "Native", "native", "Observation", "ObservationResult", "ObservationResultProfile", "PROFILE_KEY", "profile_of", - "PROFILE_VERSION", "PROFILES", "RAW_ARGUMENTS", "read_profile", "ReasoningBlock", "RecordedTask", "replay", "Rule", - "RULES", "SCHEMA_VERSION", "Selector", "Step", "StepError", "StepProfile", "strip_profile", "SubagentTrajectoryRef", - "SubagentTrajectoryRefProfile", "Task", "tasks", "timestamp", "ToolCall", "ToolCallProfile", "Trajectory", - "TrajectoryProfile", "TurnContext", "validate", "validate_live", "VOCABULARIES", + "AtifError", "AtifTurn", "AudioSource", "aux", "AuxEntry", "check", "check_adapter", "ContentItem", "ContentPart", + "Document", "dump_profile", "errors_in", "Fed", "FinalMetrics", "FinalMetricsProfile", "Finding", "finish", + "FORMAT", "ImageSource", "is_prefix", "KIT_RULES", "KitResult", "load", "Media", "media_paths", "MediaInfo", + "MediaItem", "Metrics", "MetricsProfile", "Native", "native", "Observation", "ObservationResult", + "ObservationResultProfile", "PROFILE_KEY", "profile_of", "PROFILE_VERSION", "PROFILES", "RAW_ARGUMENTS", + "read_profile", "ReasoningBlock", "RecordedTask", "replay", "Rule", "RULES", "SCHEMA_VERSION", "Selector", + "ServedData", "ServedError", "ServedMedia", "ServedTurn", "Step", "StepData", "StepError", "StepProfile", + "strip_profile", "SubagentTrajectoryRef", "SubagentTrajectoryRefProfile", "Task", "tasks", "timestamp", "ToolCall", + "ToolCallProfile", "Trajectory", "TrajectoryProfile", "TurnContext", "validate", "validate_live", "VOCABULARIES", ] diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py index ec43fda52..cd7748390 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py @@ -231,18 +231,22 @@ class _Trajectory: class Document: - """One A2A context's ATIF document, built a task at a time. Not thread-safe: records are fed one at a time.""" + """One A2A context's ATIF document, built a task at a time. Not thread-safe: records are fed one at a time. + ``trajectory_id`` names this document among the ones a context's record may span.""" - def __init__(self, spec: AdapterSpec, sink: Callable[[str, bytes], None] | None = None) -> None: + def __init__(self, spec: AdapterSpec, sink: Callable[[str, bytes], None] | None = None, *, + trajectory_id: str | None = None) -> None: self.spec = spec self.media: dict[str, bytes] = {} self._sink = sink + self._trajectory_id = _str(trajectory_id, "trajectory_id") self._stored: set[str] = set() self._root: _Trajectory | None = None self._subs: dict[str, _Trajectory] = {} self._call_home: dict[str, tuple[_Trajectory, _Step]] = {} self._spawned: dict[str, str] = {} self._unmatched: Counter[str] = Counter() + self._unmatched_at_end: list[dict[str, int]] = [] self._task_costs: list[tuple[float, str] | None] = [] self._context: TurnContext | None = None self._task = -1 @@ -281,29 +285,48 @@ def start_task(self, context: TurnContext) -> AtifTurn: return AtifTurn(self, context) def end_task(self, *, state: str = "completed", final: Sequence[Any] | None = None, - ended_at: str | datetime | None = None) -> None: + ended_at: str | datetime | None = None, data: Sequence[Mapping[str, Any]] | None = None, + error: Mapping[str, Any] | None = None) -> None: if self._context is None: raise AtifError("no task is open") if state not in TASK_STATES: raise AtifError(f"state {state!r} isn't one of {', '.join(TASK_STATES)}") root = self._root assert root is not None - if final: - parts, media = self.parse_parts(final, None) - ended = timestamp(ended_at) + parts, media = self.parse_parts(final, None) if final else ([], {}) + ended = timestamp(ended_at) + task_data, task_error = _task_data(data), _task_error(error) + if parts: last = next((s for s in reversed(root.steps) if s.task == self._task and s.source == "agent"), None) if last is None or _message(last.parts) != _message(parts): step = self._start(root, "agent", None) step.parts, step.media, step.llm_call_count = parts, media, 0 step.time = ended - root.steps[-1].profile["state"] = state + closing = root.steps[-1].profile + closing["state"] = state + if task_data: + closing["data"] = task_data + if task_error is not None and "error" not in closing: + closing["error"] = task_error + self._answer_unanswered_spawns() for trajectory in self._trajs(): for step in trajectory.steps: if step.task == self._task: step.closed = step.ended = True trajectory.open = None + self._unmatched_at_end.append(dict(sorted(self._unmatched.items()))) self._context = None + def _answer_unanswered_spawns(self) -> None: + """A call of the ending task that spawned a sub-agent and has no result gets one, canceled with no content, so + the sub-agent stays referenced from the step that started it.""" + for call_id, agent_id in self._spawned.items(): + _, home = self._call_home[call_id] + if home.task == self._task and call_id in home.pending: + home.results.append({"source_call_id": call_id, "parts": [], "profile": {"status": "canceled"}, + "subagent": agent_id}) + home.pending.discard(call_id) + # What handlers call, through AtifTurn def peek(self, key: str, agent: str | None) -> _Step | None: @@ -435,15 +458,26 @@ def parse_parts(self, content: Iterable[Any] | None, # Reading the document - def document(self) -> dict[str, Any] | None: - """The whole document so far, or None before its first step. A fresh copy each time.""" - return self._render(closed_only=False) + def document(self, *, through: int | None = None) -> dict[str, Any] | None: + """The whole document so far, or None before its first step; with ``through``, the document as it stood when + the context's task ``through`` (its 0-based place here) ended. A fresh copy each time.""" + if through is not None and not (isinstance(through, int) and 0 <= through < len(self._unmatched_at_end)): + raise AtifError(f"task {through!r} of this document hasn't ended") + return self._render(closed_only=False, through=through) def page(self) -> dict[str, Any] | None: """What a live reader is served, built when it's read: each trajectory's closed steps, up to the first one still waiting on a result, or None while there are none.""" return self._render(closed_only=True) + def step_tasks(self) -> list[int]: + """Each root step's task, in step order: the 0-based place in this document of the task it belongs to.""" + return [step.task for step in self._root.steps] if self._root is not None else [] + + def subagent_tasks(self) -> dict[str, int]: + """Each declared sub-agent's task: the 0-based place in this document of the task whose call spawned it.""" + return {agent_id: trajectory.task for agent_id, trajectory in self._subs.items()} + # Internals def _trajs(self) -> list[_Trajectory]: @@ -509,10 +543,12 @@ def _servable(self, trajectory: _Trajectory) -> int: count += 1 return count - def _counts(self, closed_only: bool) -> dict[str | None, int]: + def _counts(self, closed_only: bool, through: int | None = None) -> dict[str | None, int]: """How many steps of each trajectory a read shows, by sub-agent id (None for the root). A live page also holds back a step whose result points at a sub-agent it shows no step of yet, until the step's task ends.""" trajectories = self._trajs() + if through is not None: + return {t.actor: sum(1 for s in t.steps if s.task <= through) for t in trajectories} if not closed_only: return {t.actor: len(t.steps) for t in trajectories} counts = {t.actor: self._servable(t) for t in trajectories} @@ -526,40 +562,45 @@ def _counts(self, closed_only: bool) -> dict[str | None, int]: break return counts - def _render(self, *, closed_only: bool) -> dict[str, Any] | None: + def _render(self, *, closed_only: bool, through: int | None = None) -> dict[str, Any] | None: root = self._root if root is None: return None - counts = self._counts(closed_only) + counts = self._counts(closed_only, through) if counts[None] == 0: return None linked = {actor for actor, count in counts.items() if actor is not None and count} - doc: dict[str, Any] = {"schema_version": SCHEMA_VERSION, "session_id": self._context_id, - "agent": dict(root.agent), - "steps": _steps(root, counts[None], linked, closed_only)} + doc: dict[str, Any] = {"schema_version": SCHEMA_VERSION, "session_id": self._context_id} + if self._trajectory_id is not None: + doc["trajectory_id"] = self._trajectory_id + doc["agent"] = dict(root.agent) + doc["steps"] = _steps(root, counts[None], linked, closed_only) subs = [{"schema_version": SCHEMA_VERSION, "trajectory_id": trajectory.actor, "agent": dict(trajectory.agent), "steps": _steps(trajectory, counts[trajectory.actor], linked, closed_only)} for trajectory in self._subs.values() if counts[trajectory.actor]] if subs: doc["subagent_trajectories"] = subs - if self._context is None: - doc["final_metrics"] = self._final_metrics(root) + if through is not None or self._context is None: + doc["final_metrics"] = self._final_metrics(root, through) profile: dict[str, Any] = {"version": PROFILE_VERSION, "native_format": self.spec.native_format, "adapter": {"name": self.spec.name, "version": self.spec.version}} - if self._unmatched: - profile["unmatched"] = dict(sorted(self._unmatched.items())) + unmatched = self._unmatched_at_end[through] if through is not None else dict(sorted(self._unmatched.items())) + if unmatched: + profile["unmatched"] = unmatched doc["extra"] = {PROFILE_KEY: profile} return doc - def _final_metrics(self, root: _Trajectory) -> dict[str, Any]: - steps = [s for t in self._trajs() for s in t.steps if s.source == "agent" and s.llm_call_count != 0] + def _final_metrics(self, root: _Trajectory, through: int | None = None) -> dict[str, Any]: + last = self._task if through is None else through + steps = [s for t in self._trajs() for s in t.steps + if s.source == "agent" and s.llm_call_count != 0 and s.task <= last] totals: dict[str, Any] = {} for key, total in (("prompt_tokens", "total_prompt_tokens"), ("completion_tokens", "total_completion_tokens"), ("cached_tokens", "total_cached_tokens")): if steps and all(key in s.metrics for s in steps): totals[total] = sum(s.metrics[key] for s in steps) profile: dict[str, Any] = {} - costs = self._task_costs + costs = self._task_costs[:last + 1] if costs and all(cost is not None for cost in costs): totals["total_cost_usd"] = round(sum(cost[0] for cost in costs), 10) sources = {cost[1] for cost in costs} @@ -570,7 +611,7 @@ def _final_metrics(self, root: _Trajectory) -> dict[str, Any]: sources = {s.metrics_profile.get("cost_source") for s in steps} if len(sources) == 1 and None not in sources: profile["cost_source"] = sources.pop() - totals["total_steps"] = len(root.steps) + totals["total_steps"] = sum(1 for s in root.steps if s.task <= last) if steps and all("cache_write_tokens" in s.metrics_profile for s in steps): profile["total_cache_write_tokens"] = sum(s.metrics_profile["cache_write_tokens"] for s in steps) if profile: @@ -578,6 +619,40 @@ def _final_metrics(self, root: _Trajectory) -> dict[str, Any]: return totals +def _task_data(data: Sequence[Mapping[str, Any]] | None) -> list[dict[str, Any]]: + """A task's diagnostic DataParts as its last step's profile holds them: ``data``, and ``metadata`` when given.""" + if data is None: + return [] + if not isinstance(data, (list, tuple)): + raise AtifError(f"data is a list of DataParts, not {type(data).__name__}") + entries = [] + for item in data: + if not isinstance(item, Mapping) or "data" not in item or set(item) - {"data", "metadata"}: + raise AtifError(f"a DataPart is {{'data': ..., 'metadata': {{...}}}}, not {item!r}") + entry = {"data": _json(item["data"], "a DataPart's data")} + metadata = item.get("metadata") + if metadata: + if not isinstance(metadata, Mapping): + raise AtifError(f"a DataPart's metadata is an object, not {metadata!r}") + entry["metadata"] = _json(dict(metadata), "a DataPart's metadata") + entries.append(entry) + return entries + + +def _task_error(error: Mapping[str, Any] | None) -> dict[str, Any] | None: + """A task's error as a step's profile holds it.""" + if error is None: + return None + if not isinstance(error, Mapping) or set(error) - {"kind", "message", "code"}: + raise AtifError(f"a task's error is {{'kind', 'message', 'code'}}, not {error!r}") + kind = error.get("kind", "agent_error") + if kind not in ERROR_KINDS: + raise AtifError(f"kind {kind!r} isn't one of {', '.join(ERROR_KINDS)}") + message = _str(error.get("message"), "an error's message", optional=False) + code = _str(error.get("code"), "an error's code") + return {k: v for k, v in (("kind", kind), ("message", message), ("code", code)) if v is not None} + + def _agent(name: str | None, version: str | None, model: str | None) -> dict[str, Any]: agent = {"name": name or "unknown", "version": version or "unknown"} if model: diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/profile.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/profile.py index 9b83e9a78..0812d00f9 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/profile.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/profile.py @@ -95,6 +95,13 @@ class AgentProfile(_Profile): pass +class StepData(_Profile): + """A DataPart of a task's final response that isn't its answer, such as a harness's diagnostics, kept whole.""" + + data: Any = None + metadata: dict[str, Any] | None = None + + class StepProfile(_Profile): context_id: str | None = None task_id: str | None = None @@ -105,6 +112,7 @@ class StepProfile(_Profile): error: StepError | None = None reasoning: list[ReasoningBlock] | None = None media: dict[str, MediaInfo] | None = None + data: list[StepData] | None = None class ToolCallProfile(_Profile): diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/runner.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/runner.py index 4097ad66e..99f0cdc86 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/runner.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/runner.py @@ -6,11 +6,12 @@ from dataclasses import dataclass from datetime import datetime -from typing import Any, Callable, Iterable, Sequence +from typing import Any, Callable, Iterable, Mapping, Sequence from .adapter import Adapter, AdapterSpec from .builder import AtifTurn, Document, Media, TurnContext from .profile import AtifError +from .served import AuxEntry, ServedTurn @dataclass(frozen=True) @@ -23,13 +24,36 @@ class Fed: @dataclass(frozen=True, kw_only=True) class RecordedTask: - """A stored task: its context, its records in the order they were fed, and how it ended.""" + """A stored task: its context, its records in the order they were fed, and how it ended: its state, final response, + the final response's diagnostic DataParts and its error.""" context: TurnContext records: Sequence[Fed] = () state: str = "completed" final: Sequence[Any] | None = None ended_at: str | datetime | None = None + data: Sequence[Mapping[str, Any]] | None = None + error: Mapping[str, Any] | None = None + + @classmethod + def from_served(cls, turn: ServedTurn | Mapping[str, Any], native: Sequence[Any], + aux: Sequence[AuxEntry | Mapping[str, Any]] = ()) -> RecordedTask: + """The task an atif/1 final read describes: its ``turn_context``, its native records (the native final read's + events) and its ``aux`` log, each aux record placed after the native records fed before it. The served forms + are checked against their models.""" + served = turn if isinstance(turn, ServedTurn) else ServedTurn.model_validate(turn) + records: list[Fed] = [] + fed = 0 + for entry in (item if isinstance(item, AuxEntry) else AuxEntry.model_validate(item) for item in aux): + while fed < entry.after: + records.append(Fed(native[fed])) + fed += 1 + records.append(Fed(entry.record, aux=entry.name)) + records.extend(Fed(record) for record in native[fed:]) + return cls(context=served.turn_context(), records=records, state=served.state, final=served.final_content(), + ended_at=served.ended_at, + data=None if served.data is None else [entry.wire() for entry in served.data], + error=None if served.error is None else served.error.wire()) class AdapterRun: @@ -37,13 +61,14 @@ class AdapterRun: it's read; ``document`` is everything so far. Every read is a fresh copy. ``media`` receives each media file once, as ``(path, bytes)``; without it, the files are kept in ``media_files``.""" - def __init__(self, adapter: type[Adapter], *, media: Callable[[str, bytes], None] | None = None) -> None: + def __init__(self, adapter: type[Adapter], *, media: Callable[[str, bytes], None] | None = None, + trajectory_id: str | None = None) -> None: spec = vars(adapter).get("spec") if not isinstance(spec, AdapterSpec): raise AtifError(f"{adapter.__name__} isn't declared with @atif_adapter") self._cls = adapter self._spec = spec - self._doc = Document(spec, media) + self._doc = Document(spec, media, trajectory_id=trajectory_id) self._adapter: Adapter | None = None self._turn: AtifTurn | None = None @@ -58,12 +83,21 @@ def media(self, data: bytes, media_type: str, *, width: int | None = None, heigh return self._doc.store(data, media_type, {"width": width, "height": height, "duration_ms": duration_ms, "pages": pages, "name": name}) - def document(self) -> dict[str, Any] | None: - return self._doc.document() + def document(self, *, through: int | None = None) -> dict[str, Any] | None: + """The document so far; with ``through``, as it stood when this run's task ``through`` (from 0) ended.""" + return self._doc.document(through=through) def page(self) -> dict[str, Any] | None: return self._doc.page() + def step_tasks(self) -> list[int]: + """Each root step's task, in step order, by its 0-based place among this run's tasks.""" + return self._doc.step_tasks() + + def subagent_tasks(self) -> dict[str, int]: + """Each declared sub-agent's task, by its 0-based place among this run's tasks.""" + return self._doc.subagent_tasks() + def start_task(self, context: TurnContext) -> None: """Open a task and write its user step. The context's first task creates the adapter.""" if self._turn is not None: @@ -89,16 +123,18 @@ def aux(self, name: str, record: Any) -> None: getattr(self._adapter, method)(record, turn) def end_task(self, *, state: str = "completed", final: Sequence[Any] | None = None, - ended_at: str | datetime | None = None) -> None: - """Close the task: run the adapter's ``@finish``, then write the final response, once, and the task's - terminal state on its last step. The task is closed even when ``@finish`` raises, and the error is raised - after.""" + ended_at: str | datetime | None = None, data: Sequence[Mapping[str, Any]] | None = None, + error: Mapping[str, Any] | None = None) -> None: + """Close the task: run the adapter's ``@finish``, then write the final response, once, and on the task's last + step its terminal state, the final response's diagnostic DataParts (``data``: ``{data, metadata}`` each) and + its error (``kind``, ``message``, ``code``) unless the adapter wrote one there. The task is closed even when + ``@finish`` raises, and the error is raised after.""" turn = self._open() try: if self._spec.finish is not None: getattr(self._adapter, self._spec.finish)(turn) finally: - self._doc.end_task(state=state, final=final, ended_at=ended_at) + self._doc.end_task(state=state, final=final, ended_at=ended_at, data=data, error=error) self._turn = None def _open(self) -> AtifTurn: @@ -108,9 +144,9 @@ def _open(self) -> AtifTurn: def replay(adapter: type[Adapter], tasks: Iterable[RecordedTask], *, - media: Callable[[str, bytes], None] | None = None) -> dict[str, Any] | None: + media: Callable[[str, bytes], None] | None = None, trajectory_id: str | None = None) -> dict[str, Any] | None: """A context's stored tasks run through ``adapter`` again, as the agent ran them live: the whole document.""" - run = AdapterRun(adapter, media=media) + run = AdapterRun(adapter, media=media, trajectory_id=trajectory_id) for task in tasks: run.start_task(task.context) for fed in task.records: @@ -118,5 +154,5 @@ def replay(adapter: type[Adapter], tasks: Iterable[RecordedTask], *, run.native(fed.record) else: run.aux(fed.aux, fed.record) - run.end_task(state=task.state, final=task.final, ended_at=task.ended_at) + run.end_task(state=task.state, final=task.final, ended_at=task.ended_at, data=task.data, error=task.error) return run.document() diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/served.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/served.py new file mode 100644 index 000000000..fc841d55c --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/served.py @@ -0,0 +1,114 @@ +"""What an atif/1 final read serves beside a task's document, so the task can be replayed offline: ``turn_context``, +the task's TurnContext and how it ended, and ``aux``, its aux log. Both are JSON on the wire, and these models are +their shape; ``RecordedTask.from_served`` turns them, with the task's native records, back into a task ``replay`` +takes.""" +from __future__ import annotations + +from datetime import datetime +from typing import Annotated, Any, Mapping, Sequence, Union + +from pydantic import BaseModel, ConfigDict, Field + +from .builder import Media, TurnContext, timestamp + + +class _Served(BaseModel): + model_config = ConfigDict(extra="forbid", frozen=True) + + def wire(self) -> dict[str, Any]: + """As JSON on the wire: an optional field left at its default is left out, a required one is kept even when + null.""" + return self.model_dump(mode="json", exclude_defaults=True) + + +class ServedMedia(_Served): + """A media file content names by its path, ``media/.``; its bytes are stored apart.""" + + path: str + media_type: str + info: dict[str, Any] + + +class MediaItem(_Served): + """A content item that is a media file.""" + + media: ServedMedia + + +#: A content item: text, an ATIF content part, or a media file. +ContentItem = Annotated[Union[str, MediaItem, dict[str, Any]], Field(union_mode="left_to_right")] + + +class ServedData(_Served): + """A final response's diagnostic DataPart, as its last step's ``data`` holds it.""" + + data: Any + metadata: dict[str, Any] | None = None + + +class ServedError(_Served): + """A task's error, as its last step's ``error`` holds it.""" + + kind: str + message: str + code: str | None = None + + +class AuxEntry(_Served): + """One record of a task's aux log, in the order it was fed: its aux file, the record, and how many of the task's + native records were fed before it.""" + + name: str + record: Any + after: int = Field(ge=0) + + +class ServedTurn(_Served): + """A task's TurnContext and how it ended: its state, final response, diagnostic DataParts and error.""" + + index: int = Field(ge=0) + context_id: str + task_id: str + message_id: str | None = None + agent_name: str | None = None + agent_version: str | None = None + agent_model: str | None = None + started_at: str | None = None + inbound: list[ContentItem] = Field(default_factory=list) + state: str + final: list[ContentItem] | None = None + ended_at: str | None = None + data: list[ServedData] | None = None + error: ServedError | None = None + + @classmethod + def of(cls, context: TurnContext, *, state: str, final: Sequence[Any] | None = None, + ended_at: str | datetime | None = None, data: Sequence[Mapping[str, Any]] | None = None, + error: Mapping[str, Any] | None = None) -> ServedTurn: + """The served form of a task the runner was given ``context`` for and ended as these say.""" + return cls( + index=context.index, context_id=context.context_id, task_id=context.task_id, message_id=context.message_id, + agent_name=context.agent_name, agent_version=context.agent_version, agent_model=context.agent_model, + started_at=timestamp(context.started_at), inbound=_items(context.inbound), state=state, + final=None if final is None else _items(final), ended_at=timestamp(ended_at), + data=None if data is None else [ServedData.model_validate(dict(entry)) for entry in data], + error=None if error is None else ServedError.model_validate(dict(error))) + + def turn_context(self) -> TurnContext: + return TurnContext(index=self.index, context_id=self.context_id, task_id=self.task_id, + message_id=self.message_id, inbound=tuple(_content(self.inbound)), + agent_name=self.agent_name, agent_version=self.agent_version, agent_model=self.agent_model, + started_at=self.started_at) + + def final_content(self) -> list[Any] | None: + return None if self.final is None else _content(self.final) + + +def _items(content: Sequence[Any]) -> list[Any]: + return [MediaItem(media=ServedMedia(path=item.path, media_type=item.media_type, info=dict(item.info))) + if isinstance(item, Media) else item for item in content] + + +def _content(items: Sequence[Any]) -> list[Any]: + return [Media(item.media.path, item.media.media_type, item.media.info) if isinstance(item, MediaItem) else item + for item in items] diff --git a/packages/agentenv-protocol/src/agentenv_protocol/computer/clock.py b/packages/agentenv-protocol/src/agentenv_protocol/computer/clock.py index d19851871..d87233c9f 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/computer/clock.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/computer/clock.py @@ -24,6 +24,9 @@ FOLLOWER_USER = "agentenv-clock" CONFIG = "/etc/agentenv/clock/follower.json" STATUS = "/run/agentenv-clock/status.json" +#: The follower's clock file, replaced whole at each write: ``@ x ^`` while the clock is +#: armed (the universe at real time ``anchor``, running at ``rate``), ``+0 x1`` on real time. +CLOCK_FILE = "/run/agentenv-clock/clock" #: What a disk form's guest has, made from the computer's container image: core's root channel reaches its launcher, #: not the guest, so it can't configure a follower there, and a disk computer stays on real time for now. DISK_GUEST = "/etc/agentenv/vm/image.env" @@ -38,6 +41,21 @@ def follows() -> bool: return os.path.exists(FOLLOWER) and not os.path.exists(DISK_GUEST) +def session_time() -> float: + """The time this machine's session programs read, in epoch seconds: the universe's, from the follower's clock file, + while the clock is armed, else real time. A process that stays on real time, as an agent's A2A server does, reads + its programs' time here.""" + now = time.time() + try: + spec = Path(CLOCK_FILE).read_text().split() + except FileNotFoundError: + return now + if not spec[0].startswith("@"): + return now + universe, rate, anchor = float(spec[0][1:]), float(spec[1][1:]), float(spec[2][1:]) + return universe if rate == 0 or now <= anchor else universe + (now - anchor) * rate + + def session_zone() -> str: """The zone the computer booted with, which every session program is in.""" try: diff --git a/packages/agentenv-protocol/tests/test_a2a_agent_clock.py b/packages/agentenv-protocol/tests/test_a2a_agent_clock.py index a24bb8bae..492800497 100644 --- a/packages/agentenv-protocol/tests/test_a2a_agent_clock.py +++ b/packages/agentenv-protocol/tests/test_a2a_agent_clock.py @@ -190,3 +190,19 @@ def test_a_server_starting_without_a_saved_zone_keeps_its_own(image, monkeypatch with _app() as client: assert client.get("/.well-known/agent.json").status_code == 200 assert os.environ["TZ"] == "UTC" + + +@pytest.mark.parametrize("spec, expected", [ + (None, None), + ("+0 x1\n", None), + ("@1748768400.000000000 x2 ^{past}\n", 1748768400.0 + 20), + ("@1748768400.000000000 x1 ^{future}\n", 1748768400.0), + ("@1748768400.000000000 x0 ^{past}\n", 1748768400.0), +]) +def test_the_session_time_is_the_universe_while_the_clock_is_armed_and_real_time_otherwise( + tmp_path, monkeypatch, spec, expected): + clock_file = tmp_path / "clock" + if spec is not None: + clock_file.write_text(spec.format(past=time.time() - 10, future=time.time() + 3600)) + monkeypatch.setattr(follower, "CLOCK_FILE", str(clock_file)) + assert follower.session_time() == pytest.approx(time.time() if expected is None else expected, abs=1) diff --git a/packages/agentenv-protocol/tests/test_a2a_atif_serving.py b/packages/agentenv-protocol/tests/test_a2a_atif_serving.py new file mode 100644 index 000000000..2f7ba9715 --- /dev/null +++ b/packages/agentenv-protocol/tests/test_a2a_atif_serving.py @@ -0,0 +1,645 @@ +"""The SDK serves atif/1 beside the native log: an agent names its ATIF adapter in ``enable()``, and the SDK builds one +document per A2A context as the agent writes its log, serving it on task, context, cursor and final reads.""" +from __future__ import annotations + +import asyncio +import base64 +import json +import threading +import time +from datetime import datetime, timedelta, timezone +from typing import Any, Awaitable, Callable + +import pytest +from atif_cases import Toy +from starlette.testclient import TestClient + +from agentenv_protocol.a2a_agent import ( + TRAJECTORY_V1, + AgentEnvAgent, + AgentIdentity, + ContextTrajectoryRequest, + TaskRequest, + TaskResult, + TrajectoryLog, + Uploaded, + a2a_agent, + enable, + extension, + framework, +) +from agentenv_protocol.a2a_agent import clock as agent_clock +from agentenv_protocol.computer import clock as follower +from agentenv_protocol.atif import ( + FORMAT, + PROFILE_VERSION, + SCHEMA_VERSION, + RecordedTask, + atif_adapter, + aux, + errors_in, + replay, + validate, + validate_live, +) + +NATIVE = "toy-events/1" +_IDENTITY = AgentIdentity(name="toy-agent", description="test", version="2.0") + + +@atif_adapter(native_format=NATIVE, version="0.1.0", input_includes_cache=False) +class Hooks(Toy): + """The toy adapter, with a hook log the agent's own code feeds.""" + + @aux("hooks", type="note") + def note(self, record: dict, turn: Any) -> None: + # Takes the text out of the record it's handed, which must leave the served aux log whole. + turn.message(step=record["step"], text=record.pop("text")) + + +def _usage(step: str, prompt: int, out: int) -> dict[str, Any]: + return {"type": "usage", "step": step, "in": prompt, "out": out} + + +def _work(tag: str) -> list[dict[str, Any]]: + return [ + {"type": "say", "step": f"{tag}-1", "text": f"{tag}: listing"}, + {"type": "call", "step": f"{tag}-1", "id": f"{tag}-c1", "name": "Bash", "args": {"command": "ls"}}, + _usage(f"{tag}-1", 10, 5), + {"type": "result", "id": f"{tag}-c1", "out": "a.txt b.txt"}, + {"type": "say", "step": f"{tag}-2", "text": f"{tag}: two files"}, + _usage(f"{tag}-2", 12, 3), + {"type": "total", "cost": 0.25}, + ] + + +class _Hold: + """Where a test holds a turn: ``arrivals`` counts the holds it reached, and each goes on once ``resume`` is set.""" + + def __init__(self) -> None: + self.arrivals = 0 + self.resume = threading.Event() + + async def wait(self) -> None: + self.arrivals += 1 + while not self.resume.is_set(): + await asyncio.sleep(0.01) + self.resume.clear() + + def reached(self, count: int = 1) -> None: + deadline = time.monotonic() + 10 + while self.arrivals < count: + assert time.monotonic() < deadline, "the turn didn't reach its hold" + time.sleep(0.01) + + +#: What a toy agent's turn does, by the scenario its message names first; the message's second word is a tag unique in +#: the context, so the turn's call ids and step keys are too. +SCENARIOS: dict[str, Callable[[TrajectoryLog, str, _Hold], Awaitable[TaskResult]]] = {} + + +def _scenario(name: str) -> Callable[[Callable], Callable]: + def register(play: Callable) -> Callable: + SCENARIOS[name] = play + return play + return register + + +def _append(log: TrajectoryLog, records: list[dict[str, Any]]) -> None: + for record in records: + log.append(record) + + +def _spawning(tag: str) -> list[dict[str, Any]]: + """A Task call that spawns a sub-agent, and the sub-agent's first step.""" + return [{"type": "call", "step": f"{tag}-1", "id": f"{tag}-task", "name": "Task", "args": {"goal": "ls"}}, + {"type": "spawn", "id": f"{tag}-task", "agent": f"{tag}-sub", "name": "explorer"}, + {"type": "say", "step": f"{tag}-s1", "text": "sub: listing", "agent": f"{tag}-sub"}] + + +@_scenario("work") +async def _works(log: TrajectoryLog, tag: str, hold: _Hold) -> TaskResult: + """Lists the files and answers with its last message.""" + _append(log, _work(tag)) + return TaskResult.text(f"{tag}: two files") + + +@_scenario("hooks") +async def _hooks(log: TrajectoryLog, tag: str, hold: _Hold) -> TaskResult: + """Feeds a hook's note after its first event, and a note no handler takes at the end.""" + records = _work(tag) + log.append(records[0]) + log.aux("hooks", {"type": "note", "step": f"{tag}-h", "text": "the pre-tool hook allowed ls"}) + _append(log, records[1:]) + log.aux("hooks", {"type": "other", "step": f"{tag}-x", "text": "no handler takes this one"}) + return TaskResult.text(f"{tag}: two files") + + +@_scenario("late") +async def _late(log: TrajectoryLog, tag: str, hold: _Hold) -> TaskResult: + """Moves on before its call's result comes, holding there, and holds again once it has.""" + records = _work(tag) + _append(log, records[:3]) + log.append({"type": "say", "step": f"{tag}-w", "text": f"{tag}: waiting on ls"}) + await hold.wait() + _append(log, [records[3], {"type": "say", "step": f"{tag}-3", "text": f"{tag}: got it"}, + {"type": "say", "step": f"{tag}-4", "text": f"{tag}: two files"}]) + await hold.wait() + return TaskResult.text(f"{tag}: two files") + + +@_scenario("failed") +async def _fails(log: TrajectoryLog, tag: str, hold: _Hold) -> TaskResult: + """Works, then fails the task.""" + _append(log, _work(tag)) + return TaskResult.failure("toy.failed", "ls found nothing to fix") + + +@_scenario("raised") +async def _raises(log: TrajectoryLog, tag: str, hold: _Hold) -> TaskResult: + """Raises with its call unanswered.""" + _append(log, _work(tag)[:2]) + raise RuntimeError("the toy CLI crashed") + + +@_scenario("canceled") +async def _waits(log: TrajectoryLog, tag: str, hold: _Hold) -> TaskResult: + """Holds after its first step, for a test to cancel it or let it answer.""" + _append(log, _work(tag)[:3]) + await hold.wait() + return TaskResult.text("never reached") + + +@_scenario("data") +async def _answers_with_data(log: TrajectoryLog, tag: str, hold: _Hold) -> TaskResult: + """Answers with a structured output and the harness's diagnostics beside its text.""" + _append(log, _work(tag)) + return (TaskResult.builder().succeeded().add_text(f"{tag}: two files") + .add_structured_output({"files": ["a.txt", "b.txt"]}) + .add_data({"tool_call_count": 1, "cli_attempts": 2}).build()) + + +@_scenario("returned") +async def _returns(log: TrajectoryLog, tag: str, hold: _Hold) -> TaskResult: + """Appends nothing and returns its native trajectory at the end.""" + return (TaskResult.builder().succeeded().add_text(f"{tag}: two files") + .native_trajectory(format=NATIVE, payload=_work(tag)).build()) + + +@_scenario("both") +async def _appends_and_returns(log: TrajectoryLog, tag: str, hold: _Hold) -> TaskResult: + """Appends an event and returns a native trajectory too.""" + records = _work(tag) + log.append(records[0]) + return TaskResult.builder().succeeded().add_text("done").native_trajectory(format=NATIVE, payload=records).build() + + +@_scenario("broken") +async def _breaks_its_adapter(log: TrajectoryLog, tag: str, hold: _Hold) -> TaskResult: + """Appends a result for a call it never made, which its adapter refuses.""" + records = _work(tag) + _append(log, [records[0], {"type": "result", "id": "no-such-call", "out": "x"}, records[1]]) + return TaskResult.text("done anyway") + + +@_scenario("spawn") +async def _spawns(log: TrajectoryLog, tag: str, hold: _Hold) -> TaskResult: + """Spawns a sub-agent that works and answers.""" + _append(log, [*_spawning(tag), + {"type": "say", "step": f"{tag}-s2", "text": "sub: two files", "agent": f"{tag}-sub"}, + {"type": "result", "id": f"{tag}-task", "out": "two files"}, + {"type": "say", "step": f"{tag}-2", "text": f"{tag}: the explorer found two files"}]) + return TaskResult.text(f"{tag}: the explorer found two files") + + +@_scenario("grow") +async def _sub_agent_grows(log: TrajectoryLog, tag: str, hold: _Hold) -> TaskResult: + """Spawns a sub-agent that goes on writing steps after its call's result, holding in between.""" + _append(log, [*_spawning(tag), + {"type": "say", "step": f"{tag}-s2", "text": "sub: still listing", "agent": f"{tag}-sub"}, + {"type": "result", "id": f"{tag}-task", "out": "listing"}, + {"type": "say", "step": f"{tag}-2", "text": f"{tag}: the explorer is listing"}, + {"type": "say", "step": f"{tag}-3", "text": f"{tag}: waiting"}]) + await hold.wait() + _append(log, [{"type": "say", "step": f"{tag}-s3", "text": "sub: two files", "agent": f"{tag}-sub"}, + {"type": "say", "step": f"{tag}-4", "text": f"{tag}: two files"}]) + return TaskResult.text(f"{tag}: two files") + + +@_scenario("orphan") +async def _spawn_never_answered(log: TrajectoryLog, tag: str, hold: _Hold) -> TaskResult: + """Spawns a sub-agent and holds before its call's result, for a test to cancel it.""" + _append(log, _spawning(tag)) + await hold.wait() + return TaskResult.text("never reached") + + +async def _turn(request: TaskRequest, hold: _Hold) -> TaskResult: + scenario, tag = request.parts[0].text.split() + return await SCENARIOS[scenario](request.trajectory, tag, hold) + + +def _toy(hold: _Hold | None = None, *, live: bool = True, atif: Any = Hooks, bind_context: bool = False) -> AgentEnvAgent: + hold = hold or _Hold() + extensions = (enable(TRAJECTORY_V1, live=live, native=NATIVE, **({"atif": atif} if atif else {})),) + + if bind_context: + @a2a_agent(identity=_IDENTITY, extensions=extensions) + class Bound(AgentEnvAgent): + async def run(self, request: TaskRequest) -> TaskResult: + return await _turn(request, hold) + + @extension(TRAJECTORY_V1.get.context) + async def own_context(self, request: ContextTrajectoryRequest) -> dict[str, Any]: + return {"trajectory": ["the agent's own shape"], "format": "toy-session/1"} + + return Bound() + + @a2a_agent(identity=_IDENTITY, extensions=extensions) + class Agent(AgentEnvAgent): + async def run(self, request: TaskRequest) -> TaskResult: + return await _turn(request, hold) + + return Agent() + + +def _send(client: TestClient, text: str, message_id: str, *, context_id: str = "ctx-1", + extra_parts: list[dict[str, Any]] | None = None) -> str: + message = {"kind": "message", "messageId": message_id, "role": "user", "contextId": context_id, + "parts": [{"kind": "text", "text": text}, *(extra_parts or [])]} + response = client.post("/a2a", json={"jsonrpc": "2.0", "id": message_id, "method": "message/send", + "params": {"message": message, "configuration": {"blocking": False}}}) + return response.json()["result"]["id"] + + +def _state(client: TestClient, task_id: str) -> str: + response = client.post("/a2a", json={"jsonrpc": "2.0", "id": "get", "method": "tasks/get", + "params": {"id": task_id}}) + return response.json()["result"]["status"]["state"] + + +def _ended(client: TestClient, task_id: str, state: str = "completed") -> None: + deadline = time.monotonic() + 10 + while _state(client, task_id) not in ("completed", "failed", "canceled"): + assert time.monotonic() < deadline, f"task {task_id} didn't end" + time.sleep(0.01) + assert _state(client, task_id) == state + + +def _read(client: TestClient, **payload: Any) -> Any: + return client.post("/ext/trajectory", json=payload) + + +def _atif(client: TestClient, **payload: Any) -> dict[str, Any]: + response = _read(client, format=FORMAT, **payload) + assert response.status_code == 200, response.text + return response.json() + + +def _grant() -> dict[str, Any]: + expires = (datetime.now(timezone.utc) + timedelta(hours=1)).isoformat(timespec="seconds").replace("+00:00", "Z") + return {"media_type": "application/json", "max_bytes": 1_000_000, + "write": {"kind": "http-put", "url": "https://objects.example.test/write", "expires_at": expires}} + + +def _rebuild(pages: list[dict[str, Any]]) -> dict[str, Any]: + """A document from cursor pages: the last page's header, every page's steps, and each sub-agent's latest copy.""" + document = dict(pages[-1]["header"]) + document["steps"] = [step for page in pages for step in page["events"]] + subagents: dict[str, Any] = {} + for page in pages: + subagents.update({sub["trajectory_id"]: sub for sub in page["subagents"]}) + if subagents: + document["subagent_trajectories"] = list(subagents.values()) + return document + + +def test_the_card_offers_atif_beside_the_native_format() -> None: + card = _toy().create_app().state.agentenv_a2a.card.model_dump(mode="json", exclude_none=True) + (trajectory,) = [e for e in card["capabilities"]["extensions"] if e["uri"] == TRAJECTORY_V1.uri] + assert {key: trajectory["params"][key] for key in ("formats", "native", "default")} == { + "formats": [NATIVE, FORMAT], "native": NATIVE, "default": NATIVE} + + +@pytest.mark.parametrize("arguments, error", [ + ({"native": NATIVE, "atif": Toy.__mro__[1]}, TypeError), + ({"native": NATIVE, "atif": dict}, TypeError), + ({"atif": Hooks}, ValueError), + ({"native": "other-events/1", "atif": Hooks}, ValueError), +]) +def test_enable_refuses_an_adapter_that_doesnt_fit(arguments: dict[str, Any], error: type[Exception]) -> None: + with pytest.raises(error): + enable(TRAJECTORY_V1, **arguments) + + +def test_every_read_serves_both_formats_and_names_its_format(monkeypatch: pytest.MonkeyPatch) -> None: + uploaded: list[bytes] = [] + + async def capture(_target: Any, body: bytes) -> Uploaded: + uploaded.append(body) + return Uploaded(size_bytes=len(body)) + + monkeypatch.setattr(framework, "upload", capture) + native_bodies = [] + for agent in (_toy(atif=None), _toy()): + with TestClient(agent.create_app()) as client: + task_id = _send(client, "work t1", "m-1") + _ended(client, task_id) + bodies = [_read(client, **read).json() for read in ( + {"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"))) + with TestClient(_toy().create_app()) as client: + task_id = _send(client, "work t1", "m-1") + _ended(client, task_id) + task = _atif(client, task_id=task_id) + context = _atif(client, context_id="ctx-1") + cursor = _atif(client, task_id=task_id, after=0) + context_cursor = _atif(client, context_id="ctx-1", after=0) + objects = _atif(client, task_id=task_id, objects={"trajectory": _grant()}) + + # A read naming no format keeps today's body exactly, adapter or not. + assert native_bodies[0] == native_bodies[1] + for answer in (task, context, cursor, context_cursor, objects): + assert (answer["format"], answer["schema_version"], answer["profile_version"]) == ( + FORMAT, SCHEMA_VERSION, PROFILE_VERSION) + document = task["trajectory"] + assert errors_in(validate(document)) == [] + assert context["trajectory"] == document + assert json.loads(uploaded[-1]) == document + assert [step["step_id"] for step in cursor["events"]] == [1, 2, 3] + assert cursor["next"] == 3 and cursor["has_more"] is False and cursor["state"] == "completed" + # The task's cost is on no step, only in final_metrics, so the header has to carry it. + assert context_cursor["header"]["final_metrics"]["total_cost_usd"] == 0.25 + assert _rebuild([context_cursor]) == document + assert document["session_id"] == "ctx-1" and document["trajectory_id"] + assert document["agent"] == {"name": "toy-agent", "version": "2.0"} + user = document["steps"][0] + assert user["message"] == "work t1" + assert user["extra"]["agentenv"] == {"context_id": "ctx-1", "task_id": task_id, "message_id": "m-1", "turn": 0} + assert document["steps"][-1]["extra"]["agentenv"]["state"] == "completed" + + +@pytest.mark.parametrize("scenario, state", [ + ("work", "completed"), ("failed", "failed"), ("raised", "failed"), ("canceled", "canceled")]) +def test_the_copy_validates_on_every_terminal_path(scenario: str, state: str) -> None: + hold = _Hold() + with TestClient(_toy(hold).create_app()) as client: + task_id = _send(client, f"{scenario} t1", "m-1") + if scenario == "canceled": + hold.reached() + client.post("/a2a", json={"jsonrpc": "2.0", "id": "c", "method": "tasks/cancel", + "params": {"id": task_id}}) + _ended(client, task_id, state) + document = _atif(client, task_id=task_id)["trajectory"] + assert errors_in(validate(document)) == [] + closing = document["steps"][-1]["extra"]["agentenv"] + assert closing["state"] == state + if scenario == "failed": + assert closing["error"] == {"kind": "agent_error", "message": "ls found nothing to fix", "code": "toy.failed"} + if scenario == "raised": + assert closing["error"]["kind"] == "infra_error" + assert closing["error"]["code"] == "framework.unhandled_exception" + + +def test_two_tasks_in_one_context_make_one_document() -> None: + with TestClient(_toy().create_app()) as client: + first = _send(client, "work t1", "m-1") + _ended(client, first) + second = _send(client, "work t2", "m-2") + _ended(client, second) + through_first = _atif(client, task_id=first)["trajectory"] + through_second = _atif(client, task_id=second)["trajectory"] + assert errors_in(validate(through_second)) == [] + users = [step for step in through_second["steps"] if step["source"] == "user"] + assert [user["extra"]["agentenv"]["turn"] for user in users] == [0, 1] + assert users[1]["extra"]["agentenv"]["task_id"] == second + assert [step["step_id"] for step in through_second["steps"]] == list(range(1, len(through_second["steps"]) + 1)) + # The first task's read is the document as it stood then: a prefix of the second's. + assert through_second["steps"][:len(through_first["steps"])] == through_first["steps"] + assert through_first["final_metrics"]["total_steps"] == len(through_first["steps"]) + assert through_first["trajectory_id"] == through_second["trajectory_id"] + + +def test_a_step_waiting_on_its_result_holds_back_the_steps_after_it() -> None: + hold = _Hold() + pages = [] + with TestClient(_toy(hold).create_app()) as client: + task_id = _send(client, "late t1", "m-1") + hold.reached(1) + pages.append(_atif(client, context_id="ctx-1")["trajectory"]) + waiting = _atif(client, task_id=task_id, after=0) + hold.resume.set() + hold.reached(2) + pages.append(_atif(client, context_id="ctx-1")["trajectory"]) + hold.resume.set() + _ended(client, task_id) + final = _atif(client, task_id=task_id)["trajectory"] + # The call's step is unanswered, so only the user step is served, and the steps after it wait. + assert [step["source"] for step in pages[0]["steps"]] == ["user"] + assert [step["step_id"] for step in waiting["events"]] == [1] and waiting["state"] == "running" + assert len(pages[1]["steps"]) == 4 + assert errors_in(validate_live(pages, final)) == [] + + +def test_aux_records_reach_the_adapter_and_replay_gives_the_served_document(monkeypatch: pytest.MonkeyPatch) -> None: + uploaded: dict[str, bytes] = {} + + async def capture(target: Any, body: bytes) -> Uploaded: + uploaded[target.write.url.rsplit("/", 1)[-1]] = body + return Uploaded(size_bytes=len(body)) + + monkeypatch.setattr(framework, "upload", capture) + grants = {name: {**_grant(), "write": {**_grant()["write"], "url": f"https://objects.example.test/{name}"}} + for name in ("trajectory", "aux", "turn_context")} + with TestClient(_toy().create_app()) as client: + tasks = [] + for tag in ("t1", "t2"): + tasks.append(_send(client, f"hooks {tag}", f"m-{tag}")) + _ended(client, tasks[-1]) + final = _atif(client, task_id=tasks[1]) + natives = [_read(client, task_id=task).json()["trajectory"] for task in tasks] + served = [_atif(client, task_id=task) for task in tasks] + objects = _atif(client, task_id=tasks[1], objects=grants) + refused = _read(client, task_id=tasks[1], objects=grants) + document = final["trajectory"] + assert [step["message"] for step in document["steps"] if step["message"].endswith("allowed ls")] == [ + "the pre-tool hook allowed ls"] * 2 + assert final["aux"][0] == {"name": "hooks", "record": {"type": "note", "step": "t2-h", + "text": "the pre-tool hook allowed ls"}, "after": 1} + turn = final["turn_context"] + assert (turn["index"], turn["task_id"], turn["state"], turn["final"]) == (1, tasks[1], "completed", + ["t2: two files"]) + replayed = replay(Hooks, [RecordedTask.from_served(answer["turn_context"], native, answer["aux"]) + for answer, native in zip(served, natives)], trajectory_id=document["trajectory_id"]) + assert replayed == document + assert set(objects["objects"]) == {"trajectory", "aux", "turn_context"} + assert json.loads(uploaded["aux"]) == final["aux"] + assert json.loads(uploaded["turn_context"]) == turn + assert json.loads(uploaded["trajectory"]) == document + # The aux log and turn context ride an atif/1 task read only. + assert refused.status_code == 400 + + +def test_an_atif_context_read_goes_to_the_sdk_even_when_the_agent_binds_its_own() -> None: + with TestClient(_toy(bind_context=True).create_app()) as client: + task_id = _send(client, "work t1", "m-1") + _ended(client, task_id) + own = _read(client, context_id="ctx-1").json() + atif = _atif(client, context_id="ctx-1") + assert own == {"trajectory": ["the agent's own shape"], "format": "toy-session/1"} + assert atif["format"] == FORMAT and errors_in(validate(atif["trajectory"])) == [] + + +def test_data_parts_are_written_as_the_conversation_or_the_profile() -> None: + image = base64.b64encode(b"\x89PNG fake").decode() + with TestClient(_toy().create_app()) as client: + task_id = _send(client, "data t1", "m-1", extra_parts=[ + {"kind": "data", "data": {"ticket": 42, "priority": "high"}}, + {"kind": "file", "file": {"name": "shot.png", "mimeType": "image/png", "bytes": image}}, + {"kind": "file", "file": {"name": "log.txt", "mimeType": "text/plain", + "uri": "https://objects.example.test/log.txt?X-Signature=secret"}}]) + _ended(client, task_id) + document = _atif(client, task_id=task_id)["trajectory"] + assert errors_in(validate(document)) == [] + user = document["steps"][0] + texts = [part["text"] for part in user["message"] if part["type"] == "text"] + assert texts[:2] == ["data t1", '{"ticket":42,"priority":"high"}'] + assert "secret" not in json.dumps(user) and texts[2] == "[file: log.txt, text/plain, https://objects.example.test/log.txt]" + assert [part["type"] for part in user["message"]] == ["text", "text", "image", "text"] + last = document["steps"][-1] + assert last["message"] == 't1: two files\n\n{"files":["a.txt","b.txt"]}' + assert last["extra"]["agentenv"]["data"] == [{"data": {"tool_call_count": 1, "cli_attempts": 2}}] + assert "usage" not in json.dumps(last["extra"]) + + +def test_an_adapter_agent_that_appends_and_returns_fails_the_turn() -> None: + with TestClient(_toy().create_app()) as client: + task_id = _send(client, "both t1", "m-1") + _ended(client, task_id, "failed") + answer = client.post("/a2a", json={"jsonrpc": "2.0", "id": "g", "method": "tasks/get", + "params": {"id": task_id}}).json()["result"] + document = _atif(client, task_id=task_id)["trajectory"] + assert "framework.trajectory_appended_and_returned" in json.dumps(answer["status"]) + assert document["steps"][-1]["extra"]["agentenv"]["error"]["code"] == "framework.trajectory_appended_and_returned" + + +def test_a_returned_native_trajectory_runs_through_the_adapter_when_the_task_ends() -> None: + with TestClient(_toy(live=False).create_app()) as client: + task_id = _send(client, "returned t1", "m-1") + _ended(client, task_id) + document = _atif(client, task_id=task_id)["trajectory"] + native = _read(client, task_id=task_id).json() + assert native == {"trajectory": _work("t1"), "format": NATIVE} + assert errors_in(validate(document)) == [] + assert [step["message"] for step in document["steps"]] == ["returned t1", "t1: listing", "t1: two files"] + + +def test_an_adapter_error_stops_the_copy_not_the_turn() -> None: + with TestClient(_toy().create_app()) as client: + task_id = _send(client, "broken t1", "m-1") + _ended(client, task_id) + native = _read(client, task_id=task_id) + refused = _read(client, task_id=task_id, format=FORMAT) + later = _send(client, "work t2", "m-2") + _ended(client, later) + assert native.status_code == 200 and len(native.json()["trajectory"]) == 3 + assert refused.status_code == 409 + error = refused.json()["error"] + assert error["code"] == "atif_unavailable" and "no-such-call" in error["message"] + + +def test_cursor_pages_carry_the_header_and_their_tasks_sub_agents() -> None: + with TestClient(_toy().create_app()) as client: + task_id = _send(client, "spawn t1", "m-1") + _ended(client, task_id) + document = _atif(client, task_id=task_id)["trajectory"] + pages = [] + after = 0 + while True: + page = _atif(client, context_id="ctx-1", after=after, limit=1) + pages.append(page) + after = page["next"] + if not page["has_more"]: + break + assert errors_in(validate(document)) == [] + assert [len(page["events"]) for page in pages] == [1] * len(document["steps"]) + spawning = next(page for page in pages if any( + "subagent_trajectory_ref" in result for result in page["events"][0].get("observation", {}).get("results", []))) + assert [sub["trajectory_id"] for sub in spawning["subagents"]] == ["t1-sub"] + assert _rebuild(pages) == document + + +def test_a_reader_following_the_cursor_gets_the_steps_a_sub_agent_writes_after_its_result() -> None: + hold = _Hold() + pages = [] + with TestClient(_toy(hold).create_app()) as client: + task_id = _send(client, "grow t1", "m-1") + hold.reached() + while not pages or pages[-1]["has_more"]: + pages.append(_atif(client, context_id="ctx-1", after=pages[-1]["next"] if pages else 0)) + early = [sub["steps"] for page in pages for sub in page["subagents"]] + hold.resume.set() + _ended(client, task_id) + while pages[-1]["has_more"] or pages[-1]["state"] != "completed": + pages.append(_atif(client, context_id="ctx-1", after=pages[-1]["next"])) + document = _atif(client, task_id=task_id)["trajectory"] + # While the task ran the sub-agent had one closed step; the page that served the task's last step had all three. + assert [len(steps) for steps in early][-1] == 1 + assert [len(sub["steps"]) for sub in pages[-1]["subagents"]] == [3] + assert _rebuild(pages) == document + + +def test_a_spawn_its_task_ended_without_answering_keeps_its_sub_agent_referenced() -> None: + hold = _Hold() + with TestClient(_toy(hold).create_app()) as client: + task_id = _send(client, "orphan t1", "m-1") + hold.reached() + client.post("/a2a", json={"jsonrpc": "2.0", "id": "c", "method": "tasks/cancel", "params": {"id": task_id}}) + _ended(client, task_id, "canceled") + document = _atif(client, task_id=task_id)["trajectory"] + assert errors_in(validate(document)) == [] + (result,) = document["steps"][1]["observation"]["results"] + assert result["subagent_trajectory_ref"] == [{"trajectory_id": "t1-sub"}] + assert result["extra"]["agentenv"] == {"status": "canceled"} + + +def test_an_unknown_or_unfinished_read_is_not_found() -> None: + hold = _Hold() + with TestClient(_toy(hold).create_app()) as client: + task_id = _send(client, "canceled t1", "m-1") + hold.reached() + unfinished = _read(client, task_id=task_id, format=FORMAT) + unknown = _read(client, context_id="nowhere", format=FORMAT) + past = _read(client, context_id="ctx-1", after=99, format=FORMAT) + hold.resume.set() + _ended(client, task_id) + assert (unfinished.status_code, unknown.status_code, past.status_code) == (404, 404, 400) + + +def test_two_messages_sent_at_once_in_one_context_are_two_tasks_of_one_document() -> None: + # The second waits on the context's lock; the first is closed in the copy before that lock lets the second start. + with TestClient(_toy().create_app()) as client: + first = _send(client, "work t1", "m-1") + second = _send(client, "work t2", "m-2") + _ended(client, first) + _ended(client, second) + document = _atif(client, task_id=second)["trajectory"] + assert errors_in(validate(document)) == [] + users = [step["extra"]["agentenv"] for step in document["steps"] if step["source"] == "user"] + assert [(user["task_id"], user["turn"]) for user in users] == [(first, 0), (second, 1)] + + +def test_an_agent_on_the_envs_clock_stamps_the_sdks_steps_with_the_time_its_programs_read(tmp_path, monkeypatch): + clock_file = tmp_path / "clock" + clock_file.write_text(f"@1748768400.000000000 x1 ^{time.time()}\n") + monkeypatch.setattr(follower, "CLOCK_FILE", str(clock_file)) + monkeypatch.setattr(agent_clock, "follows", lambda: True) + with TestClient(_toy().create_app()) as client: + task_id = _send(client, "data t1", "m-1") + _ended(client, task_id) + answer = _atif(client, task_id=task_id) + steps = answer["trajectory"]["steps"] + # The user step and the final response are the SDK's; both are on the universe's 2025-06-01, as the harness is. + assert steps[0]["timestamp"].startswith("2025-06-01T09:0") and steps[-1]["timestamp"].startswith("2025-06-01T09:0") + assert answer["turn_context"]["started_at"].startswith("2025-06-01") and answer["turn_context"]["ended_at"].startswith("2025-06-01") diff --git a/packages/agentenv-protocol/tests/test_atif_builder.py b/packages/agentenv-protocol/tests/test_atif_builder.py index b4a349d30..cfac7e885 100644 --- a/packages/agentenv-protocol/tests/test_atif_builder.py +++ b/packages/agentenv-protocol/tests/test_atif_builder.py @@ -4,6 +4,7 @@ import math import pytest +from pydantic import ValidationError from agentenv_protocol.atif import ( Adapter, @@ -20,6 +21,7 @@ is_prefix, native, profile_of, + ServedTurn, replay, timestamp, ) @@ -570,3 +572,119 @@ def sink(path, data): media = run.media(b"shot", "image/png") run.media(b"shot", "image/png") assert taken == [None, media.path] + + +def test_a_document_names_the_trajectory_id_it_was_given(): + run = AdapterRun(adapter(), trajectory_id="doc-1") + run.start_task(CTX) + run.end_task(final=["done"]) + document = run.document() + assert (document["session_id"], document["trajectory_id"]) == ("ctx", "doc-1") + assert check(document) + assert "trajectory_id" not in replay(adapter(), [RecordedTask(context=CTX, final=["done"])]) + + +def test_a_document_through_an_ended_task_is_the_document_as_it_stood_then(): + run = AdapterRun(adapter()) + run.start_task(CTX) + run.native({"type": "say", "step": "a", "text": "first"}) + run.native({"type": "usage", "step": "a", "in": 5, "out": 2}) + run.end_task(final=["first"]) + then = run.document() + run.start_task(TurnContext(index=1, context_id="ctx", task_id="t2", inbound=["again"])) + run.native({"type": "say", "step": "b", "text": "second"}) + run.native({"something": "unhandled"}) + assert run.document(through=0) == then + run.end_task(final=["second"]) + assert run.document(through=0) == then + assert run.document(through=1) == run.document() + with pytest.raises(AtifError, match="hasn't ended"): + run.document(through=2) + + +def test_a_tasks_diagnostics_and_error_go_on_its_last_step(): + run = AdapterRun(adapter()) + run.start_task(CTX) + run.native({"type": "say", "step": "a", "text": "trying"}) + run.end_task(state="failed", final=["it broke"], data=[{"data": {"tool_call_count": 0}, "metadata": {"k": 1}}], + error={"kind": "agent_error", "message": "it broke", "code": "toy.broke"}) + profile = profile_of(run.document()["steps"][-1]) + assert profile["state"] == "failed" + assert profile["data"] == [{"data": {"tool_call_count": 0}, "metadata": {"k": 1}}] + assert profile["error"] == {"kind": "agent_error", "message": "it broke", "code": "toy.broke"} + assert check(run.document()) + + +@pytest.mark.parametrize("data, error", [ + ([{"tool_call_count": 0}], None), + ({"data": 1}, None), + (None, {"kind": "mystery", "message": "x"}), + (None, {"message": ""}), + (None, {"message": "x", "extra": 1}), +]) +def test_a_tasks_diagnostics_and_error_are_checked_before_anything_is_written(data, error): + run = AdapterRun(adapter()) + run.start_task(CTX) + with pytest.raises(AtifError): + run.end_task(data=data, error=error) + + +def test_a_spawn_that_never_got_its_result_is_answered_canceled_when_its_task_ends(): + @atif_adapter(native_format="toy-events/1", version="0.1.0", input_includes_cache=False) + class Spawning(adapter()): + @native(type="spawn") + def spawn(self, r, turn): + turn.subagent("sub", spawned_by=r["id"], name="explorer") + + @native(type="sub") + def sub(self, r, turn): + turn.message(step=r["step"], text=r["text"], agent="sub") + + run = AdapterRun(Spawning) + run.start_task(CTX) + for record in ({"type": "call", "step": "a", "id": "c1"}, {"type": "spawn", "id": "c1"}, + {"type": "sub", "step": "s", "text": "looking"}, {"type": "call", "step": "a", "id": "c2"}): + run.native(record) + run.end_task(state="canceled") + document = run.document() + results = document["steps"][1]["observation"]["results"] + assert results == [{"source_call_id": "c1", "content": "", "subagent_trajectory_ref": [{"trajectory_id": "sub"}], + "extra": {"agentenv": {"status": "canceled"}}}] + assert check(document) + + +def test_a_served_turn_gives_the_recorded_task_back(): + run = AdapterRun(adapter()) + shot = run.media(b"\x89PNG", "image/png", width=2, height=2) + context = TurnContext(index=3, context_id="ctx", task_id="t1", message_id="m1", inbound=["look", shot], + agent_name="toy", agent_version="1.0", started_at="2026-11-18T10:00:00.5Z") + records = [{"type": "say", "step": "a", "text": "a picture"}] + turn = ServedTurn.of(context, state="completed", final=["a picture"], ended_at="2026-11-18T10:00:01Z", + data=[{"data": {"n": 1}}]).wire() + assert turn["started_at"] == "2026-11-18T10:00:00.500Z" + assert turn["inbound"][1] == {"media": {"path": shot.path, "media_type": "image/png", "info": dict(shot.info)}} + assert "message_id" in turn and "error" not in turn + recorded = RecordedTask.from_served(turn, records, [{"name": "hooks", "record": None, "after": 1}]) + assert recorded.context.inbound == ("look", shot) + assert recorded.records == [Fed(records[0]), Fed(None, aux="hooks")] + assert (recorded.state, recorded.final, recorded.data) == ("completed", ["a picture"], [{"data": {"n": 1}}]) + + +def test_a_served_turn_keeps_a_null_it_requires_so_replay_rebuilds_the_document(): + run = AdapterRun(adapter()) + run.start_task(CTX) + error = {"kind": "agent_error", "message": "it broke", "code": None} + run.end_task(final=["done"], data=[{"data": None}], error=error) + turn = ServedTurn.of(CTX, state="completed", final=["done"], data=[{"data": None}], error=error).wire() + assert (turn["data"], turn["error"]) == ([{"data": None}], {"kind": "agent_error", "message": "it broke"}) + assert replay(adapter(), [RecordedTask.from_served(turn, [])]) == run.document() + + +@pytest.mark.parametrize("turn, aux", [ + ({"index": -1, "context_id": "ctx", "task_id": "t1", "state": "completed"}, []), + ({"index": 0, "context_id": "ctx", "task_id": "t1", "state": "completed", "surprise": 1}, []), + ({"index": 0, "context_id": "ctx", "task_id": "t1", "state": "completed"}, [{"name": "hooks", "after": -1}]), +]) +def test_a_served_turn_or_aux_log_that_breaks_its_shape_is_refused(turn, aux): + with pytest.raises(ValidationError): + RecordedTask.from_served(turn, [], aux) diff --git a/src/agent_env/a2a_agent/object_transfer.py b/src/agent_env/a2a_agent/object_transfer.py index 336b25790..6905ed47c 100644 --- a/src/agent_env/a2a_agent/object_transfer.py +++ b/src/agent_env/a2a_agent/object_transfer.py @@ -659,7 +659,8 @@ async def fetch_trajectory( payload: dict[str, Any] = dict(selector) if upload is not None: objects = TrajectoryWriteObjects(trajectory=upload.write) - payload["objects"] = objects.model_dump(mode="json") + # Only the grants given: a pinned agent's request model forbids the optional ones newer SDKs take. + payload["objects"] = objects.model_dump(mode="json", exclude_none=True) call = TransferCall("objects" if upload is not None else "legacy", payload) if timeout is None: timeout = TRANSFER_TIMEOUT_SECONDS if upload is not None else REPLY_TIMEOUT_SECONDS diff --git a/src/agent_env/agents/AGENTS.md b/src/agent_env/agents/AGENTS.md index a25b5086d..9cc1f440c 100644 --- a/src/agent_env/agents/AGENTS.md +++ b/src/agent_env/agents/AGENTS.md @@ -142,7 +142,10 @@ serves the reads; bind `get.context` and `get.context_objects` to serve a whole `native=""` in that `enable` declares the format: the card lists it as `formats`, `native` and `default`, a read naming any other format is refused before your handlers run, and the log and a returned `native_trajectory` must be in it. It needs a protocol floor that has `native`. A context read you bind names the format it serves as -`format` in its response. +`format` in its response. `atif=` there, an `@atif_adapter` class for that native format, has the SDK +serve `atif/1` too, built from your log as you append it: write the adapter (`agentenv_protocol.atif`, its +`PROFILE.md`), feed records that aren't in the native log, such as hooks' notes, with +`request.trajectory.aux(name, record)`, and append or return a native trajectory, not both. Reference: `enable(TRAJECTORY_V1, live=True, ...)`, `ClaudeCodeAgent.run` passing `event_callback=request.trajectory.append`, and `get_context_trajectory` / `upload_context_trajectory`. A runtime diff --git a/tst/data/a2a_agent/agent.py b/tst/data/a2a_agent/agent.py index 847751f7f..bf1596177 100644 --- a/tst/data/a2a_agent/agent.py +++ b/tst/data/a2a_agent/agent.py @@ -2,7 +2,8 @@ Deterministic: it echoes the prompt and records the echo in the framework's trajectory log, which a reader can follow while the turn runs; a ``live-steps `` in its prompt has it first append ``n`` step -events (at most ``MAX_LIVE_STEPS``), a second apart. Agent-config, mcp-config, trajectory and triggers +events (at most ``MAX_LIVE_STEPS``), a second apart. Its ATIF adapter, ``EchoAtif``, has the framework serve +the log as atif/1 too, each event a step. Agent-config, mcp-config, trajectory and triggers come from the agentenv-protocol framework. ``model_params`` is a write-only config field so the agent-config negotiation and its redaction on read-back can be observed. @@ -56,6 +57,7 @@ enable, extension, ) +from agentenv_protocol.atif import Adapter, atif_adapter, native from websockets.asyncio.client import connect SEND_FILE = "send-file " @@ -161,6 +163,22 @@ def _skills() -> list[str]: for path in sorted(folder.rglob("*")) if path.is_file()) for folder in sorted(SKILLS_DIR.iterdir())] +@atif_adapter(native_format=TRAJECTORY_FORMAT, version="1.0.0", input_includes_cache=None) +class EchoAtif(Adapter): + """The echo agent's events in ATIF: each live step and the echo, a step with no model call.""" + + @native(type="step") + def step(self, record: dict[str, Any], turn: Any) -> None: + key = f"step-{record['step']}" + turn.message(step=key, text=f"step {record['step']}") + turn.step(key=key, llm_call_count=0) + + @native(type="echo") + def echo(self, record: dict[str, Any], turn: Any) -> None: + turn.message(step="echo", text=record["output"]) + turn.step(key="echo", llm_call_count=0) + + @a2a_agent( identity=AgentIdentity( name="agentenv-echo-agent", @@ -168,7 +186,10 @@ def _skills() -> list[str]: version="1.0.0", ), config=EchoAgentConfig, - extensions=(MCP_CONFIG_V1, CDP_CONFIG_V1, enable(TRAJECTORY_V1, live=True, native=TRAJECTORY_FORMAT), TRIGGERS_V1), + extensions=( + MCP_CONFIG_V1, CDP_CONFIG_V1, enable(TRAJECTORY_V1, live=True, native=TRAJECTORY_FORMAT, atif=EchoAtif), + TRIGGERS_V1, + ), ) class EchoAgent(AgentEnvAgent): async def run(self, request: TaskRequest[EchoAgentConfig]) -> TaskResult: 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 fa95206d4..1d0a3dede 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 @@ -2,8 +2,9 @@ defaults. The agents are the echo agent (tst/data/a2a_agent), which appends a step a second before its echo, so a turn runs for a few seconds; over a two-turn conversation with a user-sim, each turn is stored under its own prefix, 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, which its card offers and its reads name, and a read -naming another format is refused with a code agent-env reads. Needs Docker and a throwaway local registry.""" +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.""" import json import re @@ -16,6 +17,8 @@ import httpx import pytest +from agentenv_protocol.atif import FORMAT as ATIF, PROFILE_VERSION, SCHEMA_VERSION, errors_in, validate + from agent_env.a2a_agent import A2AAgent from agent_env.a2a_agent.protocol import raise_for_extension_status from agent_env.artifact.store import reset_artifact_store @@ -135,7 +138,7 @@ async def test_each_turn_is_stored_live_under_its_own_prefix_and_joins_to_its_fi @pytest.mark.asyncio -async def test_a_deployed_agent_serves_its_native_format_and_refuses_another(local_registry): +async def test_a_deployed_agent_serves_its_native_format_and_atif_and_refuses_another(local_registry): suffix = uuid.uuid4().hex[:8] native = "agentenv-echo-agent/v1" agent = put_test_agent(f"trajectory-formats-agent-{suffix}") @@ -152,7 +155,7 @@ async def test_a_deployed_agent_serves_its_native_format_and_refuses_another(loc assert not context.metadata.get("failed_steps"), context.metadata.get("failed_steps") [deployed] = context.deployed_agents params = A2AAgent.find_extension(deployed.a2a_card, A2AAgent.EXT_TRAJECTORY)["params"] - assert (params["formats"], params["native"], params["default"]) == ([native], native, native) + assert (params["formats"], params["native"], params["default"]) == ([native, ATIF], native, native) url = deployed.a2a_url + params["endpoint"] async with httpx.AsyncClient(timeout=30, headers=deployed.control_headers) as client: page = (await client.post(url, json={"context_id": f"formats-{suffix}", "after": 0})).json() @@ -160,7 +163,15 @@ async def test_a_deployed_agent_serves_its_native_format_and_refuses_another(loc for named in ({}, {"format": native}): final = (await client.post(url, json={"task_id": page["task_id"], **named})).json() assert (final["format"], [event["type"] for event in final["trajectory"]]) == (native, ["echo"]) - refused = await client.post(url, json={"task_id": page["task_id"], "format": "atif/1"}) + atif = (await client.post(url, json={"task_id": page["task_id"], "format": ATIF})).json() + cursor = (await client.post(url, json={"context_id": f"formats-{suffix}", "after": 0, "format": ATIF})).json() + refused = await client.post(url, json={"task_id": page["task_id"], "format": "other-events/1"}) + document = atif["trajectory"] + assert (atif["format"], atif["schema_version"], atif["profile_version"]) == (ATIF, SCHEMA_VERSION, PROFILE_VERSION) + assert errors_in(validate(document)) == [] + assert [step["message"] for step in document["steps"]] == ["hello", "Echo: hello"] + assert (document["session_id"], atif["turn_context"]["task_id"]) == (f"formats-{suffix}", page["task_id"]) + assert cursor["events"] == document["steps"] and cursor["header"]["trajectory_id"] == document["trajectory_id"] with pytest.raises(httpx.HTTPStatusError, match="HTTP 400: format_not_offered"): raise_for_extension_status(refused, operation="trajectory read") diff --git a/tst/unit/a2a_agent/object_transfer_test.py b/tst/unit/a2a_agent/object_transfer_test.py index cc680292d..39f2bdcff 100644 --- a/tst/unit/a2a_agent/object_transfer_test.py +++ b/tst/unit/a2a_agent/object_transfer_test.py @@ -1,5 +1,7 @@ """The core side of object transfer: choosing a form from the card, descriptors, responses.""" +import json + import httpx import pytest from agentenv_protocol.a2a_agent import TrajectoryObjectsResponse @@ -220,6 +222,29 @@ def answer(request: httpx.Request) -> httpx.Response: ] +@pytest.mark.asyncio +async def test_a_trajectory_upload_grants_only_the_trajectory_so_a_pinned_agent_accepts_it(tmp_path, monkeypatch): + sent = [] + real_client = httpx.AsyncClient + + def answer(request: httpx.Request) -> httpx.Response: + sent.append(json.loads(request.content)) + return httpx.Response(200, json={"objects": {"trajectory": {"size_bytes": 2}}}) + + monkeypatch.setattr( + object_transfer.httpx, + "AsyncClient", + lambda **kwargs: real_client(transport=httpx.MockTransport(answer), **kwargs), + ) + store = GrantingObjectStore(str(tmp_path)) + upload = TrajectoryUpload.to(store, store.object_url("t/trajectory.json")) + + await fetch_trajectory("https://agent.test/ext/trajectory", {"task_id": "t"}, upload=upload) + + [request] = sent + assert set(request["objects"]) == {"trajectory"} + + def _answering(monkeypatch, body: dict) -> None: real_client = httpx.AsyncClient monkeypatch.setattr( diff --git a/tst/unit/env/envs/test_computer_clock_follower.py b/tst/unit/env/envs/test_computer_clock_follower.py index a0ce82c4c..9f57d3f2d 100644 --- a/tst/unit/env/envs/test_computer_clock_follower.py +++ b/tst/unit/env/envs/test_computer_clock_follower.py @@ -131,6 +131,21 @@ def test_the_followers_paths_are_the_ones_core_and_the_driver_use(): assert f'"{protocol_clock.CONFIG}"' in source and f'"{protocol_clock.STATUS}"' in source +def test_the_clock_file_the_follower_writes_reads_as_its_universe_to_a_server_on_real_time(tmp_path, monkeypatch): + assert f'"{protocol_clock.CLOCK_FILE}"' in (CLOCK / "clockpage.py").read_text() + assert f"FAKETIME_TIMESTAMP_FILE={protocol_clock.CLOCK_FILE}" in (CLOCK / "clock.conf").read_text() + clockpage = _clockpage(tmp_path / "page") + clockpage.FILE = str(tmp_path / "clock") + monkeypatch.setattr(protocol_clock, "CLOCK_FILE", clockpage.FILE) + assert protocol_clock.session_time() == pytest.approx(time.time(), abs=1) + anchor = time.time() - 10 + clockpage.write(1, 1748768400.0, 2.0, anchor) + assert protocol_clock.session_time() == pytest.approx( + clockpage._universe_at(1, 1748768400 * 10**9, int(anchor * 10**9), 2.0, time.time_ns()) / 1e9, abs=0.5) + clockpage.write(0, 0.0, 1.0, time.time()) + assert protocol_clock.session_time() == pytest.approx(time.time(), abs=1) + + def test_it_follows_the_gateway_its_config_names_and_acknowledges_each_version_with_its_next_watch(follower): gateway = Gateway() try: