feat(protocol): SDK agents serve a staging extension agent-env can move objects through

[earakely-scale]

What and why

The local object store's grants reach only agents on the local machine. An agent on a remote sandbox (Modal, E2B, a plugin provider) can't reach them. For that agent, skill bundles, snapshots and changelogs were refused, and trajectories came back inline. The core change that fixes this needs a way to hand such an agent its objects without any connection back to the user's machine. This PR is the agent side: every SDK agent now serves a staging extension, urn:agentenv:staging/v1. It is a small object store on the agent's own server at /ext/staging. Before a call, agent-env pushes into it what the agent will read. After the call, agent-env pulls out what the agent wrote.

The grants agent-env sends stay ordinary http-get / http-put / http-post-policy grants, with URLs that name staged paths on the agent's own URL. So no request or response model changes, and extension handlers and the upload / download / NamespaceUploader helpers are untouched. An agent that doesn't use the SDK can serve the same routes and add one card entry.

Route	Does
PUT {path}	stores the body (streamed to disk, renamed into place)
GET {path}	returns it, with an ETag
POST {prefix}	stores a multipart upload's file at {prefix}/{key}, as an upload-policy grant is used
GET {prefix}/	lists {objects: [{path, size_bytes, etag}]}
DELETE {path}	removes it; with If-Match, only while it still has that tag, so an object rewritten since it was read survives
DELETE {prefix}/	removes everything below the prefix

• A path's first segment is an id agent-env generates (at least 22 characters) and shares with no one. That id is what keeps staged objects private on a public agent URL, the same posture as the agent's other routes on that URL.
• Everything staged counts against AGENTENV_STAGING_MAX_BYTES: 16 GiB by default, and 0 turns staging off and drops the card entry.
• Staged objects live in AGENTENV_STAGING_DIR (default: a directory under the system temp dir).
• python-multipart joins the agent extra, for the upload forms.
• A second commit makes transfers.redacting_request_urls public. agent-env now requests secret-bearing URLs itself (its pushes and pulls) and keeps them out of httpx's logs the same way the helpers do.

This merges independently of the local-grant stack. Core starts using it in the follow-up PR, which is stacked on this one.

How it was tested

• pytest packages/agentenv-protocol/tests: 301 passed. test_a2a_staging.py is new. It covers:
  • the card entry;
  • put/get/list/delete;
  • If-Match;
  • refused short ids and unnormalized paths, and refused prefix listing without an id;
  • the quota, including a replacement needing room beside the old copy;
  • a refused streamed write leaving nothing behind;
  • the protocol's own upload, download and NamespaceUploader round-tripping through the routes.
• pytest tst/unit: 5473 passed (core is unchanged by this PR).
• uv lock --check is clean. The lock resolves from PyPI only.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge, though symlinked staging directories could change permissions on shared files.

Findings

1.   Staging IDs become visible ▶
2.  Shared stores lose coordination ▶
3.  Shared directory becomes private ▶
4.  Staged files survive restarts ▶

Fix with agent prompt

### Issue 1
packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/staging.py:undefined-242
If the agent runs on a multiuser host with a typical umask, these directories let another local user list the IDs meant to keep staged files private. That user can then use an ID with the public `GET` route to read a file. Create the staging directories so other users cannot list them.

**How this was verified:** Default directory creation does not restrict access, while the public read route checks only the path’s ID length.

### Issue 2
packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/staging.py:104-108
If two app instances or workers use the same staging directory, each has its own lock and byte count. Neither sees the other’s pending writes, so together they can exceed `AGENTENV_STAGING_MAX_BYTES`. Another instance can also rewrite a file between an `If-Match` check and deletion, causing the newer file to be deleted. Coordinate stores that share a directory, or give each one its own directory.

### Issue 3
packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/staging.py:440-442
If `AGENTENV_STAGING_DIR/objects` or `incoming` is a symlink to a shared directory, `_private` follows it and changes that directory to `0700`. A staging write can then lock other users out of files outside staging. Reject symlinked staging directories before changing their permissions.

### Issue 4
packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/staging.py:115-116
When `AGENTENV_STAGING_DIR` is unset, each server run creates a new temporary staging directory, but nothing removes it when the server stops. Staged files pile up across restarts, using disk space and keeping data longer than the documentation promises. Remove the directory when the server shuts down.

