feat: upgrade default Python runtime to PYTHON_3_13 (#658)

* feat: upgrade default Python runtime to PYTHON_3_14

Add PYTHON_3_14 to the PythonRuntime enum and make it the default
across all agent, MCP, and generate workflows. Updates defaults,
fallbacks, TUI options, tests, docs, and snapshots.

Constraint: PYTHON_3_14 must be added to the Zod enum in schema/constants.ts as all other types derive from it
Rejected: Only adding enum without changing default | user requested default upgrade
Confidence: high
Scope-risk: broad

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: revert default Python to PYTHON_3_13, keep PYTHON_3_14 in enum

The Bedrock AgentCore service API does not yet accept PYTHON_3_14.
CloudFormation validation rejects it at deploy time:
  "PYTHON_3_14 is not a valid enum value.
   Supported values: [PYTHON_3_10, PYTHON_3_11, PYTHON_3_12, PYTHON_3_13]"

Keep PYTHON_3_14 in the Zod enum for forward-compatibility but revert
all defaults and fallbacks back to PYTHON_3_13.

Constraint: Service API only supports PYTHON_3_10 through PYTHON_3_13
Rejected: Default to PYTHON_3_14 | service rejects at deploy time
Confidence: high
Scope-risk: narrow

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: remove PYTHON_3_14 from enum — service does not support it yet

The Bedrock AgentCore API only accepts PYTHON_3_10 through PYTHON_3_13.
Remove PYTHON_3_14 entirely to avoid deploy failures for users.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: jesseturner21

docs/configuration.md

@@ -29,7 +29,7 @@ Main project configuration using a **flat resource model**. Agents, memories, an
       "build": "CodeZip",
       "entrypoint": "main.py",
       "codeLocation": "app/MyAgent/",
-      "runtimeVersion": "PYTHON_3_12"
+      "runtimeVersion": "PYTHON_3_13"
     }
   ],
   "memories": [
@@ -187,7 +187,7 @@ on the next deployment.
   "build": "CodeZip",
   "entrypoint": "main.py",
   "codeLocation": "app/MyAgent/",
-  "runtimeVersion": "PYTHON_3_12",
+  "runtimeVersion": "PYTHON_3_13",
   "networkMode": "PUBLIC",
   "envVars": [{ "name": "MY_VAR", "value": "my-value" }],
   "instrumentation": {

docs/container-builds.md

@@ -59,7 +59,7 @@ In `agentcore.json`, set `"build": "Container"`:
   "build": "Container",
   "entrypoint": "main.py",
   "codeLocation": "app/MyAgent/",
-  "runtimeVersion": "PYTHON_3_12"
+  "runtimeVersion": "PYTHON_3_13"
 }
 ```
 

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

@@ -109,7 +109,7 @@ describe('mapGenerateConfigToAgent', () => {
     expect(result.name).toBe('TestProject');
     expect(result.build).toBe('CodeZip');
     expect(result.entrypoint).toBe('main.py');
-    expect(result.runtimeVersion).toBe('PYTHON_3_12');
+    expect(result.runtimeVersion).toBe('PYTHON_3_13');
     expect(result.networkMode).toBe('PUBLIC');
     expect(result.protocol).toBe('HTTP');
   });

src/cli/primitives/AgentPrimitive.tsx

@@ -513,7 +513,7 @@ export class AgentPrimitive extends BasePrimitive<AddAgentOptions, RemovableReso
       build: options.buildType,
       entrypoint: (options.entrypoint ?? 'main.py') as FilePath,
       codeLocation: codeLocation as DirectoryPath,
-      runtimeVersion: 'PYTHON_3_12',
+      runtimeVersion: 'PYTHON_3_13',
       protocol,
       networkMode,
       ...(networkMode === 'VPC' &&

src/cli/tui/screens/agent/types.ts

@@ -185,5 +185,5 @@ export const NETWORK_MODE_OPTIONS = [
   { id: 'VPC', title: 'VPC', description: 'Attach to your VPC' },
 ] as const;
 
-export const DEFAULT_PYTHON_VERSION: PythonRuntime = 'PYTHON_3_12';
+export const DEFAULT_PYTHON_VERSION: PythonRuntime = 'PYTHON_3_13';
 export const DEFAULT_ENTRYPOINT = 'main.py';

src/cli/tui/screens/generate/defaults.ts

@@ -5,7 +5,7 @@ import type { NetworkMode, PythonRuntime } from '../../../../schema';
  */
 
 /** Default Python runtime version for new agents */
-export const DEFAULT_PYTHON_VERSION: PythonRuntime = 'PYTHON_3_12';
+export const DEFAULT_PYTHON_VERSION: PythonRuntime = 'PYTHON_3_13';
 
 /** Default network mode for agent runtimes */
 export const DEFAULT_NETWORK_MODE: NetworkMode = 'PUBLIC';

src/lib/packaging/index.ts

@@ -78,7 +78,7 @@ export async function packRuntime(spec: AgentEnvSpec, options?: PackageOptions):
  * Defaults to Python if no runtimeVersion is specified.
  */
 export function packCodeZipSync(config: CodeBundleConfig | AgentEnvSpec, options?: PackageOptions): ArtifactResult {
-  const runtimeVersion = config.runtimeVersion ?? 'PYTHON_3_12';
+  const runtimeVersion = config.runtimeVersion ?? 'PYTHON_3_13';
   const packager = getCodeZipPackager(runtimeVersion);
   return packager.packCodeZip(config as AgentEnvSpec, options);
 }

src/lib/packaging/python.ts

@@ -155,7 +155,7 @@ export class PythonCodeZipPackager implements RuntimePackager {
  */
 export class PythonCodeZipPackagerSync implements CodeZipPackager {
   packCodeZip(config: AgentEnvSpec, options: PackageOptions = {}): ArtifactResult {
-    const runtimeVersion = config.runtimeVersion ?? 'PYTHON_3_12';
+    const runtimeVersion = config.runtimeVersion ?? 'PYTHON_3_13';
 
     if (!isPythonRuntimeVersion(runtimeVersion)) {
       throw new PackagingError(`Python packager only supports Python runtimes. Received: ${runtimeVersion}`);

src/tui-harness/helpers.ts

@@ -104,7 +104,7 @@ export async function createMinimalProjectDir(
       build: 'CodeZip',
       entrypoint: 'main.py:handler',
       codeLocation: 'app/TestAgent',
-      runtimeVersion: 'PYTHON_3_12',
+      runtimeVersion: 'PYTHON_3_13',
     });
 
     // Create the agent code directory so the CLI does not complain.