feat(snapshot_env): hand a service that takes parts grants an object of its own to upload to

[earakely-scale]

Stacked on #150 → #149 → #147: merge those in order, then this retargets to main.

Summary

snapshot_env becomes the first issuer of http-put-parts grants.

When a service's card lists the kind (client.write_kinds, from #149):

• Offer: it begins a write (feat(store): add begin_write, a write made through a grant, with S3 multipart parts #150) of agentenv-snapshots/<uuid>/<env>.zip, as application/zip, up to ENV_SNAPSHOT_MAX_BYTES (16 GiB, about 256 part URLs), and sends it as data/get(write_object=...).
• On an uploaded_object reply: it completes the write and registers the bundle in place, with the same key shape, file name and content type a service self-upload gets.
• On anything else (another kind of reply, an error, a timeout): it aborts the write. Nothing leaks a pending upload.
• Cancelled midway (the snapshot timeout): an export cancelled while the write begins waits for it, then aborts it. One cancelled while the write completes lets the completion finish before any abort runs. The credentials push sits inside the same try, so a cancellation there aborts the write too.
• A completion failure is UploadFailedError, a ValueError, so export_one fails only that service, as with any other bad export.

Services that don't declare parts are offered exactly what they get today.

Rollout choice to review: a parts-declaring service that also advertises the credentials extension still gets the pushed credentials. A parts upload that fails therefore falls back to them, which keeps the change regression-free while services move over. Dropping the push is the later removal.

Per-service timing log. Each export now logs one line naming how its bundle came and how long it took, with bytes and parts for a parts upload. The ways are:

• parts
• namespace
• service upload
• inline
• stream
• data
• export-state

Nothing recorded per-service export time before, and it's the comparison a rollout needs. The part count comes from the protocol's part_ranges.

Fix: services in a local compose stack can reach and trust the local grant server. A MultiEnv on the local backend renders its MCP servers into a compose file, which never gave them the local transfer CA or the host mapping. So every local grant handed to one failed with CERTIFICATE_VERIFY_FAILED, write_namespace grants included. The e2e below found it. When the sandbox is local and the store issues local grants, each MCP server now gets three things, as a single local container already does:

• the CA's trust files, mounted from a copy in the sandbox's work dir (a Docker-shared path, unlike the state dir);
• LOCAL_TRUST_ENV;
• the sandbox's extra_hosts (how host.docker.internal resolves on Linux).

Labelled bump-version: this is the release issuers pin to start offering parts grants.

Verification

An end-to-end prototype of this stack ran in a real sandbox: a 2 vCPU / 8 GB VM, with an env service holding an 8.6 GB dataset.

• Upload: 8.66 GB (over a single PUT's 5 GiB) went up in 129 parts with no credentials pushed.
• Bundle content: identical to the input on 255,035/255,036 files, with only the service's regenerated state file differing.
• Restore: loading it back and snapshotting again was identical on all 255,036 files.

End-to-end A/B on the same VM size, same service, data and bucket, 4 runs each:

Path	Mean	Container CPU
pushed credentials (boto3 multipart)	160.4 s	62.5 s
this path	159.7 s	higher

That higher CPU came from per-chunk hashing in the uploader, since fixed in #147; upload-only CPU is now about 0.58× boto3's.

Tests

snapshot_env_object_write_test.py covers:

• a parts-declaring service's grant shape, its object key, and its in-place registration and load-back, with credentials still pushed and the parts log line;
• a fresh object per export;
• a non-upload reply aborting the write and exporting as before;
• a misreported upload failing only that service while the other is exported;
• undeclared, unreachable-sandbox and no-object-write stores offered today's request;
• an export cancelled while beginning, pushing credentials or completing: no write is left open, and none is aborted mid-completion.

The existing snapshot_env tests pass unchanged.

End to end (slow tier). multi_env_snapshot_local_test.py does the following:

1. Deploy a MultiEnv on local compose whose items server takes write_object.
2. Run the snapshot_env step, and check the bundle came through the parts tier.
3. Check the registered object is agentenv-snapshots/<uuid>/items.zip, holds the state, and is application/zip.
4. Change the state, load the snapshot back, and check the state it held is restored.

env_gateway_provider_test.py checks that MCP servers get the trust files, env and host mappings only when there is a local CA. The compose fixture now closes the grant server its tests start.

Mutants, all killed:

• no object write;
• no complete;
• no abort;
• credentials withheld from parts services;
• kinds ignored;
• a shared key;
• no timing log;
• UploadFailedError not a ValueError;
• plain to_thread for beginning and for completing;
• the push before the try;
• no shield;
• no abort of a write begun after cancellation.

make unit-test passes apart from tst/unit/bundle/parse_test.py::TestFiles::test_deep_nesting[json], which fails the same way on main locally.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; no blocking issue remains.

Summary

snapshot_env offers parts-capable services their own upload object, completes successful uploads, and logs each export’s path and time.

• Parts-ready services now upload snapshots straight to their own object.
• Snapshot logs show each service’s export path and time.
• Local compose services can trust and reach the local grant server.

Diagram

sequenceDiagram
  participant Snapshot
  participant Store
  participant Service
  Snapshot->>Store: Begin write for this service
  Store-->>Snapshot: Parts grant
  Snapshot->>Service: data/get with write_object
  Service->>Store: Upload parts
  Service-->>Snapshot: uploaded_object
  Snapshot->>Store: Complete write
  Snapshot->>Snapshot: Register bundle
  Note over Snapshot,Store: Abort an unfinished write on other replies or errors

Loading

_{Reviews (10) · Last reviewed commit: "fix(local): a local compose mounts the t..." · Reviewed by Greptile}

[earakely-scale]

@greptileai review