feat(a2a): agents the object store's grants can't reach get their objects through their own staging - #46

What and why

With the local object store, an agent on a remote sandbox (Modal, E2B, a plugin provider) can't reach the store's grants. Today agent-env therefore refuses that agent's skill bundles, snapshots and changelogs ("grants do not reach agents on the 'modal' sandbox provider"), and its trajectories come back inline. This PR makes those flows work with no setup beyond the provider's own credentials: no bucket, tunnel or inbound connection to the user's machine.

An agent that serves the staging extension (#39; every SDK agent does) gets ordinary HTTPS grants naming paths on its own /ext/staging routes. agent-env moves the bytes over connections it opens itself:

• Reads (skill bundle files, snapshot load, changelog apply): before the call, each object is pushed into the agent's staging, streamed from the store.
• Writes (trajectory, snapshot save): after the call, each object the agent wrote is pulled into the store. The call's staging is cleared whether the call succeeded or not.
• Changelog capture: the namespace stays staged for the agent's life. Its increments are drained into the store every 5 seconds while a prompt runs, again when the prompt ends, and before teardown_run or a teardown_sandboxes step takes the agent down.
  • A drained increment is removed from staging only if the agent hasn't rewritten it since (If-Match).
  • If the sandbox dies mid-prompt, at most one drain interval is lost.

How it fits in:

• Choosing the store. Every call site that builds a transfer call takes its grants from transfer_store(). That function keeps the configured store whenever the store's grants reach the agent, so hosted stores, and the local store with the local provider, are unchanged. Staging is chosen only when the grants don't reach, the agent advertises staging, and the agent's URL is HTTPS.
• Agents without staging. An agent that doesn't advertise staging gets the inline forms, or the refusal it gets today.
• Error hygiene.
  • Staging failures are StagingErrors that never name a staged path, because the path's id is what keeps it private.
  • Staging requests are logged by origin only.
  • If an agent can't reach its own URL, the error says so.
• Unchanged. No request or response model changes, and no new config.

Stacked on #32 (the grant-lifetime PR), which it builds on through #13's grants_reach and sandbox_type plumbing. It also includes #39's commits, because it uses the staging extension. Merge after #39 and #32, then retarget this PR to main.

How it was tested

• pytest tst/unit packages/agentenv-protocol/tests: 5927 passed. tst/unit/a2a_agent/staging_test.py is new. It uses an in-process SDK agent at an HTTPS URL, so the agent's own calls to its staging run too, and it covers:
  • a skill bundle pushed (3 MB file);
  • a snapshot save pulled, then loaded into the agent;
  • a trajectory pulled;
  • a changelog drained, then applied to the agent;
  • mid-prompt drains plus the final drain;
  • teardown_run draining first;
  • store selection (local agent, no staging, non-HTTPS URL);
  • a full staging failing cleanly without naming a staged path.
• Integration tier on the local defaults (-m 'not int_test_slow'): 143 passed. The slow tier runs in CI.
• End to end on Modal with the local object store (claude-code-cli with the staging routes): every flow and six chaos scenarios pass; results are in this comment.

🤖 Generated with Claude Code

Confidence Score: 4/5

The PR is not ready to merge while staged uploads can fail when an object changes during transfer.

Findings

1.  Updated objects break staged uploads ▶
2.  Skill transfers repeat store lookups ▶

### Issue 1
src/agent_env/a2a_agent/staging.py:undefined-148
If another task replaces a skill or snapshot object while `push()` is running, `_push()` can open the new bytes but send the size read earlier as `Content-Length`. The upload then fails even though the object is available. The new preflight widens this gap by reading every size before any upload starts. Use a size tied to the bytes being sent.

### Issue 2
src/agent_env/a2a_agent/staging.py:undefined-148
`push()` now starts another metadata lookup for every object, all at once. Grant creation already reads that metadata, and a valid skill bundle can contain 1,000 files. This adds a burst of store requests before any file moves, increasing cost and risking slower transfers or request limits. Reuse the sizes already read or limit the new lookups.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Agents that cannot reach the configured object store can now move object data through staging on their own HTTPS server. Agent-env also drains staged changelogs while prompts run and before agents are torn down.

• SDK agents serve staging routes unless staging is turned off.
• Agent-env pushes objects the agent needs before a call and collects objects it writes afterward.
• Staged changelog increments move to the object store during prompts and before teardown.

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Store[Object store] -->|Push reads| Staging[Agent staging]
  Staging -->|Grants on agent URL| Agent[Agent call]
  Agent -->|Write results and changelogs| Staging
  Staging -->|Pull writes and drain increments| Store

_{Reviews (6) · Last reviewed commit: "Merge branch 'edgararakelyan/agent-stagi..."}