[RFC]: Managed build environments for agent verification

[JWThewes]

Summary

Add managed, immutable build environments for agent verification. The platform ships one protected Standard environment and managed tool definitions rather than separate JVM, Go, Rust, or Polyglot environments. Platform administrators publish exact tool versions, compose them into environments, and project owners assign published environments. Every intent snapshots the exact runtime and toolchain it started with.

Motivation

Agent verification needs predictable toolchains, controlled operating-system packages, immutable provenance, and a stable runtime endpoint across invocation, parallel execution, rewind, cancellation, and session shutdown. Administrators also need to add tools such as .NET without changing platform source or maintaining an opinionated environment for every language combination.

Environment model

Standard contains the protected AgentCore runtime plus Node.js and Python. New environments extend one published base revision and may add:

• exact published tool versions
• exact apt packages
• non-secret environment variables
• restricted ordered build commands

Environment revisions are immutable. They snapshot their pinned base digest, resolved tool-version definitions and OCI digests, generated Dockerfile, image digest, runtime version, endpoint, compatibility version, verification evidence, findings, and acceptance audit.

Project owners assign one published environment. Projects without an explicit assignment use Standard. New intents follow the environment's current published revision; existing intents remain pinned.

Managed tool catalog

Store tool families and immutable tool versions in the environment registry.

A tool family stores its identity, display metadata, category, dependencies, ownership, and explicit recommended-version pointer. A tool version stores:

• exact version and ARM64 source
• original and resolved public URLs
• retained source digest and trust level
• installation definition
• exposed executables
• apt and environment requirements
• version and functional verification
• OCI artifact digest and compressed size
• SBOM, scan findings, logs, and audit fields
• protected core digest and runtime compatibility used for validation

Seed Java 21.0.8, Go 1.24.6, Rust 1.89.0, Maven 3.9.11, and Gradle 9.0.0 as tool definitions. Their initial versions build automatically but require administrator review and publication. Multiple versions may remain published. Publishing does not make a version recommended automatically.

Administrators may add versions to seeded families or create families such as .NET SDK.

Tool creation and verification

Normal creation asks for a name, exact version, public HTTPS ARM64 archive, and verification preset.

The platform:

1. Resolves and validates public redirects.
2. Rejects credential-bearing URLs and private, loopback, metadata, or link-local destinations.
3. Downloads the source in a credentialless, private-network-blocked container.
4. Enforces source, evidence, extraction, and normalized-output limits.
5. Rejects archive traversal, unsafe symlinks, and unsupported layouts.
6. Computes and retains a content-addressed source digest.
7. Normalizes the payload into a dedicated immutable ARM64 OCI artifact.
8. Generates an SBOM and records compressed size.
9. Runs version and representative functional checks as the non-root runtime user.
10. Scans the resulting artifact and retains all evidence.

Publisher verified requires an independently fetched publisher checksum that matches the imported source. Otherwise the catalog records Platform pinned: the retained artifact is immutable, but no independent publisher checksum was supplied.

Presets cover Java, Go, Rust, Maven, Gradle, .NET, and generic CLI tools. Advanced Bash installers run without AWS credentials, metadata access, private-network access, the Docker socket, host mounts, or elevated capabilities. Public internet access is available to the installer, so the published OCI artifact is immutable and verified even when rerunning the installer is not fully reproducible.

Custom functional verification is networkless and supports bounded fixture files.

Dependencies and composition

Environment recipes reference exact {toolId, toolVersionId} pairs. The service resolves and snapshots the complete dependency graph before build.

Maven and Gradle depend on a published recommended Java version. The API rejects:

• missing or cyclic dependencies
• binary-name collisions
• environment-variable conflicts
• conflicting exact apt package versions
• incompatible base revisions
• projected images above the AgentCore size limit

Generated Dockerfiles copy tool payloads from exact OCI digests with multi-stage builds. The final environment is scanned and re-runs every selected tool's version and functional verification against the selected base.

Changing a recommended tool version marks affected environments with a structured update warning. Existing environment revisions and active intents remain pinned. Administrators explicitly edit, build, review, and publish replacements.

Security review

Critical and High findings enter SECURITY_REVIEW; a successful build is not represented as an image-build failure. Platform administrators may explicitly accept findings and continue validation. Findings, severity counts, affected packages, advisory references, acceptance identity, and acceptance time remain visible on ready and published tool and environment revisions.

Only revisions that pass installation, architecture, protected-runtime, non-root, smoke, functional, and AgentCore runtime validation may become ready for publication.

APIs and user experience

Platform Settings provides:

• Tools for family/version creation, source provenance, builds, logs, SBOM, findings, acceptance, publication, and recommendation
• Environments for immutable tool composition, base updates, projected size, builds, verification, publication, and retirement

Project Settings provides a published-environment selector, included tools, and repository compatibility warnings, including .NET repositories. Intent and audit views display exact snapshotted runtime and toolchain evidence.

Compatibility and retention

The platform supports the current and previous runtime compatibility versions. Images, tool artifacts, and endpoints remain available while referenced. Immutable tool artifacts and environment revisions do not follow mutable tags or recommendations.

Historical schema-v1 recipes remain readable for audit but cannot be built, retried, or published. The feature was not released before the tool-catalog model, so no automated destructive migration or reset capability is shipped.

Retirement and reversible archiving remain outside this change.

Operational costs

The design adds DynamoDB records, S3 source and build contexts, separate ECR tool artifacts, ECR scans, ARM64 CodeBuild minutes, CloudWatch logs, Lambda invocations, and AgentCore endpoints. Build roles are isolated by responsibility. Source retention is content-addressed, contexts expire, and non-production repositories are force-deleted only during stack teardown.

Alternatives considered

• Ship one predefined environment per language combination. Rejected because combinations grow rapidly and constrain administrator choice.
• Accept arbitrary administrator Dockerfiles. Rejected because they can replace protected runtime behavior and weaken provenance.
• Install arbitrary tools directly during every environment build. Rejected because downloads, normalization, scanning, and verification would be duplicated and harder to audit.
• Automatically recommend or publish every successful tool version. Rejected because tool updates require explicit administrator review.
• Move existing intents to newer environments. Rejected because active verification must remain reproducible.
• Ship an automated destructive reset. Rejected because the feature had not been released and the sole development deployment could be cleaned manually.

Acceptance criteria

• Standard is the only seeded environment.
• Java, Go, Rust, Maven, and Gradle are seeded as independently buildable, reviewable, publishable tool versions.
• An administrator can import and publish a .NET SDK without changing platform source.
• Tool sources, checksums, redirects, archives, installers, OCI artifacts, SBOMs, findings, sizes, and verification evidence are validated and retained.
• Environments reference exact immutable tool versions and resolve dependencies and conflicts deterministically.
• Recommended-version changes warn affected environments without changing published revisions or active intents.
• Security findings remain visible and may be accepted explicitly without bypassing functional or runtime validation.
• Every intent invocation and shutdown path uses its snapshotted runtime endpoint.
• Platform and project settings expose catalog management, environment composition, assignment, compatibility, and audit evidence.
• No reset API, Lambda, IAM role, route, or UI is shipped.
• Formatting, lint, frontend type checking/build/tests, Lambda tests/bundles, Terraform formatting/validation, secret scanning, CodeQL, and production dependency audits pass.