Skip to content

feat(deploy): pin Box runtimes to AgentCore Runtime V2 - #2879

Open
mquang-amazon wants to merge 2 commits into
box-integrationfrom
box/runtime-v2-platform-version
Open

mquang-amazon wants to merge 2 commits into
box-integrationfrom
box/runtime-v2-platform-version

Conversation

@mquang-amazon

Copy link
Copy Markdown
Contributor

Description

Box runs only on AgentCore Runtime V2. Without platformVersion on CreateAgentRuntime, the service picks the
platform, and its V2 default reaches only the accounts its rollout selects, so a Box runtime can land on V1. This PR
pins every runtime of a Box project to V2.

  • Schema: a runtime can set "platformVersion": "V1" or "V2" (src/projectSchemas/runtime.ts). No default, so
    projects that are not Box projects are unchanged.

  • create / add runtime: agentcore create with a box template, and add runtime in a Box project, write
    "platformVersion": "V2" on the runtime.

  • build and deploy refuse a runtime of a Box project whose platformVersion is not "V2", before the runtime
    sync rewrites agentcore.json:

    runtime "agent" has "platformVersion": "V1" in agentcore.json, but every runtime of a Box project runs on
    AgentCore Runtime V2. Set "platformVersion": "V2" on the runtime in agentcore.json, then retry.
    
  • deploy, after synth: refuses a stack in which a V2 runtime's AWS::BedrockAgentCore::Runtime does not set
    PlatformVersion: "V2". A @aws/agentcore-cdk from before platformVersion drops the field without an error, as
    assertPrivateVpcs guards for containment. The runtime's resource is found through the
    <stack>-<runtime>-RuntimeId export the CDK library writes.

Existing Box projects need "platformVersion": "V2" added to each runtime; build and deploy say so.

Depends on

  • aws/agentcore-l3-cdk-constructs#474, which sets PlatformVersion from the runtime's platformVersion. Until it is
    released and the @aws/agentcore-cdk pin in src/assets/cdk/package.json is bumped, the post-synth check refuses
    every Box deploy, because the pinned library writes no PlatformVersion. Do not merge before that.
  • Touches the same lines of deploy in manager.tsx as feat(deploy): refuse Box projects in regions without AgentCore Runtime V2 #2878 (refuse Box projects in regions without Runtime V2), so
    whichever merges second has a small conflict.

Related Issue

No GitHub issue. Tracked in the Beatbox plan ("Bugs, Findings, AIs", "support Box on Runtime V2 in V2 supported regions
alone").

Documentation PR

Not applicable.

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation update
  • Other (please describe):

Testing

How have you tested the change?

  • I ran bun test: the changed test files pass (manager.test.ts, manager.box.test.ts, assembly.test.ts,
    269 tests). The full run has 31 failures that also fail without this change; my local node_modules has
    @aws-sdk/client-bedrock-agentcore 3.1153.0 instead of ^3.1171.0, and one test needs box on PATH.
  • I ran the relevant end-to-end tests with bun run test:e2e, or explained why they are not applicable
    (CI does not run them for you): not run; a Box deploy needs the L3 release first.
  • I ran bun run typecheck: no errors in the changed files; the 53 it reports also occur without this change
    (same stale SDK).
  • I ran bun run lint:check
  • I ran bun run format:check (on the changed files)
  • I ran bun run audit
  • I ran bun run secrets:check
  • I ran bun run build
  • If I modified src/assets/, I updated affected snapshots with bun test <test-file> --update-snapshots and committed them
  • If I re-recorded fixtures or golden files, every change beyond account identifiers is explained
    by this PR
  • This PR does not change command.md (the release workflow regenerates it)

Tests added: create writes V2 only for box templates; add runtime writes V2; build and deploy refuse a missing
field and V1 and leave agentcore.json unchanged; a project that is not a Box project deploys without the field;
assertPlatformVersions accepts V2 and refuses a missing value, V1, and a runtime with no RuntimeId export. The
export name and Fn::GetAtt shape were checked against a stack synthesized by the L3 branch.

Checklist

  • I have read the CONTRIBUTING document
  • I have added any necessary tests that prove my fix is effective or my feature works
  • I have updated the documentation accordingly
  • I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
  • My changes generate no new warnings
  • Any dependent 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.

Box runs only on AgentCore Runtime V2, and without platformVersion the
service picks the platform, which can be V1.

- A runtime can set "platformVersion": "V1" or "V2". create with a box
  template and add runtime in a Box project write "V2".
- build and deploy refuse a runtime of a Box project whose platformVersion
  is not "V2", before the runtime sync rewrites agentcore.json.
- deploy refuses a stack in which a V2 runtime's
  AWS::BedrockAgentCore::Runtime does not set PlatformVersion, which is what
  a @aws/agentcore-cdk from before platformVersion synthesizes.
@mquang-amazon
mquang-amazon requested a review from a team November 20, 2026 21:16

@leo237 leo237 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @mquang-amazon. First pass from us. I read the diff against box-integration at 2379919, the L3 side (aws/agentcore-l3-cdk-constructs#474 and the v1.1.0 tag the CLI pins), and CI. All CI checks pass, and the branch is up to date with box-integration.

Verdict: COMMENT. The code looks correct to me. It is not merge-ready, because of the dependency the description already names.

Blocking for merge

  1. Unmet hard dependency. aws/agentcore-l3-cdk-constructs#474 is still open (not merged, not released), and src/assets/cdk/package.json in this PR still pins @aws/agentcore-cdk to 1.1.0. I checked v1.1.0: AgentEnvSpecSchema there is a plain z.object, so it strips the unknown platformVersion and synth still succeeds. No ConfigValidationError like the enableApplicationLogs case. But no PlatformVersion gets written either, so assertPlatformVersions will refuse every Box deploy, and create / add runtime now write the field into every new Box project. This PR is not a draft, so nothing stops a merge. Before this can merge, these need to land, in this order: (a) #474 merged into L3 box-integration, (b) an @aws/agentcore-cdk release that includes it, (c) the pin bump in src/assets/cdk/package.json, in this PR or one that merges first. Until then, please convert this PR to draft (or add a do-not-merge label) so the gate is enforced and not only described. Once those land I expect to approve. I have no blocking issue with the code itself.

Non-blocking

  • Public description. This repo is public. Please remove the reference to the internal plan and tracking document from the "Related Issue" section of the description. "No GitHub issue" is enough. The diff and commit message are clean, I found no internal names or URLs in either.
  • Fail-closed behavior, checked. A missing or renamed RuntimeId export, a missing resource, and a non-literal PlatformVersion (Fn::If, Ref) all fail PlatformVersionPropertiesSchema / the equality check and refuse the deploy. Good. The export-name sanitizer matches L3's exportName() in logical-ids.ts, and RuntimeEnvironment.createOutputs exports runtime.runtimeId, so the lookup is sound. Inline notes below cover the error text in the missing-export case and which runtimes get checked.
  • Tests. Small gaps, inline: no schema test (V1/V2 accepted, "v2"/other strings rejected) in src/projectSchemas/runtime.test.ts. The build refusal covers only V1, not a missing field. No multi-runtime case for assertPlatformVersions (one good and one bad runtime, error names only the bad one). No test for a project that is not a Box project but sets "platformVersion": "V2". That project is checked post-synth, and I think that is right, but a test would lock it in.
  • #2878 interaction. Both PRs add Box/V2 gates at the same point in deploy. When you rebase whichever merges second, consider one helper (for example spec check + region check) so the order is explicit. I suggest the region check first, since it does not depend on the user editing agentcore.json.
  • Migration UX. For existing Box projects, the build/deploy message is clear and actionable. An auto-fix (write "V2" during sync for a Box project with no field, with a step message) would be friendlier, but refusing is a reasonable choice. Your call.
  • Docs. README documents containment but not platformVersion. Worth a line once the L3 release is out.
  • Branch sync. This change is not on box-integration-development, and it is not in the squash plan's PR list, so it needs a back-merge there after it lands.

Must-survive fixes (runsInBox/assertBoxRuntimesHaveBoxVersion, assertPrivateVpcs, containment, Box gateway logs notice) are untouched. The diff only adds code. The new tests use tmpdir()/join, spawn nothing and make no AWS calls.

throw new ProjectStateError(
`Runtime ${missing.map((name) => `'${name}'`).join(", ")} has "platformVersion": ` +
`"${platformVersion}", but the synthesized stack does not set it. The @aws/agentcore-cdk ` +
"in agentcore/cdk is older than platformVersion: update it, then deploy again.",

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two nits on this message:

  1. With this PR merged before an L3 release that has platformVersion, "update it" can't succeed: no newer @aws/agentcore-cdk exists yet. That is one more reason to gate the merge on the release and pin bump (see summary). After that, maybe name the minimum version, like "update it to >= X.Y.Z".
  2. The same text is used when the <stack>-<runtime>-RuntimeId export is not found (the last test case). In that case the cause may be an export rename and not an old library, so "the synthesized stack does not set it" / "older than platformVersion" could mislead. Consider a separate message for the no-export case, like "could not find runtime 'x' in the synthesized stack". It still fails closed, which is the right behavior.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 42599ee for the no-export case: it now says "Could not find runtime 'x' in the synthesized stack '', so deploy cannot check that it runs on ..." (still fail closed). For the old-library case I kept the message generic ("update it to a release that has platformVersion"), since there is no L3 release with the field to name yet; I will name the minimum version in the pin bump.

Comment thread src/core/project/backends/cdk.ts Outdated
assemblyDirectory,
artifact,
project.spec.runtimes
.filter((runtime) => runtime.platformVersion === BOX_PLATFORM_VERSION)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only runtimes with platformVersion === "V2" are verified post-synth. Two notes:

  • A project that is not a Box project but sets "V2" explicitly is checked too. I think that is the right fail-closed behavior. Worth one test so nobody narrows it to isBoxProject later.
  • A runtime with an explicit "V1" is not verified, so an old library drops it silently and the service picks. Since the schema accepts V1, consider checking every runtime with a platformVersion against its own value (for example, pass {name, platformVersion} pairs). Then assertPlatformVersions covers what its generic name and signature suggest. Non-blocking.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 42599ee: runtimePlatformVersions picks every runtime that names a platformVersion, in a Box project or not, V1 included, and assertPlatformVersions checks each against its own value. Tests cover the selection (a non-Box V2 and a V1 are picked), V1 and V2 matches, and a two-runtime stack where only the bad runtime is named.

Comment thread src/core/project/boxValidation.ts Outdated
/**
* Throws for a runtime of a Box project whose `platformVersion` is not `"V2"`. Box runs only on
* AgentCore Runtime V2, and without the field the service picks the platform, which can be V1.
* `agentcore create` and `add runtime` write it. Build and deploy call this before they write

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: "before they write anything" is not quite true for deploy. provisionDefaultTarget can write aws-targets.json before this call. Maybe "before the runtime sync rewrites agentcore.json", which matches the call-site comments.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 42599ee: "Build and deploy call this before the runtime sync rewrites agentcore.json."

/** Only with `"containment": "PRIVATE_VPC"`. */
network: ContainedNetworkSchema.optional(),
/** No default. Every runtime of a Box project needs `"V2"`; create writes it. */
platformVersion: PlatformVersionSchema.optional(),

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you add a couple of cases to src/projectSchemas/runtime.test.ts: "V1"/"V2"/missing accepted, "v2" and "V3" rejected? It is a cheap guard on the casing users are most likely to get wrong.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 42599ee: runtime.test.ts accepts V1, V2 and a missing field, and refuses v2, V3 and an empty string.

Comment thread src/core/project/manager.test.ts Outdated
expect(existsSync(join(aws, "resources", "shared"))).toBe(false);
});

test("refuses a Box runtime that is not on AgentCore Runtime V2, before anything is written", async () => {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The deploy tests cover both missing and V1, but build covers only V1. A test.each here over missing/V1, like the deploy test, would cover the more common migration case (an existing Box project with no field).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 42599ee: the build refusal is a test.each over a missing platformVersion and V1.

@codecov-commenter

codecov-commenter commented Nov 20, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.80%. Comparing base (e2ac9d7) to head (42599ee).
⚠️ Report is 12 commits behind head on box-integration.

Additional details and impacted files
@@               Coverage Diff                @@
##           box-integration    #2879   +/-   ##
================================================
  Coverage            96.79%   96.80%           
================================================
  Files                  766      766           
  Lines                66803    66879   +76     
================================================
+ Hits                 64665    64741   +76     
  Misses                2138     2138           

☔ 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.

- Check every runtime that names a platformVersion after synth, V1 included
  and not only in a Box project (runtimePlatformVersions), each against its
  own value.
- A runtime the stack exports no RuntimeId for gets its own message, since
  the cause may be a renamed export, not an old CDK library.
- Test the schema's accepted and refused values, and the build refusal for a
  Box runtime with no platformVersion as well as V1.
- The validation comment says the check runs before the runtime sync
  rewrites agentcore.json.
@mquang-amazon
mquang-amazon marked this pull request as draft November 21, 2026 01:06
@mquang-amazon
mquang-amazon marked this pull request as ready for review November 21, 2026 01:07

@leo237 leo237 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-review at 42599ee. Thanks for the follow-up commit: the post-synth check now covers every runtime that names a platformVersion (V1 included, Box or not), a missing RuntimeId export gets its own message, the schema tests cover "v2"/"V3"/"", the build refuses a Box runtime with no field, and there's a multi-runtime test. The JSDoc wording is fixed too.

Still blocking: the aws/agentcore-l3-cdk-constructs#474 dependency. #474 is still open. No released @aws/agentcore-cdk writes PlatformVersion: the branch pins 1.1.0, and base's 1.2.0 doesn't write it either (I checked the published 1.2.0 tarball). The new commit doesn't add a capability check, version gate, or warn-instead-of-refuse fallback. So if this merges now, every Box deploy fails after synth, and create/add write a field that every deploy then rejects. This now also affects any non-Box project that sets platformVersion. The body says "Do not merge before that", but the PR isn't a draft and has no label, so nothing stops a merge. Please mark it draft (or add a do-not-merge label) until #474 is released and the pin is bumped, or degrade safely when the installed library can't write the field.

Non-blocking, still open:

  • The "Related Issue" section still names an internal plan. Please replace it with a generic note. (The commit messages are clean.)
  • The "update it to a release that has platformVersion" message points at a release that doesn't exist yet (inline).
  • README/docs don't mention platformVersion.
  • The branch is behind box-integration (pin 1.1.0 vs 1.2.0). It merges cleanly, but please back-merge.
  • FYI: a trial merge with #2878's head conflicts in boxValidation.ts, manager.tsx, and manager.test.ts. The suggestion to combine the two gates (region check first) still stands.

CI: Analyze, Windows, and CodeBuild e2e pass. Linux and macOS were still pending when I posted.

if (synthesized?.PlatformVersion === platformVersion) return [];
return [
`Runtime '${name}' has "platformVersion": "${platformVersion}", but the synthesized stack ` +
"does not set it. The @aws/agentcore-cdk in agentcore/cdk is older than platformVersion: " +

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No @aws/agentcore-cdk release has platformVersion yet (1.2.0 is the latest, and it doesn't). Until one does, this tells users to do something they can't. Consider naming the minimum version once it ships, or saying the support isn't released yet.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants