Skip to content

feat(deploy): refuse Box projects in regions without AgentCore Runtime V2 - #2878

Open
mquang-amazon wants to merge 3 commits into
box-integrationfrom
box/runtime-v2-regions
Open

mquang-amazon wants to merge 3 commits into
box-integrationfrom
box/runtime-v2-regions

Conversation

@mquang-amazon

@mquang-amazon mquang-amazon commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Description

Box runs only on AgentCore Runtime V2 (platformVersion: "V2"). agentcore deploy now refuses a
Box project ("projectType": "box") whose target is in a region without V2. The check runs as
soon as the target is known, before the runtime sync rewrites agentcore.json and before any
build or AWS call:

Cannot deploy Box project 'example' to target 'primary' in us-west-1: Box runs on AgentCore
Runtime V2, which is not available in us-west-1. Set a target in another region in
agentcore/aws-targets.json, then retry.

Blocked: ap-south-2 (Hyderabad), us-west-1 (N. California), the aws-us-gov partition, and
the isolated partitions (aws-iso, aws-iso-b, aws-iso-f). The list is a denylist in
src/core/partition.ts (supportsRuntimeV2), so a region the CLI does not know counts as having
V2 and needs no CLI release; remove a region from the list once V2 launches there. Projects that
are not Box projects are unaffected.

Where the region list comes from

AgentCore Runtime rejects platformVersion: "V2" with PLATFORM_VERSION_V2_NOT_AVAILABLE in a
region where V2 has not launched. The AgentCore Runtime team confirmed that V2 is available in
every region where AgentCore Runtime is
(https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-regions.html) except
Hyderabad (ap-south-2), N. California (us-west-1) and AWS GovCloud. It is not available in the
isolated partitions either. China (cn-north-1, cn-northwest-1) has V2, so it is not blocked.

A follow-up in the CDK library pins PlatformVersion: "V2" on the runtimes of a Box project. With
that pin, CloudFormation would also fail in these regions, but only after build and upload, and
with a stack rollback instead of this message.

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: src/core/partition.test.ts and src/core/project/manager.test.ts pass
    (231 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.
  • 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; the check fires before any AWS call.
  • I ran bun run typecheck: no errors in the changed files; the 53 errors it reports also occur
    without this change (same stale SDK).
  • I ran bun run lint:check
  • I ran bun run format:check: the changed files are formatted (the pre-commit hook ran
    Prettier on them).
  • 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)

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.

…e V2

Box runs only on AgentCore Runtime V2 (platformVersion V2). Deploy now
refuses a Box project whose target is in a region without V2
(ap-south-2, us-west-1, GovCloud, and the isolated partitions), before
the runtime sync rewrites agentcore.json. Other regions, including new
ones the CLI does not know, are allowed.
@mquang-amazon
mquang-amazon requested a review from a team November 20, 2026 20:42

@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 for this. The check is small and in the right place: deploy() resolves exactly one target (--target, or the synthesized default), and assertBoxRegionSupported runs on that target's region before syncRuntimeBuilds, applyBoxNetwork and the backend. Every later step reads target.region, so no other region source (such as AWS_REGION) gets past the check. A multi-target project is refused only for the bad target. The manager test confirms that agentcore.json stays unchanged and that the backend is never called. The unit tests cover every denylisted region and partition and pass a region the CLI does not know. Failing open for unknown regions is documented, and I think it is the right choice. The must-survive Box fixes (assertBoxRuntimesHaveBoxVersion / runtimeRunsInBox, per-runtime profiles, --containment, the logs notice) are untouched.

Resolved during review

  1. Internal names in a committed code comment. The first commit's JSDoc in src/core/partition.ts named an internal-only package and a config path. ceb0a75b removed them, so the current head is clean. That first commit still has the text, so please squash-merge, which keeps it out of the box-integration history.

Non-blocking (approving; none of these block)

  1. PR description: please remove the internal-only links. The "Where the region list comes from" section links to internal source and config files and names internal flags and validators. Please drop those links and names from the public description. The public AgentCore Regions link plus a short sentence is enough.
  2. Default-target path runs before the check. When no target exists and --target is default, provisionDefaultTarget calls STS (resolveAccount) and writes agentcore/aws-targets.json, and only then does the new check refuse. So "before any build or AWS call" in the description holds only for configured targets. This does no harm, and the message tells the user to edit that file. Still, you could run supportsRuntimeV2(input.region) for a Box project before provisioning, or reword the description. A test for this path (no aws-targets.json, Box project, region: "us-west-1") would pin whichever behavior you choose.
  3. aws-iso-e and aws-eusc are not in the partition denylist. The SDK partition data the CLI uses (@aws-sdk/core 3.978.0) defines aws-iso-e (eu-isoe-*) and aws-eusc (eusc-de-*) as well. Neither is denylisted, so they count as having V2. The comment says "the isolated partitions", but aws-iso-e is missing from that set. If leaving them out is intended (fail-open), please say so in the comment. Otherwise add them, and add an eu-isoe-west-1 case to the test.
  4. Error message wording. "Set a target in another region in agentcore/aws-targets.json" has the right path, but it is a bit vague. Something like "Change the region of target 'primary' in agentcore/aws-targets.json, or deploy with --target to a target in another region" names both ways out.
  5. Create/add do not warn. agentcore create / add of a Box project with --region us-west-1 still succeed, and the user learns about the problem only at deploy. A follow-up notice at create time would be friendly. This is out of scope here.
  6. Branch hygiene. The branch is a few commits behind box-integration (no conflicts). The change is not on box-integration-development, so it will need a back-merge there to keep the two branches in sync. The CDK follow-up that pins PlatformVersion: "V2" is fine as a separate PR.

CI at review time: CodeQL: pass; verify / Linux: pending; verify / Windows: pending; verify / macOS: pending; Analyze: pass; AWS CodeBuild us-east-1 (agentcore-e2e): pass. Please merge only after verify is green on all three OSes.

Comment thread src/core/partition.ts Outdated
* the AgentCore Runtime team's; remove a region here once V2 launches in it.
*/
const NO_RUNTIME_V2_REGIONS: ReadonlySet<string> = new Set(["ap-south-2", "us-west-1"]);
/** Partitions with no V2 in any region: GovCloud, and the isolated (ADC) partitions. */

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Non-blocking: the SDK partition data also defines aws-iso-e (eu-isoe-*), and aws-eusc too. They are not in this set, so they count as having V2. If that is intended, please say so in the comment. Otherwise add them, and add an eu-isoe-west-1 test case.

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 6f78b4f: aws-iso-e is in the set, with an eu-isoe-west-1 case. aws-eusc is left out on purpose, and the comment says so: like a region the CLI does not list, it counts as having V2 (fail open), with an eusc-de-east-1 case pinning that.

}

// Box runs only on AgentCore Runtime V2, so stop before the sync rewrites agentcore.json.
assertBoxRegionSupported(project.spec, target);

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Non-blocking: this check is in the right place for a configured target. But for a fresh project, provisionDefaultTarget (above) has already called STS and written aws-targets.json by the time we get here. You could check input.region for a Box project before provisioning, or reword "before any AWS call" in the description. Either way, a test for the default-target path would pin it.

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 6f78b4f: a Box project is checked against input.region before provisionDefaultTarget, so an unsupported region makes no STS call and writes no aws-targets.json. A test covers that path (no aws-targets.json, Box project, us-west-1): resolveAccount is never called and the file is not written.

Comment thread src/core/project/boxValidation.ts Outdated
throw new RegionUnsupportedFeatureError(
`Cannot deploy Box project '${spec.name}' to target '${target.name}' in ${target.region}: ` +
`Box runs on AgentCore Runtime V2, which is not available in ${target.region}. ` +
`Set a target in another region in agentcore/aws-targets.json, then retry.`,

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: maybe "Change the region of target '' in agentcore/aws-targets.json, or deploy with --target to a target in another region, then retry." That names both ways out.

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 6f78b4f: "Change the region of target '' in agentcore/aws-targets.json, or deploy with --target to a target in another region, then retry." For the default target that deploy would create, it says to deploy with --region, or add a target in another region.

@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.79%. Comparing base (76261f6) to head (6f78b4f).
⚠️ Report is 22 commits behind head on box-integration.

Additional details and impacted files
@@                 Coverage Diff                 @@
##           box-integration    #2878      +/-   ##
===================================================
+ Coverage            96.78%   96.79%   +0.01%     
===================================================
  Files                  766      766              
  Lines                66590    66800     +210     
===================================================
+ Hits                 64452    64662     +210     
  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.

- Refuse a Box project before deploy provisions the default target, so an
  unsupported --region makes no STS call and writes no aws-targets.json.
- Add aws-iso-e to the partitions with no Runtime V2, and say that the
  European Sovereign Cloud counts as having it, as an unknown region does.
- The error names both ways out: change the target's region, or deploy with
  --target to another target; for the default target, --region.

@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 of 6f78b4f. Still approved. Please merge only after verify / Linux|Windows|macOS pass; they were pending when I posted. CodeQL, Analyze and the CodeBuild e2e job pass.

Addressed

  • Ordering: for a new project, the check now runs before provisionDefaultTarget, so a refused region makes no STS call and writes no aws-targets.json. The new test checks both: resolveAccount is never called and the file does not exist afterwards.
  • Partitions: aws-iso-e is now on the denylist. I checked the SDK version this repo locks (@aws-sdk/core 3.978.0 partition data): it maps eu-isoe-west-1 to aws-iso-e and eusc-de-east-1 to aws-eusc, so both new test cases test real behavior. Leaving aws-eusc off on purpose, with a comment saying why, is a reasonable choice.
  • Error message: it now names both fixes (change the target's region, or use --target), and the default-target case gets a --region hint. The tests assert the full text.
  • Commit messages: no internal references.

Still open (non-blocking)

  • PR description: it still names an internal planning doc under "Related Issue". Please replace that with a generic line. The description is also out of date: it shows the old error text, leaves out aws-iso-e, and still says "before any build or AWS call" without mentioning the default-target case.
  • A friendly warning in create/add for a Box project in a blocked region is still a follow-up.
  • Please squash-merge and back-merge to box-integration-development, as discussed.

FYI
The branch merges cleanly into box-integration (it is 21 commits behind). A trial merge with #2879 conflicts in boxValidation.ts and manager.test.ts; manager.tsx auto-merges. Whichever PR lands second will need a rebase.

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