---

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

Summary

SDK agents now host a staging store that lets AgentEnv move objects through the agent when object-store grants cannot reach a sandbox. The PR also makes the URL-redaction helper public for other grant callers.

• Adds staging routes for storing, reading, listing, and deleting objects.
• Adds a configurable storage cap and private staging directories.
• Makes redacting_request_urls available to callers.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Core[agent-env] -->|push objects| Stage[Agent staging routes]
  Stage -->|read grants| Agent[Agent handler]
  Agent -->|write grants| Stage
  Stage -->|pull objects| Core

Loading

_{Reviews (4) · Last reviewed commit: "fix(protocol): staging tightens its own ..."}

[greptile-apps]

Staging IDs become visible

If the agent runs on a multiuser host with a typical umask, these directories let another local user list the IDs meant to keep staged files private. That user can then use an ID with the public GET route to read a file. Create the staging directories so other users cannot list them.

How this was verified: Default directory creation does not restrict access, while the public read route checks only the path’s ID length.

Knowledge Base Used: A2A agent runtime

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/staging.py
Line: 223

Comment:
**Staging IDs become visible**

If the agent runs on a multiuser host with a typical umask, these directories let another local user list the IDs meant to keep staged files private. That user can then use an ID with the public `GET` route to read a file. Create the staging directories so other users cannot list them.

**How this was verified:** Default directory creation does not restrict access, while the public read route checks only the path’s ID length.

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

---

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

[earakely-scale]

Fixed in ff1d3d4: the directories staging makes (objects/, incoming/, and the per-process default root from mkdtemp) are 0700. A directory given with AGENTENV_STAGING_DIR is used as it is, since chmodding a shared path like /tmp would be worse.

[greptile-apps]

Shared stores lose coordination

If two app instances or workers use the same staging directory, each has its own lock and byte count. Neither sees the other’s pending writes, so together they can exceed AGENTENV_STAGING_MAX_BYTES. Another instance can also rewrite a file between an If-Match check and deletion, causing the newer file to be deleted. Coordinate stores that share a directory, or give each one its own directory.

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/staging.py
Line: 104-108

Comment:
**Shared stores lose coordination**

If two app instances or workers use the same staging directory, each has its own lock and byte count. Neither sees the other’s pending writes, so together they can exceed `AGENTENV_STAGING_MAX_BYTES`. Another instance can also rewrite a file between an `If-Match` check and deletion, causing the newer file to be deleted. Coordinate stores that share a directory, or give each one its own directory.

---

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

[earakely-scale]

Documented in ff1d3d4 rather than coordinated: one server process owns a staging directory. An A2A agent is single-process already (the A2A SDK's task store is in memory), and without AGENTENV_STAGING_DIR each server now gets a directory of its own, so two never share one by default.

[greptile-apps]

Staged files survive restarts

When AGENTENV_STAGING_DIR is unset, each server run creates a new temporary staging directory, but nothing removes it when the server stops. Staged files pile up across restarts, using disk space and keeping data longer than the documentation promises. Remove the directory when the server shuts down.

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/staging.py
Line: 114-115

Comment:
**Staged files survive restarts**

When `AGENTENV_STAGING_DIR` is unset, each server run creates a new temporary staging directory, but nothing removes it when the server stops. Staged files pile up across restarts, using disk space and keeping data longer than the documentation promises. Remove the directory when the server shuts down.

---

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

[earakely-scale]

Fixed in 4caa425: the directory a server makes for itself is removed at exit (atexit); a directory given with AGENTENV_STAGING_DIR is left alone. A killed process can still leave one behind in the system temp dir, which the OS cleans. Test: test_a_servers_own_staging_directory_goes_when_it_exits.

[greptile-apps]

Shared directory becomes private

If AGENTENV_STAGING_DIR/objects or incoming is a symlink to a shared directory, _private follows it and changes that directory to 0700. A staging write can then lock other users out of files outside staging. Reject symlinked staging directories before changing their permissions.

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/staging.py
Line: 440-442

Comment:
**Shared directory becomes private**

If `AGENTENV_STAGING_DIR/objects` or `incoming` is a symlink to a shared directory, `_private` follows it and changes that directory to `0700`. A staging write can then lock other users out of files outside staging. Reject symlinked staging directories before changing their permissions.

---

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