build(store)!: make boto3 the optional aws extra and import the AWS store backends on first use

[earakely-scale]

Summary

A plain pip install agentenv-framework no longer installs boto3. The AWS backends (S3, Secrets Manager, ECR, DynamoDB) move to a new aws extra (boto3, botocore), and dev includes it.

• Lazy re-exports. S3ObjectStore, AwsSecretsManagerSecretStore and DynamoDbDocumentStore are imported on first use, at agent_env.store and their sub-packages, through a small store/_lazy.py.
  • With boto3 installed, old import paths and impl pointers work as before.
  • Without it, both from … import and an impl pointer fail with …; it needs the 'aws' extra, as in pip install 'agentenv-framework[aws]'.
  • The three names are left out of __all__, so import * of a store package works on a bare install.
• One install hint. The impl loader's hint logic becomes missing_extra(error) / install_hint(error). The loader, the lazy names and ECR all use it.
• ECR. boto3 is imported only when building a client, so EcrCredentials(client=...) needs no boto3. Building a client without it raises a ConfigError that names the extra.
• snapshot_env. _push_s3_credentials returns quietly without boto3, since no store can then be an S3 one.

Breaking changes

• Installs that use the AWS backends must ask for agentenv-framework[aws], unless something else already brings in boto3.
• from agent_env.store import * no longer brings in S3ObjectStore, AwsSecretsManagerSecretStore or DynamoDbDocumentStore, even with boto3 installed.

Testing

• Unit suite, after merging main (including the sail extra): 6767 passed, 13 skipped, run in a venv synced from this branch so the installed metadata declares the aws and sail extras. The DynamoDB store's tests run unchanged from main.
• test_optional_extras_stay_optional.py now covers aws (S3, Secrets Manager and DynamoDB, by impl pointer and re-export), plus four new cases:
  • AWS impl pointers name the extra;
  • each lazy name raises naming the extra;
  • import * of every store package works without boto3;
  • ECR with and without a supplied client.
• make clean-install-test: passes (build, plain install, hello twice), unchanged from main. The unit tier's test_core_and_every_store_module_import_without_the_extra[aws] proves every core module imports without the aws extra.
• Downstream: the test suites of four services built on this package (about 6,200 tests, all with boto3 installed through their own dependencies) give identical results against this branch and against main.
• Plugin API check: no break reported. Packaging isn't on the plugin surface, so the title marks the break by hand.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; no outstanding finding remains.

Summary

Plain installs no longer require AWS packages; users add the aws extra to use S3, Secrets Manager, DynamoDB, or ECR. Store packages load AWS backends only when requested, and ECR and snapshot code can run without importing the AWS SDK when it is not needed.

• Plain installs leave AWS packages out until users ask for the aws extra.
• Store packages load AWS backends only when someone asks for them.
• ECR credentials wait to import boto3 until they need to build a client.
• Snapshot code skips S3 credential sharing when the AWS backend is unavailable.

_{Reviews (6) · Last reviewed commit: "chore(config): keep missing_extra privat..." · Reviewed by Greptile}