Skip to content

feat(a2a-agent): an atif/1 copy's media files wait on the agent's disk until the worker pulls them - #834

Open
earakely-scale wants to merge 3 commits into
mainfrom
edgararakelyan/fd-6077-y3-media
Open

earakely-scale wants to merge 3 commits into
mainfrom
edgararakelyan/fd-6077-y3-media

Conversation

@earakely-scale

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

Copy link
Copy Markdown
Collaborator

Y3 for FD-6077: an atif/1 copy's media files wait on the agent's disk until the worker pulls them at each turn's end. This is the SDK half only (Y3-8). The run's folder, the pull helper and the atif/1 fetch that calls it land with Y4 (FD-6078), so each piece lands with its caller. Closes FD-6077.

What changes

  • The media spool (a2a_agent/_media_spool.py). An agent that serves atif/1 writes each media file its copies name (media/<sha256>.<ext>) to its disk, one file per sha256, instead of keeping the bytes in memory for the context's life.
    • A file is held by the contexts whose copies reference it.
    • It goes when a push confirms it, or when its context is evicted or restored over.
    • Whatever is left goes when the server stops.
    • The spool has no cap for now (Y3-7).
  • Image sizes from the header (atif/_image_size.py). A PNG, JPEG, GIF or WebP image's width and height are read from its header when the adapter gives none (Y3-6).
    • It is plain Python, so the agent extra still has no Pillow.
    • A header it can't read leaves the size out, and the image is still stored.
  • A media call on the trajectory extension (POST /ext/trajectory/media). It is listed on the card only of an agent that serves atif/1; old agents and native-only agents never get it.
    • It takes {context_id, objects: {path: write grant}} and uploads each file that context holds under its exact-object grant, 8 at a time, checking each upload against the file's name.
    • The answer has objects (what it uploaded), missing (paths the context holds no file for) and failed (uploads that failed, with why). Neither of the last two stops the rest.
    • Only media/<64 hex>.<ext> paths are accepted.
    • It is served by the SDK alone (OperationDefinition.sdk_only). An agent that serves its own trajectory reads keeps it, and binding it is refused.
    • Each spooled file is hashed before its upload. One that no longer matches its name is reported failed and never reaches the store.
  • The reader-side check. atif.media_file takes a part path only as media/<sha256>.<ext> in the document's own folder, never another path or a URL. atif.check_media refuses bytes that don't match their name. The validator now shares the same pattern.
  • A fix to feat(a2a-agent): atif/1 reads leave out the secrets the SDK knows #827's scrub. A grant URL with no query had its token-like path segments taken as its credential, and a media call's grant URL can name the file it writes (.../media/<sha256>.png). The scrub then redacted every copy's media paths. A media file's name is never taken for a token now. Chaos found this as soon as it pushed media.
  • Docs: the README's Serving ATIF section and PROFILE.md's media section.

Choices to review

  • The spool is a temp folder per server process, made on the first file and removed when the server stops. It isn't under the user's state folder: a restarted server can't serve the old copies, so their media would only be litter.
  • A file shared by two contexts stays until neither holds it. A push for one context releases only that context's hold. Each hold has its own number, so an upload that outlives a restore or eviction releases only the hold it began with, never the one a later copy took on the same path.
  • The spooled file is checked against its name twice: hashed before the upload, and the upload's checksum after. A corrupted spool file fails before anything is written.
  • The route's format check now runs only on trajectory get. It used to run on every trajectory call, and the media call carries no format.

Testing

  • tests/test_a2a_atif_media.py (26 tests):

    • an inbound image is spooled by sha256, with its size and name in the profile, and a push uploads it, leaves the spool and answers its sha256;
    • the same bytes added twice are spooled and pushed once;
    • a path the context doesn't hold, and an upload that fails, don't stop the rest, and another context can't push what it doesn't hold;
    • only media paths are accepted;
    • an agent that overrides TRAJECTORY_V1.get still starts and serves media, and binding media is refused;
    • releasing an old hold after a drop and a new copy leaves the new hold;
    • a spooled file changed on disk is reported failed, and the store gets nothing;
    • only an agent that serves atif/1 lists media;
    • a media call's grants leave the copy's media paths as they are (the scrub fix);
    • a video and a HEIC image are spooled and pushed like any file, with their plain notes;
    • eviction and restore drop a context's files, but not those another context still holds;
    • the spool goes with the server;
    • the native trajectory is unchanged;
    • header sizes for PNG, JPEG, GIF and three WebP forms, two bad headers, two truncated WebP headers, and a type ATIF has no part for;
    • dimensions an adapter passes win;
    • the reader-side path and bytes checks.

    Removing the spool, the header sizes, the release, the drop on eviction, the sdk_only refusal or its exemption from the override rule, the hold numbers, the pre-upload hash or the WebP length guard fails them.

  • Integration: a new test in test_prompt_agent_live_trajectory_local.py.

    • It deploys the echo agent and sends it a PNG, then reads the atif/1 copy's media path.
    • It mints an exact-object grant from the local store's grant server, and pushes it through the media call.
    • It checks that the object is in the store with the same bytes, the answer's sha256, and the width and height in the profile.
  • Serving chaos (the Y2b harness): after every task's final read it pushes the copy's new media and checks:

    • every file is uploaded with bytes matching its name, with nothing missing or failed;
    • asking again finds nothing held.

    60 s locally at c7b8dc8: 4,095 seeds, no failures. 20 min on an x86 test host at c7b8dc8: 83,560 seeds, 313,159 tasks, 4.09M reads, 31,214 restarts and 31,152 restores, no failures.

  • On the test host at c7b8dc8, the live-trajectory integration tests pass (5/5, the media push among them). 2343d57 only names a constant.

  • All 2,033 protocol tests pass, and ruff check . passes. Four tst/unit/task_step/computer_exec_test.py tests fail on macOS only, because BSD base64 has other flags. They don't involve this change, and CI runs them on Linux.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 5/5

The PR appears safe to merge; no new blocking issues were found.

Summary

The SDK now keeps ATIF media on disk until the worker requests an upload. The latest change names the hash read size without changing its value.

  • ATIF media stays on the agent until the worker pulls it.
  • ATIF profiles gain image sizes from file headers.
  • ATIF readers accept only media paths backed by matching bytes.
  • Grant URLs no longer hide media filenames in trajectory copies.

Reviews (7) · Last reviewed commit: "refactor(a2a_agent): name the media hash..." · Reviewed by Greptile

…k until the worker pulls them

An agent that serves atif/1 spools each media file its copies name to its disk, one file
per sha256, instead of holding the bytes in memory, with a PNG, JPEG, GIF or WebP image's
width and height read from its header when the adapter gives none. The trajectory
extension gains a media call, listed on such an agent's card: given a context and an
exact-object write grant per media/<sha256>.<ext> path, it uploads each file the context
holds, 8 at a time, checking each upload against its name, and answers what it uploaded,
the paths it holds no file for and the uploads that failed. An uploaded file leaves the
disk, as do a context's files when it is evicted or restored over, and the rest when the
server stops. atif.media_file and check_media take a part path only as
media/<sha256>.<ext> and only with the bytes that name, and the scrub never takes a media
file's name in a grant's URL for its token.

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 20, 2026 01:21
…k what they send

- The media call is served by the SDK alone (`OperationDefinition.sdk_only`): an agent that serves its
  own trajectory reads keeps it, and binding it is refused.
- Each spool hold has its own number, so an upload that outlives its context's copy releases only the
  hold it began with.
- A spooled file is hashed before its upload; one that no longer matches its name is reported failed
  and never reaches the store.
- A WebP header too short for its size fields gives no size.

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

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant