[notgitika]

Description

Implements the CLI portion of the pre-built Runtime container image design from #2718.

A Runtime can set containerUri with build: "Container" to deploy an existing private or public ECR image. The CLI validates that configuration and skips preparation that belongs only to local Dockerfile builds.

Implementation

• Adds the mirrored Runtime containerUri schema using the same ECR URI validation as Harness.
• Rejects containerUri on CodeZip and rejects combining it with dockerfile, buildContextPath, or customDockerBuildArgs.
• Prevents build synchronization from inferring a Dockerfile for pre-built images.
• Skips local code-folder, manifest, Dockerfile, build-context, CodeBuild VPC-ID, and five-security-group checks for the pre-built path.
• Retains Runtime networking validation because it still applies to the deployed Runtime.

Related work

• Design: docs(runtime): propose pre-built container image deployment #2718
• CDK implementation: aws/agentcore-l3-cdk-constructs#440
• Tracking issue: Support pre-built container image URI in agentcore deploy (skip CodeBuild) #503

Delivery dependency

This PR remains draft until the companion CDK change is released. Before merge, src/assets/cdk/package.json must be updated from @aws/agentcore-cdk 1.0.0 to the release containing aws/agentcore-l3-cdk-constructs#440.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other

Testing

• bun test — 4,721 passed; 6 Windows-only tests skipped
• bun run typecheck
• bun run lint:check
• bun run format:check
• bun run build
• Runtime end-to-end deployment — requires the published companion CDK package

Checklist

• I have read the CONTRIBUTING document
• I have added necessary tests that prove the feature works
• My changes generate no new warnings
• Dependent CDK changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

Package Tarball

aws-agentcore-1.0.1.tgz

How to install

gh release download pr-2719-tarball --repo aws/agentcore-cli --pattern "*.tgz" --dir /tmp/pr-tarball
npm install -g /tmp/pr-tarball/aws-agentcore-1.0.1.tgz

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.54%. Comparing base (fe7a568) to head (2fbdf13).

Additional details and impacted files

@@            Coverage Diff            @@
##           refactor    #2719   +/-   ##
=========================================
  Coverage     96.54%   96.54%           
=========================================
  Files           706      707    +1     
  Lines         58561    58600   +39     
=========================================
+ Hits          56539    56578   +39     
  Misses         2022     2022           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Changes requested

Reviewed against base refactor (head 2fbdf13). The schema/sync/prepare changes themselves are clean, well-scoped, and the tests use real temp dirs rather than fs mocks — good. Three things need resolving before this lands.

1. agentcore dev is left undefined for a pre-built runtime

runtimeProblems now returns early for any containerUri runtime (src/core/project/runtimeBuild.ts:589) and prepareRuntimes skips the code-folder check (src/core/project/runtimeBuild.ts:551) for both purposes, including "dev". But runner selection still routes build: "Container" to ContainerDevRunner (src/handlers/project/index.ts:66), which unconditionally builds from a local Dockerfile (src/core/dev/container.ts:78-91). So for a pre-built runtime:

• with no local source (the normal pre-built case, which this PR explicitly makes legal): agentcore dev now fails with the low-level no container build context directory exists at <path> / no container Dockerfile exists at <path> instead of the README-pointing ProjectStateError the prepare step used to produce;
• with a leftover Dockerfile in codeLocation: dev silently builds and runs an image that has nothing to do with the containerUri that will be deployed.

Options:

• gate it like the BMA case — make supportsLocalDev (src/handlers/project/dev/index.ts:71) false for containerUri runtimes and raise the existing NotImplementedError with a clear message;
• keep the Dockerfile/code-folder checks when purpose === "dev" and only skip them for "deploy", so the existing guidance still fires;
• teach ContainerDevRunner to docker run the pre-built image instead of building.

Any of these is fine, but the current state is an unhandled path for the config this PR introduces.

2. Confirm the relaxed VPC rules are mirrored in the released CDK

src/projectSchemas/runtime.ts:339 makes both the CodeBuild vpcId requirement and the five-security-group cap conditional on containerUri === undefined. In the currently published @aws/agentcore-cdk@1.0.0, AgentEnvSpecSchema still gates both on data.build === 'Container' alone, so a networkMode: "VPC" pre-built runtime without vpcId (or with 6+ SGs) would pass CLI validation and then fail inside readAgentCoreProject at synth. Please confirm aws/agentcore-l3-cdk-constructs#440 relaxes the schema side identically — these are explicitly mirrored schemas, and the design doc requires both to enforce the same rules.

Related consistency point: HarnessSpecSchema still uses isContainerBuild(data) (true when containerUri is set) for the SG cap, so runtime and harness now disagree about whether a pre-built image is subject to CodeBuild limits. Worth aligning or noting why they differ.

3. Bumping src/assets/cdk/package.json is not enough — old pins silently drop containerUri

AgentEnvSpecSchema in the published CDK is a non-strict z.object, so an unknown containerUri on a runtime is stripped, not rejected. The vended agentcore/cdk/package.json is only written at create/migrate time, so an existing project still pinned to @aws/agentcore-cdk@1.0.0 that adds containerUri will not error: the CLI now skips the Dockerfile existence check, the CDK ignores the field, and the build falls back to the source-asset → CodeBuild path (failing at build time, or worse, succeeding against a stale local Dockerfile and deploying the wrong image).

There is already a mechanism for this: MINIMUM_COMPATIBLE_CDK_VERSION / cdkCompatibilityWarning in src/core/project/backends/cdk/compatibility.ts (surfaced at src/core/project/backends/cdk.ts:219). Options:

• bump MINIMUM_COMPATIBLE_CDK_VERSION to the release containing #440 when you bump the vended pin;
• or add a feature-specific check that hard-fails (not just warns) when any runtime has containerUri and the installed @aws/agentcore-cdk predates support, with an "update agentcore/cdk/package.json" message.

Silent misdeployment is the failure mode here, so I'd lean toward an error rather than a warning.

Minor (non-blocking)

• runtimeProblems computes folder/folderLabel before the containerUri early return (src/core/project/runtimeBuild.ts:586-589) — dead work.
• A pre-built runtime with a Dockerfile sitting in codeLocation now gets no feedback that the file is ignored; a sync warning would make the chosen image source obvious (and would also explain the dev behavior if you pick option 3 above for #1).