Skip to content

feat(protocol): ATIF in agentenv_protocol: Harbor's models vendored, the agentenv profile and the adapter framework (Y1a, FD-6075) - #778

Merged
earakely-scale merged 7 commits into
mainfrom
edgararakelyan/fd-6075-y1a-atif
Nov 18, 2026
Merged

earakely-scale merged 7 commits into
mainfrom
edgararakelyan/fd-6075-y1a-atif

Conversation

@earakely-scale

@earakely-scale earakely-scale commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

agentenv now records agent trajectories as ATIF v1.8, Harbor's format, with an optional extra.agentenv profile. This replaces the yatf/1 plan of the closed #748 (FD-6074, Decision 7). This PR is Y1a (FD-6075):

  • Harbor's ATIF models, vendored;
  • the profile;
  • the adapter framework that writes ATIF steps;
  • reader helpers;
  • the profile's canonical fixtures.

Nothing reads or serves ATIF yet. The validator, its CLI and the adapter kit are Y1b, and the SDK serving atif/1 is Y2b.

What changes

New package agentenv_protocol.atif. It needs only the protocol's base dependencies, and imports nothing from a2a_agent.

  • atif/models/: Harbor 0.26.0's 11 model files, vendored.
    • The only change is import paths. Each file's first line names its source and says it was changed, as Apache-2.0 asks.
    • LICENSE is the license Harbor's wheel ships (Apache-2.0; the wheel has no NOTICE). VENDORED.md records the source wheel and each upstream file's sha256.
    • Harbor is listed in the protocol's and the repository's THIRD_PARTY_NOTICES.md, whose "no third-party source in the repository" sentence now names this exception.
    • scripts/vendor_atif.py <version> re-vendors them from a named release on PyPI; --check compares instead of writing.
    • Harbor itself can't be a dependency: it needs Python 3.12, pydantic 2.14 and 27 base dependencies.
  • atif/profile.py and atif/PROFILE.md: profile 1.0.
    • The rule: typed fields mean exactly what ATIF says, and a document without extra.agentenv is still correct ATIF that means the same.
    • Every profile field is optional. The models are tolerant and keep unknown keys.
    • The fields:
      • on a task's user step, its A2A ids and turn index;
      • on a task's last step, its terminal state;
      • on the root, the native format and the adapter;
      • the attempt number, and step errors;
      • reasoning blocks (each block's length, visibility, signature and ciphertext);
      • media details, keyed by path;
      • result status and exit code, and a late result's arrival;
      • cost_source and cache_write_tokens;
      • the unmatched-record count.
  • atif/adapter.py: the authoring API, carried over from feat(protocol): yatf/1's spec, models, reader and adapter framework (Y1a, FD-6075) #748.
    • @atif_adapter(native_format=, version=, input_includes_cache=, tested_with=), with @native, @aux and @finish.
    • from_atif returns Native(log, session) on a best-effort basis.
  • atif/builder.py: the typed step builder.
    • It holds each trajectory's open step and closes it when the next one starts.
    • A result always lands in its call's step. A late one records when it arrived.
    • It writes prompt_tokens with the cache included, using the adapter's constant. Cache writes go in the profile. A step's counts may come over several records: each is the latest given, and prompt_tokens is written once the input count is known.
    • final_metrics totals a count or cost only when every model step has it, so a total is never a partial sum.
    • It embeds sub-agents as trajectories referenced from the spawning call's result. A sub-agent belongs to its spawning call's task. One that wrote no step is left out with its reference, so every reference resolves.
    • It stores media at media/<sha256>.<ext>, with a plain note for types ATIF has no part for. With a sink, it hands each file over once and keeps only its path.
    • It wraps non-object tool arguments as Harbor does, keeping raw_arguments.
    • It normalizes timestamps to UTC, with 3 or 6 fractional digits.
    • Before touching the document, it refuses: values that aren't JSON or of the wrong type; duplicate call ids; results for no call; a second result for a call; and a result after its task ended.
  • atif/runner.py: AdapterRun and replay.
    • One adapter instance per A2A context.
    • Each task's user step comes from its TurnContext.
    • The final response is written once, and the terminal state goes on the task's last step.
    • page() is the live view, built when it's read: closed steps only. A step waiting on a result, or referencing a sub-agent the view shows no step of yet, holds back the steps after it until the task ends. Everything served is a prefix of every later read.
    • A served step never changes, so its JSON is rendered once and kept. Feeding 2,000 steps with a page every 50 takes 0.2 s, and a page at 2,000 steps takes 8 ms.
  • atif/reader.py: load, check, tasks, media_paths, strip_profile and is_prefix, for any valid ATIF document, with or without the profile. strip_profile removes extra.agentenv only from the ATIF objects that own an extra, so tool arguments keep theirs.
  • atif/fixtures/: the profile's seven canonical cases: coding, computer use, late result, multi-agent, odd parts, sub-agent and two turns. They're built through the framework from a toy format's records (tests/atif_cases.py). Their media and a copy of the coding case without the profile sit beside them.
  • README: a new "Agent trajectories: ATIF" section.

Decisions it rests on

  • FD-6074 Decisions 7 to 19, written into the Linear issues on 2026-11-18. Among them:
    • the profile only adds;
    • results stay in their call's step;
    • text output inline, whole;
    • media at media/<sha256>.<ext>;
    • one document per context, with segments;
    • the models vendored.
  • Y1a's own decisions, taken 2026-11-18:
    • profile 1.0's field set;
    • harness costs in the typed fields, with cost_source saying whose;
    • cache_write_tokens in the profile;
    • per-part data keyed by media path;
    • unmatched records counted, not kept;
    • Harbor's wrapping for non-object arguments;
    • reasoning blocks joined, with each block's length;
    • the module layout;
    • the final response written once, with the terminal state on the task's last step.

How it was checked

  • New tests: 110, in tests/test_atif_*.py, all offline.

    • They cover every Y1a done-when item, and each bug chaos or review found (below).
    • One checks the vendored files equal Harbor's once the imports are turned back, by sha256.
  • Protocol suite: pytest packages/agentenv-protocol/tests gives 1764 passed, 1 skipped (the skip was already there). ruff check is clean.

  • E2E and chaos on two admin VMs, x86_64 (m8i.2xlarge) and arm64 (m8g.2xlarge), from the built wheel with only the protocol's base dependencies. Each host ran Python 3.10, 3.11, 3.12 and 3.13, each with pydantic at the floor (2.11.10) and the latest (2.14.3), and on each:

    • the ATIF tests, against the installed wheel;

    • e2e on real data. Two recorded claude -p sessions in stream-json, one with a thinking block whose text was withheld, go through a Claude Code adapter written with the framework, as one context with two tasks. The run checks:

      • the document, its stripped copy and every live page validate;
      • every page is a prefix of the final document;
      • the tasks slice back out;
      • every call's result is in its step;
      • the withheld block's signature is kept;
      • the harness's cost reaches final_metrics.
    • chaos for 240 s. Random task scripts, with every argument's type and value fuzzed. After every record it checks:

      • only AtifError escapes;
      • every page and document is valid ATIF, survives to_json_dict unchanged, and its profiles parse;
      • everything served stays a prefix;
      • every sub-agent reference resolves;
      • cache counts fit in the prompt tokens;
      • each total is there exactly when every model step has its count.

      At the end it checks that each step's usage matches an independent sum of the counts given, that stripping keeps every tool call's arguments, that the tasks slice, that the media are stored, and that a replay builds the same document.

    • with Harbor 0.26.0 itself, on Python 3.12. The e2e document validates with Harbor's models and survives its to_json_dict unchanged; it also feeds Harbor's SFT exporter and its Claude Code resume. Harbor's own ATIF of a real session reads with these readers.

    Results:

    • 3687074: all 16 combinations and both Harbor runs passed. Chaos ran 161,282 scripts and 8,081,244 records with 0 failures.
    • 7ebe40e, with the new invariants: all 16 combinations (109 tests each) and both Harbor runs passed. Chaos ran 182,478 scripts and 9,129,497 records with 0 failures.
    • 5708f37, on arm64 only: all 8 combinations and the Harbor run passed. Chaos ran 158,296 scripts and 7,920,638 records with 0 failures. The x86 host was in use by another session, and this commit's changes are pure Python, so it was left alone.
  • What chaos and review found, each fixed with a regression test:

    • c479d4e, found by chaos:

      • timestamps out of range in UTC raised OverflowError, and years before 1000 lost digits;
      • a refused task start left a task half open;
      • values of the wrong type made invalid documents;
      • a second result for a call, or one after its task ended, changed a served step.
    • 7ebe40e, found by Greptile:

      • usage given over several records overwrote earlier counts;
      • totals skipped model steps that had no usage;
      • a sub-agent with no step left a reference to nothing;
      • strip_profile removed extra.agentenv inside tool arguments.

      Chaos had no invariant for these. It has them now, and they fail on the code before the fix.

    • 5708f37, found in self-review:

      • the runner built a whole page after every record: 46 s for a 2,000-step session, 58 ms for each record at the end;
      • media handed to a sink were also kept in memory;
      • the vendored files lacked Apache-2.0's change notice, and Harbor was missing from the notices files.
    • 405a0e0, found by Greptile: a media file the sink failed to take was skipped when written again; the millisecond conversions are named. A two-line change, checked with the ATIF tests and a local chaos run, not on the VMs.

  • Re-vendor check: python scripts/vendor_atif.py 0.26.0 --check reports "11 modules from harbor-0.26.0-py3-none-any.whl: match".

  • Fixtures:

    • every fixture validates with and without its profile;
    • every fixture survives the vendored Trajectory.to_json_dict() unchanged;
    • every live page validates and is a prefix of the final document;
    • the stripped copy slices into the same tasks.
  • Wheel: built with uv 0.13.1, it ships PROFILE.md, LICENSE, VENDORED.md, the fixtures and their media. The tests read the fixtures through importlib.resources, so they run against the installed wheel.

  • Before writing this, a spike validated the approach with Harbor 0.26.0 itself, not just the vendored copy (FD-6074, Decision 7). ATIF plus a profile was lossless on these seven cases. The documents survived Harbor's own load and save, and fed Harbor's SFT exporter and Claude Code resume.

  • Cost of the checks: about $0.46 for the two claude -p sessions, and about $0.50 of VM time (two 2xlarge hosts for 25 minutes, and arm64 again for 5, stopped after).

Notes for reviewers

  • Terminal state names. They're A2A's own terminal states: completed, failed, canceled, rejected. Y1's text said "completed, failed, canceled, raised, or failed before it started": "raised" is A2A's failed, and "failed before it started" is rejected.
  • Deliberate refusals by the builder:
    • A naive timestamp (no zone) is refused rather than assumed UTC.
    • A result for a call it never saw is refused, since ATIF puts a result in its call's step.
    • A result after its task ended is refused, since that task's steps have been served.
    • A sub-agent is spawned by a call of the open task still waiting on its result, and writes only in that task. A sub-agent's steps written later couldn't get a reference without changing a served step.
    • With input_includes_cache, cache counts over the input count are refused, since ATIF's cached_tokens is a subset of prompt_tokens.
  • Linear wording. Y1's Linear text puts the terminal state on the user step. Y1a's decision 9 moved it to the task's last step, because the live view serves the user step before the state is known. The issue text is patched to match.

Not in this PR

  • Y1b: the validator, its CLI and the adapter kit.
  • Y2a and Y2b: the card's formats, and the SDK serving atif/1.
  • The griffe gate for agentenv_protocol is FD-6178, not yet landed. Whichever lands second adds agentenv_protocol.atif to the gated surface.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 5/5

The reviewed update appears safe to merge; no new actionable issues were found.

Summary

Adds ATIF trajectory models, an optional agentenv profile, adapter and builder APIs, reader helpers, and canonical fixtures.

  • Adapters turn native agent records into typed ATIF steps.
  • Live runs expose closed ATIF steps, and recorded runs can be replayed.
  • Readers accept ATIF documents with or without the agentenv profile.

Reviews (10) · Last reviewed commit: "fix(protocol): a media file the sink fai..." · Reviewed by Greptile

…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/<sha256>.<ext>, 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 <noreply@anthropic.com>
@earakely-scale
earakely-scale requested a review from a team as a code owner November 18, 2026 17:39
….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 <noreply@anthropic.com>
earakely-scale and others added 4 commits November 18, 2026 09:59
…ep 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 <noreply@anthropic.com>
…lled

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…t, 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 <noreply@anthropic.com>
…e, 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 <noreply@anthropic.com>
…gain, and millisecond conversions are named

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale merged commit 25d4f40 into main Nov 18, 2026
39 checks passed
@earakely-scale
earakely-scale deleted the edgararakelyan/fd-6075-y1a-atif branch November 18, 2026 21:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant