fix(cli): default new agents to PYTHON_3_13 instead of PYTHON_3_14 (#907)

[aidandaly24]

Refs aws#907

Issues

• PYTHON_3_14 runtime accepted by CLI but rejected by CloudFormation aws/agentcore-cli#907 — A new user who runs agentcore init / add agent / deploy in any region where PYTHON_3_14 is not yet GA (the reporter used eu-central-1) gets the unsupported runtime written into agentcore.json by default. agentcore validate passes, but CloudFormation rejects it via AWS::EarlyValidation::PropertyValidation, leaving the stack stuck in REVIEW_IN_PROGRESS. The CLI then hard-blocks every subsequent deploy with no recovery path, so the user must manually aws cloudformation delete-stack to proceed.

Root cause

verified: DEFAULT_PYTHON_VERSION='PYTHON_3_14' at constants.ts:153 (git blame PR aws#837/b139c0507), consumed at schema-mapper.ts:129 + packaging fallbacks; picker 'Latest' at mcp/types.ts:428; no region guard in CLI/validate; REVIEW_IN_PROGRESS blocks at stack-status.ts:16 / preflight.ts:288. CDK passthrough at AgentCoreRuntime.ts:243 (no validation). Could not personally confirm service-side regional availability of PYTHON_3_14 (a service fact, not in code).

The fix

Primary (resolves the reported scenario): lower the default to a universally-available runtime — set DEFAULT_PYTHON_VERSION = 'PYTHON_3_13' in src/schema/constants.ts:153, and stop listing PYTHON_3_14 first/'Latest' in the picker at src/cli/tui/screens/mcp/types.ts:428 (keep it selectable in PythonRuntimeSchema:149 for opt-in in supported regions). This is exactly what the OPEN canonical fix PR aws#1172 does. For the MCP/Lambda compute path, apply the matching change to the CDK construct's DEFAULT_MCP_PYTHON_VERSION (mcp-utils.ts:5, currently 'PYTHON_3_14') and the lambda.Runtime fallback in McpLambdaCompute.ts:81, then ship a CDK release the vended caret range picks up. Optional hardening (CLOSED PR aws#1157's approach): special-case REVIEW_IN_PROGRESS in stack-status.ts to detect a never-deployed stuck stack and offer delete-and-retry (a --recover flag), plus surface the CFN early-validation error with a concrete hint. Design decision: prefer a safer default plus clearer error surfacing over a brittle, service-driven region-vs-runtime compatibility table.

Files touched: CLI (primary): src/schema/constants.ts:153 (DEFAULT_PYTHON_VERSION), src/cli/tui/screens/mcp/types.ts:428 (PYTHON_VERSION_OPTIONS ordering/'Latest'); optional src/cli/cloudformation/stack-status.ts:16,68-74 and src/cli/operations/deploy/preflight.ts:288 (REVIEW_IN_PROGRESS recovery). CDK construct @aws/agentcore-cdk (for MCP path only): src/cdk/constructs/components/mcp/mcp-utils.ts:5 (DEFAULT_MCP_PYTHON_VERSION) and McpLambdaCompute.ts:81 fallback. Note: schema-mapper.ts:129 and lib/packaging/{python,index}.ts consume the constant and need no change once the default is fixed.

Validation evidence

The fix was verified by reproducing the original symptom and re-running after the change:

BEFORE (HEAD): src/schema/constants.ts:153 DEFAULT_PYTHON_VERSION='PYTHON_3_14'; TUI PYTHON_VERSION_OPTIONS[0] = {id:'PYTHON_3_14', title:'Python 3.14', description:'Latest'}. schema-mapper.ts:128 sets a Python agent's runtimeVersion to DEFAULT_PYTHON_VERSION, so a new agent wrote PYTHON_3_14 into agentcore.json by default. AFTER (fix, built & run): built lib reports DEFAULT_PYTHON_VERSION=PYTHON_3_13 and DEFAULT_RUNTIME_BY_LANGUAGE.Python=PYTHON_3_13. Ran built CLI dist/cli/index.mjs: create --project-name acfix907 --defaults then add agent --name acfix907rt --language Python --framework Strands --model-provider Bedrock --memory none -> agentcore.json wrote "runtimeVersion": "PYTHON_3_13" (symptom gone). TUI PYTHON_VERSION_OPTIONS[0].id now 'PYTHON_3_13' ("Recommended"); PYTHON_3_14 moved to 2nd, labeled "Not yet available in all regions", still present/selectable. No regression: PythonRuntimeSchema.safeParse('PYTHON_3_14').success===true. Targeted tests (constants/types/schema-mapper) 103 passed incl. 3 new assertions; full npm run test:unit = 377 files / 5453 tests passed, 0 failed.

Test suite: green.

---

Staged on the fork as a draft for human review. Promote to aws/agentcore-cli after vetting.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	37.16%	13593 / 36577
🔵	Statements	36.43%	14452 / 39667
🔵	Functions	31.8%	2333 / 7336
🔵	Branches	31.1%	9000 / 28932

Generated in workflow #134 for commit ec3e86b by the Vitest Coverage Report Action