feat: agents on the local sandbox provider move objects through the local store's grants

[earakely-scale]

Summary

This is the third of three PRs, stacked on #11. It turns on the local object store's HTTPS transfer grants for agents on the local sandbox provider. With it, skill bundles, trajectories, snapshot saves and loads, and changelog capture and replay work on the all-local configuration the same way they do against S3, through the forms agents already take. Agents and the protocol don't change.

• Grants are on. LocalFilesystemObjectStore gets grants = "auto" | "off" (default "auto"), and with "auto" supports_transfer_grants is true. "off" hands out no grants.
• Local containers trust the local CA, but only when the configured object store (unwrapped from @local routing) is a local store that hands out grants. Otherwise containers run exactly as before. In that case LocalSandboxProvider runs docker create, then docker cp of the CA's public trust directory to /etc/agentenv/, then docker start, and removes the container if the copy or the start fails.
  • An agent placed on a local VM sandbox, which starts through A2AAgent._run_container, is given the CA the same way, plus the Linux host.docker.internal mapping.
  • That way the files are in place before the container's first process runs, which works on every Docker setup without a bind mount.
  • It sets SSL_CERT_FILE and REQUESTS_CA_BUNDLE to ca-bundle.pem (certifi's roots plus the CA) and NODE_EXTRA_CA_CERTS to ca.pem. A variable the caller's env already sets wins.
  • The copy runs as an argument list, not through the sandbox shell, which rewrites /app paths.
  • The base provider's docker run moves into two protected hooks, _start_container and _container_args, and its script is byte-identical.
• Grants go only to agents they reach. A new ObjectStore.grants_reach(sandbox_type) defaults to true, for public HTTPS URLs.
  • The local store answers true only for local. LocalRunObjectStore asks its local store, since an @local run writes there.
  • choose_transfer takes the agent's sandbox_type, and every call builder and call site threads the deployed agent's type through: skills, snapshot save and load, changelog enable and apply, trajectory get (prompt, judge, partial and validator), and the validator's probes.
  • An agent on Modal in an @local run keeps getting its trajectory and SKILL.md inline, as it does today.
• No more file:// in S3-named fields. A legacy s3_prefix or skill_s3_url form carrying a local store's file:// URL, which no agent can use, is now refused with the reason: grants off, a legacy-only agent, or grants that don't reach the agent's provider. A mode-None refusal adds the reachability reason when that is why.
• Unreachable-server hint. When an objects-form call fails with the SDK's transfer_unavailable and its grants came from this process's grant server, the error names the server's origin and bind address and points at grant_bind_host / grant_advertise_host. It never quotes a grant.
• Validator. The presigned-URI probe falls back to issue_read_grant when the store signs no URL, but only when those grants reach the provider the validation agents will deploy on. A fallback chain counts as its first provider. ChainedSandboxProvider gains a read-only providers property.
• Docs. The user guide has moved to the docs site, so this PR changes no docs in the repo. The local store's grants, the trust injection, the grant settings and grants_reach for custom stores need a page there, as a follow-up.

Merge order

1. fix(store): the local object store writes atomically and keeps content types #9: atomic writes and kept content types.
2. feat(store): the local object store issues HTTPS transfer grants #11: grant server, CA and issue_* methods, advertised to no one yet.
3. This PR, which carries bump-version.

Each one merges after its required checks, Greptile, and a code-owner approval, and gets rebased onto main after the previous squash-merge.

Test plan

• pytest tst/unit packages/agentenv-protocol/tests -n auto: 5751 passed, 13 skipped
  • Store: grants on and off, reach per sandbox type, S3 reaching any type, and routing delegation.
  • Form choice: local, modal and unknown sandboxes; inline trajectory and SKILL.md still reaching a remote agent; the three refusal reasons; an S3 URL passing through.
  • Provider: create → cp → start ordering and flags, the caller's env winning, a failed copy removing the created container, the copy's error reporting, no trust work without local grants, and which stores need the CA.
  • Linked agents: trust given, or not, on a local VM sandbox, and a failed copy leaving no container.
  • Validator probe: a grant for the local provider alone or first in a chain, and none for a remote one.
  • Hint: named for transfer_unavailable but not for transfer_rejected, with no token in it.
• Plugin API check against the base: no break to the plugin surface
• Slow tier on macOS with Rancher Desktop: the new test_an_agent_uploads_its_trajectory_through_a_local_grant and test_load_artifact_stages_files_into_env_and_agent passed (run with DOCKER_DEFAULT_PLATFORM=linux/amd64, since the test image cache builds amd64 images an arm64 host can't otherwise pull). Here the SDK echo agent, running as a non-root user in a local container, uploads its trajectory through a local grant.
• pytest -m 'not int_test_slow' tst/integration --ignore=tst/integration/env/gateway/gateway_test.py: 141 passed, and green in CI's integration-local.
• The CI integration-local-slow job runs the new test on Linux (the bridge-gateway bind plus host-gateway) and is green. The model-gated slow tests skip there, as before.
• Existing tests: tests that asserted a legacy s3_prefix / skill_s3_url payload carrying a local file:// URL now assert the refusal, and their positive cases moved to S3 URLs. Test fakes gained grants_reach, and fixtures name their agent's sandbox_type.

🤖 Generated with Claude Code

Confidence Score: 5/5

This PR appears safe to merge; no new actionable issue remains.

Findings

1.  Older S3 calls fail ▶

Fix with agent prompt

### Issue 1
src/agent_env/a2a_agent/object_transfer.py:312-315
When an agent accepts only `skill_s3_url`, an S3-backed skill now reaches `_require_object_form` and fails before the agent receives it. The same grant-only requirement stops snapshot saves on agents that accept only `s3_prefix`. Changelog capture also fails when S3 cannot issue a grant for the full capture lifetime. Keep the older forms for reachable S3 objects.

---

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

Summary

Local agents can now use the local object store’s HTTPS transfer grants, with containers trusting the local CA before they start. Transfer choices check which sandbox can reach a store’s grants, and validator probes and transfer errors now account for reachable local grants.

• Adds a default-on grant setting to the local store and limits its grants to local agents.
• Prepares local containers with the CA before startup and uses the agent’s sandbox type when choosing transfer forms.
• Lets validator probes use reachable grants and adds guidance when an agent cannot reach this process’s grant server.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Store[Object store] --> Reach{Grant reaches agent?}
  Reach -->|Yes| Grant[Send object grant]
  Reach -->|No| Inline[Use inline form or refuse]
  Grant --> Local[Local container trusts CA]

Loading

_{Reviews (15) · Last reviewed commit: "Merge main into local-provider-transfer-..."}

[greptile-apps]

Comments Outside Diff

These findings could not be posted inline.

•  Valid snapshot runs fail src/agent_env/task_step/snapshot_utils/snapshot_series.py:137 ▶

  For a local run ID near the 4096-byte limit, this check adds both snapshot- and -workspace. Neither ID that SnapshotSeries writes has both parts. The check can reject a run even though its real workspace and snapshot IDs fit, so no agent state is captured. Check those two IDs instead.

•  Staging test cannot run src/agent_env/a2a_agent/object_transfer.py:435 ▶

  PR feat(a2a): agents the object store's grants can't reach get their objects through their own staging #46’s staging_test.py still calls changelog_apply_call with portable=True. This signature removes portable, so that test raises TypeError before it can check changelog replay. Update the stacked caller for this API change.

•  Older trajectories go missing src/agent_env/a2a_agent/object_transfer.py:569 ▶

  When an older agent answers trajectory get with only trajectory_s3_prefix, fetch_trajectory now raises instead of returning that location. The prompt catches the error and records no per-turn trajectory. Partial captures and judge checks lose it too. Keep reading a reachable S3 prefix for this response form.

•  Stored tasks cannot resume src/agent_env/task_step/task_steps/deploy_agent.py:201 ▶

  A saved task containing agent_changelog_s3_prefix now raises in DeployAgentTaskStep.from_dict. The task store calls that method while loading the plan, so the entire task cannot resume, even if it has not reached the changelog step. Let older plans load and report an unsupported replay when that step runs.

•  Saved snapshots cannot load src/agent_env/a2a_agent/object_transfer.py:372 ▶

  When DeployAgentTaskStep loads an older S3-form snapshot, its saved file names lack the portable trajectory object. This check rejects the snapshot even if the agent accepts s3_prefix, so users cannot restore that saved work. Keep a load path for older captures or convert them first.

[greptile-apps]

Older S3 calls fail

When an agent accepts only skill_s3_url, an S3-backed skill now reaches _require_object_form and fails before the agent receives it. The same grant-only requirement stops snapshot saves on agents that accept only s3_prefix. Changelog capture also fails when S3 cannot issue a grant for the full capture lifetime. Keep the older forms for reachable S3 objects.

Knowledge Base Used:

• A2A agent runtime
• Store backends and querying

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/agent_env/a2a_agent/object_transfer.py
Line: 312-315

Comment:
**Older S3 calls fail**

When an agent accepts only `skill_s3_url`, an S3-backed skill now reaches `_require_object_form` and fails before the agent receives it. The same grant-only requirement stops snapshot saves on agents that accept only `s3_prefix`. Changelog capture also fails when S3 cannot issue a grant for the full capture lifetime. Keep the older forms for reachable S3 objects.

**Knowledge Base Used:**
- [A2A agent runtime](https://app.greptile.com/scale-ai/-/custom-context/knowledge-base/scaleapi/agentenv-framework/-/docs/a2a-agent-runtime.md)
- [Store backends and querying](https://app.greptile.com/scale-ai/-/custom-context/knowledge-base/scaleapi/agentenv-framework/-/docs/store-backends-and-querying.md)

---

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

[earakely-scale]

Intentional: main removed the S3 transfer forms in #54, and this merge carries that in. Object-backed skills, snapshots and changelogs go only through grants now, and an agent that advertises only the S3 forms is refused before anything is sent. #46's call with the removed portable= is fixed in e0fd15b.

[greptile-apps]

Thanks for the clarification. Given that #54 intentionally removes the S3 transfer forms and this PR carries that change, refusing agents that advertise only skill_s3_url/s3_prefix is expected rather than a regression. The portable= usage from #46 is also fixed in e0fd15b, so this finding is no longer actionable.

[earakely-scale]

This isn't from this PR. Its only change on these lines passes sandbox_type= through. For an S3 store grants_reach is True, so S3 behaves exactly as it does on main. The requirement that S3-backed skills, snapshot saves and changelogs use the object form comes from #54, which removed the S3 transfer forms on purpose.

The same holds for the findings posted outside the diff, which came into view with the merge of main:

• trajectory_s3_prefix answers, agent_changelog_s3_prefix in saved plans, and non-portable snapshots: refactor(a2a)!: remove the S3 transfer forms #54's intended breaking change.
• The id-length check in snapshot_series.py: from feat(store)!: name every derived id <base>__<suffix>, bare or @local #26. It validates <base>__snapshot-<step>-workspace, which is longer than either id actually written, so it is stricter than needed, but only for ids within about 10 bytes of the limit. Not changed here.
• portable=True in feat(a2a): agents the object store's grants can't reach get their objects through their own staging #46's staging_test.py: feat(a2a): agents the object store's grants can't reach get their objects through their own staging #46's branch no longer passes it.

[greptile-apps]

You're right. The change on these lines only threads sandbox_type into _require_object_form; with grants_reach=True for S3, it does not alter S3 behavior. The S3-form removals are intentional in #54, and the trajectory/changelog/snapshot and ID-length findings are from earlier PRs rather than this diff. None of these findings is actionable for PR #13.

[earakely-scale]

@greptileai review