Skip to content

feat(protocol): the SDK serves atif/1 from an agent's ATIF adapter - #807

Merged
earakely-scale merged 7 commits into
mainfrom
edgararakelyan/y2b-serve-atif
Nov 19, 2026
Merged

earakely-scale merged 7 commits into
mainfrom
edgararakelyan/y2b-serve-atif

Conversation

@earakely-scale

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

Copy link
Copy Markdown
Collaborator

The first of Y2b's three PRs for FD-6076: the agent SDK serves atif/1 beside an agent's native trajectory, built live from an ATIF adapter the agent names. Part of FD-6076. The turn index's persistence (Y2b-2) and scrubbing (Y2b-4) follow in their own PRs.

What changes

  • enable(TRAJECTORY_V1, native=..., atif=MyAdapter) names an @atif_adapter class for the native format. An adapter for another format, or one with no native, is refused at enable. The card's formats lists atif/1 beside the native format; default stays native.
  • One ATIF document per A2A context, run through one adapter instance. Every event the agent appends feeds it as it's appended. A native trajectory returned at task end runs through the adapter then, so pi-style agents get a copy too.
    • request.trajectory.aux(name, record) feeds the adapter's aux files: records that aren't in the native log, such as a hook's notes.
    • An agent with an adapter that both appends and returns fails the turn with framework.trajectory_appended_and_returned (Y2b-3). Agents without an adapter keep today's rule.
  • What the SDK writes (Y2b-1, Y2b-6):
    • session_id is the A2A context id, and a fresh trajectory_id names each document.
    • Each task's user step holds the inbound message; its profile holds the A2A ids and the turn index.
    • A DataPart in the inbound message, and a final response's structured_output, are written as their compact JSON text. Other DataParts in the final response go in the last step's new data profile field.
    • A task's error goes on its last step. File parts with bytes become media; a file part by URI becomes a note, with the URI's query dropped.
  • Reads naming atif/1 are served by the SDK, including context reads an agent binds to its own handler (Claude Code and Codex bind them). Every answer names format, schema_version and profile_version.
    • A task read is the document as it stood when the task ended, with aux, the task's aux log, and turn_context, its TurnContext and how it ended (Y2b-5, Y2b-7). The objects form takes aux and turn_context as optional grants; other reads refuse them.
    • A context read is the live page: closed steps whose calls are all answered.
    • Cursor reads page those steps by step_id, each page with the document's header and the subagents of its tasks.
  • An adapter that raises stops its context's copy, never the turn. That copy's reads answer 409 atif_unavailable; native reads are unaffected.
  • Native reads keep exactly today's bodies, with or without an adapter.
  • In agentenv_protocol.atif:
    • ServedTurn and AuxEntry (atif/served.py) are the shapes the final read serves as turn_context and aux. RecordedTask.from_served validates them, so replay rebuilds the served document offline.
    • AdapterRun.document(through=k) gives the document as task k left it.
    • The task's data and error are written at end_task.
    • A spawning call left without a result when its task ends now gets a canceled result, so its sub-agent stays referenced. This was the gap Y1b's chaos testing found.

Choices to review

  • Cursor pages carry their tasks' sub-agents, as far as each is served. This corrects Y2b-7. That decision said a page carries the sub-agents its steps reference, complete, since a spawning step is served only once its call is answered. The serving chaos test showed that premise is false: an adapter can keep writing a sub-agent's steps after the spawning call's result.
    • The steps already served never change, but the sub-agent grows, and a reader that got it on an early page would never see the rest.
    • A page now carries the sub-agents of every task its steps belong to. A task's last step closes only as the task ends, so the page serving it carries the task's sub-agents whole. Readers keep each sub-agent's latest copy.
    • The decision's intent holds: pages stand alone, and the last page's header, every page's steps and the latest sub-agents rebuild the document. FD-6076 and the decisions log record the correction.
  • One clock per document. An agent that follows the env's clock runs its programs on universe time while its server stays on real time. The steps the SDK writes now take the programs' time, from the follower's clock file (computer.clock.session_time()), so they match the adapter's steps. A test pins the reader against clockpage.py's writer. Decided with Edgar in review.
  • A failed copy answers 409 atif_unavailable. Each read of it names the adapter and its error. It stays stopped: an instance that starts partway rebuilds nothing (Decision 18).
  • The turn index lives in memory in this PR. It resets when a context is evicted. Y2b-2's PR persists it.
  • Media bytes stay inside the agent until Y3. An inbound file's bytes, and media an adapter writes, are named in the document by media/<sha256>.<ext>, sha256 and size. The SDK holds them in memory, and no read serves them. Y3 (FD-6077) delivers them: a disk-spooled cache, a push under a per-turn grant, and a media read the worker pulls through. Its grant channel and folder layout are still open there. Greptile flagged this; no bundled agent declares an adapter before then.
  • Nothing is scrubbed yet. No bundled agent declares an adapter until Y5, so nothing serves atif/1 before Y2b-4's PR lands.

