From a08268aa5f12a43a559da0b177e50cf06a62b692 Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Fri, 20 Nov 2026 12:41:10 -0800 Subject: [PATCH 1/3] feat(deploy): refuse Box projects in regions without AgentCore Runtime 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. --- src/core/partition.test.ts | 24 +++++++++++++++++++++++- src/core/partition.ts | 25 +++++++++++++++++++++++++ src/core/project/boxValidation.ts | 19 ++++++++++++++++++- src/core/project/manager.test.ts | 31 +++++++++++++++++++++++++++++++ src/core/project/manager.tsx | 5 ++++- 5 files changed, 101 insertions(+), 3 deletions(-) diff --git a/src/core/partition.test.ts b/src/core/partition.test.ts index 7275bf0827..69952b2d65 100644 --- a/src/core/partition.test.ts +++ b/src/core/partition.test.ts @@ -2,7 +2,7 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test"; import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; -import { isChinaContext, isChinaRegion } from "./partition"; +import { isChinaContext, isChinaRegion, supportsRuntimeV2 } from "./partition"; describe("isChinaRegion", () => { test.each(["cn-north-1", "cn-northwest-1"])("returns true for %s", (region) => { @@ -14,6 +14,28 @@ describe("isChinaRegion", () => { }); }); +describe("supportsRuntimeV2", () => { + // ap-east-9 is not a region: one this CLI does not know of counts as having V2. + test.each(["us-west-2", "us-east-1", "eu-west-1", "cn-north-1", "ap-east-9"])( + "returns true for %s", + (region) => { + expect(supportsRuntimeV2(region)).toBe(true); + }, + ); + + test.each([ + "ap-south-2", + "us-west-1", + "us-gov-west-1", + "us-gov-east-1", + "us-iso-east-1", + "us-isob-east-1", + "us-isof-south-1", + ])("returns false for %s", (region) => { + expect(supportsRuntimeV2(region)).toBe(false); + }); +}); + describe("isChinaContext", () => { let savedRegion: string | undefined; let savedDefaultRegion: string | undefined; diff --git a/src/core/partition.ts b/src/core/partition.ts index e2657d26e9..1c18a7d5c5 100644 --- a/src/core/partition.ts +++ b/src/core/partition.ts @@ -14,6 +14,31 @@ export function isChinaRegion(region: string): boolean { return partition(region).name === "aws-cn"; } +/** + * Regions where AgentCore Runtime offers no platformVersion V2. Box runs only on V2. The source + * of truth is the `runtimeVersion` flag in YggdrasillControlPlaneServiceConfigCDK + * (configuration/dynamic-configuration/feature-flags/prod-.json): a region without it has + * no V2. Remove a region here once V2 launches in it. + */ +const NO_RUNTIME_V2_REGIONS: ReadonlySet = new Set(["ap-south-2", "us-west-1"]); +/** Partitions with no V2 in any region: GovCloud, and the isolated (ADC) partitions. */ +const NO_RUNTIME_V2_PARTITIONS: ReadonlySet = new Set([ + "aws-us-gov", + "aws-iso", + "aws-iso-b", + "aws-iso-f", +]); + +/** + * Whether AgentCore Runtime offers platformVersion V2 in `region`. A region not listed counts as + * having V2, so a new region needs no CLI release; one without V2 fails at CreateAgentRuntime. + */ +export function supportsRuntimeV2(region: string): boolean { + return ( + !NO_RUNTIME_V2_REGIONS.has(region) && !NO_RUNTIME_V2_PARTITIONS.has(partition(region).name) + ); +} + /** * True when the CLI is operating in a China (aws-cn) context: the caller's * resolved region (when provided — telemetry resolves through the same chain diff --git a/src/core/project/boxValidation.ts b/src/core/project/boxValidation.ts index 6339514039..075685ceae 100644 --- a/src/core/project/boxValidation.ts +++ b/src/core/project/boxValidation.ts @@ -3,8 +3,9 @@ * agent with no box. The runtime sync asks the sync rules before it writes agentcore.json, and * build and deploy call {@link validateBoxRuntimes} before they read the box profiles. */ -import { ProjectStateError } from "../../errors/errors"; +import { ProjectStateError, RegionUnsupportedFeatureError } from "../../errors/errors"; import { isBoxProject, type ProjectSpec } from "../../projectSchemas/project"; +import { supportsRuntimeV2 } from "../partition"; import type { ProjectRuntime } from "../../projectSchemas/runtime"; import { BOX_RELEASE } from "./backends/boxRelease"; import { BOX_CODEZIP_ENTRYPOINT, runsInBox } from "./templates/boxProfile"; @@ -100,3 +101,19 @@ export function validateBoxRuntimes(spec: ProjectSpec): void { assertBoxRuntimesHaveBoxVersion(spec); assertBoxCodeZipRuntimesStartBox(spec); } + +/** + * Throws for a Box project deployed to a region where AgentCore Runtime has no platformVersion V2. + * Box runs only on V2, so the runtimes could not be created there. + */ +export function assertBoxRegionSupported( + spec: ProjectSpec, + target: { name: string; region: string }, +): void { + if (!isBoxProject(spec) || supportsRuntimeV2(target.region)) return; + 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.`, + ); +} diff --git a/src/core/project/manager.test.ts b/src/core/project/manager.test.ts index 99f66dc187..4238687ec1 100644 --- a/src/core/project/manager.test.ts +++ b/src/core/project/manager.test.ts @@ -1567,6 +1567,37 @@ describe("FsProjectManager.addResource", () => { expect(deployCalls).toEqual([]); }); + test.each(["ap-south-2", "us-west-1", "us-gov-west-1"])( + "deploy of a Box project to %s fails before anything is written", + async (region) => { + await inTempDirectory(); + const { subject, project, deployCalls } = await projectWithTarget( + region, + undefined, + AGENT_PYTHON_STRANDS_BOX, + ); + const specPath = join(project.rootPath, "agentcore", "agentcore.json"); + const before = await readFile(specPath, "utf8"); + + const { error } = await deployOutcome(subject, project); + expect(error).toBeInstanceOf(RegionUnsupportedFeatureError); + expect(String(error)).toContain( + `Cannot deploy Box project 'example' to target 'primary' in ${region}`, + ); + expect(await readFile(specPath, "utf8")).toBe(before); + expect(deployCalls).toEqual([]); + }, + ); + + test("deploy of a project that is not a Box project to us-west-1 is not refused", async () => { + await inTempDirectory(); + const { subject, project, deployCalls } = await projectWithTarget("us-west-1"); + + const { error } = await deployOutcome(subject, project); + expect(error).toBeUndefined(); + expect(deployCalls).toHaveLength(1); + }); + test("deploy to a China target hard-fails a Bedrock Managed Agents runtime", async () => { await inTempDirectory(); const { subject, project, deployCalls } = await projectWithTarget( diff --git a/src/core/project/manager.tsx b/src/core/project/manager.tsx index 1fc546099e..9db0da5833 100644 --- a/src/core/project/manager.tsx +++ b/src/core/project/manager.tsx @@ -74,7 +74,7 @@ import { startsInBoxOnCodeZip, } from "./templates/boxProfile"; import { defaultLogTargetNotice, observabilityOff } from "./runtimeProfile/rules/additions"; -import { validateBoxRuntimes } from "./boxValidation"; +import { assertBoxRegionSupported, validateBoxRuntimes } from "./boxValidation"; import { BOX_INSTALL_HINT, BOX_RELEASE } from "./backends/boxRelease"; import { getRuntimeTemplateResolver } from "./templates/runtime"; import { @@ -1823,6 +1823,9 @@ export class FsProjectManager implements ProjectManager { ); } + // Box runs only on AgentCore Runtime V2, so stop before the sync rewrites agentcore.json. + assertBoxRegionSupported(project.spec, target); + // Synth reads agentcore.json, so it is brought up to date with the code // first; only once the target is known, so a bad --target rewrites nothing. const synced = await this.syncRuntimeBuilds(project, { purpose: "deploy" }); From ceb0a75b6a3f8a9dc899d694c26725865c7fe57e Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Fri, 20 Nov 2026 12:46:37 -0800 Subject: [PATCH 2/3] docs(deploy): cite the AgentCore Runtime team for the Runtime V2 region list --- src/core/partition.ts | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/src/core/partition.ts b/src/core/partition.ts index 1c18a7d5c5..d45311f5ab 100644 --- a/src/core/partition.ts +++ b/src/core/partition.ts @@ -15,10 +15,8 @@ export function isChinaRegion(region: string): boolean { } /** - * Regions where AgentCore Runtime offers no platformVersion V2. Box runs only on V2. The source - * of truth is the `runtimeVersion` flag in YggdrasillControlPlaneServiceConfigCDK - * (configuration/dynamic-configuration/feature-flags/prod-.json): a region without it has - * no V2. Remove a region here once V2 launches in it. + * Regions where AgentCore Runtime offers no platformVersion V2. Box runs only on V2. The list is + * the AgentCore Runtime team's; remove a region here once V2 launches in it. */ const NO_RUNTIME_V2_REGIONS: ReadonlySet = new Set(["ap-south-2", "us-west-1"]); /** Partitions with no V2 in any region: GovCloud, and the isolated (ADC) partitions. */ From 6f78b4fdebf3a5cb4348dc9ab6a163ead0f43be9 Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Fri, 20 Nov 2026 15:45:09 -0800 Subject: [PATCH 3/3] fix(deploy): Address the review of #2878 - 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. --- src/core/partition.test.ts | 6 +++-- src/core/partition.ts | 7 ++++- src/core/project/boxValidation.ts | 12 ++++++--- src/core/project/manager.test.ts | 45 ++++++++++++++++++++++++++++++- src/core/project/manager.tsx | 6 +++++ 5 files changed, 69 insertions(+), 7 deletions(-) diff --git a/src/core/partition.test.ts b/src/core/partition.test.ts index 69952b2d65..1470bec144 100644 --- a/src/core/partition.test.ts +++ b/src/core/partition.test.ts @@ -15,8 +15,9 @@ describe("isChinaRegion", () => { }); describe("supportsRuntimeV2", () => { - // ap-east-9 is not a region: one this CLI does not know of counts as having V2. - test.each(["us-west-2", "us-east-1", "eu-west-1", "cn-north-1", "ap-east-9"])( + // ap-east-9 is not a region: one this CLI does not know of counts as having V2, as the European + // Sovereign Cloud (eusc-de-east-1) does. + test.each(["us-west-2", "us-east-1", "eu-west-1", "cn-north-1", "ap-east-9", "eusc-de-east-1"])( "returns true for %s", (region) => { expect(supportsRuntimeV2(region)).toBe(true); @@ -31,6 +32,7 @@ describe("supportsRuntimeV2", () => { "us-iso-east-1", "us-isob-east-1", "us-isof-south-1", + "eu-isoe-west-1", ])("returns false for %s", (region) => { expect(supportsRuntimeV2(region)).toBe(false); }); diff --git a/src/core/partition.ts b/src/core/partition.ts index d45311f5ab..5a08b1e05d 100644 --- a/src/core/partition.ts +++ b/src/core/partition.ts @@ -19,11 +19,16 @@ export function isChinaRegion(region: string): boolean { * the AgentCore Runtime team's; remove a region here once V2 launches in it. */ const NO_RUNTIME_V2_REGIONS: ReadonlySet = new Set(["ap-south-2", "us-west-1"]); -/** Partitions with no V2 in any region: GovCloud, and the isolated (ADC) partitions. */ +/** + * Partitions with no V2 in any region: GovCloud, and the isolated (ADC) partitions. The European + * Sovereign Cloud (`aws-eusc`) is left out on purpose: like a region the CLI does not list, it + * counts as having V2, and CreateAgentRuntime refuses it there if it does not. + */ const NO_RUNTIME_V2_PARTITIONS: ReadonlySet = new Set([ "aws-us-gov", "aws-iso", "aws-iso-b", + "aws-iso-e", "aws-iso-f", ]); diff --git a/src/core/project/boxValidation.ts b/src/core/project/boxValidation.ts index 075685ceae..be41507cb3 100644 --- a/src/core/project/boxValidation.ts +++ b/src/core/project/boxValidation.ts @@ -104,16 +104,22 @@ export function validateBoxRuntimes(spec: ProjectSpec): void { /** * Throws for a Box project deployed to a region where AgentCore Runtime has no platformVersion V2. - * Box runs only on V2, so the runtimes could not be created there. + * Box runs only on V2, so the runtimes could not be created there. `target` is a configured target, + * or, with `provisioning`, the default target deploy is about to create in that region. */ export function assertBoxRegionSupported( spec: ProjectSpec, target: { name: string; region: string }, + { provisioning = false }: { provisioning?: boolean } = {}, ): void { if (!isBoxProject(spec) || supportsRuntimeV2(target.region)) return; + const wayOut = provisioning + ? "Deploy with --region set to a region that has it, or add a target in another region to " + + "agentcore/aws-targets.json, then retry." + : `Change the region of target '${target.name}' in agentcore/aws-targets.json, or deploy ` + + "with --target to a target in another region, then retry."; 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.`, + `Box runs on AgentCore Runtime V2, which is not available in ${target.region}. ${wayOut}`, ); } diff --git a/src/core/project/manager.test.ts b/src/core/project/manager.test.ts index 4238687ec1..883d4c7aab 100644 --- a/src/core/project/manager.test.ts +++ b/src/core/project/manager.test.ts @@ -1582,13 +1582,56 @@ describe("FsProjectManager.addResource", () => { const { error } = await deployOutcome(subject, project); expect(error).toBeInstanceOf(RegionUnsupportedFeatureError); expect(String(error)).toContain( - `Cannot deploy Box project 'example' to target 'primary' in ${region}`, + `Cannot deploy Box project 'example' to target 'primary' in ${region}: Box runs on ` + + `AgentCore Runtime V2, which is not available in ${region}. Change the region of ` + + "target 'primary' in agentcore/aws-targets.json, or deploy with --target to a target " + + "in another region, then retry.", ); expect(await readFile(specPath, "utf8")).toBe(before); expect(deployCalls).toEqual([]); }, ); + test("deploy of a Box project with no target to us-west-1 fails before STS or aws-targets.json", async () => { + await inTempDirectory(); + const { project } = await projectWithTarget("us-east-1", undefined, AGENT_PYTHON_STRANDS_BOX); + const targetsPath = join(project.rootPath, "agentcore", "aws-targets.json"); + await rm(targetsPath); + const accounts: string[] = []; + const subject = new FsProjectManager({ + logger: createSilentLogger(), + identity: new TestIdentityClient(), + enableTransactionSearch: async () => {}, + boxProfileResolver: new FakeBoxProfileResolver(), + runner: async () => {}, + checkTool: async () => {}, + resolveAccount: async (region) => { + accounts.push(region); + return "111122223333"; + }, + }); + const fresh = (await subject.resolve({ filePath: project.rootPath }))!; + + const deploying = (async () => { + for await (const _ of subject.deploy(fresh, { + target: "default", + region: "us-west-1", + confirmTeardown: async () => false, + })); + })(); + + await expect(deploying).rejects.toThrow( + new RegionUnsupportedFeatureError( + "Cannot deploy Box project 'example' to target 'default' in us-west-1: Box runs on " + + "AgentCore Runtime V2, which is not available in us-west-1. Deploy with --region set " + + "to a region that has it, or add a target in another region to " + + "agentcore/aws-targets.json, then retry.", + ), + ); + expect(accounts).toEqual([]); + expect(existsSync(targetsPath)).toBe(false); + }); + test("deploy of a project that is not a Box project to us-west-1 is not refused", async () => { await inTempDirectory(); const { subject, project, deployCalls } = await projectWithTarget("us-west-1"); diff --git a/src/core/project/manager.tsx b/src/core/project/manager.tsx index 9db0da5833..6d133b5dc9 100644 --- a/src/core/project/manager.tsx +++ b/src/core/project/manager.tsx @@ -1795,6 +1795,12 @@ export class FsProjectManager implements ProjectManager { // `default` gets this treatment: inventing a *named* target would turn a // typo'd --target into a deployment somewhere unintended. if (!target && input.target === DEFAULT_TARGET_NAME) { + // Box runs only on AgentCore Runtime V2, so stop before STS or aws-targets.json. + assertBoxRegionSupported( + project.spec, + { name: DEFAULT_TARGET_NAME, region: input.region }, + { provisioning: true }, + ); target = await this.provisionDefaultTarget(project, targetsPath, input.region); yield { type: "step",