Repository navigation
feat(protocol): ATIF in agentenv_protocol: Harbor's models vendored, the agentenv profile and the adapter framework (Y1a, FD-6075) - #778
Merged
Conversation
…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>
….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>
…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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
agentenv now records agent trajectories as ATIF v1.8, Harbor's format, with an optional
extra.agentenvprofile. This replaces the yatf/1 plan of the closed #748 (FD-6074, Decision 7). This PR is Y1a (FD-6075):Nothing reads or serves ATIF yet. The validator, its CLI and the adapter kit are Y1b, and the SDK serving
atif/1is Y2b.What changes
New package
agentenv_protocol.atif. It needs only the protocol's base dependencies, and imports nothing froma2a_agent.atif/models/: Harbor 0.26.0's 11 model files, vendored.LICENSEis the license Harbor's wheel ships (Apache-2.0; the wheel has no NOTICE).VENDORED.mdrecords the source wheel and each upstream file's sha256.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;--checkcompares instead of writing.atif/profile.pyandatif/PROFILE.md: profile 1.0.extra.agentenvis still correct ATIF that means the same.cost_sourceandcache_write_tokens;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,@auxand@finish.from_atifreturnsNative(log, session)on a best-effort basis.atif/builder.py: the typed step builder.prompt_tokenswith 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, andprompt_tokensis written once the input count is known.final_metricstotals a count or cost only when every model step has it, so a total is never a partial sum.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.raw_arguments.atif/runner.py:AdapterRunandreplay.TurnContext.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.atif/reader.py:load,check,tasks,media_paths,strip_profileandis_prefix, for any valid ATIF document, with or without the profile.strip_profileremovesextra.agentenvonly from the ATIF objects that own anextra, 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.Decisions it rests on
media/<sha256>.<ext>;cost_sourcesaying whose;cache_write_tokensin the profile;How it was checked
New tests: 110, in
tests/test_atif_*.py, all offline.Protocol suite:
pytest packages/agentenv-protocol/testsgives 1764 passed, 1 skipped (the skip was already there).ruff checkis 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 -psessions 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:final_metrics.chaos for 240 s. Random task scripts, with every argument's type and value fuzzed. After every record it checks:
AtifErrorescapes;to_json_dictunchanged, and its profiles parse;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_dictunchanged; 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:
What chaos and review found, each fixed with a regression test:
c479d4e, found by chaos:
OverflowError, and years before 1000 lost digits;7ebe40e, found by Greptile:
strip_profileremovedextra.agentenvinside 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:
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 --checkreports "11 modules from harbor-0.26.0-py3-none-any.whl: match".Fixtures:
Trajectory.to_json_dict()unchanged;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 -psessions, and about $0.50 of VM time (two 2xlarge hosts for 25 minutes, and arm64 again for 5, stopped after).Notes for reviewers
completed,failed,canceled,rejected. Y1's text said "completed, failed, canceled, raised, or failed before it started": "raised" is A2A'sfailed, and "failed before it started" isrejected.input_includes_cache, cache counts over the input count are refused, since ATIF'scached_tokensis a subset ofprompt_tokens.Not in this PR
atif/1.agentenv_protocolis FD-6178, not yet landed. Whichever lands second addsagentenv_protocol.atifto the gated surface.🤖 Generated with Claude Code


Confidence 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.
Reviews (10) · Last reviewed commit: "fix(protocol): a media file the sink fai..." · Reviewed by Greptile