feat(protocol): declare env write grant kinds and take a write_object on data/get

[earakely-scale]

Stacked on #147: review and merge that first, then this retargets to main.

Summary

An env service can now be handed one caller-named object to upload its data/get export to, and tell callers which write grants it takes. The data/get operation itself is unchanged.

• The write_object parameter.
  • A @get_data handler may take an optional write_object: WriteObject.
  • _invoke_get validates it only for a handler that takes it, naming the failing fields and never their values, as for write_namespace.
  • The handler uploads with transfers.upload() (parallel parts for an http-put-parts grant) and answers uploaded_object_part(uploaded, name=..., mime_type=...), read back with uploaded_object(part). The name must be relative.
• The declaration, urn:agentenv:transfers/v1. It declares the write grant kinds a handler uploads through as {"write": [...]}, derived from its signature:
  • write_namespace adds http-post-policy, so these handlers' cards gain this entry next to their existing data-objects/v1;
  • write_object adds http-put and http-put-parts.
• client.write_kinds(card) reads the declaration. A card without it counts as accepting http-post-policy alone if it advertises data-objects/v1, and nothing otherwise. A caller sends only a grant whose kind the card lists.
• client.get_data(..., write_object=) sends the grant.
• No data-objects/v2. The kind implies the parameter, and data-objects/v1 stays as it is for existing callers.

Wire freeze. test_the_object_write_wire_shape_is_frozen pins the field sets of HttpPartsPutGrant, HttpPutGrant, WriteObject and Uploaded. Receivers refuse unknown fields, so a field added later must be negotiated rather than sent to everyone. A receiver can advertise it in its transfers/v1 entry, whose unknown params readers ignore, or it can be a new grant kind.

Labelled bump-version: this is the release env services pin to start receiving parts grants. No issuer sends write_object yet; that lands in core separately.

Tests

test_data_objects.py covers:

• the card kinds for write_object-only and combined handlers;
• write_kinds for declared, data-objects-only and bare cards;
• the handler receiving the grant or None;
• an invalid grant refused without echoing its signature;
• the client sending it;
• an end-to-end export through the real handler, parts uploader, client and reader;
• the reply surviving the wire, non-object parts reading as None, and relative names.

The two existing advertisement tests now expect the transfers entry too.

Integration (local tier, server_env_local_test.py). The items test server now takes write_object: it uploads its state as a zip bundle, and data/add loads such a bundle back. The new test does the following:

1. Deploy it in a local container.
2. Hand it a 40-URL parts grant on the local TLS grant server.
3. Check the server used only the URLs its bundle's size takes, more than PARTS_IN_FLIGHT of them.
4. Check each part holds its range, and the parts joined make the bundle.

It also checks that the card declares http-put-parts. gateway_test.py's exact-set check of the items card now includes transfers/v1, and the README example names its bundle github.zip. Out-of-tree mutants are all killed: declaration dropped, write_object ignored, write_kinds precedence, reply marker ignored, name unvalidated, client dropping the grant, and an error echoing the grant.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; no blocking issues remain.

Summary

Adds write_object support to data/get, declares accepted write grant kinds, and adds helpers to read upload results.

• A data/get handler can upload its export to one caller-named object.
• Environment cards list the write grant kinds each handler accepts.

Diagram

sequenceDiagram
  participant C as Caller
  participant E as Environment
  participant S as Object store
  C->>E: Read card and accepted write kinds
  C->>E: data/get with write_object
  E->>S: Upload export through grant
  E-->>C: File part with upload result

Loading

_{Reviews (4) · Last reviewed commit: "test(integration): close the grant serve..." · Reviewed by Greptile}