From 5e03dba51b1409a6b28d8ea9965c4f7abd70ded8 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 21:59:41 -0800 Subject: [PATCH 1/7] feat(protocol): the SDK serves atif/1 from an agent's ATIF adapter enable(TRAJECTORY_V1, native=..., atif=Adapter) adds atif/1 to the card's formats. The SDK keeps one document per A2A context, fed every event the agent appends and every aux record its code feeds, and serves atif/1 task, context, cursor and final reads, context reads an agent binds included. A task read is the document as it stood when the task ended, with its aux log and turn context; cursor pages carry the header and the sub-agents their steps reference. An adapter that raises stops its context's copy, not the turn. Part of FD-6076 (Y2b-1, -3, -5, -6, -7). Co-Authored-By: Claude Opus 5.5 --- packages/agentenv-protocol/README.md | 44 ++ .../agentenv_protocol/a2a_agent/__init__.py | 6 + .../agentenv_protocol/a2a_agent/_atif_copy.py | 274 +++++++++ .../a2a_agent/_trajectory_log.py | 138 ++++- .../agentenv_protocol/a2a_agent/extensions.py | 69 ++- .../agentenv_protocol/a2a_agent/framework.py | 170 +++++- .../agentenv_protocol/a2a_agent/tasks/v1.py | 39 +- .../src/agentenv_protocol/atif/PROFILE.md | 14 +- .../src/agentenv_protocol/atif/__init__.py | 9 +- .../src/agentenv_protocol/atif/builder.py | 115 +++- .../src/agentenv_protocol/atif/profile.py | 8 + .../src/agentenv_protocol/atif/runner.py | 93 +++- .../tests/test_a2a_atif_serving.py | 520 ++++++++++++++++++ .../tests/test_atif_builder.py | 96 ++++ src/agent_env/agents/AGENTS.md | 5 +- tst/data/a2a_agent/agent.py | 25 +- ...test_prompt_agent_live_trajectory_local.py | 21 +- 17 files changed, 1553 insertions(+), 93 deletions(-) create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_atif_copy.py create mode 100644 packages/agentenv-protocol/tests/test_a2a_atif_serving.py diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index 09e21129b..7740f4202 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1598,6 +1598,50 @@ 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. `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. 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, and `subagents`, the embedded + sub-agent trajectories its steps reference. + +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..b92e336f0 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_atif_copy.py @@ -0,0 +1,274 @@ +"""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 dataclasses import dataclass, field +from datetime import datetime, timezone +from typing import Any, Iterable, Sequence +from urllib.parse import urlsplit, urlunsplit + +from ..atif import FORMAT, PROFILE_KEY, Adapter, AdapterRun, Media, TurnContext, served_turn +from ..errors import AgentEnvError +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[dict[str, Any]] = field(default_factory=list) + turn: dict[str, Any] | 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``.""" + + 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 + + def start(self, task_id: str, index: int, turn: TurnStart) -> None: + with self._lock: + if self._failed is not None: + return + try: + context = TurnContext( + index=index, context_id=self._context_id, task_id=task_id, message_id=turn.message_id, + inbound=_content(turn.parts, self._run)[0], agent_name=turn.agent_name, + agent_version=turn.agent_version, agent_model=turn.agent_model, started_at=_now()) + self._run.start_task(context) + except Exception as exc: + self._fail(exc) + return + 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: + 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 + task.aux.append({"name": name, "record": record, "after": task.natives}) + try: + self._run.aux(name, record) + except Exception as exc: + self._fail(exc) + + 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 + try: + for record in (native if isinstance(native, list) else [native]) if native is not None else (): + self._feed(task, record) + if self._failed is not None: + return + content, data = _content(final, self._run, answer=True) + failure = None if error is None else {"kind": error.error_type, "message": error.message, + "code": error.code} + ended = _now() + ending = {"state": state, "final": content or None, "ended_at": ended, "data": data or None, + "error": failure} + self._run.end_task(**ending) + task.turn = served_turn(task.context, **ending) + except Exception as exc: + self._fail(exc) + finally: + task.ended = True + + def task_read(self, task_id: str) -> tuple[dict[str, Any], list[dict[str, Any]], dict[str, Any]] | 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, json.loads(json.dumps(task.aux)), dict(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 self._lock: + self._check() + document = self._run.page() + 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") + scope = [step for step, owner in zip(steps, _owners(steps)) if task_id is None or owner == task_id] + pending = [step for step in scope if step["step_id"] > after] + served: list[dict[str, Any]] = [] + used = 0 + for step in pending[:max_steps]: + size = len(json.dumps(step)) + if served and used + size > max_bytes: + break + served.append(step) + used += size + header = None + if document is not None: + header = {key: value for key, value in document.items() + if key not in ("steps", "subagent_trajectories", "final_metrics")} + return AtifPage(header=header, subagents=_referenced(served, (document or {}).get("subagent_trajectories", [])), + 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: + try: + self._run.native(record) + except Exception as exc: + self._fail(exc) + task.natives += 1 + + def _fail(self, exc: Exception) -> None: + 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 _now() -> datetime: + return datetime.now(timezone.utc) + + +def _content(parts: Iterable[Any], run: AdapterRun, *, answer: bool = False) -> tuple[list[Any], list[dict[str, Any]]]: + """A2A parts 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. In a final response (``answer``), a DataPart other than a structured output is the + harness's diagnostics, so it goes to the data list for the profile instead.""" + 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 answer and set(value) == {STRUCTURED_OUTPUT}: + content.append(_compact(value[STRUCTURED_OUTPUT])) + elif answer: + entry: dict[str, Any] = {"data": value} + if part.metadata: + entry["metadata"] = _thaw(part.metadata) + data.append(entry) + else: + content.append(_compact(value)) + 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) + + +def _owners(steps: Sequence[dict[str, Any]]) -> list[str | None]: + """The task each step belongs to: the one whose user step opened the run of steps it's in.""" + owners: list[str | None] = [] + owner = None + for step in steps: + if step.get("source") == "user": + owner = ((step.get("extra") or {}).get(PROFILE_KEY) or {}).get("task_id", owner) + owners.append(owner) + return owners + + +def _referenced(steps: Sequence[dict[str, Any]], subagents: Sequence[dict[str, Any]]) -> list[dict[str, Any]]: + """The embedded sub-agent trajectories ``steps`` reference, and those they reference in turn, in document + order.""" + by_id = {sub["trajectory_id"]: sub for sub in subagents} + wanted: set[str] = set() + frontier = list(steps) + while frontier: + step = frontier.pop() + for result in (step.get("observation") or {}).get("results", []): + for ref in result.get("subagent_trajectory_ref") or (): + trajectory_id = ref.get("trajectory_id") + if trajectory_id in by_id and trajectory_id not in wanted: + wanted.add(trajectory_id) + frontier.extend(by_id[trajectory_id]["steps"]) + return [sub for sub in subagents if sub["trajectory_id"] in wanted] 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..efbbade0f 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 +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__) @@ -57,27 +61,39 @@ 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, + aux=frozenset(self._atif.spec.aux) 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 +104,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 +125,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 +144,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 +205,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 +227,75 @@ 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 + ) -> tuple[dict[str, Any], list[dict[str, Any]], dict[str, Any]] | 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) + return copy.task_read(task_id) + + 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 + ) -> tuple[AtifPage, str, TrajectoryState] | None: + """A cursor page of the task's closed atif/1 steps, its context id and 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 + return copy.page(after, max_steps, max_bytes, task_id=task_id), record.context_id, state + + def atif_context_page( + self, context_id: str, after: int, max_steps: int, max_bytes: int + ) -> tuple[AtifPage, str, TrajectoryState] | None: + """A cursor page of the context's closed atif/1 steps, the current task's id and 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) + return copy.page(after, max_steps, max_bytes), task_id, 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 +317,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..04f932945 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,25 @@ 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 ``subagents`` the embedded sub-agent trajectories these + steps reference, whole, so the page stands alone; the last page's header with every page's steps and 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 +1155,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..c025aa09f 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,14 @@ async def trajectory_get( | ContextObjectTrajectoryRequest | ContextEventsTrajectoryRequest, ) -> Any: + if request.format == ATIF_FORMAT: + return await self._atif_get(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 +862,88 @@ async def trajectory_get( objects=TrajectoryUploadedObjects(trajectory=uploaded), format=trajectory.format ) + async def _atif_get( + self, + request: TaskTrajectoryRequest + | TaskObjectTrajectoryRequest + | TaskEventsTrajectoryRequest + | ContextTrajectoryRequest + | ContextObjectTrajectoryRequest + | ContextEventsTrajectoryRequest, + ) -> dict[str, Any]: + """An atif/1 read, served from the context's copy: a task read is the document as it + stood when the task ended, with its aux log and turn context; a context read is the live + page; a cursor read pages closed steps by ``step_id``.""" + trajectories = self.task_trajectories + if isinstance(request, (TaskEventsTrajectoryRequest, ContextEventsTrajectoryRequest)): + max_steps = request.limit or MAX_TRAJECTORY_READ_EVENTS + try: + if isinstance(request, TaskEventsTrajectoryRequest): + found = trajectories.atif_task_page( + request.task_id, request.after, max_steps, MAX_TRAJECTORY_READ_BYTES + ) + unknown = f"Unknown task '{request.task_id}'" + else: + found = 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 found is None: + raise HTTPException(status_code=404, detail=unknown) + if isinstance(request, TaskEventsTrajectoryRequest): + page, context_id, state = found + task_id = request.task_id + else: + page, task_id, state = found + context_id = request.context_id + return AtifEventsResponse( + context_id=context_id, + task_id=task_id, + state=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) + aux: list[dict[str, Any]] | None = None + turn: dict[str, Any] | None = None + if isinstance(request, (TaskTrajectoryRequest, TaskObjectTrajectoryRequest)): + found_task = trajectories.atif_task(request.task_id) + if found_task is None: + raise HTTPException( + status_code=404, + detail=f"No completed trajectory available for task '{request.task_id}'", + ) + document, aux, turn = found_task + else: + if isinstance(request, ContextObjectTrajectoryRequest): + _refuse_turn_objects(request) + document = 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)): + answer: dict[str, Any] = {"trajectory": document, "format": ATIF_FORMAT, **versions} + if turn is not None: + answer.update(aux=aux, turn_context=turn) + return answer + 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(aux)), + turn_context=( + None if objects.turn_context is None else await upload(objects.turn_context, _json_bytes(turn)) + ), + ) + 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 +1331,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 +1445,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 +1476,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 +1498,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 +1510,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 +1600,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..9027f907a 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 @@ -156,11 +156,15 @@ 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 + (``aux`` names the aux files it declares), 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", "_aux_names", "_atif", + ) - def __init__(self, *, native: str | None = None) -> None: + def __init__(self, *, native: str | None = None, aux: frozenset[str] | None = None) -> None: self._events: list[bytes] = [] self._size_bytes = 0 self._format: str | None = native @@ -168,6 +172,8 @@ def __init__(self, *, native: str | None = None) -> None: self._sealed = False self._task_id: str | None = None self._warned = False + self._aux_names = aux + self._atif: Any = None @property def format(self) -> str | None: @@ -195,6 +201,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 +211,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._aux_names is None: + raise RuntimeError("aux records feed an ATIF adapter: enable(TRAJECTORY_V1, native=..., atif=...)") + if name not in self._aux_names: + 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._aux_names 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..094002d93 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,7 +50,12 @@ 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 @@ -109,6 +118,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..4414d33eb 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, @@ -46,7 +47,7 @@ ) 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 .runner import AdapterRun, Fed, RecordedTask, replay, served_turn from .validator import RULES, Finding, Rule, errors_in, validate, validate_live __all__ = [ @@ -56,7 +57,7 @@ "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", + "RULES", "SCHEMA_VERSION", "Selector", "served_turn", "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..19f50ec11 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,9 +458,12 @@ 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 @@ -509,10 +535,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 +554,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 +603,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 +611,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..5a2421342 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/runner.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/runner.py @@ -4,12 +4,13 @@ document.""" from __future__ import annotations +import json 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 .builder import AtifTurn, Document, Media, TurnContext, timestamp from .profile import AtifError @@ -23,13 +24,71 @@ 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: Mapping[str, Any], native: Sequence[Any], + aux: Sequence[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.""" + records: list[Fed] = [] + fed = 0 + for entry 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:]) + context = TurnContext(**{key: turn.get(key) for key in _CONTEXT_FIELDS}, + inbound=_content_from_json(turn.get("inbound") or ())) + return cls(context=context, records=records, state=turn["state"], + final=_content_from_json(turn["final"]) if turn.get("final") is not None else None, + ended_at=turn.get("ended_at"), data=turn.get("data"), error=turn.get("error")) + + +_CONTEXT_FIELDS = ("index", "context_id", "task_id", "message_id", "agent_name", "agent_version", "agent_model", + "started_at") + + +def served_turn(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) -> dict[str, Any]: + """A task's TurnContext and how it ended, as JSON: what an atif/1 final read serves as ``turn_context``, so an + offline replay has everything but the records. Media in the content are named by path, their bytes stored apart.""" + turn: dict[str, Any] = {} + for key in _CONTEXT_FIELDS: + value = getattr(context, key) + if key == "started_at": + value = timestamp(value) + if value is not None: + turn[key] = value + turn["inbound"] = _content_json(context.inbound) + turn["state"] = state + for key, value in (("final", None if final is None else _content_json(final)), ("ended_at", timestamp(ended_at)), + ("data", None if data is None else [dict(entry) for entry in data]), + ("error", None if error is None else dict(error))): + if value is not None: + turn[key] = value + return json.loads(json.dumps(turn, allow_nan=False)) + + +def _content_json(content: Sequence[Any]) -> list[Any]: + return [{"media": {"path": item.path, "media_type": item.media_type, "info": dict(item.info)}} + if isinstance(item, Media) else item for item in content] + + +def _content_from_json(content: Sequence[Any]) -> list[Any]: + return [Media(item["media"]["path"], item["media"]["media_type"], item["media"]["info"]) + if isinstance(item, Mapping) and set(item) == {"media"} else item for item in content] class AdapterRun: @@ -37,13 +96,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,8 +118,9 @@ 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() @@ -89,16 +150,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 +171,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 +181,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/tests/test_a2a_atif_serving.py b/packages/agentenv-protocol/tests/test_a2a_atif_serving.py new file mode 100644 index 000000000..333d0f227 --- /dev/null +++ b/packages/agentenv-protocol/tests/test_a2a_atif_serving.py @@ -0,0 +1,520 @@ +"""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 + +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, + Uploaded, + a2a_agent, + enable, + extension, + framework, +) +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: + turn.message(step=record["step"], text=record["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), + ] + + +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) + + +async def _turn(request: TaskRequest, hold: _Hold) -> TaskResult: + """The toy agent's turn: its message names a scenario and a tag unique in the context.""" + scenario, tag = request.parts[0].text.split() + log = request.trajectory + records = _work(tag) + if scenario == "work": + for record in records: + log.append(record) + return TaskResult.text(f"{tag}: two files") + if scenario == "hooks": + log.append(records[0]) + log.aux("hooks", {"type": "note", "step": f"{tag}-h", "text": "the pre-tool hook allowed ls"}) + for record in records[1:]: + log.append(record) + log.aux("hooks", {"type": "other", "step": f"{tag}-x", "text": "no handler takes this one"}) + return TaskResult.text(f"{tag}: two files") + if scenario == "late": + for record in records[:3]: + log.append(record) + log.append({"type": "say", "step": f"{tag}-w", "text": f"{tag}: waiting on ls"}) + await hold.wait() + log.append(records[3]) + log.append({"type": "say", "step": f"{tag}-3", "text": f"{tag}: got it"}) + log.append({"type": "say", "step": f"{tag}-4", "text": f"{tag}: two files"}) + await hold.wait() + return TaskResult.text(f"{tag}: two files") + if scenario == "failed": + for record in records: + log.append(record) + return TaskResult.failure("toy.failed", "ls found nothing to fix") + if scenario == "raised": + for record in records[:2]: + log.append(record) + raise RuntimeError("the toy CLI crashed") + if scenario == "canceled": + for record in records[:3]: + log.append(record) + await hold.wait() + return TaskResult.text("never reached") + if scenario == "data": + for record in records: + log.append(record) + 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()) + if scenario == "returned": + return (TaskResult.builder().succeeded().add_text(f"{tag}: two files") + .native_trajectory(format=NATIVE, payload=records).build()) + if scenario == "both": + log.append(records[0]) + return (TaskResult.builder().succeeded().add_text("done") + .native_trajectory(format=NATIVE, payload=records).build()) + if scenario == "broken": + log.append(records[0]) + log.append({"type": "result", "id": "no-such-call", "out": "x"}) + log.append(records[1]) + return TaskResult.text("done anyway") + if scenario == "spawn": + log.append({"type": "call", "step": f"{tag}-1", "id": f"{tag}-task", "name": "Task", "args": {"goal": "ls"}}) + log.append({"type": "spawn", "id": f"{tag}-task", "agent": f"{tag}-sub", "name": "explorer"}) + log.append({"type": "say", "step": f"{tag}-s1", "text": "sub: listing", "agent": f"{tag}-sub"}) + log.append({"type": "say", "step": f"{tag}-s2", "text": "sub: two files", "agent": f"{tag}-sub"}) + log.append({"type": "result", "id": f"{tag}-task", "out": "two files"}) + log.append({"type": "say", "step": f"{tag}-2", "text": f"{tag}: the explorer found two files"}) + return TaskResult.text(f"{tag}: the explorer found two files") + if scenario == "orphan": + log.append({"type": "call", "step": f"{tag}-1", "id": f"{tag}-task", "name": "Task", "args": {"goal": "ls"}}) + log.append({"type": "spawn", "id": f"{tag}-task", "agent": f"{tag}-sub", "name": "explorer"}) + log.append({"type": "say", "step": f"{tag}-s1", "text": "sub: listing", "agent": f"{tag}-sub"}) + await hold.wait() + return TaskResult.text("never reached") + raise AssertionError(f"no scenario {scenario!r}") + + +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 their sub-agents.""" + document = dict(pages[-1]["header"]) + document["steps"] = [step for page in pages for step in page["events"]] + subagents = {sub["trajectory_id"]: sub for page in pages for sub in page["subagents"]} + if subagents: + document["subagent_trajectories"] = list(subagents.values()) + return document + + +def _strip_final_metrics(document: dict[str, Any]) -> dict[str, Any]: + return {key: value for key, value in document.items() if key != "final_metrics"} + + +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" + assert _rebuild([context_cursor]) == _strip_final_metrics(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_the_sub_agents_they_reference() -> 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) == _strip_final_metrics(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) diff --git a/packages/agentenv-protocol/tests/test_atif_builder.py b/packages/agentenv-protocol/tests/test_atif_builder.py index b4a349d30..d35a97506 100644 --- a/packages/agentenv-protocol/tests/test_atif_builder.py +++ b/packages/agentenv-protocol/tests/test_atif_builder.py @@ -21,6 +21,7 @@ native, profile_of, replay, + served_turn, timestamp, ) @@ -570,3 +571,98 @@ 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 = served_turn(context, state="completed", final=["a picture"], ended_at="2026-11-18T10:00:01Z", + data=[{"data": {"n": 1}}]) + 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)}} + recorded = RecordedTask.from_served(turn, records, [{"name": "hooks", "record": {"x": 1}, "after": 1}]) + assert recorded.context.inbound[1] == shot + assert recorded.records == [Fed(records[0]), Fed({"x": 1}, aux="hooks")] + assert (recorded.state, recorded.final, recorded.data) == ("completed", ["a picture"], [{"data": {"n": 1}}]) 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") From 7f7616adb24d23e2ef0db247a537738cdfca8428 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 22:06:25 -0800 Subject: [PATCH 2/7] fix(protocol): an atif/1 cursor page carries its tasks' sub-agents as far as each is served A sub-agent can gain steps after its spawning call's result, so a page carrying only the sub-agents its own steps reference could leave a reader with an early copy forever. A page now carries the sub-agents of every task its steps belong to; the page that serves a task's last step, which closes only as the task ends, carries them whole. Co-Authored-By: Claude Opus 5.5 --- packages/agentenv-protocol/README.md | 5 ++- .../agentenv_protocol/a2a_agent/_atif_copy.py | 44 ++++++++----------- .../agentenv_protocol/a2a_agent/extensions.py | 7 +-- .../src/agentenv_protocol/atif/builder.py | 4 ++ .../src/agentenv_protocol/atif/runner.py | 4 ++ .../tests/test_a2a_atif_serving.py | 40 +++++++++++++++-- 6 files changed, 72 insertions(+), 32 deletions(-) diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index 7740f4202..1f6f2f23d 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1635,7 +1635,10 @@ included: - 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, and `subagents`, the embedded - sub-agent trajectories its steps reference. + 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 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 index b92e336f0..b1c249e1f 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_atif_copy.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_atif_copy.py @@ -50,7 +50,8 @@ class _Task: @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``.""" + """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]] @@ -146,30 +147,40 @@ def context_read(self) -> dict[str, Any] | None: 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.""" + 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() + places = {place: task_id for task_id, place in + ((task_id, task.place) for task_id, task in self._tasks.items())} + sub_tasks = {agent_id: places.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") - scope = [step for step, owner in zip(steps, _owners(steps)) if task_id is None or owner == task_id] - pending = [step for step in scope if step["step_id"] > after] + owners = _owners(steps) + scope = [(step, owner) for step, owner in zip(steps, owners) if task_id is None or owner == task_id] + pending = [(step, owner) for step, owner in scope if step["step_id"] > after] served: list[dict[str, Any]] = [] + tasks: set[str | None] = set() used = 0 - for step in pending[:max_steps]: + 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", "final_metrics")} - return AtifPage(header=header, subagents=_referenced(served, (document or {}).get("subagent_trajectories", [])), - steps=served, next=served[-1]["step_id"] if served else after, - has_more=len(served) < len(pending)) + 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: @@ -255,20 +266,3 @@ def _owners(steps: Sequence[dict[str, Any]]) -> list[str | None]: owner = ((step.get("extra") or {}).get(PROFILE_KEY) or {}).get("task_id", owner) owners.append(owner) return owners - - -def _referenced(steps: Sequence[dict[str, Any]], subagents: Sequence[dict[str, Any]]) -> list[dict[str, Any]]: - """The embedded sub-agent trajectories ``steps`` reference, and those they reference in turn, in document - order.""" - by_id = {sub["trajectory_id"]: sub for sub in subagents} - wanted: set[str] = set() - frontier = list(steps) - while frontier: - step = frontier.pop() - for result in (step.get("observation") or {}).get("results", []): - for ref in result.get("subagent_trajectory_ref") or (): - trajectory_id = ref.get("trajectory_id") - if trajectory_id in by_id and trajectory_id not in wanted: - wanted.add(trajectory_id) - frontier.extend(by_id[trajectory_id]["steps"]) - return [sub for sub in subagents if sub["trajectory_id"] in wanted] 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 04f932945..6abb95287 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/extensions.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/extensions.py @@ -264,9 +264,10 @@ class TrajectoryEventsResponse(ExtensionResponse): 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 ``subagents`` the embedded sub-agent trajectories these - steps reference, whole, so the page stands alone; the last page's header with every page's steps and sub-agents - is the document.""" + ``header`` is the document's root without its steps, 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 diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py index 19f50ec11..ed99a3504 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py @@ -470,6 +470,10 @@ def page(self) -> dict[str, Any] | None: still waiting on a result, or None while there are none.""" return self._render(closed_only=True) + 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]: diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/runner.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/runner.py index 5a2421342..6a374eda3 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/runner.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/runner.py @@ -125,6 +125,10 @@ def document(self, *, through: int | None = None) -> dict[str, Any] | None: def page(self) -> dict[str, Any] | None: return self._doc.page() + 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: diff --git a/packages/agentenv-protocol/tests/test_a2a_atif_serving.py b/packages/agentenv-protocol/tests/test_a2a_atif_serving.py index 333d0f227..81f5490b0 100644 --- a/packages/agentenv-protocol/tests/test_a2a_atif_serving.py +++ b/packages/agentenv-protocol/tests/test_a2a_atif_serving.py @@ -153,6 +153,18 @@ async def _turn(request: TaskRequest, hold: _Hold) -> TaskResult: log.append({"type": "result", "id": f"{tag}-task", "out": "two files"}) log.append({"type": "say", "step": f"{tag}-2", "text": f"{tag}: the explorer found two files"}) return TaskResult.text(f"{tag}: the explorer found two files") + if scenario == "grow": + log.append({"type": "call", "step": f"{tag}-1", "id": f"{tag}-task", "name": "Task", "args": {"goal": "ls"}}) + log.append({"type": "spawn", "id": f"{tag}-task", "agent": f"{tag}-sub", "name": "explorer"}) + log.append({"type": "say", "step": f"{tag}-s1", "text": "sub: listing", "agent": f"{tag}-sub"}) + log.append({"type": "say", "step": f"{tag}-s2", "text": "sub: still listing", "agent": f"{tag}-sub"}) + log.append({"type": "result", "id": f"{tag}-task", "out": "listing"}) + log.append({"type": "say", "step": f"{tag}-2", "text": f"{tag}: the explorer is listing"}) + log.append({"type": "say", "step": f"{tag}-3", "text": f"{tag}: waiting"}) + await hold.wait() + log.append({"type": "say", "step": f"{tag}-s3", "text": "sub: two files", "agent": f"{tag}-sub"}) + log.append({"type": "say", "step": f"{tag}-4", "text": f"{tag}: two files"}) + return TaskResult.text(f"{tag}: two files") if scenario == "orphan": log.append({"type": "call", "step": f"{tag}-1", "id": f"{tag}-task", "name": "Task", "args": {"goal": "ls"}}) log.append({"type": "spawn", "id": f"{tag}-task", "agent": f"{tag}-sub", "name": "explorer"}) @@ -226,10 +238,12 @@ def _grant() -> dict[str, Any]: 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 their sub-agents.""" + """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 = {sub["trajectory_id"]: sub for page in pages for sub in page["subagents"]} + 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 @@ -472,7 +486,7 @@ def test_an_adapter_error_stops_the_copy_not_the_turn() -> None: assert error["code"] == "atif_unavailable" and "no-such-call" in error["message"] -def test_cursor_pages_carry_the_header_and_the_sub_agents_they_reference() -> None: +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) @@ -493,6 +507,26 @@ def test_cursor_pages_carry_the_header_and_the_sub_agents_they_reference() -> No assert _rebuild(pages) == _strip_final_metrics(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) == _strip_final_metrics(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: From b41c01cc607c91d1e2bc2c1f3dae4cd1ddeecb7d Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 22:34:41 -0800 Subject: [PATCH 3/7] fix(a2a_agent): a trajectory upload grants only the trajectory, so pinned agents accept it TrajectoryWriteObjects gained optional aux and turn_context grants; dumped with their None values, they reached agents on an older protocol, whose request model forbids unknown fields, and every objects-form trajectory read got HTTP 400. Co-Authored-By: Claude Opus 5.5 --- src/agent_env/a2a_agent/object_transfer.py | 3 ++- tst/unit/a2a_agent/object_transfer_test.py | 25 ++++++++++++++++++++++ 2 files changed, 27 insertions(+), 1 deletion(-) 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/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( From ad1d6bd739c3bad20afe63048576957fa3b2da16 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 23:48:50 -0800 Subject: [PATCH 4/7] fix(protocol): an atif/1 copy keeps replay's inputs as fed, and a cursor header keeps final_metrics An aux handler that changed the record it was handed changed the served aux log, so replay could build another document: the log keeps its own copy, and a task's inbound content is a tuple. A cost reported for a whole task is on no step, so a cursor page's header now keeps final_metrics once no task is open, and pages rebuild the document whole. Co-Authored-By: Claude Opus 5.5 --- packages/agentenv-protocol/README.md | 3 ++- .../agentenv_protocol/a2a_agent/_atif_copy.py | 8 ++++---- .../agentenv_protocol/a2a_agent/extensions.py | 3 ++- .../tests/test_a2a_atif_serving.py | 16 ++++++++-------- 4 files changed, 16 insertions(+), 14 deletions(-) diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index 1f6f2f23d..893db130d 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1634,7 +1634,8 @@ included: 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, and `subagents`, the embedded + 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 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 index b1c249e1f..7887fd776 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_atif_copy.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_atif_copy.py @@ -78,7 +78,7 @@ def start(self, task_id: str, index: int, turn: TurnStart) -> None: try: context = TurnContext( index=index, context_id=self._context_id, task_id=task_id, message_id=turn.message_id, - inbound=_content(turn.parts, self._run)[0], agent_name=turn.agent_name, + inbound=tuple(_content(turn.parts, self._run)[0]), agent_name=turn.agent_name, agent_version=turn.agent_version, agent_model=turn.agent_model, started_at=_now()) self._run.start_task(context) except Exception as exc: @@ -97,7 +97,8 @@ def aux(self, task_id: str, name: str, record: Any) -> None: task = self._open(task_id) if task is None: return - task.aux.append({"name": name, "record": record, "after": task.natives}) + # A copy: an adapter may change the record it's handed, and the log is replay's input. + task.aux.append({"name": name, "record": json.loads(json.dumps(record)), "after": task.natives}) try: self._run.aux(name, record) except Exception as exc: @@ -175,8 +176,7 @@ def page(self, after: int, max_steps: int, max_bytes: int, *, task_id: str | Non 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", "final_metrics")} + 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, 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 6abb95287..50deffab4 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/extensions.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/extensions.py @@ -264,7 +264,8 @@ class TrajectoryEventsResponse(ExtensionResponse): 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 ``subagents`` the embedded sub-agent trajectories of the + ``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.""" diff --git a/packages/agentenv-protocol/tests/test_a2a_atif_serving.py b/packages/agentenv-protocol/tests/test_a2a_atif_serving.py index 81f5490b0..da5c007f4 100644 --- a/packages/agentenv-protocol/tests/test_a2a_atif_serving.py +++ b/packages/agentenv-protocol/tests/test_a2a_atif_serving.py @@ -50,7 +50,8 @@ class Hooks(Toy): @aux("hooks", type="note") def note(self, record: dict, turn: Any) -> None: - turn.message(step=record["step"], text=record["text"]) + # 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]: @@ -65,6 +66,7 @@ def _work(tag: str) -> list[dict[str, Any]]: {"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}, ] @@ -249,10 +251,6 @@ def _rebuild(pages: list[dict[str, Any]]) -> dict[str, Any]: return document -def _strip_final_metrics(document: dict[str, Any]) -> dict[str, Any]: - return {key: value for key, value in document.items() if key != "final_metrics"} - - 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] @@ -308,7 +306,9 @@ async def capture(_target: Any, body: bytes) -> Uploaded: 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" - assert _rebuild([context_cursor]) == _strip_final_metrics(document) + # 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] @@ -504,7 +504,7 @@ def test_cursor_pages_carry_the_header_and_their_tasks_sub_agents() -> None: 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) == _strip_final_metrics(document) + assert _rebuild(pages) == document def test_a_reader_following_the_cursor_gets_the_steps_a_sub_agent_writes_after_its_result() -> None: @@ -524,7 +524,7 @@ def test_a_reader_following_the_cursor_gets_the_steps_a_sub_agent_writes_after_i # 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) == _strip_final_metrics(document) + assert _rebuild(pages) == document def test_a_spawn_its_task_ended_without_answering_keeps_its_sub_agent_referenced() -> None: From a360ce77eda3308a22a1db27cf17a3a006021c46 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Thu, 19 Nov 2026 00:28:01 -0800 Subject: [PATCH 5/7] refactor(protocol): typed served turns, one task mapping and one guard in the atif/1 copy - ServedTurn and AuxEntry (atif/served.py) are the shapes an atif/1 final read serves as turn_context and aux; RecordedTask.from_served validates them. - The copy maps steps and sub-agents to tasks through the builder (step_tasks, subagent_tasks), not by reading rendered profiles back. - One _guarded() context manager stops the copy on an adapter error. - _inbound and _final replace one function with an answer flag. - TrajectoryLog takes the adapter's spec; the appended-and-returned refusal no longer rides on aux bookkeeping. - The atif read path splits into _atif_events and _atif_document, and TaskTrajectories names its results (AtifTaskRead, AtifCursor). - The serving tests' toy agent plays named scenarios from a table. Co-Authored-By: Claude Opus 5.5 --- packages/agentenv-protocol/README.md | 7 +- .../agentenv_protocol/a2a_agent/_atif_copy.py | 124 +++++----- .../a2a_agent/_trajectory_log.py | 47 ++-- .../agentenv_protocol/a2a_agent/framework.py | 108 ++++----- .../agentenv_protocol/a2a_agent/tasks/v1.py | 17 +- .../src/agentenv_protocol/atif/__init__.py | 16 +- .../src/agentenv_protocol/atif/builder.py | 4 + .../src/agentenv_protocol/atif/runner.py | 67 ++---- .../src/agentenv_protocol/atif/served.py | 117 +++++++++ .../tests/test_a2a_atif_serving.py | 227 +++++++++++------- .../tests/test_atif_builder.py | 24 +- 11 files changed, 466 insertions(+), 292 deletions(-) create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/served.py diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index 893db130d..78033524e 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1626,9 +1626,10 @@ 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. 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 + 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. 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 index 7887fd776..99a8fdff7 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_atif_copy.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_atif_copy.py @@ -10,12 +10,13 @@ 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, Sequence +from typing import Any, Iterable, Iterator, Sequence from urllib.parse import urlsplit, urlunsplit -from ..atif import FORMAT, PROFILE_KEY, Adapter, AdapterRun, Media, TurnContext, served_turn +from ..atif import FORMAT, Adapter, AdapterRun, AuxEntry, Media, ServedTurn, TurnContext from ..errors import AgentEnvError from .tasks.v1 import DataPart, FilePart, TaskError, TextPart, _thaw @@ -43,8 +44,8 @@ class _Task: place: int context: TurnContext natives: int = 0 - aux: list[dict[str, Any]] = field(default_factory=list) - turn: dict[str, Any] | None = None + aux: list[AuxEntry] = field(default_factory=list) + turn: ServedTurn | None = None ended: bool = False @@ -75,22 +76,20 @@ def start(self, task_id: str, index: int, turn: TurnStart) -> None: with self._lock: if self._failed is not None: return - try: + with self._guarded(): context = TurnContext( index=index, context_id=self._context_id, task_id=task_id, message_id=turn.message_id, - inbound=tuple(_content(turn.parts, self._run)[0]), agent_name=turn.agent_name, + inbound=tuple(_inbound(turn.parts, self._run)), agent_name=turn.agent_name, agent_version=turn.agent_version, agent_model=turn.agent_model, started_at=_now()) self._run.start_task(context) - except Exception as exc: - self._fail(exc) - return - self._tasks[task_id] = _Task(place=len(self._tasks), context=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: - self._feed(task, record) + with self._guarded(): + self._feed(task, record) def aux(self, task_id: str, name: str, record: Any) -> None: with self._lock: @@ -98,11 +97,9 @@ def aux(self, task_id: str, name: str, record: Any) -> None: 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({"name": name, "record": json.loads(json.dumps(record)), "after": task.natives}) - try: + task.aux.append(AuxEntry(name=name, record=json.loads(json.dumps(record)), after=task.natives)) + with self._guarded(): self._run.aux(name, record) - except Exception as exc: - self._fail(exc) def end(self, task_id: str, *, state: str, final: Sequence[Any] = (), error: TaskError | None = None, native: Any = None) -> None: @@ -111,25 +108,20 @@ def end(self, task_id: str, *, state: str, final: Sequence[Any] = (), error: Tas task = self._open(task_id) if task is None: return - try: + with self._guarded(): for record in (native if isinstance(native, list) else [native]) if native is not None else (): self._feed(task, record) - if self._failed is not None: - return - content, data = _content(final, self._run, answer=True) - failure = None if error is None else {"kind": error.error_type, "message": error.message, - "code": error.code} - ended = _now() - ending = {"state": state, "final": content or None, "ended_at": ended, "data": data or None, - "error": failure} + content, data = _final(final, self._run) + ending = { + "state": state, "final": content or None, "ended_at": _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 = served_turn(task.context, **ending) - except Exception as exc: - self._fail(exc) - finally: - task.ended = True + task.turn = ServedTurn.of(task.context, **ending) + task.ended = True - def task_read(self, task_id: str) -> tuple[dict[str, Any], list[dict[str, Any]], dict[str, Any]] | None: + 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() @@ -138,7 +130,7 @@ def task_read(self, task_id: str) -> tuple[dict[str, Any], list[dict[str, Any]], return None document = self._run.document(through=task.place) assert document is not None - return document, json.loads(json.dumps(task.aux)), dict(task.turn) + 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.""" @@ -154,15 +146,14 @@ def page(self, after: int, max_steps: int, max_bytes: int, *, task_id: str | Non with self._lock: self._check() document = self._run.page() - places = {place: task_id for task_id, place in - ((task_id, task.place) for task_id, task in self._tasks.items())} - sub_tasks = {agent_id: places.get(place) for agent_id, place in self._run.subagent_tasks().items()} + 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") - owners = _owners(steps) - scope = [(step, owner) for step, owner in zip(steps, owners) if task_id is None or owner == task_id] - pending = [(step, owner) for step, owner in scope if step["step_id"] > after] + 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 @@ -189,16 +180,18 @@ def _open(self, task_id: str) -> _Task | None: return task if task is not None and not task.ended else None def _feed(self, task: _Task, record: Any) -> None: - try: - self._run.native(record) - except Exception as exc: - self._fail(exc) + self._run.native(record) task.natives += 1 - def _fail(self, exc: Exception) -> None: - 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) + @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: @@ -214,10 +207,23 @@ def _now() -> datetime: return datetime.now(timezone.utc) -def _content(parts: Iterable[Any], run: AdapterRun, *, answer: bool = False) -> tuple[list[Any], list[dict[str, Any]]]: - """A2A parts 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. In a final response (``answer``), a DataPart other than a structured output is the - harness's diagnostics, so it goes to the data list for the profile instead.""" +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: @@ -225,15 +231,10 @@ def _content(parts: Iterable[Any], run: AdapterRun, *, answer: bool = False) -> content.append(part.text) elif isinstance(part, DataPart): value = _thaw(part.data) - if answer and set(value) == {STRUCTURED_OUTPUT}: + if set(value) == {STRUCTURED_OUTPUT}: content.append(_compact(value[STRUCTURED_OUTPUT])) - elif answer: - entry: dict[str, Any] = {"data": value} - if part.metadata: - entry["metadata"] = _thaw(part.metadata) - data.append(entry) else: - content.append(_compact(value)) + data.append({"data": value, **({"metadata": _thaw(part.metadata)} if part.metadata else {})}) elif isinstance(part, FilePart): content.append(_file(part, run)) return content, data @@ -255,14 +256,3 @@ def _file(part: FilePart, run: AdapterRun) -> Media | str: def _compact(value: Any) -> str: return json.dumps(value, separators=(",", ":"), ensure_ascii=False, allow_nan=False) - - -def _owners(steps: Sequence[dict[str, Any]]) -> list[str | None]: - """The task each step belongs to: the one whose user step opened the run of steps it's in.""" - owners: list[str | None] = [] - owner = None - for step in steps: - if step.get("source") == "user": - owner = ((step.get("extra") or {}).get(PROFILE_KEY) or {}).get("task_id", owner) - owners.append(owner) - return owners 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 efbbade0f..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 @@ -8,7 +8,7 @@ from dataclasses import dataclass from typing import Any, Sequence -from ..atif import Adapter +from ..atif import Adapter, AuxEntry, ServedTurn from ._atif_copy import AtifCopy, AtifPage, TurnStart from .extensions import TrajectoryState from .tasks.v1 import TaskError, TrajectoryLog @@ -54,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. @@ -82,8 +101,7 @@ def register(self, task_id: str, context_id: str) -> TrajectoryLog: record = self._tasks.get(task_id) if record is None: log = TrajectoryLog( - native=self._native, - aux=frozenset(self._atif.spec.aux) if self._atif is not None else None, + 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) @@ -234,9 +252,7 @@ def context_page( total=sum(lengths), ) - def atif_task( - self, task_id: str - ) -> tuple[dict[str, Any], list[dict[str, Any]], dict[str, Any]] | None: + 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) @@ -244,7 +260,8 @@ def atif_task( if copy is None: return None self._touch(record.context_id) - return copy.task_read(task_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.""" @@ -256,27 +273,29 @@ def atif_context(self, context_id: str) -> dict[str, Any] | None: def atif_task_page( self, task_id: str, after: int, max_steps: int, max_bytes: int - ) -> tuple[AtifPage, str, TrajectoryState] | None: - """A cursor page of the task's closed atif/1 steps, its context id and the task's state.""" + ) -> 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 - return copy.page(after, max_steps, max_bytes, task_id=task_id), record.context_id, 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 - ) -> tuple[AtifPage, str, TrajectoryState] | None: - """A cursor page of the context's closed atif/1 steps, the current task's id and the - context's state.""" + ) -> 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) - return copy.page(after, max_steps, max_bytes), task_id, state + 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] 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 c025aa09f..032771f91 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py @@ -833,7 +833,9 @@ async def trajectory_get( | ContextEventsTrajectoryRequest, ) -> Any: if request.format == ATIF_FORMAT: - return await self._atif_get(request) + if isinstance(request, (TaskEventsTrajectoryRequest, ContextEventsTrajectoryRequest)): + return self._atif_events(request) + return await self._atif_document(request) if isinstance( request, (TaskEventsTrajectoryRequest, ContextEventsTrajectoryRequest) ): @@ -862,67 +864,64 @@ async def trajectory_get( objects=TrajectoryUploadedObjects(trajectory=uploaded), format=trajectory.format ) - async def _atif_get( + 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 - | TaskEventsTrajectoryRequest | ContextTrajectoryRequest - | ContextObjectTrajectoryRequest - | ContextEventsTrajectoryRequest, + | ContextObjectTrajectoryRequest, ) -> dict[str, Any]: - """An atif/1 read, served from the context's copy: a task read is the document as it - stood when the task ended, with its aux log and turn context; a context read is the live - page; a cursor read pages closed steps by ``step_id``.""" - trajectories = self.task_trajectories - if isinstance(request, (TaskEventsTrajectoryRequest, ContextEventsTrajectoryRequest)): - max_steps = request.limit or MAX_TRAJECTORY_READ_EVENTS - try: - if isinstance(request, TaskEventsTrajectoryRequest): - found = trajectories.atif_task_page( - request.task_id, request.after, max_steps, MAX_TRAJECTORY_READ_BYTES - ) - unknown = f"Unknown task '{request.task_id}'" - else: - found = 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 found is None: - raise HTTPException(status_code=404, detail=unknown) - if isinstance(request, TaskEventsTrajectoryRequest): - page, context_id, state = found - task_id = request.task_id - else: - page, task_id, state = found - context_id = request.context_id - return AtifEventsResponse( - context_id=context_id, - task_id=task_id, - state=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) - aux: list[dict[str, Any]] | None = None - turn: dict[str, Any] | None = None + """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)): - found_task = trajectories.atif_task(request.task_id) - if found_task is None: + 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, aux, turn = found_task + 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 = trajectories.atif_context(request.context_id) + document = self.task_trajectories.atif_context(request.context_id) if document is None: raise HTTPException( status_code=404, @@ -930,16 +929,15 @@ async def _atif_get( ) versions = _atif_versions(document) if isinstance(request, (TaskTrajectoryRequest, ContextTrajectoryRequest)): - answer: dict[str, Any] = {"trajectory": document, "format": ATIF_FORMAT, **versions} - if turn is not None: - answer.update(aux=aux, turn_context=turn) - return answer + 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(aux)), + 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(turn)) + 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) 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 9027f907a..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 @@ -157,14 +159,13 @@ class TrajectoryLog: 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. With an ATIF adapter - (``aux`` names the aux files it declares), every event and aux record also feeds the - context's atif/1 copy.""" + (``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", "_aux_names", "_atif", + "_events", "_size_bytes", "_format", "_native", "_sealed", "_task_id", "_warned", "_adapter", "_atif", ) - def __init__(self, *, native: str | None = None, aux: frozenset[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 @@ -172,7 +173,7 @@ def __init__(self, *, native: str | None = None, aux: frozenset[str] | None = No self._sealed = False self._task_id: str | None = None self._warned = False - self._aux_names = aux + self._adapter = adapter self._atif: Any = None @property @@ -215,9 +216,9 @@ 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._aux_names is None: + if self._adapter is None: raise RuntimeError("aux records feed an ATIF adapter: enable(TRAJECTORY_V1, native=..., atif=...)") - if name not in self._aux_names: + 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) @@ -232,7 +233,7 @@ def _hold_returned(self, format: str) -> None: 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._aux_names is not None and self._events: + 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, " diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/__init__.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/__init__.py index 4414d33eb..b66f06e58 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/__init__.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/__init__.py @@ -47,17 +47,19 @@ ) 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, served_turn +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", "served_turn", "Step", "StepData", "StepError", "StepProfile", + "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 ed99a3504..cd7748390 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py @@ -470,6 +470,10 @@ def page(self) -> dict[str, Any] | None: 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()} diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/runner.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/runner.py index 6a374eda3..99f0cdc86 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/runner.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/runner.py @@ -4,14 +4,14 @@ document.""" from __future__ import annotations -import json from dataclasses import dataclass from datetime import datetime from typing import Any, Callable, Iterable, Mapping, Sequence from .adapter import Adapter, AdapterSpec -from .builder import AtifTurn, Document, Media, TurnContext, timestamp +from .builder import AtifTurn, Document, Media, TurnContext from .profile import AtifError +from .served import AuxEntry, ServedTurn @dataclass(frozen=True) @@ -36,59 +36,24 @@ class RecordedTask: error: Mapping[str, Any] | None = None @classmethod - def from_served(cls, turn: Mapping[str, Any], native: Sequence[Any], - aux: Sequence[Mapping[str, Any]] = ()) -> RecordedTask: + 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.""" + 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 aux: - while fed < entry["after"]: + 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.append(Fed(entry.record, aux=entry.name)) records.extend(Fed(record) for record in native[fed:]) - context = TurnContext(**{key: turn.get(key) for key in _CONTEXT_FIELDS}, - inbound=_content_from_json(turn.get("inbound") or ())) - return cls(context=context, records=records, state=turn["state"], - final=_content_from_json(turn["final"]) if turn.get("final") is not None else None, - ended_at=turn.get("ended_at"), data=turn.get("data"), error=turn.get("error")) - - -_CONTEXT_FIELDS = ("index", "context_id", "task_id", "message_id", "agent_name", "agent_version", "agent_model", - "started_at") - - -def served_turn(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) -> dict[str, Any]: - """A task's TurnContext and how it ended, as JSON: what an atif/1 final read serves as ``turn_context``, so an - offline replay has everything but the records. Media in the content are named by path, their bytes stored apart.""" - turn: dict[str, Any] = {} - for key in _CONTEXT_FIELDS: - value = getattr(context, key) - if key == "started_at": - value = timestamp(value) - if value is not None: - turn[key] = value - turn["inbound"] = _content_json(context.inbound) - turn["state"] = state - for key, value in (("final", None if final is None else _content_json(final)), ("ended_at", timestamp(ended_at)), - ("data", None if data is None else [dict(entry) for entry in data]), - ("error", None if error is None else dict(error))): - if value is not None: - turn[key] = value - return json.loads(json.dumps(turn, allow_nan=False)) - - -def _content_json(content: Sequence[Any]) -> list[Any]: - return [{"media": {"path": item.path, "media_type": item.media_type, "info": dict(item.info)}} - if isinstance(item, Media) else item for item in content] - - -def _content_from_json(content: Sequence[Any]) -> list[Any]: - return [Media(item["media"]["path"], item["media"]["media_type"], item["media"]["info"]) - if isinstance(item, Mapping) and set(item) == {"media"} else item for item in content] + 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: @@ -125,6 +90,10 @@ def document(self, *, through: int | None = None) -> dict[str, Any] | None: 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() 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..4e6ce19aa --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/served.py @@ -0,0 +1,117 @@ +"""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: fields that aren't set are left out.""" + return self.model_dump(mode="json", exclude_none=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) + + def wire(self) -> dict[str, Any]: + """As JSON on the wire, the record whole, even when it is null.""" + return self.model_dump(mode="json") + + +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/tests/test_a2a_atif_serving.py b/packages/agentenv-protocol/tests/test_a2a_atif_serving.py index da5c007f4..0b397787c 100644 --- a/packages/agentenv-protocol/tests/test_a2a_atif_serving.py +++ b/packages/agentenv-protocol/tests/test_a2a_atif_serving.py @@ -8,7 +8,7 @@ import threading import time from datetime import datetime, timedelta, timezone -from typing import Any +from typing import Any, Awaitable, Callable import pytest from atif_cases import Toy @@ -21,6 +21,7 @@ ContextTrajectoryRequest, TaskRequest, TaskResult, + TrajectoryLog, Uploaded, a2a_agent, enable, @@ -90,90 +91,150 @@ def reached(self, count: int = 1) -> None: 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: - """The toy agent's turn: its message names a scenario and a tag unique in the context.""" scenario, tag = request.parts[0].text.split() - log = request.trajectory - records = _work(tag) - if scenario == "work": - for record in records: - log.append(record) - return TaskResult.text(f"{tag}: two files") - if scenario == "hooks": - log.append(records[0]) - log.aux("hooks", {"type": "note", "step": f"{tag}-h", "text": "the pre-tool hook allowed ls"}) - for record in records[1:]: - log.append(record) - log.aux("hooks", {"type": "other", "step": f"{tag}-x", "text": "no handler takes this one"}) - return TaskResult.text(f"{tag}: two files") - if scenario == "late": - for record in records[:3]: - log.append(record) - log.append({"type": "say", "step": f"{tag}-w", "text": f"{tag}: waiting on ls"}) - await hold.wait() - log.append(records[3]) - log.append({"type": "say", "step": f"{tag}-3", "text": f"{tag}: got it"}) - log.append({"type": "say", "step": f"{tag}-4", "text": f"{tag}: two files"}) - await hold.wait() - return TaskResult.text(f"{tag}: two files") - if scenario == "failed": - for record in records: - log.append(record) - return TaskResult.failure("toy.failed", "ls found nothing to fix") - if scenario == "raised": - for record in records[:2]: - log.append(record) - raise RuntimeError("the toy CLI crashed") - if scenario == "canceled": - for record in records[:3]: - log.append(record) - await hold.wait() - return TaskResult.text("never reached") - if scenario == "data": - for record in records: - log.append(record) - 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()) - if scenario == "returned": - return (TaskResult.builder().succeeded().add_text(f"{tag}: two files") - .native_trajectory(format=NATIVE, payload=records).build()) - if scenario == "both": - log.append(records[0]) - return (TaskResult.builder().succeeded().add_text("done") - .native_trajectory(format=NATIVE, payload=records).build()) - if scenario == "broken": - log.append(records[0]) - log.append({"type": "result", "id": "no-such-call", "out": "x"}) - log.append(records[1]) - return TaskResult.text("done anyway") - if scenario == "spawn": - log.append({"type": "call", "step": f"{tag}-1", "id": f"{tag}-task", "name": "Task", "args": {"goal": "ls"}}) - log.append({"type": "spawn", "id": f"{tag}-task", "agent": f"{tag}-sub", "name": "explorer"}) - log.append({"type": "say", "step": f"{tag}-s1", "text": "sub: listing", "agent": f"{tag}-sub"}) - log.append({"type": "say", "step": f"{tag}-s2", "text": "sub: two files", "agent": f"{tag}-sub"}) - log.append({"type": "result", "id": f"{tag}-task", "out": "two files"}) - log.append({"type": "say", "step": f"{tag}-2", "text": f"{tag}: the explorer found two files"}) - return TaskResult.text(f"{tag}: the explorer found two files") - if scenario == "grow": - log.append({"type": "call", "step": f"{tag}-1", "id": f"{tag}-task", "name": "Task", "args": {"goal": "ls"}}) - log.append({"type": "spawn", "id": f"{tag}-task", "agent": f"{tag}-sub", "name": "explorer"}) - log.append({"type": "say", "step": f"{tag}-s1", "text": "sub: listing", "agent": f"{tag}-sub"}) - log.append({"type": "say", "step": f"{tag}-s2", "text": "sub: still listing", "agent": f"{tag}-sub"}) - log.append({"type": "result", "id": f"{tag}-task", "out": "listing"}) - log.append({"type": "say", "step": f"{tag}-2", "text": f"{tag}: the explorer is listing"}) - log.append({"type": "say", "step": f"{tag}-3", "text": f"{tag}: waiting"}) - await hold.wait() - log.append({"type": "say", "step": f"{tag}-s3", "text": "sub: two files", "agent": f"{tag}-sub"}) - log.append({"type": "say", "step": f"{tag}-4", "text": f"{tag}: two files"}) - return TaskResult.text(f"{tag}: two files") - if scenario == "orphan": - log.append({"type": "call", "step": f"{tag}-1", "id": f"{tag}-task", "name": "Task", "args": {"goal": "ls"}}) - log.append({"type": "spawn", "id": f"{tag}-task", "agent": f"{tag}-sub", "name": "explorer"}) - log.append({"type": "say", "step": f"{tag}-s1", "text": "sub: listing", "agent": f"{tag}-sub"}) - await hold.wait() - return TaskResult.text("never reached") - raise AssertionError(f"no scenario {scenario!r}") + 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: diff --git a/packages/agentenv-protocol/tests/test_atif_builder.py b/packages/agentenv-protocol/tests/test_atif_builder.py index d35a97506..5c7a2f878 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,8 +21,8 @@ is_prefix, native, profile_of, + ServedTurn, replay, - served_turn, timestamp, ) @@ -658,11 +659,22 @@ def test_a_served_turn_gives_the_recorded_task_back(): 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 = served_turn(context, state="completed", final=["a picture"], ended_at="2026-11-18T10:00:01Z", - data=[{"data": {"n": 1}}]) + 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)}} - recorded = RecordedTask.from_served(turn, records, [{"name": "hooks", "record": {"x": 1}, "after": 1}]) - assert recorded.context.inbound[1] == shot - assert recorded.records == [Fed(records[0]), Fed({"x": 1}, aux="hooks")] + 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}}]) + + +@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) From 30a01a496d9e0892dea3fe8e29170767b7dc985c Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Thu, 19 Nov 2026 00:47:00 -0800 Subject: [PATCH 6/7] fix(protocol): a served turn keeps a null its model requires wire() left out every None, so a diagnostic DataPart whose data is null lost its required field and replay refused the turn. It now leaves out only optional fields at their default. Co-Authored-By: Claude Opus 5.5 --- .../src/agentenv_protocol/atif/served.py | 9 +++------ packages/agentenv-protocol/tests/test_atif_builder.py | 10 ++++++++++ 2 files changed, 13 insertions(+), 6 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/served.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/served.py index 4e6ce19aa..fc841d55c 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/served.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/served.py @@ -16,8 +16,9 @@ class _Served(BaseModel): model_config = ConfigDict(extra="forbid", frozen=True) def wire(self) -> dict[str, Any]: - """As JSON on the wire: fields that aren't set are left out.""" - return self.model_dump(mode="json", exclude_none=True) + """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): @@ -61,10 +62,6 @@ class AuxEntry(_Served): record: Any after: int = Field(ge=0) - def wire(self) -> dict[str, Any]: - """As JSON on the wire, the record whole, even when it is null.""" - return self.model_dump(mode="json") - class ServedTurn(_Served): """A task's TurnContext and how it ended: its state, final response, diagnostic DataParts and error.""" diff --git a/packages/agentenv-protocol/tests/test_atif_builder.py b/packages/agentenv-protocol/tests/test_atif_builder.py index 5c7a2f878..cfac7e885 100644 --- a/packages/agentenv-protocol/tests/test_atif_builder.py +++ b/packages/agentenv-protocol/tests/test_atif_builder.py @@ -670,6 +670,16 @@ def test_a_served_turn_gives_the_recorded_task_back(): 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}, []), From 2e82fe61095d61dd4d79f1e0227d1569575a6505 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Thu, 19 Nov 2026 08:28:20 -0800 Subject: [PATCH 7/7] fix(protocol): an atif/1 copy keeps one clock, and back-to-back turns are tested An agent that follows the env's clock runs its programs on the universe's time, while its A2A server stays on real time, so the SDK's own steps (each task's user step and final response) were stamped on another clock than the adapter's. They now take the time the agent's programs read: session_time() in the protocol's computer clock reads the follower's clock file, and a test pins it against clockpage.py's writer. Two messages sent at once in one context are now tested: the first is closed in the copy before the context's lock lets the second start, which an await added before the seal would break. Co-Authored-By: Claude Opus 5.5 --- packages/agentenv-protocol/README.md | 3 +- .../agentenv_protocol/a2a_agent/_atif_copy.py | 15 ++++++++-- .../src/agentenv_protocol/atif/PROFILE.md | 4 ++- .../src/agentenv_protocol/computer/clock.py | 18 +++++++++++ .../tests/test_a2a_agent_clock.py | 16 ++++++++++ .../tests/test_a2a_atif_serving.py | 30 +++++++++++++++++++ .../env/envs/test_computer_clock_follower.py | 15 ++++++++++ 7 files changed, 96 insertions(+), 5 deletions(-) diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index 78033524e..d359234ed 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1620,7 +1620,8 @@ 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. `session_id` is the A2A context id, and `trajectory_id` names the document. +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: 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 index 99a8fdff7..47f3e4749 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_atif_copy.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_atif_copy.py @@ -17,7 +17,9 @@ 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__) @@ -71,6 +73,9 @@ def __init__(self, adapter: type[Adapter], context_id: str) -> None: 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: @@ -80,7 +85,7 @@ def start(self, task_id: str, index: int, turn: TurnStart) -> None: 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=_now()) + 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) @@ -113,7 +118,7 @@ def end(self, task_id: str, *, state: str, final: Sequence[Any] = (), error: Tas self._feed(task, record) content, data = _final(final, self._run) ending = { - "state": state, "final": content or None, "ended_at": _now(), "data": data or None, + "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}, } @@ -203,10 +208,14 @@ def _check(self) -> None: ) -def _now() -> datetime: +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.""" diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md b/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md index 094002d93..41fff3053 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md @@ -61,7 +61,9 @@ to native exactly. - `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 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 index 0b397787c..2f7ba9715 100644 --- a/packages/agentenv-protocol/tests/test_a2a_atif_serving.py +++ b/packages/agentenv-protocol/tests/test_a2a_atif_serving.py @@ -28,6 +28,8 @@ 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, @@ -613,3 +615,31 @@ def test_an_unknown_or_unfinished_read_is_not_found() -> None: 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/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: