From eae394aede7b16b31b3b13d258600b84c2caac86 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 09:38:39 -0800 Subject: [PATCH 1/7] feat(protocol): ATIF in agentenv_protocol: Harbor's models vendored, the agentenv profile and the adapter framework (Y1a, FD-6075) agentenv records agent trajectories as ATIF v1.8 with an optional extra.agentenv profile (FD-6074, Decision 7), replacing the yatf/1 plan of the closed #748. - atif.models: Harbor 0.26.0's 11 model files, changed only in import paths, with Harbor's Apache-2.0 license and VENDORED.md (each upstream file's sha256); scripts/vendor_atif.py re-vendors them from a named release. - profile.py and PROFILE.md: profile 1.0, every field optional and ignorable by plain ATIF readers. - adapter.py, builder.py, runner.py: @atif_adapter with @native, @aux and @finish; a typed step builder that closes steps, keeps results in their call's step with a late one's arrival, writes usage in ATIF's terms, embeds sub-agents, stores media at media/., wraps non-object arguments as Harbor does and normalizes timestamps; a runner that writes each task's user step, the final response once and the terminal state on the task's last step, and serves closed steps live. - reader.py: load, tasks, media_paths, strip_profile, is_prefix, for documents with or without the profile. - fixtures/: seven canonical cases built through the framework from a toy format, plus one stripped of the profile. Co-Authored-By: Claude Opus 5.5 --- packages/agentenv-protocol/README.md | 39 ++ .../src/agentenv_protocol/atif/PROFILE.md | 144 ++++ .../src/agentenv_protocol/atif/__init__.py | 59 ++ .../src/agentenv_protocol/atif/adapter.py | 178 +++++ .../src/agentenv_protocol/atif/builder.py | 661 ++++++++++++++++++ .../atif/fixtures/coding.json | 229 ++++++ .../atif/fixtures/coding.stripped.json | 155 ++++ .../atif/fixtures/computer_use.json | 246 +++++++ .../atif/fixtures/late_result.json | 145 ++++ ...a7a100637507670576fa73a20ad5420d55c66f.png | 1 + ...e3fdfda68478bb4e9bd24d481ef391c7804e8.heic | 1 + ...14de0396618b29b4238b9af5207aeb69936e6d.mp4 | 1 + ...cc4275b39fc0434aa6483a9f58b66ef2f3c896.png | 1 + ...0d1cb9a7af2f474cecd82e8d371e8384d72315.png | 1 + ...c278ac09a7230d61e5dfd2e1b1fbb436ac8917.pdf | Bin 0 -> 6 bytes .../atif/fixtures/multi_agent.json | 118 ++++ .../atif/fixtures/odd_parts.json | 182 +++++ .../atif/fixtures/subagent.json | 171 +++++ .../atif/fixtures/two_turns.json | 301 ++++++++ .../src/agentenv_protocol/atif/models/LICENSE | 201 ++++++ .../agentenv_protocol/atif/models/VENDORED.md | 23 + .../agentenv_protocol/atif/models/__init__.py | 35 + .../agentenv_protocol/atif/models/agent.py | 32 + .../agentenv_protocol/atif/models/content.py | 156 +++++ .../atif/models/final_metrics.py | 40 ++ .../agentenv_protocol/atif/models/metrics.py | 44 ++ .../atif/models/observation.py | 16 + .../atif/models/observation_result.py | 42 ++ .../src/agentenv_protocol/atif/models/step.py | 139 ++++ .../atif/models/subagent_trajectory_ref.py | 85 +++ .../atif/models/tool_call.py | 31 + .../atif/models/trajectory.py | 206 ++++++ .../src/agentenv_protocol/atif/profile.py | 167 +++++ .../src/agentenv_protocol/atif/reader.py | 145 ++++ .../src/agentenv_protocol/atif/runner.py | 126 ++++ .../agentenv-protocol/tests/atif_cases.py | 261 +++++++ .../tests/test_atif_builder.py | 344 +++++++++ .../tests/test_atif_fixtures.py | 46 ++ .../tests/test_atif_profile.py | 51 ++ .../tests/test_atif_reader.py | 62 ++ .../tests/test_atif_vendored.py | 50 ++ scripts/vendor_atif.py | 115 +++ 42 files changed, 5050 insertions(+) create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/__init__.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/adapter.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/coding.json create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/coding.stripped.json create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/computer_use.json create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/late_result.json create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/media/482405b002a62efa8516c36709a7a100637507670576fa73a20ad5420d55c66f.png create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/media/55c64d0fcd6f9d5f7c828093857e3fdfda68478bb4e9bd24d481ef391c7804e8.heic create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/media/67905ad3cc2dd52b1f5f6a6d2814de0396618b29b4238b9af5207aeb69936e6d.mp4 create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/media/69a8aa01fe5537076d023dd5e9cc4275b39fc0434aa6483a9f58b66ef2f3c896.png create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/media/82e60066a2de261b6653bcdda90d1cb9a7af2f474cecd82e8d371e8384d72315.png create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/media/845e91831319e89c4d656bdb80c278ac09a7230d61e5dfd2e1b1fbb436ac8917.pdf create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/multi_agent.json create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/odd_parts.json create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/subagent.json create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/two_turns.json create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/models/LICENSE create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/models/VENDORED.md create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/models/__init__.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/models/agent.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/models/content.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/models/final_metrics.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/models/metrics.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/models/observation.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/models/observation_result.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/models/step.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/models/subagent_trajectory_ref.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/models/tool_call.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/models/trajectory.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/profile.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/reader.py create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/atif/runner.py create mode 100644 packages/agentenv-protocol/tests/atif_cases.py create mode 100644 packages/agentenv-protocol/tests/test_atif_builder.py create mode 100644 packages/agentenv-protocol/tests/test_atif_fixtures.py create mode 100644 packages/agentenv-protocol/tests/test_atif_profile.py create mode 100644 packages/agentenv-protocol/tests/test_atif_reader.py create mode 100644 packages/agentenv-protocol/tests/test_atif_vendored.py create mode 100644 scripts/vendor_atif.py diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index 75aaead43..cb6d54056 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1253,6 +1253,45 @@ are the profile's template. The base class adds: - **Its skill**: sites by their real names, files to upload in `~/Uploads` and downloads in `~/Downloads`, folders it makes. +## Agent trajectories: ATIF + +`agentenv_protocol.atif` is the record every agent serves beside its native log, as format `atif/1`: +[ATIF v1.8](https://github.com/harbor-framework/harbor/blob/main/rfcs/0001-trajectory-format.md), Harbor's Agent +Trajectory Interchange Format, plus agentenv's optional `extra.agentenv` profile. A document without the profile is +still correct ATIF that means the same, so Harbor's tools read every document as is. `PROFILE.md` beside the module is +the profile's spec, and `fixtures/` holds its canonical examples. The package needs only the base dependencies. + +- **The models** are Harbor 0.26.0's own, vendored in `atif.models` and changed only in import paths (Harbor is + Apache-2.0; its license is beside them). `python scripts/vendor_atif.py ` refreshes them. +- **An adapter** turns an agent's native records into ATIF steps. It's a class declared with `@atif_adapter`, whose + `@native`, `@aux` and `@finish` methods write through the typed step builder they're handed: + + ```python + from agentenv_protocol.atif import Adapter, atif_adapter, native + + @atif_adapter(native_format="my-cli-events/1", version="0.1.0", usage_input_includes_cache=False) + class MyCliAtif(Adapter): + @native(type="assistant") + def assistant(self, record, turn): + turn.message(step=record["id"], text=record["text"]) + turn.step(key=record["id"], model_name=record["model"], input_tokens=record["in"], + cache_read_tokens=record["cache_read"], output_tokens=record["out"]) + + @native(type="tool_result") + def result(self, record, turn): + turn.tool_result(source_call_id=record["call_id"], text=record["output"]) + ``` + + The builder closes a step when the next one starts, puts every result in its call's step, writes `prompt_tokens` + with the cache included, stores media at `media/.`, embeds sub-agents and normalizes timestamps. A + record no method takes is counted in the root profile. +- **The runner** (`AdapterRun`, `replay`) feeds one A2A context's records through one adapter instance, a task at a + time. It writes each task's user step from its `TurnContext`, and the final response once, with the task's + terminal state on its last step. After every record it gives the live view: closed steps only, so a reader's earlier + page is always a prefix of a later one. +- **Readers** (`load`, `tasks`, `media_paths`, `strip_profile`, `is_prefix`) take any valid ATIF document, with or + without the profile, such as a Harbor task's trajectory.json. + ## A2A agent framework The distribution exposes two unrelated decorators named `extension`: diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md b/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md new file mode 100644 index 000000000..7c4baa2b5 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md @@ -0,0 +1,144 @@ +# The agentenv profile of ATIF + +Profile 1.0. agentenv records what an agent did as an ATIF v1.8 document: Harbor's +[Agent Trajectory Interchange Format](https://github.com/harbor-framework/harbor/blob/main/rfcs/0001-trajectory-format.md), +whose models are vendored in `models/`. An agent serves it as format `atif/1`, beside its native log. What ATIF has no +typed field for, agentenv adds under `extra.agentenv` on the objects that have an `extra`. This file is the profile's spec. + +## The rule + +- Typed fields mean exactly what ATIF says they mean. A document with `extra.agentenv` removed, or with any part of it + missing, is still correct ATIF and means the same. +- Every profile field is optional, for readers and for producers. A producer that can't fill one leaves it out. +- No typed field holds a placeholder or a value whose meaning needs the profile. +- Readers keep profile keys they don't know and write them back unchanged. Producers write only fields this version + defines; the validator holds them to it. +- An adapter writes nothing in an `extra` outside `extra.agentenv`, except the one key this file names: + `ToolCall.extra.raw_arguments`. + +The native log is stored beside every ATIF copy, so a copy may leave things out. Nothing needs the copy to convert back +to native exactly. + +## Documents + +- One document per agent per A2A context. Each A2A task starts at a `source: user` step that holds the inbound + message, with the task's ids in that step's profile. Steps number from 1 across the whole document. +- A context's record may span several documents: after an agent instance restarts, after a snapshot restore, and when + long runs are sealed into segments. They share `session_id`, the first user step of each carries the continuing turn + index, and each earlier document names the next in `continued_trajectory_ref`. The worker that stores the earlier + document sets that link, since the agent that wrote it may be gone. +- A sub-agent is an embedded trajectory in `subagent_trajectories`, with its own steps, referenced from the spawning + call's result by `subagent_trajectory_ref`. +- `schema_version` is the oldest ATIF version that holds the document's fields: `ATIF-v1.8` for profile 1.0. +- Format id: `atif/1`. The profile's own version is the root's `extra.agentenv.version`. + +## Steps + +- A step is one model response, keyed by its native id (a message id), or a step with no model call + (`llm_call_count` 0, no metrics or reasoning). A step closes when the next step of its trajectory starts, or when its + task ends. +- A result always sits in the step that made its call, as ATIF requires. One that arrives after that step closed records + when, in `arrived`. +- A live reader is served closed steps only, each trajectory up to its first step still waiting on a result. Steps are + ordered, so a step waiting on a late result holds back the steps after it until the result comes or the task ends. + Everything a reader is served is a prefix of every later read. +- The final response is written once. When the task's last agent step already holds the same text, nothing is added; + otherwise one step is appended, `source: agent` and `llm_call_count` 0. The task's terminal state goes on the task's + last step, which closes only when the task ends, so it is never served before the state is known. +- An agent message whose parts are all text is one string, the parts joined by a blank line; Harbor's tools read only + strings there. Text output always goes in whole: there is no reference part and no cap. +- `reasoning_content` joins a step's reasoning blocks' texts with a blank line. The profile's `reasoning` lists every + block, in native order, with its share of that text, so a reader that knows the profile can rebuild exact blocks. +- Timestamps are UTC, written `YYYY-MM-DDTHH:MM:SS(.fff|.ffffff)Z`. Other precisions are normalized: ATIF's Step + validator on Python 3.10 reads no other. +- Usage follows ATIF: `prompt_tokens` includes cache reads and writes, and `cached_tokens` is the cache reads. Each + adapter's `usage_input_includes_cache` constant says whether its native input count already includes the cache. + Cache writes go in `Metrics.extra.agentenv.cache_write_tokens`. +- A tool call whose input isn't a JSON object is wrapped as Harbor wraps it: a string as `{"input": ...}`, a missing + input as `{}`, any other value as `{"value": ...}`. The native input is kept in `ToolCall.extra.raw_arguments`, only + when wrapping changed it. Harbor's ATIF-to-Codex resume reads that key back. +- A native record no adapter method takes is counted by its type in the root's `unmatched`; it stays in the native copy. + +## Cost + +ATIF defines a step's `cost_usd` as the cost "based on current provider pricing for this step", and says the cost fields +"store the calculated cost at the time of execution". + +- A cost the harness calculated from its own price table, or a billed amount the provider's API reported, goes in + `Metrics.cost_usd` or `FinalMetrics.total_cost_usd`. Its `cost_source` in the profile says which: `harness` or + `provider`. +- A cost agentenv computes itself, from its own price table after the run, never goes in a typed field. +- When nothing reports a cost, the typed fields stay empty, which ATIF readers read as unknown. + +## Errors + +One vocabulary, in three places: + +- A tool result's `status` and `exit_code` go on its ObservationResult's profile. No status means `ok`. +- A step-level error, such as a refused or failed model call or a harness error, goes on its Step's profile as `error`. +- A task's terminal state goes on its last step's profile as `state`. + +## Media + +- Media are files beside the trajectory, at `media/.`, relative to the trajectory file. +- An image or audio part of a type ATIF has names that path. +- Media ATIF has no part type for is stored the same way, with a plain note in the typed content, such as + `[video: media/.mp4, 4.4 MB, 31 s]`. That covers video, documents, images other than JPEG, PNG, GIF and WebP + (such as HEIC or SVG), audio outside ATIF's eight types, and other files. +- Each file's details go in the `media` map of the profile of the object that holds the part (Step for a message, + ObservationResult for a result), keyed by its path. + +## Fields + +| Object | Field | Meaning | Read by | +| --- | --- | --- | --- | +| Trajectory | `version` | The profile version: `1.0` | every reader | +| Trajectory | `native_format` | The native format id the copy was built from | Y4, Y11 | +| Trajectory | `adapter` | The adapter's `name` and `version` | Y4, Y11 | +| Trajectory | `unmatched` | Native records no method took, counted by type | Y1b's adapter kit | +| Step | `context_id`, `task_id`, `message_id`, `turn` | On a task's user step: its A2A ids and turn index | Y2b, Y4, Hub F3 | +| Step | `state` | On a task's last step: its terminal state | Y7, Hub F3 | +| Step | `attempt` | The harness attempt the step belongs to; absent means 1 | Y7 | +| Step | `error` | A step-level error: `kind`, `message`, `code` | Y7 | +| Step | `reasoning` | Each reasoning block: `chars`, `visibility`, `signature`, `data` | Y5 resume, Y10 RL replay | +| Step | `media` | Details of the media the message names, by path | Y3, Y7 | +| ObservationResult | `status` | The result's status; absent means `ok` | Y7 | +| ObservationResult | `exit_code` | The command's exit code | Y7 | +| ObservationResult | `arrived` | A late result's arrival: `at`, and the `step_id` open when it came | live readers, Y7 | +| ObservationResult | `media` | Details of the media the result names, by path | Y3, Y7 | +| Metrics | `cost_source` | Where `cost_usd` came from | E13 | +| Metrics | `cache_write_tokens` | Cache writes, beside ATIF's `cached_tokens` | E13 | +| FinalMetrics | `cost_source` | Where `total_cost_usd` came from | E13 | +| FinalMetrics | `total_cache_write_tokens` | Cache writes summed over the steps | E13 | + +A media entry (MediaInfo) holds `sha256`, `bytes`, and, where they apply, `width`, `height`, `duration_ms`, `pages` +and `name`, plus `media_type` for media ATIF has no part type for. A reasoning block (ReasoningBlock) holds `chars`, +its share of `reasoning_content` (0 when the provider withheld the text), its `visibility`, the provider's `signature`, +and a redacted block's ciphertext as `data`, byte for byte. A step error (StepError) holds `kind`, `message` and `code`. +An arrival (Arrival) holds `at` and `step_id`. The Agent, ToolCall and SubagentTrajectoryRef profiles define no fields +in 1.0. + +## Vocabularies + +A reader keeps a value it doesn't know. + +| Field | Values | +| --- | --- | +| `StepProfile.state` | `completed`, `failed`, `canceled`, `rejected` (A2A's terminal task states) | +| `ObservationResultProfile.status` | `ok`, `error`, `canceled`, `timeout` | +| `StepError.kind` | `agent_error`, `infra_error` | +| `ReasoningBlock.visibility` | `raw`, `summary`, `omitted`, `redacted` | +| `MetricsProfile.cost_source`, `FinalMetricsProfile.cost_source` | `harness`, `provider` | + +## Versions + +A minor version only adds optional fields and vocabulary values, each with the reader or producer that needs it. A +field added in a later minor names the version it arrived in. Proposed for a later minor, with their first producer: +`usage_input_includes_cache` on the root and `cost_status` (with F12's cross-check), per-part origins (when a reader +needs them), and the always-on harness's five fields (FD-5840). + +## Fixtures + +`fixtures/` holds the profile's canonical examples, built through the adapter framework from a toy format's records: +`coding`, `computer_use`, `late_result`, `multi_agent`, `odd_parts`, `subagent` and `two_turns`, with their media in +`fixtures/media/`, and `coding.stripped.json`, the coding case without its profile. diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/__init__.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/__init__.py new file mode 100644 index 000000000..78e3c8a36 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/__init__.py @@ -0,0 +1,59 @@ +"""ATIF in agentenv: Harbor's Agent Trajectory Interchange Format (v1.8), the record every agent serves beside its +native log as ``atif/1``, plus agentenv's optional ``extra.agentenv`` profile. ``models`` holds Harbor's own models, +vendored; ``PROFILE.md`` beside this module is the profile's spec. The package needs only the protocol's base +dependencies, so anything can read a document or write an adapter.""" +from .adapter import Adapter, AdapterSpec, Native, Selector, atif_adapter, aux, finish, native +from .builder import AtifTurn, Document, Media, TurnContext, timestamp +from .models import ( + Agent, + AudioSource, + ContentPart, + FinalMetrics, + ImageSource, + Metrics, + Observation, + ObservationResult, + Step, + SubagentTrajectoryRef, + ToolCall, + Trajectory, +) +from .profile import ( + FORMAT, + PROFILE_KEY, + PROFILE_VERSION, + PROFILES, + RAW_ARGUMENTS, + SCHEMA_VERSION, + VOCABULARIES, + AdapterRef, + AgentProfile, + Arrival, + AtifError, + FinalMetricsProfile, + MediaInfo, + MetricsProfile, + ObservationResultProfile, + ReasoningBlock, + StepError, + StepProfile, + SubagentTrajectoryRefProfile, + ToolCallProfile, + TrajectoryProfile, + dump_profile, + profile_of, + read_profile, +) +from .reader import Task, check, is_prefix, load, media_paths, strip_profile, tasks +from .runner import AdapterRun, Fed, RecordedTask, replay + +__all__ = [ + "Adapter", "AdapterRef", "AdapterRun", "AdapterSpec", "Agent", "AgentProfile", "Arrival", "AtifError", "AtifTurn", + "AudioSource", "ContentPart", "Document", "FORMAT", "Fed", "FinalMetrics", "FinalMetricsProfile", "ImageSource", + "Media", "MediaInfo", "Metrics", "MetricsProfile", "Native", "Observation", "ObservationResult", + "ObservationResultProfile", "PROFILES", "PROFILE_KEY", "PROFILE_VERSION", "RAW_ARGUMENTS", "ReasoningBlock", + "RecordedTask", "SCHEMA_VERSION", "Selector", "Step", "StepError", "StepProfile", "SubagentTrajectoryRef", + "SubagentTrajectoryRefProfile", "Task", "ToolCall", "ToolCallProfile", "Trajectory", "TrajectoryProfile", + "TurnContext", "VOCABULARIES", "atif_adapter", "aux", "check", "dump_profile", "finish", "is_prefix", "load", + "media_paths", "native", "profile_of", "read_profile", "replay", "strip_profile", "tasks", "timestamp", +] diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/adapter.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/adapter.py new file mode 100644 index 000000000..23ebbaff9 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/adapter.py @@ -0,0 +1,178 @@ +"""Writing an ATIF adapter: a class, declared with ``@atif_adapter``, whose ``@native``, ``@aux`` and ``@finish`` +methods turn an agent's native records into ATIF steps through the AtifTurn each one is handed. It reads only what the +run stores, so an offline replay builds the document the agent served live.""" +from __future__ import annotations + +import re +from dataclasses import dataclass, field +from typing import TYPE_CHECKING, Any, Callable, ClassVar, Mapping, Sequence, TypeVar + +from .profile import AtifError + +if TYPE_CHECKING: + from .builder import AtifTurn + +#: A native format id: ``/``, as ``claude-code-stream-json/1``. +NATIVE_FORMAT = re.compile(r"^[a-z0-9][a-z0-9._-]*/[A-Za-z0-9._-]+$") +_MISSING = object() + +A = TypeVar("A", bound="Adapter") + + +@dataclass(frozen=True) +class Native: + """What ``from_atif`` gives back, on a best-effort basis: the native log, and the files the CLI resumes from, by + name, or None when this adapter can't seed a session.""" + + log: 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("__atif_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 task end, after the task's last record: write what's held and reset per-task state.""" + method.__atif_finish__ = True + return method + + +@dataclass(frozen=True) +class AdapterSpec: + """What ``@atif_adapter`` declares, and its handlers by selector.""" + + name: str + native_format: str + version: str + usage_input_includes_cache: bool | None + tested_with: tuple[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 AtifError(f"a record matches {', '.join(methods)} equally; make one of them more specific") + return methods[0] + + +def atif_adapter(*, native_format: str, version: str, usage_input_includes_cache: bool | None, + tested_with: Sequence[str] = (), name: 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); the builder uses it to write ATIF's ``prompt_tokens``, which include them. + ``tested_with`` names the native producer versions its recorded fixtures come from.""" + if not isinstance(native_format, str) or not NATIVE_FORMAT.match(native_format): + raise AtifError(f"native_format {native_format!r} isn't /") + if native_format.startswith("atif/"): + raise AtifError(f"native_format {native_format!r}: atif is the format adapters produce, not a native one") + if not isinstance(version, str) or not version: + raise AtifError("version is the adapter's own version string") + if usage_input_includes_cache not in (True, False, None): + raise AtifError("usage_input_includes_cache is true, false or None") + + def declare(cls: type[A]) -> type[A]: + if not (isinstance(cls, type) and issubclass(cls, Adapter)): + raise TypeError("@atif_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, "__atif_finish__", False): + finishes.append(attr) + for selector in getattr(member, "__atif_selectors__", ()): + if selector in owners and owners[selector] != attr: + raise AtifError(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 AtifError(f"aux file {selector.aux!r} is declared as both {known} and " + f"{selector.media_type}") + if len(finishes) > 1: + raise AtifError(f"{cls.__name__} has more than one @finish method: {', '.join(finishes)}") + cls.spec = AdapterSpec( + name=name or f"{native_format.split('/', 1)[0]}-atif", native_format=native_format, version=version, + usage_input_includes_cache=usage_input_includes_cache, tested_with=tuple(tested_with), + 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 an ATIF adapter. One instance serves an A2A context across its tasks; per-task state resets in + ``@finish``.""" + + spec: ClassVar[AdapterSpec] + + def __init__(self, turn: AtifTurn) -> None: + """Set up for the context whose first task here is ``turn``.""" + + def unmatched(self, record: Any, turn: AtifTurn) -> None: + """A native record no handler takes: counted by its type in the root profile, and left to the native copy.""" + turn.unmatched(record) + + @classmethod + def from_atif(cls, document: Mapping[str, Any]) -> Native: + """Any valid ATIF document, with or without ``extra.agentenv``, back to native, on a best-effort basis.""" + raise NotImplementedError(f"{cls.__name__} doesn't convert ATIF back to its native format") diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py new file mode 100644 index 000000000..172419d76 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py @@ -0,0 +1,661 @@ +"""The typed step builder: what an adapter's handlers write ATIF steps through, and the document it keeps for one A2A +context. It holds each trajectory's open step and closes it when the next one starts or the task ends, puts every +result in its call's step, writes usage in ATIF's terms, embeds sub-agents, hands media bytes to a sink and checks +every value is JSON. A live reader is served closed steps only, so nothing it has seen ever changes.""" +from __future__ import annotations + +import hashlib +import json +import mimetypes +import re +from collections import Counter +from dataclasses import dataclass, field +from datetime import datetime, timezone +from typing import Any, Callable, Iterable, Mapping, Sequence, get_args + +from pydantic import ValidationError + +from .adapter import AdapterSpec +from .models.content import AudioMediaType, ContentPart, ImageSource +from .profile import ( + COST_SOURCES, + ERROR_KINDS, + PROFILE_KEY, + PROFILE_VERSION, + RAW_ARGUMENTS, + RESULT_STATUSES, + SCHEMA_VERSION, + TASK_STATES, + VISIBILITIES, + AtifError, +) + +#: Media types ATIF has a part type for; any other medium is written as a text note naming its file. +IMAGE_TYPES = frozenset(get_args(ImageSource.model_fields["media_type"].annotation)) +AUDIO_TYPES = frozenset(get_args(AudioMediaType)) +_EXTENSIONS = { + "image/png": ".png", "image/jpeg": ".jpg", "image/gif": ".gif", "image/webp": ".webp", "image/heic": ".heic", + "image/svg+xml": ".svg", "audio/wav": ".wav", "audio/mpeg": ".mp3", "audio/mp4": ".m4a", "audio/aac": ".aac", + "audio/ogg": ".ogg", "audio/flac": ".flac", "audio/webm": ".webm", "audio/aiff": ".aiff", "video/mp4": ".mp4", + "video/webm": ".webm", "video/quicktime": ".mov", "application/pdf": ".pdf", "text/plain": ".txt", + "text/csv": ".csv", "application/json": ".json", "application/zip": ".zip", +} +_TIME = re.compile(r"^(\d{4}-\d{2}-\d{2})[Tt ](\d{2}):(\d{2}):(\d{2})(?:[.,](\d+))?([Zz]|[+-]\d{2}:?\d{2})$") +_JOIN = "\n\n" +_UNSET: Any = object() + + +def timestamp(value: str | datetime | None) -> str | None: + """An RFC 3339 time as the builder writes it: UTC, ``Z``, and 3 or 6 fractional digits (or none), since ATIF's + Step validator on Python 3.10 reads no other precision.""" + if value is None: + return None + if isinstance(value, datetime): + if value.tzinfo is None: + raise AtifError(f"{value!r} has no time zone") + moment = value.astimezone(timezone.utc) + fraction = f".{moment.microsecond:06d}" if moment.microsecond else "" + return moment.strftime("%Y-%m-%dT%H:%M:%S") + fraction + "Z" + match = _TIME.match(value.strip()) if isinstance(value, str) else None + if not match: + raise AtifError(f"{value!r} isn't an RFC 3339 time with a zone") + date, hours, minutes, seconds, digits, zone = match.groups() + zone = "+00:00" if zone in ("Z", "z") else (zone if ":" in zone else f"{zone[:3]}:{zone[3:]}") + micro = int((digits + "000000")[:6]) if digits else 0 + try: + moment = datetime.fromisoformat(f"{date}T{hours}:{minutes}:{seconds}.{micro:06d}{zone}").astimezone(timezone.utc) + except ValueError as exc: + raise AtifError(f"{value!r}: {exc}") from exc + text = moment.strftime("%Y-%m-%dT%H:%M:%S") + if digits: + text += f".{moment.microsecond // 1000:03d}" if len(digits) <= 3 else f".{moment.microsecond:06d}" + return text + "Z" + + +def _json(value: Any, what: str) -> Any: + try: + json.dumps(value, allow_nan=False) + except (TypeError, ValueError) as exc: + raise AtifError(f"{what} isn't JSON: {exc}") from exc + return json.loads(json.dumps(value)) + + +def _size(count: int) -> str: + if count < 1000: + return f"{count} B" + return f"{count / 1000:.1f} KB" if count < 1_000_000 else f"{count / 1_000_000:.1f} MB" + + +@dataclass(frozen=True) +class Media: + """A media file stored at ``path`` (``media/.``, relative to the trajectory). As content it is an + image or audio part when ATIF has the type, and otherwise a plain text note naming the file.""" + + path: str + media_type: str + info: Mapping[str, Any] + + @property + def typed(self) -> bool: + return self.media_type in IMAGE_TYPES or self.media_type in AUDIO_TYPES + + def part(self) -> dict[str, Any]: + if self.media_type in IMAGE_TYPES: + return {"type": "image", "source": {"media_type": self.media_type, "path": self.path}} + if self.media_type in AUDIO_TYPES: + source: dict[str, Any] = {"media_type": self.media_type, "path": self.path} + if self.info.get("duration_ms") is not None: + source["duration_sec"] = self.info["duration_ms"] / 1000 + return {"type": "audio", "source": source} + major = self.media_type.split("/", 1)[0] + kind = major if major in ("image", "audio", "video") else ( + "document" if self.media_type == "application/pdf" else "file") + details = [self.path, _size(self.info["bytes"])] + if self.info.get("duration_ms") is not None: + details.append(f"{round(self.info['duration_ms'] / 1000)} s") + if self.info.get("pages") is not None: + details.append(f"{self.info['pages']} pages") + return {"type": "text", "text": f"[{kind}: {', '.join(details)}]"} + + def profile(self) -> dict[str, Any]: + info = dict(self.info) + if not self.typed: + info["media_type"] = self.media_type + return info + + +@dataclass(frozen=True, kw_only=True) +class TurnContext: + """What the SDK knows of an A2A task when it starts: its ids and turn index, the inbound message's content, and + the agent as its card names it. The builder writes the task's user step from it.""" + + index: int + context_id: str + task_id: str + message_id: str | None = None + inbound: Sequence[Any] = () + agent_name: str | None = None + agent_version: str | None = None + agent_model: str | None = None + started_at: str | datetime | None = None + + +@dataclass(eq=False) +class _Step: + source: str + key: str | None + task: int + index: int + attempt: int + parts: list[dict[str, Any]] = field(default_factory=list) + media: dict[str, Any] = field(default_factory=dict) + reasoning: list[dict[str, Any]] = field(default_factory=list) + calls: list[dict[str, Any]] = field(default_factory=list) + results: list[dict[str, Any]] = field(default_factory=list) + metrics: dict[str, Any] = field(default_factory=dict) + metrics_profile: dict[str, Any] = field(default_factory=dict) + profile: dict[str, Any] = field(default_factory=dict) + pending: set[str] = field(default_factory=set) + model_name: str | None = None + reasoning_effort: str | float | None = None + llm_call_count: int | None = None + is_copied_context: bool | None = None + time: str | None = None + step_time: str | None = None + closed: bool = False + ended: bool = False + + +@dataclass(eq=False) +class _Trajectory: + actor: str | None + agent: dict[str, Any] + steps: list[_Step] = field(default_factory=list) + open: _Step | None = None + + +class Document: + """One A2A context's ATIF document, built a task at a time. Not thread-safe: records are fed one at a time.""" + + def __init__(self, spec: AdapterSpec, sink: Callable[[str, bytes], None] | None = None) -> None: + self.spec = spec + self.media: dict[str, bytes] = {} + self._sink = sink + self._root: _Trajectory | None = None + self._subs: dict[str, _Trajectory] = {} + self._call_home: dict[str, tuple[_Trajectory, _Step]] = {} + self._spawned: dict[str, str] = {} + self._unmatched: Counter[str] = Counter() + self._task_costs: list[tuple[float, str] | None] = [] + self._context: TurnContext | None = None + self._task = -1 + self._attempt = 1 + + # Tasks + + @property + def task_open(self) -> bool: + return self._context is not None + + def start_task(self, context: TurnContext) -> AtifTurn: + if self._context is not None: + raise AtifError(f"task {self._context.task_id} is still open") + if self._root is None: + self._root = _Trajectory(None, _agent(context.agent_name, context.agent_version, context.agent_model)) + self._context_id = context.context_id + elif context.context_id != self._context_id: + raise AtifError(f"context {context.context_id} isn't this document's {self._context_id}") + self._context, self._task, self._attempt = context, self._task + 1, 1 + self._task_costs.append(None) + step = self._start(self._root, "user", None) + step.time = timestamp(context.started_at) + self._add_parts(step.parts, step.media, context.inbound, None) + step.profile.update({key: value for key, value in ( + ("context_id", context.context_id), ("task_id", context.task_id), ("message_id", context.message_id), + ("turn", context.index)) if value is not None}) + return AtifTurn(self, context) + + def end_task(self, *, state: str = "completed", final: Sequence[Any] | None = None, + ended_at: str | datetime | None = None) -> None: + if self._context is None: + raise AtifError("no task is open") + if state not in TASK_STATES: + raise AtifError(f"state {state!r} isn't one of {', '.join(TASK_STATES)}") + root = self._root + assert root is not None + if final: + parts: list[dict[str, Any]] = [] + media: dict[str, Any] = {} + self._add_parts(parts, media, final, None) + last = next((s for s in reversed(root.steps) if s.task == self._task and s.source == "agent"), None) + if last is None or _message(last.parts) != _message(parts): + step = self._start(root, "agent", None) + step.parts, step.media, step.llm_call_count = parts, media, 0 + step.time = timestamp(ended_at) + root.steps[-1].profile["state"] = state + for trajectory in self._trajs(): + for step in trajectory.steps: + if step.task == self._task: + step.closed = step.ended = True + trajectory.open = None + self._context = None + + # What handlers call, through AtifTurn + + def step_for(self, key: str, agent: str | None) -> _Step: + trajectory = self._traj(agent) + step = trajectory.open + if step is None or step.key != key or step.source != "agent": + step = self._start(trajectory, "agent", key) + return step + + def open_step(self, agent: str | None) -> _Step: + step = self._traj(agent).open + if step is None: + raise AtifError("no step is open: name the step this belongs to") + return step + + def call(self, step: _Step, call_id: str, name: str, arguments: Any) -> None: + if not isinstance(call_id, str) or not call_id: + raise AtifError("tool_call_id is a non-empty string") + if call_id in self._call_home: + raise AtifError(f"tool_call_id {call_id!r} is already in this document") + if isinstance(arguments, Mapping): + typed, raw = _json(dict(arguments), f"{name}'s arguments"), _UNSET + else: + raw = _json(arguments, f"{name}'s arguments") + typed = {} if arguments is None else ({"input": arguments} if isinstance(arguments, str) + else {"value": raw}) + step.calls.append({"tool_call_id": call_id, "function_name": name, "arguments": typed, "raw": raw}) + step.pending.add(call_id) + self._call_home[call_id] = (self._owner(step), step) + + def result(self, call_id: str, content: Sequence[Any], status: str, exit_code: int | None, + at: str | None) -> None: + if call_id not in self._call_home: + raise AtifError(f"a result for {call_id!r}, which no call in this document made") + if status not in RESULT_STATUSES: + raise AtifError(f"status {status!r} isn't one of {', '.join(RESULT_STATUSES)}") + trajectory, home = self._call_home[call_id] + parts: list[dict[str, Any]] = [] + media: dict[str, Any] = {} + self._add_parts(parts, media, content, None) + profile: dict[str, Any] = {} + if status != "ok": + profile["status"] = status + if exit_code is not None: + profile["exit_code"] = _json(exit_code, "exit_code") + if home.closed: + opened = trajectory.open + profile["arrived"] = {key: value for key, value in ( + ("at", at), ("step_id", opened.index + 1 if opened is not None else None)) if value is not None} + if media: + profile["media"] = media + result: dict[str, Any] = {"source_call_id": call_id, "parts": parts, "profile": profile} + if call_id in self._spawned: + result["subagent"] = self._spawned[call_id] + home.results.append(result) + home.pending.discard(call_id) + + def subagent(self, agent_id: str, spawned_by: str, name: str | None, version: str | None, + model_name: str | None) -> None: + if agent_id in self._subs: + raise AtifError(f"sub-agent {agent_id!r} is already declared") + self._subs[agent_id] = _Trajectory(agent_id, _agent(name or agent_id, version, model_name)) + self._spawned[spawned_by] = agent_id + + def store(self, data: bytes, media_type: str, info: Mapping[str, Any]) -> Media: + if not isinstance(data, (bytes, bytearray)): + raise AtifError("media bytes are bytes") + digest = hashlib.sha256(data).hexdigest() + extension = _EXTENSIONS.get(media_type) or mimetypes.guess_extension(media_type, strict=False) or ".bin" + path = f"media/{digest}{extension}" + if path not in self.media: + self.media[path] = bytes(data) + if self._sink is not None: + self._sink(path, bytes(data)) + details = {"sha256": digest, "bytes": len(data), **{k: v for k, v in info.items() if v is not None}} + return Media(path, media_type, _json(details, "media details")) + + def count_unmatched(self, record: Any) -> None: + kind = record.get("type") if isinstance(record, Mapping) else None + self._unmatched[kind if isinstance(kind, str) else type(record).__name__] += 1 + + def task_cost(self, cost_usd: float, source: str) -> None: + if source not in COST_SOURCES: + raise AtifError(f"cost_source {source!r} isn't one of {', '.join(COST_SOURCES)}") + self._task_costs[self._task] = (_json(cost_usd, "cost_usd"), source) + + def set_attempt(self, number: int) -> None: + if not isinstance(number, int) or number < 1: + raise AtifError("an attempt number is 1 or more") + self._attempt = number + + def add_parts(self, step: _Step, content: Sequence[Any] | None, text: str | None) -> None: + self._add_parts(step.parts, step.media, content, text) + + # Reading the document + + def document(self) -> dict[str, Any] | None: + """The whole document so far, or None before its first step. A fresh copy each time.""" + return self._render(closed_only=False) + + def page(self) -> dict[str, Any] | None: + """What a live reader is served: each trajectory's closed steps, up to the first one still waiting on a + result, or None while there are none.""" + return self._render(closed_only=True) + + # Internals + + def _trajs(self) -> list[_Trajectory]: + return ([self._root] if self._root is not None else []) + list(self._subs.values()) + + def _traj(self, agent: str | None) -> _Trajectory: + if self._root is None or self._context is None: + raise AtifError("no task is open") + if agent is None: + return self._root + if agent not in self._subs: + raise AtifError(f"sub-agent {agent!r} isn't declared: call turn.subagent first") + return self._subs[agent] + + def _owner(self, step: _Step) -> _Trajectory: + return next(t for t in self._trajs() if any(s is step for s in t.steps)) + + def _start(self, trajectory: _Trajectory, source: str, key: str | None) -> _Step: + if trajectory.open is not None: + trajectory.open.closed = True + step = _Step(source=source, key=key, task=self._task, index=len(trajectory.steps), attempt=self._attempt) + if self._attempt > 1: + step.profile["attempt"] = self._attempt + trajectory.steps.append(step) + trajectory.open = step + return step + + def _add_parts(self, parts: list[dict[str, Any]], media: dict[str, Any], content: Iterable[Any] | None, + text: str | None) -> None: + if text is not None: + if content is not None: + raise AtifError("give content or text, not both") + content = [text] + for item in content or (): + if isinstance(item, Media): + parts.append(item.part()) + media[item.path] = item.profile() + continue + if isinstance(item, str): + part: Any = {"type": "text", "text": item} + elif isinstance(item, Mapping): + part = _json(dict(item), "a content part") + else: + raise AtifError(f"content is text, a Media or an ATIF part, not {type(item).__name__}") + try: + ContentPart.model_validate(part) + except ValidationError as exc: + raise AtifError(f"content part: {exc}") from exc + parts.append(part) + + def _servable(self, trajectory: _Trajectory) -> int: + count = 0 + for step in trajectory.steps: + if not step.closed or (step.pending and not step.ended): + break + count += 1 + return count + + def _render(self, *, closed_only: bool) -> dict[str, Any] | None: + root = self._root + if root is None: + return None + root_count = self._servable(root) if closed_only else len(root.steps) + if root_count == 0: + return None + doc: dict[str, Any] = {"schema_version": SCHEMA_VERSION, "session_id": self._context_id, + "agent": dict(root.agent), + "steps": [_render_step(s) for s in root.steps[:root_count]]} + subs = [] + for trajectory in self._subs.values(): + count = self._servable(trajectory) if closed_only else len(trajectory.steps) + if count: + subs.append({"schema_version": SCHEMA_VERSION, "trajectory_id": trajectory.actor, + "agent": dict(trajectory.agent), + "steps": [_render_step(s) for s in trajectory.steps[:count]]}) + if subs: + doc["subagent_trajectories"] = subs + if self._context is None: + doc["final_metrics"] = self._final_metrics(root) + profile: dict[str, Any] = {"version": PROFILE_VERSION, "native_format": self.spec.native_format, + "adapter": {"name": self.spec.name, "version": self.spec.version}} + if self._unmatched: + profile["unmatched"] = dict(sorted(self._unmatched.items())) + doc["extra"] = {PROFILE_KEY: profile} + return doc + + def _final_metrics(self, root: _Trajectory) -> dict[str, Any]: + steps = [s for t in self._trajs() for s in t.steps + if s.source == "agent" and s.llm_call_count != 0 and (s.metrics or s.metrics_profile)] + totals: dict[str, Any] = {} + for key, total in (("prompt_tokens", "total_prompt_tokens"), ("completion_tokens", "total_completion_tokens"), + ("cached_tokens", "total_cached_tokens")): + if steps and all(key in s.metrics for s in steps): + totals[total] = sum(s.metrics[key] for s in steps) + profile: dict[str, Any] = {} + costs = self._task_costs + if costs and all(cost is not None for cost in costs): + totals["total_cost_usd"] = round(sum(cost[0] for cost in costs), 10) + sources = {cost[1] for cost in costs} + if len(sources) == 1: + profile["cost_source"] = sources.pop() + elif steps and all("cost_usd" in s.metrics for s in steps): + totals["total_cost_usd"] = round(sum(s.metrics["cost_usd"] for s in steps), 10) + sources = {s.metrics_profile.get("cost_source") for s in steps} + if len(sources) == 1 and None not in sources: + profile["cost_source"] = sources.pop() + totals["total_steps"] = len(root.steps) + if steps and all("cache_write_tokens" in s.metrics_profile for s in steps): + profile["total_cache_write_tokens"] = sum(s.metrics_profile["cache_write_tokens"] for s in steps) + if profile: + totals["extra"] = {PROFILE_KEY: profile} + return totals + + +def _agent(name: str | None, version: str | None, model: str | None) -> dict[str, Any]: + agent = {"name": name or "unknown", "version": version or "unknown"} + if model: + agent["model_name"] = model + return agent + + +def _message(parts: list[dict[str, Any]]) -> str | list[dict[str, Any]]: + """A step's message: one string when every part is text, else the parts.""" + if all(part["type"] == "text" for part in parts): + return _JOIN.join(part["text"] for part in parts) + return [dict(part) for part in parts] + + +def _render_step(step: _Step) -> dict[str, Any]: + agentic = step.source == "agent" + out: dict[str, Any] = {"step_id": step.index + 1} + when = step.step_time or step.time + if when: + out["timestamp"] = when + out["source"] = step.source + if agentic and step.model_name: + out["model_name"] = step.model_name + if agentic and step.reasoning_effort is not None: + out["reasoning_effort"] = step.reasoning_effort + out["message"] = _message(step.parts) + texts = [block["text"] for block in step.reasoning if block.get("text")] + if agentic and texts and step.llm_call_count != 0: + out["reasoning_content"] = _JOIN.join(texts) + if agentic and step.calls: + calls = [] + for call in step.calls: + rendered = {k: call[k] for k in ("tool_call_id", "function_name", "arguments")} + if call["raw"] is not _UNSET: + rendered["extra"] = {RAW_ARGUMENTS: call["raw"]} + calls.append(rendered) + out["tool_calls"] = calls + if step.results: + results = [] + for result in step.results: + rendered = {"source_call_id": result["source_call_id"], "content": _message(result["parts"])} + if "subagent" in result: + rendered["subagent_trajectory_ref"] = [{"trajectory_id": result["subagent"]}] + if result["profile"]: + rendered["extra"] = {PROFILE_KEY: dict(result["profile"])} + results.append(rendered) + out["observation"] = {"results": results} + if agentic and step.llm_call_count != 0 and (step.metrics or step.metrics_profile): + metrics = dict(step.metrics) + if step.metrics_profile: + metrics["extra"] = {PROFILE_KEY: dict(step.metrics_profile)} + out["metrics"] = metrics + if agentic and step.llm_call_count is not None: + out["llm_call_count"] = step.llm_call_count + if step.is_copied_context is not None: + out["is_copied_context"] = step.is_copied_context + profile = dict(step.profile) + if step.media: + profile["media"] = dict(step.media) + blocks = step.reasoning + if blocks and (len(blocks) > 1 or any(b.get("signature") or b.get("data") or b["visibility"] != "raw" + for b in blocks)): + profile["reasoning"] = [{key: value for key, value in ( + ("chars", len(b.get("text") or "")), ("visibility", b["visibility"]), ("signature", b.get("signature")), + ("data", b.get("data"))) if value is not None} for b in blocks] + if profile: + out["extra"] = {PROFILE_KEY: profile} + return json.loads(json.dumps(out)) + + +class AtifTurn: + """What a handler writes one task's steps through. ``step`` keys group the content of one model response (its + message id): content under a new key starts a step and closes the open one. ``agent`` names a declared sub-agent, + whose steps go in its own embedded trajectory.""" + + def __init__(self, document: Document, context: TurnContext) -> None: + self._doc = document + self.context = context + + @property + def spec(self) -> AdapterSpec: + return self._doc.spec + + def message(self, *, step: str, text: str | None = None, content: Sequence[Any] | None = None, + time: str | datetime | None = None, agent: str | None = None) -> None: + """Assistant content in step ``step``: text, Media from ``media``, or ATIF parts.""" + target = self._doc.step_for(step, agent) + self._doc.add_parts(target, content, text) + self._touch(target, time) + + def reasoning(self, *, step: str, text: str | None = None, visibility: str = "raw", signature: str | None = None, + data: str | None = None, time: str | datetime | None = None, agent: str | None = None) -> None: + """One reasoning block: its text (None when withheld), its visibility, and the provider's signature or a + redacted block's ciphertext, kept byte for byte.""" + if visibility not in VISIBILITIES: + raise AtifError(f"visibility {visibility!r} isn't one of {', '.join(VISIBILITIES)}") + for name, value in (("text", text), ("signature", signature), ("data", data)): + if value is not None and not isinstance(value, str): + raise AtifError(f"reasoning {name} is a string") + target = self._doc.step_for(step, agent) + target.reasoning.append({"text": text, "visibility": visibility, "signature": signature, "data": data}) + self._touch(target, time) + + def tool_call(self, *, step: str, tool_call_id: str, function_name: str, arguments: Any, + time: str | datetime | None = None, agent: str | None = None) -> None: + """A call in step ``step``. Arguments that aren't a JSON object are wrapped as Harbor wraps them (a string as + ``{"input": ...}``, None as ``{}``, any other value as ``{"value": ...}``) and kept whole in ``raw_arguments``.""" + target = self._doc.step_for(step, agent) + self._doc.call(target, tool_call_id, function_name, arguments) + self._touch(target, time) + + def tool_result(self, *, source_call_id: str, text: str | None = None, content: Sequence[Any] | None = None, + status: str = "ok", exit_code: int | None = None, time: str | datetime | None = None) -> None: + """A result, written in its call's step. One that comes after that step closed keeps when it arrived.""" + if (text is None) == (content is None): + raise AtifError("give a result's content or its text") + self._doc.result(source_call_id, [text] if text is not None else list(content or ()), status, exit_code, + timestamp(time)) + + def step(self, *, key: str, model_name: str | None = None, llm_call_count: int | None = 1, + reasoning_effort: str | float | None = None, input_tokens: int | None = None, + output_tokens: int | None = None, cache_read_tokens: int | None = None, + cache_write_tokens: int | None = None, cost_usd: float | None = None, cost_source: str | None = None, + time: str | datetime | None = None, is_copied_context: bool | None = None, + agent: str | None = None) -> None: + """What one model response cost and produced. Token counts are the native's; ATIF's ``prompt_tokens`` + includes cache reads and writes, so the adapter's ``usage_input_includes_cache`` decides the sum. A cost is + the harness's or the provider's (``cost_source``), never one agentenv computed.""" + target = self._doc.step_for(key, agent) + if model_name is not None: + target.model_name = model_name + if reasoning_effort is not None: + target.reasoning_effort = reasoning_effort + target.llm_call_count = llm_call_count + if is_copied_context is not None: + target.is_copied_context = is_copied_context + counts = (input_tokens, output_tokens, cache_read_tokens, cache_write_tokens) + if any(value is not None for value in counts) or cost_usd is not None: + if llm_call_count == 0: + raise AtifError("a step with no model call (llm_call_count 0) has no usage or cost") + for value in counts: + if value is not None and (not isinstance(value, int) or isinstance(value, bool) or value < 0): + raise AtifError(f"token counts are non-negative integers, not {value!r}") + if input_tokens is not None or cache_read_tokens is not None or cache_write_tokens is not None: + includes = self.spec.usage_input_includes_cache + if includes is None: + raise AtifError("declare usage_input_includes_cache on @atif_adapter to write prompt tokens") + prompt = (input_tokens or 0) + (0 if includes else (cache_read_tokens or 0) + (cache_write_tokens or 0)) + target.metrics["prompt_tokens"] = prompt + if cache_read_tokens is not None: + target.metrics["cached_tokens"] = cache_read_tokens + if cache_write_tokens is not None: + target.metrics_profile["cache_write_tokens"] = cache_write_tokens + if output_tokens is not None: + target.metrics["completion_tokens"] = output_tokens + if cost_usd is not None: + if cost_source not in COST_SOURCES: + raise AtifError(f"a cost names its cost_source: one of {', '.join(COST_SOURCES)}") + target.metrics["cost_usd"] = _json(cost_usd, "cost_usd") + target.metrics_profile["cost_source"] = cost_source + if time is not None: + target.step_time = timestamp(time) + + def task_cost(self, cost_usd: float, *, source: str) -> None: + """The task's total cost, as the harness or provider reported it, when its steps carry none.""" + self._doc.task_cost(cost_usd, source) + + def error(self, *, message: str, kind: str = "agent_error", code: str | None = None, step: str | None = None, + agent: str | None = None) -> None: + """A step-level error: a refused or failed model call, or a harness error. On step ``step``, else the open + step; a later error on the same step replaces it.""" + if kind not in ERROR_KINDS: + raise AtifError(f"kind {kind!r} isn't one of {', '.join(ERROR_KINDS)}") + target = self._doc.step_for(step, agent) if step is not None else self._doc.open_step(agent) + target.profile["error"] = {k: v for k, v in (("kind", kind), ("message", message), ("code", code)) + if v is not None} + + def attempt(self, number: int) -> None: + """A harness retry: steps from here on carry attempt ``number``.""" + self._doc.set_attempt(number) + + def subagent(self, agent_id: str, *, spawned_by: str, name: str | None = None, version: str | None = None, + model_name: str | None = None) -> None: + """Declare a sub-agent the call ``spawned_by`` started. Its steps (written with ``agent=agent_id``) form an + embedded trajectory, and the spawning call's result points at it.""" + self._doc.subagent(agent_id, spawned_by, name, version, model_name) + + def media(self, data: bytes, media_type: str, *, width: int | None = None, height: int | None = None, + duration_ms: int | None = None, pages: int | None = None, name: str | None = None) -> Media: + """Store media bytes (through the sink) and return the Media to put in content.""" + return self._doc.store(data, media_type, {"width": width, "height": height, "duration_ms": duration_ms, + "pages": pages, "name": name}) + + def unmatched(self, record: Any) -> None: + """Count a native record nothing handled, by its type, in the root profile.""" + self._doc.count_unmatched(record) + + def _touch(self, step: _Step, time: str | datetime | None) -> None: + if step.time is None and time is not None: + step.time = timestamp(time) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/coding.json b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/coding.json new file mode 100644 index 000000000..e537c7ee7 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/coding.json @@ -0,0 +1,229 @@ +{ + "schema_version": "ATIF-v1.8", + "session_id": "ctx-7f3a", + "agent": { + "name": "toy", + "version": "1.0", + "model_name": "claude-opus-5-5" + }, + "steps": [ + { + "step_id": 1, + "timestamp": "2026-11-04T17:02:11.204Z", + "source": "user", + "message": "tests/test_parse.py::test_utc fails. Fix parse_date without changing the test.", + "extra": { + "agentenv": { + "context_id": "ctx-7f3a", + "task_id": "task-91c2", + "message_id": "msg-a1", + "turn": 0 + } + } + }, + { + "step_id": 2, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "", + "reasoning_content": "Run the failing test first to see the error.", + "tool_calls": [ + { + "tool_call_id": "toolu_01", + "function_name": "Bash", + "arguments": { + "command": "pytest tests/test_parse.py -q" + } + } + ], + "observation": { + "results": [ + { + "source_call_id": "toolu_01", + "content": "FAILED tests/test_parse.py::test_utc - ValueError: Invalid isoformat string: '2026-01-02T03:04:05Z'", + "extra": { + "agentenv": { + "status": "error", + "exit_code": 1 + } + } + } + ] + }, + "metrics": { + "prompt_tokens": 18432, + "cached_tokens": 16890, + "completion_tokens": 212, + "extra": { + "agentenv": { + "cache_write_tokens": 1402 + } + } + }, + "llm_call_count": 1, + "extra": { + "agentenv": { + "reasoning": [ + { + "chars": 44, + "visibility": "raw", + "signature": "EqQBCkgIBhABGAIiQKm3" + } + ] + } + } + }, + { + "step_id": 3, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "", + "tool_calls": [ + { + "tool_call_id": "toolu_02", + "function_name": "Read", + "arguments": { + "file_path": "tests/fixtures/dates.txt" + } + } + ], + "observation": { + "results": [ + { + "source_call_id": "toolu_02", + "content": "2026-01-01T03:04:05Z -> 2026-01-01 03:04:05+00:00\n2026-01-02T03:04:05Z -> 2026-01-02 03:04:05+00:00\n2026-01-03T03:04:05Z -> 2026-01-03 03:04:05+00:00\n2026-01-04T03:04:05Z -> 2026-01-04 03:04:05+00:00\n2026-01-05T03:04:05Z -> 2026-01-05 03:04:05+00:00\n2026-01-06T03:04:05Z -> 2026-01-06 03:04:05+00:00\n2026-01-07T03:04:05Z -> 2026-01-07 03:04:05+00:00\n2026-01-08T03:04:05Z -> 2026-01-08 03:04:05+00:00\n2026-01-09T03:04:05Z -> 2026-01-09 03:04:05+00:00\n2026-01-10T03:04:05Z -> 2026-01-10 03:04:05+00:00\n2026-01-11T03:04:05Z -> 2026-01-11 03:04:05+00:00\n2026-01-12T03:04:05Z -> 2026-01-12 03:04:05+00:00\n2026-01-13T03:04:05Z -> 2026-01-13 03:04:05+00:00\n2026-01-14T03:04:05Z -> 2026-01-14 03:04:05+00:00\n2026-01-15T03:04:05Z -> 2026-01-15 03:04:05+00:00\n2026-01-16T03:04:05Z -> 2026-01-16 03:04:05+00:00\n2026-01-17T03:04:05Z -> 2026-01-17 03:04:05+00:00\n2026-01-18T03:04:05Z -> 2026-01-18 03:04:05+00:00\n2026-01-19T03:04:05Z -> 2026-01-19 03:04:05+00:00\n2026-01-20T03:04:05Z -> 2026-01-20 03:04:05+00:00\n2026-01-21T03:04:05Z -> 2026-01-21 03:04:05+00:00\n2026-01-22T03:04:05Z -> 2026-01-22 03:04:05+00:00\n2026-01-23T03:04:05Z -> 2026-01-23 03:04:05+00:00\n2026-01-24T03:04:05Z -> 2026-01-24 03:04:05+00:00\n2026-01-25T03:04:05Z -> 2026-01-25 03:04:05+00:00\n2026-01-26T03:04:05Z -> 2026-01-26 03:04:05+00:00\n2026-01-27T03:04:05Z -> 2026-01-27 03:04:05+00:00\n2026-01-28T03:04:05Z -> 2026-01-28 03:04:05+00:00\n" + } + ] + }, + "metrics": { + "prompt_tokens": 18901, + "cached_tokens": 18292, + "completion_tokens": 96, + "extra": { + "agentenv": { + "cache_write_tokens": 469 + } + } + }, + "llm_call_count": 1 + }, + { + "step_id": 4, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "", + "tool_calls": [ + { + "tool_call_id": "toolu_03", + "function_name": "Edit", + "arguments": { + "file_path": "src/parse.py", + "old_string": "datetime.fromisoformat(s)", + "new_string": "datetime.fromisoformat(s.replace('Z', '+00:00'))" + } + } + ], + "observation": { + "results": [ + { + "source_call_id": "toolu_03", + "content": "The file src/parse.py has been updated." + } + ] + }, + "metrics": { + "prompt_tokens": 31377, + "cached_tokens": 18761, + "completion_tokens": 188, + "extra": { + "agentenv": { + "cache_write_tokens": 12476 + } + } + }, + "llm_call_count": 1 + }, + { + "step_id": 5, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "", + "tool_calls": [ + { + "tool_call_id": "toolu_04", + "function_name": "Bash", + "arguments": { + "command": "pytest tests/test_parse.py -q" + } + } + ], + "observation": { + "results": [ + { + "source_call_id": "toolu_04", + "content": "3 passed in 0.18s" + } + ] + }, + "metrics": { + "prompt_tokens": 31702, + "cached_tokens": 31237, + "completion_tokens": 74, + "extra": { + "agentenv": { + "cache_write_tokens": 325 + } + } + }, + "llm_call_count": 1 + }, + { + "step_id": 6, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "parse_date now accepts a trailing Z; all 3 tests in tests/test_parse.py pass.", + "metrics": { + "prompt_tokens": 31890, + "cached_tokens": 31562, + "completion_tokens": 41, + "extra": { + "agentenv": { + "cache_write_tokens": 188 + } + } + }, + "llm_call_count": 1, + "extra": { + "agentenv": { + "state": "completed" + } + } + } + ], + "final_metrics": { + "total_prompt_tokens": 132302, + "total_completion_tokens": 611, + "total_cached_tokens": 116742, + "total_cost_usd": 0.2117, + "total_steps": 6, + "extra": { + "agentenv": { + "cost_source": "harness", + "total_cache_write_tokens": 14860 + } + } + }, + "extra": { + "agentenv": { + "version": "1.0", + "native_format": "toy-events/1", + "adapter": { + "name": "toy-events-atif", + "version": "0.1.0" + }, + "unmatched": { + "system": 1 + } + } + } +} diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/coding.stripped.json b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/coding.stripped.json new file mode 100644 index 000000000..41e2c27df --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/coding.stripped.json @@ -0,0 +1,155 @@ +{ + "schema_version": "ATIF-v1.8", + "session_id": "ctx-7f3a", + "agent": { + "name": "toy", + "version": "1.0", + "model_name": "claude-opus-5-5" + }, + "steps": [ + { + "step_id": 1, + "timestamp": "2026-11-04T17:02:11.204Z", + "source": "user", + "message": "tests/test_parse.py::test_utc fails. Fix parse_date without changing the test." + }, + { + "step_id": 2, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "", + "reasoning_content": "Run the failing test first to see the error.", + "tool_calls": [ + { + "tool_call_id": "toolu_01", + "function_name": "Bash", + "arguments": { + "command": "pytest tests/test_parse.py -q" + } + } + ], + "observation": { + "results": [ + { + "source_call_id": "toolu_01", + "content": "FAILED tests/test_parse.py::test_utc - ValueError: Invalid isoformat string: '2026-01-02T03:04:05Z'" + } + ] + }, + "metrics": { + "prompt_tokens": 18432, + "cached_tokens": 16890, + "completion_tokens": 212 + }, + "llm_call_count": 1 + }, + { + "step_id": 3, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "", + "tool_calls": [ + { + "tool_call_id": "toolu_02", + "function_name": "Read", + "arguments": { + "file_path": "tests/fixtures/dates.txt" + } + } + ], + "observation": { + "results": [ + { + "source_call_id": "toolu_02", + "content": "2026-01-01T03:04:05Z -> 2026-01-01 03:04:05+00:00\n2026-01-02T03:04:05Z -> 2026-01-02 03:04:05+00:00\n2026-01-03T03:04:05Z -> 2026-01-03 03:04:05+00:00\n2026-01-04T03:04:05Z -> 2026-01-04 03:04:05+00:00\n2026-01-05T03:04:05Z -> 2026-01-05 03:04:05+00:00\n2026-01-06T03:04:05Z -> 2026-01-06 03:04:05+00:00\n2026-01-07T03:04:05Z -> 2026-01-07 03:04:05+00:00\n2026-01-08T03:04:05Z -> 2026-01-08 03:04:05+00:00\n2026-01-09T03:04:05Z -> 2026-01-09 03:04:05+00:00\n2026-01-10T03:04:05Z -> 2026-01-10 03:04:05+00:00\n2026-01-11T03:04:05Z -> 2026-01-11 03:04:05+00:00\n2026-01-12T03:04:05Z -> 2026-01-12 03:04:05+00:00\n2026-01-13T03:04:05Z -> 2026-01-13 03:04:05+00:00\n2026-01-14T03:04:05Z -> 2026-01-14 03:04:05+00:00\n2026-01-15T03:04:05Z -> 2026-01-15 03:04:05+00:00\n2026-01-16T03:04:05Z -> 2026-01-16 03:04:05+00:00\n2026-01-17T03:04:05Z -> 2026-01-17 03:04:05+00:00\n2026-01-18T03:04:05Z -> 2026-01-18 03:04:05+00:00\n2026-01-19T03:04:05Z -> 2026-01-19 03:04:05+00:00\n2026-01-20T03:04:05Z -> 2026-01-20 03:04:05+00:00\n2026-01-21T03:04:05Z -> 2026-01-21 03:04:05+00:00\n2026-01-22T03:04:05Z -> 2026-01-22 03:04:05+00:00\n2026-01-23T03:04:05Z -> 2026-01-23 03:04:05+00:00\n2026-01-24T03:04:05Z -> 2026-01-24 03:04:05+00:00\n2026-01-25T03:04:05Z -> 2026-01-25 03:04:05+00:00\n2026-01-26T03:04:05Z -> 2026-01-26 03:04:05+00:00\n2026-01-27T03:04:05Z -> 2026-01-27 03:04:05+00:00\n2026-01-28T03:04:05Z -> 2026-01-28 03:04:05+00:00\n" + } + ] + }, + "metrics": { + "prompt_tokens": 18901, + "cached_tokens": 18292, + "completion_tokens": 96 + }, + "llm_call_count": 1 + }, + { + "step_id": 4, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "", + "tool_calls": [ + { + "tool_call_id": "toolu_03", + "function_name": "Edit", + "arguments": { + "file_path": "src/parse.py", + "old_string": "datetime.fromisoformat(s)", + "new_string": "datetime.fromisoformat(s.replace('Z', '+00:00'))" + } + } + ], + "observation": { + "results": [ + { + "source_call_id": "toolu_03", + "content": "The file src/parse.py has been updated." + } + ] + }, + "metrics": { + "prompt_tokens": 31377, + "cached_tokens": 18761, + "completion_tokens": 188 + }, + "llm_call_count": 1 + }, + { + "step_id": 5, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "", + "tool_calls": [ + { + "tool_call_id": "toolu_04", + "function_name": "Bash", + "arguments": { + "command": "pytest tests/test_parse.py -q" + } + } + ], + "observation": { + "results": [ + { + "source_call_id": "toolu_04", + "content": "3 passed in 0.18s" + } + ] + }, + "metrics": { + "prompt_tokens": 31702, + "cached_tokens": 31237, + "completion_tokens": 74 + }, + "llm_call_count": 1 + }, + { + "step_id": 6, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "parse_date now accepts a trailing Z; all 3 tests in tests/test_parse.py pass.", + "metrics": { + "prompt_tokens": 31890, + "cached_tokens": 31562, + "completion_tokens": 41 + }, + "llm_call_count": 1 + } + ], + "final_metrics": { + "total_prompt_tokens": 132302, + "total_completion_tokens": 611, + "total_cached_tokens": 116742, + "total_cost_usd": 0.2117, + "total_steps": 6 + } +} diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/computer_use.json b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/computer_use.json new file mode 100644 index 000000000..80131b2da --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/computer_use.json @@ -0,0 +1,246 @@ +{ + "schema_version": "ATIF-v1.8", + "session_id": "ctx-7f3a", + "agent": { + "name": "toy", + "version": "1.0", + "model_name": "claude-opus-5-5" + }, + "steps": [ + { + "step_id": 1, + "timestamp": "2026-11-04T19:10:01.020Z", + "source": "user", + "message": "In the open spreadsheet, set B2 to 42 and save the file.", + "extra": { + "agentenv": { + "context_id": "ctx-7f3a", + "task_id": "task-c1", + "message_id": "msg-c1", + "turn": 0 + } + } + }, + { + "step_id": 2, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "", + "tool_calls": [ + { + "tool_call_id": "toolu_c1", + "function_name": "computer", + "arguments": { + "action": "screenshot" + } + } + ], + "observation": { + "results": [ + { + "source_call_id": "toolu_c1", + "content": [ + { + "type": "image", + "source": { + "media_type": "image/png", + "path": "media/82e60066a2de261b6653bcdda90d1cb9a7af2f474cecd82e8d371e8384d72315.png" + } + } + ], + "extra": { + "agentenv": { + "media": { + "media/82e60066a2de261b6653bcdda90d1cb9a7af2f474cecd82e8d371e8384d72315.png": { + "sha256": "82e60066a2de261b6653bcdda90d1cb9a7af2f474cecd82e8d371e8384d72315", + "bytes": 12, + "width": 1280, + "height": 800 + } + } + } + } + } + ] + }, + "metrics": { + "prompt_tokens": 6210, + "cached_tokens": 5120, + "completion_tokens": 58, + "extra": { + "agentenv": { + "cache_write_tokens": 1024 + } + } + }, + "llm_call_count": 1 + }, + { + "step_id": 3, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "", + "tool_calls": [ + { + "tool_call_id": "toolu_c2", + "function_name": "computer", + "arguments": { + "action": "left_click", + "coordinate": [ + 212, + 318 + ] + } + } + ], + "observation": { + "results": [ + { + "source_call_id": "toolu_c2", + "content": [ + { + "type": "image", + "source": { + "media_type": "image/png", + "path": "media/69a8aa01fe5537076d023dd5e9cc4275b39fc0434aa6483a9f58b66ef2f3c896.png" + } + } + ], + "extra": { + "agentenv": { + "media": { + "media/69a8aa01fe5537076d023dd5e9cc4275b39fc0434aa6483a9f58b66ef2f3c896.png": { + "sha256": "69a8aa01fe5537076d023dd5e9cc4275b39fc0434aa6483a9f58b66ef2f3c896", + "bytes": 12, + "width": 1280, + "height": 800 + } + } + } + } + } + ] + }, + "metrics": { + "prompt_tokens": 7802, + "cached_tokens": 6144, + "completion_tokens": 121, + "extra": { + "agentenv": { + "cache_write_tokens": 1658 + } + } + }, + "llm_call_count": 1, + "extra": { + "agentenv": { + "reasoning": [ + { + "chars": 0, + "visibility": "omitted", + "signature": "EpwBCkYIBRgCIkB2" + } + ] + } + } + }, + { + "step_id": 4, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "", + "tool_calls": [ + { + "tool_call_id": "toolu_c3", + "function_name": "computer", + "arguments": { + "action": "type", + "text": "42" + } + } + ], + "observation": { + "results": [ + { + "source_call_id": "toolu_c3", + "content": [ + { + "type": "image", + "source": { + "media_type": "image/png", + "path": "media/482405b002a62efa8516c36709a7a100637507670576fa73a20ad5420d55c66f.png" + } + } + ], + "extra": { + "agentenv": { + "media": { + "media/482405b002a62efa8516c36709a7a100637507670576fa73a20ad5420d55c66f.png": { + "sha256": "482405b002a62efa8516c36709a7a100637507670576fa73a20ad5420d55c66f", + "bytes": 12, + "width": 1280, + "height": 800 + } + } + } + } + } + ] + }, + "metrics": { + "prompt_tokens": 9805, + "cached_tokens": 7680, + "completion_tokens": 47, + "extra": { + "agentenv": { + "cache_write_tokens": 2125 + } + } + }, + "llm_call_count": 1 + }, + { + "step_id": 5, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "B2 is now 42 and the file is saved.", + "metrics": { + "prompt_tokens": 12129, + "cached_tokens": 10969, + "completion_tokens": 23, + "extra": { + "agentenv": { + "cache_write_tokens": 1160 + } + } + }, + "llm_call_count": 1, + "extra": { + "agentenv": { + "state": "completed" + } + } + } + ], + "final_metrics": { + "total_prompt_tokens": 35946, + "total_completion_tokens": 249, + "total_cached_tokens": 29913, + "total_steps": 5, + "extra": { + "agentenv": { + "total_cache_write_tokens": 5967 + } + } + }, + "extra": { + "agentenv": { + "version": "1.0", + "native_format": "toy-events/1", + "adapter": { + "name": "toy-events-atif", + "version": "0.1.0" + } + } + } +} diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/late_result.json b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/late_result.json new file mode 100644 index 000000000..daa7ad0cb --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/late_result.json @@ -0,0 +1,145 @@ +{ + "schema_version": "ATIF-v1.8", + "session_id": "ctx-7f3a", + "agent": { + "name": "toy", + "version": "1.0", + "model_name": "claude-opus-5-5" + }, + "steps": [ + { + "step_id": 1, + "timestamp": "2026-11-04T17:00:00.000Z", + "source": "user", + "message": "Run the slow suite and check src/app.py meanwhile.", + "extra": { + "agentenv": { + "context_id": "ctx-7f3a", + "task_id": "task-l1", + "message_id": "msg-l1", + "turn": 0 + } + } + }, + { + "step_id": 2, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "", + "tool_calls": [ + { + "tool_call_id": "toolu_07", + "function_name": "Task", + "arguments": { + "description": "run the slow suite", + "run_in_background": true + } + } + ], + "observation": { + "results": [ + { + "source_call_id": "toolu_07", + "content": "312 passed", + "extra": { + "agentenv": { + "arrived": { + "at": "2026-11-04T17:09:12.004Z", + "step_id": 3 + } + } + } + } + ] + }, + "metrics": { + "prompt_tokens": 1000, + "cached_tokens": 800, + "completion_tokens": 50, + "extra": { + "agentenv": { + "cache_write_tokens": 100 + } + } + }, + "llm_call_count": 1 + }, + { + "step_id": 3, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "", + "tool_calls": [ + { + "tool_call_id": "toolu_08", + "function_name": "Read", + "arguments": { + "file_path": "src/app.py" + } + } + ], + "observation": { + "results": [ + { + "source_call_id": "toolu_08", + "content": "def main(): ..." + } + ] + }, + "metrics": { + "prompt_tokens": 1100, + "cached_tokens": 900, + "completion_tokens": 40, + "extra": { + "agentenv": { + "cache_write_tokens": 100 + } + } + }, + "llm_call_count": 1 + }, + { + "step_id": 4, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "The suite passes and app.py looks fine.", + "metrics": { + "prompt_tokens": 1200, + "cached_tokens": 1000, + "completion_tokens": 30, + "extra": { + "agentenv": { + "cache_write_tokens": 100 + } + } + }, + "llm_call_count": 1, + "extra": { + "agentenv": { + "state": "completed" + } + } + } + ], + "final_metrics": { + "total_prompt_tokens": 3300, + "total_completion_tokens": 120, + "total_cached_tokens": 2700, + "total_steps": 4, + "extra": { + "agentenv": { + "total_cache_write_tokens": 300 + } + } + }, + "extra": { + "agentenv": { + "version": "1.0", + "native_format": "toy-events/1", + "adapter": { + "name": "toy-events-atif", + "version": "0.1.0" + } + } + } +} diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/media/482405b002a62efa8516c36709a7a100637507670576fa73a20ad5420d55c66f.png b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/media/482405b002a62efa8516c36709a7a100637507670576fa73a20ad5420d55c66f.png new file mode 100644 index 000000000..faa904f21 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/media/482405b002a62efa8516c36709a7a100637507670576fa73a20ad5420d55c66f.png @@ -0,0 +1 @@ +screenshot-3 \ No newline at end of file diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/media/55c64d0fcd6f9d5f7c828093857e3fdfda68478bb4e9bd24d481ef391c7804e8.heic b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/media/55c64d0fcd6f9d5f7c828093857e3fdfda68478bb4e9bd24d481ef391c7804e8.heic new file mode 100644 index 000000000..9e2c0a25a --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/media/55c64d0fcd6f9d5f7c828093857e3fdfda68478bb4e9bd24d481ef391c7804e8.heic @@ -0,0 +1 @@ +photo \ No newline at end of file diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/media/67905ad3cc2dd52b1f5f6a6d2814de0396618b29b4238b9af5207aeb69936e6d.mp4 b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/media/67905ad3cc2dd52b1f5f6a6d2814de0396618b29b4238b9af5207aeb69936e6d.mp4 new file mode 100644 index 000000000..e3bd6ea9a --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/media/67905ad3cc2dd52b1f5f6a6d2814de0396618b29b4238b9af5207aeb69936e6d.mp4 @@ -0,0 +1 @@ +clip \ No newline at end of file diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/media/69a8aa01fe5537076d023dd5e9cc4275b39fc0434aa6483a9f58b66ef2f3c896.png b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/media/69a8aa01fe5537076d023dd5e9cc4275b39fc0434aa6483a9f58b66ef2f3c896.png new file mode 100644 index 000000000..cac0d9b37 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/media/69a8aa01fe5537076d023dd5e9cc4275b39fc0434aa6483a9f58b66ef2f3c896.png @@ -0,0 +1 @@ +screenshot-2 \ No newline at end of file diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/media/82e60066a2de261b6653bcdda90d1cb9a7af2f474cecd82e8d371e8384d72315.png b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/media/82e60066a2de261b6653bcdda90d1cb9a7af2f474cecd82e8d371e8384d72315.png new file mode 100644 index 000000000..d73256dad --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/media/82e60066a2de261b6653bcdda90d1cb9a7af2f474cecd82e8d371e8384d72315.png @@ -0,0 +1 @@ +screenshot-1 \ No newline at end of file diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/media/845e91831319e89c4d656bdb80c278ac09a7230d61e5dfd2e1b1fbb436ac8917.pdf b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/media/845e91831319e89c4d656bdb80c278ac09a7230d61e5dfd2e1b1fbb436ac8917.pdf new file mode 100644 index 0000000000000000000000000000000000000000..7d7e0b781bc291b6d477bcff5bee9ef37625c521 GIT binary patch literal 6 NcmXR)Eyyn_0RRaQ0-XQ= literal 0 HcmV?d00001 diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/multi_agent.json b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/multi_agent.json new file mode 100644 index 000000000..6b5ffe8d1 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/multi_agent.json @@ -0,0 +1,118 @@ +{ + "schema_version": "ATIF-v1.8", + "session_id": "ctx-1", + "agent": { + "name": "toy", + "version": "1.0", + "model_name": "claude-opus-5-5" + }, + "steps": [ + { + "step_id": 1, + "timestamp": "2026-11-04T18:01:40.530Z", + "source": "user", + "message": "[Email from Priya Shah] Board review moved to 3:00pm today.\n\nUgh. Can you make sure my 1:1 with Sam doesn't clash?", + "extra": { + "agentenv": { + "context_id": "ctx-1", + "task_id": "task-b2", + "message_id": "msg-b2", + "turn": 1 + } + } + }, + { + "step_id": 2, + "timestamp": "2026-11-04T18:01:46.902Z", + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "", + "reasoning_content": "Board is now 3-4pm; the 1:1 is at 3pm. Move the 1:1 to 4pm.", + "tool_calls": [ + { + "tool_call_id": "toolu_9a", + "function_name": "calendar_update_event", + "arguments": { + "event_id": "evt_1on1_sam", + "start": "2026-03-12T16:00:00-05:00", + "end": "2026-03-12T16:30:00-05:00" + } + } + ], + "observation": { + "results": [ + { + "source_call_id": "toolu_9a", + "content": "Updated evt_1on1_sam: 4:00pm-4:30pm" + } + ] + }, + "metrics": { + "prompt_tokens": 9120, + "cached_tokens": 0, + "completion_tokens": 144, + "extra": { + "agentenv": { + "cache_write_tokens": 0 + } + } + }, + "llm_call_count": 1, + "extra": { + "agentenv": { + "reasoning": [ + { + "chars": 59, + "visibility": "raw", + "signature": "ErUBCkYIBRgCKkAx" + } + ] + } + } + }, + { + "step_id": 3, + "timestamp": "2026-11-04T18:01:52.812Z", + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "Moved your 1:1 with Sam to 4:00pm, right after the board review.", + "metrics": { + "prompt_tokens": 9402, + "cached_tokens": 0, + "completion_tokens": 31, + "extra": { + "agentenv": { + "cache_write_tokens": 0 + } + } + }, + "llm_call_count": 1, + "extra": { + "agentenv": { + "state": "completed" + } + } + } + ], + "final_metrics": { + "total_prompt_tokens": 18522, + "total_completion_tokens": 175, + "total_cached_tokens": 0, + "total_steps": 3, + "extra": { + "agentenv": { + "total_cache_write_tokens": 0 + } + } + }, + "extra": { + "agentenv": { + "version": "1.0", + "native_format": "toy-events/1", + "adapter": { + "name": "toy-events-atif", + "version": "0.1.0" + } + } + } +} diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/odd_parts.json b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/odd_parts.json new file mode 100644 index 000000000..2dde0ae8e --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/odd_parts.json @@ -0,0 +1,182 @@ +{ + "schema_version": "ATIF-v1.8", + "session_id": "ctx-7f3a", + "agent": { + "name": "toy", + "version": "1.0", + "model_name": "claude-opus-5-5" + }, + "steps": [ + { + "step_id": 1, + "timestamp": "2026-11-04T17:00:00.000Z", + "source": "user", + "message": "Summarize the attached report and the clip.\n\n[document: media/845e91831319e89c4d656bdb80c278ac09a7230d61e5dfd2e1b1fbb436ac8917.pdf, 6 B, 12 pages]\n\n[video: media/67905ad3cc2dd52b1f5f6a6d2814de0396618b29b4238b9af5207aeb69936e6d.mp4, 4 B, 31 s]\n\n[image: media/55c64d0fcd6f9d5f7c828093857e3fdfda68478bb4e9bd24d481ef391c7804e8.heic, 5 B]\n\n{\"ticket\": 4411, \"priority\": \"high\"}", + "extra": { + "agentenv": { + "context_id": "ctx-7f3a", + "task_id": "task-o1", + "message_id": "msg-o1", + "turn": 0, + "media": { + "media/845e91831319e89c4d656bdb80c278ac09a7230d61e5dfd2e1b1fbb436ac8917.pdf": { + "sha256": "845e91831319e89c4d656bdb80c278ac09a7230d61e5dfd2e1b1fbb436ac8917", + "bytes": 6, + "pages": 12, + "media_type": "application/pdf" + }, + "media/67905ad3cc2dd52b1f5f6a6d2814de0396618b29b4238b9af5207aeb69936e6d.mp4": { + "sha256": "67905ad3cc2dd52b1f5f6a6d2814de0396618b29b4238b9af5207aeb69936e6d", + "bytes": 4, + "duration_ms": 31000, + "media_type": "video/mp4" + }, + "media/55c64d0fcd6f9d5f7c828093857e3fdfda68478bb4e9bd24d481ef391c7804e8.heic": { + "sha256": "55c64d0fcd6f9d5f7c828093857e3fdfda68478bb4e9bd24d481ef391c7804e8", + "bytes": 5, + "width": 640, + "height": 480, + "media_type": "image/heic" + } + } + } + } + }, + { + "step_id": 2, + "source": "agent", + "model_name": "claude-opus-5-5", + "reasoning_effort": "high", + "message": "Patching the summary file.\n\nPatch sent.", + "reasoning_content": "Read the report first.", + "tool_calls": [ + { + "tool_call_id": "toolu_p1", + "function_name": "apply_patch", + "arguments": { + "input": "*** Begin Patch\n*** End Patch" + }, + "extra": { + "raw_arguments": "*** Begin Patch\n*** End Patch" + } + } + ], + "observation": { + "results": [ + { + "source_call_id": "toolu_p1", + "content": "patch failed: no such file", + "extra": { + "agentenv": { + "status": "error", + "exit_code": 2 + } + } + } + ] + }, + "metrics": { + "prompt_tokens": 1900, + "cached_tokens": 800, + "completion_tokens": 50, + "extra": { + "agentenv": { + "cache_write_tokens": 100 + } + } + }, + "llm_call_count": 1, + "extra": { + "agentenv": { + "error": { + "kind": "infra_error", + "message": "sandbox disk full" + }, + "reasoning": [ + { + "chars": 22, + "visibility": "summary" + }, + { + "chars": 0, + "visibility": "redacted", + "data": "RVJyZWRhY3RlZA==" + } + ] + } + } + }, + { + "step_id": 3, + "source": "agent", + "message": "Retrying after a 529.", + "llm_call_count": 0, + "extra": { + "agentenv": { + "attempt": 2 + } + } + }, + { + "step_id": 4, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "Done: the summary is in SUMMARY.md.", + "metrics": { + "prompt_tokens": 3500, + "cached_tokens": 1500, + "completion_tokens": 40, + "cost_usd": 0.01, + "extra": { + "agentenv": { + "cache_write_tokens": 0, + "cost_source": "provider" + } + } + }, + "llm_call_count": 1, + "extra": { + "agentenv": { + "attempt": 2 + } + } + }, + { + "step_id": 5, + "timestamp": "2026-11-04T17:09:30.000Z", + "source": "agent", + "message": "Done: the summary is in SUMMARY.md.\n\n{\"files\": [\"SUMMARY.md\"]}", + "llm_call_count": 0, + "extra": { + "agentenv": { + "attempt": 2, + "state": "completed" + } + } + } + ], + "final_metrics": { + "total_prompt_tokens": 5400, + "total_completion_tokens": 90, + "total_cached_tokens": 2300, + "total_steps": 5, + "extra": { + "agentenv": { + "total_cache_write_tokens": 100 + } + } + }, + "extra": { + "agentenv": { + "version": "1.0", + "native_format": "toy-events/1", + "adapter": { + "name": "toy-events-atif", + "version": "0.1.0" + }, + "unmatched": { + "rate_limit_event": 1 + } + } + } +} diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/subagent.json b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/subagent.json new file mode 100644 index 000000000..78f6b2c97 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/subagent.json @@ -0,0 +1,171 @@ +{ + "schema_version": "ATIF-v1.8", + "session_id": "ctx-7f3a", + "agent": { + "name": "toy", + "version": "1.0", + "model_name": "claude-opus-5-5" + }, + "steps": [ + { + "step_id": 1, + "timestamp": "2026-11-04T17:00:00.000Z", + "source": "user", + "message": "Find the config files.", + "extra": { + "agentenv": { + "context_id": "ctx-7f3a", + "task_id": "task-s1", + "message_id": "msg-s1", + "turn": 0 + } + } + }, + { + "step_id": 2, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "", + "tool_calls": [ + { + "tool_call_id": "toolu_s1", + "function_name": "Task", + "arguments": { + "description": "find config files" + } + } + ], + "observation": { + "results": [ + { + "source_call_id": "toolu_s1", + "content": "Found a.toml, b.toml and c.toml.", + "subagent_trajectory_ref": [ + { + "trajectory_id": "sub1" + } + ] + } + ] + }, + "metrics": { + "prompt_tokens": 1000, + "cached_tokens": 800, + "completion_tokens": 50, + "extra": { + "agentenv": { + "cache_write_tokens": 100 + } + } + }, + "llm_call_count": 1 + }, + { + "step_id": 3, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "There are three: a.toml, b.toml and c.toml.", + "metrics": { + "prompt_tokens": 1050, + "cached_tokens": 900, + "completion_tokens": 30, + "extra": { + "agentenv": { + "cache_write_tokens": 50 + } + } + }, + "llm_call_count": 1, + "extra": { + "agentenv": { + "state": "completed" + } + } + } + ], + "subagent_trajectories": [ + { + "schema_version": "ATIF-v1.8", + "trajectory_id": "sub1", + "agent": { + "name": "explore", + "version": "unknown", + "model_name": "claude-haiku-5-5" + }, + "steps": [ + { + "step_id": 1, + "source": "agent", + "model_name": "claude-haiku-5-5", + "message": "", + "tool_calls": [ + { + "tool_call_id": "toolu_s2", + "function_name": "Bash", + "arguments": { + "command": "ls config" + } + } + ], + "observation": { + "results": [ + { + "source_call_id": "toolu_s2", + "content": "a.toml b.toml c.toml" + } + ] + }, + "metrics": { + "prompt_tokens": 500, + "cached_tokens": 400, + "completion_tokens": 20, + "extra": { + "agentenv": { + "cache_write_tokens": 50 + } + } + }, + "llm_call_count": 1 + }, + { + "step_id": 2, + "source": "agent", + "model_name": "claude-haiku-5-5", + "message": "Found a.toml, b.toml and c.toml.", + "metrics": { + "prompt_tokens": 510, + "cached_tokens": 450, + "completion_tokens": 15, + "extra": { + "agentenv": { + "cache_write_tokens": 0 + } + } + }, + "llm_call_count": 1 + } + ] + } + ], + "final_metrics": { + "total_prompt_tokens": 3060, + "total_completion_tokens": 115, + "total_cached_tokens": 2550, + "total_steps": 3, + "extra": { + "agentenv": { + "total_cache_write_tokens": 200 + } + } + }, + "extra": { + "agentenv": { + "version": "1.0", + "native_format": "toy-events/1", + "adapter": { + "name": "toy-events-atif", + "version": "0.1.0" + } + } + } +} diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/two_turns.json b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/two_turns.json new file mode 100644 index 000000000..ef02fb44d --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/fixtures/two_turns.json @@ -0,0 +1,301 @@ +{ + "schema_version": "ATIF-v1.8", + "session_id": "ctx-7f3a", + "agent": { + "name": "toy", + "version": "1.0", + "model_name": "claude-opus-5-5" + }, + "steps": [ + { + "step_id": 1, + "timestamp": "2026-11-04T17:02:11.204Z", + "source": "user", + "message": "tests/test_parse.py::test_utc fails. Fix parse_date without changing the test.", + "extra": { + "agentenv": { + "context_id": "ctx-7f3a", + "task_id": "task-91c2", + "message_id": "msg-a1", + "turn": 0 + } + } + }, + { + "step_id": 2, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "", + "reasoning_content": "Run the failing test first to see the error.", + "tool_calls": [ + { + "tool_call_id": "toolu_01", + "function_name": "Bash", + "arguments": { + "command": "pytest tests/test_parse.py -q" + } + } + ], + "observation": { + "results": [ + { + "source_call_id": "toolu_01", + "content": "FAILED tests/test_parse.py::test_utc - ValueError: Invalid isoformat string: '2026-01-02T03:04:05Z'", + "extra": { + "agentenv": { + "status": "error", + "exit_code": 1 + } + } + } + ] + }, + "metrics": { + "prompt_tokens": 18432, + "cached_tokens": 16890, + "completion_tokens": 212, + "extra": { + "agentenv": { + "cache_write_tokens": 1402 + } + } + }, + "llm_call_count": 1, + "extra": { + "agentenv": { + "reasoning": [ + { + "chars": 44, + "visibility": "raw", + "signature": "EqQBCkgIBhABGAIiQKm3" + } + ] + } + } + }, + { + "step_id": 3, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "", + "tool_calls": [ + { + "tool_call_id": "toolu_02", + "function_name": "Read", + "arguments": { + "file_path": "tests/fixtures/dates.txt" + } + } + ], + "observation": { + "results": [ + { + "source_call_id": "toolu_02", + "content": "2026-01-01T03:04:05Z -> 2026-01-01 03:04:05+00:00\n2026-01-02T03:04:05Z -> 2026-01-02 03:04:05+00:00\n2026-01-03T03:04:05Z -> 2026-01-03 03:04:05+00:00\n2026-01-04T03:04:05Z -> 2026-01-04 03:04:05+00:00\n2026-01-05T03:04:05Z -> 2026-01-05 03:04:05+00:00\n2026-01-06T03:04:05Z -> 2026-01-06 03:04:05+00:00\n2026-01-07T03:04:05Z -> 2026-01-07 03:04:05+00:00\n2026-01-08T03:04:05Z -> 2026-01-08 03:04:05+00:00\n2026-01-09T03:04:05Z -> 2026-01-09 03:04:05+00:00\n2026-01-10T03:04:05Z -> 2026-01-10 03:04:05+00:00\n2026-01-11T03:04:05Z -> 2026-01-11 03:04:05+00:00\n2026-01-12T03:04:05Z -> 2026-01-12 03:04:05+00:00\n2026-01-13T03:04:05Z -> 2026-01-13 03:04:05+00:00\n2026-01-14T03:04:05Z -> 2026-01-14 03:04:05+00:00\n2026-01-15T03:04:05Z -> 2026-01-15 03:04:05+00:00\n2026-01-16T03:04:05Z -> 2026-01-16 03:04:05+00:00\n2026-01-17T03:04:05Z -> 2026-01-17 03:04:05+00:00\n2026-01-18T03:04:05Z -> 2026-01-18 03:04:05+00:00\n2026-01-19T03:04:05Z -> 2026-01-19 03:04:05+00:00\n2026-01-20T03:04:05Z -> 2026-01-20 03:04:05+00:00\n2026-01-21T03:04:05Z -> 2026-01-21 03:04:05+00:00\n2026-01-22T03:04:05Z -> 2026-01-22 03:04:05+00:00\n2026-01-23T03:04:05Z -> 2026-01-23 03:04:05+00:00\n2026-01-24T03:04:05Z -> 2026-01-24 03:04:05+00:00\n2026-01-25T03:04:05Z -> 2026-01-25 03:04:05+00:00\n2026-01-26T03:04:05Z -> 2026-01-26 03:04:05+00:00\n2026-01-27T03:04:05Z -> 2026-01-27 03:04:05+00:00\n2026-01-28T03:04:05Z -> 2026-01-28 03:04:05+00:00\n" + } + ] + }, + "metrics": { + "prompt_tokens": 18901, + "cached_tokens": 18292, + "completion_tokens": 96, + "extra": { + "agentenv": { + "cache_write_tokens": 469 + } + } + }, + "llm_call_count": 1 + }, + { + "step_id": 4, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "", + "tool_calls": [ + { + "tool_call_id": "toolu_03", + "function_name": "Edit", + "arguments": { + "file_path": "src/parse.py", + "old_string": "datetime.fromisoformat(s)", + "new_string": "datetime.fromisoformat(s.replace('Z', '+00:00'))" + } + } + ], + "observation": { + "results": [ + { + "source_call_id": "toolu_03", + "content": "The file src/parse.py has been updated." + } + ] + }, + "metrics": { + "prompt_tokens": 31377, + "cached_tokens": 18761, + "completion_tokens": 188, + "extra": { + "agentenv": { + "cache_write_tokens": 12476 + } + } + }, + "llm_call_count": 1 + }, + { + "step_id": 5, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "", + "tool_calls": [ + { + "tool_call_id": "toolu_04", + "function_name": "Bash", + "arguments": { + "command": "pytest tests/test_parse.py -q" + } + } + ], + "observation": { + "results": [ + { + "source_call_id": "toolu_04", + "content": "3 passed in 0.18s" + } + ] + }, + "metrics": { + "prompt_tokens": 31702, + "cached_tokens": 31237, + "completion_tokens": 74, + "extra": { + "agentenv": { + "cache_write_tokens": 325 + } + } + }, + "llm_call_count": 1 + }, + { + "step_id": 6, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "parse_date now accepts a trailing Z; all 3 tests in tests/test_parse.py pass.", + "metrics": { + "prompt_tokens": 31890, + "cached_tokens": 31562, + "completion_tokens": 41, + "extra": { + "agentenv": { + "cache_write_tokens": 188 + } + } + }, + "llm_call_count": 1, + "extra": { + "agentenv": { + "state": "completed" + } + } + }, + { + "step_id": 7, + "timestamp": "2026-11-04T17:05:00.000Z", + "source": "user", + "message": "Also cover a +05:30 offset.", + "extra": { + "agentenv": { + "context_id": "ctx-7f3a", + "task_id": "task-91c3", + "message_id": "msg-a2", + "turn": 1 + } + } + }, + { + "step_id": 8, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "", + "tool_calls": [ + { + "tool_call_id": "toolu_05", + "function_name": "Edit", + "arguments": { + "file_path": "tests/test_parse.py", + "old_string": "", + "new_string": "def test_offset(): ..." + } + } + ], + "observation": { + "results": [ + { + "source_call_id": "toolu_05", + "content": "The file tests/test_parse.py has been updated." + } + ] + }, + "metrics": { + "prompt_tokens": 32240, + "cached_tokens": 31700, + "completion_tokens": 90, + "extra": { + "agentenv": { + "cache_write_tokens": 400 + } + } + }, + "llm_call_count": 1 + }, + { + "step_id": 9, + "source": "agent", + "model_name": "claude-opus-5-5", + "message": "Added test_offset.", + "metrics": { + "prompt_tokens": 32360, + "cached_tokens": 32100, + "completion_tokens": 12, + "extra": { + "agentenv": { + "cache_write_tokens": 120 + } + } + }, + "llm_call_count": 1, + "extra": { + "agentenv": { + "state": "completed" + } + } + } + ], + "final_metrics": { + "total_prompt_tokens": 196902, + "total_completion_tokens": 713, + "total_cached_tokens": 180542, + "total_cost_usd": 0.2558, + "total_steps": 9, + "extra": { + "agentenv": { + "cost_source": "harness", + "total_cache_write_tokens": 15380 + } + } + }, + "extra": { + "agentenv": { + "version": "1.0", + "native_format": "toy-events/1", + "adapter": { + "name": "toy-events-atif", + "version": "0.1.0" + }, + "unmatched": { + "system": 1 + } + } + } +} diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/LICENSE b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/LICENSE new file mode 100644 index 000000000..261eeb9e9 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/VENDORED.md b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/VENDORED.md new file mode 100644 index 000000000..99e986e0f --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/VENDORED.md @@ -0,0 +1,23 @@ +# Vendored ATIF models + +These files are Harbor's ATIF models, from `harbor/models/trajectories/` in the Harbor 0.26.0 release on PyPI (`harbor-0.26.0-py3-none-any.whl`, sha256 +`b7c752c5b51ae2ee1fc2ea30621493c7dc0b5a3d0157295bed4552115027baee`). Harbor is Apache-2.0; `LICENSE` beside this file is the license that wheel ships. + +The only change is import paths: each `from harbor.models.trajectories...` import reads `from agentenv_protocol.atif.models...`. Nothing else differs. A unit +test turns the imports back and checks each file's sha256 against the table below. + +Refresh with `python scripts/vendor_atif.py ` from the repository root, then review the diff and the fixtures. + +| File | Upstream sha256 | +| --- | --- | +| `__init__.py` | `8eac32584166ff8f3a30d42027bc53793c4804fed7b07dcc4a94795557e11846` | +| `agent.py` | `ae26f91b1aa9cba2f9f308b3b1b6a8e92c0851bb191e4bd8df3042b49a0425c6` | +| `content.py` | `568f8ac708141b63b5facb363274b93d8bb76ae36250bcee656781f189ad3426` | +| `final_metrics.py` | `c4897c3b7f6d6be0d891d5fc9a72d13407d01c897c099e3ca195c50424734caf` | +| `metrics.py` | `c6d724d80d250dd27fefc4462a3f70aff2333fe42775382cb8073b889becf165` | +| `observation.py` | `2bb40e781053428e172af45110b0119bda4143594d592e414e9af0a60f057d28` | +| `observation_result.py` | `edbe26ca85aa8ef5f13a08a62d4d777d20832a7a5b67dcfa9162d6dbdaaf4c0a` | +| `step.py` | `6d8cc176449e0d5be46b40fdc9802bcb417f6b11d295c111e670055552abaa4a` | +| `subagent_trajectory_ref.py` | `207388b30eec20aaba3d21effb66f984caecfa0cb23dbaaa8fc055abd6347aea` | +| `tool_call.py` | `b28fc0526c45a5a253edaaaa305a8f53ac436e5fd44918fe4dadbe573214030b` | +| `trajectory.py` | `74c3aa74f3de38cdcdf3727b771c7ad75d66c2f5a6b43ec7982ed5b1e56b6fbf` | diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/__init__.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/__init__.py new file mode 100644 index 000000000..e8f939aab --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/__init__.py @@ -0,0 +1,35 @@ +"""Pydantic models for Agent Trajectory Interchange Format (ATIF). + +This module provides Pydantic models for validating and constructing +trajectory data following the ATIF specification (RFC 0001). +""" + +from agentenv_protocol.atif.models.agent import Agent +from agentenv_protocol.atif.models.content import ( + AudioSource, + ContentPart, + ImageSource, +) +from agentenv_protocol.atif.models.final_metrics import FinalMetrics +from agentenv_protocol.atif.models.metrics import Metrics +from agentenv_protocol.atif.models.observation import Observation +from agentenv_protocol.atif.models.observation_result import ObservationResult +from agentenv_protocol.atif.models.step import Step +from agentenv_protocol.atif.models.subagent_trajectory_ref import SubagentTrajectoryRef +from agentenv_protocol.atif.models.tool_call import ToolCall +from agentenv_protocol.atif.models.trajectory import Trajectory + +__all__ = [ + "Agent", + "AudioSource", + "ContentPart", + "FinalMetrics", + "ImageSource", + "Metrics", + "Observation", + "ObservationResult", + "Step", + "SubagentTrajectoryRef", + "ToolCall", + "Trajectory", +] diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/agent.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/agent.py new file mode 100644 index 000000000..1f9cd992c --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/agent.py @@ -0,0 +1,32 @@ +"""Agent configuration model for ATIF trajectories.""" + +from typing import Any + +from pydantic import BaseModel, Field + + +class Agent(BaseModel): + """Agent configuration.""" + + name: str = Field( + default=..., + description="The name of the agent system", + ) + version: str = Field( + default=..., + description="The version identifier of the agent system", + ) + model_name: str | None = Field( + default=None, + description="Default LLM model used for this trajectory", + ) + tool_definitions: list[dict[str, Any]] | None = Field( + default=None, + description="Array of tool/function definitions available to the agent. Each element follows OpenAI's function calling schema.", + ) + extra: dict[str, Any] | None = Field( + default=None, + description="Custom agent configuration details", + ) + + model_config = {"extra": "forbid"} diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/content.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/content.py new file mode 100644 index 000000000..ee092bdf0 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/content.py @@ -0,0 +1,156 @@ +"""Content models for multimodal ATIF trajectories. + +Added in ATIF-v1.6 to support multimodal content (images) in trajectories. +Extended in ATIF-v1.8 with audio. +""" + +from typing import Any, Literal + +from pydantic import BaseModel, Field, field_validator, model_validator + +# Canonical audio MIME types, chosen to cover what multimodal and transcription +# APIs actually accept: Gemini audio understanding (wav, mp3, aiff, aac, ogg, +# flac), OpenAI transcription (flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm), +# and `audio/webm`, which is what a browser's MediaRecorder produces and so what +# human-recorded task data usually arrives as. +AudioMediaType = Literal[ + "audio/wav", + "audio/mpeg", + "audio/mp4", + "audio/aac", + "audio/ogg", + "audio/flac", + "audio/webm", + "audio/aiff", +] + +# Aliases producers emit in place of the registered MIME type, normalized on the +# way in so consumers only ever see one spelling per format. `audio/mp3` is the +# important one: it is not a registered type, but the Gemini API documents and +# emits it, so a producer copying a provider response verbatim would otherwise +# fail validation. +_AUDIO_MEDIA_TYPE_ALIASES = { + "audio/mp3": "audio/mpeg", + "audio/mpga": "audio/mpeg", + "audio/x-mpeg": "audio/mpeg", + "audio/x-wav": "audio/wav", + "audio/wave": "audio/wav", + "audio/vnd.wave": "audio/wav", + "audio/x-m4a": "audio/mp4", + "audio/m4a": "audio/mp4", + "audio/x-aac": "audio/aac", + "audio/x-flac": "audio/flac", + "audio/x-aiff": "audio/aiff", +} + + +class ImageSource(BaseModel): + """Image source specification for images stored as files or at remote URLs.""" + + media_type: Literal["image/jpeg", "image/png", "image/gif", "image/webp"] = Field( + default=..., + description="MIME type of the image", + ) + path: str = Field( + default=..., + description=( + "Location of the image. Can be a relative or absolute file path, or a URL." + ), + ) + + model_config = {"extra": "forbid"} + + +class AudioSource(BaseModel): + """Audio source specification for audio stored as files or at remote URLs. + + Added in ATIF-v1.8. Mirrors ``ImageSource`` so that consumers can treat any + referenced media the same way, with one addition: ``duration_sec``. Duration + is worth recording because several providers bill audio per second and + dataset statistics need it, and unlike an image's dimensions it cannot be + recovered without decoding the file. + """ + + media_type: AudioMediaType = Field( + default=..., + description="MIME type of the audio", + ) + path: str = Field( + default=..., + description=( + "Location of the audio. Can be a relative or absolute file path, or a URL." + ), + ) + duration_sec: float | None = Field( + default=None, + ge=0, + description=( + "Optional duration of the audio in seconds. Useful for cost " + "accounting and dataset statistics; omit when unknown." + ), + ) + + model_config = {"extra": "forbid"} + + @field_validator("media_type", mode="before") + @classmethod + def normalize_media_type(cls, value: Any) -> Any: + """Accept common non-registered spellings, storing the canonical one.""" + if isinstance(value, str): + normalized = value.strip().lower() + return _AUDIO_MEDIA_TYPE_ALIASES.get(normalized, normalized) + return value + + +class ContentPart(BaseModel): + """A single content part within a multimodal message. + + Used when a message or observation contains mixed content types (text, + images, or audio). For text-only content, a plain string can still be used + instead of a ContentPart array. + """ + + type: Literal["text", "image", "audio"] = Field( + default=..., + description="The type of content", + ) + text: str | None = Field( + default=None, + description="Text content. Required when type='text'.", + ) + source: ImageSource | AudioSource | None = Field( + default=None, + description=( + "Media source (file reference). Required when type='image' or " + "type='audio', and must match that type." + ), + ) + + model_config = {"extra": "forbid"} + + @model_validator(mode="after") + def validate_content_type(self) -> "ContentPart": + """Validate that the correct fields are present for each content type.""" + if self.type == "text": + if self.text is None: + raise ValueError("'text' field is required when type='text'") + if self.source is not None: + raise ValueError("'source' field is not allowed when type='text'") + return self + + # Media parts: a source is required, text is not allowed, and the source + # must be of the kind the `type` declares. Without the last check a + # `source` union would happily accept an ImageSource under + # type='audio' (and vice versa), silently mislabelling the content. + if self.source is None: + raise ValueError(f"'source' field is required when type='{self.type}'") + if self.text is not None: + raise ValueError(f"'text' field is not allowed when type='{self.type}'") + + expected = ImageSource if self.type == "image" else AudioSource + if not isinstance(self.source, expected): + raise ValueError( + f"type='{self.type}' requires a {expected.__name__}, but the " + f"source's media_type is {self.source.media_type!r}" + ) + return self diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/final_metrics.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/final_metrics.py new file mode 100644 index 000000000..a30c3fca2 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/final_metrics.py @@ -0,0 +1,40 @@ +"""Final metrics model for ATIF trajectories.""" + +from typing import Any + +from pydantic import BaseModel, Field + + +class FinalMetrics(BaseModel): + """Aggregate statistics for the entire trajectory.""" + + total_prompt_tokens: int | None = Field( + default=None, + description="Sum of all prompt tokens across all steps, including cached tokens", + ) + total_completion_tokens: int | None = Field( + default=None, + description="Sum of all completion tokens across all steps", + ) + total_cached_tokens: int | None = Field( + default=None, + description="Sum of all cached tokens across all steps", + ) + total_cost_usd: float | None = Field( + default=None, + description="Total real monetary cost for the entire trajectory, including cost for subagents, if any", + ) + total_steps: int | None = Field( + default=None, + ge=0, + description=( + "Total number of steps. If not equivalent to the number of steps in the " + "trajectory, must be documented in the root-level notes field." + ), + ) + extra: dict[str, Any] | None = Field( + default=None, + description="Custom aggregate metrics", + ) + + model_config = {"extra": "forbid"} diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/metrics.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/metrics.py new file mode 100644 index 000000000..e79185d93 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/metrics.py @@ -0,0 +1,44 @@ +"""Metrics model for ATIF trajectories.""" + +from typing import Any + +from pydantic import BaseModel, Field + + +class Metrics(BaseModel): + """LLM operational and confidence data.""" + + prompt_tokens: int | None = Field( + default=None, + description="Total input tokens including cached and non-cached", + ) + completion_tokens: int | None = Field( + default=None, + description="Total tokens generated by the LLM response", + ) + cached_tokens: int | None = Field( + default=None, + description="Subset of prompt_tokens that were cache hits", + ) + cost_usd: float | None = Field( + default=None, + description="Monetary cost of the API call in USD", + ) + prompt_token_ids: list[int] | None = Field( + default=None, + description="Token IDs for prompt (input) tokens sent to the LLM, including chat history (if applicable)", + ) + completion_token_ids: list[int] | None = Field( + default=None, + description="Token IDs for completion (response) tokens, enabling RL training without retokenization drift", + ) + logprobs: list[float] | None = Field( + default=None, + description="Log probability assigned to each generated token", + ) + extra: dict[str, Any] | None = Field( + default=None, + description="Other metrics", + ) + + model_config = {"extra": "forbid"} diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/observation.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/observation.py new file mode 100644 index 000000000..fb4896f4e --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/observation.py @@ -0,0 +1,16 @@ +"""Observation model for ATIF trajectories.""" + +from pydantic import BaseModel, Field + +from agentenv_protocol.atif.models.observation_result import ObservationResult + + +class Observation(BaseModel): + """Environment feedback/result after actions or system events.""" + + results: list[ObservationResult] = Field( + default=..., + description="Array of result objects from tool calls or actions", + ) + + model_config = {"extra": "forbid"} diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/observation_result.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/observation_result.py new file mode 100644 index 000000000..e979954cb --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/observation_result.py @@ -0,0 +1,42 @@ +"""Observation result model for ATIF trajectories.""" + +from typing import Any + +from pydantic import BaseModel, Field + +from agentenv_protocol.atif.models.content import ContentPart +from agentenv_protocol.atif.models.subagent_trajectory_ref import SubagentTrajectoryRef + + +class ObservationResult(BaseModel): + """A single result within an observation.""" + + source_call_id: str | None = Field( + default=None, + description=( + "The `tool_call_id` from the _tool_calls_ array in _StepObject_ that this " + "result corresponds to. If null or omitted, the result comes from an " + "action that doesn't use the standard tool calling format (e.g., agent " + "actions without tool calls or system-initiated operations)." + ), + ) + content: str | list[ContentPart] | None = Field( + default=None, + description=( + "The output or result from the tool execution. String for text-only " + "content, or array of ContentPart for multimodal content (added in ATIF-v1.6)." + ), + ) + subagent_trajectory_ref: list[SubagentTrajectoryRef] | None = Field( + default=None, + description="Array of references to delegated subagent trajectories", + ) + extra: dict[str, Any] | None = Field( + default=None, + description=( + "Custom observation-result-level metadata (e.g., confidence score, " + "retrieval score, source document ID). Added in ATIF-v1.7." + ), + ) + + model_config = {"extra": "forbid"} diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/step.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/step.py new file mode 100644 index 000000000..7f52431e6 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/step.py @@ -0,0 +1,139 @@ +"""Step model for ATIF trajectories.""" + +from datetime import datetime +from typing import Any, Literal + +from pydantic import BaseModel, Field, field_validator, model_validator + +from agentenv_protocol.atif.models.content import ContentPart +from agentenv_protocol.atif.models.metrics import Metrics +from agentenv_protocol.atif.models.observation import Observation +from agentenv_protocol.atif.models.tool_call import ToolCall + + +class Step(BaseModel): + """A single step in the trajectory.""" + + step_id: int = Field( + default=..., + ge=1, + description="Ordinal index of the turn (starting from 1)", + ) + timestamp: str | None = Field( + default=None, + description="ISO 8601 timestamp indicating when this step occurred", + ) + source: Literal["system", "user", "agent"] = Field( + default=..., + description="The originator of this step", + ) + model_name: str | None = Field( + default=None, + description=( + "The specific LLM model used for this turn. Omission implies the model " + "defined in the root-level agent config." + ), + ) + reasoning_effort: str | float | None = Field( + default=None, + description="Qualitative or quantitative measure of effort", + ) + message: str | list[ContentPart] = Field( + default=..., + description=( + "The dialogue message. String for text-only content, or array of " + "ContentPart for multimodal content (added in ATIF-v1.6)." + ), + ) + reasoning_content: str | None = Field( + default=None, + description="The agent's explicit internal reasoning", + ) + tool_calls: list[ToolCall] | None = Field( + default=None, + description="Array of structured objects for the agent's actions", + ) + observation: Observation | None = Field( + default=None, + description="Environment feedback/result after actions or system events", + ) + metrics: Metrics | None = Field( + default=None, + description="LLM operational and confidence data for this step", + ) + is_copied_context: bool | None = Field( + default=None, + description=( + "Indicates whether this step was copied from a previous trajectory " + "for context (e.g., during continuation after summarization). " + "Steps marked as copied context should not be included in training data " + "as they represent previously-trained interactions. " + "Added in ATIF-v1.5." + ), + ) + llm_call_count: int | None = Field( + default=None, + ge=0, + description=( + "Number of LLM inferences this step represents. When >1, metrics are " + "aggregated across multiple LLM calls. When 1, the step represents exactly " + "one inference. When 0 on a `source: 'agent'` step, the step represents a " + "deterministic (non-LLM) dispatch; `metrics` and `reasoning_content` MUST " + "be absent in that case. When null, the producer did not track this " + "(backward-compatible default). Added in ATIF-v1.7." + ), + ) + extra: dict[str, Any] | None = Field( + default=None, + description="Custom step-level metadata", + ) + + model_config = {"extra": "forbid"} + + @field_validator("timestamp") + @classmethod + def validate_timestamp(cls, v: str | None) -> str | None: + """Validate that timestamp is a valid ISO 8601 string.""" + if v is not None: + try: + datetime.fromisoformat(v.replace("Z", "+00:00")) + except ValueError as e: + raise ValueError(f"Invalid ISO 8601 timestamp: {e}") + return v + + @model_validator(mode="after") + def validate_agent_only_fields(self) -> "Step": + """Validate that certain fields are only present for agent steps.""" + if self.source != "agent": + agent_only_fields = [ + "model_name", + "reasoning_effort", + "reasoning_content", + "tool_calls", + "metrics", + ] + for field in agent_only_fields: + if getattr(self, field) is not None: + raise ValueError( + f"Field '{field}' is only applicable when source is 'agent', " + f"but source is '{self.source}'" + ) + return self + + @model_validator(mode="after") + def validate_llm_call_count_zero_fields(self) -> "Step": + """Enforce ATIF v1.7 no-LLM orchestration rule. + + When ``llm_call_count == 0`` on a ``source: "agent"`` step, the step + represents a deterministic (non-LLM) dispatch. LLM-specific fields + (``metrics``, ``reasoning_content``) MUST be absent on such steps. + """ + if self.llm_call_count == 0 and self.source == "agent": + llm_only_fields = ["metrics", "reasoning_content"] + for field in llm_only_fields: + if getattr(self, field) is not None: + raise ValueError( + f"Field '{field}' must be absent when llm_call_count is 0 " + f"(deterministic dispatch on a 'source: agent' step)" + ) + return self diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/subagent_trajectory_ref.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/subagent_trajectory_ref.py new file mode 100644 index 000000000..f6fea9168 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/subagent_trajectory_ref.py @@ -0,0 +1,85 @@ +"""Subagent trajectory reference model for ATIF trajectories.""" + +from typing import Any + +from pydantic import BaseModel, Field, model_validator + + +class SubagentTrajectoryRef(BaseModel): + """Reference to a delegated subagent trajectory. + + A subagent reference is resolved by one of two mechanisms: + + 1. **Embedded form** — set `trajectory_id` to match the + `Trajectory.trajectory_id` of an entry in the parent's + `subagent_trajectories` array. + 2. **File-ref form** — set `trajectory_path` to the location + (file path, S3 URL, etc.) of an external trajectory file. + + These two mechanisms are the only resolution keys. `session_id`, when + present on the ref, is **informational only**: it records the run + identity of the delegated subagent for debug / correlation / cross- + trajectory search purposes, and MUST NOT be used as a matching key + (it is run-scoped and MAY collide across siblings — see + `Trajectory.session_id`). A ref therefore MUST set at least one of + `trajectory_id` or `trajectory_path`; `session_id` alone is not a + resolvable reference. + """ + + trajectory_id: str | None = Field( + default=None, + description=( + "Canonical identifier of the delegated subagent trajectory. " + "Matches `Trajectory.trajectory_id` of an entry in the parent's " + "`subagent_trajectories` array and is the resolution key for " + "embedded references. Added in ATIF-v1.7 to provide a document-" + "unique matching key without overloading `session_id`." + ), + ) + session_id: str | None = Field( + default=None, + description=( + "Run identity of the delegated subagent trajectory. Informational " + "only: recorded so consumers can correlate this ref back to the " + "subagent's run for debug / search / display purposes. Run-scoped " + "(see `Trajectory.session_id`) and therefore NOT a valid " + "resolution key — consumers MUST resolve via `trajectory_id` " + "(embedded) or `trajectory_path` (external file)." + ), + ) + trajectory_path: str | None = Field( + default=None, + description=( + "Location of the complete subagent trajectory as an external " + "file (file path, S3 URL, database reference, etc.). Resolution " + "key for file-ref references. When both `trajectory_id` and " + "`trajectory_path` are set, consumers MAY choose either; " + "typically `trajectory_id` is preferred when the embedded " + "trajectory is available in-memory." + ), + ) + extra: dict[str, Any] | None = Field( + default=None, + description="Custom metadata about the subagent execution", + ) + + model_config = {"extra": "forbid"} + + @model_validator(mode="after") + def validate_is_resolvable(self) -> "SubagentTrajectoryRef": + """A ref must be resolvable: set `trajectory_id` or `trajectory_path`. + + `session_id` alone is not sufficient because it is run-scoped and + MAY collide across siblings (see `Trajectory.session_id`), so it + cannot unambiguously identify which subagent trajectory a ref + points at. + """ + if self.trajectory_id is None and self.trajectory_path is None: + raise ValueError( + "SubagentTrajectoryRef must be resolvable: set either " + "`trajectory_id` (for embedded references) or " + "`trajectory_path` (for external-file references). " + "`session_id` alone is not a resolution key — it is " + "run-scoped and may collide across siblings." + ) + return self diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/tool_call.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/tool_call.py new file mode 100644 index 000000000..2dd0d697b --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/tool_call.py @@ -0,0 +1,31 @@ +"""Tool call model for ATIF trajectories.""" + +from typing import Any + +from pydantic import BaseModel, Field + + +class ToolCall(BaseModel): + """A tool call within a step.""" + + tool_call_id: str = Field( + default=..., + description="Unique identifier for this specific tool call", + ) + function_name: str = Field( + default=..., + description="The name of the function or tool being invoked", + ) + arguments: dict[str, Any] = Field( + default=..., + description="Arguments passed to the function (can be empty dict)", + ) + extra: dict[str, Any] | None = Field( + default=None, + description=( + "Custom tool-call-level metadata (e.g., timeout, retry count, tool version). " + "Added in ATIF-v1.7." + ), + ) + + model_config = {"extra": "forbid"} diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/trajectory.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/trajectory.py new file mode 100644 index 000000000..53e1d478c --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/trajectory.py @@ -0,0 +1,206 @@ +"""Trajectory model for ATIF (Agent Trajectory Interchange Format).""" + +from typing import Any, Literal + +from pydantic import BaseModel, Field, model_validator + +from agentenv_protocol.atif.models.agent import Agent +from agentenv_protocol.atif.models.final_metrics import FinalMetrics +from agentenv_protocol.atif.models.step import Step + + +class Trajectory(BaseModel): + """Agent Trajectory in ATIF (Agent Trajectory Interchange Format).""" + + schema_version: Literal[ + "ATIF-v1.0", + "ATIF-v1.1", + "ATIF-v1.2", + "ATIF-v1.3", + "ATIF-v1.4", + "ATIF-v1.5", + "ATIF-v1.6", + "ATIF-v1.7", + "ATIF-v1.8", + ] = Field( + default="ATIF-v1.8", + description="String defining ATIF compatibility", + ) + session_id: str | None = Field( + default=None, + description=( + "Identifier for the agent run this trajectory belongs to. Scoped " + "to the run, NOT to an individual trajectory document: multiple " + "Trajectory objects MAY share the same `session_id` when they " + "represent the same logical run (e.g., a parent trajectory and " + "its embedded subagents, or a trajectory and its continuation " + "segments linked via `continued_trajectory_ref`). Therefore " + "`session_id`s within a parent's `subagent_trajectories` array " + "are NOT required to be unique. Use `trajectory_id` when a " + "per-trajectory-document unique identifier is required (e.g., " + "for `SubagentTrajectoryRef` resolution). Optional since " + "ATIF-v1.7; producers SHOULD set this on root trajectories for " + "run-level traceability, and MAY omit it on embedded subagents " + "that inherit the parent's run identity." + ), + ) + trajectory_id: str | None = Field( + default=None, + description=( + "Canonical per-trajectory-document identifier, distinct from " + "`session_id`. Unlike `session_id` (which is run-scoped and MAY " + "be shared), `trajectory_id` uniquely identifies THIS trajectory " + "object. Used to resolve `SubagentTrajectoryRef` entries against " + "the root's `subagent_trajectories` array without overloading " + "`session_id`'s run-scoped semantics. Optional on standalone " + "trajectories, but REQUIRED on any trajectory embedded in a " + "parent's `subagent_trajectories` array. `trajectory_id`s within " + "a single parent's `subagent_trajectories` array MUST be unique. " + "Added in ATIF-v1.7." + ), + ) + agent: Agent = Field( + default=..., + description="Object specifying the agent configuration", + ) + steps: list[Step] = Field( + default=..., + min_length=1, + description="Array of step objects representing the complete interaction history", + ) + notes: str | None = Field( + default=None, + description="Custom information, design notes, or explanations", + ) + final_metrics: FinalMetrics | None = Field( + default=None, + description="Summary metrics for the entire trajectory", + ) + continued_trajectory_ref: str | None = Field( + default=None, + description="Reference to the continuation trajectory file if this trajectory is continued in another file", + ) + extra: dict[str, Any] | None = Field( + default=None, + description="Custom root-level metadata", + ) + subagent_trajectories: list["Trajectory"] | None = Field( + default=None, + description=( + "Array of embedded subagent trajectories. Each element is a complete, " + "independently-valid ATIF Trajectory with its own schema_version, " + "agent, and step_id sequence starting at 1. Enables single-file " + "storage of multi-agent workflows: when a " + "SubagentTrajectoryRef.trajectory_path is null, consumers resolve " + "the reference by matching SubagentTrajectoryRef.trajectory_id " + "against Trajectory.trajectory_id of entries in this array. " + "Uniqueness rules: every embedded subagent MUST set `trajectory_id`, " + "and `trajectory_id`s within this array MUST be unique. " + "`session_id`, by contrast, is run-scoped and MAY collide across " + "siblings (or match the parent) when all trajectories belong to " + "the same logical run; embedded subagents MAY also omit " + "`session_id` entirely to inherit the parent's run identity. " + "Added in ATIF-v1.7." + ), + ) + + model_config = {"extra": "forbid"} + + def to_json_dict(self, exclude_none: bool = True) -> dict[str, Any]: + """Export trajectory to a dictionary suitable for JSON serialization. + + Args: + exclude_none: If True, exclude fields with None values from output. + + Returns: + Dictionary representation of the trajectory. + """ + return self.model_dump(exclude_none=exclude_none, mode="json") + + @model_validator(mode="after") + def validate_step_ids(self) -> "Trajectory": + """Validate that step_ids are sequential starting from 1.""" + for i, step in enumerate(self.steps): + expected_step_id = i + 1 + if step.step_id != expected_step_id: + raise ValueError( + f"steps[{i}].step_id: expected {expected_step_id} " + f"(sequential from 1), got {step.step_id}" + ) + return self + + @model_validator(mode="after") + def validate_embedded_subagent_trajectory_ids(self) -> "Trajectory": + """Every embedded subagent must carry a unique, non-null `trajectory_id`. + + Embedded subagents are resolved by matching + `SubagentTrajectoryRef.trajectory_id` against + `Trajectory.trajectory_id`, so the identifier must be present and + unique within a parent's `subagent_trajectories` array. Note that + no such constraint is placed on `session_id` — siblings MAY share + a `session_id` (or omit it entirely to inherit the parent's) when + they represent the same logical agent run. + """ + if not self.subagent_trajectories: + return self + seen: set[str] = set() + for i, sub in enumerate(self.subagent_trajectories): + if sub.trajectory_id is None: + raise ValueError( + f"subagent_trajectories[{i}].trajectory_id is required " + f"for embedded subagents " + f"(agent.name={sub.agent.name!r}, " + f"session_id={sub.session_id!r})" + ) + if sub.trajectory_id in seen: + raise ValueError( + f"subagent_trajectories[{i}].trajectory_id " + f"{sub.trajectory_id!r} is not unique within " + f"subagent_trajectories" + ) + seen.add(sub.trajectory_id) + return self + + @model_validator(mode="after") + def validate_tool_call_references(self) -> "Trajectory": + """Validate that observation source_call_ids reference valid tool_call_ids.""" + for step in self.steps: + if step.observation is None: + continue + + # Collect all tool_call_ids from this step + tool_call_ids = set() + if step.tool_calls: + tool_call_ids = {tc.tool_call_id for tc in step.tool_calls} + + # Check that source_call_ids reference valid tool_call_ids + for result in step.observation.results: + if result.source_call_id is not None: + if result.source_call_id not in tool_call_ids: + raise ValueError( + f"Observation result references source_call_id " + f"'{result.source_call_id}' which is not found in " + f"step {step.step_id}'s tool_calls" + ) + return self + + def has_multimodal_content(self) -> bool: + """Check if any step contains multimodal content (images or audio). + + Returns: + True if any step message or observation contains a media content + part. Audio counts since ATIF-v1.8. + """ + media_types = {"image", "audio"} + for step in self.steps: + if isinstance(step.message, list): + for part in step.message: + if part.type in media_types: + return True + if step.observation: + for result in step.observation.results: + if isinstance(result.content, list): + for part in result.content: + if part.type in media_types: + return True + return False diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/profile.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/profile.py new file mode 100644 index 000000000..9b83e9a78 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/profile.py @@ -0,0 +1,167 @@ +"""agentenv's ATIF profile: what agentenv adds under ``extra.agentenv`` on the objects ATIF gives an ``extra``. Every +field is optional, for readers and producers, and a document with the profile removed is still correct ATIF that means +the same; PROFILE.md beside this module is the spec. The models are tolerant, so a reader keeps keys it doesn't know and +writes them back; strictness for producers belongs to the validator.""" +from __future__ import annotations + +from typing import Any, Mapping, TypeVar + +from pydantic import BaseModel, ConfigDict, ValidationError + +#: The format id an agent serves and the worker stores. +FORMAT = "atif/1" +#: The key under each ``extra`` that holds the profile. +PROFILE_KEY = "agentenv" +PROFILE_VERSION = "1.0" +#: The ATIF version producers write: the oldest that holds the fields they use. +SCHEMA_VERSION = "ATIF-v1.8" +#: The only key outside ``extra.agentenv`` a producer writes: Harbor's, on a ToolCall whose input wasn't an object. +RAW_ARGUMENTS = "raw_arguments" + +#: Vocabularies. A reader keeps a value it doesn't know. +TASK_STATES = ("completed", "failed", "canceled", "rejected") +RESULT_STATUSES = ("ok", "error", "canceled", "timeout") +ERROR_KINDS = ("agent_error", "infra_error") +VISIBILITIES = ("raw", "summary", "omitted", "redacted") +COST_SOURCES = ("harness", "provider") +VOCABULARIES = { + "StepProfile.state": TASK_STATES, + "ObservationResultProfile.status": RESULT_STATUSES, + "StepError.kind": ERROR_KINDS, + "ReasoningBlock.visibility": VISIBILITIES, + "MetricsProfile.cost_source": COST_SOURCES, + "FinalMetricsProfile.cost_source": COST_SOURCES, +} + + +class AtifError(ValueError): + """A document, profile or adapter that breaks ATIF or the profile.""" + + +class _Profile(BaseModel): + model_config = ConfigDict(extra="allow", protected_namespaces=()) + + +class AdapterRef(_Profile): + name: str | None = None + version: str | None = None + + +class MediaInfo(_Profile): + """A media file the parts beside it name by ``media/.``. ``media_type`` is written only for media ATIF + has no part type for, since an image or audio part carries its own.""" + + media_type: str | None = None + sha256: str | None = None + bytes: int | None = None + width: int | None = None + height: int | None = None + duration_ms: int | None = None + pages: int | None = None + name: str | None = None + + +class ReasoningBlock(_Profile): + """One reasoning block of a step, in native order. ``chars`` is its share of ``reasoning_content`` (0 when the + provider withheld the text); ``data`` holds a redacted block's ciphertext byte for byte.""" + + chars: int | None = None + visibility: str | None = None + signature: str | None = None + data: str | None = None + + +class StepError(_Profile): + kind: str | None = None + message: str | None = None + code: str | None = None + + +class Arrival(_Profile): + """When a result arrived after its call's step had closed: its time, and the step open when it came.""" + + at: str | None = None + step_id: int | None = None + + +class TrajectoryProfile(_Profile): + version: str | None = None + native_format: str | None = None + adapter: AdapterRef | None = None + unmatched: dict[str, int] | None = None + + +class AgentProfile(_Profile): + pass + + +class StepProfile(_Profile): + context_id: str | None = None + task_id: str | None = None + message_id: str | None = None + turn: int | None = None + state: str | None = None + attempt: int | None = None + error: StepError | None = None + reasoning: list[ReasoningBlock] | None = None + media: dict[str, MediaInfo] | None = None + + +class ToolCallProfile(_Profile): + pass + + +class ObservationResultProfile(_Profile): + status: str | None = None + exit_code: int | None = None + arrived: Arrival | None = None + media: dict[str, MediaInfo] | None = None + + +class MetricsProfile(_Profile): + cost_source: str | None = None + cache_write_tokens: int | None = None + + +class FinalMetricsProfile(_Profile): + cost_source: str | None = None + total_cache_write_tokens: int | None = None + + +class SubagentTrajectoryRefProfile(_Profile): + pass + + +#: The profile model for each ATIF object that has an ``extra``. +PROFILES: dict[str, type[_Profile]] = { + "Trajectory": TrajectoryProfile, + "Agent": AgentProfile, + "Step": StepProfile, + "ToolCall": ToolCallProfile, + "ObservationResult": ObservationResultProfile, + "Metrics": MetricsProfile, + "FinalMetrics": FinalMetricsProfile, + "SubagentTrajectoryRef": SubagentTrajectoryRefProfile, +} + +P = TypeVar("P", bound=_Profile) + + +def profile_of(obj: Mapping[str, Any] | None) -> dict[str, Any]: + """The raw ``extra.agentenv`` dict of an ATIF object as a dict, or an empty dict when it has none.""" + extra = (obj or {}).get("extra") + value = extra.get(PROFILE_KEY) if isinstance(extra, Mapping) else None + return dict(value) if isinstance(value, Mapping) else {} + + +def read_profile(obj: Mapping[str, Any] | None, model: type[P]) -> P: + """An ATIF object's profile as ``model``, unknown keys kept.""" + try: + return model.model_validate(profile_of(obj)) + except ValidationError as exc: + raise AtifError(f"extra.{PROFILE_KEY}: {exc}") from exc + + +def dump_profile(profile: _Profile) -> dict[str, Any]: + """A profile as JSON-ready data: what was set, unknown keys included, as it was read.""" + return profile.model_dump(mode="json", exclude_unset=True) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/reader.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/reader.py new file mode 100644 index 000000000..0e1f445f2 --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/reader.py @@ -0,0 +1,145 @@ +"""Reading ATIF documents, with or without ``extra.agentenv``: load and check one with the vendored models, slice it +into its A2A tasks, list the media it names, strip the profile, and tell whether a live page is a prefix of a later +read. Every helper accepts any valid ATIF document, such as a Harbor task's trajectory.json.""" +from __future__ import annotations + +import copy +import json +from dataclasses import dataclass, field +from pathlib import Path +from typing import Any, Iterator, Mapping + +from pydantic import ValidationError + +from .models import Trajectory +from .profile import PROFILE_KEY, AtifError, profile_of + + +def _no_constant(name: str) -> Any: + raise AtifError(f"{name} isn't JSON") + + +def load(source: str | bytes | Path | Mapping[str, Any]) -> dict[str, Any]: + """A document from JSON text, a file or a parsed mapping, checked with the vendored ATIF models. JSON is read + strictly: UTF-8, and no NaN or infinity.""" + if isinstance(source, Path): + source = source.read_bytes() + if isinstance(source, (bytes, bytearray)): + try: + source = bytes(source).decode("utf-8") + except UnicodeDecodeError as exc: + raise AtifError(f"a document is UTF-8: {exc}") from exc + if isinstance(source, str): + try: + source = json.loads(source, parse_constant=_no_constant) + except json.JSONDecodeError as exc: + raise AtifError(f"a document isn't JSON: {exc}") from exc + if not isinstance(source, Mapping): + raise AtifError("a document is a JSON object") + document = copy.deepcopy(dict(source)) + check(document) + return document + + +def check(document: Mapping[str, Any]) -> Trajectory: + """The document as ATIF's own models read it, or AtifError naming what they refused.""" + try: + return Trajectory.model_validate(document) + except ValidationError as exc: + raise AtifError(f"not valid ATIF: {exc}") from exc + + +@dataclass(frozen=True) +class Task: + """One A2A task's steps: from its user step up to the next task's. The ids and turn come from the user step's + profile; without one, ``turn`` counts the tasks in order and the ids are None.""" + + turn: int + steps: list[dict[str, Any]] = field(default_factory=list) + task_id: str | None = None + context_id: str | None = None + message_id: str | None = None + + @property + def state(self) -> str | None: + """The task's terminal state, which the profile puts on its last step.""" + return profile_of(self.steps[-1]).get("state") if self.steps else None + + +def tasks(document: Mapping[str, Any]) -> list[Task]: + """The root trajectory's steps sliced into A2A tasks. A task starts at a user step: one carrying a task id in its + profile, or, in a document without the profile, any ``source: user`` step.""" + steps = list(document.get("steps") or []) + profiled = any(profile_of(s).get("task_id") for s in steps if s.get("source") == "user") + out: list[Task] = [] + for step in steps: + profile = profile_of(step) + starts = step.get("source") == "user" and (profile.get("task_id") is not None or not profiled) + if starts or not out: + turn = profile.get("turn") if isinstance(profile.get("turn"), int) else len(out) + out.append(Task(turn=turn, task_id=profile.get("task_id"), context_id=profile.get("context_id"), + message_id=profile.get("message_id"))) + out[-1].steps.append(step) + return out + + +def _trajectories(document: Mapping[str, Any]) -> Iterator[Mapping[str, Any]]: + yield document + for sub in document.get("subagent_trajectories") or []: + yield from _trajectories(sub) + + +def _parts(value: Any) -> list[Mapping[str, Any]]: + return [p for p in value if isinstance(p, Mapping)] if isinstance(value, list) else [] + + +def media_paths(document: Mapping[str, Any]) -> list[str]: + """Every media file the document names, once each, in the order they appear: image and audio parts' paths, and + the files the profile records for media ATIF has no part type for.""" + seen: dict[str, None] = {} + for trajectory in _trajectories(document): + for step in trajectory.get("steps") or []: + holders = [step] + list((step.get("observation") or {}).get("results") or []) + for holder in holders: + for part in _parts(holder.get("message") if holder is step else holder.get("content")): + path = (part.get("source") or {}).get("path") + if isinstance(path, str): + seen.setdefault(path) + for path in profile_of(holder).get("media") or {}: + seen.setdefault(path) + return list(seen) + + +def strip_profile(document: Mapping[str, Any]) -> dict[str, Any]: + """A copy without any ``extra.agentenv``; an ``extra`` left empty goes too. What remains is plain ATIF.""" + def walk(value: Any) -> Any: + if isinstance(value, Mapping): + out = {} + for key, item in value.items(): + if key == "extra" and isinstance(item, Mapping): + rest = {k: walk(v) for k, v in item.items() if k != PROFILE_KEY} + if rest: + out[key] = rest + continue + out[key] = walk(item) + return out + if isinstance(value, list): + return [walk(item) for item in value] + return value + return walk(document) + + +def is_prefix(page: Mapping[str, Any] | None, later: Mapping[str, Any] | None) -> bool: + """Whether a live page's steps are the first steps of a later read, trajectory by trajectory. Nothing served is a + prefix of anything.""" + if page is None: + return True + if later is None: + return False + if list(later.get("steps") or [])[:len(page.get("steps") or [])] != list(page.get("steps") or []): + return False + subs = {sub.get("trajectory_id"): sub for sub in later.get("subagent_trajectories") or []} + for sub in page.get("subagent_trajectories") or []: + if not is_prefix(sub, subs.get(sub.get("trajectory_id"))): + return False + return True diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/runner.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/runner.py new file mode 100644 index 000000000..2443469bf --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/runner.py @@ -0,0 +1,126 @@ +"""Running an adapter: feed one A2A context's records through it, a task at a time. The runner writes each task's +user step and final response from what the SDK knows, and hands every handler the AtifTurn it writes through. The SDK +runs it live and the adapter kit replays it offline, so the same records, fed in the same order, build the same +document.""" +from __future__ import annotations + +from dataclasses import dataclass +from datetime import datetime +from typing import Any, Callable, Iterable, Sequence + +from .adapter import Adapter, AdapterSpec +from .builder import AtifTurn, Document, Media, TurnContext +from .profile import AtifError + + +@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 RecordedTask: + """A stored task: its context, its records in the order they were fed, and how it ended.""" + + context: TurnContext + records: Sequence[Fed] = () + state: str = "completed" + final: Sequence[Any] | None = None + ended_at: str | datetime | None = None + + +class AdapterRun: + """One A2A context's conversion. Each call returns the live view after it, the closed steps a reader may be + served; ``document`` is everything so far. Every read is a fresh copy. ``media`` receives each media file once, + as ``(path, bytes)``; the files are also kept in ``media_files``.""" + + def __init__(self, adapter: type[Adapter], *, media: Callable[[str, bytes], None] | None = None) -> None: + spec = vars(adapter).get("spec") + if not isinstance(spec, AdapterSpec): + raise AtifError(f"{adapter.__name__} isn't declared with @atif_adapter") + self._cls = adapter + self._spec = spec + self._doc = Document(spec, media) + self._adapter: Adapter | None = None + self._turn: AtifTurn | None = None + + @property + def media_files(self) -> dict[str, bytes]: + return dict(self._doc.media) + + def media(self, data: bytes, media_type: str, *, width: int | None = None, height: int | None = None, + duration_ms: int | None = None, pages: int | None = None, name: str | None = None) -> Media: + """Store media for a TurnContext's inbound content or a final response, as a handler's ``turn.media`` + does.""" + return self._doc.store(data, media_type, {"width": width, "height": height, "duration_ms": duration_ms, + "pages": pages, "name": name}) + + def document(self) -> dict[str, Any] | None: + return self._doc.document() + + def page(self) -> dict[str, Any] | None: + return self._doc.page() + + def start_task(self, context: TurnContext) -> dict[str, Any] | None: + """Open a task and write its user step. The context's first task creates the adapter.""" + if self._turn is not None: + raise AtifError(f"task {self._turn.context.task_id} is still open") + turn = self._doc.start_task(context) + self._turn = turn + if self._adapter is None: + self._adapter = self._cls(turn) + return self.page() + + def native(self, record: Any) -> dict[str, Any] | None: + """Feed the task's next native record.""" + turn = self._open() + method = self._spec.handler(None, record) or "unmatched" + getattr(self._adapter, method)(record, turn) + return self.page() + + def aux(self, name: str, record: Any) -> dict[str, Any] | None: + """Feed the task's next record of aux file ``name``.""" + turn = self._open() + if name not in self._spec.aux: + raise AtifError(f"{self._cls.__name__} declares no aux file {name!r}") + method = self._spec.handler(name, record) + if method is not None: + getattr(self._adapter, method)(record, turn) + return self.page() + + def end_task(self, *, state: str = "completed", final: Sequence[Any] | None = None, + ended_at: str | datetime | None = None) -> dict[str, Any] | None: + """Close the task: run the adapter's ``@finish``, then write the final response, once, and the task's + terminal state on its last step. The task is closed even when ``@finish`` raises, and the error is raised + after.""" + turn = self._open() + try: + if self._spec.finish is not None: + getattr(self._adapter, self._spec.finish)(turn) + finally: + self._doc.end_task(state=state, final=final, ended_at=ended_at) + self._turn = None + return self.page() + + def _open(self) -> AtifTurn: + if self._turn is None: + raise AtifError("no task is open: call start_task first") + return self._turn + + +def replay(adapter: type[Adapter], tasks: Iterable[RecordedTask], *, + media: Callable[[str, bytes], None] | None = None) -> dict[str, Any] | None: + """A context's stored tasks run through ``adapter`` again, as the agent ran them live: the whole document.""" + run = AdapterRun(adapter, media=media) + for task in tasks: + run.start_task(task.context) + for fed in task.records: + if fed.aux is None: + run.native(fed.record) + else: + run.aux(fed.aux, fed.record) + run.end_task(state=task.state, final=task.final, ended_at=task.ended_at) + return run.document() diff --git a/packages/agentenv-protocol/tests/atif_cases.py b/packages/agentenv-protocol/tests/atif_cases.py new file mode 100644 index 000000000..152ac3bad --- /dev/null +++ b/packages/agentenv-protocol/tests/atif_cases.py @@ -0,0 +1,261 @@ +"""The seven canonical cases, built through the adapter framework from native-shaped records of a toy format, so the +checked-in fixtures are what a real adapter would write. ``python tests/atif_cases.py`` rewrites the fixtures; a test +checks they still match.""" +from __future__ import annotations + +import json +import sys +from dataclasses import dataclass, field +from pathlib import Path +from typing import Any + +from agentenv_protocol.atif import Adapter, AdapterRun, TurnContext, atif_adapter, finish, native, strip_profile + +FIXTURES = Path(__file__).resolve().parents[1] / "src/agentenv_protocol/atif/fixtures" +CONTEXT = "ctx-7f3a" + + +@atif_adapter(native_format="toy-events/1", version="0.1.0", usage_input_includes_cache=False, + tested_with=("toy 1.0",)) +class Toy(Adapter): + """A toy CLI whose records map one to one onto builder calls.""" + + def __init__(self, turn: Any) -> None: + self.tasks = 0 + + @native(type="say") + def say(self, r: dict, turn: Any) -> None: + turn.message(step=r["step"], text=r["text"], time=r.get("at"), agent=r.get("agent")) + + @native(type="think") + def think(self, r: dict, turn: Any) -> None: + turn.reasoning(step=r["step"], text=r.get("text"), visibility=r.get("visibility", "raw"), + signature=r.get("signature"), data=r.get("data"), time=r.get("at")) + + @native(type="call") + def call(self, r: dict, turn: Any) -> None: + turn.tool_call(step=r["step"], tool_call_id=r["id"], function_name=r["name"], arguments=r.get("args"), + time=r.get("at"), agent=r.get("agent")) + + @native(type="result") + def result(self, r: dict, turn: Any) -> None: + content = None + if "png" in r: + content = [turn.media(r["png"].encode(), "image/png", width=1280, height=800)] + turn.tool_result(source_call_id=r["id"], text=r.get("out") if content is None else None, content=content, + status=r.get("status", "ok"), exit_code=r.get("exit"), time=r.get("at")) + + @native(type="usage") + def usage(self, r: dict, turn: Any) -> None: + turn.step(key=r["step"], model_name=r.get("model", "claude-opus-5-5"), input_tokens=r.get("in"), + cache_read_tokens=r.get("read"), cache_write_tokens=r.get("write"), output_tokens=r.get("out"), + cost_usd=r.get("cost"), cost_source=r.get("cost_source"), reasoning_effort=r.get("effort"), + time=r.get("at"), agent=r.get("agent")) + + @native(type="dispatch") + def dispatch(self, r: dict, turn: Any) -> None: + turn.message(step=r["step"], text=r["text"]) + turn.step(key=r["step"], llm_call_count=0) + + @native(type="spawn") + def spawn(self, r: dict, turn: Any) -> None: + turn.subagent(r["agent"], spawned_by=r["id"], name=r["name"], model_name=r.get("model")) + + @native(type="error") + def error(self, r: dict, turn: Any) -> None: + turn.error(message=r["message"], kind=r.get("kind", "agent_error"), code=r.get("code"), step=r.get("step")) + + @native(type="retry") + def retry(self, r: dict, turn: Any) -> None: + turn.attempt(r["n"]) + + @native(type="total") + def total(self, r: dict, turn: Any) -> None: + turn.task_cost(r["cost"], source="harness") + + @finish + def close(self, turn: Any) -> None: + self.tasks += 1 + + +@dataclass +class Task: + context: dict[str, Any] + records: list[dict[str, Any]] + final: list[Any] | None = None + state: str = "completed" + ended_at: str | None = None + inbound_media: list[tuple[str, str, dict[str, Any]]] = field(default_factory=list) + + +def _ctx(index: int, task_id: str, message_id: str, started: str, context: str = CONTEXT, **kw: Any) -> dict[str, Any]: + return {"index": index, "context_id": context, "task_id": task_id, "message_id": message_id, + "agent_name": "toy", "agent_version": "1.0", "agent_model": "claude-opus-5-5", "started_at": started, **kw} + + +def _u(step: str, inp: int, read: int, write: int, out: int, **kw: Any) -> dict[str, Any]: + return {"type": "usage", "step": step, "in": inp, "read": read, "write": write, "out": out, **kw} + + +LONG_READ = "".join(f"2026-01-{d:02d}T03:04:05Z -> 2026-01-{d:02d} 03:04:05+00:00\n" for d in range(1, 29)) + +CASES: dict[str, list[Task]] = { + "coding": [Task( + _ctx(0, "task-91c2", "msg-a1", "2026-11-04T17:02:11.204Z", + inbound=["tests/test_parse.py::test_utc fails. Fix parse_date without changing the test."]), + [{"type": "think", "step": "msg_01A", "text": "Run the failing test first to see the error.", + "signature": "EqQBCkgIBhABGAIiQKm3"}, + {"type": "call", "step": "msg_01A", "id": "toolu_01", "name": "Bash", "args": {"command": "pytest tests/test_parse.py -q"}}, + _u("msg_01A", 140, 16890, 1402, 212), + {"type": "result", "id": "toolu_01", "status": "error", "exit": 1, "at": "2026-11-04T17:02:19.877Z", + "out": "FAILED tests/test_parse.py::test_utc - ValueError: Invalid isoformat string: '2026-01-02T03:04:05Z'"}, + {"type": "call", "step": "msg_01B", "id": "toolu_02", "name": "Read", "args": {"file_path": "tests/fixtures/dates.txt"}}, + _u("msg_01B", 140, 18292, 469, 96), + {"type": "result", "id": "toolu_02", "out": LONG_READ, "at": "2026-11-04T17:02:24.310Z"}, + {"type": "call", "step": "msg_01C", "id": "toolu_03", "name": "Edit", + "args": {"file_path": "src/parse.py", "old_string": "datetime.fromisoformat(s)", + "new_string": "datetime.fromisoformat(s.replace('Z', '+00:00'))"}}, + _u("msg_01C", 140, 18761, 12476, 188), + {"type": "result", "id": "toolu_03", "out": "The file src/parse.py has been updated.", "at": "2026-11-04T17:02:41.002Z"}, + {"type": "call", "step": "msg_01D", "id": "toolu_04", "name": "Bash", "args": {"command": "pytest tests/test_parse.py -q"}}, + _u("msg_01D", 140, 31237, 325, 74), + {"type": "result", "id": "toolu_04", "out": "3 passed in 0.18s", "at": "2026-11-04T17:02:55.419Z"}, + {"type": "say", "step": "msg_01E", "text": "parse_date now accepts a trailing Z; all 3 tests in tests/test_parse.py pass."}, + _u("msg_01E", 140, 31562, 188, 41), + {"type": "total", "cost": 0.2117}, + {"type": "system", "subtype": "hook_started"}], + final=["parse_date now accepts a trailing Z; all 3 tests in tests/test_parse.py pass."], + ended_at="2026-11-04T17:03:02.551Z")], + "computer_use": [Task( + _ctx(0, "task-c1", "msg-c1", "2026-11-04T19:10:01.020Z", + inbound=["In the open spreadsheet, set B2 to 42 and save the file."]), + [{"type": "call", "step": "msg_c1", "id": "toolu_c1", "name": "computer", "args": {"action": "screenshot"}}, + _u("msg_c1", 66, 5120, 1024, 58), + {"type": "result", "id": "toolu_c1", "png": "screenshot-1", "at": "2026-11-04T19:10:04.118Z"}, + {"type": "think", "step": "msg_c2", "visibility": "omitted", "signature": "EpwBCkYIBRgCIkB2"}, + {"type": "call", "step": "msg_c2", "id": "toolu_c2", "name": "computer", + "args": {"action": "left_click", "coordinate": [212, 318]}}, + _u("msg_c2", 0, 6144, 1658, 121), + {"type": "result", "id": "toolu_c2", "png": "screenshot-2", "at": "2026-11-04T19:10:07.412Z"}, + {"type": "call", "step": "msg_c3", "id": "toolu_c3", "name": "computer", "args": {"action": "type", "text": "42"}}, + _u("msg_c3", 0, 7680, 2125, 47), + {"type": "result", "id": "toolu_c3", "png": "screenshot-3", "at": "2026-11-04T19:10:10.906Z"}, + {"type": "say", "step": "msg_c4", "text": "B2 is now 42 and the file is saved."}, + _u("msg_c4", 0, 10969, 1160, 23)], + final=["B2 is now 42 and the file is saved."], ended_at="2026-11-04T19:10:16.004Z")], + "late_result": [Task( + _ctx(0, "task-l1", "msg-l1", "2026-11-04T17:00:00.000Z", + inbound=["Run the slow suite and check src/app.py meanwhile."]), + [{"type": "call", "step": "msg_A", "id": "toolu_07", "name": "Task", + "args": {"description": "run the slow suite", "run_in_background": True}}, + _u("msg_A", 100, 800, 100, 50), + {"type": "call", "step": "msg_B", "id": "toolu_08", "name": "Read", "args": {"file_path": "src/app.py"}}, + _u("msg_B", 100, 900, 100, 40), + {"type": "result", "id": "toolu_08", "out": "def main(): ...", "at": "2026-11-04T17:08:31.220Z"}, + {"type": "result", "id": "toolu_07", "out": "312 passed", "at": "2026-11-04T17:09:12.004Z"}, + {"type": "say", "step": "msg_C", "text": "The suite passes and app.py looks fine."}, + _u("msg_C", 100, 1000, 100, 30)], + final=["The suite passes and app.py looks fine."], ended_at="2026-11-04T17:09:30.000Z")], + "multi_agent": [Task( + _ctx(1, "task-b2", "msg-b2", "2026-11-04T18:01:40.530Z", context="ctx-1", + inbound=["[Email from Priya Shah] Board review moved to 3:00pm today.", + "Ugh. Can you make sure my 1:1 with Sam doesn't clash?"]), + [{"type": "think", "step": "resp-1a", "text": "Board is now 3-4pm; the 1:1 is at 3pm. Move the 1:1 to 4pm.", + "signature": "ErUBCkYIBRgCKkAx", "at": "2026-11-04T18:01:46.902Z"}, + {"type": "call", "step": "resp-1a", "id": "toolu_9a", "name": "calendar_update_event", + "args": {"event_id": "evt_1on1_sam", "start": "2026-03-12T16:00:00-05:00", "end": "2026-03-12T16:30:00-05:00"}}, + _u("resp-1a", 9120, 0, 0, 144, at="2026-11-04T18:01:46.902Z"), + {"type": "result", "id": "toolu_9a", "out": "Updated evt_1on1_sam: 4:00pm-4:30pm", "at": "2026-11-04T18:01:47.611Z"}, + {"type": "say", "step": "resp-1b", "text": "Moved your 1:1 with Sam to 4:00pm, right after the board review."}, + _u("resp-1b", 9402, 0, 0, 31, at="2026-11-04T18:01:52.812Z")], + final=["Moved your 1:1 with Sam to 4:00pm, right after the board review."], + ended_at="2026-11-04T18:01:52.850Z")], + "odd_parts": [Task( + _ctx(0, "task-o1", "msg-o1", "2026-11-04T17:00:00.000Z", inbound=["Summarize the attached report and the clip."]), + [{"type": "think", "step": "msg_A", "visibility": "summary", "text": "Read the report first."}, + {"type": "think", "step": "msg_A", "visibility": "redacted", "data": "RVJyZWRhY3RlZA=="}, + {"type": "say", "step": "msg_A", "text": "Patching the summary file."}, + {"type": "call", "step": "msg_A", "id": "toolu_p1", "name": "apply_patch", "args": "*** Begin Patch\n*** End Patch"}, + {"type": "say", "step": "msg_A", "text": "Patch sent."}, + _u("msg_A", 1000, 800, 100, 50, effort="high"), + {"type": "result", "id": "toolu_p1", "status": "error", "exit": 2, "out": "patch failed: no such file"}, + {"type": "error", "message": "sandbox disk full", "kind": "infra_error", "step": "msg_A"}, + {"type": "rate_limit_event"}, + {"type": "retry", "n": 2}, + {"type": "dispatch", "step": "dispatch-1", "text": "Retrying after a 529."}, + {"type": "say", "step": "msg_B", "text": "Done: the summary is in SUMMARY.md."}, + _u("msg_B", 2000, 1500, 0, 40, cost=0.01, cost_source="provider")], + final=["Done: the summary is in SUMMARY.md.", {"type": "text", "text": "{\"files\": [\"SUMMARY.md\"]}"}], + ended_at="2026-11-04T17:09:30.000Z", + inbound_media=[("report", "application/pdf", {"pages": 12}), ("clip", "video/mp4", {"duration_ms": 31000}), + ("photo", "image/heic", {"width": 640, "height": 480})])], + "subagent": [Task( + _ctx(0, "task-s1", "msg-s1", "2026-11-04T17:00:00.000Z", inbound=["Find the config files."]), + [{"type": "call", "step": "msg_A", "id": "toolu_s1", "name": "Task", "args": {"description": "find config files"}}, + _u("msg_A", 100, 800, 100, 50), + {"type": "spawn", "id": "toolu_s1", "agent": "sub1", "name": "explore", "model": "claude-haiku-5-5"}, + {"type": "call", "step": "msg_S1", "id": "toolu_s2", "name": "Bash", "args": {"command": "ls config"}, "agent": "sub1"}, + _u("msg_S1", 50, 400, 50, 20, agent="sub1", model="claude-haiku-5-5"), + {"type": "result", "id": "toolu_s2", "out": "a.toml b.toml c.toml", "at": "2026-11-04T17:01:05.000Z"}, + {"type": "say", "step": "msg_S2", "text": "Found a.toml, b.toml and c.toml.", "agent": "sub1"}, + _u("msg_S2", 60, 450, 0, 15, agent="sub1", model="claude-haiku-5-5"), + {"type": "result", "id": "toolu_s1", "out": "Found a.toml, b.toml and c.toml.", "at": "2026-11-04T17:01:09.000Z"}, + {"type": "say", "step": "msg_B", "text": "There are three: a.toml, b.toml and c.toml."}, + _u("msg_B", 100, 900, 50, 30)], + final=["There are three: a.toml, b.toml and c.toml."], ended_at="2026-11-04T17:01:20.000Z")], +} +CASES["two_turns"] = CASES["coding"] + [Task( + _ctx(1, "task-91c3", "msg-a2", "2026-11-04T17:05:00.000Z", inbound=["Also cover a +05:30 offset."]), + [{"type": "call", "step": "msg_02A", "id": "toolu_05", "name": "Edit", + "args": {"file_path": "tests/test_parse.py", "old_string": "", "new_string": "def test_offset(): ..."}}, + _u("msg_02A", 140, 31700, 400, 90), + {"type": "result", "id": "toolu_05", "out": "The file tests/test_parse.py has been updated.", "at": "2026-11-04T17:05:02.000Z"}, + {"type": "say", "step": "msg_02B", "text": "Added test_offset."}, + _u("msg_02B", 140, 32100, 120, 12), + {"type": "total", "cost": 0.0441}], + final=["Added test_offset."], ended_at="2026-11-04T17:05:09.000Z")] + + +def build(name: str) -> tuple[dict[str, Any], list[dict[str, Any] | None], dict[str, bytes]]: + """A case's document, the live page after every call, and its media files.""" + run = AdapterRun(Toy) + pages: list[dict[str, Any] | None] = [] + for task in CASES[name]: + context = dict(task.context) + inbound = list(context.pop("inbound", [])) + inbound += [run.media(label.encode(), media_type, **info) for label, media_type, info in task.inbound_media] + if task.inbound_media and name == "odd_parts": + inbound.append({"type": "text", "text": json.dumps({"ticket": 4411, "priority": "high"})}) + pages.append(run.start_task(TurnContext(inbound=inbound, **context))) + for record in task.records: + pages.append(run.native(record)) + pages.append(run.end_task(state=task.state, final=task.final, ended_at=task.ended_at)) + document = run.document() + assert document is not None + return document, pages, run.media_files + + +def fixtures() -> dict[str, Any]: + """Every fixture file by name: each case's document, the coding case stripped of its profile, and the media.""" + out: dict[str, Any] = {} + media: dict[str, bytes] = {} + for name in CASES: + document, _, files = build(name) + out[f"{name}.json"] = document + media.update(files) + out["coding.stripped.json"] = strip_profile(out["coding.json"]) + for path, data in media.items(): + out[path] = data + return out + + +def _text(value: Any) -> bytes: + return value if isinstance(value, bytes) else (json.dumps(value, indent=1, ensure_ascii=False) + "\n").encode() + + +if __name__ == "__main__": + for rel, value in fixtures().items(): + path = FIXTURES / rel + path.parent.mkdir(parents=True, exist_ok=True) + path.write_bytes(_text(value)) + print(f"wrote {len(fixtures())} files to {FIXTURES}", file=sys.stderr) diff --git a/packages/agentenv-protocol/tests/test_atif_builder.py b/packages/agentenv-protocol/tests/test_atif_builder.py new file mode 100644 index 000000000..37d19b657 --- /dev/null +++ b/packages/agentenv-protocol/tests/test_atif_builder.py @@ -0,0 +1,344 @@ +"""The adapter framework and the step builder: declarations checked at import, records routed to the most specific +handler, each task's user step and final response written from its TurnContext, results in their call's step, usage +in ATIF's terms, and a live view that only ever grows.""" +import math + +import pytest + +from agentenv_protocol.atif import ( + Adapter, + AdapterRun, + AtifError, + Fed, + Native, + RecordedTask, + Step, + TurnContext, + atif_adapter, + check, + finish, + is_prefix, + native, + profile_of, + replay, + timestamp, +) + + +def adapter(includes_cache=False): + @atif_adapter(native_format="toy-events/1", version="0.1.0", usage_input_includes_cache=includes_cache) + class Toy(Adapter): + @native(type="say") + def say(self, r, turn): + turn.message(step=r["step"], text=r["text"]) + + @native(type="call") + def call(self, r, turn): + turn.tool_call(step=r["step"], tool_call_id=r["id"], function_name="Bash", arguments=r.get("args", {})) + + @native(type="result") + def result(self, r, turn): + turn.tool_result(source_call_id=r["id"], text=r.get("out", "done"), time=r.get("at")) + + @native(type="usage") + def usage(self, r, turn): + turn.step(key=r["step"], input_tokens=r.get("in"), cache_read_tokens=r.get("read"), + cache_write_tokens=r.get("write"), output_tokens=r.get("out")) + return Toy + + +CTX = TurnContext(index=0, context_id="ctx", task_id="t1", message_id="m1", inbound=["hello"], agent_name="toy", + agent_version="1.0", started_at="2026-11-18T10:00:00Z") + + +def run_task(records, *, final=None, state="completed", cls=None): + run = AdapterRun(cls or adapter()) + pages = [run.start_task(CTX)] + [run.native(r) for r in records] + pages.append(run.end_task(final=final, state=state, ended_at="2026-11-18T10:05:00Z")) + return run, pages + + +def test_the_user_step_comes_from_the_turn_context(): + run, _ = run_task([{"type": "say", "step": "s1", "text": "hi"}]) + user = run.document()["steps"][0] + assert user["source"] == "user" and user["message"] == "hello" and user["timestamp"] == "2026-11-18T10:00:00Z" + assert profile_of(user) == {"context_id": "ctx", "task_id": "t1", "message_id": "m1", "turn": 0} + assert run.document()["agent"] == {"name": "toy", "version": "1.0"} + + +def test_a_final_response_the_last_step_holds_is_written_once(): + run, _ = run_task([{"type": "say", "step": "s1", "text": "all done"}], final=["all done"]) + steps = run.document()["steps"] + assert len(steps) == 2 and profile_of(steps[-1])["state"] == "completed" + + +def test_a_final_response_the_last_step_lacks_gets_its_own_step_with_no_model_call(): + run, _ = run_task([{"type": "say", "step": "s1", "text": "working"}], final=["{\"ok\": true}"], state="failed") + last = run.document()["steps"][-1] + assert last["message"] == "{\"ok\": true}" and last["llm_call_count"] == 0 and "metrics" not in last + assert profile_of(last)["state"] == "failed" and last["timestamp"] == "2026-11-18T10:05:00Z" + check(run.document()) + + +def test_the_terminal_state_is_never_served_before_the_task_ends(): + run, pages = run_task([{"type": "say", "step": "s1", "text": "a"}, {"type": "say", "step": "s2", "text": "b"}]) + for page in pages[:-1]: + assert all("state" not in profile_of(s) for s in (page or {}).get("steps", [])) + assert profile_of(pages[-1]["steps"][-1])["state"] == "completed" + with pytest.raises(AtifError): + AdapterRun(adapter()).end_task() + + +def test_a_late_result_lands_in_its_calls_step_and_holds_back_the_steps_after_it(): + records = [{"type": "call", "step": "A", "id": "c1"}, {"type": "call", "step": "B", "id": "c2"}, + {"type": "result", "id": "c2"}, {"type": "say", "step": "C", "text": "waiting"}, + {"type": "result", "id": "c1", "out": "312 passed", "at": "2026-11-18T10:04:00.5Z"}, + {"type": "say", "step": "D", "text": "done"}] + run, pages = run_task(records) + served = [len(p["steps"]) if p else 0 for p in pages] + assert served == [0, 1, 1, 1, 1, 3, 4, 5] + step_a = run.document()["steps"][1] + assert [r["source_call_id"] for r in step_a["observation"]["results"]] == ["c1"] + assert profile_of(step_a["observation"]["results"][0]) == {"arrived": {"at": "2026-11-18T10:04:00.500Z", + "step_id": 4}} + assert all(is_prefix(p, run.document()) for p in pages) + + +def test_a_step_still_waiting_on_a_result_is_served_when_its_task_ends(): + run, pages = run_task([{"type": "call", "step": "A", "id": "c1"}, {"type": "say", "step": "B", "text": "x"}]) + assert [len(p["steps"]) if p else 0 for p in pages] == [0, 1, 1, 3] + assert "observation" not in pages[-1]["steps"][1] + check(pages[-1]) + + +@pytest.mark.parametrize("includes,expected", [(False, 95), (True, 10)]) +def test_usage_is_written_in_atifs_terms(includes, expected): + run, _ = run_task([{"type": "usage", "step": "s1", "in": 10, "read": 80, "write": 5, "out": 7}], + cls=adapter(includes)) + metrics = run.document()["steps"][1]["metrics"] + assert metrics["prompt_tokens"] == expected and metrics["cached_tokens"] == 80 + assert metrics["completion_tokens"] == 7 and metrics["extra"] == {"agentenv": {"cache_write_tokens": 5}} + with pytest.raises(AtifError): + run_task([{"type": "usage", "step": "s1", "in": 10}], cls=adapter(None)) + + +@pytest.mark.parametrize("value,expected", [ + ("2026-11-18T01:02:03.12345Z", "2026-11-18T01:02:03.123450Z"), + ("2026-11-18T01:02:03.123456789Z", "2026-11-18T01:02:03.123456Z"), + ("2026-11-18T01:02:03.1+05:30", "2026-11-17T19:32:03.100Z"), + ("2026-11-18T01:02:03.123Z", "2026-11-18T01:02:03.123Z"), + ("2026-11-18 01:02:03-0700", "2026-11-18T08:02:03Z"), +]) +def test_timestamps_are_normalized_to_what_atif_reads_everywhere(value, expected): + assert timestamp(value) == expected + Step.model_validate({"step_id": 1, "source": "user", "message": "", "timestamp": timestamp(value)}) + + +@pytest.mark.parametrize("value", ["2026-11-18T01:02:03", "yesterday", "2026-11-18T25:00:00Z", 1700000000]) +def test_a_time_without_a_zone_or_that_isnt_one_is_refused(value): + with pytest.raises(AtifError): + timestamp(value) + + +@pytest.mark.parametrize("arguments,typed", [ + ("*** Begin Patch", {"input": "*** Begin Patch"}), (None, {}), ([1, 2], {"value": [1, 2]}), (7, {"value": 7}), +]) +def test_arguments_that_arent_an_object_are_wrapped_as_harbor_wraps_them(arguments, typed): + run, _ = run_task([{"type": "call", "step": "s1", "id": "c1", "args": arguments}]) + call = run.document()["steps"][1]["tool_calls"][0] + assert call["arguments"] == typed and call["extra"] == {"raw_arguments": arguments} + run, _ = run_task([{"type": "call", "step": "s1", "id": "c1", "args": {"command": "ls"}}]) + assert "extra" not in run.document()["steps"][1]["tool_calls"][0] + + +def test_a_duplicate_call_id_and_a_result_for_no_call_are_refused(): + with pytest.raises(AtifError, match="already"): + run_task([{"type": "call", "step": "s1", "id": "c1"}, {"type": "call", "step": "s2", "id": "c1"}]) + with pytest.raises(AtifError, match="no call"): + run_task([{"type": "result", "id": "nope"}]) + + +def test_values_that_arent_json_are_refused_as_they_are_written(): + with pytest.raises(AtifError, match="JSON"): + run_task([{"type": "call", "step": "s1", "id": "c1", "args": {"x": math.nan}}]) + with pytest.raises(AtifError, match="JSON"): + run_task([{"type": "call", "step": "s1", "id": "c1", "args": {"x": object()}}]) + + +def test_reads_are_fresh_copies(): + run, _ = run_task([{"type": "say", "step": "s1", "text": "a"}]) + run.document()["steps"].clear() + run.page()["steps"][0]["message"] = "rewritten" + assert len(run.document()["steps"]) == 2 and run.page()["steps"][0]["message"] == "hello" + + +def test_reasoning_blocks_keep_their_boundaries_signatures_and_ciphertext(): + @atif_adapter(native_format="toy-think/1", version="1", usage_input_includes_cache=None) + class Thinker(Adapter): + @native(type="think") + def think(self, r, turn): + turn.reasoning(step="s1", text=r.get("text"), visibility=r["vis"], signature=r.get("sig"), + data=r.get("data")) + + run = AdapterRun(Thinker) + run.start_task(CTX) + for r in [{"vis": "raw", "text": "first", "sig": "S1"}, {"vis": "omitted", "sig": "S2"}, + {"vis": "redacted", "data": "Q0lQSEVS"}, {"vis": "summary", "text": "second"}]: + run.native({"type": "think", **r}) + run.end_task() + step = run.document()["steps"][1] + blocks = profile_of(step)["reasoning"] + assert step["reasoning_content"] == "first\n\nsecond" + assert [b["chars"] for b in blocks] == [5, 0, 0, 6] and blocks[2]["data"] == "Q0lQSEVS" + text, pieces = step["reasoning_content"], [] + for block in blocks: + pieces.append(text[:block["chars"]]) + text = text[block["chars"] + 2:] if block["chars"] else text + assert pieces == ["first", "", "", "second"] + + +def test_media_go_to_the_sink_once_and_types_atif_lacks_become_notes(): + @atif_adapter(native_format="toy-media/1", version="1", usage_input_includes_cache=None) + class Shots(Adapter): + @native(type="shot") + def shot(self, r, turn): + turn.tool_call(step=r["step"], tool_call_id=r["id"], function_name="computer", arguments={}) + turn.tool_result(source_call_id=r["id"], content=[turn.media(r["data"], r["mt"], width=2, height=1)]) + + sunk = [] + run = AdapterRun(Shots, media=lambda path, data: sunk.append(path)) + run.start_task(CTX) + for i, mt in enumerate(["image/png", "image/png", "video/mp4"]): + run.native({"type": "shot", "step": f"s{i}", "id": f"c{i}", "data": b"same" if i < 2 else b"clip", "mt": mt}) + run.end_task() + document = run.document() + check(document) + png, mp4 = (r["observation"]["results"][0] for r in document["steps"][1::2]) + path = png["content"][0]["source"]["path"] + assert path.startswith("media/") and path.endswith(".png") and len(sunk) == 2 + assert profile_of(png)["media"][path] == {"sha256": path[6:-4], "bytes": 4, "width": 2, "height": 1} + assert mp4["content"].startswith("[video: media/") and mp4["content"].endswith(", 4 B]") + assert list(profile_of(mp4)["media"].values())[0]["media_type"] == "video/mp4" + + +def test_records_no_method_takes_are_counted_by_type(): + run, _ = run_task([{"type": "system"}, {"type": "system"}, {"kind": "no type"}]) + assert profile_of(run.document())["unmatched"] == {"dict": 1, "system": 2} + + +def test_a_sub_agent_is_an_embedded_trajectory_its_spawning_result_points_at(): + @atif_adapter(native_format="toy-sub/1", version="1", usage_input_includes_cache=True) + class Parent(Adapter): + @native(type="go") + def go(self, r, turn): + turn.tool_call(step="p1", tool_call_id="task", function_name="Task", arguments={}) + turn.subagent("sub", spawned_by="task", name="explore", model_name="small") + turn.message(step="x1", text="looking", agent="sub") + turn.step(key="x1", input_tokens=5, output_tokens=1, agent="sub") + turn.step(key="p1", input_tokens=10, output_tokens=2) + turn.tool_result(source_call_id="task", text="found it") + + run = AdapterRun(Parent) + run.start_task(CTX) + run.native({"type": "go"}) + run.end_task() + document = run.document() + check(document) + sub = document["subagent_trajectories"][0] + assert sub["trajectory_id"] == "sub" and sub["agent"] == {"name": "explore", "version": "unknown", + "model_name": "small"} + result = document["steps"][1]["observation"]["results"][0] + assert result["subagent_trajectory_ref"] == [{"trajectory_id": "sub"}] + assert document["final_metrics"]["total_prompt_tokens"] == 15 and document["final_metrics"]["total_steps"] == 2 + + +def test_a_step_with_no_model_call_takes_no_usage(): + @atif_adapter(native_format="toy-dispatch/1", version="1", usage_input_includes_cache=True) + class Dispatch(Adapter): + @native(type="d") + def d(self, r, turn): + turn.step(key="s1", llm_call_count=0, input_tokens=3) + + with pytest.raises(AtifError): + run_task([{"type": "d"}], cls=Dispatch) + + +def test_finish_raising_still_closes_the_task(): + @atif_adapter(native_format="toy-fail/1", version="1", usage_input_includes_cache=None) + class Fails(Adapter): + @finish + def close(self, turn): + raise RuntimeError("boom") + + run = AdapterRun(Fails) + run.start_task(CTX) + with pytest.raises(RuntimeError): + run.end_task(state="failed") + assert profile_of(run.document()["steps"][-1])["state"] == "failed" + run.start_task(TurnContext(index=1, context_id="ctx", task_id="t2", inbound=["again"])) + + +def test_replaying_a_contexts_stored_tasks_builds_what_it_built_live(): + records = [{"type": "call", "step": "s1", "id": "c1"}, {"type": "usage", "step": "s1", "in": 1, "out": 1}, + {"type": "result", "id": "c1"}, {"type": "say", "step": "s2", "text": "ok"}] + live, _ = run_task(records, final=["ok"]) + stored = [RecordedTask(context=CTX, records=[Fed(r) for r in records], final=["ok"], + ended_at="2026-11-18T10:05:00Z")] + assert replay(adapter(), stored) == live.document() + + +def test_declarations_are_checked_at_import(): + with pytest.raises(AtifError): + atif_adapter(native_format="atif/1", version="1", usage_input_includes_cache=True) + with pytest.raises(AtifError): + atif_adapter(native_format="no-version", version="1", usage_input_includes_cache=True) + with pytest.raises(AtifError): + atif_adapter(native_format="toy/1", version="", usage_input_includes_cache=True) + with pytest.raises(AtifError): + atif_adapter(native_format="toy/1", version="1", usage_input_includes_cache="yes") + with pytest.raises(AtifError): + @atif_adapter(native_format="toy/1", version="1", usage_input_includes_cache=True) + class TwoFinishes(Adapter): + @finish + def a(self, turn): + pass + + @finish + def b(self, turn): + pass + with pytest.raises(AtifError): + AdapterRun(Adapter) + + +def test_the_most_specific_handler_takes_a_record_and_a_tie_is_refused(): + @atif_adapter(native_format="toy-pick/1", version="1", usage_input_includes_cache=None) + class Pick(Adapter): + @native(type="e") + def general(self, r, turn): + turn.message(step="g", text="general") + + @native(type="e", where={"kind": "retry"}) + def retry(self, r, turn): + turn.message(step="r", text="retry") + + run, _ = run_task([{"type": "e", "kind": "retry"}, {"type": "e", "kind": "other"}], cls=Pick) + assert [s["message"] for s in run.document()["steps"][1:]] == ["retry", "general"] + + @atif_adapter(native_format="toy-tie/1", version="1", usage_input_includes_cache=None) + class Tie(Adapter): + @native(where={"a": 1}) + def one(self, r, turn): + pass + + @native(where={"b": 1}) + def two(self, r, turn): + pass + + with pytest.raises(AtifError, match="equally"): + run_task([{"a": 1, "b": 1}], cls=Tie) + + +def test_from_atif_is_each_adapters_own(): + with pytest.raises(NotImplementedError): + adapter().from_atif({}) + assert Native(log=[{"type": "x"}]).session is None diff --git a/packages/agentenv-protocol/tests/test_atif_fixtures.py b/packages/agentenv-protocol/tests/test_atif_fixtures.py new file mode 100644 index 000000000..b1a812cd7 --- /dev/null +++ b/packages/agentenv-protocol/tests/test_atif_fixtures.py @@ -0,0 +1,46 @@ +"""The profile's canonical fixtures: rebuilt through the adapter framework, valid ATIF with or without the profile, +unchanged by Harbor's own load and save, and a prefix of themselves at every live page.""" +import json + +import pytest + +from agentenv_protocol.atif import Trajectory, check, is_prefix, strip_profile +from atif_cases import CASES, FIXTURES, _text, build, fixtures + + +def test_the_checked_in_fixtures_are_what_the_cases_build(): + built = fixtures() + shipped = {str(p.relative_to(FIXTURES)) for p in FIXTURES.rglob("*") if p.is_file()} + assert shipped == set(built), "rewrite them with: python packages/agentenv-protocol/tests/atif_cases.py" + for rel, value in built.items(): + assert (FIXTURES / rel).read_bytes() == _text(value), ( + f"{rel} is stale; rewrite with: python packages/agentenv-protocol/tests/atif_cases.py") + + +@pytest.mark.parametrize("name", sorted(CASES)) +def test_a_fixture_is_atif_with_and_without_its_profile_and_survives_harbors_save(name): + document = json.loads((FIXTURES / f"{name}.json").read_text(encoding="utf-8")) + check(document) + stripped = strip_profile(document) + check(stripped) + assert Trajectory.model_validate(document).to_json_dict() == document + assert Trajectory.model_validate(stripped).to_json_dict() == stripped + + +@pytest.mark.parametrize("name", sorted(CASES)) +def test_every_live_page_validates_and_is_a_prefix_of_the_final_document(name): + document, pages, _ = build(name) + for page in pages: + if page is not None: + check(page) + assert is_prefix(page, document) + assert pages[-1] == document + + +@pytest.mark.parametrize("name", sorted(CASES)) +def test_an_all_text_message_is_one_string_as_harbors_tools_read_it(name): + document = json.loads((FIXTURES / f"{name}.json").read_text(encoding="utf-8")) + for trajectory in [document, *document.get("subagent_trajectories", [])]: + for step in trajectory["steps"]: + message = step["message"] + assert isinstance(message, str) or any(p["type"] != "text" for p in message) diff --git a/packages/agentenv-protocol/tests/test_atif_profile.py b/packages/agentenv-protocol/tests/test_atif_profile.py new file mode 100644 index 000000000..be834ab3c --- /dev/null +++ b/packages/agentenv-protocol/tests/test_atif_profile.py @@ -0,0 +1,51 @@ +"""The extra.agentenv profile: every field optional, unknown keys kept, and PROFILE.md naming every field and value.""" +import json +from importlib.resources import files + +import pytest + +from agentenv_protocol.atif import ( + PROFILES, + VOCABULARIES, + AtifError, + StepProfile, + dump_profile, + load, + profile_of, + read_profile, +) +from agentenv_protocol.atif.profile import AdapterRef, Arrival, MediaInfo, ReasoningBlock, StepError + +SPEC = files("agentenv_protocol.atif").joinpath("PROFILE.md").read_text(encoding="utf-8") +NESTED = (AdapterRef, Arrival, MediaInfo, ReasoningBlock, StepError) + + +@pytest.mark.parametrize("model", [*PROFILES.values(), *NESTED]) +def test_every_profile_field_is_optional(model): + assert model() is not None + assert all(not f.is_required() for f in model.model_fields.values()) + + +def test_a_reader_keeps_an_unknown_profile_key(): + step = {"step_id": 1, "source": "user", "message": "x", + "extra": {"agentenv": {"turn": 0, "later_field": {"a": [1, None]}, "state": "paused"}}} + profile = read_profile(step, StepProfile) + assert profile.turn == 0 and profile.state == "paused" + assert dump_profile(profile) == step["extra"]["agentenv"] + document = {"agent": {"name": "a", "version": "1"}, "steps": [step], "extra": {"agentenv": {"later": True}}} + again = load(json.dumps(document)) + assert profile_of(again["steps"][0])["later_field"] == {"a": [1, None]} and profile_of(again) == {"later": True} + + +def test_a_profile_of_the_wrong_shape_is_refused(): + with pytest.raises(AtifError): + read_profile({"extra": {"agentenv": {"turn": "zero"}}}, StepProfile) + + +def test_profile_md_names_every_field_and_vocabulary_value(): + fields = {name for model in [*PROFILES.values(), *NESTED] for name in model.model_fields} + missing = sorted(name for name in fields if f"`{name}`" not in SPEC) + assert not missing, f"PROFILE.md doesn't name: {missing}" + for field, values in VOCABULARIES.items(): + assert f"`{field.split('.')[1]}`" in SPEC + assert all(f"`{value}`" in SPEC for value in values), field diff --git a/packages/agentenv-protocol/tests/test_atif_reader.py b/packages/agentenv-protocol/tests/test_atif_reader.py new file mode 100644 index 000000000..85e2e8c42 --- /dev/null +++ b/packages/agentenv-protocol/tests/test_atif_reader.py @@ -0,0 +1,62 @@ +"""Reading documents with or without the profile: strict loading, slicing into tasks, media paths, stripping the +profile, and telling a live page from a later read.""" +import json + +import pytest + +from agentenv_protocol.atif import AtifError, is_prefix, load, media_paths, strip_profile, tasks +from atif_cases import FIXTURES + + +def fixture(name): + return load(FIXTURES / f"{name}.json") + + +def test_loading_is_strict_json_checked_with_atifs_models(): + with pytest.raises(AtifError, match="JSON"): + load('{"agent": {"name": "a", "version": "1"}, "steps": [], "x": NaN}') + with pytest.raises(AtifError, match="UTF-8"): + load(b"\xff\xfe") + with pytest.raises(AtifError, match="ATIF"): + load({"agent": {"name": "a", "version": "1"}, "steps": []}) + assert load(json.dumps(fixture("coding")).encode())["session_id"] == "ctx-7f3a" + + +def test_a_document_slices_into_its_tasks_by_the_user_steps_profile_ids(): + sliced = tasks(fixture("two_turns")) + assert [(t.turn, t.task_id, len(t.steps), t.state) for t in sliced] == [ + (0, "task-91c2", 6, "completed"), (1, "task-91c3", 3, "completed")] + + +@pytest.mark.parametrize("name", ["coding", "two_turns", "multi_agent", "subagent"]) +def test_a_document_without_the_profile_slices_into_the_same_tasks(name): + with_profile = tasks(fixture(name)) + without = tasks(strip_profile(fixture(name))) + assert [strip_profile({"steps": t.steps}) for t in with_profile] == [{"steps": t.steps} for t in without] + assert [t.turn for t in without] == list(range(len(without))) and all(t.task_id is None for t in without) + + +def test_the_stripped_fixture_is_the_coding_fixture_without_its_profile(): + stripped = fixture("coding.stripped") + assert stripped == strip_profile(fixture("coding")) + assert "agentenv" not in json.dumps(stripped) + assert stripped["steps"][1]["tool_calls"][0]["function_name"] == "Bash" + + +def test_media_paths_lists_every_file_once_including_the_ones_atif_has_no_part_for(): + assert len(media_paths(fixture("computer_use"))) == 3 + odd = media_paths(fixture("odd_parts")) + assert {p.rsplit(".", 1)[1] for p in odd} == {"pdf", "mp4", "heic"} + assert media_paths(fixture("coding")) == [] + for name in ("computer_use", "odd_parts"): + assert all((FIXTURES / path).exists() for path in media_paths(fixture(name))) + + +def test_a_page_is_a_prefix_only_when_its_steps_lead_every_trajectory(): + final = fixture("subagent") + page = {**final, "steps": final["steps"][:2], + "subagent_trajectories": [{**final["subagent_trajectories"][0], + "steps": final["subagent_trajectories"][0]["steps"][:1]}]} + assert is_prefix(page, final) and is_prefix(None, final) + assert not is_prefix({**page, "steps": final["steps"][1:3]}, final) + assert not is_prefix(final, {**final, "subagent_trajectories": []}) diff --git a/packages/agentenv-protocol/tests/test_atif_vendored.py b/packages/agentenv-protocol/tests/test_atif_vendored.py new file mode 100644 index 000000000..08d54b8dc --- /dev/null +++ b/packages/agentenv-protocol/tests/test_atif_vendored.py @@ -0,0 +1,50 @@ +"""Harbor's ATIF models, vendored: the same code as Harbor 0.26.0's but for import paths, as strict as Harbor's, with its +license beside them, importable with only the protocol's base dependencies.""" +import hashlib +import re +import subprocess +import sys +from importlib.resources import files + +import pytest + +from agentenv_protocol.atif import AtifError, Step, Trajectory, check + +MODELS = files("agentenv_protocol.atif.models") +LOCAL_IMPORT = re.compile(r"^(\s*(?:from|import)\s+)agentenv_protocol\.atif\.models\b", re.M) + + +def recorded() -> dict[str, str]: + table = MODELS.joinpath("VENDORED.md").read_text(encoding="utf-8") + return dict(re.findall(r"^\| `([^`]+\.py)` \| `([0-9a-f]{64})` \|$", table, re.M)) + + +def test_the_vendored_files_differ_from_harbors_only_in_import_paths(): + shipped = {p.name for p in MODELS.iterdir() if p.name.endswith(".py")} + assert shipped == set(recorded()) and len(shipped) == 11 + for name, digest in recorded().items(): + text = MODELS.joinpath(name).read_text(encoding="utf-8") + assert "harbor" not in "".join(line for line in text.splitlines() if line.lstrip().startswith(("from", "import"))) + upstream = LOCAL_IMPORT.sub(r"\g<1>harbor.models.trajectories", text) + assert hashlib.sha256(upstream.encode("utf-8")).hexdigest() == digest, name + + +def test_harbors_license_ships_beside_them(): + assert "Apache License" in MODELS.joinpath("LICENSE").read_text(encoding="utf-8") + + +def test_atif_fields_stay_as_strict_as_harbors(): + with pytest.raises(ValueError): + Step.model_validate({"step_id": 1, "source": "user", "message": "x", "later_field": 1}) + with pytest.raises(AtifError): + check({"schema_version": "ATIF-v9.9", "agent": {"name": "a", "version": "1"}, + "steps": [{"step_id": 1, "source": "user", "message": "x"}]}) + assert Trajectory.model_validate({"agent": {"name": "a", "version": "1"}, + "steps": [{"step_id": 1, "source": "user", "message": "x"}]}) + + +def test_atif_imports_with_only_the_protocols_base_dependencies(): + probe = ("import sys\nimport agentenv_protocol.atif\n" + "assert not any(m == 'a2a' or m.startswith('a2a.') for m in sys.modules), 'a2a imported'\n" + "assert not any(m.startswith('agentenv_protocol.a2a_agent') for m in sys.modules), 'a2a_agent imported'\n") + subprocess.run([sys.executable, "-c", probe], check=True, capture_output=True, text=True) diff --git a/scripts/vendor_atif.py b/scripts/vendor_atif.py new file mode 100644 index 000000000..f2090a425 --- /dev/null +++ b/scripts/vendor_atif.py @@ -0,0 +1,115 @@ +"""Vendor Harbor's ATIF models into agentenv_protocol.atif.models from a named Harbor release on PyPI. Run from +anywhere, with network: + + python scripts/vendor_atif.py 0.26.0 [--check] + +It downloads that release's wheel, takes the modules under harbor/models/trajectories, rewrites their imports of +harbor.models.trajectories to agentenv_protocol.atif.models and changes nothing else, and writes them with VENDORED.md, +which records each upstream file's sha256 so a unit test can check offline that the copies differ from Harbor's only in +import paths. ``--check`` compares instead of writing and exits 1 on any difference.""" +from __future__ import annotations + +import argparse +import hashlib +import io +import json +import re +import sys +import urllib.request +import zipfile +from pathlib import Path + +UPSTREAM = "harbor.models.trajectories" +LOCAL = "agentenv_protocol.atif.models" +SOURCE = "harbor/models/trajectories/" +DEST = Path(__file__).resolve().parents[1] / "packages/agentenv-protocol/src/agentenv_protocol/atif/models" +_IMPORT = re.compile(r"^(\s*(?:from|import)\s+)" + re.escape(UPSTREAM) + r"\b", re.M) +_LOCAL_IMPORT = re.compile(r"^(\s*(?:from|import)\s+)" + re.escape(LOCAL) + r"\b", re.M) + + +def localize(text: str) -> str: + """Harbor's module text with its imports of the trajectory models pointed at the vendored copy.""" + return _IMPORT.sub(r"\g<1>" + LOCAL, text) + + +def upstream(text: str) -> str: + """A vendored module's text as Harbor wrote it: the inverse of ``localize``.""" + return _LOCAL_IMPORT.sub(r"\g<1>" + UPSTREAM, text) + + +def _get(url: str) -> bytes: + with urllib.request.urlopen(url, timeout=60) as response: + return response.read() + + +def fetch(version: str) -> tuple[str, str, dict[str, str], str]: + """The release's wheel name, its sha256, its trajectory modules' text by file name, and its license.""" + release = json.loads(_get(f"https://pypi.org/pypi/harbor/{version}/json")) + wheel = next(u for u in release["urls"] if u["packagetype"] == "bdist_wheel") + data = _get(wheel["url"]) + digest = hashlib.sha256(data).hexdigest() + if digest != wheel["digests"]["sha256"]: + raise SystemExit(f"{wheel['filename']}: sha256 {digest} isn't PyPI's {wheel['digests']['sha256']}") + with zipfile.ZipFile(io.BytesIO(data)) as archive: + files = {name[len(SOURCE):]: archive.read(name).decode("utf-8") for name in archive.namelist() + if name.startswith(SOURCE) and name.endswith(".py") and "/" not in name[len(SOURCE):]} + licenses = [name for name in archive.namelist() if name.endswith(".dist-info/licenses/LICENSE")] + if len(licenses) != 1: + raise SystemExit(f"{wheel['filename']} has no single dist-info/licenses/LICENSE") + license_text = archive.read(licenses[0]).decode("utf-8") + if not files: + raise SystemExit(f"{wheel['filename']} has no {SOURCE}*.py") + return wheel["filename"], digest, files, license_text + + +def vendored_md(version: str, wheel: str, digest: str, files: dict[str, str]) -> str: + rows = "\n".join(f"| `{name}` | `{hashlib.sha256(text.encode('utf-8')).hexdigest()}` |" + for name, text in sorted(files.items())) + return f"""# Vendored ATIF models + +These files are Harbor's ATIF models, from `{SOURCE}` in the Harbor {version} release on PyPI (`{wheel}`, sha256 +`{digest}`). Harbor is Apache-2.0; `LICENSE` beside this file is the license that wheel ships. + +The only change is import paths: each `from {UPSTREAM}...` import reads `from {LOCAL}...`. Nothing else differs. A unit +test turns the imports back and checks each file's sha256 against the table below. + +Refresh with `python scripts/vendor_atif.py ` from the repository root, then review the diff and the fixtures. + +| File | Upstream sha256 | +| --- | --- | +{rows} +""" + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0]) + parser.add_argument("version", help="the Harbor release, such as 0.26.0") + parser.add_argument("--check", action="store_true", help="compare with the checked-in copy instead of writing") + args = parser.parse_args() + wheel, digest, files, license_text = fetch(args.version) + wanted = {name: localize(text) for name, text in files.items()} + wanted["VENDORED.md"] = vendored_md(args.version, wheel, digest, files) + wanted["LICENSE"] = license_text + if args.check: + present = {p.name for p in DEST.glob("*.py")} | {n for n in ("VENDORED.md", "LICENSE") if (DEST / n).exists()} + differ = sorted(name for name, text in wanted.items() + if not (DEST / name).exists() or (DEST / name).read_text(encoding="utf-8") != text) + extra = sorted(present - set(wanted)) + for name in differ: + print(f"differs: {name}") + for name in extra: + print(f"not in {args.version}: {name}") + print(f"{len(files)} modules from {wheel}: {'match' if not differ and not extra else 'mismatch'}") + return 1 if differ or extra else 0 + DEST.mkdir(parents=True, exist_ok=True) + for stale in DEST.glob("*.py"): + if stale.name not in wanted: + stale.unlink() + for name, text in wanted.items(): + (DEST / name).write_text(text, encoding="utf-8") + print(f"wrote {len(files)} modules from {wheel} to {DEST}") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) From c8f6738b64c940417e3e9fdeee4ad69b1cc38870 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 09:51:16 -0800 Subject: [PATCH 2/7] refactor(protocol): one name for the includes-cache flag, and PROFILE.md names readers, not tickets - @atif_adapter's usage_input_includes_cache is now input_includes_cache, the name the protocol's Usage gets for its per-turn flag, so the adapter's constant and each turn's flag share one spelling. - PROFILE.md's cost rule says what `provider` covers (the endpoint's billed figure, the provider's or a proxy's) and that a cost agentenv prices itself is recorded with the run's usage as `priced`, never in a typed field. - PROFILE.md names each field's readers by what they are, without issue ids. Co-Authored-By: Claude Opus 5.5 --- packages/agentenv-protocol/README.md | 2 +- .../src/agentenv_protocol/atif/PROFILE.md | 50 ++++++++++--------- .../src/agentenv_protocol/atif/adapter.py | 12 ++--- .../src/agentenv_protocol/atif/builder.py | 6 +-- .../agentenv-protocol/tests/atif_cases.py | 2 +- .../tests/test_atif_builder.py | 26 +++++----- 6 files changed, 50 insertions(+), 48 deletions(-) diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index cb6d54056..289227b60 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1269,7 +1269,7 @@ the profile's spec, and `fixtures/` holds its canonical examples. The package ne ```python from agentenv_protocol.atif import Adapter, atif_adapter, native - @atif_adapter(native_format="my-cli-events/1", version="0.1.0", usage_input_includes_cache=False) + @atif_adapter(native_format="my-cli-events/1", version="0.1.0", input_includes_cache=False) class MyCliAtif(Adapter): @native(type="assistant") def assistant(self, record, turn): diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md b/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md index 7c4baa2b5..520e8f6a2 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md @@ -52,7 +52,7 @@ to native exactly. - Timestamps are UTC, written `YYYY-MM-DDTHH:MM:SS(.fff|.ffffff)Z`. Other precisions are normalized: ATIF's Step validator on Python 3.10 reads no other. - Usage follows ATIF: `prompt_tokens` includes cache reads and writes, and `cached_tokens` is the cache reads. Each - adapter's `usage_input_includes_cache` constant says whether its native input count already includes the cache. + adapter's `input_includes_cache` constant says whether its native input count already includes the cache. Cache writes go in `Metrics.extra.agentenv.cache_write_tokens`. - A tool call whose input isn't a JSON object is wrapped as Harbor wraps it: a string as `{"input": ...}`, a missing input as `{}`, any other value as `{"value": ...}`. The native input is kept in `ToolCall.extra.raw_arguments`, only @@ -64,10 +64,12 @@ to native exactly. ATIF defines a step's `cost_usd` as the cost "based on current provider pricing for this step", and says the cost fields "store the calculated cost at the time of execution". -- A cost the harness calculated from its own price table, or a billed amount the provider's API reported, goes in - `Metrics.cost_usd` or `FinalMetrics.total_cost_usd`. Its `cost_source` in the profile says which: `harness` or - `provider`. -- A cost agentenv computes itself, from its own price table after the run, never goes in a typed field. +- A cost the harness calculated from its own price table, or the endpoint's billed figure (the provider's, or a + proxy's such as LiteLLM's `x-litellm-response-cost`), goes in `Metrics.cost_usd` or `FinalMetrics.total_cost_usd`. + Its `cost_source` in the profile says which: `harness` or `provider`. These are the framework's reported costs. +- A cost agentenv computes itself, from its own price table after the run, never goes in a typed field. The framework + records that one with the run's usage instead, as a `priced` cost whose `cost_source` names the price table's + version; `harness` and `provider` mean the same there as here. - When nothing reports a cost, the typed fields stay empty, which ATIF readers read as unknown. ## Errors @@ -93,23 +95,23 @@ One vocabulary, in three places: | Object | Field | Meaning | Read by | | --- | --- | --- | --- | | Trajectory | `version` | The profile version: `1.0` | every reader | -| Trajectory | `native_format` | The native format id the copy was built from | Y4, Y11 | -| Trajectory | `adapter` | The adapter's `name` and `version` | Y4, Y11 | -| Trajectory | `unmatched` | Native records no method took, counted by type | Y1b's adapter kit | -| Step | `context_id`, `task_id`, `message_id`, `turn` | On a task's user step: its A2A ids and turn index | Y2b, Y4, Hub F3 | -| Step | `state` | On a task's last step: its terminal state | Y7, Hub F3 | -| Step | `attempt` | The harness attempt the step belongs to; absent means 1 | Y7 | -| Step | `error` | A step-level error: `kind`, `message`, `code` | Y7 | -| Step | `reasoning` | Each reasoning block: `chars`, `visibility`, `signature`, `data` | Y5 resume, Y10 RL replay | -| Step | `media` | Details of the media the message names, by path | Y3, Y7 | -| ObservationResult | `status` | The result's status; absent means `ok` | Y7 | -| ObservationResult | `exit_code` | The command's exit code | Y7 | -| ObservationResult | `arrived` | A late result's arrival: `at`, and the `step_id` open when it came | live readers, Y7 | -| ObservationResult | `media` | Details of the media the result names, by path | Y3, Y7 | -| Metrics | `cost_source` | Where `cost_usd` came from | E13 | -| Metrics | `cache_write_tokens` | Cache writes, beside ATIF's `cached_tokens` | E13 | -| FinalMetrics | `cost_source` | Where `total_cost_usd` came from | E13 | -| FinalMetrics | `total_cache_write_tokens` | Cache writes summed over the steps | E13 | +| Trajectory | `native_format` | The native format id the copy was built from | the worker that stores copies; renormalizing | +| Trajectory | `adapter` | The adapter's `name` and `version` | the worker that stores copies; renormalizing | +| Trajectory | `unmatched` | Native records no method took, counted by type | the adapter kit | +| Step | `context_id`, `task_id`, `message_id`, `turn` | On a task's user step: its A2A ids and turn index | the SDK, the worker, the hub's turns view | +| Step | `state` | On a task's last step: its terminal state | the explorer, the hub's turns view | +| Step | `attempt` | The harness attempt the step belongs to; absent means 1 | the explorer | +| Step | `error` | A step-level error: `kind`, `message`, `code` | the explorer | +| Step | `reasoning` | Each reasoning block: `chars`, `visibility`, `signature`, `data` | resuming a session; RL replay | +| Step | `media` | Details of the media the message names, by path | media transfer; the explorer | +| ObservationResult | `status` | The result's status; absent means `ok` | the explorer, judges' turn events | +| ObservationResult | `exit_code` | The command's exit code | the explorer, judges' turn events | +| ObservationResult | `arrived` | A late result's arrival: `at`, and the `step_id` open when it came | live readers, the explorer | +| ObservationResult | `media` | Details of the media the result names, by path | media transfer; the explorer | +| Metrics | `cost_source` | Where `cost_usd` came from | the run's usage and cost result | +| Metrics | `cache_write_tokens` | Cache writes, beside ATIF's `cached_tokens` | the run's usage and cost result | +| FinalMetrics | `cost_source` | Where `total_cost_usd` came from | the run's usage and cost result | +| FinalMetrics | `total_cache_write_tokens` | Cache writes summed over the steps | the run's usage and cost result | A media entry (MediaInfo) holds `sha256`, `bytes`, and, where they apply, `width`, `height`, `duration_ms`, `pages` and `name`, plus `media_type` for media ATIF has no part type for. A reasoning block (ReasoningBlock) holds `chars`, @@ -134,8 +136,8 @@ A reader keeps a value it doesn't know. A minor version only adds optional fields and vocabulary values, each with the reader or producer that needs it. A field added in a later minor names the version it arrived in. Proposed for a later minor, with their first producer: -`usage_input_includes_cache` on the root and `cost_status` (with F12's cross-check), per-part origins (when a reader -needs them), and the always-on harness's five fields (FD-5840). +`input_includes_cache` on the root and `cost_status` (`reported`, `priced` or `unpriced`), with the usage +cross-check that reads them; per-part origins, when a reader needs them; and an always-on harness's fields. ## Fixtures diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/adapter.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/adapter.py index 23ebbaff9..3e5b7d8a2 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/adapter.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/adapter.py @@ -92,7 +92,7 @@ class AdapterSpec: name: str native_format: str version: str - usage_input_includes_cache: bool | None + input_includes_cache: bool | None tested_with: tuple[str, ...] aux: Mapping[str, str] handlers: tuple[tuple[Selector, str], ...] @@ -111,11 +111,11 @@ def handler(self, aux_name: str | None, record: Any) -> str | None: return methods[0] -def atif_adapter(*, native_format: str, version: str, usage_input_includes_cache: bool | None, +def atif_adapter(*, native_format: str, version: str, input_includes_cache: bool | None, tested_with: Sequence[str] = (), name: 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 + ``input_includes_cache`` says whether the native input token count already includes cache reads and writes (None when the native reports no usage); the builder uses it to write ATIF's ``prompt_tokens``, which include them. ``tested_with`` names the native producer versions its recorded fixtures come from.""" if not isinstance(native_format, str) or not NATIVE_FORMAT.match(native_format): @@ -124,8 +124,8 @@ def atif_adapter(*, native_format: str, version: str, usage_input_includes_cache raise AtifError(f"native_format {native_format!r}: atif is the format adapters produce, not a native one") if not isinstance(version, str) or not version: raise AtifError("version is the adapter's own version string") - if usage_input_includes_cache not in (True, False, None): - raise AtifError("usage_input_includes_cache is true, false or None") + if input_includes_cache not in (True, False, None): + raise AtifError("input_includes_cache is true, false or None") def declare(cls: type[A]) -> type[A]: if not (isinstance(cls, type) and issubclass(cls, Adapter)): @@ -152,7 +152,7 @@ def declare(cls: type[A]) -> type[A]: raise AtifError(f"{cls.__name__} has more than one @finish method: {', '.join(finishes)}") cls.spec = AdapterSpec( name=name or f"{native_format.split('/', 1)[0]}-atif", native_format=native_format, version=version, - usage_input_includes_cache=usage_input_includes_cache, tested_with=tuple(tested_with), + input_includes_cache=input_includes_cache, tested_with=tuple(tested_with), aux=dict(aux_types), handlers=tuple((selector, attr) for selector, attr in owners.items()), finish=finishes[0] if finishes else None) return cls diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py index 172419d76..2e90cd6c1 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py @@ -585,7 +585,7 @@ def step(self, *, key: str, model_name: str | None = None, llm_call_count: int | time: str | datetime | None = None, is_copied_context: bool | None = None, agent: str | None = None) -> None: """What one model response cost and produced. Token counts are the native's; ATIF's ``prompt_tokens`` - includes cache reads and writes, so the adapter's ``usage_input_includes_cache`` decides the sum. A cost is + includes cache reads and writes, so the adapter's ``input_includes_cache`` decides the sum. A cost is the harness's or the provider's (``cost_source``), never one agentenv computed.""" target = self._doc.step_for(key, agent) if model_name is not None: @@ -603,9 +603,9 @@ def step(self, *, key: str, model_name: str | None = None, llm_call_count: int | if value is not None and (not isinstance(value, int) or isinstance(value, bool) or value < 0): raise AtifError(f"token counts are non-negative integers, not {value!r}") if input_tokens is not None or cache_read_tokens is not None or cache_write_tokens is not None: - includes = self.spec.usage_input_includes_cache + includes = self.spec.input_includes_cache if includes is None: - raise AtifError("declare usage_input_includes_cache on @atif_adapter to write prompt tokens") + raise AtifError("declare input_includes_cache on @atif_adapter to write prompt tokens") prompt = (input_tokens or 0) + (0 if includes else (cache_read_tokens or 0) + (cache_write_tokens or 0)) target.metrics["prompt_tokens"] = prompt if cache_read_tokens is not None: diff --git a/packages/agentenv-protocol/tests/atif_cases.py b/packages/agentenv-protocol/tests/atif_cases.py index 152ac3bad..83a084487 100644 --- a/packages/agentenv-protocol/tests/atif_cases.py +++ b/packages/agentenv-protocol/tests/atif_cases.py @@ -15,7 +15,7 @@ CONTEXT = "ctx-7f3a" -@atif_adapter(native_format="toy-events/1", version="0.1.0", usage_input_includes_cache=False, +@atif_adapter(native_format="toy-events/1", version="0.1.0", input_includes_cache=False, tested_with=("toy 1.0",)) class Toy(Adapter): """A toy CLI whose records map one to one onto builder calls.""" diff --git a/packages/agentenv-protocol/tests/test_atif_builder.py b/packages/agentenv-protocol/tests/test_atif_builder.py index 37d19b657..7783ba6f0 100644 --- a/packages/agentenv-protocol/tests/test_atif_builder.py +++ b/packages/agentenv-protocol/tests/test_atif_builder.py @@ -26,7 +26,7 @@ def adapter(includes_cache=False): - @atif_adapter(native_format="toy-events/1", version="0.1.0", usage_input_includes_cache=includes_cache) + @atif_adapter(native_format="toy-events/1", version="0.1.0", input_includes_cache=includes_cache) class Toy(Adapter): @native(type="say") def say(self, r, turn): @@ -173,7 +173,7 @@ def test_reads_are_fresh_copies(): def test_reasoning_blocks_keep_their_boundaries_signatures_and_ciphertext(): - @atif_adapter(native_format="toy-think/1", version="1", usage_input_includes_cache=None) + @atif_adapter(native_format="toy-think/1", version="1", input_includes_cache=None) class Thinker(Adapter): @native(type="think") def think(self, r, turn): @@ -198,7 +198,7 @@ def think(self, r, turn): def test_media_go_to_the_sink_once_and_types_atif_lacks_become_notes(): - @atif_adapter(native_format="toy-media/1", version="1", usage_input_includes_cache=None) + @atif_adapter(native_format="toy-media/1", version="1", input_includes_cache=None) class Shots(Adapter): @native(type="shot") def shot(self, r, turn): @@ -227,7 +227,7 @@ def test_records_no_method_takes_are_counted_by_type(): def test_a_sub_agent_is_an_embedded_trajectory_its_spawning_result_points_at(): - @atif_adapter(native_format="toy-sub/1", version="1", usage_input_includes_cache=True) + @atif_adapter(native_format="toy-sub/1", version="1", input_includes_cache=True) class Parent(Adapter): @native(type="go") def go(self, r, turn): @@ -253,7 +253,7 @@ def go(self, r, turn): def test_a_step_with_no_model_call_takes_no_usage(): - @atif_adapter(native_format="toy-dispatch/1", version="1", usage_input_includes_cache=True) + @atif_adapter(native_format="toy-dispatch/1", version="1", input_includes_cache=True) class Dispatch(Adapter): @native(type="d") def d(self, r, turn): @@ -264,7 +264,7 @@ def d(self, r, turn): def test_finish_raising_still_closes_the_task(): - @atif_adapter(native_format="toy-fail/1", version="1", usage_input_includes_cache=None) + @atif_adapter(native_format="toy-fail/1", version="1", input_includes_cache=None) class Fails(Adapter): @finish def close(self, turn): @@ -289,15 +289,15 @@ def test_replaying_a_contexts_stored_tasks_builds_what_it_built_live(): def test_declarations_are_checked_at_import(): with pytest.raises(AtifError): - atif_adapter(native_format="atif/1", version="1", usage_input_includes_cache=True) + atif_adapter(native_format="atif/1", version="1", input_includes_cache=True) with pytest.raises(AtifError): - atif_adapter(native_format="no-version", version="1", usage_input_includes_cache=True) + atif_adapter(native_format="no-version", version="1", input_includes_cache=True) with pytest.raises(AtifError): - atif_adapter(native_format="toy/1", version="", usage_input_includes_cache=True) + atif_adapter(native_format="toy/1", version="", input_includes_cache=True) with pytest.raises(AtifError): - atif_adapter(native_format="toy/1", version="1", usage_input_includes_cache="yes") + atif_adapter(native_format="toy/1", version="1", input_includes_cache="yes") with pytest.raises(AtifError): - @atif_adapter(native_format="toy/1", version="1", usage_input_includes_cache=True) + @atif_adapter(native_format="toy/1", version="1", input_includes_cache=True) class TwoFinishes(Adapter): @finish def a(self, turn): @@ -311,7 +311,7 @@ def b(self, turn): def test_the_most_specific_handler_takes_a_record_and_a_tie_is_refused(): - @atif_adapter(native_format="toy-pick/1", version="1", usage_input_includes_cache=None) + @atif_adapter(native_format="toy-pick/1", version="1", input_includes_cache=None) class Pick(Adapter): @native(type="e") def general(self, r, turn): @@ -324,7 +324,7 @@ def retry(self, r, turn): run, _ = run_task([{"type": "e", "kind": "retry"}, {"type": "e", "kind": "other"}], cls=Pick) assert [s["message"] for s in run.document()["steps"][1:]] == ["retry", "general"] - @atif_adapter(native_format="toy-tie/1", version="1", usage_input_includes_cache=None) + @atif_adapter(native_format="toy-tie/1", version="1", input_includes_cache=None) class Tie(Adapter): @native(where={"a": 1}) def one(self, r, turn): From c479d4e0c3328d73ab483b6b596d3b7c6d439da7 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 09:59:43 -0800 Subject: [PATCH 3/7] fix(protocol): the ATIF builder refuses what would change a served step or break the document, before changing anything Found by a chaos run that fuzzes every builder argument: - A call takes one result, and none once its task has ended: either would have changed a step a live reader was already served. - Every argument's type is checked where it is written (ids, names, counts, costs, media details, agent, content), so a wrong one is refused instead of writing a document ATIF or the profile can't read. - Values are checked before any step is chosen, so a refused call leaves the document as it was; a refused start_task no longer leaves a task half open. - A time that overflows when moved to UTC is refused, and years before 1000 keep four digits on every platform. - A step with no model call takes no reasoning, and no usage once it has some. Co-Authored-By: Claude Opus 5.5 --- .../src/agentenv_protocol/atif/builder.py | 224 +++++++++++++----- .../tests/test_atif_builder.py | 96 ++++++++ 2 files changed, 256 insertions(+), 64 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py index 2e90cd6c1..35bdc8abf 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py @@ -6,6 +6,7 @@ import hashlib import json +import math import mimetypes import re from collections import Counter @@ -53,25 +54,58 @@ def timestamp(value: str | datetime | None) -> str | None: if isinstance(value, datetime): if value.tzinfo is None: raise AtifError(f"{value!r} has no time zone") - moment = value.astimezone(timezone.utc) - fraction = f".{moment.microsecond:06d}" if moment.microsecond else "" - return moment.strftime("%Y-%m-%dT%H:%M:%S") + fraction + "Z" - match = _TIME.match(value.strip()) if isinstance(value, str) else None - if not match: - raise AtifError(f"{value!r} isn't an RFC 3339 time with a zone") - date, hours, minutes, seconds, digits, zone = match.groups() - zone = "+00:00" if zone in ("Z", "z") else (zone if ":" in zone else f"{zone[:3]}:{zone[3:]}") - micro = int((digits + "000000")[:6]) if digits else 0 - try: - moment = datetime.fromisoformat(f"{date}T{hours}:{minutes}:{seconds}.{micro:06d}{zone}").astimezone(timezone.utc) - except ValueError as exc: - raise AtifError(f"{value!r}: {exc}") from exc - text = moment.strftime("%Y-%m-%dT%H:%M:%S") + moment, digits = _utc(value, value), "000000" if value.microsecond else "" + else: + match = _TIME.match(value.strip()) if isinstance(value, str) else None + if not match: + raise AtifError(f"{value!r} isn't an RFC 3339 time with a zone") + date, hours, minutes, seconds, digits, zone = match.groups() + digits = digits or "" + zone = "+00:00" if zone in ("Z", "z") else (zone if ":" in zone else f"{zone[:3]}:{zone[3:]}") + try: + parsed = datetime.fromisoformat(f"{date}T{hours}:{minutes}:{seconds}.{int((digits + '000000')[:6]):06d}{zone}") + except ValueError as exc: + raise AtifError(f"{value!r}: {exc}") from exc + moment = _utc(parsed, value) + text = (f"{moment.year:04d}-{moment.month:02d}-{moment.day:02d}T{moment.hour:02d}:{moment.minute:02d}:" + f"{moment.second:02d}") if digits: text += f".{moment.microsecond // 1000:03d}" if len(digits) <= 3 else f".{moment.microsecond:06d}" return text + "Z" +def _utc(moment: datetime, value: Any) -> datetime: + try: + return moment.astimezone(timezone.utc) + except (OverflowError, ValueError) as exc: + raise AtifError(f"{value!r} is out of range in UTC: {exc}") from exc + + +def _str(value: Any, what: str, *, optional: bool = True) -> str | None: + if value is None and optional: + return None + if not isinstance(value, str) or not value: + raise AtifError(f"{what} is a non-empty string, not {value!r}") + return value + + +def _int(value: Any, what: str, *, minimum: int | None = 0) -> int | None: + if value is None: + return None + if not isinstance(value, int) or isinstance(value, bool) or (minimum is not None and value < minimum): + floor = f" of {minimum} or more" if minimum is not None else "" + raise AtifError(f"{what} is an integer{floor}, not {value!r}") + return value + + +def _number(value: Any, what: str) -> float | int | None: + if value is None: + return None + if not isinstance(value, (int, float)) or isinstance(value, bool) or not math.isfinite(value): + raise AtifError(f"{what} is a finite number, not {value!r}") + return value + + def _json(value: Any, what: str) -> Any: try: json.dumps(value, allow_nan=False) @@ -200,6 +234,15 @@ def task_open(self) -> bool: def start_task(self, context: TurnContext) -> AtifTurn: if self._context is not None: raise AtifError(f"task {self._context.task_id} is still open") + _int(context.index, "TurnContext.index") + if context.index is None: + raise AtifError("TurnContext.index is the task's turn index") + _str(context.context_id, "TurnContext.context_id", optional=False) + _str(context.task_id, "TurnContext.task_id", optional=False) + for name in ("message_id", "agent_name", "agent_version", "agent_model"): + _str(getattr(context, name), f"TurnContext.{name}") + started = timestamp(context.started_at) + inbound, inbound_media = self.parse_parts(context.inbound, None) if self._root is None: self._root = _Trajectory(None, _agent(context.agent_name, context.agent_version, context.agent_model)) self._context_id = context.context_id @@ -208,8 +251,7 @@ def start_task(self, context: TurnContext) -> AtifTurn: self._context, self._task, self._attempt = context, self._task + 1, 1 self._task_costs.append(None) step = self._start(self._root, "user", None) - step.time = timestamp(context.started_at) - self._add_parts(step.parts, step.media, context.inbound, None) + step.time, step.parts, step.media = started, inbound, inbound_media step.profile.update({key: value for key, value in ( ("context_id", context.context_id), ("task_id", context.task_id), ("message_id", context.message_id), ("turn", context.index)) if value is not None}) @@ -224,14 +266,13 @@ def end_task(self, *, state: str = "completed", final: Sequence[Any] | None = No root = self._root assert root is not None if final: - parts: list[dict[str, Any]] = [] - media: dict[str, Any] = {} - self._add_parts(parts, media, final, None) + parts, media = self.parse_parts(final, None) + ended = timestamp(ended_at) last = next((s for s in reversed(root.steps) if s.task == self._task and s.source == "agent"), None) if last is None or _message(last.parts) != _message(parts): step = self._start(root, "agent", None) step.parts, step.media, step.llm_call_count = parts, media, 0 - step.time = timestamp(ended_at) + step.time = ended root.steps[-1].profile["state"] = state for trajectory in self._trajs(): for step in trajectory.steps: @@ -255,9 +296,10 @@ def open_step(self, agent: str | None) -> _Step: raise AtifError("no step is open: name the step this belongs to") return step - def call(self, step: _Step, call_id: str, name: str, arguments: Any) -> None: - if not isinstance(call_id, str) or not call_id: - raise AtifError("tool_call_id is a non-empty string") + def prepare_call(self, call_id: Any, name: Any, arguments: Any) -> dict[str, Any]: + """A call checked and shaped, before any step is touched.""" + _str(call_id, "tool_call_id", optional=False) + _str(name, "function_name", optional=False) if call_id in self._call_home: raise AtifError(f"tool_call_id {call_id!r} is already in this document") if isinstance(arguments, Mapping): @@ -266,25 +308,31 @@ def call(self, step: _Step, call_id: str, name: str, arguments: Any) -> None: raw = _json(arguments, f"{name}'s arguments") typed = {} if arguments is None else ({"input": arguments} if isinstance(arguments, str) else {"value": raw}) - step.calls.append({"tool_call_id": call_id, "function_name": name, "arguments": typed, "raw": raw}) - step.pending.add(call_id) - self._call_home[call_id] = (self._owner(step), step) + return {"tool_call_id": call_id, "function_name": name, "arguments": typed, "raw": raw} + + def call(self, step: _Step, call: dict[str, Any]) -> None: + step.calls.append(call) + step.pending.add(call["tool_call_id"]) + self._call_home[call["tool_call_id"]] = (self._owner(step), step) def result(self, call_id: str, content: Sequence[Any], status: str, exit_code: int | None, at: str | None) -> None: - if call_id not in self._call_home: + if not isinstance(call_id, str) or call_id not in self._call_home: raise AtifError(f"a result for {call_id!r}, which no call in this document made") + _int(exit_code, "exit_code", minimum=None) if status not in RESULT_STATUSES: raise AtifError(f"status {status!r} isn't one of {', '.join(RESULT_STATUSES)}") trajectory, home = self._call_home[call_id] - parts: list[dict[str, Any]] = [] - media: dict[str, Any] = {} - self._add_parts(parts, media, content, None) + if home.ended: + raise AtifError(f"call {call_id!r}'s task has ended, so its step is served and can't take a result") + if call_id not in home.pending: + raise AtifError(f"call {call_id!r} already has its result") + parts, media = self.parse_parts(content, None) profile: dict[str, Any] = {} if status != "ok": profile["status"] = status if exit_code is not None: - profile["exit_code"] = _json(exit_code, "exit_code") + profile["exit_code"] = exit_code if home.closed: opened = trajectory.open profile["arrived"] = {key: value for key, value in ( @@ -299,6 +347,10 @@ def result(self, call_id: str, content: Sequence[Any], status: str, exit_code: i def subagent(self, agent_id: str, spawned_by: str, name: str | None, version: str | None, model_name: str | None) -> None: + _str(agent_id, "a sub-agent's id", optional=False) + _str(spawned_by, "spawned_by", optional=False) + for what, value in (("name", name), ("version", version), ("model_name", model_name)): + _str(value, f"a sub-agent's {what}") if agent_id in self._subs: raise AtifError(f"sub-agent {agent_id!r} is already declared") self._subs[agent_id] = _Trajectory(agent_id, _agent(name or agent_id, version, model_name)) @@ -307,6 +359,11 @@ def subagent(self, agent_id: str, spawned_by: str, name: str | None, version: st def store(self, data: bytes, media_type: str, info: Mapping[str, Any]) -> Media: if not isinstance(data, (bytes, bytearray)): raise AtifError("media bytes are bytes") + if not isinstance(media_type, str) or "/" not in media_type: + raise AtifError(f"a media type is type/subtype, not {media_type!r}") + for key in ("width", "height", "duration_ms", "pages"): + _int(info.get(key), key) + _str(info.get("name"), "a media file's name") digest = hashlib.sha256(data).hexdigest() extension = _EXTENSIONS.get(media_type) or mimetypes.guess_extension(media_type, strict=False) or ".bin" path = f"media/{digest}{extension}" @@ -324,15 +381,24 @@ def count_unmatched(self, record: Any) -> None: def task_cost(self, cost_usd: float, source: str) -> None: if source not in COST_SOURCES: raise AtifError(f"cost_source {source!r} isn't one of {', '.join(COST_SOURCES)}") - self._task_costs[self._task] = (_json(cost_usd, "cost_usd"), source) + if self._context is None: + raise AtifError("no task is open") + if _number(cost_usd, "cost_usd") is None: + raise AtifError("cost_usd is a finite number") + self._task_costs[self._task] = (cost_usd, source) def set_attempt(self, number: int) -> None: - if not isinstance(number, int) or number < 1: + if _int(number, "an attempt number", minimum=1) is None: raise AtifError("an attempt number is 1 or more") self._attempt = number - def add_parts(self, step: _Step, content: Sequence[Any] | None, text: str | None) -> None: - self._add_parts(step.parts, step.media, content, text) + def parse_parts(self, content: Iterable[Any] | None, + text: str | None) -> tuple[list[dict[str, Any]], dict[str, Any]]: + """Content as ATIF parts and the media details they name, checked, before any step is touched.""" + parts: list[dict[str, Any]] = [] + media: dict[str, Any] = {} + self._add_parts(parts, media, content, text) + return parts, media # Reading the document @@ -355,6 +421,8 @@ def _traj(self, agent: str | None) -> _Trajectory: raise AtifError("no task is open") if agent is None: return self._root + if not isinstance(agent, str): + raise AtifError(f"agent names a declared sub-agent by its id, not {agent!r}") if agent not in self._subs: raise AtifError(f"sub-agent {agent!r} isn't declared: call turn.subagent first") return self._subs[agent] @@ -378,6 +446,8 @@ def _add_parts(self, parts: list[dict[str, Any]], media: dict[str, Any], content if content is not None: raise AtifError("give content or text, not both") content = [text] + if content is not None and not isinstance(content, (list, tuple)): + raise AtifError(f"content is a list of parts, not {type(content).__name__}") for item in content or (): if isinstance(item, Media): parts.append(item.part()) @@ -545,9 +615,12 @@ def spec(self) -> AdapterSpec: def message(self, *, step: str, text: str | None = None, content: Sequence[Any] | None = None, time: str | datetime | None = None, agent: str | None = None) -> None: """Assistant content in step ``step``: text, Media from ``media``, or ATIF parts.""" - target = self._doc.step_for(step, agent) - self._doc.add_parts(target, content, text) - self._touch(target, time) + parts, media = self._doc.parse_parts(content, text) + when = timestamp(time) + target = self._doc.step_for(_key(step), agent) + target.parts.extend(parts) + target.media.update(media) + self._touch(target, when) def reasoning(self, *, step: str, text: str | None = None, visibility: str = "raw", signature: str | None = None, data: str | None = None, time: str | datetime | None = None, agent: str | None = None) -> None: @@ -558,17 +631,22 @@ def reasoning(self, *, step: str, text: str | None = None, visibility: str = "ra for name, value in (("text", text), ("signature", signature), ("data", data)): if value is not None and not isinstance(value, str): raise AtifError(f"reasoning {name} is a string") - target = self._doc.step_for(step, agent) + when = timestamp(time) + target = self._doc.step_for(_key(step), agent) + if target.llm_call_count == 0: + raise AtifError("a step with no model call (llm_call_count 0) has no reasoning") target.reasoning.append({"text": text, "visibility": visibility, "signature": signature, "data": data}) - self._touch(target, time) + self._touch(target, when) def tool_call(self, *, step: str, tool_call_id: str, function_name: str, arguments: Any, time: str | datetime | None = None, agent: str | None = None) -> None: """A call in step ``step``. Arguments that aren't a JSON object are wrapped as Harbor wraps them (a string as ``{"input": ...}``, None as ``{}``, any other value as ``{"value": ...}``) and kept whole in ``raw_arguments``.""" - target = self._doc.step_for(step, agent) - self._doc.call(target, tool_call_id, function_name, arguments) - self._touch(target, time) + call = self._doc.prepare_call(tool_call_id, function_name, arguments) + when = timestamp(time) + target = self._doc.step_for(_key(step), agent) + self._doc.call(target, call) + self._touch(target, when) def tool_result(self, *, source_call_id: str, text: str | None = None, content: Sequence[Any] | None = None, status: str = "ok", exit_code: int | None = None, time: str | datetime | None = None) -> None: @@ -587,7 +665,29 @@ def step(self, *, key: str, model_name: str | None = None, llm_call_count: int | """What one model response cost and produced. Token counts are the native's; ATIF's ``prompt_tokens`` includes cache reads and writes, so the adapter's ``input_includes_cache`` decides the sum. A cost is the harness's or the provider's (``cost_source``), never one agentenv computed.""" - target = self._doc.step_for(key, agent) + _str(model_name, "model_name") + _int(llm_call_count, "llm_call_count") + if reasoning_effort is not None and not isinstance(reasoning_effort, str): + _number(reasoning_effort, "reasoning_effort") + if is_copied_context is not None and not isinstance(is_copied_context, bool): + raise AtifError(f"is_copied_context is true or false, not {is_copied_context!r}") + counts = (input_tokens, output_tokens, cache_read_tokens, cache_write_tokens) + for value in counts: + _int(value, "a token count") + _number(cost_usd, "cost_usd") + if any(value is not None for value in counts) or cost_usd is not None: + if llm_call_count == 0: + raise AtifError("a step with no model call (llm_call_count 0) has no usage or cost") + prompt_parts = (input_tokens, cache_read_tokens, cache_write_tokens) + includes = self.spec.input_includes_cache + if any(value is not None for value in prompt_parts) and includes is None: + raise AtifError("declare input_includes_cache on @atif_adapter to write prompt tokens") + if cost_usd is not None and cost_source not in COST_SOURCES: + raise AtifError(f"a cost names its cost_source: one of {', '.join(COST_SOURCES)}") + when = timestamp(time) + target = self._doc.step_for(_key(key), agent) + if llm_call_count == 0 and (target.metrics or target.metrics_profile or target.reasoning): + raise AtifError("a step with no model call (llm_call_count 0) has no usage or reasoning, and this one has") if model_name is not None: target.model_name = model_name if reasoning_effort is not None: @@ -595,17 +695,7 @@ def step(self, *, key: str, model_name: str | None = None, llm_call_count: int | target.llm_call_count = llm_call_count if is_copied_context is not None: target.is_copied_context = is_copied_context - counts = (input_tokens, output_tokens, cache_read_tokens, cache_write_tokens) - if any(value is not None for value in counts) or cost_usd is not None: - if llm_call_count == 0: - raise AtifError("a step with no model call (llm_call_count 0) has no usage or cost") - for value in counts: - if value is not None and (not isinstance(value, int) or isinstance(value, bool) or value < 0): - raise AtifError(f"token counts are non-negative integers, not {value!r}") - if input_tokens is not None or cache_read_tokens is not None or cache_write_tokens is not None: - includes = self.spec.input_includes_cache - if includes is None: - raise AtifError("declare input_includes_cache on @atif_adapter to write prompt tokens") + if any(value is not None for value in prompt_parts): prompt = (input_tokens or 0) + (0 if includes else (cache_read_tokens or 0) + (cache_write_tokens or 0)) target.metrics["prompt_tokens"] = prompt if cache_read_tokens is not None: @@ -615,12 +705,10 @@ def step(self, *, key: str, model_name: str | None = None, llm_call_count: int | if output_tokens is not None: target.metrics["completion_tokens"] = output_tokens if cost_usd is not None: - if cost_source not in COST_SOURCES: - raise AtifError(f"a cost names its cost_source: one of {', '.join(COST_SOURCES)}") - target.metrics["cost_usd"] = _json(cost_usd, "cost_usd") + target.metrics["cost_usd"] = cost_usd target.metrics_profile["cost_source"] = cost_source - if time is not None: - target.step_time = timestamp(time) + if when is not None: + target.step_time = when def task_cost(self, cost_usd: float, *, source: str) -> None: """The task's total cost, as the harness or provider reported it, when its steps carry none.""" @@ -632,7 +720,9 @@ def error(self, *, message: str, kind: str = "agent_error", code: str | None = N step; a later error on the same step replaces it.""" if kind not in ERROR_KINDS: raise AtifError(f"kind {kind!r} isn't one of {', '.join(ERROR_KINDS)}") - target = self._doc.step_for(step, agent) if step is not None else self._doc.open_step(agent) + _str(message, "an error's message", optional=False) + _str(code, "an error's code") + target = self._doc.step_for(_key(step), agent) if step is not None else self._doc.open_step(agent) target.profile["error"] = {k: v for k, v in (("kind", kind), ("message", message), ("code", code)) if v is not None} @@ -656,6 +746,12 @@ def unmatched(self, record: Any) -> None: """Count a native record nothing handled, by its type, in the root profile.""" self._doc.count_unmatched(record) - def _touch(self, step: _Step, time: str | datetime | None) -> None: - if step.time is None and time is not None: - step.time = timestamp(time) + def _touch(self, step: _Step, when: str | None) -> None: + if step.time is None and when is not None: + step.time = when + + +def _key(key: Any) -> str: + if not isinstance(key, str) or not key: + raise AtifError(f"a step key is a non-empty string, not {key!r}") + return key diff --git a/packages/agentenv-protocol/tests/test_atif_builder.py b/packages/agentenv-protocol/tests/test_atif_builder.py index 7783ba6f0..8ea75bff4 100644 --- a/packages/agentenv-protocol/tests/test_atif_builder.py +++ b/packages/agentenv-protocol/tests/test_atif_builder.py @@ -342,3 +342,99 @@ def test_from_atif_is_each_adapters_own(): with pytest.raises(NotImplementedError): adapter().from_atif({}) assert Native(log=[{"type": "x"}]).session is None + + +def test_a_time_out_of_range_in_utc_is_refused_and_early_years_keep_four_digits(): + with pytest.raises(AtifError, match="out of range"): + timestamp("0001-01-01T00:00:00+05:00") + with pytest.raises(AtifError, match="out of range"): + timestamp("9999-12-31T23:59:59-05:00") + assert timestamp("0099-01-01T00:00:00Z") == "0099-01-01T00:00:00Z" + + +def test_a_refused_task_start_leaves_no_task_open(): + run = AdapterRun(adapter()) + with pytest.raises(AtifError): + run.start_task(TurnContext(index=0, context_id="ctx", task_id="t1", started_at="yesterday")) + assert run.document() is None + run.start_task(CTX) + run.end_task() + + +@pytest.mark.parametrize("record", [ + {"type": "call", "step": "s1", "id": "c1", "args": {}, "name": 3}, + {"type": "call", "step": ["s1"], "id": "c1"}, + {"type": "say", "step": "s1", "text": 1.5}, +]) +def test_a_value_of_the_wrong_type_is_refused_without_touching_the_document(record): + @atif_adapter(native_format="toy-types/1", version="1", input_includes_cache=None) + class Raw(Adapter): + @native(type="call") + def call(self, r, turn): + turn.tool_call(step=r["step"], tool_call_id=r["id"], function_name=r.get("name", "Bash"), + arguments=r.get("args")) + + @native(type="say") + def say(self, r, turn): + turn.message(step=r["step"], text=r["text"]) + + run = AdapterRun(Raw) + run.start_task(CTX) + before = run.document() + with pytest.raises(AtifError): + run.native(record) + assert run.document() == before + + +@pytest.mark.parametrize("call", [ + lambda turn: turn.step(key="s1", llm_call_count=[1]), + lambda turn: turn.step(key="s1", reasoning_effort=float("nan")), + lambda turn: turn.message(step="s1", content=1.5), + lambda turn: turn.message(step="s1", text="x", agent={"id": "sub"}), + lambda turn: turn.media(b"x", "image/png", pages=1.5), + lambda turn: turn.media(b"x", "png"), + lambda turn: turn.tool_result(source_call_id="none", text="x"), + lambda turn: turn.error(message=""), + lambda turn: turn.attempt(True), +]) +def test_the_builder_refuses_values_atif_or_the_profile_would_not_read(call): + @atif_adapter(native_format="toy-call/1", version="1", input_includes_cache=True) + class Calls(Adapter): + @native(type="go") + def go(self, r, turn): + turn.message(step="s1", text="open") + r["call"](turn) + + run = AdapterRun(Calls) + run.start_task(CTX) + with pytest.raises(AtifError): + run.native({"type": "go", "call": call}) + + +def test_a_call_takes_one_result_and_none_once_its_task_has_ended(): + run = AdapterRun(adapter()) + run.start_task(CTX) + for record in [{"type": "call", "step": "A", "id": "c1"}, {"type": "result", "id": "c1"}, + {"type": "call", "step": "B", "id": "c2"}, {"type": "say", "step": "C", "text": "x"}]: + run.native(record) + served = run.page() + with pytest.raises(AtifError, match="already has its result"): + run.native({"type": "result", "id": "c1"}) + run.end_task() + served = run.page() + run.start_task(TurnContext(index=1, context_id="ctx", task_id="t2", inbound=["more"])) + with pytest.raises(AtifError, match="task has ended"): + run.native({"type": "result", "id": "c2"}) + assert run.document()["steps"][:len(served["steps"])] == served["steps"] + + +def test_a_step_with_no_model_call_takes_no_reasoning(): + @atif_adapter(native_format="toy-zero/1", version="1", input_includes_cache=True) + class Zero(Adapter): + @native(type="z") + def z(self, r, turn): + turn.reasoning(step="s1", text="thinking") + turn.step(key="s1", llm_call_count=0) + + with pytest.raises(AtifError, match="no model call"): + run_task([{"type": "z"}], cls=Zero) From 3687074f8981b96a98e81a5dc61ecad8b61a690e Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 10:00:05 -0800 Subject: [PATCH 4/7] test(protocol): the ATIF fixtures are read where the package is installed Co-Authored-By: Claude Opus 5.5 --- packages/agentenv-protocol/tests/atif_cases.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/agentenv-protocol/tests/atif_cases.py b/packages/agentenv-protocol/tests/atif_cases.py index 83a084487..169846f6b 100644 --- a/packages/agentenv-protocol/tests/atif_cases.py +++ b/packages/agentenv-protocol/tests/atif_cases.py @@ -6,12 +6,13 @@ import json import sys from dataclasses import dataclass, field +from importlib.resources import files from pathlib import Path from typing import Any from agentenv_protocol.atif import Adapter, AdapterRun, TurnContext, atif_adapter, finish, native, strip_profile -FIXTURES = Path(__file__).resolve().parents[1] / "src/agentenv_protocol/atif/fixtures" +FIXTURES = Path(str(files("agentenv_protocol.atif").joinpath("fixtures"))) CONTEXT = "ctx-7f3a" From 7ebe40e0ece1a56875290425991de4f75479fd76 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 10:17:33 -0800 Subject: [PATCH 5/7] fix(protocol): ATIF usage given over several records keeps every count, totals need every model step, sub-agent references always resolve, and stripping the profile leaves arguments alone - AtifTurn.step keeps each step's native counts (input, cache reads, cache writes), each the latest given, and writes prompt_tokens from all of them once the input count is known; with input_includes_cache, cache counts over the input count are refused. - final_metrics totals a count or cost only when every model step (every agent step but llm_call_count 0) has it. - A sub-agent is spawned by a call of the open task still waiting on its result, and writes only in that task. One that wrote no step is left out with its reference; a live page holds back a step whose result references a sub-agent it shows no step of yet, until the task ends. - strip_profile takes extra.agentenv off the ATIF objects that own an extra only, so tool arguments, raw_arguments and other extras keep it. - _size's byte thresholds are named. Co-Authored-By: Claude Opus 5.5 --- .../src/agentenv_protocol/atif/PROFILE.md | 19 ++- .../src/agentenv_protocol/atif/builder.py | 122 ++++++++++++------ .../src/agentenv_protocol/atif/reader.py | 45 ++++--- .../tests/test_atif_builder.py | 113 +++++++++++++++- .../tests/test_atif_reader.py | 16 ++- 5 files changed, 253 insertions(+), 62 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md b/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md index 520e8f6a2..717283ba5 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md @@ -28,7 +28,8 @@ to native exactly. index, and each earlier document names the next in `continued_trajectory_ref`. The worker that stores the earlier document sets that link, since the agent that wrote it may be gone. - A sub-agent is an embedded trajectory in `subagent_trajectories`, with its own steps, referenced from the spawning - call's result by `subagent_trajectory_ref`. + call's result by `subagent_trajectory_ref`. It belongs to the task of the call that spawned it. A sub-agent that + wrote no step is left out, and so is the reference to it. - `schema_version` is the oldest ATIF version that holds the document's fields: `ATIF-v1.8` for profile 1.0. - Format id: `atif/1`. The profile's own version is the root's `extra.agentenv.version`. @@ -39,9 +40,10 @@ to native exactly. task ends. - A result always sits in the step that made its call, as ATIF requires. One that arrives after that step closed records when, in `arrived`. -- A live reader is served closed steps only, each trajectory up to its first step still waiting on a result. Steps are - ordered, so a step waiting on a late result holds back the steps after it until the result comes or the task ends. - Everything a reader is served is a prefix of every later read. +- A live reader is served closed steps only, each trajectory up to its first step still waiting on a result or + referencing a sub-agent the reader isn't served a step of yet. Steps are ordered, so such a step holds back the steps + after it until the result or the sub-agent's step comes, or the task ends. Everything a reader is served is a prefix + of every later read, and every reference it is served resolves. - The final response is written once. When the task's last agent step already holds the same text, nothing is added; otherwise one step is appended, `source: agent` and `llm_call_count` 0. The task's terminal state goes on the task's last step, which closes only when the task ends, so it is never served before the state is known. @@ -53,7 +55,10 @@ to native exactly. validator on Python 3.10 reads no other. - Usage follows ATIF: `prompt_tokens` includes cache reads and writes, and `cached_tokens` is the cache reads. Each adapter's `input_includes_cache` constant says whether its native input count already includes the cache. - Cache writes go in `Metrics.extra.agentenv.cache_write_tokens`. + Cache writes go in `Metrics.extra.agentenv.cache_write_tokens`. An adapter may give a step's counts over several + records: each count is the latest given, and `prompt_tokens` is written once the input count is known. +- `final_metrics` totals a count only when every model step, every agent step but those with `llm_call_count` 0, has + it; otherwise the total is left out, which ATIF readers read as unknown. - A tool call whose input isn't a JSON object is wrapped as Harbor wraps it: a string as `{"input": ...}`, a missing input as `{}`, any other value as `{"value": ...}`. The native input is kept in `ToolCall.extra.raw_arguments`, only when wrapping changed it. Harbor's ATIF-to-Codex resume reads that key back. @@ -70,7 +75,9 @@ ATIF defines a step's `cost_usd` as the cost "based on current provider pricing - A cost agentenv computes itself, from its own price table after the run, never goes in a typed field. The framework records that one with the run's usage instead, as a `priced` cost whose `cost_source` names the price table's version; `harness` and `provider` mean the same there as here. -- When nothing reports a cost, the typed fields stay empty, which ATIF readers read as unknown. +- `total_cost_usd` is the sum of the tasks' reported costs when every task has one, else of the steps' costs when + every model step has one. When nothing reports a cost, the typed fields stay empty, which ATIF readers read as + unknown. ## Errors diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py index 35bdc8abf..35ccc58c6 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py @@ -44,6 +44,9 @@ _TIME = re.compile(r"^(\d{4}-\d{2}-\d{2})[Tt ](\d{2}):(\d{2}):(\d{2})(?:[.,](\d+))?([Zz]|[+-]\d{2}:?\d{2})$") _JOIN = "\n\n" _UNSET: Any = object() +_KILOBYTE = 1000 +_MEGABYTE = 1_000_000 +_PROMPT_PARTS = ("input", "cache_read", "cache_write") def timestamp(value: str | datetime | None) -> str | None: @@ -115,9 +118,23 @@ def _json(value: Any, what: str) -> Any: def _size(count: int) -> str: - if count < 1000: + if count < _KILOBYTE: return f"{count} B" - return f"{count / 1000:.1f} KB" if count < 1_000_000 else f"{count / 1_000_000:.1f} MB" + return f"{count / _KILOBYTE:.1f} KB" if count < _MEGABYTE else f"{count / _MEGABYTE:.1f} MB" + + +def _prompt_tokens(usage: Mapping[str, int], includes: bool | None) -> int | None: + """ATIF's ``prompt_tokens``, cache reads and writes included, from a step's native counts; unknown until its + input count is.""" + if "input" not in usage: + return None + cache = usage.get("cache_read", 0) + usage.get("cache_write", 0) + if not includes: + return usage["input"] + cache + if cache > usage["input"]: + raise AtifError(f"cache reads and writes ({cache}) exceed the input count that includes them " + f"({usage['input']})") + return usage["input"] @dataclass(frozen=True) @@ -188,6 +205,7 @@ class _Step: results: list[dict[str, Any]] = field(default_factory=list) metrics: dict[str, Any] = field(default_factory=dict) metrics_profile: dict[str, Any] = field(default_factory=dict) + usage: dict[str, int] = field(default_factory=dict) profile: dict[str, Any] = field(default_factory=dict) pending: set[str] = field(default_factory=set) model_name: str | None = None @@ -206,6 +224,7 @@ class _Trajectory: agent: dict[str, Any] steps: list[_Step] = field(default_factory=list) open: _Step | None = None + task: int = -1 class Document: @@ -283,12 +302,13 @@ def end_task(self, *, state: str = "completed", final: Sequence[Any] | None = No # What handlers call, through AtifTurn + def peek(self, key: str, agent: str | None) -> _Step | None: + """The open step content under ``key`` would go to, or None when it would start a new one.""" + step = self._traj(agent).open + return step if step is not None and step.key == key and step.source == "agent" else None + def step_for(self, key: str, agent: str | None) -> _Step: - trajectory = self._traj(agent) - step = trajectory.open - if step is None or step.key != key or step.source != "agent": - step = self._start(trajectory, "agent", key) - return step + return self.peek(key, agent) or self._start(self._traj(agent), "agent", key) def open_step(self, agent: str | None) -> _Step: step = self._traj(agent).open @@ -353,7 +373,14 @@ def subagent(self, agent_id: str, spawned_by: str, name: str | None, version: st _str(value, f"a sub-agent's {what}") if agent_id in self._subs: raise AtifError(f"sub-agent {agent_id!r} is already declared") - self._subs[agent_id] = _Trajectory(agent_id, _agent(name or agent_id, version, model_name)) + if self._context is None: + raise AtifError("no task is open") + home = self._call_home.get(spawned_by) + if home is None or home[1].task != self._task or spawned_by not in home[1].pending: + raise AtifError(f"spawned_by is a call of this task still waiting on its result, not {spawned_by!r}") + if spawned_by in self._spawned: + raise AtifError(f"call {spawned_by!r} already spawned sub-agent {self._spawned[spawned_by]!r}") + self._subs[agent_id] = _Trajectory(agent_id, _agent(name or agent_id, version, model_name), task=self._task) self._spawned[spawned_by] = agent_id def store(self, data: bytes, media_type: str, info: Mapping[str, Any]) -> Media: @@ -425,7 +452,10 @@ def _traj(self, agent: str | None) -> _Trajectory: raise AtifError(f"agent names a declared sub-agent by its id, not {agent!r}") if agent not in self._subs: raise AtifError(f"sub-agent {agent!r} isn't declared: call turn.subagent first") - return self._subs[agent] + trajectory = self._subs[agent] + if trajectory.task != self._task: + raise AtifError(f"sub-agent {agent!r} belongs to an earlier task") + return trajectory def _owner(self, step: _Step) -> _Trajectory: return next(t for t in self._trajs() if any(s is step for s in t.steps)) @@ -473,23 +503,37 @@ def _servable(self, trajectory: _Trajectory) -> int: count += 1 return count + def _counts(self, closed_only: bool) -> dict[str | None, int]: + """How many steps of each trajectory a read shows, by sub-agent id (None for the root). A live page also holds + back a step whose result points at a sub-agent it shows no step of yet, until the step's task ends.""" + trajectories = self._trajs() + if not closed_only: + return {t.actor: len(t.steps) for t in trajectories} + counts = {t.actor: self._servable(t) for t in trajectories} + cut = True + while cut: + cut = False + for trajectory in trajectories: + for index, step in enumerate(trajectory.steps[:counts[trajectory.actor]]): + if not step.ended and any(not counts[r["subagent"]] for r in step.results if "subagent" in r): + counts[trajectory.actor], cut = index, True + break + return counts + def _render(self, *, closed_only: bool) -> dict[str, Any] | None: root = self._root if root is None: return None - root_count = self._servable(root) if closed_only else len(root.steps) - if root_count == 0: + counts = self._counts(closed_only) + if counts[None] == 0: return None + linked = {actor for actor, count in counts.items() if actor is not None and count} doc: dict[str, Any] = {"schema_version": SCHEMA_VERSION, "session_id": self._context_id, "agent": dict(root.agent), - "steps": [_render_step(s) for s in root.steps[:root_count]]} - subs = [] - for trajectory in self._subs.values(): - count = self._servable(trajectory) if closed_only else len(trajectory.steps) - if count: - subs.append({"schema_version": SCHEMA_VERSION, "trajectory_id": trajectory.actor, - "agent": dict(trajectory.agent), - "steps": [_render_step(s) for s in trajectory.steps[:count]]}) + "steps": [_render_step(s, linked) for s in root.steps[:counts[None]]]} + subs = [{"schema_version": SCHEMA_VERSION, "trajectory_id": trajectory.actor, "agent": dict(trajectory.agent), + "steps": [_render_step(s, linked) for s in trajectory.steps[:counts[trajectory.actor]]]} + for trajectory in self._subs.values() if counts[trajectory.actor]] if subs: doc["subagent_trajectories"] = subs if self._context is None: @@ -502,8 +546,7 @@ def _render(self, *, closed_only: bool) -> dict[str, Any] | None: return doc def _final_metrics(self, root: _Trajectory) -> dict[str, Any]: - steps = [s for t in self._trajs() for s in t.steps - if s.source == "agent" and s.llm_call_count != 0 and (s.metrics or s.metrics_profile)] + steps = [s for t in self._trajs() for s in t.steps if s.source == "agent" and s.llm_call_count != 0] totals: dict[str, Any] = {} for key, total in (("prompt_tokens", "total_prompt_tokens"), ("completion_tokens", "total_completion_tokens"), ("cached_tokens", "total_cached_tokens")): @@ -543,7 +586,7 @@ def _message(parts: list[dict[str, Any]]) -> str | list[dict[str, Any]]: return [dict(part) for part in parts] -def _render_step(step: _Step) -> dict[str, Any]: +def _render_step(step: _Step, linked: set[str]) -> dict[str, Any]: agentic = step.source == "agent" out: dict[str, Any] = {"step_id": step.index + 1} when = step.step_time or step.time @@ -570,7 +613,7 @@ def _render_step(step: _Step) -> dict[str, Any]: results = [] for result in step.results: rendered = {"source_call_id": result["source_call_id"], "content": _message(result["parts"])} - if "subagent" in result: + if result.get("subagent") in linked: rendered["subagent_trajectory_ref"] = [{"trajectory_id": result["subagent"]}] if result["profile"]: rendered["extra"] = {PROFILE_KEY: dict(result["profile"])} @@ -662,9 +705,10 @@ def step(self, *, key: str, model_name: str | None = None, llm_call_count: int | cache_write_tokens: int | None = None, cost_usd: float | None = None, cost_source: str | None = None, time: str | datetime | None = None, is_copied_context: bool | None = None, agent: str | None = None) -> None: - """What one model response cost and produced. Token counts are the native's; ATIF's ``prompt_tokens`` - includes cache reads and writes, so the adapter's ``input_includes_cache`` decides the sum. A cost is - the harness's or the provider's (``cost_source``), never one agentenv computed.""" + """What one model response cost and produced. Token counts are the native's, each the latest given for the + step; ATIF's ``prompt_tokens`` includes cache reads and writes, so the adapter's ``input_includes_cache`` + decides the sum, written once the input count is known. A cost is the harness's or the provider's + (``cost_source``), never one agentenv computed.""" _str(model_name, "model_name") _int(llm_call_count, "llm_call_count") if reasoning_effort is not None and not isinstance(reasoning_effort, str): @@ -685,9 +729,14 @@ def step(self, *, key: str, model_name: str | None = None, llm_call_count: int | if cost_usd is not None and cost_source not in COST_SOURCES: raise AtifError(f"a cost names its cost_source: one of {', '.join(COST_SOURCES)}") when = timestamp(time) - target = self._doc.step_for(_key(key), agent) - if llm_call_count == 0 and (target.metrics or target.metrics_profile or target.reasoning): + current = self._doc.peek(_key(key), agent) + usage = dict(current.usage) if current is not None else {} + usage.update({name: value for name, value in zip(_PROMPT_PARTS, prompt_parts) if value is not None}) + prompt = _prompt_tokens(usage, includes) + if llm_call_count == 0 and current is not None and (current.metrics or current.metrics_profile + or current.reasoning): raise AtifError("a step with no model call (llm_call_count 0) has no usage or reasoning, and this one has") + target = self._doc.step_for(_key(key), agent) if model_name is not None: target.model_name = model_name if reasoning_effort is not None: @@ -695,13 +744,13 @@ def step(self, *, key: str, model_name: str | None = None, llm_call_count: int | target.llm_call_count = llm_call_count if is_copied_context is not None: target.is_copied_context = is_copied_context - if any(value is not None for value in prompt_parts): - prompt = (input_tokens or 0) + (0 if includes else (cache_read_tokens or 0) + (cache_write_tokens or 0)) + target.usage = usage + if prompt is not None: target.metrics["prompt_tokens"] = prompt - if cache_read_tokens is not None: - target.metrics["cached_tokens"] = cache_read_tokens - if cache_write_tokens is not None: - target.metrics_profile["cache_write_tokens"] = cache_write_tokens + if "cache_read" in usage: + target.metrics["cached_tokens"] = usage["cache_read"] + if "cache_write" in usage: + target.metrics_profile["cache_write_tokens"] = usage["cache_write"] if output_tokens is not None: target.metrics["completion_tokens"] = output_tokens if cost_usd is not None: @@ -732,8 +781,9 @@ def attempt(self, number: int) -> None: def subagent(self, agent_id: str, *, spawned_by: str, name: str | None = None, version: str | None = None, model_name: str | None = None) -> None: - """Declare a sub-agent the call ``spawned_by`` started. Its steps (written with ``agent=agent_id``) form an - embedded trajectory, and the spawning call's result points at it.""" + """Declare a sub-agent the call ``spawned_by`` started: a call of this task still waiting on its result. Its + steps (written with ``agent=agent_id``, in this task) form an embedded trajectory, and the spawning call's + result points at it; a sub-agent that writes no step is left out, and so is the pointer.""" self._doc.subagent(agent_id, spawned_by, name, version, model_name) def media(self, data: bytes, media_type: str, *, width: int | None = None, height: int | None = None, diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/reader.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/reader.py index 0e1f445f2..a8dc625d9 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/reader.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/reader.py @@ -111,22 +111,35 @@ def media_paths(document: Mapping[str, Any]) -> list[str]: def strip_profile(document: Mapping[str, Any]) -> dict[str, Any]: - """A copy without any ``extra.agentenv``; an ``extra`` left empty goes too. What remains is plain ATIF.""" - def walk(value: Any) -> Any: - if isinstance(value, Mapping): - out = {} - for key, item in value.items(): - if key == "extra" and isinstance(item, Mapping): - rest = {k: walk(v) for k, v in item.items() if k != PROFILE_KEY} - if rest: - out[key] = rest - continue - out[key] = walk(item) - return out - if isinstance(value, list): - return [walk(item) for item in value] - return value - return walk(document) + """A copy without the profile: ``extra.agentenv`` taken off each ATIF object that has an ``extra``, and an + ``extra`` left empty with it. Tool arguments and every other free-form value stay as they are.""" + stripped = copy.deepcopy(dict(document)) + _strip_trajectory(stripped) + return stripped + + +def _strip_trajectory(trajectory: dict[str, Any]) -> None: + for owner in (trajectory, trajectory.get("agent"), trajectory.get("final_metrics")): + _strip(owner) + for step in trajectory.get("steps") or []: + _strip(step) + _strip(step.get("metrics")) + for call in step.get("tool_calls") or []: + _strip(call) + for result in (step.get("observation") or {}).get("results") or []: + _strip(result) + for ref in result.get("subagent_trajectory_ref") or []: + _strip(ref) + for sub in trajectory.get("subagent_trajectories") or []: + _strip_trajectory(sub) + + +def _strip(owner: Any) -> None: + extra = owner.get("extra") if isinstance(owner, dict) else None + if isinstance(extra, dict) and PROFILE_KEY in extra: + del extra[PROFILE_KEY] + if not extra: + del owner["extra"] def is_prefix(page: Mapping[str, Any] | None, later: Mapping[str, Any] | None) -> bool: diff --git a/packages/agentenv-protocol/tests/test_atif_builder.py b/packages/agentenv-protocol/tests/test_atif_builder.py index 8ea75bff4..372cf7562 100644 --- a/packages/agentenv-protocol/tests/test_atif_builder.py +++ b/packages/agentenv-protocol/tests/test_atif_builder.py @@ -111,9 +111,9 @@ def test_a_step_still_waiting_on_a_result_is_served_when_its_task_ends(): check(pages[-1]) -@pytest.mark.parametrize("includes,expected", [(False, 95), (True, 10)]) -def test_usage_is_written_in_atifs_terms(includes, expected): - run, _ = run_task([{"type": "usage", "step": "s1", "in": 10, "read": 80, "write": 5, "out": 7}], +@pytest.mark.parametrize("includes,given,expected", [(False, 10, 95), (True, 100, 100)]) +def test_usage_is_written_in_atifs_terms(includes, given, expected): + run, _ = run_task([{"type": "usage", "step": "s1", "in": given, "read": 80, "write": 5, "out": 7}], cls=adapter(includes)) metrics = run.document()["steps"][1]["metrics"] assert metrics["prompt_tokens"] == expected and metrics["cached_tokens"] == 80 @@ -438,3 +438,110 @@ def z(self, r, turn): with pytest.raises(AtifError, match="no model call"): run_task([{"type": "z"}], cls=Zero) + + +@pytest.mark.parametrize("includes,expected", [(False, 160), (True, 100)]) +def test_usage_given_over_several_records_keeps_every_count(includes, expected): + run, pages = run_task([{"type": "usage", "step": "s1", "read": 50}, {"type": "usage", "step": "s1", "in": 100}, + {"type": "usage", "step": "s1", "write": 10, "out": 7}], cls=adapter(includes)) + metrics = run.document()["steps"][1]["metrics"] + assert metrics["prompt_tokens"] == expected and metrics["cached_tokens"] == 50 and metrics["completion_tokens"] == 7 + assert metrics["extra"] == {"agentenv": {"cache_write_tokens": 10}} + early = AdapterRun(adapter(includes)) + early.start_task(CTX) + early.native({"type": "usage", "step": "s1", "read": 50}) + assert "prompt_tokens" not in early.document()["steps"][1]["metrics"] + + +def test_cache_counts_over_an_input_count_that_includes_them_are_refused(): + run = AdapterRun(adapter(True)) + run.start_task(CTX) + run.native({"type": "usage", "step": "s1", "in": 40, "read": 30}) + before = run.document() + with pytest.raises(AtifError, match="exceed the input count"): + run.native({"type": "usage", "step": "s1", "write": 20}) + assert run.document() == before + + +def test_a_total_is_left_out_when_a_model_step_has_no_count(): + run, _ = run_task([{"type": "say", "step": "s1", "text": "a"}, {"type": "usage", "step": "s1", "in": 100, "out": 5}, + {"type": "say", "step": "s2", "text": "b"}], final=["done"]) + totals = run.document()["final_metrics"] + assert "total_prompt_tokens" not in totals and "total_completion_tokens" not in totals + measured, _ = run_task([{"type": "say", "step": "s1", "text": "a"}, {"type": "usage", "step": "s1", "in": 100}], + final=["done"]) + assert measured.document()["final_metrics"]["total_prompt_tokens"] == 100 + + +def _spawner(): + @atif_adapter(native_format="toy-spawn/1", version="1", input_includes_cache=True) + class Spawner(Adapter): + @native(type="task") + def task(self, r, turn): + turn.tool_call(step=r["step"], tool_call_id=r["id"], function_name="Task", arguments={}) + + @native(type="spawn") + def spawn(self, r, turn): + turn.subagent(r["agent"], spawned_by=r["id"]) + + @native(type="sub") + def sub(self, r, turn): + turn.message(step=r["step"], text="working", agent=r["agent"]) + + @native(type="result") + def result(self, r, turn): + turn.tool_result(source_call_id=r["id"], text="done") + + @native(type="say") + def say(self, r, turn): + turn.message(step=r["step"], text=r["text"]) + return Spawner + + +def _refs(read): + return [ref["trajectory_id"] for step in read["steps"] for result in (step.get("observation") or {}).get("results") + or [] for ref in result.get("subagent_trajectory_ref") or []] + + +def test_a_sub_agent_that_wrote_no_step_is_left_out_with_its_pointer(): + run, _ = run_task([{"type": "task", "step": "p1", "id": "c1"}, {"type": "spawn", "id": "c1", "agent": "sub"}, + {"type": "result", "id": "c1"}], final=["done"], cls=_spawner()) + document = run.document() + check(document) + assert _refs(document) == [] and "subagent_trajectories" not in document + + +def test_a_live_page_shows_a_pointer_only_with_a_step_of_its_sub_agent(): + run = AdapterRun(_spawner()) + run.start_task(CTX) + pages = [] + for record in [{"type": "task", "step": "p1", "id": "c1"}, {"type": "spawn", "id": "c1", "agent": "sub"}, + {"type": "sub", "step": "x1", "agent": "sub"}, {"type": "result", "id": "c1"}, + {"type": "say", "step": "p2", "text": "next"}, {"type": "say", "step": "p3", "text": "more"}, + {"type": "sub", "step": "x2", "agent": "sub"}]: + pages.append(run.native(record)) + pages.append(run.end_task()) + assert [len(p["steps"]) if p else 0 for p in pages] == [1, 1, 1, 1, 1, 1, 3, 4] + for page in filter(None, pages): + trajectories = {sub["trajectory_id"] for sub in page.get("subagent_trajectories") or []} + assert set(_refs(page)) <= trajectories and is_prefix(page, run.document()) + assert _refs(pages[-1]) == ["sub"] + + +def test_a_sub_agent_is_spawned_by_a_call_of_its_task_waiting_on_its_result_and_writes_only_in_that_task(): + run = AdapterRun(_spawner()) + run.start_task(CTX) + for record in [{"type": "task", "step": "p1", "id": "c1"}, {"type": "result", "id": "c1"}]: + run.native(record) + with pytest.raises(AtifError, match="still waiting on its result"): + run.native({"type": "spawn", "id": "c1", "agent": "late"}) + with pytest.raises(AtifError, match="still waiting on its result"): + run.native({"type": "spawn", "id": "nothing", "agent": "late"}) + run.native({"type": "task", "step": "p2", "id": "c2"}) + run.native({"type": "spawn", "id": "c2", "agent": "sub"}) + with pytest.raises(AtifError, match="already spawned"): + run.native({"type": "spawn", "id": "c2", "agent": "other"}) + run.end_task() + run.start_task(TurnContext(index=1, context_id="ctx", task_id="t2", inbound=["more"])) + with pytest.raises(AtifError, match="earlier task"): + run.native({"type": "sub", "step": "x1", "agent": "sub"}) diff --git a/packages/agentenv-protocol/tests/test_atif_reader.py b/packages/agentenv-protocol/tests/test_atif_reader.py index 85e2e8c42..ef16f4105 100644 --- a/packages/agentenv-protocol/tests/test_atif_reader.py +++ b/packages/agentenv-protocol/tests/test_atif_reader.py @@ -4,7 +4,7 @@ import pytest -from agentenv_protocol.atif import AtifError, is_prefix, load, media_paths, strip_profile, tasks +from agentenv_protocol.atif import AtifError, check, is_prefix, load, media_paths, strip_profile, tasks from atif_cases import FIXTURES @@ -60,3 +60,17 @@ def test_a_page_is_a_prefix_only_when_its_steps_lead_every_trajectory(): assert is_prefix(page, final) and is_prefix(None, final) assert not is_prefix({**page, "steps": final["steps"][1:3]}, final) assert not is_prefix(final, {**final, "subagent_trajectories": []}) + + +def test_stripping_the_profile_leaves_tool_arguments_and_other_extras_alone(): + document = fixture("coding") + payload = {"extra": {"agentenv": {"x": 1}}, "nested": [{"extra": {"agentenv": 2}}]} + call = document["steps"][1]["tool_calls"][0] + call["arguments"] = payload + call["extra"] = {"raw_arguments": payload, "agentenv": {}} + document["extra"]["other"] = {"agentenv": "kept"} + stripped = strip_profile(document) + assert stripped["steps"][1]["tool_calls"][0] == {**call, "extra": {"raw_arguments": payload}} + assert stripped["extra"] == {"other": {"agentenv": "kept"}} + assert "extra" not in stripped["steps"][0] and document["steps"][1]["tool_calls"][0]["extra"]["agentenv"] == {} + check(stripped) From 5708f3723c117ab363a7716020ed1a8ca078fff4 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 10:47:15 -0800 Subject: [PATCH 6/7] fix(protocol): ATIF pages are built when read from steps rendered once, media given to a sink aren't kept, and the vendored models carry their notices - AdapterRun's start_task, native, aux and end_task return nothing; page() builds the live view when it's read. A step a page served never changes, so its JSON is rendered once and kept, and a read costs one parse. Feeding 2,000 steps with a page every 50 took 0.2 s (46 s when every record built a page). - With a media sink, the builder keeps only the paths it stored, not the bytes; media_files holds the files only without a sink. - Each vendored Harbor module's first line names its source and says it was changed, as Apache-2.0 asks; vendor_atif.py writes it and the sha256 test takes it off before comparing. Harbor's models are in the protocol's and the repository's THIRD_PARTY_NOTICES.md. Co-Authored-By: Claude Opus 5.5 --- THIRD_PARTY_NOTICES.md | 17 ++++++++-- packages/agentenv-protocol/README.md | 5 +-- .../agentenv-protocol/THIRD_PARTY_NOTICES.md | 16 ++++++++-- .../src/agentenv_protocol/atif/builder.py | 32 ++++++++++++++----- .../agentenv_protocol/atif/models/VENDORED.md | 5 +-- .../agentenv_protocol/atif/models/__init__.py | 1 + .../agentenv_protocol/atif/models/agent.py | 1 + .../agentenv_protocol/atif/models/content.py | 1 + .../atif/models/final_metrics.py | 1 + .../agentenv_protocol/atif/models/metrics.py | 1 + .../atif/models/observation.py | 1 + .../atif/models/observation_result.py | 1 + .../src/agentenv_protocol/atif/models/step.py | 1 + .../atif/models/subagent_trajectory_ref.py | 1 + .../atif/models/tool_call.py | 1 + .../atif/models/trajectory.py | 1 + .../src/agentenv_protocol/atif/runner.py | 18 ++++------- .../agentenv-protocol/tests/atif_cases.py | 9 ++++-- .../tests/test_atif_builder.py | 17 +++++++--- .../tests/test_atif_vendored.py | 8 +++-- scripts/vendor_atif.py | 25 +++++++++------ 21 files changed, 116 insertions(+), 47 deletions(-) diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index 12ef9de6c..7acf9d941 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -2,8 +2,9 @@ This project is licensed under the Apache License, Version 2.0, but depends on third-party software identified below. These dependencies are installed separately from the Python Package -Index and imported at runtime. Apart from agent-env's changes to libfaketime, described below, third-party -source code is not incorporated into or statically linked with the source repository. +Index and imported at runtime. Apart from agent-env's changes to libfaketime and the protocol package's copy of +Harbor's ATIF models, both described below, third-party source code is not incorporated into or statically linked with +the source repository. Each third-party component remains subject to its applicable license. Copyright notices, license files, source-code offers, and other materials accompanying each component form part of its @@ -2556,6 +2557,18 @@ The folder's other files, like the rest of the repository, are licensed under th - Source: - License: GPL-2.0-only +## Harbor's ATIF models + +`packages/agentenv-protocol/src/agentenv_protocol/atif/models/` holds the trajectory models of [Harbor](https://github.com/harbor-framework/harbor) 0.26.0, the 11 modules +of its `harbor/models/trajectories/`, copied from Harbor's wheel on PyPI. Each copy's first line says where it's from +and that it was changed; the only change is its import paths. They are licensed as Harbor is, under the Apache License, +Version 2.0: the folder's `LICENSE` is the license file Harbor's wheel ships, which has no NOTICE file. The folder's +`VENDORED.md` records the wheel's sha256 and each upstream file's. + +- Source: (`harbor` 0.26.0 on PyPI) +- Author: Alex Shaw +- License: Apache-2.0 + ## The egress proxy's Go modules `src/agent_env/utils/egress_proxy/` is agent-env's egress proxy, a Go program the base diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index 289227b60..6a6e4e228 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1287,8 +1287,9 @@ the profile's spec, and `fixtures/` holds its canonical examples. The package ne record no method takes is counted in the root profile. - **The runner** (`AdapterRun`, `replay`) feeds one A2A context's records through one adapter instance, a task at a time. It writes each task's user step from its `TurnContext`, and the final response once, with the task's - terminal state on its last step. After every record it gives the live view: closed steps only, so a reader's earlier - page is always a prefix of a later one. + terminal state on its last step. Its `page()` is the live view, built when it's read: closed steps only, so a + reader's earlier page is always a prefix of a later one. A step is rendered once a page serves it and kept, so a + read costs one parse of the document, not a render of every step. - **Readers** (`load`, `tasks`, `media_paths`, `strip_profile`, `is_prefix`) take any valid ATIF document, with or without the profile, such as a Harbor task's trajectory.json. diff --git a/packages/agentenv-protocol/THIRD_PARTY_NOTICES.md b/packages/agentenv-protocol/THIRD_PARTY_NOTICES.md index 4126ccaca..1569a421c 100644 --- a/packages/agentenv-protocol/THIRD_PARTY_NOTICES.md +++ b/packages/agentenv-protocol/THIRD_PARTY_NOTICES.md @@ -2,8 +2,8 @@ This project is licensed under the Apache License, Version 2.0, but depends on third-party software identified below. These dependencies are installed separately from the Python Package -Index and imported at runtime. Third-party source code is not incorporated into or statically -linked with the source repository. +Index and imported at runtime. Apart from Harbor's ATIF models, described below, third-party source +code is not incorporated into or statically linked with the source repository. Each third-party component remains subject to its applicable license. Copyright notices, license files, source-code offers, and other materials accompanying each component form part of its @@ -254,6 +254,18 @@ The runtime dependencies of `agentenv-protocol` and its `agent` extra, at the ve - Source: - [License text 11](#license-text-11) +## Harbor's ATIF models + +`src/agentenv_protocol/atif/models/` holds the trajectory models of [Harbor](https://github.com/harbor-framework/harbor) 0.26.0, the 11 modules +of its `harbor/models/trajectories/`, copied from Harbor's wheel on PyPI. Each copy's first line says where it's from +and that it was changed; the only change is its import paths. They are licensed as Harbor is, under the Apache License, +Version 2.0: the folder's `LICENSE` is the license file Harbor's wheel ships, which has no NOTICE file. The folder's +`VENDORED.md` records the wheel's sha256 and each upstream file's. + +- Source: (`harbor` 0.26.0 on PyPI) +- Author: Alex Shaw +- License: Apache-2.0 + ## License texts License and notice files as shipped by each package, with copyright lines removed: they are listed with each package above. Packages whose files differ only in those lines share a text. diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py index 35ccc58c6..c90e0cbfa 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py @@ -216,6 +216,7 @@ class _Step: step_time: str | None = None closed: bool = False ended: bool = False + served: str | None = None @dataclass(eq=False) @@ -234,6 +235,7 @@ def __init__(self, spec: AdapterSpec, sink: Callable[[str, bytes], None] | None self.spec = spec self.media: dict[str, bytes] = {} self._sink = sink + self._stored: set[str] = set() self._root: _Trajectory | None = None self._subs: dict[str, _Trajectory] = {} self._call_home: dict[str, tuple[_Trajectory, _Step]] = {} @@ -394,10 +396,12 @@ def store(self, data: bytes, media_type: str, info: Mapping[str, Any]) -> Media: digest = hashlib.sha256(data).hexdigest() extension = _EXTENSIONS.get(media_type) or mimetypes.guess_extension(media_type, strict=False) or ".bin" path = f"media/{digest}{extension}" - if path not in self.media: - self.media[path] = bytes(data) + if path not in self._stored: + self._stored.add(path) if self._sink is not None: self._sink(path, bytes(data)) + else: + self.media[path] = bytes(data) details = {"sha256": digest, "bytes": len(data), **{k: v for k, v in info.items() if v is not None}} return Media(path, media_type, _json(details, "media details")) @@ -434,8 +438,8 @@ def document(self) -> dict[str, Any] | None: return self._render(closed_only=False) def page(self) -> dict[str, Any] | None: - """What a live reader is served: each trajectory's closed steps, up to the first one still waiting on a - result, or None while there are none.""" + """What a live reader is served, built when it's read: each trajectory's closed steps, up to the first one + still waiting on a result, or None while there are none.""" return self._render(closed_only=True) # Internals @@ -530,9 +534,9 @@ def _render(self, *, closed_only: bool) -> dict[str, Any] | None: linked = {actor for actor, count in counts.items() if actor is not None and count} doc: dict[str, Any] = {"schema_version": SCHEMA_VERSION, "session_id": self._context_id, "agent": dict(root.agent), - "steps": [_render_step(s, linked) for s in root.steps[:counts[None]]]} + "steps": _steps(root, counts[None], linked, closed_only)} subs = [{"schema_version": SCHEMA_VERSION, "trajectory_id": trajectory.actor, "agent": dict(trajectory.agent), - "steps": [_render_step(s, linked) for s in trajectory.steps[:counts[trajectory.actor]]]} + "steps": _steps(trajectory, counts[trajectory.actor], linked, closed_only)} for trajectory in self._subs.values() if counts[trajectory.actor]] if subs: doc["subagent_trajectories"] = subs @@ -586,7 +590,19 @@ def _message(parts: list[dict[str, Any]]) -> str | list[dict[str, Any]]: return [dict(part) for part in parts] -def _render_step(step: _Step, linked: set[str]) -> dict[str, Any]: +def _steps(trajectory: _Trajectory, count: int, linked: set[str], serving: bool) -> list[dict[str, Any]]: + """A trajectory's first ``count`` steps, as fresh copies. A step a page served never changes again, so its JSON is + rendered once and kept, and a read of a long document costs one parse rather than a render of every step.""" + texts = [] + for step in trajectory.steps[:count]: + text = step.served if step.served is not None else _step_json(step, linked) + if serving: + step.served = text + texts.append(text) + return json.loads(f"[{','.join(texts)}]") + + +def _step_json(step: _Step, linked: set[str]) -> str: agentic = step.source == "agent" out: dict[str, Any] = {"step_id": step.index + 1} when = step.step_time or step.time @@ -639,7 +655,7 @@ def _render_step(step: _Step, linked: set[str]) -> dict[str, Any]: ("data", b.get("data"))) if value is not None} for b in blocks] if profile: out["extra"] = {PROFILE_KEY: profile} - return json.loads(json.dumps(out)) + return json.dumps(out) class AtifTurn: diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/VENDORED.md b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/VENDORED.md index 99e986e0f..7d4a3ed31 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/VENDORED.md +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/VENDORED.md @@ -3,8 +3,9 @@ These files are Harbor's ATIF models, from `harbor/models/trajectories/` in the Harbor 0.26.0 release on PyPI (`harbor-0.26.0-py3-none-any.whl`, sha256 `b7c752c5b51ae2ee1fc2ea30621493c7dc0b5a3d0157295bed4552115027baee`). Harbor is Apache-2.0; `LICENSE` beside this file is the license that wheel ships. -The only change is import paths: each `from harbor.models.trajectories...` import reads `from agentenv_protocol.atif.models...`. Nothing else differs. A unit -test turns the imports back and checks each file's sha256 against the table below. +Each file has a first line naming its source and saying it was changed, and the only change is import paths: each +`from harbor.models.trajectories...` import reads `from agentenv_protocol.atif.models...`. Nothing else differs. A unit test takes off the first line, turns +the imports back and checks each file's sha256 against the table below. Refresh with `python scripts/vendor_atif.py ` from the repository root, then review the diff and the fixtures. diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/__init__.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/__init__.py index e8f939aab..828a77ac0 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/__init__.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/__init__.py @@ -1,3 +1,4 @@ +# From Harbor 0.26.0, harbor/models/trajectories/__init__.py (Apache-2.0), with its import paths changed: see VENDORED.md. """Pydantic models for Agent Trajectory Interchange Format (ATIF). This module provides Pydantic models for validating and constructing diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/agent.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/agent.py index 1f9cd992c..9806e5c9a 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/agent.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/agent.py @@ -1,3 +1,4 @@ +# From Harbor 0.26.0, harbor/models/trajectories/agent.py (Apache-2.0), with its import paths changed: see VENDORED.md. """Agent configuration model for ATIF trajectories.""" from typing import Any diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/content.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/content.py index ee092bdf0..e85f4e4f3 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/content.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/content.py @@ -1,3 +1,4 @@ +# From Harbor 0.26.0, harbor/models/trajectories/content.py (Apache-2.0), with its import paths changed: see VENDORED.md. """Content models for multimodal ATIF trajectories. Added in ATIF-v1.6 to support multimodal content (images) in trajectories. diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/final_metrics.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/final_metrics.py index a30c3fca2..054090cfc 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/final_metrics.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/final_metrics.py @@ -1,3 +1,4 @@ +# From Harbor 0.26.0, harbor/models/trajectories/final_metrics.py (Apache-2.0), with its import paths changed: see VENDORED.md. """Final metrics model for ATIF trajectories.""" from typing import Any diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/metrics.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/metrics.py index e79185d93..7d6737cd0 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/metrics.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/metrics.py @@ -1,3 +1,4 @@ +# From Harbor 0.26.0, harbor/models/trajectories/metrics.py (Apache-2.0), with its import paths changed: see VENDORED.md. """Metrics model for ATIF trajectories.""" from typing import Any diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/observation.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/observation.py index fb4896f4e..d6ddbb75a 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/observation.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/observation.py @@ -1,3 +1,4 @@ +# From Harbor 0.26.0, harbor/models/trajectories/observation.py (Apache-2.0), with its import paths changed: see VENDORED.md. """Observation model for ATIF trajectories.""" from pydantic import BaseModel, Field diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/observation_result.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/observation_result.py index e979954cb..387fa3059 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/observation_result.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/observation_result.py @@ -1,3 +1,4 @@ +# From Harbor 0.26.0, harbor/models/trajectories/observation_result.py (Apache-2.0), with its import paths changed: see VENDORED.md. """Observation result model for ATIF trajectories.""" from typing import Any diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/step.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/step.py index 7f52431e6..470034e80 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/step.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/step.py @@ -1,3 +1,4 @@ +# From Harbor 0.26.0, harbor/models/trajectories/step.py (Apache-2.0), with its import paths changed: see VENDORED.md. """Step model for ATIF trajectories.""" from datetime import datetime diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/subagent_trajectory_ref.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/subagent_trajectory_ref.py index f6fea9168..0267a965f 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/subagent_trajectory_ref.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/subagent_trajectory_ref.py @@ -1,3 +1,4 @@ +# From Harbor 0.26.0, harbor/models/trajectories/subagent_trajectory_ref.py (Apache-2.0), with its import paths changed: see VENDORED.md. """Subagent trajectory reference model for ATIF trajectories.""" from typing import Any diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/tool_call.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/tool_call.py index 2dd0d697b..59dc4b00d 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/tool_call.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/tool_call.py @@ -1,3 +1,4 @@ +# From Harbor 0.26.0, harbor/models/trajectories/tool_call.py (Apache-2.0), with its import paths changed: see VENDORED.md. """Tool call model for ATIF trajectories.""" from typing import Any diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/trajectory.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/trajectory.py index 53e1d478c..3d48b3a05 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/models/trajectory.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/models/trajectory.py @@ -1,3 +1,4 @@ +# From Harbor 0.26.0, harbor/models/trajectories/trajectory.py (Apache-2.0), with its import paths changed: see VENDORED.md. """Trajectory model for ATIF (Agent Trajectory Interchange Format).""" from typing import Any, Literal diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/runner.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/runner.py index 2443469bf..4097ad66e 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/runner.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/runner.py @@ -33,9 +33,9 @@ class RecordedTask: class AdapterRun: - """One A2A context's conversion. Each call returns the live view after it, the closed steps a reader may be - served; ``document`` is everything so far. Every read is a fresh copy. ``media`` receives each media file once, - as ``(path, bytes)``; the files are also kept in ``media_files``.""" + """One A2A context's conversion. ``page`` is the live view, the closed steps a reader may be served, built when + it's read; ``document`` is everything so far. Every read is a fresh copy. ``media`` receives each media file once, + as ``(path, bytes)``; without it, the files are kept in ``media_files``.""" def __init__(self, adapter: type[Adapter], *, media: Callable[[str, bytes], None] | None = None) -> None: spec = vars(adapter).get("spec") @@ -64,7 +64,7 @@ def document(self) -> dict[str, Any] | None: def page(self) -> dict[str, Any] | None: return self._doc.page() - def start_task(self, context: TurnContext) -> dict[str, Any] | None: + def start_task(self, context: TurnContext) -> None: """Open a task and write its user step. The context's first task creates the adapter.""" if self._turn is not None: raise AtifError(f"task {self._turn.context.task_id} is still open") @@ -72,16 +72,14 @@ def start_task(self, context: TurnContext) -> dict[str, Any] | None: self._turn = turn if self._adapter is None: self._adapter = self._cls(turn) - return self.page() - def native(self, record: Any) -> dict[str, Any] | None: + def native(self, record: Any) -> None: """Feed the task's next native record.""" turn = self._open() method = self._spec.handler(None, record) or "unmatched" getattr(self._adapter, method)(record, turn) - return self.page() - def aux(self, name: str, record: Any) -> dict[str, Any] | None: + def aux(self, name: str, record: Any) -> None: """Feed the task's next record of aux file ``name``.""" turn = self._open() if name not in self._spec.aux: @@ -89,10 +87,9 @@ def aux(self, name: str, record: Any) -> dict[str, Any] | None: method = self._spec.handler(name, record) if method is not None: getattr(self._adapter, method)(record, turn) - return self.page() def end_task(self, *, state: str = "completed", final: Sequence[Any] | None = None, - ended_at: str | datetime | None = None) -> dict[str, Any] | None: + ended_at: str | datetime | None = None) -> None: """Close the task: run the adapter's ``@finish``, then write the final response, once, and the task's terminal state on its last step. The task is closed even when ``@finish`` raises, and the error is raised after.""" @@ -103,7 +100,6 @@ def end_task(self, *, state: str = "completed", final: Sequence[Any] | None = No finally: self._doc.end_task(state=state, final=final, ended_at=ended_at) self._turn = None - return self.page() def _open(self) -> AtifTurn: if self._turn is None: diff --git a/packages/agentenv-protocol/tests/atif_cases.py b/packages/agentenv-protocol/tests/atif_cases.py index 169846f6b..567face52 100644 --- a/packages/agentenv-protocol/tests/atif_cases.py +++ b/packages/agentenv-protocol/tests/atif_cases.py @@ -227,10 +227,13 @@ def build(name: str) -> tuple[dict[str, Any], list[dict[str, Any] | None], dict[ inbound += [run.media(label.encode(), media_type, **info) for label, media_type, info in task.inbound_media] if task.inbound_media and name == "odd_parts": inbound.append({"type": "text", "text": json.dumps({"ticket": 4411, "priority": "high"})}) - pages.append(run.start_task(TurnContext(inbound=inbound, **context))) + run.start_task(TurnContext(inbound=inbound, **context)) + pages.append(run.page()) for record in task.records: - pages.append(run.native(record)) - pages.append(run.end_task(state=task.state, final=task.final, ended_at=task.ended_at)) + run.native(record) + pages.append(run.page()) + run.end_task(state=task.state, final=task.final, ended_at=task.ended_at) + pages.append(run.page()) document = run.document() assert document is not None return document, pages, run.media_files diff --git a/packages/agentenv-protocol/tests/test_atif_builder.py b/packages/agentenv-protocol/tests/test_atif_builder.py index 372cf7562..f4e3675f7 100644 --- a/packages/agentenv-protocol/tests/test_atif_builder.py +++ b/packages/agentenv-protocol/tests/test_atif_builder.py @@ -53,8 +53,13 @@ def usage(self, r, turn): def run_task(records, *, final=None, state="completed", cls=None): run = AdapterRun(cls or adapter()) - pages = [run.start_task(CTX)] + [run.native(r) for r in records] - pages.append(run.end_task(final=final, state=state, ended_at="2026-11-18T10:05:00Z")) + run.start_task(CTX) + pages = [run.page()] + for record in records: + run.native(record) + pages.append(run.page()) + run.end_task(final=final, state=state, ended_at="2026-11-18T10:05:00Z") + pages.append(run.page()) return run, pages @@ -215,7 +220,7 @@ def shot(self, r, turn): check(document) png, mp4 = (r["observation"]["results"][0] for r in document["steps"][1::2]) path = png["content"][0]["source"]["path"] - assert path.startswith("media/") and path.endswith(".png") and len(sunk) == 2 + assert path.startswith("media/") and path.endswith(".png") and len(sunk) == 2 and run.media_files == {} assert profile_of(png)["media"][path] == {"sha256": path[6:-4], "bytes": 4, "width": 2, "height": 1} assert mp4["content"].startswith("[video: media/") and mp4["content"].endswith(", 4 B]") assert list(profile_of(mp4)["media"].values())[0]["media_type"] == "video/mp4" @@ -519,8 +524,10 @@ def test_a_live_page_shows_a_pointer_only_with_a_step_of_its_sub_agent(): {"type": "sub", "step": "x1", "agent": "sub"}, {"type": "result", "id": "c1"}, {"type": "say", "step": "p2", "text": "next"}, {"type": "say", "step": "p3", "text": "more"}, {"type": "sub", "step": "x2", "agent": "sub"}]: - pages.append(run.native(record)) - pages.append(run.end_task()) + run.native(record) + pages.append(run.page()) + run.end_task() + pages.append(run.page()) assert [len(p["steps"]) if p else 0 for p in pages] == [1, 1, 1, 1, 1, 1, 3, 4] for page in filter(None, pages): trajectories = {sub["trajectory_id"] for sub in page.get("subagent_trajectories") or []} diff --git a/packages/agentenv-protocol/tests/test_atif_vendored.py b/packages/agentenv-protocol/tests/test_atif_vendored.py index 08d54b8dc..51a88944b 100644 --- a/packages/agentenv-protocol/tests/test_atif_vendored.py +++ b/packages/agentenv-protocol/tests/test_atif_vendored.py @@ -12,6 +12,8 @@ MODELS = files("agentenv_protocol.atif.models") LOCAL_IMPORT = re.compile(r"^(\s*(?:from|import)\s+)agentenv_protocol\.atif\.models\b", re.M) +HEADER = re.compile(r"\A# From Harbor 0\.26\.0, harbor/models/trajectories/(\S+) \(Apache-2\.0\), with its import paths " + r"changed: see VENDORED\.md\.\n") def recorded() -> dict[str, str]: @@ -19,13 +21,15 @@ def recorded() -> dict[str, str]: return dict(re.findall(r"^\| `([^`]+\.py)` \| `([0-9a-f]{64})` \|$", table, re.M)) -def test_the_vendored_files_differ_from_harbors_only_in_import_paths(): +def test_the_vendored_files_say_they_were_changed_and_differ_from_harbors_only_in_import_paths(): shipped = {p.name for p in MODELS.iterdir() if p.name.endswith(".py")} assert shipped == set(recorded()) and len(shipped) == 11 for name, digest in recorded().items(): text = MODELS.joinpath(name).read_text(encoding="utf-8") + header = HEADER.match(text) + assert header and header.group(1) == name, name assert "harbor" not in "".join(line for line in text.splitlines() if line.lstrip().startswith(("from", "import"))) - upstream = LOCAL_IMPORT.sub(r"\g<1>harbor.models.trajectories", text) + upstream = LOCAL_IMPORT.sub(r"\g<1>harbor.models.trajectories", text[header.end():]) assert hashlib.sha256(upstream.encode("utf-8")).hexdigest() == digest, name diff --git a/scripts/vendor_atif.py b/scripts/vendor_atif.py index f2090a425..a149bfa86 100644 --- a/scripts/vendor_atif.py +++ b/scripts/vendor_atif.py @@ -4,9 +4,10 @@ python scripts/vendor_atif.py 0.26.0 [--check] It downloads that release's wheel, takes the modules under harbor/models/trajectories, rewrites their imports of -harbor.models.trajectories to agentenv_protocol.atif.models and changes nothing else, and writes them with VENDORED.md, -which records each upstream file's sha256 so a unit test can check offline that the copies differ from Harbor's only in -import paths. ``--check`` compares instead of writing and exits 1 on any difference.""" +harbor.models.trajectories to agentenv_protocol.atif.models, puts a first line on each saying where it's from and that it +was changed, as Apache-2.0 asks, and changes nothing else. It writes them with VENDORED.md, which records each upstream +file's sha256 so a unit test can check offline that the copies differ from Harbor's only in that line and the import +paths. ``--check`` compares instead of writing and exits 1 on any difference.""" from __future__ import annotations import argparse @@ -25,16 +26,19 @@ DEST = Path(__file__).resolve().parents[1] / "packages/agentenv-protocol/src/agentenv_protocol/atif/models" _IMPORT = re.compile(r"^(\s*(?:from|import)\s+)" + re.escape(UPSTREAM) + r"\b", re.M) _LOCAL_IMPORT = re.compile(r"^(\s*(?:from|import)\s+)" + re.escape(LOCAL) + r"\b", re.M) +_HEADER = re.compile(r"\A# From Harbor [^\n]*\n") -def localize(text: str) -> str: - """Harbor's module text with its imports of the trajectory models pointed at the vendored copy.""" - return _IMPORT.sub(r"\g<1>" + LOCAL, text) +def localize(text: str, name: str, version: str) -> str: + """Harbor's module text with its imports of the trajectory models pointed at the vendored copy, under a first line + naming its source and the change.""" + header = f"# From Harbor {version}, {SOURCE}{name} (Apache-2.0), with its import paths changed: see VENDORED.md.\n" + return header + _IMPORT.sub(r"\g<1>" + LOCAL, text) def upstream(text: str) -> str: """A vendored module's text as Harbor wrote it: the inverse of ``localize``.""" - return _LOCAL_IMPORT.sub(r"\g<1>" + UPSTREAM, text) + return _LOCAL_IMPORT.sub(r"\g<1>" + UPSTREAM, _HEADER.sub("", text)) def _get(url: str) -> bytes: @@ -70,8 +74,9 @@ def vendored_md(version: str, wheel: str, digest: str, files: dict[str, str]) -> These files are Harbor's ATIF models, from `{SOURCE}` in the Harbor {version} release on PyPI (`{wheel}`, sha256 `{digest}`). Harbor is Apache-2.0; `LICENSE` beside this file is the license that wheel ships. -The only change is import paths: each `from {UPSTREAM}...` import reads `from {LOCAL}...`. Nothing else differs. A unit -test turns the imports back and checks each file's sha256 against the table below. +Each file has a first line naming its source and saying it was changed, and the only change is import paths: each +`from {UPSTREAM}...` import reads `from {LOCAL}...`. Nothing else differs. A unit test takes off the first line, turns +the imports back and checks each file's sha256 against the table below. Refresh with `python scripts/vendor_atif.py ` from the repository root, then review the diff and the fixtures. @@ -87,7 +92,7 @@ def main() -> int: parser.add_argument("--check", action="store_true", help="compare with the checked-in copy instead of writing") args = parser.parse_args() wheel, digest, files, license_text = fetch(args.version) - wanted = {name: localize(text) for name, text in files.items()} + wanted = {name: localize(text, name, args.version) for name, text in files.items()} wanted["VENDORED.md"] = vendored_md(args.version, wheel, digest, files) wanted["LICENSE"] = license_text if args.check: From 405a0e0dbdd5798966f8c93b2d7b25bb81486a0d Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 11:36:37 -0800 Subject: [PATCH 7/7] fix(protocol): a media file the sink failed to take is handed to it again, and millisecond conversions are named Co-Authored-By: Claude Opus 5.5 --- .../src/agentenv_protocol/atif/builder.py | 10 ++++++---- .../tests/test_atif_builder.py | 18 ++++++++++++++++++ 2 files changed, 24 insertions(+), 4 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py b/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py index c90e0cbfa..ec43fda52 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/builder.py @@ -46,6 +46,8 @@ _UNSET: Any = object() _KILOBYTE = 1000 _MEGABYTE = 1_000_000 +_MS_PER_SECOND = 1000 +_US_PER_MS = 1000 _PROMPT_PARTS = ("input", "cache_read", "cache_write") @@ -73,7 +75,7 @@ def timestamp(value: str | datetime | None) -> str | None: text = (f"{moment.year:04d}-{moment.month:02d}-{moment.day:02d}T{moment.hour:02d}:{moment.minute:02d}:" f"{moment.second:02d}") if digits: - text += f".{moment.microsecond // 1000:03d}" if len(digits) <= 3 else f".{moment.microsecond:06d}" + text += f".{moment.microsecond // _US_PER_MS:03d}" if len(digits) <= 3 else f".{moment.microsecond:06d}" return text + "Z" @@ -156,14 +158,14 @@ def part(self) -> dict[str, Any]: if self.media_type in AUDIO_TYPES: source: dict[str, Any] = {"media_type": self.media_type, "path": self.path} if self.info.get("duration_ms") is not None: - source["duration_sec"] = self.info["duration_ms"] / 1000 + source["duration_sec"] = self.info["duration_ms"] / _MS_PER_SECOND return {"type": "audio", "source": source} major = self.media_type.split("/", 1)[0] kind = major if major in ("image", "audio", "video") else ( "document" if self.media_type == "application/pdf" else "file") details = [self.path, _size(self.info["bytes"])] if self.info.get("duration_ms") is not None: - details.append(f"{round(self.info['duration_ms'] / 1000)} s") + details.append(f"{round(self.info['duration_ms'] / _MS_PER_SECOND)} s") if self.info.get("pages") is not None: details.append(f"{self.info['pages']} pages") return {"type": "text", "text": f"[{kind}: {', '.join(details)}]"} @@ -397,11 +399,11 @@ def store(self, data: bytes, media_type: str, info: Mapping[str, Any]) -> Media: extension = _EXTENSIONS.get(media_type) or mimetypes.guess_extension(media_type, strict=False) or ".bin" path = f"media/{digest}{extension}" if path not in self._stored: - self._stored.add(path) if self._sink is not None: self._sink(path, bytes(data)) else: self.media[path] = bytes(data) + self._stored.add(path) details = {"sha256": digest, "bytes": len(data), **{k: v for k, v in info.items() if v is not None}} return Media(path, media_type, _json(details, "media details")) diff --git a/packages/agentenv-protocol/tests/test_atif_builder.py b/packages/agentenv-protocol/tests/test_atif_builder.py index f4e3675f7..b4a349d30 100644 --- a/packages/agentenv-protocol/tests/test_atif_builder.py +++ b/packages/agentenv-protocol/tests/test_atif_builder.py @@ -552,3 +552,21 @@ def test_a_sub_agent_is_spawned_by_a_call_of_its_task_waiting_on_its_result_and_ run.start_task(TurnContext(index=1, context_id="ctx", task_id="t2", inbound=["more"])) with pytest.raises(AtifError, match="earlier task"): run.native({"type": "sub", "step": "x1", "agent": "sub"}) + + +def test_a_file_the_sink_failed_to_take_is_handed_to_it_again(): + taken = [] + + def sink(path, data): + if not taken: + taken.append(None) + raise OSError("disk full") + taken.append(path) + + run = AdapterRun(adapter(), media=sink) + run.start_task(CTX) + with pytest.raises(OSError): + run.media(b"shot", "image/png") + media = run.media(b"shot", "image/png") + run.media(b"shot", "image/png") + assert taken == [None, media.path]