refactor(a2a)!: remove the S3 transfer forms

[earakely-scale]

What and why

agent-env moves skill bundles, snapshots and changelogs only through transfer grants. The S3 call shapes are removed: s3_prefix, presigned_post and skill_s3_url. agent-env also no longer reads a trajectory_s3_prefix that an agent names in its answer. SDK agents haven't taken those shapes since the object variants shipped. Keeping them meant a second path through every call builder, plus an agent-echoed prefix that had to be clamped before it was registered.

Behaviour

• Object calls: an object-backed skill add, a snapshot save or load, and a changelog enable or apply each need two things: an Agent Card that advertises the object form, and an object store that issues grants. If either is missing, the call raises a RuntimeError naming which one, before any request is sent or grant issued. Changelog enable still raises GrantUnavailableError when the store can't sign a namespace grant that lasts the agent's lifetime.
• Old snapshots: loading a snapshot without the portable layout (no trajectory object) is refused, so those captures can no longer be restored.
• Trajectory answers: a trajectory get answer that names only trajectory_s3_prefix now raises. Every caller already treats a failed trajectory fetch as best effort, so this shows up as a warning instead of a silently missing trajectory. If the answer also has an inline trajectory, the inline one is used.
• Unchanged:
  • inline skills (skill_md) and inline trajectory gets;
  • the TransferMode values;
  • snapshot_load_call's signature;
  • ObjectStore.signed_post, which issue_upload_policy uses;
  • SkillArtifact's skill_s3_url alias;
  • the skill_s3_url / s3_uri spellings of an object-backed skill in a deploy_agent step, which now go as a bundle.

Breaking for downstream

• DeployAgentTaskStep: drops agent_changelog_s3_prefix, and VerifyA2ASkillConfigStep drops skill_s3_url. A stored VerifyA2ASkillConfigStep with skill_s3_url loads, and the key isn't written back. A stored deploy_agent step whose agent_changelog_s3_prefix is set is refused when it loads, since an S3-form changelog can't be applied and silently skipping the rewind would change what the step does; the empty field every stored step carries still loads.
• Call builders:
  • changelog_apply_call drops portable;
  • skill_add_call drops forms;
  • bounded_echo and FetchedTrajectory.legacy_prefix are removed.
• Validator: no longer probes skill_s3_url or trajectory_s3_prefix. Its reports drop the s3 keys and those options.
• Plugin API: check_plugin_api.py --base origin/main reports no break to the plugin surface. The ! is for agents that take only the S3 forms.

Merge order

• Hold: ready for review, but don't merge until no deployment still relies on the S3 forms.
• Conflicts: it conflicts with feat: agents on the local sandbox provider move objects through the local store's grants #13 and feat(a2a): agents the object store's grants can't reach get their objects through their own staging #46, which change the same call builders. Whichever lands second rebases. After feat: agents on the local sandbox provider move objects through the local store's grants #13, its _s3_form_url guard goes away along with the forms it guards, and its reachability reason moves into the object-form refusal.

How it was tested

• pytest tst/unit packages/agentenv-protocol/tests -n auto: 5824 passed, 13 skipped (with main merged in).
• Replaced tests: the ones that pinned S3-form behaviour are now refusal tests:
  • an agent without the object form;
  • a store without grants;
  • a snapshot in the old layout;
  • a prefix-only trajectory answer;
  • stored steps carrying a removed field.
• Mutants: I dropped each new guard in turn, in a copy outside the tree. Each mutant was caught: the layout guard by 3 tests, the grant guard by 6, the trajectory guard by 1.
• Leftovers: git grep for the removed shapes now finds only the refusal message, the SkillArtifact alias, PromptResponse.agent_trajectory_s3_prefix (agent-env's own output prefix), and the CLI's --skill-s3-url source option.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge once deployments no longer rely on the removed S3 forms.

Summary

AgentEnv removes S3-shaped transfer calls for skills, snapshots, changelogs, and trajectory reads, leaving transfer grants as the path for object-backed data. This simplifies the transfer choices while keeping inline skills and trajectories available.

• Object-backed calls now require an advertised object form and a store that issues grants.
• Snapshot loads refuse captures without the portable trajectory object; trajectory reads refuse prefix-only answers.
• Validators and stored task-step fields no longer use the removed S3 forms.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Load stored deploy step] --> B{S3 changelog source?}
  B -->|Yes| C[Refuse to load]
  B -->|No| D[Load step]
  D --> E{Object changelog source?}
  E -->|Yes| F[Apply with read grants]
  E -->|No| G[Continue without rewind]

Loading

_{Reviews (3) · Last reviewed commit: "fix(task-step): refuse a stored deploy_a..."}