feat(store): each object store sets how long its transfer grants last, 12 hours by default

[earakely-scale]

Summary

Each object store now sets how long its transfer grants last, instead of agent-env asking for a fixed hour. The default is 12 hours.

• A setting on every built-in store. S3ObjectStore, GcsObjectStore and LocalFilesystemObjectStore take grant_lifetime_seconds in their config table (default 43200), and it applies to read and write grants. A caller can still pass expires_in. ObjectStore.grant_lifetime_seconds carries the default for other stores.

  [stores.object]
  impl = "agent_env.store.object_store:S3ObjectStore"
  config = { bucket = "<bucket>", grant_lifetime_seconds = 3600 }

• agent-env no longer picks the lifetime. write_object, read_object and the validator's probe call issue_write_grant / issue_read_grant without expires_in, whose default is now None, meaning the store's setting. GRANT_LIFETIME_SECONDS is gone.

  • Under @local routing, each grant is issued, and timed, by the store that owns its object. expires_in is passed on only when the caller named one, so a custom store's own default is left alone.
  • A custom store that kept its own expires_in default still behaves exactly as before.

• Checked when the store is made. The value must be a whole number of seconds and at least 15 minutes (MIN_GRANT_LIFETIME_SECONDS), which outlasts the 10 minutes agent-env waits for a transfer. It can be no more than the store can sign: 7 days for S3's SigV4, for GCS 12 hours when signing through IAM or 7 days with a key, and 7 days for the local store. 12 hours is exactly the GCS IAM maximum, so the default is valid on every store.

  • An S3 grant signed with temporary credentials still ends when they do, and its expires_at says so.
  • Local grants still end when the process that issued them exits.

• Unchanged: the changelog upload policy. It keeps lasting the agent's TTL, which it must cover for the whole capture.

Longer grants mean a leaked grant URL stays valid longer. Deployments that want the old window can set grant_lifetime_seconds = 3600.

Test plan

• pytest tst/unit packages/agentenv-protocol/tests -n auto: 6029 passed.
  • The 12-hour default; a configured lifetime on S3, GCS and the local store (the local case through its real grant server); a caller's explicit expires_in still honoured.
  • Invalid values refused at construction: non-integers, anything under 15 minutes, S3's and the local store's 7-day cap, and GCS's IAM and key caps. The floor stays above the transfer timeout.
  • @local routing leaves a custom store's own expires_in default alone.
  • agent-env's read and write grants following the issuing store; @local routing following the owning store; and the setting read from [stores.object] config.
• pytest -m 'not int_test_slow' tst/integration --ignore=tst/integration/env/gateway/gateway_test.py: 141 passed.
• Plugin API check against the base: no break.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; the earlier grant-lifetime findings are addressed.

What we checked:

• Custom store default survives routing: No. Routing omits expires_in when the caller leaves it out, so the custom store uses its own default.
• Short store grants are refused: The setting must be at least 15 minutes; the transfer wait is 10 minutes.

Summary

Object stores now choose how long read and write transfer grants last, with a 12-hour default. Agent-env leaves the expiry to the store that issues each grant unless a caller supplies one.

• Built-in stores set how long transfer grants last.
• Agent-env lets the store issuing a grant choose its expiry.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Transfer caller] --> B[Object store]
  B --> C{Caller named a lifetime?}
  C -->|Yes| D[Use caller's lifetime]
  C -->|No| E[Use issuing store's default]
  D --> F[Issue grant]
  E --> F

Loading

_{Reviews (8) · Last reviewed commit: "Merge main into store-grant-lifetime"}