From 822dee67cb5b4481c1d0d9afdc1b309109b8820c Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Tue, 17 Nov 2026 13:43:32 -0800 Subject: [PATCH 1/7] feat(protocol): yatf/1's spec, models, reader and adapter framework (Y1a, FD-6075) Add agentenv_protocol.yatf: the yatf/1 spec (SPEC.md, version 1.0), its event models, a strict JSON schema generated from them and checked in, reader helpers, the adapter framework and the runner that feeds records through an adapter, plus the design's three worked examples, corrected, as the spec's fixtures. Nothing serves or reads yatf/1 yet. - Models are one tolerant tree: readers keep fields, event and part types and vocabulary values this version doesn't define, and write them back out unchanged. The checked-in schema is strict for producers. - Spec 1.0 defines the types slice 1 produces and reserves delegation, context, producer, activation and usage.checkpoint. - An adapter is an Adapter subclass declared with @yatf_adapter, whose @native, @aux and @finish methods write through a YatfTurn that stamps the envelope. One instance serves an A2A context; AdapterRun and replay make the same events from the same records, live or offline. - The package needs only the protocol's base dependencies. Co-Authored-By: Claude Opus 5.5 --- packages/agentenv-protocol/README.md | 78 + packages/agentenv-protocol/pyproject.toml | 1 + .../src/agentenv_protocol/yatf/SPEC.md | 201 + .../src/agentenv_protocol/yatf/__init__.py | 89 + .../src/agentenv_protocol/yatf/__main__.py | 20 + .../src/agentenv_protocol/yatf/adapter.py | 414 ++ .../yatf/examples/coding.json | 22 + .../yatf/examples/computer_use.json | 21 + .../yatf/examples/multi_agent.json | 12 + .../src/agentenv_protocol/yatf/models.py | 467 +++ .../src/agentenv_protocol/yatf/reader.py | 125 + .../src/agentenv_protocol/yatf/runner.py | 124 + .../src/agentenv_protocol/yatf/schema.py | 32 + .../agentenv_protocol/yatf/yatf-1.schema.json | 3344 +++++++++++++++++ .../tests/test_yatf_adapter.py | 306 ++ .../tests/test_yatf_examples.py | 52 + .../tests/test_yatf_models.py | 94 + .../tests/test_yatf_reader.py | 66 + .../tests/test_yatf_schema.py | 57 + uv.lock | 2 + 20 files changed, 5527 insertions(+) create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/yatf/SPEC.md create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/yatf/__init__.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/yatf/__main__.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/yatf/adapter.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/yatf/examples/coding.json create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/yatf/examples/computer_use.json create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/yatf/examples/multi_agent.json create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/yatf/models.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/yatf/reader.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/yatf/runner.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/yatf/schema.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/yatf/yatf-1.schema.json create mode 100644 packages/agentenv-protocol/tests/test_yatf_adapter.py create mode 100644 packages/agentenv-protocol/tests/test_yatf_examples.py create mode 100644 packages/agentenv-protocol/tests/test_yatf_models.py create mode 100644 packages/agentenv-protocol/tests/test_yatf_reader.py create mode 100644 packages/agentenv-protocol/tests/test_yatf_schema.py 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..d87129e89 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/SPEC.md @@ -0,0 +1,201 @@ +# 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. +- 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..b2eed402d --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/__init__.py @@ -0,0 +1,89 @@ +"""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, + TurnContext, + YatfTurn, + 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, + 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, 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", + "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..a5b6940fc --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/adapter.py @@ -0,0 +1,414 @@ +"""Writing a yatf/1 adapter: a class that turns an agent's native records into YATF events. It's declared with +``@yatf_adapter``, its ``@native``, ``@aux`` and ``@finish`` methods write through a YatfTurn, and one instance serves +an A2A context. It reads only what the run stores (the turn's context, its native records and its aux records), 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 Any, Callable, ClassVar, Iterable, Mapping, Sequence, TypeVar + +from pydantic import ValidationError + +from .models import ( + 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, +) + +#: 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._-]+$") +#: The step key of a turn's inbound message, ``in-``. +INBOUND_STEP = "in-{turn}" +_ENVELOPE = frozenset(Event.model_fields) +_MISSING = object() +_CURRENT: Any = 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, declared with ``@yatf_adapter``. One instance serves an A2A context across its turns, + so state on ``self`` carries over; per-turn state resets in the ``@finish`` method. A handler may hold an event + back until another record places it: capture ``turn.source`` and pass it as ``derived_from`` when it's emitted.""" + + 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) + + +@dataclass(frozen=True, kw_only=True) +class TurnContext: + """What the SDK knows of a turn from A2A, written into its frame: ``turn.start`` with the declared actors (by + default the agent and, with an inbound message, its sender), the inbound message from ``inbound_actor``, and + ``turn.end``. ``actor`` is the agent's own actor id, the default for every event the adapter writes.""" + + 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: + """Builds one turn's events. An adapter calls its methods and writes only what the native says; the turn stamps + ``seq``, ``id``, ``turn``, ``observer``, the actor (the agent's unless given), the attempt and ``derived_from`` + (the record being handled, unless given). Each method returns the event it emitted. Not thread-safe: records are + fed one at a time.""" + + def __init__(self, context: TurnContext, spec: AdapterSpec) -> 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._events: list[dict[str, Any]] = [] + self._drained = 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]]: + return list(self._events) + + 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) -> Message: + return self._emit(Message, "message", time, actor, derived_from, x, step=step, role=role, + content=_content(content, text)) + + 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) -> Reasoning: + return self._emit(Reasoning, "reasoning", time, actor, derived_from, x, step=step, visibility=visibility, + text=text, opaque=None if opaque is None else list(opaque)) + + 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) -> ToolCall: + return self._emit(ToolCall, "tool_call", time, actor, derived_from, x, ("arguments",), 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) + + 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) -> ToolResult: + return self._emit(ToolResult, "tool_result", time, actor, derived_from, x, step=step, + source_call_id=source_call_id, status=status, content=_content(content, text), + exit_code=exit_code) + + 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) -> StepEvent: + return self._emit(StepEvent, "step", time, actor, derived_from, x, 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=provider_ids, + first_token_at=first_token_at, sampling=sampling) + + 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) -> Tools: + return self._emit(Tools, "tools", time, actor, derived_from, x, mode=mode, tools=list(tools)) + + 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) -> ActorDeclared: + """Declare an actor that appears mid-turn, such as a sub-agent, before any event names it.""" + return self._emit(ActorDeclared, "actor", time, actor, derived_from, x, declared=declared) + + 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) -> ErrorEvent: + return self._emit(ErrorEvent, "error", time, actor, derived_from, x, step=step, error_type=error_type, + message=message, code=code, fatal=fatal) + + 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) -> Attempt: + """A harness retry within the task: this event and every later one carry ``attempt`` = ``number``.""" + self._attempt = number + return self._emit(Attempt, "attempt", time, actor, derived_from, x, number=number, reason=reason) + + def note(self, text: str, *, time: Any = None, actor: str | None = None, derived_from: Any = _CURRENT, + x: Mapping[str, Any] | None = None) -> Note: + return self._emit(Note, "note", time, actor, derived_from, x, text=text) + + def raw(self, record: Any, *, time: Any = None, actor: str | None = None, + derived_from: Any = _CURRENT) -> 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) + + 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) -> ExtensionEvent: + """An event of the ``/`` type ``kind``, with ``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, kind, time, actor, derived_from, x, **body) + + 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], event_type: str, time: Any, actor: str | None, derived_from: Any, + x: Mapping[str, Any] | None, nulls: tuple[str, ...] = (), /, **body: Any) -> Any: + source = self.source if derived_from is _CURRENT else derived_from + envelope: dict[str, Any] = {"seq": len(self._events), "id": f"{self.index}.{len(self._events)}", + "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) + fields = {key: value for key, value in body.items() if value is not None or key in nulls} + try: + event = model(**envelope, **fields) + except ValidationError as exc: + raise YatfError(f"{event_type} event: {exc}") from exc + self._events.append(dump_event(event)) + 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 []) + self._emit(TurnStart, "turn.start", context.started_at, None, None, None, ("usage_input_includes_cache",), + 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=AdapterInfo(name=self.spec.name, version=self.spec.version, + lossy=list(self.spec.lossy) or None), + usage_input_includes_cache=self.spec.usage_input_includes_cache, actors=actors) + if context.inbound is not None: + self._emit(Message, "message", context.started_at, context.inbound_actor, None, None, + step=INBOUND_STEP.format(turn=self.index), role="user", content=list(context.inbound)) + + def _end(self, state: str, final: Sequence[Any] | None, ended_at: str | None) -> None: + if final is not None: + self._emit(FinalResponse, "final_response", ended_at, None, None, None, content=list(final)) + calls = sum(1 for event in self._events if event["type"] == "tool_call") + self._emit(TurnEnd, "turn.end", ended_at, None, None, None, state=state, tool_call_count=calls, + final_metrics=self._final_metrics) + + def _drain(self) -> list[dict[str, Any]]: + new, self._drained = self._events[self._drained:], len(self._events) + return new 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..d96adf82f --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/models.py @@ -0,0 +1,467 @@ +"""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 re +from typing import Annotated, Any, ClassVar, Literal, Union + +from pydantic import BaseModel, ConfigDict, Discriminator, Tag, TypeAdapter, ValidationError, WithJsonSchema + +FORMAT = "yatf/1" +SPEC_VERSION = "1.0" + +CORE_TYPES = frozenset({ + "turn.start", "message", "final_response", "turn.end", "step", "reasoning", "tool_call", "tool_result", "tools", + "actor", "error", "attempt", "note", +}) +#: 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") +MEDIA_KINDS = ("image", "audio", "video", "document", "file") +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") + + +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.""" + + +class YatfModel(BaseModel): + """Keeps fields it doesn't know through a dump (the validator reports them); the strict schema forbids them.""" + + model_config = ConfigDict(extra="allow", protected_namespaces=(), json_schema_extra={"additionalProperties": False}) + #: 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 = ConfigDict(extra="allow", protected_namespaces=(), json_schema_extra={"additionalProperties": True}) + 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: Literal["image", "audio", "video", "document", "file"] + 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: 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: 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 = 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 = ConfigDict(extra="allow", protected_namespaces=(), json_schema_extra={"additionalProperties": True}) + 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 = ConfigDict(extra="allow", protected_namespaces=(), json_schema_extra={"additionalProperties": True}) + OPEN: ClassVar[bool] = True + + +EVENT_MODELS: dict[str, type[Event]] = { + "turn.start": TurnStart, "message": Message, "final_response": FinalResponse, "turn.end": TurnEnd, + "step": StepEvent, "reasoning": Reasoning, "tool_call": ToolCall, "tool_result": ToolResult, "tools": Tools, + "actor": ActorDeclared, "error": ErrorEvent, "attempt": Attempt, "note": Note, +} + + +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 parse_event(value: Any) -> Event: + """One event as its typed model; an unknown type parses as UnknownEvent and a namespaced one as ExtensionEvent.""" + 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, with exactly the fields it was given, unknown ones included.""" + return event.model_dump(mode="json", 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..b57b12a80 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/reader.py @@ -0,0 +1,125 @@ +"""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 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.""" + if isinstance(data, (bytes, bytearray)): + data = bytes(data).decode("utf-8") + if isinstance(data, str): + text = data.lstrip("") + if text.lstrip().startswith("["): + try: + items = json.loads(text) + except json.JSONDecodeError 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)) + except json.JSONDecodeError 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.""" + dumped = [dump_event(event) for event in events] + if jsonl: + return "".join(json.dumps(item, ensure_ascii=False, separators=(",", ":")) + "\n" for item in dumped) + return json.dumps(dumped, ensure_ascii=False, separators=(",", ":")) + + +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..346f64ea7 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/runner.py @@ -0,0 +1,124 @@ +"""Running an adapter: feed one A2A context's records through it, a turn at a time, and collect the events. 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 + +from dataclasses import dataclass +from typing import Any, Iterable, Mapping, Sequence + +from .adapter import Adapter, AdapterSpec, TurnContext, YatfTurn +from .models import DerivedFrom, Part, YatfError + + +@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, in order, so a live reader sees them as + they come; ``events`` holds every event so far.""" + + 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[dict[str, Any]] = [] + self._native = 0 + self._aux: dict[str, int] = {} + + @property + def events(self) -> list[dict[str, Any]]: + return list(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._turn, self._native, self._aux = turn, 0, {} + turn._start() + if self._adapter is None: + self._adapter = self._cls(turn) + return self._drain(turn) + + 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._drain(turn) + + 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._drain(turn) + + 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 + new = self._drain(turn) + return new + + 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 _drain(self, turn: YatfTurn) -> list[dict[str, Any]]: + new = turn._drain() + self._events.extend(new) + return new + + +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..287a54b58 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/yatf-1.schema.json @@ -0,0 +1,3344 @@ +{ + "$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": "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": "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" + } + ], + "default": 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" + ], + "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": "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..7cda38fdf --- /dev/null +++ b/packages/agentenv-protocol/tests/test_yatf_adapter.py @@ -0,0 +1,306 @@ +"""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 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_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 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..a2fd61613 --- /dev/null +++ b/packages/agentenv-protocol/tests/test_yatf_models.py @@ -0,0 +1,94 @@ +"""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 + +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} + + +@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("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..65e7b43cd --- /dev/null +++ b/packages/agentenv-protocol/tests/test_yatf_reader.py @@ -0,0 +1,66 @@ +"""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') + + +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..602019604 --- /dev/null +++ b/packages/agentenv-protocol/tests/test_yatf_schema.py @@ -0,0 +1,57 @@ +"""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(): + assert files("agentenv_protocol.yatf").joinpath(SCHEMA_FILE).read_text(encoding="utf-8") == schema_text() + + +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" }, From 4eee6557336d3a3fbf4bf7e03bcc907613984583 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Tue, 17 Nov 2026 13:51:44 -0800 Subject: [PATCH 2/7] fix(protocol): yatf readers take values as written and dump any text Found by chaos runs against the yatf package: - Models are strict: "5" or true is no longer coerced into an integer field, and NaN and infinity are refused, so whatever parses dumps back exactly. Cost fields take an int or a float, so 0 stays 0. - dump_event no longer encodes strings, so a lone surrogate in an unknown field or an Any value doesn't raise; dump_events escapes to ASCII, as the SDK writes native logs. - parse_events raises YatfError for input that isn't UTF-8, and refuses NaN and Infinity tokens. Co-Authored-By: Claude Opus 5.5 --- .../src/agentenv_protocol/yatf/SPEC.md | 5 +++- .../src/agentenv_protocol/yatf/adapter.py | 5 ++-- .../src/agentenv_protocol/yatf/models.py | 24 ++++++++++------- .../src/agentenv_protocol/yatf/reader.py | 27 ++++++++++++------- .../agentenv_protocol/yatf/yatf-1.schema.json | 9 +++++++ .../tests/test_yatf_models.py | 16 +++++++++++ .../tests/test_yatf_reader.py | 12 +++++++++ 7 files changed, 77 insertions(+), 21 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/SPEC.md b/packages/agentenv-protocol/src/agentenv_protocol/yatf/SPEC.md index d87129e89..60d2de5e5 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/yatf/SPEC.md +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/SPEC.md @@ -23,7 +23,10 @@ worked examples in `examples/` are its canonical fixtures. 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. +- 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. +- 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. diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/adapter.py b/packages/agentenv-protocol/src/agentenv_protocol/yatf/adapter.py index a5b6940fc..76748f310 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/yatf/adapter.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/adapter.py @@ -317,8 +317,9 @@ def step(self, *, key: str, source: str = "agent", llm_call_count: int | None = x: Mapping[str, Any] | None = None) -> StepEvent: return self._emit(StepEvent, "step", time, actor, derived_from, x, 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=provider_ids, - first_token_at=first_token_at, sampling=sampling) + 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)) 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) -> Tools: diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/models.py b/packages/agentenv-protocol/src/agentenv_protocol/yatf/models.py index d96adf82f..deff50fcb 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/yatf/models.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/models.py @@ -69,15 +69,18 @@ class YatfError(ValueError): class YatfModel(BaseModel): - """Keeps fields it doesn't know through a dump (the validator reports them); the strict schema forbids them.""" + """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 = ConfigDict(extra="allow", protected_namespaces=(), json_schema_extra={"additionalProperties": False}) + model_config = ConfigDict(extra="allow", strict=True, allow_inf_nan=False, protected_namespaces=(), + json_schema_extra={"additionalProperties": False}) #: 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 = ConfigDict(extra="allow", protected_namespaces=(), json_schema_extra={"additionalProperties": True}) + model_config = ConfigDict(extra="allow", strict=True, allow_inf_nan=False, protected_namespaces=(), + json_schema_extra={"additionalProperties": True}) OPEN: ClassVar[bool] = True @@ -234,7 +237,7 @@ class Metrics(YatfModel): cached_tokens: int | None = None cache_write_tokens: int | None = None reasoning_tokens: int | None = None - cost_usd: float | None = None + cost_usd: int | float | None = None cost_status: CostStatus | None = None cost_source: str | None = None raw: dict[str, Any] | None = None @@ -246,7 +249,7 @@ class UsageTotals(YatfModel): total_cached_tokens: int | None = None total_cache_write_tokens: int | None = None total_reasoning_tokens: int | None = None - total_cost_usd: float | None = None + total_cost_usd: int | float | None = None cost_status: CostStatus | None = None cost_source: str | None = None @@ -413,7 +416,8 @@ class Note(Event): class ExtensionEvent(Event): """A ``/`` type, such as an adapter's raw native record: readers keep it and may skip it.""" - model_config = ConfigDict(extra="allow", protected_namespaces=(), json_schema_extra={"additionalProperties": True}) + model_config = ConfigDict(extra="allow", strict=True, allow_inf_nan=False, protected_namespaces=(), + json_schema_extra={"additionalProperties": True}) OPEN: ClassVar[bool] = True type: Annotated[str, WithJsonSchema({"type": "string", "pattern": EXTENSION_TYPE.pattern})] @@ -421,7 +425,8 @@ class ExtensionEvent(Event): class UnknownEvent(Event): """An event type this version doesn't define: readers keep it, producers may not write it.""" - model_config = ConfigDict(extra="allow", protected_namespaces=(), json_schema_extra={"additionalProperties": True}) + model_config = ConfigDict(extra="allow", strict=True, allow_inf_nan=False, protected_namespaces=(), + json_schema_extra={"additionalProperties": True}) OPEN: ClassVar[bool] = True @@ -463,5 +468,6 @@ def parse_event(value: Any) -> Event: def dump_event(event: Event) -> dict[str, Any]: - """The event as JSON, with exactly the fields it was given, unknown ones included.""" - return event.model_dump(mode="json", exclude_unset=True) + """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 index b57b12a80..c70d39f1f 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/yatf/reader.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/reader.py @@ -13,16 +13,24 @@ 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.""" + """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)): - data = bytes(data).decode("utf-8") + 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) - except json.JSONDecodeError as exc: + items = json.loads(text, parse_constant=_strict_json) + except ValueError as exc: raise YatfError(f"not a JSON array: {exc}") from exc else: items = [] @@ -30,8 +38,8 @@ def parse_events(data: str | bytes | Iterable[Mapping[str, Any]]) -> list[Event] if not line.strip(): continue try: - items.append(json.loads(line)) - except json.JSONDecodeError as exc: + 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) @@ -47,11 +55,12 @@ def parse_events(data: str | bytes | Iterable[Mapping[str, Any]]) -> list[Event] def dump_events(events: Iterable[Event], *, jsonl: bool = True) -> str: - """Events as JSONL, one per line, or as one JSON array.""" + """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, ensure_ascii=False, separators=(",", ":")) + "\n" for item in dumped) - return json.dumps(dumped, ensure_ascii=False, separators=(",", ":")) + 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]: 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 index 287a54b58..1687f6c11 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/yatf/yatf-1.schema.json +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/yatf-1.schema.json @@ -961,6 +961,9 @@ }, "total_cost_usd": { "anyOf": [ + { + "type": "integer" + }, { "type": "number" }, @@ -1420,6 +1423,9 @@ }, "cost_usd": { "anyOf": [ + { + "type": "integer" + }, { "type": "number" }, @@ -3221,6 +3227,9 @@ }, "total_cost_usd": { "anyOf": [ + { + "type": "integer" + }, { "type": "number" }, diff --git a/packages/agentenv-protocol/tests/test_yatf_models.py b/packages/agentenv-protocol/tests/test_yatf_models.py index a2fd61613..17eb328f4 100644 --- a/packages/agentenv-protocol/tests/test_yatf_models.py +++ b/packages/agentenv-protocol/tests/test_yatf_models.py @@ -82,6 +82,22 @@ def test_a_non_event_is_refused(value): 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("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): diff --git a/packages/agentenv-protocol/tests/test_yatf_reader.py b/packages/agentenv-protocol/tests/test_yatf_reader.py index 65e7b43cd..16fedc204 100644 --- a/packages/agentenv-protocol/tests/test_yatf_reader.py +++ b/packages/agentenv-protocol/tests/test_yatf_reader.py @@ -28,6 +28,18 @@ def test_a_stream_that_is_not_json_says_where(): 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')) + + +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(): From 63370729512b3c1e2d6843dca76f5c9196c7daeb Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Tue, 17 Nov 2026 13:57:18 -0800 Subject: [PATCH 3/7] fix(protocol): yatf keeps explicit nulls, refuses non-JSON numbers, hands out copies From review: - YatfTurn.extension keeps every key of its body, None included, so raw(None) keeps its record; reasoning always writes text, null when it was withheld. - A NaN or infinity anywhere in an event is refused: parse_event checks unknown fields and Any values too (1e400 reads as infinity), and the builder refuses an event JSON can't write as it's emitted. - YatfTurn and AdapterRun keep events as JSON text and hand out fresh copies, so a caller editing a returned event can't change the stream. Co-Authored-By: Claude Opus 5.5 --- .../src/agentenv_protocol/yatf/adapter.py | 31 ++++++++++++------- .../src/agentenv_protocol/yatf/models.py | 17 +++++++++- .../src/agentenv_protocol/yatf/runner.py | 9 +++--- .../tests/test_yatf_adapter.py | 30 ++++++++++++++++++ .../tests/test_yatf_models.py | 6 ++++ .../tests/test_yatf_reader.py | 2 ++ 6 files changed, 78 insertions(+), 17 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/adapter.py b/packages/agentenv-protocol/src/agentenv_protocol/yatf/adapter.py index 76748f310..82f9f1c58 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/yatf/adapter.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/adapter.py @@ -4,6 +4,7 @@ offline replay makes the events the agent served live.""" from __future__ import annotations +import json import re from dataclasses import dataclass, field from typing import Any, Callable, ClassVar, Iterable, Mapping, Sequence, TypeVar @@ -258,16 +259,18 @@ def _content(content: Iterable[Any] | None, text: str | None) -> list[Any]: class YatfTurn: """Builds one turn's events. An adapter calls its methods and writes only what the native says; the turn stamps ``seq``, ``id``, ``turn``, ``observer``, the actor (the agent's unless given), the attempt and ``derived_from`` - (the record being handled, unless given). Each method returns the event it emitted. Not thread-safe: records are - fed one at a time.""" + (the record being handled, unless given). Each method returns the event it emitted. Events are kept as JSON text, + so what a reader is handed is a copy, and an event that isn't JSON is refused as it's written. Not thread-safe: + records are fed one at a time.""" def __init__(self, context: TurnContext, spec: AdapterSpec) -> 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._events: list[dict[str, Any]] = [] + self._events: list[str] = [] self._drained = 0 + self._calls = 0 self._attempt = 1 self._final_metrics: FinalMetrics | None = None @@ -277,7 +280,7 @@ def index(self) -> int: @property def events(self) -> list[dict[str, Any]]: - return list(self._events) + return [json.loads(text) for text in self._events] 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, @@ -289,8 +292,8 @@ def reasoning(self, *, visibility: str, step: str | None = None, text: str | Non 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) -> Reasoning: - return self._emit(Reasoning, "reasoning", time, actor, derived_from, x, step=step, visibility=visibility, - text=text, opaque=None if opaque is None else list(opaque)) + return self._emit(Reasoning, "reasoning", time, actor, derived_from, x, ("text",), step=step, + visibility=visibility, text=text, opaque=None if opaque is None else list(opaque)) 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, @@ -359,7 +362,7 @@ def extension(self, kind: str, body: Mapping[str, Any], *, time: Any = None, act 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, kind, time, actor, derived_from, x, **body) + return self._emit(ExtensionEvent, kind, time, actor, derived_from, x, tuple(body), **body) def final_metrics(self, metrics: FinalMetrics | Mapping[str, Any]) -> None: """The turn's totals, written into ``turn.end``.""" @@ -372,7 +375,8 @@ def final_metrics(self, metrics: FinalMetrics | Mapping[str, Any]) -> None: def _emit(self, model: type[Event], event_type: str, time: Any, actor: str | None, derived_from: Any, x: Mapping[str, Any] | None, nulls: tuple[str, ...] = (), /, **body: Any) -> Any: source = self.source if derived_from is _CURRENT else derived_from - envelope: dict[str, Any] = {"seq": len(self._events), "id": f"{self.index}.{len(self._events)}", + seq = len(self._events) + 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: @@ -384,9 +388,13 @@ def _emit(self, model: type[Event], event_type: str, time: Any, actor: str | Non fields = {key: value for key, value in body.items() if value is not None or key in nulls} 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 - self._events.append(dump_event(event)) + except (TypeError, ValueError) as exc: + raise YatfError(f"{event_type} event isn't JSON: {exc}") from exc + self._events.append(text) + self._calls += event_type == "tool_call" return event def _start(self) -> None: @@ -406,10 +414,9 @@ def _start(self) -> None: def _end(self, state: str, final: Sequence[Any] | None, ended_at: str | None) -> None: if final is not None: self._emit(FinalResponse, "final_response", ended_at, None, None, None, content=list(final)) - calls = sum(1 for event in self._events if event["type"] == "tool_call") - self._emit(TurnEnd, "turn.end", ended_at, None, None, None, state=state, tool_call_count=calls, + self._emit(TurnEnd, "turn.end", ended_at, None, None, None, state=state, tool_call_count=self._calls, final_metrics=self._final_metrics) - def _drain(self) -> list[dict[str, Any]]: + def _drain(self) -> list[str]: new, self._drained = self._events[self._drained:], len(self._events) return new diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/models.py b/packages/agentenv-protocol/src/agentenv_protocol/yatf/models.py index deff50fcb..20afd8651 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/yatf/models.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/models.py @@ -3,6 +3,7 @@ JSON schema generated from these models.""" from __future__ import annotations +import math import re from typing import Annotated, Any, ClassVar, Literal, Union @@ -459,8 +460,22 @@ def _event_tag(value: Any) -> str: _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.""" + """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: diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/runner.py b/packages/agentenv-protocol/src/agentenv_protocol/yatf/runner.py index 346f64ea7..d76604358 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/yatf/runner.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/runner.py @@ -2,6 +2,7 @@ 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 @@ -30,7 +31,7 @@ class RecordedTurn: class AdapterRun: """One A2A context's conversion. Each call returns the events it emitted, in order, so a live reader sees them as - they come; ``events`` holds every event so far.""" + they come; ``events`` holds every event so far. 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") @@ -40,13 +41,13 @@ def __init__(self, adapter: type[Adapter]) -> None: self._spec = spec self._adapter: Adapter | None = None self._turn: YatfTurn | None = None - self._events: list[dict[str, Any]] = [] + self._events: list[str] = [] self._native = 0 self._aux: dict[str, int] = {} @property def events(self) -> list[dict[str, Any]]: - return list(self._events) + 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.""" @@ -107,7 +108,7 @@ def _handle(self, turn: YatfTurn, source: DerivedFrom, method: str, record: Any) def _drain(self, turn: YatfTurn) -> list[dict[str, Any]]: new = turn._drain() self._events.extend(new) - return new + return [json.loads(text) for text in new] def replay(adapter: type[Adapter], turns: Iterable[RecordedTurn]) -> list[dict[str, Any]]: diff --git a/packages/agentenv-protocol/tests/test_yatf_adapter.py b/packages/agentenv-protocol/tests/test_yatf_adapter.py index 7cda38fdf..66479488a 100644 --- a/packages/agentenv-protocol/tests/test_yatf_adapter.py +++ b/packages/agentenv-protocol/tests/test_yatf_adapter.py @@ -225,6 +225,36 @@ def test_extension_events_are_namespaced_outside_yatf(): turn.message(role="assistant", content=[{"type": "text"}]) +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] + + def adapter_class(**declared): options = {"native_format": "toy-events/1", "version": "0.1.0", "usage_input_includes_cache": None, **declared} diff --git a/packages/agentenv-protocol/tests/test_yatf_models.py b/packages/agentenv-protocol/tests/test_yatf_models.py index 17eb328f4..3775afba6 100644 --- a/packages/agentenv-protocol/tests/test_yatf_models.py +++ b/packages/agentenv-protocol/tests/test_yatf_models.py @@ -98,6 +98,12 @@ def test_a_number_dumps_as_it_was_written_and_nan_is_refused(): 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}) + + @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): diff --git a/packages/agentenv-protocol/tests/test_yatf_reader.py b/packages/agentenv-protocol/tests/test_yatf_reader.py index 16fedc204..a70bbb77d 100644 --- a/packages/agentenv-protocol/tests/test_yatf_reader.py +++ b/packages/agentenv-protocol/tests/test_yatf_reader.py @@ -32,6 +32,8 @@ def test_a_stream_that_is_not_json_says_where(): 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(): From 0fc406b99042c52a39b6c96b94cc72174a67dff0 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Tue, 17 Nov 2026 14:01:56 -0800 Subject: [PATCH 4/7] docs(protocol): yatf field names are valid Unicode, as I-JSON requires A chaos run found that a field name holding a lone surrogate at a typed level is refused, while values may hold one. The spec now says so and a test pins it: a native log that cut an emoji in half still reads. Co-Authored-By: Claude Opus 5.5 --- .../agentenv-protocol/src/agentenv_protocol/yatf/SPEC.md | 3 ++- packages/agentenv-protocol/tests/test_yatf_models.py | 7 +++++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/SPEC.md b/packages/agentenv-protocol/src/agentenv_protocol/yatf/SPEC.md index 60d2de5e5..1dc414ff7 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/yatf/SPEC.md +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/SPEC.md @@ -24,7 +24,8 @@ worked examples in `examples/` are its canonical fixtures. - 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. + with no NaN or Infinity. A field name is valid Unicode, with no lone surrogate, as I-JSON (RFC 7493) requires. A + string value may hold one, 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`. diff --git a/packages/agentenv-protocol/tests/test_yatf_models.py b/packages/agentenv-protocol/tests/test_yatf_models.py index 3775afba6..7f85e2561 100644 --- a/packages/agentenv-protocol/tests/test_yatf_models.py +++ b/packages/agentenv-protocol/tests/test_yatf_models.py @@ -76,6 +76,13 @@ def test_a_dump_writes_only_the_fields_the_event_was_given(): 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"]}) + 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): From b91771c5985263f4fbb3dcd3a6ff3f25a43cd139 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Tue, 17 Nov 2026 14:05:25 -0800 Subject: [PATCH 5/7] docs(protocol): the yatf Unicode rule covers the names the spec defines From review: the rule against lone surrogates covers the names of an event's fields and of the objects the spec defines, known or not, not keys inside free JSON (arguments, x, a raw record). The test now pins a surrogate key under x as kept too. Co-Authored-By: Claude Opus 5.5 --- .../agentenv-protocol/src/agentenv_protocol/yatf/SPEC.md | 7 +++++-- packages/agentenv-protocol/tests/test_yatf_models.py | 2 +- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/SPEC.md b/packages/agentenv-protocol/src/agentenv_protocol/yatf/SPEC.md index 1dc414ff7..2084c4847 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/yatf/SPEC.md +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/SPEC.md @@ -24,8 +24,11 @@ worked examples in `examples/` are its canonical fixtures. - 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. A field name is valid Unicode, with no lone surrogate, as I-JSON (RFC 7493) requires. A - string value may hold one, as a native log that cut an emoji in half can. + 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`. diff --git a/packages/agentenv-protocol/tests/test_yatf_models.py b/packages/agentenv-protocol/tests/test_yatf_models.py index 7f85e2561..c94d6afd4 100644 --- a/packages/agentenv-protocol/tests/test_yatf_models.py +++ b/packages/agentenv-protocol/tests/test_yatf_models.py @@ -77,7 +77,7 @@ def test_a_dump_writes_only_the_fields_the_event_was_given(): def test_a_lone_surrogate_may_be_in_a_value_but_not_a_field_name(): - kept = event("note", text="cut \ud83d", later={"\ud800": ["\udfff"]}) + 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}) From ba8fa0ba0ac705888f5fdb50c48a339efba7f9b4 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Tue, 17 Nov 2026 16:26:18 -0800 Subject: [PATCH 6/7] refactor(protocol): yatf keeps each list once and the turn beside its runner From a maintainability pass over the yatf package: - runner.py now holds TurnContext, YatfTurn and the frame it writes, beside AdapterRun, which owns the one event buffer the turn writes into. adapter.py is only the authoring API, so nothing reaches into another module's private methods. - YatfTurn's _emit takes the body as a dict and the rest by keyword. Whether a None is written as null follows the model: a required field or an extension's own key keeps it, an optional field leaves it out. Reasoning.text is required, so withheld text is always null. - Builder methods can set is_copied_context, ATIF's flag for replayed context, which no adapter could set before. - EVENT_MODELS and CORE_TYPES come from the models' own type literals, MEDIA_KINDS from MediaPart's Literal, and the two model configs are defined once. VOCABULARIES lists every vocabulary. - New guards: every builder method takes every field of its model and every envelope field an adapter may set; SPEC.md names every type and vocabulary value; a stale schema fails with the command that regenerates it. Co-Authored-By: Claude Opus 5.5 --- .../src/agentenv_protocol/yatf/__init__.py | 18 +- .../src/agentenv_protocol/yatf/adapter.py | 253 +-------------- .../src/agentenv_protocol/yatf/models.py | 47 +-- .../src/agentenv_protocol/yatf/runner.py | 292 +++++++++++++++++- .../agentenv_protocol/yatf/yatf-1.schema.json | 4 +- .../tests/test_yatf_adapter.py | 21 ++ .../tests/test_yatf_models.py | 8 + .../tests/test_yatf_schema.py | 5 +- 8 files changed, 354 insertions(+), 294 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/__init__.py b/packages/agentenv-protocol/src/agentenv_protocol/yatf/__init__.py index b2eed402d..29aaf35bc 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/yatf/__init__.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/__init__.py @@ -1,18 +1,7 @@ """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, - TurnContext, - YatfTurn, - aux, - finish, - native, - yatf_adapter, -) +from .adapter import Adapter, AdapterSpec, Native, Selector, aux, finish, native, yatf_adapter from .models import ( CORE_TYPES, EVENT_MODELS, @@ -55,6 +44,7 @@ UnknownEvent, UnknownPart, UsageTotals, + VOCABULARIES, VirtualTime, YatfError, YatfModel, @@ -73,7 +63,7 @@ pair_tool_calls, parse_events, ) -from .runner import AdapterRun, Fed, RecordedTurn, replay +from .runner import AdapterRun, Fed, RecordedTurn, TurnContext, YatfTurn, replay from .schema import json_schema, load_schema __all__ = [ @@ -83,7 +73,7 @@ "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", - "VirtualTime", "YatfError", "YatfModel", "YatfTurn", "aux", "dump_event", "dump_events", "finish", + "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/adapter.py b/packages/agentenv-protocol/src/agentenv_protocol/yatf/adapter.py index 82f9f1c58..db9501a4a 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/yatf/adapter.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/adapter.py @@ -1,54 +1,20 @@ -"""Writing a yatf/1 adapter: a class that turns an agent's native records into YATF events. It's declared with -``@yatf_adapter``, its ``@native``, ``@aux`` and ``@finish`` methods write through a YatfTurn, and one instance serves -an A2A context. It reads only what the run stores (the turn's context, its native records and its aux records), so an -offline replay makes the events the agent served live.""" +"""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 json import re from dataclasses import dataclass, field -from typing import Any, Callable, ClassVar, Iterable, Mapping, Sequence, TypeVar - -from pydantic import ValidationError - -from .models import ( - 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, -) +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._-]+$") -#: The step key of a turn's inbound message, ``in-``. -INBOUND_STEP = "in-{turn}" -_ENVELOPE = frozenset(Event.model_fields) _MISSING = object() -_CURRENT: Any = object() A = TypeVar("A", bound="Adapter") @@ -202,9 +168,8 @@ def declare(cls: type[A]) -> type[A]: class Adapter: - """Base of a yatf/1 adapter, declared with ``@yatf_adapter``. One instance serves an A2A context across its turns, - so state on ``self`` carries over; per-turn state resets in the ``@finish`` method. A handler may hold an event - back until another record places it: capture ``turn.source`` and pass it as ``derived_from`` when it's emitted.""" + """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] @@ -224,199 +189,3 @@ def from_yatf(cls, events: list[Event]) -> Native: def normal_form(cls, records: list[Any]) -> list[Any]: """What the round trip compares: by default the parsed records themselves.""" return list(records) - - -@dataclass(frozen=True, kw_only=True) -class TurnContext: - """What the SDK knows of a turn from A2A, written into its frame: ``turn.start`` with the declared actors (by - default the agent and, with an inbound message, its sender), the inbound message from ``inbound_actor``, and - ``turn.end``. ``actor`` is the agent's own actor id, the default for every event the adapter writes.""" - - 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: - """Builds one turn's events. An adapter calls its methods and writes only what the native says; the turn stamps - ``seq``, ``id``, ``turn``, ``observer``, the actor (the agent's unless given), the attempt and ``derived_from`` - (the record being handled, unless given). Each method returns the event it emitted. Events are kept as JSON text, - so what a reader is handed is a copy, and an event that isn't JSON is refused as it's written. Not thread-safe: - records are fed one at a time.""" - - def __init__(self, context: TurnContext, spec: AdapterSpec) -> 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._events: list[str] = [] - self._drained = 0 - 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]]: - return [json.loads(text) for text in self._events] - - 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) -> Message: - return self._emit(Message, "message", time, actor, derived_from, x, step=step, role=role, - content=_content(content, text)) - - 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) -> Reasoning: - return self._emit(Reasoning, "reasoning", time, actor, derived_from, x, ("text",), step=step, - visibility=visibility, text=text, opaque=None if opaque is None else list(opaque)) - - 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) -> ToolCall: - return self._emit(ToolCall, "tool_call", time, actor, derived_from, x, ("arguments",), 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) - - 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) -> ToolResult: - return self._emit(ToolResult, "tool_result", time, actor, derived_from, x, step=step, - source_call_id=source_call_id, status=status, content=_content(content, text), - exit_code=exit_code) - - 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) -> StepEvent: - return self._emit(StepEvent, "step", time, actor, derived_from, x, 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)) - - 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) -> Tools: - return self._emit(Tools, "tools", time, actor, derived_from, x, mode=mode, tools=list(tools)) - - 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) -> ActorDeclared: - """Declare an actor that appears mid-turn, such as a sub-agent, before any event names it.""" - return self._emit(ActorDeclared, "actor", time, actor, derived_from, x, declared=declared) - - 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) -> ErrorEvent: - return self._emit(ErrorEvent, "error", time, actor, derived_from, x, step=step, error_type=error_type, - message=message, code=code, fatal=fatal) - - 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) -> Attempt: - """A harness retry within the task: this event and every later one carry ``attempt`` = ``number``.""" - self._attempt = number - return self._emit(Attempt, "attempt", time, actor, derived_from, x, number=number, reason=reason) - - def note(self, text: str, *, time: Any = None, actor: str | None = None, derived_from: Any = _CURRENT, - x: Mapping[str, Any] | None = None) -> Note: - return self._emit(Note, "note", time, actor, derived_from, x, text=text) - - def raw(self, record: Any, *, time: Any = None, actor: str | None = None, - derived_from: Any = _CURRENT) -> 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) - - 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) -> ExtensionEvent: - """An event of the ``/`` type ``kind``, with ``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, kind, time, actor, derived_from, x, tuple(body), **body) - - 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], event_type: str, time: Any, actor: str | None, derived_from: Any, - x: Mapping[str, Any] | None, nulls: tuple[str, ...] = (), /, **body: Any) -> Any: - source = self.source if derived_from is _CURRENT else derived_from - seq = len(self._events) - 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) - fields = {key: value for key, value in body.items() if value is not None or key in nulls} - 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._events.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 []) - self._emit(TurnStart, "turn.start", context.started_at, None, None, None, ("usage_input_includes_cache",), - 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=AdapterInfo(name=self.spec.name, version=self.spec.version, - lossy=list(self.spec.lossy) or None), - usage_input_includes_cache=self.spec.usage_input_includes_cache, actors=actors) - if context.inbound is not None: - self._emit(Message, "message", context.started_at, context.inbound_actor, None, None, - step=INBOUND_STEP.format(turn=self.index), role="user", content=list(context.inbound)) - - def _end(self, state: str, final: Sequence[Any] | None, ended_at: str | None) -> None: - if final is not None: - self._emit(FinalResponse, "final_response", ended_at, None, None, None, content=list(final)) - self._emit(TurnEnd, "turn.end", ended_at, None, None, None, state=state, tool_call_count=self._calls, - final_metrics=self._final_metrics) - - def _drain(self) -> list[str]: - new, self._drained = self._events[self._drained:], len(self._events) - return new diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/models.py b/packages/agentenv-protocol/src/agentenv_protocol/yatf/models.py index 20afd8651..782eb8865 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/yatf/models.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/models.py @@ -5,17 +5,13 @@ import math import re -from typing import Annotated, Any, ClassVar, Literal, Union +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" -CORE_TYPES = frozenset({ - "turn.start", "message", "final_response", "turn.end", "step", "reasoning", "tool_call", "tool_result", "tools", - "actor", "error", "attempt", "note", -}) #: 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. @@ -26,7 +22,8 @@ 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") -MEDIA_KINDS = ("image", "audio", "video", "document", "file") +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") @@ -39,6 +36,15 @@ 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: @@ -69,19 +75,22 @@ 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 = ConfigDict(extra="allow", strict=True, allow_inf_nan=False, protected_namespaces=(), - json_schema_extra={"additionalProperties": False}) + 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 = ConfigDict(extra="allow", strict=True, allow_inf_nan=False, protected_namespaces=(), - json_schema_extra={"additionalProperties": True}) + model_config = _OPEN OPEN: ClassVar[bool] = True @@ -149,7 +158,7 @@ class RefPart(YatfModel): class MediaPart(YatfModel): - type: Literal["image", "audio", "video", "document", "file"] + type: MediaKind source: Source purpose: str | None = None origin: Origin | None = None @@ -352,7 +361,7 @@ class StepEvent(Event): class Reasoning(Event): type: Literal["reasoning"] visibility: Visibility - text: str | None = None + text: str | None opaque: list[Opaque] | None = None @@ -417,8 +426,7 @@ class Note(Event): class ExtensionEvent(Event): """A ``/`` type, such as an adapter's raw native record: readers keep it and may skip it.""" - model_config = ConfigDict(extra="allow", strict=True, allow_inf_nan=False, protected_namespaces=(), - json_schema_extra={"additionalProperties": True}) + model_config = _OPEN OPEN: ClassVar[bool] = True type: Annotated[str, WithJsonSchema({"type": "string", "pattern": EXTENSION_TYPE.pattern})] @@ -426,16 +434,17 @@ class ExtensionEvent(Event): class UnknownEvent(Event): """An event type this version doesn't define: readers keep it, producers may not write it.""" - model_config = ConfigDict(extra="allow", strict=True, allow_inf_nan=False, protected_namespaces=(), - json_schema_extra={"additionalProperties": True}) + 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]] = { - "turn.start": TurnStart, "message": Message, "final_response": FinalResponse, "turn.end": TurnEnd, - "step": StepEvent, "reasoning": Reasoning, "tool_call": ToolCall, "tool_result": ToolResult, "tools": Tools, - "actor": ActorDeclared, "error": ErrorEvent, "attempt": Attempt, "note": Note, + 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: diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/runner.py b/packages/agentenv-protocol/src/agentenv_protocol/yatf/runner.py index d76604358..c35991e1c 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/yatf/runner.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/runner.py @@ -1,13 +1,273 @@ -"""Running an adapter: feed one A2A context's records through it, a turn at a time, and collect the events. 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.""" +"""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 .adapter import Adapter, AdapterSpec, TurnContext, YatfTurn -from .models import DerivedFrom, Part, YatfError +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. 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._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, as fresh copies.""" + return [json.loads(text) for text in self._out[self._first:]] + + 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] + 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) @dataclass(frozen=True) @@ -30,8 +290,8 @@ class RecordedTurn: class AdapterRun: - """One A2A context's conversion. Each call returns the events it emitted, in order, so a live reader sees them as - they come; ``events`` holds every event so far. Every read is a fresh copy, so a caller can't rewrite history.""" + """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") @@ -42,6 +302,7 @@ def __init__(self, adapter: type[Adapter]) -> None: 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] = {} @@ -53,19 +314,19 @@ 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) + 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._drain(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._drain(turn) + return self._page() def aux(self, name: str, record: Any) -> list[dict[str, Any]]: """Feed the turn's next record of aux file ``name``.""" @@ -77,7 +338,7 @@ def aux(self, name: str, record: Any) -> list[dict[str, Any]]: method = self._spec.handler(name, record) if method is not None: self._handle(turn, DerivedFrom(index=index, aux=name), method, record) - return self._drain(turn) + 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]]: @@ -90,8 +351,8 @@ def end_turn(self, *, state: str = "completed", final: Sequence[Part | Mapping[s finally: turn._end(state, final, ended_at) self._turn = None - new = self._drain(turn) - return new + page = self._page() + return page def _open(self) -> YatfTurn: if self._turn is None: @@ -105,10 +366,9 @@ def _handle(self, turn: YatfTurn, source: DerivedFrom, method: str, record: Any) finally: turn.source = None - def _drain(self, turn: YatfTurn) -> list[dict[str, Any]]: - new = turn._drain() - self._events.extend(new) - return [json.loads(text) for text in new] + 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]]: 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 index 1687f6c11..7e25f4207 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/yatf/yatf-1.schema.json +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/yatf-1.schema.json @@ -1748,7 +1748,6 @@ "type": "null" } ], - "default": null, "title": "Text" }, "time": { @@ -1795,7 +1794,8 @@ "actor", "observer", "time", - "visibility" + "visibility", + "text" ], "title": "Reasoning", "type": "object" diff --git a/packages/agentenv-protocol/tests/test_yatf_adapter.py b/packages/agentenv-protocol/tests/test_yatf_adapter.py index 66479488a..c715d570f 100644 --- a/packages/agentenv-protocol/tests/test_yatf_adapter.py +++ b/packages/agentenv-protocol/tests/test_yatf_adapter.py @@ -1,5 +1,7 @@ """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 @@ -225,6 +227,13 @@ def test_extension_events_are_namespaced_outside_yatf(): 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}) @@ -255,6 +264,18 @@ def test_what_a_run_hands_out_is_a_copy(): 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} diff --git a/packages/agentenv-protocol/tests/test_yatf_models.py b/packages/agentenv-protocol/tests/test_yatf_models.py index c94d6afd4..4a2b9c592 100644 --- a/packages/agentenv-protocol/tests/test_yatf_models.py +++ b/packages/agentenv-protocol/tests/test_yatf_models.py @@ -1,6 +1,7 @@ """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 @@ -111,6 +112,13 @@ def test_a_number_json_cannot_write_is_refused_anywhere_in_an_event(later): 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): diff --git a/packages/agentenv-protocol/tests/test_yatf_schema.py b/packages/agentenv-protocol/tests/test_yatf_schema.py index 602019604..a6d6304f6 100644 --- a/packages/agentenv-protocol/tests/test_yatf_schema.py +++ b/packages/agentenv-protocol/tests/test_yatf_schema.py @@ -18,7 +18,10 @@ def example_events(): def test_the_checked_in_schema_is_the_generated_one(): - assert files("agentenv_protocol.yatf").joinpath(SCHEMA_FILE).read_text(encoding="utf-8") == schema_text() + 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(): From acb1d1692e13f5d36ef130bdc568e042be61bd5e Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Tue, 17 Nov 2026 16:48:13 -0800 Subject: [PATCH 7/7] fix(protocol): a closed yatf turn keeps only its own events and takes no more From review: AdapterRun hands each turn its one shared buffer, so a closed turn's events ran on into later turns. The turn now records where it ended, its events stop there, and writing through a closed turn, such as one an adapter kept from an earlier handler, raises instead of landing in another turn with the wrong seq. Co-Authored-By: Claude Opus 5.5 --- .../src/agentenv_protocol/yatf/runner.py | 11 +++++++--- .../tests/test_yatf_adapter.py | 20 +++++++++++++++++++ 2 files changed, 28 insertions(+), 3 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/yatf/runner.py b/packages/agentenv-protocol/src/agentenv_protocol/yatf/runner.py index c35991e1c..bdbed6f14 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/yatf/runner.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/yatf/runner.py @@ -81,7 +81,8 @@ def _content(content: Iterable[Any] | None, text: str | None) -> list[Any]: 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. Not thread-safe: records are fed one at a time.""" + 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 @@ -90,6 +91,7 @@ def __init__(self, context: TurnContext, spec: AdapterSpec, out: list[str] | Non 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 @@ -100,8 +102,8 @@ def index(self) -> int: @property def events(self) -> list[dict[str, Any]]: - """This turn's events so far, as fresh copies.""" - return [json.loads(text) for text in self._out[self._first:]] + """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, @@ -223,6 +225,8 @@ def _emit(self, model: type[Event], body: dict[str, Any], *, time: Any = None, a """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, @@ -268,6 +272,7 @@ def _end(self, state: str, final: Sequence[Any] | None, ended_at: str | 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) diff --git a/packages/agentenv-protocol/tests/test_yatf_adapter.py b/packages/agentenv-protocol/tests/test_yatf_adapter.py index c715d570f..33ec939ac 100644 --- a/packages/agentenv-protocol/tests/test_yatf_adapter.py +++ b/packages/agentenv-protocol/tests/test_yatf_adapter.py @@ -179,6 +179,26 @@ def test_a_live_run_and_a_replay_of_its_records_make_the_same_events(): 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)])