Testing

  • tests/test_a2a_atif_serving.py (24 tests) is a toy agent that offers native and atif/1. It covers:

    • every read form, each naming its format and versions;
    • native bodies unchanged, adapter or not;
    • the copy validating as a producer on completed, failed, raised and canceled turns;
    • two tasks giving one document;
    • an unanswered call holding back later steps, with the pages passing validate_live;
    • aux records reaching the adapter, and replaying the served inputs giving the served document;
    • a bound context read still getting the SDK's document;
    • DataParts and files written as decided;
    • the appended-and-returned refusal;
    • a returned native trajectory run through the adapter at seal;
    • an adapter error stopping only the copy;
    • cursor pages rebuilding the document, including a sub-agent that grows after its result;
    • an orphaned spawn kept referenced, and the 404 and 400 cases;
    • two messages sent at once in one context, which fails if anything awaits between the lock's release and the seal;
    • a clock-following agent's SDK steps on its programs' clock.
  • tests/test_atif_builder.py (7 new tests, 13 cases): trajectory_id, document(through=), task data and error and their checks, the canceled spawn result, the served turn's round trip, and served shapes that break their models being refused.

  • Integration: the echo agent (tst/data/a2a_agent) now declares an ATIF adapter. The existing format test checks, against the agent deployed through agent-env:

    • its card offers atif/1;
    • its atif/1 task read validates, carries the turn context, and names the versions;
    • its cursor page matches;
    • a read naming another format is refused.
      These are assertions in an existing test, so CI time doesn't change.
  • Greptile's two P2s are fixed and covered by tests:

    • The aux log keeps its own copy of each record, and the toy's aux handler now mutates the record it's handed.
    • The cursor header keeps final_metrics, so a task-level cost survives the rebuild.
  • All 1,956 protocol tests and the 1,261 agent and a2a_agent unit tests pass, and ruff check . passes.

  • Pinned agents still read: TrajectoryWriteObjects gained optional grants. agent-env now dumps a trajectory grant without its Nones (object_transfer.fetch_trajectory), because an agent on an older protocol refuses unknown fields.

    • The slow tier caught this. Its sandboxed proxy installs the protocol from PyPI, and its objects read got HTTP 400.
    • tst/unit/a2a_agent/object_transfer_test.py now checks the grant names only trajectory. It fails without the fix.
  • Chaos on an arm64 test host, 25 minutes, 7 workers (chaos_serving.py, kept outside the repo). An agent app ran random turns: scripts of valid adapter ops and aux notes, ending in every way (completed, failed, raised, canceled, returned, appended and returned). A reader polled every read form at random moments, and 3% of turns carried a bad op. It checked:

    • no read answered 500, and a 409 came only from a stopped copy;
    • every live page validated, and the pages passed validate_live against the final read;
    • served steps never changed, and served sub-agents only gained steps;
    • each task read validated, equaled the context as the task ended, and was a prefix of the next;
    • cursor pages at random limits rebuilt the document;
    • replaying the served inputs gave the last task read;
    • objects uploads equaled inline reads, and native reads were what was appended or returned;
    • ids, turn indexes, states and the refusal code were right;
    • every sub-agent was referenced.

    The run covered 149,626 seeds, 561,204 turns and 7,407,285 reads, with no failures. It found the sub-agent flaw described under Choices before the run, and caught two bugs I planted (a dropped aux log, an off-by-one cursor).

  • The integration test runs in CI's integration-local, which passed. The arm64 host can't run the echo agent's amd64-only image.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 5/5

