fix(#907): default new agents to PYTHON_3_13 to avoid CloudFormation rejection

src/cli/operations/agent/generate/__tests__/schema-mapper.test.ts

@@ -1,5 +1,6 @@
 import { computeManagedOAuthCredentialName } from '../../../../primitives/credential-utils.js';
 import { mapByoConfigToAgent } from '../../../../tui/screens/agent/useAddAgent.js';
+import { DEFAULT_PYTHON_VERSION } from '../../../../tui/screens/generate/defaults.js';
 import type { GenerateConfig } from '../../../../tui/screens/generate/types.js';
 import {
   mapGenerateConfigToAgent,
@@ -87,7 +88,8 @@ describe('mapGenerateConfigToAgent', () => {
     expect(result.name).toBe('TestProject');
     expect(result.build).toBe('CodeZip');
     expect(result.entrypoint).toBe('main.py');
-    expect(result.runtimeVersion).toBe('PYTHON_3_14');
+    expect(result.runtimeVersion).toBe(DEFAULT_PYTHON_VERSION);
+    expect(result.runtimeVersion).toBe('PYTHON_3_13');
     expect(result.networkMode).toBe('PUBLIC');
     expect(result.protocol).toBe('HTTP');
   });

src/schema/__tests__/constants.test.ts

@@ -1,4 +1,5 @@
 import {
+  DEFAULT_PYTHON_VERSION,
   ModelProviderSchema,
   NetworkModeSchema,
   NodeRuntimeSchema,
@@ -193,3 +194,32 @@ describe('isFrameworkSupportedForProtocol', () => {
     expect(isFrameworkSupportedForProtocol('MCP', 'OpenAIAgents')).toBe(false);
   });
 });
+
+describe('DEFAULT_PYTHON_VERSION (issue #907)', () => {
+  // Issue #907: PYTHON_3_14 was the default but is rejected by CloudFormation
+  // in many regions (only us-west-2 / us-east-1 are tested per maintainers).
+  // The default must therefore be a server-side-supported version.
+  it('defaults to PYTHON_3_13 (not PYTHON_3_14)', () => {
+    expect(DEFAULT_PYTHON_VERSION).toBe('PYTHON_3_13');
+    expect(DEFAULT_PYTHON_VERSION).not.toBe('PYTHON_3_14');
+  });
+
+  it('is a valid member of PythonRuntimeSchema', () => {
+    expect(PythonRuntimeSchema.safeParse(DEFAULT_PYTHON_VERSION).success).toBe(true);
+  });
+
+  // Regression invariant: the default must lag the newest enum entry until
+  // CloudFormation catches up. If a future PR bumps both the newest version
+  // and the default in lockstep, this test will fail and force a maintainer
+  // to confirm CFN support.
+  it('does not equal the newest entry in PythonRuntimeSchema', () => {
+    const versions = PythonRuntimeSchema.options;
+    expect(DEFAULT_PYTHON_VERSION).not.toBe(versions[versions.length - 1]);
+  });
+
+  // PYTHON_3_14 is intentionally retained as a valid opt-in for users in
+  // CloudFormation-supported regions (us-west-2, us-east-1).
+  it('still accepts PYTHON_3_14 as an explicit opt-in via PythonRuntimeSchema', () => {
+    expect(PythonRuntimeSchema.safeParse('PYTHON_3_14').success).toBe(true);
+  });
+});

src/schema/constants.ts

@@ -143,11 +143,31 @@ export function isReservedProjectName(name: string): boolean {
 // Infrastructure Constants (shared between agent-env and mcp schemas)
 // ============================================================================
 
+/**
+ * Supported Python runtime versions.
+ *
+ * NOTE on PYTHON_3_14 (issue #907): PYTHON_3_14 is kept in this enum because
+ * CloudFormation accepts it in `us-west-2` and `us-east-1`. In other regions,
+ * `AWS::EarlyValidation::PropertyValidation` rejects it. To avoid breaking
+ * users in supported regions while protecting users in unsupported regions,
+ * PYTHON_3_14 remains opt-in and is not the default — see DEFAULT_PYTHON_VERSION
+ * below.
+ */
 export const PythonRuntimeSchema = z.enum(['PYTHON_3_10', 'PYTHON_3_11', 'PYTHON_3_12', 'PYTHON_3_13', 'PYTHON_3_14']);
 export type PythonRuntime = z.infer<typeof PythonRuntimeSchema>;
 
-/** Default Python runtime version for new agents and MCP tools */
-export const DEFAULT_PYTHON_VERSION: PythonRuntime = 'PYTHON_3_14';
+/**
+ * Default Python runtime version for new agents and MCP tools.
+ *
+ * NOTE: Keep this below the newest enum value until CloudFormation supports
+ * it in all regions. PYTHON_3_14 is intentionally NOT the default — see
+ * issue #907 (https://github.com/aws/agentcore-cli/issues/907):
+ * CloudFormation's `AWS::EarlyValidation::PropertyValidation` rejects
+ * PYTHON_3_14 outside of us-west-2 / us-east-1, leaving stacks stuck in
+ * REVIEW_IN_PROGRESS. PYTHON_3_14 remains a valid enum member for users
+ * deploying in supported regions who explicitly opt in.
+ */
+export const DEFAULT_PYTHON_VERSION: PythonRuntime = 'PYTHON_3_13';
 
 export const NodeRuntimeSchema = z.enum(['NODE_18', 'NODE_20', 'NODE_22']);
 export type NodeRuntime = z.infer<typeof NodeRuntimeSchema>;