(compute): repo-defined development environments from repository configuration

[krokoko]

Component

CDK / infrastructure

Describe the feature

Establish a clear environment resolution hierarchy for every onboarded repo:

1. Platform default — A maintained base agent image ships with the CDK stack and works out of the box for repos with no extra configuration (same as today, but explicit in Blueprint and docs).
2. Blueprint override — Operators can point a repo at a custom image (ECR URI, built artifact digest, or reference to a repo-local spec) via Blueprint props without every repo owner authoring a full manifest on day one.
3. Repo-defined spec (optional) — When present, a version-controlled manifest in the repository (for example, Dev Container or Dockerfile) becomes the source of truth and supersedes the Blueprint image override except where Blueprint explicitly pins a digest for reproducibility.

The compute layer should resolve this stack at task start so every task runs with predictable runtimes, system packages, and setup hooks.

Today, agent tasks largely share a common container image with limited per-repo customization via Blueprint (compute.type, runtimeArn only). There is no documented default-vs-override model, and repos that need specific toolchains must wait for a bespoke image path rather than opting in gradually.

Use case

I'm always frustrated when an agent task fails because the sandbox lacks a dependency that exists in the repo's CI workflow or local dev setup. Operators should not have to fork the platform image or hand-maintain Blueprint overrides for every toolchain variation. Reproducible, repo-authored environment definitions would reduce false failures, shorten debugging cycles, and make alternative compute backends (for example, ECS when image size exceeds AgentCore limits) a natural extension of onboarding rather than a special case.

Proposed solution

1. Default image contract — Document the platform base image (toolchain versions, preinstalled CLIs, size limits). Blueprint compute.image defaults to platform with no operator action required for new repos.
2. Blueprint override — Add Blueprint props, for example compute.image: 'platform' | { ecrUri, digest? } | { fromRepoSpec: 'devcontainer' | 'dockerfile', path? }. Persist resolved policy in RepoConfig.
3. Repo-side manifest — When fromRepoSpec is used or a manifest is detected at a conventional path, build or select the image from that file. Manifest wins over a bare ECR override unless Blueprint pins digest.
4. Resolution order — Document and implement: pinned digest → repo manifest (if enabled) → Blueprint ECR override → platform default. Record the resolved image id on the task for audit.
5. Image build path — On Blueprint deploy or on a scheduled pre-warm job, build/push repo-specific images to ECR when a manifest or Dockerfile is present.
6. ComputeStrategy integration — AgentCore and ECS strategies consume the resolved image at session start. Pass environment metadata (install commands, test command hints) into workflow context hydration.
7. Pre-warm hook — Tie into roadmap "Environment pre-warming": snapshot or rebuild on default-branch updates.
8. Validation at onboarding — Preflight or Blueprint synth checks that specs parse and fit the chosen compute backend (image size, GPU, etc.).

Acceptance criteria

• Platform default image is documented; Blueprint exposes compute.image (or equivalent) with platform as the default—existing repos behave unchanged.
• Operators can override the default via Blueprint (ECR URI and/or repo manifest reference) without adding files to the target repo.
• Repos with a repo-side manifest use that spec when enabled; resolved image digest is recorded on the task.
• Resolution precedence is documented and covered by unit tests.
• Design docs and operator guide describe authoring, size limits, and compute-backend constraints.
• Tests cover manifest parsing, Blueprint wiring, and at least one end-to-end task using a custom environment fixture.

Other information

• Related roadmap: Environment pre-warming, Alternative compute (ComputeStrategy, ECS path).
• Related design: docs/design/COMPUTE.md, docs/design/REPO_ONBOARDING.md.
• Alternatives considered: per-repo Dockerfile only in Blueprint CDK (harder for repo owners to maintain); runtime mise install on every task (slow, non-deterministic).

Acknowledgements

• I may be able to implement this feature
• This might be a breaking change