The reviewed changes appear safe to merge; no new blocking issue was found.

Summary

The SDK serves atif/1 beside native trajectories, using one adapter per context and supporting task, context, cursor, and uploaded reads.

  • Agents can build an ATIF copy from their native trajectory.
  • ATIF reads return task snapshots, live documents, and cursor pages.
  • Served task records can rebuild the ATIF document offline.
  • SDK-written ATIF timestamps follow the agent’s session clock.
  • Trajectory uploads send only the grants the agent receives.

Reviews (11) · Last reviewed commit: "fix(protocol): an atif/1 copy keeps one ..." · Reviewed by Greptile

earakely-scale and others added 3 commits November 18, 2026 21:59
enable(TRAJECTORY_V1, native=..., atif=Adapter) adds atif/1 to the card's
formats. The SDK keeps one document per A2A context, fed every event the
agent appends and every aux record its code feeds, and serves atif/1 task,
context, cursor and final reads, context reads an agent binds included. A
task read is the document as it stood when the task ended, with its aux log
and turn context; cursor pages carry the header and the sub-agents their
steps reference. An adapter that raises stops its context's copy, not the
turn. Part of FD-6076 (Y2b-1, -3, -5, -6, -7).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… far as each is served

A sub-agent can gain steps after its spawning call's result, so a page carrying
only the sub-agents its own steps reference could leave a reader with an early
copy forever. A page now carries the sub-agents of every task its steps belong
to; the page that serves a task's last step, which closes only as the task ends,
carries them whole.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nned agents accept it

TrajectoryWriteObjects gained optional aux and turn_context grants; dumped with
their None values, they reached agents on an older protocol, whose request model
forbids unknown fields, and every objects-form trajectory read got HTTP 400.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale marked this pull request as ready for review November 19, 2026 07:07
@earakely-scale
earakely-scale requested a review from a team as a code owner November 19, 2026 07:07
earakely-scale and others added 2 commits November 18, 2026 23:48
…sor header keeps final_metrics

An aux handler that changed the record it was handed changed the served aux log,
so replay could build another document: the log keeps its own copy, and a task's
inbound content is a tuple. A cost reported for a whole task is on no step, so a
cursor page's header now keeps final_metrics once no task is open, and pages
rebuild the document whole.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d in the atif/1 copy

- ServedTurn and AuxEntry (atif/served.py) are the shapes an atif/1 final read
  serves as turn_context and aux; RecordedTask.from_served validates them.
- The copy maps steps and sub-agents to tasks through the builder
  (step_tasks, subagent_tasks), not by reading rendered profiles back.
- One _guarded() context manager stops the copy on an adapter error.
- _inbound and _final replace one function with an answer flag.
- TrajectoryLog takes the adapter's spec; the appended-and-returned refusal
  no longer rides on aux bookkeeping.
- The atif read path splits into _atif_events and _atif_document, and
  TaskTrajectories names its results (AtifTaskRead, AtifCursor).
- The serving tests' toy agent plays named scenarios from a table.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
earakely-scale and others added 2 commits November 19, 2026 00:47
wire() left out every None, so a diagnostic DataPart whose data is null lost its
required field and replay refused the turn. It now leaves out only optional
fields at their default.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… are tested

An agent that follows the env's clock runs its programs on the universe's time,
while its A2A server stays on real time, so the SDK's own steps (each task's
user step and final response) were stamped on another clock than the adapter's.
They now take the time the agent's programs read: session_time() in the
protocol's computer clock reads the follower's clock file, and a test pins it
against clockpage.py's writer.

Two messages sent at once in one context are now tested: the first is closed in
the copy before the context's lock lets the second start, which an await added
before the seal would break.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale merged commit 292435a into main Nov 19, 2026
64 of 66 checks passed
@earakely-scale
earakely-scale deleted the edgararakelyan/y2b-serve-atif branch November 19, 2026 16:59
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