diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index cd70d4e0f..ddc40d1c2 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1917,3 +1917,81 @@ process ends, in a directory of the process's own (or under server process owns a staging directory. An agent that doesn't use the SDK can serve the same routes and add `{uri: "urn:agentenv:staging/v1", params: {endpoint: "/ext/staging"}}` to its card. + +## Agent trajectories: yatf/1 + +`agentenv_protocol.yatf` is yatf/1, the trajectory format an agent serves beside +its native log: an append-only stream of JSON events, one turn per A2A task, +that each agent builds from its own native records with an adapter. The spec is +[`yatf/SPEC.md`](src/agentenv_protocol/yatf/SPEC.md). `yatf-1.schema.json` beside it +is the strict JSON schema of one event, and `examples/` holds the spec's worked +examples. The package needs only the protocol's base dependencies. + +Reading a stream: + +```python +from agentenv_protocol import yatf + +events = yatf.parse_events(text) # a JSON array, as on the wire, or JSONL, as stored +for step in yatf.fold_steps(events): # ATIF-style steps, each call's results regrouped into it + print(step.key, step.step.metrics if step.step else None) +for pair in yatf.pair_tool_calls(events): + print(pair.call.function_name, [result.status for result in pair.results]) +``` + +A reader keeps fields, event types and part types it doesn't know, so +`yatf.dump_events(events)` writes a newer 1.x stream back out unchanged. The +order is `(turn, seq)` (`yatf.ordered`), never timestamps. + +Writing an adapter: declare an `Adapter` subclass with `@yatf_adapter`, handle +native records with `@native` methods and aux records with `@aux` methods, and +write events through the `turn` each handler gets: + +```python +from agentenv_protocol.yatf import Adapter, aux, finish, native, yatf_adapter + + +@yatf_adapter(native_format="my-cli-events/1", version="0.1.0", + usage_input_includes_cache=False, tested_with=("2.1.0",)) +class MyCliYatf(Adapter): + def __init__(self, turn): + self.times = {} + + @aux("session", type="assistant") + def session_record(self, record, turn): + self.times[record["id"]] = record["timestamp"] + + @native(type="assistant", where={"block.type": "text"}) + def text(self, record, turn): + turn.message(role="assistant", step=record["id"], text=record["block"]["text"], + time=self.times.get(record["id"])) + + @native(type="assistant", where={"block.type": "tool_use"}) + def tool_use(self, record, turn): + block = record["block"] + turn.tool_call(tool_call_id=block["id"], function_name=block["name"], + arguments=block["input"], step=record["id"]) + + @finish + def close(self, turn): + self.times = {} +``` + +- One instance serves an A2A context across its turns. Per-turn state resets in + the `@finish` method. +- A handler reads only the record it's given and the turn's context. Aux + records are fed in by the agent's own code, and the run stores them in the + order fed, so replaying a stored turn makes the events served live. +- The turn stamps `seq`, `id`, `turn`, `observer`, the actor and + `derived_from`. To emit an event later than its record arrived, keep + `turn.source` and pass it as `derived_from`. +- Of the handlers that match a record, the one with the most conditions takes + it. A native record no handler takes is kept as a `/raw` event. + An aux record no handler takes is dropped. +- `from_yatf` converts back. It returns `Native(log, session)`: each turn's + native log, for the round trip, and the files the CLI resumes from, or None. + +`yatf.AdapterRun` feeds one context's records through an adapter a turn at a +time. It writes each turn's frame (`turn.start`, the inbound message, +`final_response`, `turn.end`) and returns the events each call emits. +`yatf.replay` runs stored turns through it again. diff --git a/packages/agentenv-protocol/pyproject.toml b/packages/agentenv-protocol/pyproject.toml index 915a03f04..1ae8a31fd 100644 --- a/packages/agentenv-protocol/pyproject.toml +++ b/packages/agentenv-protocol/pyproject.toml @@ -80,6 +80,7 @@ dev = [ "websockets>=13", # the computer extra's /svc// relay "brotli>=1.2", # the app extra's network.har decoding "zstandard>=0.23", + "jsonschema>=4.20", # the yatf tests check events against the strict schema ] [project.urls] Homepage = "https://www.agentenvframework.com" diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/SPEC.md b/packages/agentenv-protocol/src/agentenv_protocol/yatf/SPEC.md new file mode 100644 index 000000000..2084c4847 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/SPEC.md @@ -0,0 +1,208 @@ +# yatf/1: the agent trajectory format + +Spec 1.0. A yatf/1 stream is an append-only sequence of small JSON events that records what one agent did in one A2A +context. Each agent builds it from its own native log with an adapter, and serves it beside that log through +`urn:agentenv:trajectory/v1`. The native log stays the agent's default, so a reader that names no format sees no +change. + +Three terms are used throughout: + +- The **native log** is the record the agent's native format id names (`claude-code-stream-json/1`, + `pydantic-ai-messages/v1`). The agent serves it today, and judges read it. +- An **aux file** is a second record the harness writes, such as Claude Code's session JSONL or Codex's rollout. The + adapter reads it to fill gaps in the native log. It is stored beside the native copy, is never served as a format, + and is never read by judges. +- The **YATF copy** is the output: the stream this spec describes. + +The machine-readable form of this spec is the strict JSON schema `yatf-1.schema.json`, which validates one event. The +worked examples in `examples/` are its canonical fixtures. + +## Streams + +- A stream belongs to one agent and one A2A context. It holds one **turn** per A2A task, numbered from 0 within the + context, and each turn holds its events. +- Events are final once appended. A live reader sees the same events as the final read, in the same order. +- The order is (`turn`, `seq`), never timestamps. `seq` is dense from 0 within each turn. +- On the wire a stream is a JSON array. In storage it is JSONL, one event per line. JSON is read strictly: UTF-8, + with no NaN or Infinity. +- The names of an event's fields, and of the fields of the objects this spec defines (parts, sources, metrics and + the like), known to this version or not, are valid Unicode, with no lone surrogate, as I-JSON (RFC 7493) requires. + Free JSON, such as a tool call's `arguments`, `x` or a raw native record, may use any key, and any string value may + hold a lone surrogate, as a native log that cut an emoji in half can. +- Values are taken as written, never coerced, so whatever a reader parses it writes back exactly. An integer is a + JSON integer, with no fraction or exponent: JSON Schema's `integer` also matches `5.0`, but a reader refuses it. +- The agent SDK writes each turn's **frame**: `turn.start`, the inbound `message`, `final_response` and `turn.end`. + It also stamps every event's `seq`, `id`, `turn` and `observer`. The adapter writes everything between, from the + native records, one event per native block in native order. + +## Event envelope + +Every event is one JSON object: these fields, plus the body of its type. + +| Field | Required | Meaning | +| --- | --- | --- | +| `seq` | yes | Position from 0 in its turn | +| `id` | yes | `.`, stable | +| `type` | yes | A core type, or an extension type `/` | +| `turn` | yes | Index of the A2A task within its context | +| `actor` | yes | The declared actor the event belongs to | +| `observer` | yes | Who recorded it: `agent`, `gateway`, `browser` or `framework`; `agent` in an agent's stream | +| `time` | yes | A Time object; an unknown time is an explicit null, never omitted | +| `step` | content events | Step key: groups the events of one inference, dispatch or inbound message | +| `attempt` | no | Harness retry within the task; absent means 1 | +| `is_copied_context` | no | ATIF's flag, kept by name: replayed context that SFT may exclude | +| `derived_from` | recommended | The record the event came from: `{"index": n}` in the turn's native log, or `{"aux": name, "index": n}` in an aux log | +| `x` | no | Extension data keyed by namespace, kept untouched | + +## Time + +- `at`: when it happened per the native record, RFC 3339 with a zone, or null. It is never an empty string, never 0 + and never an estimate. The time a record arrived is not a native time. +- `start` and `end`: only when the native gives both ends. `duration_ms`: only when the native reports one. +- `raw`: the native time string, verbatim, whenever it differs from `at`. +- `virtual`: the env clock's time, one `{env_id, env_step_id, at}` per armed env, never derived from wall time. + +## Event types + +Spec 1.0 defines these types. The names `delegation`, `context`, `producer`, `activation` and `usage.checkpoint` are +reserved: a later 1.x defines each one with its first producer, and no 1.0 producer writes them. + +| Type | Written by | Body | +| --- | --- | --- | +| `turn.start` | SDK | `spec_version`, `context_id`, `task_id`, `message_id`, `native_format`, `live`, `adapter` (`name`, `version`, `lossy`), `usage_input_includes_cache`, `actors` | +| `message` | SDK (inbound), adapter | `role` (`user`, `assistant`, `system`, `developer`), `content` (parts) | +| `final_response` | SDK | `content`: the A2A result's parts | +| `turn.end` | SDK | `state` (`completed`, `failed`, `canceled`), `tool_call_count`, `final_metrics` | +| `step` | adapter | `source` (`agent`, `user`, `system`), `llm_call_count` (0 dispatch, 1 call, more aggregated), `model_name`, `reasoning_effort`, `metrics`, `stop_reason`, `provider_ids`, `first_token_at`, `sampling` | +| `reasoning` | adapter | `visibility` (`raw`, `summary`, `omitted`, `redacted`), `text` (null when omitted), `opaque`: provider payloads kept byte for byte (`kind` `signature`, `encrypted` or `redacted_data`, `provider`, `value`) | +| `tool_call` | adapter | `tool_call_id`, `function_name`, `arguments` (any JSON value), `arguments_raw` (the native string when it was one), `kind` (`builtin`, `mcp`, `function`, `custom`), `server`, `executor` (`agent`, `env`, `provider`, `client`), `env_id` | +| `tool_result` | adapter | `source_call_id`, `status` (`ok`, `error`, `canceled`, `timeout`), `content` (parts), `exit_code` | +| `tools` | adapter | `mode` (`replace`, `add`, `remove`), `tools`: `name`, `kind`, `server`, `description`, `input_schema` | +| `actor` | adapter | `declared`: an actor that appears mid-turn, such as a sub-agent | +| `error` | adapter | `error_type` (`agent_error`, `infra_error`), `message`, `code`, `fatal` | +| `attempt` | adapter | `number`, `reason`: a harness retry; this event and every later one carry `attempt` = `number` | +| `note` | adapter | `text` | + +- Content events (messages, reasoning, tool calls and an inference's errors) carry the key of the step they belong + to, and the inbound message's key is `in-`. `tools`, `tool_result` and the frame's other events carry none. +- A `step` event closes the step whose key it carries. Its content events (messages, reasoning, tool calls) share the + key and may come before or after it. +- A result is a separate event that answers any earlier call in the context, by `source_call_id`, and stays where + it arrived. Folding into ATIF steps regroups results into their call's step. +- Strings named as vocabularies above may gain values in a minor version. A reader keeps a value it doesn't know. + +## Parts + +Content is a list of parts. + +| Part `type` | Fields | +| --- | --- | +| `text` | `text` (inline up to 16 KiB), `origin`, `elision` | +| `ref` | `preview` (at most 2 KiB) and `source`: text over 16 KiB, by reference | +| `image`, `audio`, `video`, `document`, `file` | `source`, `purpose` (such as `screenshot`), `origin`: media, by reference only | +| `data` | `data` (any JSON value), `origin`: a structured A2A part | +| `elided` | `elision`, `media_type`: content that isn't there, and why | + +- A **source** is `url`, `media_type`, `bytes` and `sha256`, plus `width` and `height`, `duration_ms`, `pages` or + `name` where they apply. A `sha256:` URL resolves under the run's blob prefix. Media is never inline base64. +- An **elision** is `reason` (`truncated`, `redacted`, `digest_only`, `evicted`, `not_captured`, `not_requested`), + the original `bytes` and its `sha256`. A secret the agent was given is scrubbed by the SDK before the event is + appended, as a `redacted` elision with its length and no hash, since a hash of a short secret can be brute-forced. +- A user-side part carries an **origin**: `kind` (`framework`, `user_sim`, `trigger`, `notification`, `peer`, + `human`) beside the part's own metadata, such as a notification's channel and id. + +## Actors + +- Actors are declared before any event names them, in `turn.start` or in an `actor` event. +- An actor is `id`, `kind` (`agent`, `subagent`, `user`, `user_sim`, `human`, `peer`, `trigger_executor`, `env`, + `judge`, `framework`), and optionally `name`, `version`, `model_name`, `model_source` (`configured`, `reported`, + `unknown`), `role` (the gateway role, which joins the actor to env events), `participant` (its run-level id), + `a2a_agent_id`, `parent`, `spawned_by` and `stream`. +- A sub-agent lives in its parent's stream, under its own actor, with `parent` and `spawned_by` (the spawning + `tool_call_id`). It gets a `stream` of its own only when the native keeps it in its own file. +- A step event may belong to any actor, so a summarizer's inference is attributed where it happened. + +## Steps and usage + +- Usage is inclusive, as in ATIF and OTel: `prompt_tokens` includes cache reads and writes, and `completion_tokens` + includes reasoning. `cached_tokens`, `cache_write_tokens` and `reasoning_tokens` are subsets of those. `raw` keeps + the native counters. +- `usage_input_includes_cache` in `turn.start` says whether the native input count already included the cache, so a + reader can line YATF's numbers up with the native ones. Each adapter declares it as a constant, backed by a + recorded real run. +- `cost_status` is `reported` (the harness's own figure), `priced` (with `cost_source` naming the price table and + version) or `unpriced`. `cost_usd` is null exactly when unpriced. Agents serve what they report; pricing happens + elsewhere, never in the YATF copy. +- An unknown count is null or absent, never 0. +- `turn.end.final_metrics` uses ATIF's FinalMetrics names: `total_prompt_tokens`, `total_completion_tokens`, + `total_cached_tokens`, `total_cache_write_tokens`, `total_reasoning_tokens`, `total_cost_usd`, `cost_status` and + `cost_source`, plus: + - `basis`: `steps` when the totals sum the turn's step events, `reported` when they are what the harness reported; + - `total_steps`: the number of `step` events; + - `partial`: some usage is missing, such as an earlier attempt's after a retry; + - `includes_subagents`; + - `by_actor` and `by_model`: totals broken down. + +## Extensions and unknown fields + +- An **extension type** is `/`, lowercase, outside the `yatf` namespace. Readers keep it and may skip + it. An adapter keeps a native record that no handler takes as `/raw`, so converting back to native loses + nothing. +- `x` carries extension data on any event, keyed by namespace, such as `x.claude_code` for native fields YATF has no + field for. +- **Readers are tolerant.** A reader accepts any 1.x stream. It keeps fields, event types and part types it doesn't + know, and writes them back out unchanged. +- **Producers are strict.** A producer writes only what the minor version it declares defines. The validator reports + an unknown field as an error for a producer and as a warning for a reader. The JSON schema forbids unknown fields + everywhere except in an `origin`, an `x` and an extension event's body. + +## Versioning + +- The major version is in the format id. A breaking change is `yatf/2`, served beside `yatf/1`. +- A minor version only adds optional fields, types and vocabulary values. A field added in a minor version names the + version it arrived in, so the validator catches a producer that declares 1.0 but uses it. +- `turn.start` names the spec version, the native format and the adapter's name and version. The solver's actor names + the agent's version. + +## Validator rules + +The validator reports findings tagged with these rules, each fatal or a warning. V1 to V12 and V14 apply to agent +streams. `a2a-agent validate` makes them fatal for an agent that advertises `yatf/1`. + +| Rule | Checks | +| --- | --- | +| V1 frame | Each turn starts with `turn.start` and ends with `turn.end`. The inbound message follows `turn.start`, and at most one `final_response` comes just before `turn.end` | +| V2 positions | `seq` is dense from 0 in each turn and equals the cursor position; ids are `.` and unique | +| V3 actors | Every actor is declared before use, and every sub-agent's parent resolves | +| V4 calls | `tool_call_id` is unique in the context, and every `source_call_id` names an earlier call | +| V5 time | `at` is null or RFC 3339 with a zone; `start` is before `end`; `raw` is present when it differs | +| V6 usage | Subsets fit inside totals; cost is null exactly when unpriced; with basis `steps`, totals equal the step sums; `total_steps` counts the step events | +| V7 references | Every source has a URL, media type, size and sha256; `sha256:` URLs match their hash; a media part's kind agrees with its media type | +| V8 no inline payloads | No `data:` URIs, and no base64 run over 1 KiB outside opaque reasoning; an event is at most 256 KiB | +| V9 live equals final | The concatenated live pages equal the final read, event for event | +| V10 format labels | The card lists `yatf/1`, and every read names the format it served | +| V11 unknown fields | An error for a producer, a warning for a reader | +| V12 elision | Elided content has a reason and its original size, and a hash unless it was never captured or is a redacted secret | +| V14 round trip | Native to YATF to native equals the original up to the adapter's normal form, and YATF to native to YATF is the identity, on recorded fixtures | + +## Adapters + +- An adapter reads only what the run stores: the turn's context as the SDK records it in `turn.start`, the turn's + native records, and its aux records. The agent's own code feeds aux records in, and the SDK stores them in the + order fed. Replaying a stored turn therefore gives the events the agent served live. +- One adapter instance serves an A2A context across its turns. Renormalizing replays a context from turn 0. +- An adapter converts back with `from_yatf`. It gives each turn's native log, for the round trip, and the files the + CLI resumes from, or none. +- `lossy` names only what the native never records. Everything the native does record has a YATF field, sits under + `x.`, or is kept as a `/raw` event. + +## Examples + +`examples/` holds the design's three worked examples. Each one is a single turn's events. + +- `coding.json`: Claude Code fixes a failing test. Steps come from stream-json, with times null where stream-json has + none. A large read result is a `ref` part, and the turn totals are what the harness reported. +- `multi_agent.json`: a pydantic-ai solver's second turn. A simulated user's reply and a delivered notification arrive + as one inbound message, each part with its origin. +- `computer_use.json`: Claude Code drives a desktop. Screenshots are image parts by reference, and one reasoning + block's text was withheld (`visibility` `omitted`). diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/__init__.py b/packages/agentenv-protocol/src/agentenv_protocol/yatf/__init__.py new file mode 100644 index 000000000..29aaf35bc --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/__init__.py @@ -0,0 +1,79 @@ +"""yatf/1, the agent trajectory format: an append-only stream of JSON events each agent builds from its own native log +with an adapter and serves beside it. ``SPEC.md`` beside this module is the spec. The package needs only the protocol's +base dependencies, not the agent SDK, so anything can read a stream or write an adapter.""" +from .adapter import Adapter, AdapterSpec, Native, Selector, aux, finish, native, yatf_adapter +from .models import ( + CORE_TYPES, + EVENT_MODELS, + FORMAT, + RESERVED_TYPES, + SPEC_VERSION, + Actor, + ActorDeclared, + AdapterInfo, + AnyEvent, + Attempt, + DataPart, + DerivedFrom, + ElidedPart, + Elision, + ErrorEvent, + Event, + ExtensionEvent, + FinalMetrics, + FinalResponse, + MediaPart, + Message, + Metrics, + Note, + Opaque, + Origin, + Part, + Reasoning, + RefPart, + Source, + StepEvent, + TextPart, + Time, + ToolCall, + ToolDef, + ToolResult, + Tools, + TurnEnd, + TurnStart, + UnknownEvent, + UnknownPart, + UsageTotals, + VOCABULARIES, + VirtualTime, + YatfError, + YatfModel, + dump_event, + is_extension_type, + parse_event, +) +from .reader import ( + EXAMPLES, + FoldedStep, + ToolPair, + dump_events, + fold_steps, + load_example, + ordered, + pair_tool_calls, + parse_events, +) +from .runner import AdapterRun, Fed, RecordedTurn, TurnContext, YatfTurn, replay +from .schema import json_schema, load_schema + +__all__ = [ + "Actor", "ActorDeclared", "Adapter", "AdapterInfo", "AdapterRun", "AdapterSpec", "AnyEvent", "Attempt", + "CORE_TYPES", "DataPart", "DerivedFrom", "EVENT_MODELS", "EXAMPLES", "ElidedPart", "Elision", "ErrorEvent", + "Event", "ExtensionEvent", "FORMAT", "Fed", "FinalMetrics", "FinalResponse", "FoldedStep", "MediaPart", "Message", + "Metrics", "Native", "Note", "Opaque", "Origin", "Part", "RESERVED_TYPES", "Reasoning", "RecordedTurn", "RefPart", + "SPEC_VERSION", "Selector", "Source", "StepEvent", "TextPart", "Time", "ToolCall", "ToolDef", "ToolPair", + "ToolResult", "Tools", "TurnContext", "TurnEnd", "TurnStart", "UnknownEvent", "UnknownPart", "UsageTotals", + "VOCABULARIES", "VirtualTime", "YatfError", "YatfModel", "YatfTurn", "aux", "dump_event", "dump_events", "finish", + "fold_steps", "is_extension_type", "json_schema", "load_example", "load_schema", "native", "ordered", + "pair_tool_calls", "parse_event", "parse_events", "replay", "yatf_adapter", +] diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/__main__.py b/packages/agentenv-protocol/src/agentenv_protocol/yatf/__main__.py new file mode 100644 index 000000000..851f82eed --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/__main__.py @@ -0,0 +1,20 @@ +"""``python -m agentenv_protocol.yatf schema`` prints the strict JSON schema, as ``yatf-1.schema.json`` is checked in.""" +from __future__ import annotations + +import argparse +import sys + +from .schema import schema_text + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(prog="python -m agentenv_protocol.yatf") + commands = parser.add_subparsers(dest="command", required=True) + commands.add_parser("schema", help="print the strict JSON schema of one yatf/1 event") + parser.parse_args(argv) + sys.stdout.write(schema_text()) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/adapter.py b/packages/agentenv-protocol/src/agentenv_protocol/yatf/adapter.py new file mode 100644 index 000000000..db9501a4a --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/adapter.py @@ -0,0 +1,191 @@ +"""Writing a yatf/1 adapter: a class, declared with ``@yatf_adapter``, whose ``@native``, ``@aux`` and ``@finish`` +methods turn an agent's native records into YATF events through the YatfTurn each one is handed. It reads only what the +run stores, so an offline replay makes the events the agent served live.""" +from __future__ import annotations + +import re +from dataclasses import dataclass, field +from typing import TYPE_CHECKING, Any, Callable, ClassVar, Mapping, Sequence, TypeVar + +from .models import Event, YatfError, is_extension_type + +if TYPE_CHECKING: + from .runner import YatfTurn + +#: A native format id: ``/``, as ``claude-code-stream-json/1``. +NATIVE_FORMAT = re.compile(r"^[a-z0-9][a-z0-9._-]*/[A-Za-z0-9._-]+$") +_MISSING = object() + +A = TypeVar("A", bound="Adapter") + + +@dataclass(frozen=True) +class Native: + """What ``from_yatf`` gives back: each turn's native log in turn order, for the round trip, and the files the CLI + resumes from, by name, or None when this adapter can't seed a session.""" + + log: list[list[Any]] + session: dict[str, bytes] | None = None + + +@dataclass(frozen=True) +class Selector: + """The records a handler takes: native ones when ``aux`` is None, else aux file ``aux``'s, whose fields at each + dotted path in ``conditions`` hold one of the listed values.""" + + aux: str | None + conditions: tuple[tuple[str, tuple[Any, ...]], ...] + media_type: str | None = field(default=None, compare=False) + + def matches(self, record: Any) -> bool: + return all(_lookup(record, path) in allowed for path, allowed in self.conditions) + + +def _lookup(record: Any, path: str) -> Any: + value = record + for key in path.split("."): + if not isinstance(value, Mapping) or key not in value: + return _MISSING + value = value[key] + return value + + +def _values(value: Any) -> tuple[Any, ...]: + return tuple(value) if isinstance(value, (tuple, list, set, frozenset)) else (value,) + + +def _handler(aux_name: str | None, kind: Any, where: Mapping[str, Any] | None, + media_type: str | None) -> Callable[[Callable], Callable]: + conditions = ([("type", _values(kind))] if kind is not None else []) + [ + (path, _values(value)) for path, value in (where or {}).items()] + selector = Selector(aux_name, tuple(conditions), media_type) + + def mark(method: Callable) -> Callable: + method.__dict__.setdefault("__yatf_selectors__", []).append(selector) + return method + return mark + + +def native(*, type: Any = None, where: Mapping[str, Any] | None = None) -> Callable[[Callable], Callable]: + """Handle native records whose ``type`` is ``type`` (one value or several) and whose fields at the dotted ``where`` + paths hold the given values. Of the handlers that match a record, the one with the most conditions takes it.""" + return _handler(None, type, where, None) + + +def aux(name: str, *, media_type: str = "application/jsonl", type: Any = None, + where: Mapping[str, Any] | None = None) -> Callable[[Callable], Callable]: + """Handle records of the aux file ``name``, matched as ``native`` matches; this also declares the file. Aux + records no handler takes are dropped, since the run stores them anyway.""" + return _handler(name, type, where, media_type) + + +def finish(method: Callable) -> Callable: + """Run at turn end, after the last record: emit what's held and reset per-turn state.""" + method.__yatf_finish__ = True + return method + + +@dataclass(frozen=True) +class AdapterSpec: + """What ``@yatf_adapter`` declares, and its handlers by selector.""" + + name: str + native_format: str + version: str + usage_input_includes_cache: bool | None + tested_with: tuple[str, ...] + lossy: tuple[str, ...] + namespace: str + aux: Mapping[str, str] + handlers: tuple[tuple[Selector, str], ...] + finish: str | None + + def handler(self, aux_name: str | None, record: Any) -> str | None: + """The method that takes ``record``: the most specific matching handler, None when none matches.""" + matches = [(len(sel.conditions), method) for sel, method in self.handlers + if sel.aux == aux_name and sel.matches(record)] + if not matches: + return None + best = max(count for count, _ in matches) + methods = sorted({method for count, method in matches if count == best}) + if len(methods) > 1: + raise YatfError(f"a record matches {', '.join(methods)} equally; make one of them more specific") + return methods[0] + + +def yatf_adapter(*, native_format: str, version: str, usage_input_includes_cache: bool | None, + tested_with: Sequence[str] = (), lossy: Sequence[str] = (), name: str | None = None, + namespace: str | None = None) -> Callable[[type[A]], type[A]]: + """Declare an Adapter subclass for ``native_format``. + + ``usage_input_includes_cache`` says whether the native input token count already includes cache reads and writes + (None when the native reports no usage). ``tested_with`` names the native producer versions its recorded fixtures + come from, ``lossy`` only what the native never records, and ``namespace`` its extension types + (``/raw``), by default the native format's name.""" + if not isinstance(native_format, str) or not NATIVE_FORMAT.match(native_format): + raise YatfError(f"native_format {native_format!r} isn't /") + if native_format.startswith("yatf/"): + raise YatfError(f"native_format {native_format!r}: yatf is the format adapters produce, not a native one") + if not isinstance(version, str) or not version: + raise YatfError("version is the adapter's own version string") + if usage_input_includes_cache not in (True, False, None): + raise YatfError("usage_input_includes_cache is true, false or None") + ns = namespace or native_format.split("/", 1)[0] + if not is_extension_type(f"{ns}/raw"): + raise YatfError(f"namespace {ns!r} can't name extension types") + + def declare(cls: type[A]) -> type[A]: + if not (isinstance(cls, type) and issubclass(cls, Adapter)): + raise TypeError("@yatf_adapter decorates an Adapter subclass") + members: dict[str, Any] = {} + for klass in reversed(cls.__mro__): + members.update(vars(klass)) + owners: dict[Selector, str] = {} + aux_types: dict[str, str] = {} + finishes = [] + for attr, member in members.items(): + if getattr(member, "__yatf_finish__", False): + finishes.append(attr) + for selector in getattr(member, "__yatf_selectors__", ()): + if selector in owners and owners[selector] != attr: + raise YatfError(f"{cls.__name__}.{owners[selector]} and .{attr} take the same records") + owners[selector] = attr + if selector.aux is not None: + known = aux_types.setdefault(selector.aux, selector.media_type) + if known != selector.media_type: + raise YatfError(f"aux file {selector.aux!r} is declared as both {known} and " + f"{selector.media_type}") + if len(finishes) > 1: + raise YatfError(f"{cls.__name__} has more than one @finish method: {', '.join(finishes)}") + cls.spec = AdapterSpec( + name=name or f"{ns}-yatf", native_format=native_format, version=version, + usage_input_includes_cache=usage_input_includes_cache, tested_with=tuple(tested_with), + lossy=tuple(lossy), namespace=ns, aux=dict(aux_types), + handlers=tuple((selector, attr) for selector, attr in owners.items()), + finish=finishes[0] if finishes else None) + return cls + return declare + + +class Adapter: + """Base of a yatf/1 adapter. One instance serves an A2A context across its turns; per-turn state resets in + ``@finish``. To emit an event later than its record, keep ``turn.source`` and pass it as ``derived_from``.""" + + spec: ClassVar[AdapterSpec] + + def __init__(self, turn: YatfTurn) -> None: + """Set up for the context whose first turn here is ``turn``.""" + + def unmatched(self, record: Any, turn: YatfTurn) -> None: + """A native record no handler takes, kept as a ``/raw`` event so nothing is lost.""" + turn.raw(record) + + @classmethod + def from_yatf(cls, events: list[Event]) -> Native: + """A context's events, every turn so far, back to native.""" + raise NotImplementedError(f"{cls.__name__} doesn't convert yatf/1 back to its native format") + + @classmethod + def normal_form(cls, records: list[Any]) -> list[Any]: + """What the round trip compares: by default the parsed records themselves.""" + return list(records) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/examples/coding.json b/packages/agentenv-protocol/src/agentenv_protocol/yatf/examples/coding.json new file mode 100644 index 000000000..4ace4888e --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/examples/coding.json @@ -0,0 +1,22 @@ +[ +{"seq":0,"id":"0.0","type":"turn.start","turn":0,"actor":"solver","observer":"agent","time":{"at":"2026-11-04T17:02:11.204Z"},"spec_version":"1.0","context_id":"ctx-7f3a","task_id":"task-91c2","message_id":"msg-a1","native_format":"claude-code-stream-json/1","live":true,"adapter":{"name":"claude-code-yatf","version":"0.1.0","lossy":["system prompt is not in stream-json"]},"actors":[{"id":"solver","kind":"agent","name":"claude-code","a2a_agent_id":"claude-code","version":"2.3.1","model_name":"claude-opus-5-5","model_source":"configured","participant":"solver"},{"id":"caller","kind":"framework","name":"prompt_agent","participant":"framework"}],"usage_input_includes_cache":false}, +{"seq":1,"id":"0.1","type":"message","turn":0,"actor":"caller","observer":"agent","time":{"at":"2026-11-04T17:02:11.204Z"},"step":"in-0","role":"user","content":[{"type":"text","text":"tests/test_parse.py::test_utc fails. Fix parse_date without changing the test.","origin":{"kind":"framework"}}]}, +{"seq":2,"id":"0.2","type":"tools","turn":0,"actor":"solver","observer":"agent","time":{"at":null},"mode":"replace","tools":[{"name":"Bash","kind":"builtin"},{"name":"Read","kind":"builtin"},{"name":"Edit","kind":"builtin"}],"derived_from":{"index":0}}, +{"seq":3,"id":"0.3","type":"reasoning","turn":0,"actor":"solver","observer":"agent","time":{"at":null},"step":"msg_01A","visibility":"raw","text":"Run the failing test first to see the error.","opaque":[{"kind":"signature","provider":"anthropic","value":"EqQBCkgIBhABGAIiQKm3"}],"derived_from":{"index":1}}, +{"seq":4,"id":"0.4","type":"tool_call","turn":0,"actor":"solver","observer":"agent","time":{"at":null},"step":"msg_01A","tool_call_id":"toolu_01","function_name":"Bash","kind":"builtin","executor":"agent","arguments":{"command":"pytest tests/test_parse.py -q"},"derived_from":{"index":2}}, +{"seq":5,"id":"0.5","type":"step","turn":0,"actor":"solver","observer":"agent","time":{"at":null},"step":"msg_01A","source":"agent","llm_call_count":1,"model_name":"claude-opus-5-5","stop_reason":"tool_use","provider_ids":{"response_id":"msg_01A"},"metrics":{"prompt_tokens":18432,"completion_tokens":212,"cached_tokens":16890,"cache_write_tokens":1402,"cost_usd":null,"cost_status":"unpriced","raw":{"input_tokens":140,"cache_read_input_tokens":16890,"cache_creation_input_tokens":1402,"output_tokens":212}}}, +{"seq":6,"id":"0.6","type":"tool_result","turn":0,"actor":"solver","observer":"agent","time":{"at":"2026-11-04T17:02:19.877Z"},"source_call_id":"toolu_01","status":"error","content":[{"type":"text","text":"FAILED tests/test_parse.py::test_utc - ValueError: Invalid isoformat string: '2026-01-02T03:04:05Z'"}]}, +{"seq":7,"id":"0.7","type":"tool_call","turn":0,"actor":"solver","observer":"agent","time":{"at":null},"step":"msg_01B","tool_call_id":"toolu_02","function_name":"Read","kind":"builtin","executor":"agent","arguments":{"file_path":"tests/fixtures/dates.txt"}}, +{"seq":8,"id":"0.8","type":"step","turn":0,"actor":"solver","observer":"agent","time":{"at":null},"step":"msg_01B","source":"agent","llm_call_count":1,"model_name":"claude-opus-5-5","stop_reason":"tool_use","metrics":{"prompt_tokens":18901,"completion_tokens":96,"cached_tokens":18292,"cache_write_tokens":469,"cost_usd":null,"cost_status":"unpriced"}}, +{"seq":9,"id":"0.9","type":"tool_result","turn":0,"actor":"solver","observer":"agent","time":{"at":"2026-11-04T17:02:24.310Z"},"source_call_id":"toolu_02","status":"ok","content":[{"type":"ref","preview":"2026-01-02T03:04:05Z -> 2026-01-02 03:04:05+00:00","source":{"url":"sha256:5b4818f81c7256e686ba2e0537258c852c6f5c3e646e84f9625f8744ede6a8f8","media_type":"text/plain","bytes":48211,"sha256":"5b4818f81c7256e686ba2e0537258c852c6f5c3e646e84f9625f8744ede6a8f8"}}]}, +{"seq":10,"id":"0.10","type":"tool_call","turn":0,"actor":"solver","observer":"agent","time":{"at":null},"step":"msg_01C","tool_call_id":"toolu_03","function_name":"Edit","kind":"builtin","executor":"agent","arguments":{"file_path":"src/parse.py","old_string":"datetime.fromisoformat(s)","new_string":"datetime.fromisoformat(s.replace('Z', '+00:00'))"}}, +{"seq":11,"id":"0.11","type":"step","turn":0,"actor":"solver","observer":"agent","time":{"at":null},"step":"msg_01C","source":"agent","llm_call_count":1,"model_name":"claude-opus-5-5","stop_reason":"tool_use","metrics":{"prompt_tokens":31377,"completion_tokens":188,"cached_tokens":18761,"cache_write_tokens":12476,"cost_usd":null,"cost_status":"unpriced"}}, +{"seq":12,"id":"0.12","type":"tool_result","turn":0,"actor":"solver","observer":"agent","time":{"at":"2026-11-04T17:02:41.002Z"},"source_call_id":"toolu_03","status":"ok","content":[{"type":"text","text":"The file src/parse.py has been updated."}]}, +{"seq":13,"id":"0.13","type":"tool_call","turn":0,"actor":"solver","observer":"agent","time":{"at":null},"step":"msg_01D","tool_call_id":"toolu_04","function_name":"Bash","kind":"builtin","executor":"agent","arguments":{"command":"pytest tests/test_parse.py -q"}}, +{"seq":14,"id":"0.14","type":"step","turn":0,"actor":"solver","observer":"agent","time":{"at":null},"step":"msg_01D","source":"agent","llm_call_count":1,"model_name":"claude-opus-5-5","stop_reason":"tool_use","metrics":{"prompt_tokens":31702,"completion_tokens":74,"cached_tokens":31237,"cache_write_tokens":325,"cost_usd":null,"cost_status":"unpriced"}}, +{"seq":15,"id":"0.15","type":"tool_result","turn":0,"actor":"solver","observer":"agent","time":{"at":"2026-11-04T17:02:55.419Z"},"source_call_id":"toolu_04","status":"ok","content":[{"type":"text","text":"3 passed in 0.18s"}]}, +{"seq":16,"id":"0.16","type":"message","turn":0,"actor":"solver","observer":"agent","time":{"at":null},"step":"msg_01E","role":"assistant","content":[{"type":"text","text":"parse_date now accepts a trailing Z; all 3 tests in tests/test_parse.py pass."}]}, +{"seq":17,"id":"0.17","type":"step","turn":0,"actor":"solver","observer":"agent","time":{"at":null},"step":"msg_01E","source":"agent","llm_call_count":1,"model_name":"claude-opus-5-5","stop_reason":"end_turn","metrics":{"prompt_tokens":31890,"completion_tokens":41,"cached_tokens":31562,"cache_write_tokens":188,"cost_usd":null,"cost_status":"unpriced"}}, +{"seq":18,"id":"0.18","type":"final_response","turn":0,"actor":"solver","observer":"agent","time":{"at":"2026-11-04T17:03:02.551Z"},"content":[{"type":"text","text":"parse_date now accepts a trailing Z; all 3 tests in tests/test_parse.py pass."}]}, +{"seq":19,"id":"0.19","type":"turn.end","turn":0,"actor":"solver","observer":"agent","time":{"at":"2026-11-04T17:03:02.551Z"},"state":"completed","tool_call_count":4,"final_metrics":{"total_prompt_tokens":132302,"total_completion_tokens":611,"total_cached_tokens":116742,"total_cache_write_tokens":14860,"total_steps":5,"basis":"reported","includes_subagents":true,"partial":false,"total_cost_usd":0.2117,"cost_status":"reported","cost_source":"harness"}} +] diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/examples/computer_use.json b/packages/agentenv-protocol/src/agentenv_protocol/yatf/examples/computer_use.json new file mode 100644 index 000000000..a2ef5203f --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/examples/computer_use.json @@ -0,0 +1,21 @@ +[ +{"seq":0,"id":"0.0","type":"turn.start","turn":0,"actor":"solver","observer":"agent","time":{"at":"2026-11-04T19:10:01.020Z"},"spec_version":"1.0","context_id":"ctx-c","task_id":"task-c1","native_format":"claude-code-stream-json/1","live":true,"adapter":{"name":"claude-code-yatf","version":"0.1.0"},"actors":[{"id":"solver","kind":"agent","name":"claude-code","model_name":"claude-opus-5-5","model_source":"configured","participant":"solver"},{"id":"caller","kind":"framework","name":"prompt_agent","participant":"framework"}],"message_id":"msg-c1","usage_input_includes_cache":false}, +{"seq":1,"id":"0.1","type":"message","turn":0,"actor":"caller","observer":"agent","time":{"at":"2026-11-04T19:10:01.020Z"},"step":"in-0","role":"user","content":[{"type":"text","text":"In the open spreadsheet, set B2 to 42 and save the file.","origin":{"kind":"framework"}}]}, +{"seq":2,"id":"0.2","type":"tool_call","turn":0,"actor":"solver","observer":"agent","time":{"at":null},"step":"msg_c1","tool_call_id":"toolu_c1","function_name":"computer","kind":"mcp","server":"desktop","executor":"env","env_id":"desktop","arguments":{"action":"screenshot"}}, +{"seq":3,"id":"0.3","type":"step","turn":0,"actor":"solver","observer":"agent","time":{"at":null},"step":"msg_c1","source":"agent","llm_call_count":1,"model_name":"claude-opus-5-5","stop_reason":"tool_use","metrics":{"prompt_tokens":6210,"completion_tokens":58,"cached_tokens":5120,"cache_write_tokens":1024,"cost_usd":null,"cost_status":"unpriced"}}, +{"seq":4,"id":"0.4","type":"tool_result","turn":0,"actor":"solver","observer":"agent","time":{"at":"2026-11-04T19:10:04.118Z"},"source_call_id":"toolu_c1","status":"ok","content":[{"type":"image","purpose":"screenshot","source":{"url":"sha256:55876e316eab4b5a0b5b3cbcebfb0bfefc3c82a87abf007c9db55c9c4d25510a","media_type":"image/png","bytes":184311,"sha256":"55876e316eab4b5a0b5b3cbcebfb0bfefc3c82a87abf007c9db55c9c4d25510a","width":1280,"height":800}}]}, +{"seq":5,"id":"0.5","type":"reasoning","turn":0,"actor":"solver","observer":"agent","time":{"at":null},"step":"msg_c2","visibility":"omitted","text":null,"opaque":[{"kind":"signature","provider":"anthropic","value":"EpwBCkYIBRgCIkB2"}]}, +{"seq":6,"id":"0.6","type":"tool_call","turn":0,"actor":"solver","observer":"agent","time":{"at":null},"step":"msg_c2","tool_call_id":"toolu_c2","function_name":"computer","kind":"mcp","server":"desktop","executor":"env","env_id":"desktop","arguments":{"action":"left_click","coordinate":[212,318]}}, +{"seq":7,"id":"0.7","type":"step","turn":0,"actor":"solver","observer":"agent","time":{"at":null},"step":"msg_c2","source":"agent","llm_call_count":1,"model_name":"claude-opus-5-5","stop_reason":"tool_use","metrics":{"prompt_tokens":7802,"completion_tokens":121,"cached_tokens":6144,"cache_write_tokens":1658,"cost_usd":null,"cost_status":"unpriced"}}, +{"seq":8,"id":"0.8","type":"tool_result","turn":0,"actor":"solver","observer":"agent","time":{"at":"2026-11-04T19:10:07.412Z"},"source_call_id":"toolu_c2","status":"ok","content":[{"type":"image","purpose":"screenshot","source":{"url":"sha256:9fdfb62359af014a0d6b3c570a0ae1ba569cb593ca355d4ac03632c9c734acd3","media_type":"image/png","bytes":186020,"sha256":"9fdfb62359af014a0d6b3c570a0ae1ba569cb593ca355d4ac03632c9c734acd3","width":1280,"height":800}}]}, +{"seq":9,"id":"0.9","type":"tool_call","turn":0,"actor":"solver","observer":"agent","time":{"at":null},"step":"msg_c3","tool_call_id":"toolu_c3","function_name":"computer","kind":"mcp","server":"desktop","executor":"env","env_id":"desktop","arguments":{"action":"type","text":"42"}}, +{"seq":10,"id":"0.10","type":"step","turn":0,"actor":"solver","observer":"agent","time":{"at":null},"step":"msg_c3","source":"agent","llm_call_count":1,"model_name":"claude-opus-5-5","stop_reason":"tool_use","metrics":{"prompt_tokens":9805,"completion_tokens":47,"cached_tokens":7680,"cache_write_tokens":2125,"cost_usd":null,"cost_status":"unpriced"}}, +{"seq":11,"id":"0.11","type":"tool_result","turn":0,"actor":"solver","observer":"agent","time":{"at":"2026-11-04T19:10:10.906Z"},"source_call_id":"toolu_c3","status":"ok","content":[{"type":"image","purpose":"screenshot","source":{"url":"sha256:3c1b6f0e8a9d42b7c5e1f0a2d4b6c8e0f1a3b5c7d9e2f4a6b8c0d1e3f5a7b9c2","media_type":"image/png","bytes":185009,"sha256":"3c1b6f0e8a9d42b7c5e1f0a2d4b6c8e0f1a3b5c7d9e2f4a6b8c0d1e3f5a7b9c2","width":1280,"height":800}}]}, +{"seq":12,"id":"0.12","type":"tool_call","turn":0,"actor":"solver","observer":"agent","time":{"at":null},"step":"msg_c4","tool_call_id":"toolu_c4","function_name":"computer","kind":"mcp","server":"desktop","executor":"env","env_id":"desktop","arguments":{"action":"key","text":"ctrl+s"}}, +{"seq":13,"id":"0.13","type":"step","turn":0,"actor":"solver","observer":"agent","time":{"at":null},"step":"msg_c4","source":"agent","llm_call_count":1,"model_name":"claude-opus-5-5","stop_reason":"tool_use","metrics":{"prompt_tokens":11431,"completion_tokens":38,"cached_tokens":9728,"cache_write_tokens":1703,"cost_usd":null,"cost_status":"unpriced"}}, +{"seq":14,"id":"0.14","type":"tool_result","turn":0,"actor":"solver","observer":"agent","time":{"at":"2026-11-04T19:10:13.287Z"},"source_call_id":"toolu_c4","status":"ok","content":[{"type":"image","purpose":"screenshot","source":{"url":"sha256:7e2d9a4c1f6b38e5d0a7c2b9f4e1d6a3c8b5f2e9d4a1c6b3f8e5d2a9c4b1f6e3","media_type":"image/png","bytes":185012,"sha256":"7e2d9a4c1f6b38e5d0a7c2b9f4e1d6a3c8b5f2e9d4a1c6b3f8e5d2a9c4b1f6e3","width":1280,"height":800}}]}, +{"seq":15,"id":"0.15","type":"message","turn":0,"actor":"solver","observer":"agent","time":{"at":null},"step":"msg_c5","role":"assistant","content":[{"type":"text","text":"B2 is now 42 and the file is saved."}]}, +{"seq":16,"id":"0.16","type":"step","turn":0,"actor":"solver","observer":"agent","time":{"at":null},"step":"msg_c5","source":"agent","llm_call_count":1,"model_name":"claude-opus-5-5","stop_reason":"end_turn","metrics":{"prompt_tokens":12129,"completion_tokens":23,"cached_tokens":10969,"cache_write_tokens":1160,"cost_usd":null,"cost_status":"unpriced"}}, +{"seq":17,"id":"0.17","type":"final_response","turn":0,"actor":"solver","observer":"agent","time":{"at":"2026-11-04T19:10:16.004Z"},"content":[{"type":"text","text":"B2 is now 42 and the file is saved."}]}, +{"seq":18,"id":"0.18","type":"turn.end","turn":0,"actor":"solver","observer":"agent","time":{"at":"2026-11-04T19:10:16.005Z"},"state":"completed","tool_call_count":4,"final_metrics":{"total_prompt_tokens":47377,"total_completion_tokens":287,"total_cached_tokens":39641,"total_cache_write_tokens":7670,"total_steps":5,"basis":"reported","includes_subagents":true,"partial":false,"total_cost_usd":0.0914,"cost_status":"reported","cost_source":"harness"}} +] diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/examples/multi_agent.json b/packages/agentenv-protocol/src/agentenv_protocol/yatf/examples/multi_agent.json new file mode 100644 index 000000000..433e1a881 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/examples/multi_agent.json @@ -0,0 +1,12 @@ +[ +{"seq":0,"id":"1.0","type":"turn.start","turn":1,"actor":"solver","observer":"agent","time":{"at":"2026-11-04T18:01:40.530Z"},"spec_version":"1.0","context_id":"ctx-1","task_id":"task-b2","native_format":"pydantic-ai-messages/v1","live":true,"adapter":{"name":"pydantic-ai-yatf","version":"0.1.0"},"actors":[{"id":"solver","kind":"agent","name":"pydantic-ai","model_name":"claude-opus-5-5","model_source":"configured","role":"dana","participant":"solver"},{"id":"user_sim","kind":"user_sim","name":"usersim","model_name":"gpt-6-astra","participant":"user_sim"}],"message_id":"msg-b2","usage_input_includes_cache":true}, +{"seq":1,"id":"1.1","type":"message","turn":1,"actor":"user_sim","observer":"agent","time":{"at":"2026-11-04T18:01:40.530Z"},"step":"in-1","role":"user","content":[{"type":"text","text":"[Email from Priya Shah] Board review moved to 3:00pm today.","origin":{"kind":"notification","id":"ntf-07","to":"dana","at":"2026-03-12T13:30:00-05:00","source":"gmail","source_id":"msg-18c","channel":"email","env_id":"workspace"}},{"type":"text","text":"Ugh. Can you make sure my 1:1 with Sam doesn't clash?","origin":{"kind":"user_sim","actor":"user_sim","done":false}}]}, +{"seq":2,"id":"1.2","type":"reasoning","turn":1,"actor":"solver","observer":"agent","time":{"at":"2026-11-04T18:01:46.902Z"},"step":"resp-1a","visibility":"raw","text":"Board is now 3-4pm; the 1:1 is at 3pm. Move the 1:1 to 4pm.","opaque":[{"kind":"signature","provider":"anthropic","value":"ErUBCkYIBRgCKkAx"}]}, +{"seq":3,"id":"1.3","type":"tool_call","turn":1,"actor":"solver","observer":"agent","time":{"at":"2026-11-04T18:01:46.902Z"},"step":"resp-1a","tool_call_id":"toolu_9a","function_name":"calendar_update_event","kind":"mcp","server":"workspace","executor":"env","env_id":"workspace","arguments":{"event_id":"evt_1on1_sam","start":"2026-03-12T16:00:00-05:00","end":"2026-03-12T16:30:00-05:00"}}, +{"seq":4,"id":"1.4","type":"step","turn":1,"actor":"solver","observer":"agent","time":{"at":"2026-11-04T18:01:46.902Z"},"step":"resp-1a","source":"agent","llm_call_count":1,"model_name":"claude-opus-5-5","stop_reason":"tool_call","metrics":{"prompt_tokens":9120,"completion_tokens":144,"cached_tokens":8448,"cache_write_tokens":512,"cost_usd":null,"cost_status":"unpriced"}}, +{"seq":5,"id":"1.5","type":"tool_result","turn":1,"actor":"solver","observer":"agent","time":{"at":"2026-11-04T18:01:47.611Z"},"source_call_id":"toolu_9a","status":"ok","content":[{"type":"text","text":"Updated evt_1on1_sam: 4:00pm-4:30pm"}]}, +{"seq":6,"id":"1.6","type":"message","turn":1,"actor":"solver","observer":"agent","time":{"at":"2026-11-04T18:01:52.812Z"},"step":"resp-1b","role":"assistant","content":[{"type":"text","text":"Moved your 1:1 with Sam to 4:00pm, right after the board review."}]}, +{"seq":7,"id":"1.7","type":"step","turn":1,"actor":"solver","observer":"agent","time":{"at":"2026-11-04T18:01:52.812Z"},"step":"resp-1b","source":"agent","llm_call_count":1,"model_name":"claude-opus-5-5","stop_reason":"stop","metrics":{"prompt_tokens":9402,"completion_tokens":31,"cached_tokens":8960,"cache_write_tokens":160,"cost_usd":null,"cost_status":"unpriced"}}, +{"seq":8,"id":"1.8","type":"final_response","turn":1,"actor":"solver","observer":"agent","time":{"at":"2026-11-04T18:01:52.850Z"},"content":[{"type":"text","text":"Moved your 1:1 with Sam to 4:00pm, right after the board review."}]}, +{"seq":9,"id":"1.9","type":"turn.end","turn":1,"actor":"solver","observer":"agent","time":{"at":"2026-11-04T18:01:52.851Z"},"state":"completed","tool_call_count":1,"final_metrics":{"total_prompt_tokens":18522,"total_completion_tokens":175,"total_cached_tokens":17408,"total_cache_write_tokens":672,"total_steps":2,"basis":"steps","includes_subagents":true,"total_cost_usd":null,"cost_status":"unpriced"}} +] diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/models.py b/packages/agentenv-protocol/src/agentenv_protocol/yatf/models.py new file mode 100644 index 000000000..782eb8865 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/models.py @@ -0,0 +1,497 @@ +"""The yatf/1 event models: one tolerant tree that keeps every field, event type and part type it doesn't know, so a +reader writes a newer 1.x stream back out unchanged. A producer's strictness lives in the validator and in the strict +JSON schema generated from these models.""" +from __future__ import annotations + +import math +import re +from typing import Annotated, Any, ClassVar, Literal, Union, get_args + +from pydantic import BaseModel, ConfigDict, Discriminator, Tag, TypeAdapter, ValidationError, WithJsonSchema + +FORMAT = "yatf/1" +SPEC_VERSION = "1.0" + +#: Defined by a later 1.x together with its first producer; no 1.0 producer may write them. +RESERVED_TYPES = frozenset({"delegation", "context", "producer", "activation", "usage.checkpoint"}) +#: An extension type is ``/``; the ``yatf`` namespace belongs to the spec. +EXTENSION_TYPE = re.compile(r"^(?!yatf/)[a-z0-9][a-z0-9._-]*/[a-z0-9][a-z0-9._-]*$") + +OBSERVERS = ("agent", "gateway", "browser", "framework") +ACTOR_KINDS = ("agent", "subagent", "user", "user_sim", "human", "peer", "trigger_executor", "env", "judge", "framework") +MODEL_SOURCES = ("configured", "reported", "unknown") +ORIGIN_KINDS = ("framework", "user_sim", "trigger", "notification", "peer", "human") +ELISION_REASONS = ("truncated", "redacted", "digest_only", "evicted", "not_captured", "not_requested") +MediaKind = Literal["image", "audio", "video", "document", "file"] +MEDIA_KINDS: tuple[str, ...] = get_args(MediaKind) +ROLES = ("user", "assistant", "system", "developer") +STEP_SOURCES = ("agent", "user", "system") +COST_STATUSES = ("reported", "priced", "unpriced") +BASES = ("steps", "reported") +VISIBILITIES = ("raw", "summary", "omitted", "redacted") +OPAQUE_KINDS = ("signature", "encrypted", "redacted_data") +TOOL_KINDS = ("builtin", "mcp", "function", "custom") +EXECUTORS = ("agent", "env", "provider", "client") +RESULT_STATUSES = ("ok", "error", "canceled", "timeout") +TOOLS_MODES = ("replace", "add", "remove") +TURN_STATES = ("completed", "failed", "canceled") +ERROR_TYPES = ("agent_error", "infra_error") +#: Every vocabulary, by the field that takes it: a later minor may add values, which a reader keeps. +VOCABULARIES: dict[str, tuple[str, ...]] = { + "observer": OBSERVERS, "actor.kind": ACTOR_KINDS, "actor.model_source": MODEL_SOURCES, "origin.kind": ORIGIN_KINDS, + "elision.reason": ELISION_REASONS, "media part type": MEDIA_KINDS, "message.role": ROLES, "step.source": STEP_SOURCES, + "cost_status": COST_STATUSES, "final_metrics.basis": BASES, "reasoning.visibility": VISIBILITIES, + "opaque.kind": OPAQUE_KINDS, "tool kind": TOOL_KINDS, "tool_call.executor": EXECUTORS, + "tool_result.status": RESULT_STATUSES, "tools.mode": TOOLS_MODES, "turn.end.state": TURN_STATES, + "error.error_type": ERROR_TYPES, +} + + +def _vocabulary(values: tuple[str, ...]) -> WithJsonSchema: + """A string the strict schema limits to ``values``; the model takes any string, as a later minor may add one.""" + return WithJsonSchema({"type": "string", "enum": list(values)}) + + +Observer = Annotated[str, _vocabulary(OBSERVERS)] +ActorKind = Annotated[str, _vocabulary(ACTOR_KINDS)] +ModelSource = Annotated[str, _vocabulary(MODEL_SOURCES)] +OriginKind = Annotated[str, _vocabulary(ORIGIN_KINDS)] +ElisionReason = Annotated[str, _vocabulary(ELISION_REASONS)] +Role = Annotated[str, _vocabulary(ROLES)] +StepSource = Annotated[str, _vocabulary(STEP_SOURCES)] +CostStatus = Annotated[str, _vocabulary(COST_STATUSES)] +Basis = Annotated[str, _vocabulary(BASES)] +Visibility = Annotated[str, _vocabulary(VISIBILITIES)] +OpaqueKind = Annotated[str, _vocabulary(OPAQUE_KINDS)] +ToolKind = Annotated[str, _vocabulary(TOOL_KINDS)] +Executor = Annotated[str, _vocabulary(EXECUTORS)] +ResultStatus = Annotated[str, _vocabulary(RESULT_STATUSES)] +ToolsMode = Annotated[str, _vocabulary(TOOLS_MODES)] +TurnState = Annotated[str, _vocabulary(TURN_STATES)] +ErrorType = Annotated[str, _vocabulary(ERROR_TYPES)] + + +class YatfError(ValueError): + """A stream or event that isn't yatf/1, or an adapter that breaks the adapter contract.""" + + +_CLOSED = ConfigDict(extra="allow", strict=True, allow_inf_nan=False, protected_namespaces=(), + json_schema_extra={"additionalProperties": False}) +_OPEN = ConfigDict({**_CLOSED, "json_schema_extra": {"additionalProperties": True}}) + + +class YatfModel(BaseModel): + """Keeps fields it doesn't know through a dump (the validator reports them), while the strict schema forbids them. + Values are taken as given, never coerced, so whatever parses dumps back exactly.""" + + model_config = _CLOSED + #: Whether fields this version doesn't name are part of the model's meaning, not unknowns (V11 skips them). + OPEN: ClassVar[bool] = False + + +class _Open(YatfModel): + model_config = _OPEN + OPEN: ClassVar[bool] = True + + +class VirtualTime(YatfModel): + env_id: str + env_step_id: str | None = None + at: str + + +class Time(YatfModel): + """When an event happened per the native record. ``at`` is always present and null when the native has no time; + ``raw`` is the native string whenever it differs from ``at``.""" + + at: str | None + start: str | None = None + end: str | None = None + duration_ms: int | None = None + raw: str | None = None + virtual: list[VirtualTime] | None = None + + +class Source(YatfModel): + """Bytes held by reference: a ``sha256:`` URL resolved under the run's blob prefix, or an absolute URL.""" + + url: str + media_type: str + bytes: int + sha256: str + width: int | None = None + height: int | None = None + duration_ms: int | None = None + pages: int | None = None + name: str | None = None + + +class Elision(YatfModel): + """Why content is missing, so elided never reads as empty. A redacted secret has its length and no hash.""" + + reason: ElisionReason + bytes: int | None = None + sha256: str | None = None + + +class Origin(_Open): + """Where a user-side part came from; the part's own metadata (a notification's channel, a peer's id) sits beside + ``kind``.""" + + kind: OriginKind + + +class TextPart(YatfModel): + type: Literal["text"] + text: str + origin: Origin | None = None + elision: Elision | None = None + + +class RefPart(YatfModel): + """Text over the inline limit: a preview and the full text by reference.""" + + type: Literal["ref"] + preview: str + source: Source + origin: Origin | None = None + + +class MediaPart(YatfModel): + type: MediaKind + source: Source + purpose: str | None = None + origin: Origin | None = None + + +class DataPart(YatfModel): + """A structured A2A part, such as a harness's tool-call count or a structured output.""" + + type: Literal["data"] + data: Any + origin: Origin | None = None + + +class ElidedPart(YatfModel): + type: Literal["elided"] + elision: Elision + media_type: str | None = None + + +class UnknownPart(_Open): + """A part type this version doesn't define: readers keep it, producers may not write it.""" + + type: str + + +_PART_TAGS = {"text": "text", "ref": "ref", "data": "data", "elided": "elided", **{kind: "media" for kind in MEDIA_KINDS}} +_NOTHING = WithJsonSchema({"not": {}, "description": "A type this version doesn't define: readers keep it, producers may " + "not write it."}) + + +def _part_tag(value: Any) -> str: + kind = value.get("type") if isinstance(value, dict) else getattr(value, "type", None) + return _PART_TAGS.get(kind, "unknown") if isinstance(kind, str) else "unknown" + + +Part = Annotated[ + Union[ + Annotated[TextPart, Tag("text")], + Annotated[RefPart, Tag("ref")], + Annotated[MediaPart, Tag("media")], + Annotated[DataPart, Tag("data")], + Annotated[ElidedPart, Tag("elided")], + Annotated[UnknownPart, Tag("unknown"), _NOTHING], + ], + Discriminator(_part_tag), +] + + +class Actor(YatfModel): + """A participant, declared in ``turn.start`` or an ``actor`` event before any event names it. A sub-agent carries + its ``parent`` actor and the ``tool_call_id`` that ``spawned_by`` it.""" + + id: str + kind: ActorKind + name: str | None = None + version: str | None = None + model_name: str | None = None + model_source: ModelSource | None = None + role: str | None = None + participant: str | None = None + a2a_agent_id: str | None = None + parent: str | None = None + spawned_by: str | None = None + stream: str | None = None + + +class DerivedFrom(YatfModel): + """The record an event came from: its position in the turn's stored native log, or in the named aux log.""" + + index: int + aux: str | None = None + + +class AdapterInfo(YatfModel): + name: str + version: str + lossy: list[str] | None = None + + +class Metrics(YatfModel): + """One step's usage, inclusive as in ATIF: ``prompt_tokens`` counts cache reads and writes, ``completion_tokens`` + counts reasoning. An unknown count is null or absent, never 0; ``raw`` keeps the native counters.""" + + prompt_tokens: int | None = None + completion_tokens: int | None = None + cached_tokens: int | None = None + cache_write_tokens: int | None = None + reasoning_tokens: int | None = None + cost_usd: int | float | None = None + cost_status: CostStatus | None = None + cost_source: str | None = None + raw: dict[str, Any] | None = None + + +class UsageTotals(YatfModel): + total_prompt_tokens: int | None = None + total_completion_tokens: int | None = None + total_cached_tokens: int | None = None + total_cache_write_tokens: int | None = None + total_reasoning_tokens: int | None = None + total_cost_usd: int | float | None = None + cost_status: CostStatus | None = None + cost_source: str | None = None + + +class FinalMetrics(UsageTotals): + """A turn's totals under ATIF's FinalMetrics names. ``basis`` says whether they sum the turn's steps or are what + the harness reported; ``total_steps`` counts its ``step`` events.""" + + basis: Basis + total_steps: int | None = None + partial: bool | None = None + includes_subagents: bool | None = None + by_actor: dict[str, UsageTotals] | None = None + by_model: dict[str, UsageTotals] | None = None + + +class Opaque(YatfModel): + """A provider payload kept byte for byte, such as a thinking signature, for replay.""" + + kind: OpaqueKind + value: str + provider: str | None = None + + +class ToolDef(YatfModel): + name: str + kind: ToolKind | None = None + server: str | None = None + description: str | None = None + input_schema: dict[str, Any] | None = None + + +class Event(YatfModel): + """The envelope every event carries. Its order is (``turn``, ``seq``), and ``id`` is ``.``.""" + + seq: int + id: str + type: str + turn: int + actor: str + observer: Observer + time: Time + step: str | None = None + attempt: int | None = None + is_copied_context: bool | None = None + derived_from: DerivedFrom | None = None + x: dict[str, Any] | None = None + + +class TurnStart(Event): + """Opens a turn, one per A2A task. It names who made the stream and declares the turn's actors.""" + + type: Literal["turn.start"] + spec_version: str + context_id: str + task_id: str + message_id: str | None = None + native_format: str + live: bool | None = None + adapter: AdapterInfo + usage_input_includes_cache: bool | None + actors: list[Actor] + + +class Message(Event): + type: Literal["message"] + role: Role + content: list[Part] + + +class FinalResponse(Event): + type: Literal["final_response"] + content: list[Part] + + +class TurnEnd(Event): + type: Literal["turn.end"] + state: TurnState + tool_call_count: int | None = None + final_metrics: FinalMetrics | None = None + + +class StepEvent(Event): + """One inference, dispatch or inbound message, under ATIF's step names; the content events that share its + ``step`` key belong to it.""" + + type: Literal["step"] + source: StepSource + llm_call_count: int | None = None + model_name: str | None = None + reasoning_effort: str | None = None + metrics: Metrics | None = None + stop_reason: str | None = None + provider_ids: dict[str, str] | None = None + first_token_at: str | None = None + sampling: dict[str, Any] | None = None + + +class Reasoning(Event): + type: Literal["reasoning"] + visibility: Visibility + text: str | None + opaque: list[Opaque] | None = None + + +class ToolCall(Event): + """A tool call; ``arguments`` is any JSON value, and ``arguments_raw`` the native string when it was one.""" + + type: Literal["tool_call"] + tool_call_id: str + function_name: str + arguments: Any + kind: ToolKind | None = None + server: str | None = None + executor: Executor | None = None + env_id: str | None = None + arguments_raw: str | None = None + + +class ToolResult(Event): + """A result answering any earlier call in the context, kept where it arrived.""" + + type: Literal["tool_result"] + source_call_id: str + status: ResultStatus + content: list[Part] + exit_code: int | None = None + + +class Tools(Event): + """The tools the agent can call from here on: the whole set, or ones added or removed.""" + + type: Literal["tools"] + mode: ToolsMode + tools: list[ToolDef] + + +class ActorDeclared(Event): + type: Literal["actor"] + declared: Actor + + +class ErrorEvent(Event): + type: Literal["error"] + error_type: ErrorType + message: str + code: str | None = None + fatal: bool | None = None + + +class Attempt(Event): + """A harness retry within the task; later events carry ``attempt`` equal to ``number``.""" + + type: Literal["attempt"] + number: int + reason: str | None = None + + +class Note(Event): + type: Literal["note"] + text: str + + +class ExtensionEvent(Event): + """A ``/`` type, such as an adapter's raw native record: readers keep it and may skip it.""" + + model_config = _OPEN + OPEN: ClassVar[bool] = True + type: Annotated[str, WithJsonSchema({"type": "string", "pattern": EXTENSION_TYPE.pattern})] + + +class UnknownEvent(Event): + """An event type this version doesn't define: readers keep it, producers may not write it.""" + + model_config = _OPEN + OPEN: ClassVar[bool] = True + + +#: The event types spec 1.0 defines, each by the ``type`` its model takes. +EVENT_MODELS: dict[str, type[Event]] = { + get_args(model.model_fields["type"].annotation)[0]: model + for model in (TurnStart, Message, FinalResponse, TurnEnd, StepEvent, Reasoning, ToolCall, ToolResult, Tools, + ActorDeclared, ErrorEvent, Attempt, Note) +} +CORE_TYPES = frozenset(EVENT_MODELS) + + +def is_extension_type(kind: str) -> bool: + """Whether ``kind`` names an extension type an adapter may write.""" + return bool(EXTENSION_TYPE.match(kind)) + + +def _event_tag(value: Any) -> str: + kind = value.get("type") if isinstance(value, dict) else getattr(value, "type", None) + if not isinstance(kind, str): + return "unknown" + if kind in EVENT_MODELS: + return kind + return "extension" if is_extension_type(kind) else "unknown" + + +AnyEvent = Annotated[ + Union[tuple(Annotated[model, Tag(kind)] for kind, model in EVENT_MODELS.items()) + + (Annotated[ExtensionEvent, Tag("extension")], Annotated[UnknownEvent, Tag("unknown"), _NOTHING])], + Discriminator(_event_tag), +] +_EVENT = TypeAdapter(AnyEvent) + + +def _finite(value: Any) -> None: + stack = [value] + while stack: + item = stack.pop() + if isinstance(item, float) and not math.isfinite(item): + raise YatfError(f"not a yatf/1 event: {item} isn't a JSON number") + if isinstance(item, dict): + stack.extend(item.values()) + elif isinstance(item, list): + stack.extend(item) + + +def parse_event(value: Any) -> Event: + """One event as its typed model; an unknown type parses as UnknownEvent and a namespaced one as ExtensionEvent. + A NaN or infinity anywhere in it is refused, unknown fields included, since JSON can't write one back.""" + _finite(value) + try: + return _EVENT.validate_python(value) + except ValidationError as exc: + raise YatfError(f"not a yatf/1 event: {exc}") from exc + + +def dump_event(event: Event) -> dict[str, Any]: + """The event as JSON values, with exactly the fields it was given, unknown ones included. Every field is a JSON + type already, so the strings stay as given, a lone surrogate included, for ``json.dumps`` to escape.""" + return event.model_dump(exclude_unset=True) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/reader.py b/packages/agentenv-protocol/src/agentenv_protocol/yatf/reader.py new file mode 100644 index 000000000..c70d39f1f --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/reader.py @@ -0,0 +1,134 @@ +"""Reading a yatf/1 stream: parse a JSON array or JSONL, order it by (turn, seq), fold its events into ATIF-style steps +and pair each tool call with its results.""" +from __future__ import annotations + +import json +from dataclasses import dataclass +from importlib.resources import files +from typing import Any, Iterable, Mapping + +from .models import Event, StepEvent, ToolCall, ToolResult, YatfError, dump_event, parse_event + +#: The design's worked examples, checked in as the spec's canonical fixtures. +EXAMPLES = ("coding", "multi_agent", "computer_use") + + +def _strict_json(constant: str) -> Any: + raise ValueError(f"{constant} isn't JSON") + + +def parse_events(data: str | bytes | Iterable[Mapping[str, Any]]) -> list[Event]: + """A stream's events, from a JSON array (as on the wire), JSONL (as stored) or already-parsed objects. JSON is + read strictly: UTF-8, with no NaN or Infinity.""" + if isinstance(data, (bytes, bytearray)): + try: + data = bytes(data).decode("utf-8") + except UnicodeDecodeError as exc: + raise YatfError(f"not UTF-8: {exc}") from exc + if isinstance(data, str): + text = data.lstrip("") + if text.lstrip().startswith("["): + try: + items = json.loads(text, parse_constant=_strict_json) + except ValueError as exc: + raise YatfError(f"not a JSON array: {exc}") from exc + else: + items = [] + for number, line in enumerate(text.splitlines(), 1): + if not line.strip(): + continue + try: + items.append(json.loads(line, parse_constant=_strict_json)) + except ValueError as exc: + raise YatfError(f"line {number} isn't JSON: {exc}") from exc + else: + items = list(data) + if not isinstance(items, list): + raise YatfError("a stream is a JSON array or JSONL of events") + events = [] + for position, item in enumerate(items): + try: + events.append(parse_event(item)) + except YatfError as exc: + raise YatfError(f"event {position}: {exc}") from exc + return events + + +def dump_events(events: Iterable[Event], *, jsonl: bool = True) -> str: + """Events as JSONL, one per line, or as one JSON array, ASCII-escaped as the SDK writes native logs, so any text + an event holds encodes.""" + dumped = [dump_event(event) for event in events] + if jsonl: + return "".join(json.dumps(item, separators=(",", ":"), allow_nan=False) + "\n" for item in dumped) + return json.dumps(dumped, separators=(",", ":"), allow_nan=False) + + +def ordered(events: Iterable[Event]) -> list[Event]: + """Events in stream order, (turn, seq), never by timestamp.""" + return sorted(events, key=lambda event: (event.turn, event.seq)) + + +def load_example(name: str) -> list[Event]: + """One of the spec's worked examples, by name (``EXAMPLES``).""" + if name not in EXAMPLES: + raise YatfError(f"no example {name!r}: there are {', '.join(EXAMPLES)}") + return parse_events(files(__package__).joinpath("examples", f"{name}.json").read_text(encoding="utf-8")) + + +@dataclass(frozen=True) +class ToolPair: + """A tool call and the results that answer it, in stream order; a call with no result has none.""" + + call: ToolCall + results: tuple[ToolResult, ...] + + +def pair_tool_calls(events: Iterable[Event]) -> list[ToolPair]: + """Every tool call in the stream with its results. A result whose call isn't in the stream is left out.""" + calls: dict[str, ToolCall] = {} + results: dict[str, list[ToolResult]] = {} + for event in ordered(events): + if isinstance(event, ToolCall): + calls.setdefault(event.tool_call_id, event) + results.setdefault(event.tool_call_id, []) + elif isinstance(event, ToolResult) and event.source_call_id in calls: + results[event.source_call_id].append(event) + return [ToolPair(call, tuple(results[call_id])) for call_id, call in calls.items()] + + +@dataclass(frozen=True) +class FoldedStep: + """One ATIF-style step: the content events that share a turn and a ``step`` key, its ``step`` event (None for an + inbound message), and the results that answer its calls, regrouped from wherever they arrived.""" + + turn: int + key: str + actor: str + step: StepEvent | None + events: tuple[Event, ...] + results: tuple[ToolResult, ...] + + +def fold_steps(events: Iterable[Event]) -> list[FoldedStep]: + """The stream's steps, in the order each first appears.""" + events = ordered(events) + groups: dict[tuple[int, str], dict[str, Any]] = {} + call_step: dict[str, tuple[int, str]] = {} + for event in events: + if event.step is None or isinstance(event, ToolResult): + continue + group = groups.setdefault((event.turn, event.step), {"actor": event.actor, "step": None, "events": []}) + if isinstance(event, StepEvent): + group["step"] = event + group["actor"] = event.actor + else: + group["events"].append(event) + if isinstance(event, ToolCall): + call_step.setdefault(event.tool_call_id, (event.turn, event.step)) + results: dict[tuple[int, str], list[ToolResult]] = {} + for event in events: + if isinstance(event, ToolResult) and event.source_call_id in call_step: + results.setdefault(call_step[event.source_call_id], []).append(event) + return [FoldedStep(turn=turn, key=key, actor=group["actor"], step=group["step"], events=tuple(group["events"]), + results=tuple(results.get((turn, key), ()))) + for (turn, key), group in groups.items()] diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/runner.py b/packages/agentenv-protocol/src/agentenv_protocol/yatf/runner.py new file mode 100644 index 000000000..bdbed6f14 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/runner.py @@ -0,0 +1,390 @@ +"""Running an adapter: feed one A2A context's records through it, a turn at a time. The run writes each turn's frame and +hands every handler the YatfTurn it writes through. The SDK runs it live and the round-trip kit replays it offline, so +the same records, fed in the same order, make the same events.""" +from __future__ import annotations + +import json +from dataclasses import dataclass +from typing import Any, Iterable, Mapping, Sequence + +from pydantic import ValidationError + +from .adapter import Adapter, AdapterSpec +from .models import ( + EVENT_MODELS, + SPEC_VERSION, + Actor, + ActorDeclared, + AdapterInfo, + Attempt, + DerivedFrom, + ErrorEvent, + Event, + ExtensionEvent, + FinalMetrics, + FinalResponse, + Message, + Metrics, + Note, + Opaque, + Part, + Reasoning, + StepEvent, + Time, + ToolCall, + ToolDef, + ToolResult, + Tools, + TurnEnd, + TurnStart, + YatfError, + dump_event, + is_extension_type, +) + +#: The step key of a turn's inbound message, ``in-``. +INBOUND_STEP = "in-{turn}" +_ENVELOPE = frozenset(Event.model_fields) +_TYPE_OF = {model: kind for kind, model in EVENT_MODELS.items()} +_CURRENT: Any = object() + + +@dataclass(frozen=True, kw_only=True) +class TurnContext: + """What the SDK knows of a turn from A2A, written into its frame. ``actor`` is the agent's own actor id, the + default for every event; ``actors`` defaults to the agent and, with an ``inbound`` message, its sender.""" + + index: int + context_id: str + task_id: str + message_id: str | None = None + actor: str = "agent" + actors: Sequence[Actor | Mapping[str, Any]] = () + inbound: Sequence[Part | Mapping[str, Any]] | None = None + inbound_actor: str = "caller" + started_at: str | None = None + live: bool = True + + +def _time(value: Any) -> Time: + if value is None or isinstance(value, str): + return Time(at=value) + return value if isinstance(value, Time) else Time.model_validate(value) + + +def _content(content: Iterable[Any] | None, text: str | None) -> list[Any]: + if (content is None) == (text is None): + raise YatfError("give either content or text") + return [{"type": "text", "text": text}] if text is not None else list(content) + + +class YatfTurn: + """What a handler writes one turn's events through. It stamps the envelope (``seq``, ``id``, ``turn``, + ``observer``, the agent's actor, the attempt, ``derived_from``) and keeps each event as JSON text, refusing one + that isn't JSON as it's written, and any once the turn has closed. Not thread-safe: records are fed one at a + time.""" + + def __init__(self, context: TurnContext, spec: AdapterSpec, out: list[str] | None = None) -> None: + self.context = context + self.spec = spec + #: The record being handled: capture it to emit an event that comes from it later. + self.source: DerivedFrom | None = None + self._out = [] if out is None else out + self._first = len(self._out) + self._last: int | None = None + self._calls = 0 + self._attempt = 1 + self._final_metrics: FinalMetrics | None = None + + @property + def index(self) -> int: + return self.context.index + + @property + def events(self) -> list[dict[str, Any]]: + """This turn's events so far, and no later turn's, as fresh copies.""" + return [json.loads(text) for text in self._out[self._first:self._last]] + + def message(self, *, role: str, step: str | None = None, content: Iterable[Any] | None = None, + text: str | None = None, time: Any = None, actor: str | None = None, derived_from: Any = _CURRENT, + x: Mapping[str, Any] | None = None, is_copied_context: bool | None = None) -> Message: + return self._emit(Message, {"step": step, "role": role, "content": _content(content, text)}, + time=time, actor=actor, derived_from=derived_from, x=x, + is_copied_context=is_copied_context) + + def reasoning(self, *, visibility: str, step: str | None = None, text: str | None = None, + opaque: Iterable[Opaque | Mapping[str, Any]] | None = None, time: Any = None, + actor: str | None = None, derived_from: Any = _CURRENT, + x: Mapping[str, Any] | None = None, is_copied_context: bool | None = None) -> Reasoning: + return self._emit(Reasoning, {"step": step, "visibility": visibility, "text": text, + "opaque": None if opaque is None else list(opaque)}, + time=time, actor=actor, derived_from=derived_from, x=x, + is_copied_context=is_copied_context) + + def tool_call(self, *, tool_call_id: str, function_name: str, arguments: Any, step: str | None = None, + kind: str | None = None, server: str | None = None, executor: str | None = None, + env_id: str | None = None, arguments_raw: str | None = None, time: Any = None, + actor: str | None = None, derived_from: Any = _CURRENT, + x: Mapping[str, Any] | None = None, is_copied_context: bool | None = None) -> ToolCall: + return self._emit(ToolCall, {"step": step, "tool_call_id": tool_call_id, "function_name": function_name, + "arguments": arguments, "kind": kind, "server": server, "executor": executor, + "env_id": env_id, "arguments_raw": arguments_raw}, + time=time, actor=actor, derived_from=derived_from, x=x, + is_copied_context=is_copied_context) + + def tool_result(self, *, source_call_id: str, status: str = "ok", content: Iterable[Any] | None = None, + text: str | None = None, exit_code: int | None = None, step: str | None = None, time: Any = None, + actor: str | None = None, derived_from: Any = _CURRENT, + x: Mapping[str, Any] | None = None, is_copied_context: bool | None = None) -> ToolResult: + return self._emit(ToolResult, {"step": step, "source_call_id": source_call_id, "status": status, + "content": _content(content, text), "exit_code": exit_code}, + time=time, actor=actor, derived_from=derived_from, x=x, + is_copied_context=is_copied_context) + + def step(self, *, key: str, source: str = "agent", llm_call_count: int | None = 1, model_name: str | None = None, + reasoning_effort: str | None = None, metrics: Metrics | Mapping[str, Any] | None = None, + stop_reason: str | None = None, provider_ids: Mapping[str, str] | None = None, + first_token_at: str | None = None, sampling: Mapping[str, Any] | None = None, time: Any = None, + actor: str | None = None, derived_from: Any = _CURRENT, + x: Mapping[str, Any] | None = None, is_copied_context: bool | None = None) -> StepEvent: + return self._emit(StepEvent, {"step": key, "source": source, "llm_call_count": llm_call_count, + "model_name": model_name, "reasoning_effort": reasoning_effort, + "metrics": metrics, "stop_reason": stop_reason, + "provider_ids": None if provider_ids is None else dict(provider_ids), + "first_token_at": first_token_at, + "sampling": None if sampling is None else dict(sampling)}, + time=time, actor=actor, derived_from=derived_from, x=x, + is_copied_context=is_copied_context) + + def tools(self, tools: Iterable[ToolDef | Mapping[str, Any]], *, mode: str = "replace", time: Any = None, + actor: str | None = None, derived_from: Any = _CURRENT, x: Mapping[str, Any] | None = None, + is_copied_context: bool | None = None) -> Tools: + return self._emit(Tools, {"mode": mode, "tools": list(tools)}, + time=time, actor=actor, derived_from=derived_from, x=x, + is_copied_context=is_copied_context) + + def declare(self, declared: Actor | Mapping[str, Any], *, time: Any = None, actor: str | None = None, + derived_from: Any = _CURRENT, x: Mapping[str, Any] | None = None, + is_copied_context: bool | None = None) -> ActorDeclared: + """Declare an actor that appears mid-turn, such as a sub-agent, before any event names it.""" + return self._emit(ActorDeclared, {"declared": declared}, + time=time, actor=actor, derived_from=derived_from, x=x, + is_copied_context=is_copied_context) + + def error(self, *, message: str, error_type: str = "agent_error", code: str | None = None, + fatal: bool | None = None, step: str | None = None, time: Any = None, actor: str | None = None, + derived_from: Any = _CURRENT, x: Mapping[str, Any] | None = None, + is_copied_context: bool | None = None) -> ErrorEvent: + return self._emit(ErrorEvent, {"step": step, "error_type": error_type, "message": message, "code": code, + "fatal": fatal}, + time=time, actor=actor, derived_from=derived_from, x=x, + is_copied_context=is_copied_context) + + def attempt(self, number: int, *, reason: str | None = None, time: Any = None, actor: str | None = None, + derived_from: Any = _CURRENT, x: Mapping[str, Any] | None = None, + is_copied_context: bool | None = None) -> Attempt: + """A harness retry within the task: this event and every later one carry ``attempt`` = ``number``.""" + self._attempt = number + return self._emit(Attempt, {"number": number, "reason": reason}, + time=time, actor=actor, derived_from=derived_from, x=x, + is_copied_context=is_copied_context) + + def note(self, text: str, *, time: Any = None, actor: str | None = None, derived_from: Any = _CURRENT, + x: Mapping[str, Any] | None = None, is_copied_context: bool | None = None) -> Note: + return self._emit(Note, {"text": text}, time=time, actor=actor, derived_from=derived_from, x=x, + is_copied_context=is_copied_context) + + def raw(self, record: Any, *, time: Any = None, actor: str | None = None, derived_from: Any = _CURRENT, + is_copied_context: bool | None = None) -> ExtensionEvent: + """A native record kept whole, as ``/raw``.""" + return self.extension(f"{self.spec.namespace}/raw", {"record": record}, time=time, actor=actor, + derived_from=derived_from, is_copied_context=is_copied_context) + + def extension(self, kind: str, body: Mapping[str, Any], *, time: Any = None, actor: str | None = None, + derived_from: Any = _CURRENT, x: Mapping[str, Any] | None = None, + is_copied_context: bool | None = None) -> ExtensionEvent: + """An event of the ``/`` type ``kind``, with every key of ``body`` beside the envelope.""" + if not is_extension_type(kind): + raise YatfError(f"{kind!r} isn't an extension type: /, outside the yatf namespace") + if clash := sorted(_ENVELOPE & set(body)): + raise YatfError(f"an extension body can't set envelope fields: {', '.join(clash)}") + return self._emit(ExtensionEvent, {**body, "type": kind}, time=time, actor=actor, derived_from=derived_from, + x=x, is_copied_context=is_copied_context) + + def final_metrics(self, metrics: FinalMetrics | Mapping[str, Any]) -> None: + """The turn's totals, written into ``turn.end``.""" + try: + self._final_metrics = (metrics if isinstance(metrics, FinalMetrics) + else FinalMetrics.model_validate(metrics)) + except ValidationError as exc: + raise YatfError(f"final_metrics: {exc}") from exc + + def _emit(self, model: type[Event], body: dict[str, Any], *, time: Any = None, actor: str | None = None, + derived_from: Any = _CURRENT, x: Mapping[str, Any] | None = None, + is_copied_context: bool | None = None) -> Any: + """Write one event. A None in ``body`` leaves an optional field out and writes null for a required one or for + an extension's own key, so whether a null is written follows the model.""" + event_type = body.pop("type", None) or _TYPE_OF[model] + if self._last is not None: + raise YatfError(f"turn {self.index} is closed: write through the turn the handler is given") + source = self.source if derived_from is _CURRENT else derived_from + seq = len(self._out) - self._first + envelope: dict[str, Any] = {"seq": seq, "id": f"{self.index}.{seq}", "type": event_type, "turn": self.index, + "actor": actor or self.context.actor, "observer": "agent", "time": _time(time)} + if self._attempt > 1: + envelope["attempt"] = self._attempt + if source is not None: + envelope["derived_from"] = source + if x is not None: + envelope["x"] = dict(x) + if is_copied_context is not None: + envelope["is_copied_context"] = is_copied_context + fields = {key: value for key, value in body.items() + if value is not None or key not in model.model_fields or model.model_fields[key].is_required()} + try: + event = model(**envelope, **fields) + text = json.dumps(dump_event(event), separators=(",", ":"), allow_nan=False) + except ValidationError as exc: + raise YatfError(f"{event_type} event: {exc}") from exc + except (TypeError, ValueError) as exc: + raise YatfError(f"{event_type} event isn't JSON: {exc}") from exc + self._out.append(text) + self._calls += event_type == "tool_call" + return event + + def _start(self) -> None: + context = self.context + actors = list(context.actors) or [Actor(id=context.actor, kind="agent")] + ( + [Actor(id=context.inbound_actor, kind="framework")] if context.inbound is not None else []) + adapter = AdapterInfo(name=self.spec.name, version=self.spec.version, lossy=list(self.spec.lossy) or None) + self._emit(TurnStart, {"spec_version": SPEC_VERSION, "context_id": context.context_id, + "task_id": context.task_id, "message_id": context.message_id, + "native_format": self.spec.native_format, "live": context.live, "adapter": adapter, + "usage_input_includes_cache": self.spec.usage_input_includes_cache, "actors": actors}, + time=context.started_at, derived_from=None) + if context.inbound is not None: + self._emit(Message, {"step": INBOUND_STEP.format(turn=self.index), "role": "user", + "content": list(context.inbound)}, + time=context.started_at, actor=context.inbound_actor, derived_from=None) + + def _end(self, state: str, final: Sequence[Any] | None, ended_at: str | None) -> None: + if final is not None: + self._emit(FinalResponse, {"content": list(final)}, time=ended_at, derived_from=None) + self._emit(TurnEnd, {"state": state, "tool_call_count": self._calls, "final_metrics": self._final_metrics}, + time=ended_at, derived_from=None) + self._last = len(self._out) + + +@dataclass(frozen=True) +class Fed: + """One record as it was fed: a native record, or a record of the aux file ``aux``.""" + + record: Any + aux: str | None = None + + +@dataclass(frozen=True, kw_only=True) +class RecordedTurn: + """A stored turn: its context, its records in the order they were fed, and how it ended.""" + + context: TurnContext + records: Sequence[Fed] = () + state: str = "completed" + final: Sequence[Part | Mapping[str, Any]] | None = None + ended_at: str | None = None + + +class AdapterRun: + """One A2A context's conversion. Each call returns the events it emitted, so a live reader sees them as they come, + and ``events`` holds them all; every read is a fresh copy, so a caller can't rewrite history.""" + + def __init__(self, adapter: type[Adapter]) -> None: + spec = vars(adapter).get("spec") + if not isinstance(spec, AdapterSpec): + raise YatfError(f"{adapter.__name__} isn't declared with @yatf_adapter") + self._cls = adapter + self._spec = spec + self._adapter: Adapter | None = None + self._turn: YatfTurn | None = None + self._events: list[str] = [] + self._sent = 0 + self._native = 0 + self._aux: dict[str, int] = {} + + @property + def events(self) -> list[dict[str, Any]]: + return [json.loads(text) for text in self._events] + + def start_turn(self, context: TurnContext) -> list[dict[str, Any]]: + """Open a turn: write ``turn.start`` and the inbound message. The context's first turn creates the adapter.""" + if self._turn is not None: + raise YatfError(f"turn {self._turn.index} is still open") + turn = YatfTurn(context, self._spec, self._events) + self._turn, self._native, self._aux = turn, 0, {} + turn._start() + if self._adapter is None: + self._adapter = self._cls(turn) + return self._page() + + def native(self, record: Any) -> list[dict[str, Any]]: + """Feed the turn's next native record.""" + turn = self._open() + source, self._native = DerivedFrom(index=self._native), self._native + 1 + self._handle(turn, source, self._spec.handler(None, record) or "unmatched", record) + return self._page() + + def aux(self, name: str, record: Any) -> list[dict[str, Any]]: + """Feed the turn's next record of aux file ``name``.""" + turn = self._open() + if name not in self._spec.aux: + raise YatfError(f"{self._cls.__name__} declares no aux file {name!r}") + index = self._aux.get(name, 0) + self._aux[name] = index + 1 + method = self._spec.handler(name, record) + if method is not None: + self._handle(turn, DerivedFrom(index=index, aux=name), method, record) + return self._page() + + def end_turn(self, *, state: str = "completed", final: Sequence[Part | Mapping[str, Any]] | None = None, + ended_at: str | None = None) -> list[dict[str, Any]]: + """Close the turn: run the adapter's ``@finish`` method, then write ``final_response`` and ``turn.end``. The + frame is written even when ``@finish`` raises, and the error is raised after it.""" + turn = self._open() + try: + if self._spec.finish is not None: + getattr(self._adapter, self._spec.finish)(turn) + finally: + turn._end(state, final, ended_at) + self._turn = None + page = self._page() + return page + + def _open(self) -> YatfTurn: + if self._turn is None: + raise YatfError("no turn is open: call start_turn first") + return self._turn + + def _handle(self, turn: YatfTurn, source: DerivedFrom, method: str, record: Any) -> None: + turn.source = source + try: + getattr(self._adapter, method)(record, turn) + finally: + turn.source = None + + def _page(self) -> list[dict[str, Any]]: + page, self._sent = self._events[self._sent:], len(self._events) + return [json.loads(text) for text in page] + + +def replay(adapter: type[Adapter], turns: Iterable[RecordedTurn]) -> list[dict[str, Any]]: + """A context's stored turns run through ``adapter`` again, as the agent ran them live.""" + run = AdapterRun(adapter) + for turn in turns: + run.start_turn(turn.context) + for fed in turn.records: + if fed.aux is None: + run.native(fed.record) + else: + run.aux(fed.aux, fed.record) + run.end_turn(state=turn.state, final=turn.final, ended_at=turn.ended_at) + return run.events diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/schema.py b/packages/agentenv-protocol/src/agentenv_protocol/yatf/schema.py new file mode 100644 index 000000000..41dc126c8 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/schema.py @@ -0,0 +1,32 @@ +"""The strict JSON schema of one yatf/1 event, for producers in other languages: generated from the models, with every +field and type this version doesn't define forbidden, and checked in as ``yatf-1.schema.json``: + + python -m agentenv_protocol.yatf schema > packages/agentenv-protocol/src/agentenv_protocol/yatf/yatf-1.schema.json +""" +from __future__ import annotations + +import json +from importlib.resources import files +from typing import Any + +from pydantic import TypeAdapter + +from .models import FORMAT, SPEC_VERSION, AnyEvent + +SCHEMA_FILE = "yatf-1.schema.json" + + +def json_schema() -> dict[str, Any]: + """The schema of one event, generated from the models.""" + return {"$schema": "https://json-schema.org/draft/2020-12/schema", + "title": f"{FORMAT} event, spec {SPEC_VERSION}", **TypeAdapter(AnyEvent).json_schema()} + + +def schema_text() -> str: + """The schema as it's checked in.""" + return json.dumps(json_schema(), indent=2, sort_keys=True) + "\n" + + +def load_schema() -> dict[str, Any]: + """The checked-in schema.""" + return json.loads(files(__package__).joinpath(SCHEMA_FILE).read_text(encoding="utf-8")) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/yatf-1.schema.json b/packages/agentenv-protocol/src/agentenv_protocol/yatf/yatf-1.schema.json new file mode 100644 index 000000000..7e25f4207 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/yatf-1.schema.json @@ -0,0 +1,3353 @@ +{ + "$defs": { + "Actor": { + "additionalProperties": false, + "description": "A participant, declared in ``turn.start`` or an ``actor`` event before any event names it. A sub-agent carries\nits ``parent`` actor and the ``tool_call_id`` that ``spawned_by`` it.", + "properties": { + "a2a_agent_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "A2A Agent Id" + }, + "id": { + "title": "Id", + "type": "string" + }, + "kind": { + "enum": [ + "agent", + "subagent", + "user", + "user_sim", + "human", + "peer", + "trigger_executor", + "env", + "judge", + "framework" + ], + "title": "Kind", + "type": "string" + }, + "model_name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Model Name" + }, + "model_source": { + "anyOf": [ + { + "enum": [ + "configured", + "reported", + "unknown" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Model Source" + }, + "name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Name" + }, + "parent": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Parent" + }, + "participant": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Participant" + }, + "role": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Role" + }, + "spawned_by": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Spawned By" + }, + "stream": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Stream" + }, + "version": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Version" + } + }, + "required": [ + "id", + "kind" + ], + "title": "Actor", + "type": "object" + }, + "ActorDeclared": { + "additionalProperties": false, + "properties": { + "actor": { + "title": "Actor", + "type": "string" + }, + "attempt": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Attempt" + }, + "declared": { + "$ref": "#/$defs/Actor" + }, + "derived_from": { + "anyOf": [ + { + "$ref": "#/$defs/DerivedFrom" + }, + { + "type": "null" + } + ], + "default": null + }, + "id": { + "title": "Id", + "type": "string" + }, + "is_copied_context": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Is Copied Context" + }, + "observer": { + "enum": [ + "agent", + "gateway", + "browser", + "framework" + ], + "title": "Observer", + "type": "string" + }, + "seq": { + "title": "Seq", + "type": "integer" + }, + "step": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Step" + }, + "time": { + "$ref": "#/$defs/Time" + }, + "turn": { + "title": "Turn", + "type": "integer" + }, + "type": { + "const": "actor", + "title": "Type", + "type": "string" + }, + "x": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "default": null, + "title": "X" + } + }, + "required": [ + "seq", + "id", + "type", + "turn", + "actor", + "observer", + "time", + "declared" + ], + "title": "ActorDeclared", + "type": "object" + }, + "AdapterInfo": { + "additionalProperties": false, + "properties": { + "lossy": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Lossy" + }, + "name": { + "title": "Name", + "type": "string" + }, + "version": { + "title": "Version", + "type": "string" + } + }, + "required": [ + "name", + "version" + ], + "title": "AdapterInfo", + "type": "object" + }, + "Attempt": { + "additionalProperties": false, + "description": "A harness retry within the task; later events carry ``attempt`` equal to ``number``.", + "properties": { + "actor": { + "title": "Actor", + "type": "string" + }, + "attempt": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Attempt" + }, + "derived_from": { + "anyOf": [ + { + "$ref": "#/$defs/DerivedFrom" + }, + { + "type": "null" + } + ], + "default": null + }, + "id": { + "title": "Id", + "type": "string" + }, + "is_copied_context": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Is Copied Context" + }, + "number": { + "title": "Number", + "type": "integer" + }, + "observer": { + "enum": [ + "agent", + "gateway", + "browser", + "framework" + ], + "title": "Observer", + "type": "string" + }, + "reason": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Reason" + }, + "seq": { + "title": "Seq", + "type": "integer" + }, + "step": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Step" + }, + "time": { + "$ref": "#/$defs/Time" + }, + "turn": { + "title": "Turn", + "type": "integer" + }, + "type": { + "const": "attempt", + "title": "Type", + "type": "string" + }, + "x": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "default": null, + "title": "X" + } + }, + "required": [ + "seq", + "id", + "type", + "turn", + "actor", + "observer", + "time", + "number" + ], + "title": "Attempt", + "type": "object" + }, + "DataPart": { + "additionalProperties": false, + "description": "A structured A2A part, such as a harness's tool-call count or a structured output.", + "properties": { + "data": { + "title": "Data" + }, + "origin": { + "anyOf": [ + { + "$ref": "#/$defs/Origin" + }, + { + "type": "null" + } + ], + "default": null + }, + "type": { + "const": "data", + "title": "Type", + "type": "string" + } + }, + "required": [ + "type", + "data" + ], + "title": "DataPart", + "type": "object" + }, + "DerivedFrom": { + "additionalProperties": false, + "description": "The record an event came from: its position in the turn's stored native log, or in the named aux log.", + "properties": { + "aux": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Aux" + }, + "index": { + "title": "Index", + "type": "integer" + } + }, + "required": [ + "index" + ], + "title": "DerivedFrom", + "type": "object" + }, + "ElidedPart": { + "additionalProperties": false, + "properties": { + "elision": { + "$ref": "#/$defs/Elision" + }, + "media_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Media Type" + }, + "type": { + "const": "elided", + "title": "Type", + "type": "string" + } + }, + "required": [ + "type", + "elision" + ], + "title": "ElidedPart", + "type": "object" + }, + "Elision": { + "additionalProperties": false, + "description": "Why content is missing, so elided never reads as empty. A redacted secret has its length and no hash.", + "properties": { + "bytes": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Bytes" + }, + "reason": { + "enum": [ + "truncated", + "redacted", + "digest_only", + "evicted", + "not_captured", + "not_requested" + ], + "title": "Reason", + "type": "string" + }, + "sha256": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Sha256" + } + }, + "required": [ + "reason" + ], + "title": "Elision", + "type": "object" + }, + "ErrorEvent": { + "additionalProperties": false, + "properties": { + "actor": { + "title": "Actor", + "type": "string" + }, + "attempt": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Attempt" + }, + "code": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Code" + }, + "derived_from": { + "anyOf": [ + { + "$ref": "#/$defs/DerivedFrom" + }, + { + "type": "null" + } + ], + "default": null + }, + "error_type": { + "enum": [ + "agent_error", + "infra_error" + ], + "title": "Error Type", + "type": "string" + }, + "fatal": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Fatal" + }, + "id": { + "title": "Id", + "type": "string" + }, + "is_copied_context": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Is Copied Context" + }, + "message": { + "title": "Message", + "type": "string" + }, + "observer": { + "enum": [ + "agent", + "gateway", + "browser", + "framework" + ], + "title": "Observer", + "type": "string" + }, + "seq": { + "title": "Seq", + "type": "integer" + }, + "step": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Step" + }, + "time": { + "$ref": "#/$defs/Time" + }, + "turn": { + "title": "Turn", + "type": "integer" + }, + "type": { + "const": "error", + "title": "Type", + "type": "string" + }, + "x": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "default": null, + "title": "X" + } + }, + "required": [ + "seq", + "id", + "type", + "turn", + "actor", + "observer", + "time", + "error_type", + "message" + ], + "title": "ErrorEvent", + "type": "object" + }, + "ExtensionEvent": { + "additionalProperties": true, + "description": "A ``/`` type, such as an adapter's raw native record: readers keep it and may skip it.", + "properties": { + "actor": { + "title": "Actor", + "type": "string" + }, + "attempt": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Attempt" + }, + "derived_from": { + "anyOf": [ + { + "$ref": "#/$defs/DerivedFrom" + }, + { + "type": "null" + } + ], + "default": null + }, + "id": { + "title": "Id", + "type": "string" + }, + "is_copied_context": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Is Copied Context" + }, + "observer": { + "enum": [ + "agent", + "gateway", + "browser", + "framework" + ], + "title": "Observer", + "type": "string" + }, + "seq": { + "title": "Seq", + "type": "integer" + }, + "step": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Step" + }, + "time": { + "$ref": "#/$defs/Time" + }, + "turn": { + "title": "Turn", + "type": "integer" + }, + "type": { + "pattern": "^(?!yatf/)[a-z0-9][a-z0-9._-]*/[a-z0-9][a-z0-9._-]*$", + "title": "Type", + "type": "string" + }, + "x": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "default": null, + "title": "X" + } + }, + "required": [ + "seq", + "id", + "type", + "turn", + "actor", + "observer", + "time" + ], + "title": "ExtensionEvent", + "type": "object" + }, + "FinalMetrics": { + "additionalProperties": false, + "description": "A turn's totals under ATIF's FinalMetrics names. ``basis`` says whether they sum the turn's steps or are what\nthe harness reported; ``total_steps`` counts its ``step`` events.", + "properties": { + "basis": { + "enum": [ + "steps", + "reported" + ], + "title": "Basis", + "type": "string" + }, + "by_actor": { + "anyOf": [ + { + "additionalProperties": { + "$ref": "#/$defs/UsageTotals" + }, + "type": "object" + }, + { + "type": "null" + } + ], + "default": null, + "title": "By Actor" + }, + "by_model": { + "anyOf": [ + { + "additionalProperties": { + "$ref": "#/$defs/UsageTotals" + }, + "type": "object" + }, + { + "type": "null" + } + ], + "default": null, + "title": "By Model" + }, + "cost_source": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Cost Source" + }, + "cost_status": { + "anyOf": [ + { + "enum": [ + "reported", + "priced", + "unpriced" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Cost Status" + }, + "includes_subagents": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Includes Subagents" + }, + "partial": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Partial" + }, + "total_cache_write_tokens": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Total Cache Write Tokens" + }, + "total_cached_tokens": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Total Cached Tokens" + }, + "total_completion_tokens": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Total Completion Tokens" + }, + "total_cost_usd": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "number" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Total Cost Usd" + }, + "total_prompt_tokens": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Total Prompt Tokens" + }, + "total_reasoning_tokens": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Total Reasoning Tokens" + }, + "total_steps": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Total Steps" + } + }, + "required": [ + "basis" + ], + "title": "FinalMetrics", + "type": "object" + }, + "FinalResponse": { + "additionalProperties": false, + "properties": { + "actor": { + "title": "Actor", + "type": "string" + }, + "attempt": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Attempt" + }, + "content": { + "items": { + "oneOf": [ + { + "$ref": "#/$defs/TextPart" + }, + { + "$ref": "#/$defs/RefPart" + }, + { + "$ref": "#/$defs/MediaPart" + }, + { + "$ref": "#/$defs/DataPart" + }, + { + "$ref": "#/$defs/ElidedPart" + }, + { + "description": "A type this version doesn't define: readers keep it, producers may not write it.", + "not": {} + } + ] + }, + "title": "Content", + "type": "array" + }, + "derived_from": { + "anyOf": [ + { + "$ref": "#/$defs/DerivedFrom" + }, + { + "type": "null" + } + ], + "default": null + }, + "id": { + "title": "Id", + "type": "string" + }, + "is_copied_context": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Is Copied Context" + }, + "observer": { + "enum": [ + "agent", + "gateway", + "browser", + "framework" + ], + "title": "Observer", + "type": "string" + }, + "seq": { + "title": "Seq", + "type": "integer" + }, + "step": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Step" + }, + "time": { + "$ref": "#/$defs/Time" + }, + "turn": { + "title": "Turn", + "type": "integer" + }, + "type": { + "const": "final_response", + "title": "Type", + "type": "string" + }, + "x": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "default": null, + "title": "X" + } + }, + "required": [ + "seq", + "id", + "type", + "turn", + "actor", + "observer", + "time", + "content" + ], + "title": "FinalResponse", + "type": "object" + }, + "MediaPart": { + "additionalProperties": false, + "properties": { + "origin": { + "anyOf": [ + { + "$ref": "#/$defs/Origin" + }, + { + "type": "null" + } + ], + "default": null + }, + "purpose": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Purpose" + }, + "source": { + "$ref": "#/$defs/Source" + }, + "type": { + "enum": [ + "image", + "audio", + "video", + "document", + "file" + ], + "title": "Type", + "type": "string" + } + }, + "required": [ + "type", + "source" + ], + "title": "MediaPart", + "type": "object" + }, + "Message": { + "additionalProperties": false, + "properties": { + "actor": { + "title": "Actor", + "type": "string" + }, + "attempt": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Attempt" + }, + "content": { + "items": { + "oneOf": [ + { + "$ref": "#/$defs/TextPart" + }, + { + "$ref": "#/$defs/RefPart" + }, + { + "$ref": "#/$defs/MediaPart" + }, + { + "$ref": "#/$defs/DataPart" + }, + { + "$ref": "#/$defs/ElidedPart" + }, + { + "description": "A type this version doesn't define: readers keep it, producers may not write it.", + "not": {} + } + ] + }, + "title": "Content", + "type": "array" + }, + "derived_from": { + "anyOf": [ + { + "$ref": "#/$defs/DerivedFrom" + }, + { + "type": "null" + } + ], + "default": null + }, + "id": { + "title": "Id", + "type": "string" + }, + "is_copied_context": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Is Copied Context" + }, + "observer": { + "enum": [ + "agent", + "gateway", + "browser", + "framework" + ], + "title": "Observer", + "type": "string" + }, + "role": { + "enum": [ + "user", + "assistant", + "system", + "developer" + ], + "title": "Role", + "type": "string" + }, + "seq": { + "title": "Seq", + "type": "integer" + }, + "step": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Step" + }, + "time": { + "$ref": "#/$defs/Time" + }, + "turn": { + "title": "Turn", + "type": "integer" + }, + "type": { + "const": "message", + "title": "Type", + "type": "string" + }, + "x": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "default": null, + "title": "X" + } + }, + "required": [ + "seq", + "id", + "type", + "turn", + "actor", + "observer", + "time", + "role", + "content" + ], + "title": "Message", + "type": "object" + }, + "Metrics": { + "additionalProperties": false, + "description": "One step's usage, inclusive as in ATIF: ``prompt_tokens`` counts cache reads and writes, ``completion_tokens``\ncounts reasoning. An unknown count is null or absent, never 0; ``raw`` keeps the native counters.", + "properties": { + "cache_write_tokens": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Cache Write Tokens" + }, + "cached_tokens": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Cached Tokens" + }, + "completion_tokens": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Completion Tokens" + }, + "cost_source": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Cost Source" + }, + "cost_status": { + "anyOf": [ + { + "enum": [ + "reported", + "priced", + "unpriced" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Cost Status" + }, + "cost_usd": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "number" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Cost Usd" + }, + "prompt_tokens": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Prompt Tokens" + }, + "raw": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Raw" + }, + "reasoning_tokens": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Reasoning Tokens" + } + }, + "title": "Metrics", + "type": "object" + }, + "Note": { + "additionalProperties": false, + "properties": { + "actor": { + "title": "Actor", + "type": "string" + }, + "attempt": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Attempt" + }, + "derived_from": { + "anyOf": [ + { + "$ref": "#/$defs/DerivedFrom" + }, + { + "type": "null" + } + ], + "default": null + }, + "id": { + "title": "Id", + "type": "string" + }, + "is_copied_context": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Is Copied Context" + }, + "observer": { + "enum": [ + "agent", + "gateway", + "browser", + "framework" + ], + "title": "Observer", + "type": "string" + }, + "seq": { + "title": "Seq", + "type": "integer" + }, + "step": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Step" + }, + "text": { + "title": "Text", + "type": "string" + }, + "time": { + "$ref": "#/$defs/Time" + }, + "turn": { + "title": "Turn", + "type": "integer" + }, + "type": { + "const": "note", + "title": "Type", + "type": "string" + }, + "x": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "default": null, + "title": "X" + } + }, + "required": [ + "seq", + "id", + "type", + "turn", + "actor", + "observer", + "time", + "text" + ], + "title": "Note", + "type": "object" + }, + "Opaque": { + "additionalProperties": false, + "description": "A provider payload kept byte for byte, such as a thinking signature, for replay.", + "properties": { + "kind": { + "enum": [ + "signature", + "encrypted", + "redacted_data" + ], + "title": "Kind", + "type": "string" + }, + "provider": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Provider" + }, + "value": { + "title": "Value", + "type": "string" + } + }, + "required": [ + "kind", + "value" + ], + "title": "Opaque", + "type": "object" + }, + "Origin": { + "additionalProperties": true, + "description": "Where a user-side part came from; the part's own metadata (a notification's channel, a peer's id) sits beside\n``kind``.", + "properties": { + "kind": { + "enum": [ + "framework", + "user_sim", + "trigger", + "notification", + "peer", + "human" + ], + "title": "Kind", + "type": "string" + } + }, + "required": [ + "kind" + ], + "title": "Origin", + "type": "object" + }, + "Reasoning": { + "additionalProperties": false, + "properties": { + "actor": { + "title": "Actor", + "type": "string" + }, + "attempt": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Attempt" + }, + "derived_from": { + "anyOf": [ + { + "$ref": "#/$defs/DerivedFrom" + }, + { + "type": "null" + } + ], + "default": null + }, + "id": { + "title": "Id", + "type": "string" + }, + "is_copied_context": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Is Copied Context" + }, + "observer": { + "enum": [ + "agent", + "gateway", + "browser", + "framework" + ], + "title": "Observer", + "type": "string" + }, + "opaque": { + "anyOf": [ + { + "items": { + "$ref": "#/$defs/Opaque" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Opaque" + }, + "seq": { + "title": "Seq", + "type": "integer" + }, + "step": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Step" + }, + "text": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Text" + }, + "time": { + "$ref": "#/$defs/Time" + }, + "turn": { + "title": "Turn", + "type": "integer" + }, + "type": { + "const": "reasoning", + "title": "Type", + "type": "string" + }, + "visibility": { + "enum": [ + "raw", + "summary", + "omitted", + "redacted" + ], + "title": "Visibility", + "type": "string" + }, + "x": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "default": null, + "title": "X" + } + }, + "required": [ + "seq", + "id", + "type", + "turn", + "actor", + "observer", + "time", + "visibility", + "text" + ], + "title": "Reasoning", + "type": "object" + }, + "RefPart": { + "additionalProperties": false, + "description": "Text over the inline limit: a preview and the full text by reference.", + "properties": { + "origin": { + "anyOf": [ + { + "$ref": "#/$defs/Origin" + }, + { + "type": "null" + } + ], + "default": null + }, + "preview": { + "title": "Preview", + "type": "string" + }, + "source": { + "$ref": "#/$defs/Source" + }, + "type": { + "const": "ref", + "title": "Type", + "type": "string" + } + }, + "required": [ + "type", + "preview", + "source" + ], + "title": "RefPart", + "type": "object" + }, + "Source": { + "additionalProperties": false, + "description": "Bytes held by reference: a ``sha256:`` URL resolved under the run's blob prefix, or an absolute URL.", + "properties": { + "bytes": { + "title": "Bytes", + "type": "integer" + }, + "duration_ms": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Duration Ms" + }, + "height": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Height" + }, + "media_type": { + "title": "Media Type", + "type": "string" + }, + "name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Name" + }, + "pages": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Pages" + }, + "sha256": { + "title": "Sha256", + "type": "string" + }, + "url": { + "title": "Url", + "type": "string" + }, + "width": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Width" + } + }, + "required": [ + "url", + "media_type", + "bytes", + "sha256" + ], + "title": "Source", + "type": "object" + }, + "StepEvent": { + "additionalProperties": false, + "description": "One inference, dispatch or inbound message, under ATIF's step names; the content events that share its\n``step`` key belong to it.", + "properties": { + "actor": { + "title": "Actor", + "type": "string" + }, + "attempt": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Attempt" + }, + "derived_from": { + "anyOf": [ + { + "$ref": "#/$defs/DerivedFrom" + }, + { + "type": "null" + } + ], + "default": null + }, + "first_token_at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "First Token At" + }, + "id": { + "title": "Id", + "type": "string" + }, + "is_copied_context": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Is Copied Context" + }, + "llm_call_count": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Llm Call Count" + }, + "metrics": { + "anyOf": [ + { + "$ref": "#/$defs/Metrics" + }, + { + "type": "null" + } + ], + "default": null + }, + "model_name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Model Name" + }, + "observer": { + "enum": [ + "agent", + "gateway", + "browser", + "framework" + ], + "title": "Observer", + "type": "string" + }, + "provider_ids": { + "anyOf": [ + { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Provider Ids" + }, + "reasoning_effort": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Reasoning Effort" + }, + "sampling": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Sampling" + }, + "seq": { + "title": "Seq", + "type": "integer" + }, + "source": { + "enum": [ + "agent", + "user", + "system" + ], + "title": "Source", + "type": "string" + }, + "step": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Step" + }, + "stop_reason": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Stop Reason" + }, + "time": { + "$ref": "#/$defs/Time" + }, + "turn": { + "title": "Turn", + "type": "integer" + }, + "type": { + "const": "step", + "title": "Type", + "type": "string" + }, + "x": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "default": null, + "title": "X" + } + }, + "required": [ + "seq", + "id", + "type", + "turn", + "actor", + "observer", + "time", + "source" + ], + "title": "StepEvent", + "type": "object" + }, + "TextPart": { + "additionalProperties": false, + "properties": { + "elision": { + "anyOf": [ + { + "$ref": "#/$defs/Elision" + }, + { + "type": "null" + } + ], + "default": null + }, + "origin": { + "anyOf": [ + { + "$ref": "#/$defs/Origin" + }, + { + "type": "null" + } + ], + "default": null + }, + "text": { + "title": "Text", + "type": "string" + }, + "type": { + "const": "text", + "title": "Type", + "type": "string" + } + }, + "required": [ + "type", + "text" + ], + "title": "TextPart", + "type": "object" + }, + "Time": { + "additionalProperties": false, + "description": "When an event happened per the native record. ``at`` is always present and null when the native has no time;\n``raw`` is the native string whenever it differs from ``at``.", + "properties": { + "at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "At" + }, + "duration_ms": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Duration Ms" + }, + "end": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "End" + }, + "raw": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Raw" + }, + "start": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Start" + }, + "virtual": { + "anyOf": [ + { + "items": { + "$ref": "#/$defs/VirtualTime" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Virtual" + } + }, + "required": [ + "at" + ], + "title": "Time", + "type": "object" + }, + "ToolCall": { + "additionalProperties": false, + "description": "A tool call; ``arguments`` is any JSON value, and ``arguments_raw`` the native string when it was one.", + "properties": { + "actor": { + "title": "Actor", + "type": "string" + }, + "arguments": { + "title": "Arguments" + }, + "arguments_raw": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Arguments Raw" + }, + "attempt": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Attempt" + }, + "derived_from": { + "anyOf": [ + { + "$ref": "#/$defs/DerivedFrom" + }, + { + "type": "null" + } + ], + "default": null + }, + "env_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Env Id" + }, + "executor": { + "anyOf": [ + { + "enum": [ + "agent", + "env", + "provider", + "client" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Executor" + }, + "function_name": { + "title": "Function Name", + "type": "string" + }, + "id": { + "title": "Id", + "type": "string" + }, + "is_copied_context": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Is Copied Context" + }, + "kind": { + "anyOf": [ + { + "enum": [ + "builtin", + "mcp", + "function", + "custom" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Kind" + }, + "observer": { + "enum": [ + "agent", + "gateway", + "browser", + "framework" + ], + "title": "Observer", + "type": "string" + }, + "seq": { + "title": "Seq", + "type": "integer" + }, + "server": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Server" + }, + "step": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Step" + }, + "time": { + "$ref": "#/$defs/Time" + }, + "tool_call_id": { + "title": "Tool Call Id", + "type": "string" + }, + "turn": { + "title": "Turn", + "type": "integer" + }, + "type": { + "const": "tool_call", + "title": "Type", + "type": "string" + }, + "x": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "default": null, + "title": "X" + } + }, + "required": [ + "seq", + "id", + "type", + "turn", + "actor", + "observer", + "time", + "tool_call_id", + "function_name", + "arguments" + ], + "title": "ToolCall", + "type": "object" + }, + "ToolDef": { + "additionalProperties": false, + "properties": { + "description": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Description" + }, + "input_schema": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Input Schema" + }, + "kind": { + "anyOf": [ + { + "enum": [ + "builtin", + "mcp", + "function", + "custom" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Kind" + }, + "name": { + "title": "Name", + "type": "string" + }, + "server": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Server" + } + }, + "required": [ + "name" + ], + "title": "ToolDef", + "type": "object" + }, + "ToolResult": { + "additionalProperties": false, + "description": "A result answering any earlier call in the context, kept where it arrived.", + "properties": { + "actor": { + "title": "Actor", + "type": "string" + }, + "attempt": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Attempt" + }, + "content": { + "items": { + "oneOf": [ + { + "$ref": "#/$defs/TextPart" + }, + { + "$ref": "#/$defs/RefPart" + }, + { + "$ref": "#/$defs/MediaPart" + }, + { + "$ref": "#/$defs/DataPart" + }, + { + "$ref": "#/$defs/ElidedPart" + }, + { + "description": "A type this version doesn't define: readers keep it, producers may not write it.", + "not": {} + } + ] + }, + "title": "Content", + "type": "array" + }, + "derived_from": { + "anyOf": [ + { + "$ref": "#/$defs/DerivedFrom" + }, + { + "type": "null" + } + ], + "default": null + }, + "exit_code": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Exit Code" + }, + "id": { + "title": "Id", + "type": "string" + }, + "is_copied_context": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Is Copied Context" + }, + "observer": { + "enum": [ + "agent", + "gateway", + "browser", + "framework" + ], + "title": "Observer", + "type": "string" + }, + "seq": { + "title": "Seq", + "type": "integer" + }, + "source_call_id": { + "title": "Source Call Id", + "type": "string" + }, + "status": { + "enum": [ + "ok", + "error", + "canceled", + "timeout" + ], + "title": "Status", + "type": "string" + }, + "step": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Step" + }, + "time": { + "$ref": "#/$defs/Time" + }, + "turn": { + "title": "Turn", + "type": "integer" + }, + "type": { + "const": "tool_result", + "title": "Type", + "type": "string" + }, + "x": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "default": null, + "title": "X" + } + }, + "required": [ + "seq", + "id", + "type", + "turn", + "actor", + "observer", + "time", + "source_call_id", + "status", + "content" + ], + "title": "ToolResult", + "type": "object" + }, + "Tools": { + "additionalProperties": false, + "description": "The tools the agent can call from here on: the whole set, or ones added or removed.", + "properties": { + "actor": { + "title": "Actor", + "type": "string" + }, + "attempt": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Attempt" + }, + "derived_from": { + "anyOf": [ + { + "$ref": "#/$defs/DerivedFrom" + }, + { + "type": "null" + } + ], + "default": null + }, + "id": { + "title": "Id", + "type": "string" + }, + "is_copied_context": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Is Copied Context" + }, + "mode": { + "enum": [ + "replace", + "add", + "remove" + ], + "title": "Mode", + "type": "string" + }, + "observer": { + "enum": [ + "agent", + "gateway", + "browser", + "framework" + ], + "title": "Observer", + "type": "string" + }, + "seq": { + "title": "Seq", + "type": "integer" + }, + "step": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Step" + }, + "time": { + "$ref": "#/$defs/Time" + }, + "tools": { + "items": { + "$ref": "#/$defs/ToolDef" + }, + "title": "Tools", + "type": "array" + }, + "turn": { + "title": "Turn", + "type": "integer" + }, + "type": { + "const": "tools", + "title": "Type", + "type": "string" + }, + "x": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "default": null, + "title": "X" + } + }, + "required": [ + "seq", + "id", + "type", + "turn", + "actor", + "observer", + "time", + "mode", + "tools" + ], + "title": "Tools", + "type": "object" + }, + "TurnEnd": { + "additionalProperties": false, + "properties": { + "actor": { + "title": "Actor", + "type": "string" + }, + "attempt": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Attempt" + }, + "derived_from": { + "anyOf": [ + { + "$ref": "#/$defs/DerivedFrom" + }, + { + "type": "null" + } + ], + "default": null + }, + "final_metrics": { + "anyOf": [ + { + "$ref": "#/$defs/FinalMetrics" + }, + { + "type": "null" + } + ], + "default": null + }, + "id": { + "title": "Id", + "type": "string" + }, + "is_copied_context": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Is Copied Context" + }, + "observer": { + "enum": [ + "agent", + "gateway", + "browser", + "framework" + ], + "title": "Observer", + "type": "string" + }, + "seq": { + "title": "Seq", + "type": "integer" + }, + "state": { + "enum": [ + "completed", + "failed", + "canceled" + ], + "title": "State", + "type": "string" + }, + "step": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Step" + }, + "time": { + "$ref": "#/$defs/Time" + }, + "tool_call_count": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Tool Call Count" + }, + "turn": { + "title": "Turn", + "type": "integer" + }, + "type": { + "const": "turn.end", + "title": "Type", + "type": "string" + }, + "x": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "default": null, + "title": "X" + } + }, + "required": [ + "seq", + "id", + "type", + "turn", + "actor", + "observer", + "time", + "state" + ], + "title": "TurnEnd", + "type": "object" + }, + "TurnStart": { + "additionalProperties": false, + "description": "Opens a turn, one per A2A task. It names who made the stream and declares the turn's actors.", + "properties": { + "actor": { + "title": "Actor", + "type": "string" + }, + "actors": { + "items": { + "$ref": "#/$defs/Actor" + }, + "title": "Actors", + "type": "array" + }, + "adapter": { + "$ref": "#/$defs/AdapterInfo" + }, + "attempt": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Attempt" + }, + "context_id": { + "title": "Context Id", + "type": "string" + }, + "derived_from": { + "anyOf": [ + { + "$ref": "#/$defs/DerivedFrom" + }, + { + "type": "null" + } + ], + "default": null + }, + "id": { + "title": "Id", + "type": "string" + }, + "is_copied_context": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Is Copied Context" + }, + "live": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Live" + }, + "message_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Message Id" + }, + "native_format": { + "title": "Native Format", + "type": "string" + }, + "observer": { + "enum": [ + "agent", + "gateway", + "browser", + "framework" + ], + "title": "Observer", + "type": "string" + }, + "seq": { + "title": "Seq", + "type": "integer" + }, + "spec_version": { + "title": "Spec Version", + "type": "string" + }, + "step": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Step" + }, + "task_id": { + "title": "Task Id", + "type": "string" + }, + "time": { + "$ref": "#/$defs/Time" + }, + "turn": { + "title": "Turn", + "type": "integer" + }, + "type": { + "const": "turn.start", + "title": "Type", + "type": "string" + }, + "usage_input_includes_cache": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "title": "Usage Input Includes Cache" + }, + "x": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "default": null, + "title": "X" + } + }, + "required": [ + "seq", + "id", + "type", + "turn", + "actor", + "observer", + "time", + "spec_version", + "context_id", + "task_id", + "native_format", + "adapter", + "usage_input_includes_cache", + "actors" + ], + "title": "TurnStart", + "type": "object" + }, + "UsageTotals": { + "additionalProperties": false, + "properties": { + "cost_source": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Cost Source" + }, + "cost_status": { + "anyOf": [ + { + "enum": [ + "reported", + "priced", + "unpriced" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Cost Status" + }, + "total_cache_write_tokens": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Total Cache Write Tokens" + }, + "total_cached_tokens": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Total Cached Tokens" + }, + "total_completion_tokens": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Total Completion Tokens" + }, + "total_cost_usd": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "number" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Total Cost Usd" + }, + "total_prompt_tokens": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Total Prompt Tokens" + }, + "total_reasoning_tokens": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Total Reasoning Tokens" + } + }, + "title": "UsageTotals", + "type": "object" + }, + "VirtualTime": { + "additionalProperties": false, + "properties": { + "at": { + "title": "At", + "type": "string" + }, + "env_id": { + "title": "Env Id", + "type": "string" + }, + "env_step_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Env Step Id" + } + }, + "required": [ + "env_id", + "at" + ], + "title": "VirtualTime", + "type": "object" + } + }, + "$schema": "https://json-schema.org/draft/2020-12/schema", + "oneOf": [ + { + "$ref": "#/$defs/TurnStart" + }, + { + "$ref": "#/$defs/Message" + }, + { + "$ref": "#/$defs/FinalResponse" + }, + { + "$ref": "#/$defs/TurnEnd" + }, + { + "$ref": "#/$defs/StepEvent" + }, + { + "$ref": "#/$defs/Reasoning" + }, + { + "$ref": "#/$defs/ToolCall" + }, + { + "$ref": "#/$defs/ToolResult" + }, + { + "$ref": "#/$defs/Tools" + }, + { + "$ref": "#/$defs/ActorDeclared" + }, + { + "$ref": "#/$defs/ErrorEvent" + }, + { + "$ref": "#/$defs/Attempt" + }, + { + "$ref": "#/$defs/Note" + }, + { + "$ref": "#/$defs/ExtensionEvent" + }, + { + "description": "A type this version doesn't define: readers keep it, producers may not write it.", + "not": {} + } + ], + "title": "yatf/1 event, spec 1.0" +} diff --git a/packages/agentenv-protocol/tests/test_yatf_adapter.py b/packages/agentenv-protocol/tests/test_yatf_adapter.py new file mode 100644 index 000000000..33ec939ac --- /dev/null +++ b/packages/agentenv-protocol/tests/test_yatf_adapter.py @@ -0,0 +1,377 @@ +"""yatf/1 adapters: declared with decorators, fed a context's native and aux records a turn at a time, and stamped by +the turn they write through, so a replay of the stored records makes the same events.""" +import inspect + +import jsonschema +import pytest + +from agentenv_protocol import yatf +from agentenv_protocol.yatf import Adapter, AdapterRun, Fed, RecordedTurn, TurnContext, aux, finish, native + +VALIDATOR = jsonschema.Draft202012Validator(yatf.load_schema()) +CREATED = [] + + +@yatf.yatf_adapter(native_format="toy-events/1", version="0.1.0", usage_input_includes_cache=True, + tested_with=("toy 1.0",), lossy=("system prompt",)) +class Toy(Adapter): + """A toy CLI whose calls get their times from an aux clock file, so a call waits for its tick.""" + + def __init__(self, turn): + CREATED.append(self) + self.held = {} + self.ticks = {} + self.turns = 0 + + @native(type="say") + def say(self, record, turn): + turn.message(role="assistant", step=record["id"], text=record["text"]) + + @native(type="call") + def call(self, record, turn): + self.held[record["id"]] = (record, turn.source) + self.emit_ready(turn) + + @aux("clock", type="tick") + def tick(self, record, turn): + self.ticks[record["id"]] = record["at"] + self.emit_ready(turn) + + @aux("clock", type="drift") + def drift(self, record, turn): + turn.note("the clock drifted") + + def emit_ready(self, turn): + for call_id in [call_id for call_id in self.held if call_id in self.ticks]: + record, source = self.held.pop(call_id) + turn.tool_call(tool_call_id=call_id, function_name=record["name"], arguments=record["args"], + step=record["step"], kind="builtin", executor="agent", time=self.ticks[call_id], + derived_from=source) + + @native(type="result") + def result(self, record, turn): + turn.tool_result(source_call_id=record["id"], text=record["out"], time=record["at"]) + + @native(type="usage") + def usage(self, record, turn): + turn.step(key=record["step"], model_name="toy-model", + metrics={"prompt_tokens": record["prompt"], "completion_tokens": record["completion"], + "cost_usd": None, "cost_status": "unpriced"}) + + @native(type="event") + def event(self, record, turn): + turn.note(record["kind"]) + + @native(type="event", where={"kind": "retry"}) + def retry(self, record, turn): + turn.attempt(record["n"], reason="api error") + + @finish + def close(self, turn): + for call_id, (record, source) in self.held.items(): + turn.tool_call(tool_call_id=call_id, function_name=record["name"], arguments=record["args"], + step=record["step"], derived_from=source) + self.held, self.ticks = {}, {} + self.turns += 1 + + +RECORDS = ( + Fed({"type": "say", "id": "m1", "text": "listing"}), + Fed({"type": "call", "id": "c1", "step": "m1", "name": "Bash", "args": {"command": "ls"}}), + Fed({"type": "tick", "id": "c1", "at": "2026-11-17T10:00:01Z"}, aux="clock"), + Fed({"type": "noise"}, aux="clock"), + Fed({"type": "result", "id": "c1", "out": "a b", "at": "2026-11-17T10:00:02Z"}), + Fed({"type": "usage", "step": "m1", "prompt": 10, "completion": 2}), + Fed({"type": "debug", "detail": 1}), + Fed({"type": "event", "kind": "compacted"}), + Fed({"type": "drift"}, aux="clock"), +) + + +def context(index=0): + return TurnContext(index=index, context_id="ctx", task_id=f"t{index}", message_id=f"m-{index}", + inbound=[{"type": "text", "text": "list files"}], started_at="2026-11-17T10:00:00Z") + + +def recorded(index=0, records=RECORDS): + return RecordedTurn(context=context(index), records=records, final=[{"type": "text", "text": "a b"}], + ended_at="2026-11-17T10:00:03Z") + + +@pytest.fixture(autouse=True) +def fresh(): + CREATED.clear() + + +def test_a_turn_is_framed_stamped_and_valid(): + events = yatf.replay(Toy, [recorded()]) + assert [event["type"] for event in events] == [ + "turn.start", "message", "message", "tool_call", "tool_result", "step", "toy-events/raw", "note", "note", + "final_response", "turn.end"] + assert [(event["seq"], event["id"], event["turn"], event["observer"]) for event in events] == [ + (seq, f"0.{seq}", 0, "agent") for seq in range(len(events))] + for event in events: + VALIDATOR.validate(event) + start, inbound, end = events[0], events[1], events[-1] + assert start["native_format"] == "toy-events/1" and start["usage_input_includes_cache"] is True + assert start["adapter"] == {"name": "toy-events-yatf", "version": "0.1.0", "lossy": ["system prompt"]} + assert start["actors"] == [{"id": "agent", "kind": "agent"}, {"id": "caller", "kind": "framework"}] + assert (inbound["actor"], inbound["step"], inbound["role"]) == ("caller", "in-0", "user") + assert end["state"] == "completed" and end["tool_call_count"] == 1 + assert end["time"] == {"at": "2026-11-17T10:00:03Z"} + + +def test_every_event_names_the_record_it_came_from(): + by_type = {} + for event in yatf.replay(Toy, [recorded()]): + by_type.setdefault(event["type"], []).append(event.get("derived_from")) + assert by_type["turn.start"] == [None] and by_type["final_response"] == [None] + assert by_type["tool_call"] == [{"index": 1}] + assert by_type["tool_result"] == [{"index": 2}] and by_type["step"] == [{"index": 3}] + assert by_type["toy-events/raw"] == [{"index": 4}] + assert by_type["note"] == [{"index": 5}, {"index": 2, "aux": "clock"}] + + +def test_unmatched_native_records_are_kept_and_unmatched_aux_records_dropped(): + events = yatf.replay(Toy, [recorded()]) + raw = [event for event in events if event["type"] == "toy-events/raw"] + assert [event["record"] for event in raw] == [{"type": "debug", "detail": 1}] + assert not any("noise" in str(event) for event in events) + + +def test_the_most_specific_handler_takes_a_record(): + records = (Fed({"type": "event", "kind": "retry", "n": 2}), Fed({"type": "say", "id": "m2", "text": "again"})) + events = yatf.replay(Toy, [recorded(records=records)]) + assert [event["type"] for event in events[2:4]] == ["attempt", "message"] + assert events[2]["number"] == 2 and events[2]["attempt"] == 2 and events[3]["attempt"] == 2 + assert "attempt" not in events[0] and events[-1]["attempt"] == 2 + + +def test_equally_specific_handlers_that_both_match_are_refused(): + @yatf.yatf_adapter(native_format="toy-events/1", version="0.1.0", usage_input_includes_cache=None) + class Ambiguous(Adapter): + @native(type="x") + def by_type(self, record, turn): + pass + + @native(where={"kind": "y"}) + def by_kind(self, record, turn): + pass + + with pytest.raises(yatf.YatfError, match="by_kind, by_type"): + yatf.replay(Ambiguous, [recorded(records=(Fed({"type": "x", "kind": "y"}),))]) + + +def test_one_adapter_serves_the_whole_context(): + events = yatf.replay(Toy, [recorded(0), recorded(1)]) + assert len(CREATED) == 1 and CREATED[0].turns == 2 + second = [event for event in events if event["turn"] == 1] + assert second[0]["type"] == "turn.start" and second[0]["task_id"] == "t1" + assert [event["id"] for event in second] == [f"1.{seq}" for seq in range(len(second))] + + +def test_a_live_run_and_a_replay_of_its_records_make_the_same_events(): + run = AdapterRun(Toy) + live = run.start_turn(context()) + for fed in RECORDS: + live += run.native(fed.record) if fed.aux is None else run.aux(fed.aux, fed.record) + live += run.end_turn(final=[{"type": "text", "text": "a b"}], ended_at="2026-11-17T10:00:03Z") + assert live == run.events == yatf.replay(Toy, [recorded()]) + + +def test_a_closed_turn_keeps_its_own_events_and_takes_no_more(): + handed = [] + + @yatf.yatf_adapter(native_format="toy-events/1", version="0.1.0", usage_input_includes_cache=None) + class Keeper(Adapter): + @native(type="say") + def say(self, record, turn): + handed.append(turn) + turn.note(record["text"]) + + events = yatf.replay(Keeper, [recorded(0, (Fed({"type": "say", "text": "a"}),)), + recorded(1, (Fed({"type": "say", "text": "b"}),))]) + first, second = handed + assert first.events == [event for event in events if event["turn"] == 0] + assert second.events == [event for event in events if event["turn"] == 1] + with pytest.raises(yatf.YatfError, match="turn 0 is closed"): + first.note("late") + assert first.events == [event for event in events if event["turn"] == 0] + + +def test_a_call_still_held_at_turn_end_is_written_without_a_time(): + records = (Fed({"type": "call", "id": "c9", "step": "m9", "name": "Read", "args": {}}),) + events = yatf.replay(Toy, [recorded(records=records)]) + call = next(event for event in events if event["type"] == "tool_call") + assert call["time"] == {"at": None} and call["derived_from"] == {"index": 0} + + +def test_the_frame_is_written_when_finish_raises(): + @yatf.yatf_adapter(native_format="toy-events/1", version="0.1.0", usage_input_includes_cache=None) + class Broken(Adapter): + @finish + def close(self, turn): + raise RuntimeError("boom") + + run = AdapterRun(Broken) + run.start_turn(context()) + with pytest.raises(RuntimeError, match="boom"): + run.end_turn() + assert run.events[-1]["type"] == "turn.end" + run.start_turn(context(1)) + + +def test_records_are_fed_only_inside_a_turn_and_only_to_declared_aux_files(): + run = AdapterRun(Toy) + with pytest.raises(yatf.YatfError, match="no turn is open"): + run.native({"type": "say"}) + run.start_turn(context()) + with pytest.raises(yatf.YatfError, match="still open"): + run.start_turn(context(1)) + with pytest.raises(yatf.YatfError, match="no aux file 'rollout'"): + run.aux("rollout", {}) + + +def test_extension_events_are_namespaced_outside_yatf(): + turn = yatf.YatfTurn(context(), Toy.spec) + body = {"note": "kept", "model": 1, "event_type": 2, "nulls": 3, "kind": 4} + assert turn.extension("toy-events/marker", body).model_extra == body + for kind in ("delegation", "yatf/thing", "note"): + with pytest.raises(yatf.YatfError, match="isn't an extension type"): + turn.extension(kind, {}) + with pytest.raises(yatf.YatfError, match="envelope fields: seq"): + turn.extension("toy-events/marker", {"seq": 3}) + with pytest.raises(yatf.YatfError, match="either content or text"): + turn.message(role="assistant", text="a", content=[]) + with pytest.raises(yatf.YatfError, match="message event"): + turn.message(role="assistant", content=[{"type": "text"}]) + + +def test_an_adapter_marks_replayed_context_as_copied(): + turn = yatf.YatfTurn(context(), Toy.spec) + turn.message(role="user", step="s0", text="earlier", is_copied_context=True) + turn.raw({"type": "history"}, is_copied_context=True) + assert [event["is_copied_context"] for event in turn.events] == [True, True] + + +def test_explicit_nulls_an_adapter_writes_are_kept(): + turn = yatf.YatfTurn(context(), Toy.spec) + turn.extension("toy-events/marker", {"value": None}) + turn.raw(None) + turn.reasoning(visibility="omitted", step="s1", opaque=[{"kind": "signature", "value": "sig"}]) + marker, raw, reasoning = turn.events + assert "value" in marker and marker["value"] is None + assert "record" in raw and raw["record"] is None + assert "text" in reasoning and reasoning["text"] is None + + +def test_an_event_that_is_not_json_is_refused_as_it_is_written(): + turn = yatf.YatfTurn(context(), Toy.spec) + for arguments in ({"x": float("inf")}, {"x": {1, 2}}, {"x": b"raw"}): + with pytest.raises(yatf.YatfError, match="isn't JSON"): + turn.tool_call(tool_call_id="c1", function_name="Bash", arguments=arguments) + assert turn.events == [] + assert turn.note("next").seq == 0 + + +def test_what_a_run_hands_out_is_a_copy(): + run = AdapterRun(Toy) + page = run.start_turn(context()) + page[0]["tampered"] = True + page[1]["content"][0]["text"] = "changed" + assert "tampered" not in run.events[0] and run.events[1]["content"][0]["text"] == "list files" + run.events[0]["also"] = 1 + assert "also" not in run.events[0] + + +@pytest.mark.parametrize("method,model", [ + ("message", yatf.Message), ("reasoning", yatf.Reasoning), ("tool_call", yatf.ToolCall), + ("tool_result", yatf.ToolResult), ("step", yatf.StepEvent), ("tools", yatf.Tools), ("declare", yatf.ActorDeclared), + ("error", yatf.ErrorEvent), ("attempt", yatf.Attempt), ("note", yatf.Note), +]) +def test_every_builder_method_takes_every_field_of_its_model(method, model): + taken = set(inspect.signature(getattr(yatf.YatfTurn, method)).parameters) + assert set(model.model_fields) - set(yatf.Event.model_fields) <= taken + settable = set(yatf.Event.model_fields) - {"seq", "id", "type", "turn", "observer", "attempt", "step"} + assert {"time", "actor", "derived_from", "x", "is_copied_context"} == settable <= taken + + +def adapter_class(**declared): + options = {"native_format": "toy-events/1", "version": "0.1.0", "usage_input_includes_cache": None, **declared} + + @yatf.yatf_adapter(**options) + class Declared(Adapter): + pass + return Declared + + +@pytest.mark.parametrize("declared,message", [ + ({"native_format": "toy"}, "/"), + ({"native_format": "yatf/1"}, "not a native one"), + ({"version": ""}, "version"), + ({"usage_input_includes_cache": "yes"}, "true, false or None"), + ({"namespace": "Toy"}, "can't name extension types"), +]) +def test_a_bad_declaration_is_refused_at_import(declared, message): + with pytest.raises(yatf.YatfError, match=message): + adapter_class(**declared) + + +def test_conflicting_handlers_are_refused_at_import(): + declare = yatf.yatf_adapter(native_format="toy-events/1", version="0.1.0", usage_input_includes_cache=None) + with pytest.raises(TypeError, match="Adapter subclass"): + declare(type("Plain", (), {})) + + class Twice(Adapter): + @native(type="say") + def one(self, record, turn): + pass + + @native(type=["say"]) + def two(self, record, turn): + pass + + class TwoFinishes(Adapter): + @finish + def one(self, turn): + pass + + @finish + def two(self, turn): + pass + + class TwoMediaTypes(Adapter): + @aux("log", media_type="application/jsonl", type="a") + def one(self, record, turn): + pass + + @aux("log", media_type="text/plain", type="b") + def two(self, record, turn): + pass + + for cls, message in ((Twice, "take the same records"), (TwoFinishes, "more than one @finish"), + (TwoMediaTypes, "declared as both")): + with pytest.raises(yatf.YatfError, match=message): + declare(cls) + with pytest.raises(yatf.YatfError, match="isn't declared"): + AdapterRun(type("Undeclared", (Toy,), {})) + + +def test_a_subclass_inherits_and_overrides_handlers(): + @yatf.yatf_adapter(native_format="toy-events/2", version="0.2.0", usage_input_includes_cache=True) + class Louder(Toy): + @native(type="say") + def say(self, record, turn): + turn.message(role="assistant", step=record["id"], text=record["text"].upper()) + + events = yatf.replay(Louder, [recorded()]) + assert events[2]["content"] == [{"type": "text", "text": "LISTING"}] + assert events[0]["native_format"] == "toy-events/2" and events[3]["type"] == "tool_call" + + +def test_converting_back_is_the_adapters_to_write(): + assert Toy.spec.aux == {"clock": "application/jsonl"} and Toy.spec.finish == "close" + with pytest.raises(NotImplementedError, match="Toy"): + Toy.from_yatf([]) + assert Toy.normal_form([{"a": 1}]) == [{"a": 1}] + assert yatf.Native(log=[[{"type": "say"}]]).session is None diff --git a/packages/agentenv-protocol/tests/test_yatf_examples.py b/packages/agentenv-protocol/tests/test_yatf_examples.py new file mode 100644 index 000000000..77d57e22f --- /dev/null +++ b/packages/agentenv-protocol/tests/test_yatf_examples.py @@ -0,0 +1,52 @@ +"""yatf/1's worked examples, the spec's canonical fixtures: each is one turn that reads back exactly as written and +agrees with itself.""" +import json +from importlib.resources import files + +import pytest + +from agentenv_protocol import yatf + + +@pytest.mark.parametrize("name", yatf.EXAMPLES) +def test_an_example_reads_back_exactly_as_written(name): + text = files("agentenv_protocol.yatf").joinpath("examples", f"{name}.json").read_text(encoding="utf-8") + assert [yatf.dump_event(event) for event in yatf.load_example(name)] == json.loads(text) + + +@pytest.mark.parametrize("name", yatf.EXAMPLES) +def test_an_example_is_one_whole_turn(name): + events = yatf.load_example(name) + assert [type(events[0]), type(events[1]), type(events[-2]), type(events[-1])] == [ + yatf.TurnStart, yatf.Message, yatf.FinalResponse, yatf.TurnEnd] + assert [event.seq for event in events] == list(range(len(events))) + assert all(event.id == f"{event.turn}.{event.seq}" for event in events) + start = events[0] + assert start.spec_version == yatf.SPEC_VERSION and start.usage_input_includes_cache is not None + declared = {actor.id for actor in start.actors} + assert {event.actor for event in events} <= declared + + +@pytest.mark.parametrize("name", yatf.EXAMPLES) +def test_an_examples_totals_add_up(name): + events = yatf.load_example(name) + steps = [event for event in events if isinstance(event, yatf.StepEvent)] + end = events[-1] + totals = end.final_metrics + assert totals.total_steps == len(steps) + assert end.tool_call_count == sum(isinstance(event, yatf.ToolCall) for event in events) + for field in ("prompt_tokens", "completion_tokens", "cached_tokens", "cache_write_tokens"): + assert sum(getattr(step.metrics, field) for step in steps) == getattr(totals, f"total_{field}") + for step in steps: + assert step.metrics.cached_tokens + step.metrics.cache_write_tokens <= step.metrics.prompt_tokens + + +def test_every_call_in_the_examples_has_its_result(): + for name in yatf.EXAMPLES: + pairs = yatf.pair_tool_calls(yatf.load_example(name)) + assert pairs and all(len(pair.results) == 1 for pair in pairs) + + +def test_load_example_names_the_examples_it_has(): + with pytest.raises(yatf.YatfError, match="coding"): + yatf.load_example("chess") diff --git a/packages/agentenv-protocol/tests/test_yatf_models.py b/packages/agentenv-protocol/tests/test_yatf_models.py new file mode 100644 index 000000000..4a2b9c592 --- /dev/null +++ b/packages/agentenv-protocol/tests/test_yatf_models.py @@ -0,0 +1,131 @@ +"""yatf/1's models: each type parses as its own model, and a reader keeps what this version doesn't define.""" +import subprocess +import sys +from importlib.resources import files + +import pytest + +from agentenv_protocol import yatf + + +def event(kind: str, **body): + return {"seq": 0, "id": "0.0", "type": kind, "turn": 0, "actor": "agent", "observer": "agent", + "time": {"at": None}, **body} + + +def test_every_core_type_parses_as_its_model(): + bodies = { + "turn.start": {"spec_version": "1.0", "context_id": "c", "task_id": "t", "native_format": "toy/1", + "adapter": {"name": "toy-yatf", "version": "0.1.0"}, "usage_input_includes_cache": None, + "actors": [{"id": "agent", "kind": "agent"}]}, + "message": {"role": "user", "content": [{"type": "text", "text": "hi"}]}, + "final_response": {"content": [{"type": "data", "data": {"tool_call_count": 0}}]}, + "turn.end": {"state": "completed"}, + "step": {"source": "agent", "metrics": {"prompt_tokens": 3, "cost_usd": None, "cost_status": "unpriced"}}, + "reasoning": {"visibility": "omitted", "text": None, "opaque": [{"kind": "signature", "value": "sig"}]}, + "tool_call": {"tool_call_id": "c1", "function_name": "Bash", "arguments": None}, + "tool_result": {"source_call_id": "c1", "status": "ok", "content": []}, + "tools": {"mode": "replace", "tools": [{"name": "Bash", "kind": "builtin"}]}, + "actor": {"declared": {"id": "sub", "kind": "subagent", "parent": "agent", "spawned_by": "c1"}}, + "error": {"error_type": "infra_error", "message": "upstream 529"}, + "attempt": {"number": 2, "reason": "api error"}, + "note": {"text": "compacted"}, + } + assert set(bodies) == yatf.CORE_TYPES + for kind, body in bodies.items(): + parsed = yatf.parse_event(event(kind, **body)) + assert type(parsed) is yatf.EVENT_MODELS[kind] + assert yatf.dump_event(parsed) == event(kind, **body) + + +def test_a_reader_keeps_fields_this_version_does_not_define(): + raw = event("message", role="assistant", step="s1", later_field={"a": 1}, + content=[{"type": "text", "text": "hi", "tone": "dry"}]) + raw["time"]["leap"] = True + parsed = yatf.parse_event(raw) + assert parsed.model_extra == {"later_field": {"a": 1}} + assert yatf.dump_event(parsed) == raw + + +def test_unknown_and_reserved_types_are_kept_and_namespaced_ones_are_extensions(): + later = yatf.parse_event(event("delegation", to="peer")) + vendor = yatf.parse_event(event("claude-code/raw", record={"type": "system"})) + assert type(later) is yatf.UnknownEvent and later.model_extra == {"to": "peer"} + assert type(vendor) is yatf.ExtensionEvent and vendor.model_extra == {"record": {"type": "system"}} + assert type(yatf.parse_event(event("yatf/thing"))) is yatf.UnknownEvent + assert "delegation" in yatf.RESERVED_TYPES + + +def test_a_reader_keeps_part_types_and_vocabulary_values_this_version_lacks(): + raw = event("message", role="narrator", observer="robot", content=[{"type": "hologram", "frames": 3}]) + parsed = yatf.parse_event(raw) + assert parsed.observer == "robot" and parsed.role == "narrator" + assert type(parsed.content[0]) is yatf.UnknownPart + assert yatf.dump_event(parsed) == raw + + +def test_time_at_is_always_present_and_may_be_null(): + assert yatf.parse_event(event("note", text="x")).time.at is None + missing = event("note", text="x") + missing["time"] = {} + with pytest.raises(yatf.YatfError): + yatf.parse_event(missing) + + +def test_a_dump_writes_only_the_fields_the_event_was_given(): + dumped = yatf.dump_event(yatf.parse_event(event("note", text="x"))) + assert "attempt" not in dumped and "derived_from" not in dumped and dumped["time"] == {"at": None} + + +def test_a_lone_surrogate_may_be_in_a_value_but_not_a_field_name(): + kept = event("note", text="cut \ud83d", later={"\ud800": ["\udfff"]}, x={"\udfff": {"\ud800": 1}}) + assert yatf.dump_event(yatf.parse_event(kept)) == kept + with pytest.raises(yatf.YatfError): + yatf.parse_event({**event("note", text="x"), "later\ud800": 1}) + + +@pytest.mark.parametrize("value", [{"type": "note"}, [], "note", {**event("note", text="x"), "seq": "zero"}]) +def test_a_non_event_is_refused(value): + with pytest.raises(yatf.YatfError): + yatf.parse_event(value) + + +@pytest.mark.parametrize("field,value", [("seq", "5"), ("seq", 5.0), ("seq", True), ("attempt", False), + ("text", 5), ("is_copied_context", "yes")]) +def test_values_are_taken_as_given_never_coerced(field, value): + with pytest.raises(yatf.YatfError): + yatf.parse_event({**event("note", text="x"), field: value}) + + +def test_a_number_dumps_as_it_was_written_and_nan_is_refused(): + raw = event("step", source="agent", metrics={"cost_usd": 0, "cost_status": "reported", "prompt_tokens": 3}) + assert yatf.dump_event(yatf.parse_event(raw))["metrics"]["cost_usd"] == 0 + assert type(yatf.dump_event(yatf.parse_event(raw))["metrics"]["cost_usd"]) is int + raw["metrics"]["cost_usd"] = float("nan") + with pytest.raises(yatf.YatfError): + yatf.parse_event(raw) + + +@pytest.mark.parametrize("later", [float("inf"), [float("-inf")], {"deep": [float("nan")]}]) +def test_a_number_json_cannot_write_is_refused_anywhere_in_an_event(later): + with pytest.raises(yatf.YatfError, match="isn't a JSON number"): + yatf.parse_event({**event("note", text="x"), "later": later}) + + +def test_the_spec_names_every_type_and_vocabulary_value(): + spec = files("agentenv_protocol.yatf").joinpath("SPEC.md").read_text(encoding="utf-8") + names = sorted(yatf.CORE_TYPES | yatf.RESERVED_TYPES) + names += [value for values in yatf.VOCABULARIES.values() for value in values] + assert [name for name in names if f"`{name}`" not in spec] == [] + + +@pytest.mark.parametrize("kind,ok", [("claude-code/raw", True), ("codex/item.v2", True), ("yatf/raw", False), + ("delegation", False), ("Claude/raw", False), ("a/b/c", False)]) +def test_extension_types_are_namespaced_outside_yatf(kind, ok): + assert yatf.is_extension_type(kind) is ok + + +def test_the_package_imports_without_the_agent_sdk(): + script = ("import sys, agentenv_protocol.yatf; " + "sys.exit(any(name == 'a2a' or name.startswith('a2a.') for name in sys.modules))") + assert subprocess.run([sys.executable, "-c", script]).returncode == 0 diff --git a/packages/agentenv-protocol/tests/test_yatf_reader.py b/packages/agentenv-protocol/tests/test_yatf_reader.py new file mode 100644 index 000000000..a70bbb77d --- /dev/null +++ b/packages/agentenv-protocol/tests/test_yatf_reader.py @@ -0,0 +1,80 @@ +"""Reading a yatf/1 stream: JSON array or JSONL, (turn, seq) order, ATIF-style steps and paired tool calls.""" +import json + +import pytest + +from agentenv_protocol import yatf + + +def coding(): + return yatf.load_example("coding") + + +def test_a_json_array_and_jsonl_read_the_same(): + events = coding() + as_jsonl = yatf.dump_events(events) + as_array = yatf.dump_events(events, jsonl=False) + assert len(as_jsonl.splitlines()) == len(events) and as_array.startswith("[") + for text in (as_jsonl, as_array, as_jsonl.encode(), "" + as_jsonl.replace("\n", "\n\n")): + assert [yatf.dump_event(e) for e in yatf.parse_events(text)] == [yatf.dump_event(e) for e in events] + + +def test_a_stream_that_is_not_json_says_where(): + lines = yatf.dump_events(coding()).splitlines() + lines[3] = lines[3][:-5] + with pytest.raises(yatf.YatfError, match="line 4"): + yatf.parse_events("\n".join(lines)) + with pytest.raises(yatf.YatfError, match="event 1"): + yatf.parse_events([yatf.dump_event(coding()[0]), {"type": "note"}]) + with pytest.raises(yatf.YatfError): + yatf.parse_events('{"not": "an array"}\n[1') + with pytest.raises(yatf.YatfError, match="not UTF-8"): + yatf.parse_events(b'{"text": "\xff"}\n') + with pytest.raises(yatf.YatfError, match="NaN isn't JSON"): + yatf.parse_events(lines[0].replace('"turn":0', '"turn":NaN')) + with pytest.raises(yatf.YatfError, match="event 0: .*isn't a JSON number"): + yatf.parse_events(lines[0].replace('"turn":0', '"turn":0,"later":{"n":1e400}')) + + +def test_any_text_an_event_holds_dumps_to_encodable_jsonl(): + note = {"seq": 0, "id": "0.0", "type": "note", "turn": 0, "actor": "agent", "observer": "agent", + "time": {"at": None}, "text": "\ud800 é 漢 🤖 \x00", "later": {"\ude3a": ["\udfff"]}} + dumped = yatf.dump_events(yatf.parse_events([note])) + assert dumped.isascii() and dumped.encode("utf-8") + assert yatf.dump_event(yatf.parse_events(dumped)[0]) == note + + +def test_order_is_turn_then_seq_never_time(): + events = coding() + shuffled = list(reversed(events)) + later_turn = yatf.parse_event({**yatf.dump_event(events[0]), "turn": 1, "time": {"at": "2000-01-01T00:00:00Z"}}) + assert yatf.ordered(shuffled + [later_turn]) == events + [later_turn] + + +def test_tool_calls_pair_with_their_results_across_the_context(): + events = coding() + pairs = yatf.pair_tool_calls(events) + assert [pair.call.tool_call_id for pair in pairs] == ["toolu_01", "toolu_02", "toolu_03", "toolu_04"] + assert [pair.results[0].status for pair in pairs] == ["error", "ok", "ok", "ok"] + orphan = yatf.parse_event({**yatf.dump_event(events[6]), "seq": 99, "id": "0.99", "source_call_id": "gone"}) + unanswered = yatf.parse_event({**yatf.dump_event(events[4]), "seq": 98, "id": "0.98", "tool_call_id": "toolu_05"}) + pairs = yatf.pair_tool_calls(events + [orphan, unanswered]) + assert pairs[-1].call.tool_call_id == "toolu_05" and pairs[-1].results == () + assert all(result.source_call_id != "gone" for pair in pairs for result in pair.results) + + +def test_events_fold_into_steps_with_their_results_regrouped(): + steps = yatf.fold_steps(coding()) + assert [step.key for step in steps] == ["in-0", "msg_01A", "msg_01B", "msg_01C", "msg_01D", "msg_01E"] + inbound, first = steps[0], steps[1] + assert inbound.step is None and inbound.actor == "caller" + assert [type(event) for event in first.events] == [yatf.Reasoning, yatf.ToolCall] + assert first.step.metrics.prompt_tokens == 18432 + assert [result.source_call_id for result in first.results] == ["toolu_01"] + assert steps[-1].results == () and isinstance(steps[-1].events[0], yatf.Message) + + +def test_a_dump_round_trips_unknown_fields(): + raw = json.loads(yatf.dump_events(coding(), jsonl=False)) + raw[2]["later_field"] = [1] + assert json.loads(yatf.dump_events(yatf.parse_events(raw), jsonl=False)) == raw diff --git a/packages/agentenv-protocol/tests/test_yatf_schema.py b/packages/agentenv-protocol/tests/test_yatf_schema.py new file mode 100644 index 000000000..a6d6304f6 --- /dev/null +++ b/packages/agentenv-protocol/tests/test_yatf_schema.py @@ -0,0 +1,60 @@ +"""yatf/1's strict JSON schema: generated from the models, checked in, and stricter than a reader.""" +import copy +import subprocess +import sys +from importlib.resources import files + +import jsonschema +import pytest + +from agentenv_protocol import yatf +from agentenv_protocol.yatf.schema import SCHEMA_FILE, schema_text + +VALIDATOR = jsonschema.Draft202012Validator(yatf.load_schema()) + + +def example_events(): + return [yatf.dump_event(event) for name in yatf.EXAMPLES for event in yatf.load_example(name)] + + +def test_the_checked_in_schema_is_the_generated_one(): + if files("agentenv_protocol.yatf").joinpath(SCHEMA_FILE).read_text(encoding="utf-8") != schema_text(): + pytest.fail(f"{SCHEMA_FILE} is stale, after a model change or a pydantic upgrade; regenerate it with " + f"python -m agentenv_protocol.yatf schema > " + f"packages/agentenv-protocol/src/agentenv_protocol/yatf/{SCHEMA_FILE}") + + +def test_python_m_prints_the_schema(): + out = subprocess.run([sys.executable, "-m", "agentenv_protocol.yatf", "schema"], capture_output=True, text=True, + check=True) + assert out.stdout == schema_text() and out.stderr == "" + + +def test_every_example_event_is_valid(): + for raw in example_events(): + VALIDATOR.validate(raw) + + +@pytest.mark.parametrize("change", [ + lambda e: e.update(later_field=1), + lambda e: e["time"].update(leap=True), + lambda e: e.update(observer="robot"), + lambda e: e.update(type="delegation"), + lambda e: e.update(type="yatf/thing"), + lambda e: e.pop("time"), +]) +def test_what_a_reader_keeps_a_producer_may_not_write(change): + raw = copy.deepcopy(next(e for e in example_events() if e["type"] == "message")) + change(raw) + assert not VALIDATOR.is_valid(raw) + if "time" in raw: + yatf.parse_event(raw) + + +def test_extension_events_and_origins_are_open(): + vendor = {"seq": 0, "id": "0.0", "type": "claude-code/raw", "turn": 0, "actor": "agent", "observer": "agent", + "time": {"at": None}, "record": {"anything": [1, 2]}} + VALIDATOR.validate(vendor) + inbound = next(e for e in example_events() if e["type"] == "message" and e["actor"] == "user_sim") + assert "channel" in inbound["content"][0]["origin"] + VALIDATOR.validate(inbound) diff --git a/uv.lock b/uv.lock index 8635f3a2d..a875ad561 100644 --- a/uv.lock +++ b/uv.lock @@ -322,6 +322,7 @@ dev = [ { name = "av", version = "19.0.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" }, { name = "brotli" }, { name = "fastmcp" }, + { name = "jsonschema" }, { name = "mcp" }, { name = "pillow" }, { name = "pytest" }, @@ -353,6 +354,7 @@ requires-dist = [ { name = "brotli", marker = "extra == 'dev'", specifier = ">=1.2" }, { name = "fastmcp", marker = "extra == 'dev'", specifier = ">=3.4,<4" }, { name = "httpx", specifier = ">=0.27" }, + { name = "jsonschema", marker = "extra == 'dev'", specifier = ">=4.20" }, { name = "mcp", marker = "extra == 'agent'", specifier = ">=1.25,<2" }, { name = "mcp", marker = "extra == 'app'", specifier = ">=1.25,<2" }, { name = "mcp", marker = "extra == 'computer'", specifier = ">=1.25,<2" },