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

[aidandaly24]

Description

#907 — PYTHON_3_14 runtime accepted by CLI but rejected by CloudFormation

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.

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 #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 #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.

This fix was produced by an automated triage+fix run and validated locally (build + unit suite + symptom reproduction). It is being opened as a draft for CI and human review.

Related Issue

Closes #907

Documentation PR

In-repo docs updated in this PR: docs/configuration.md and docs/container-builds.md had agentcore.json example snippets showing "runtimeVersion": "PYTHON_3_14" as the value the CLI generates. Those examples are now "PYTHON_3_13" to match the new default. The Runtime Versions reference list still includes PYTHON_3_14 since it remains a selectable opt-in value. No external devguide change is required.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other (please describe):

Testing

How have you tested the change?

• I ran npm run test:unit and npm run test:integ
• I ran npm run typecheck
• I ran npm run lint
• If I modified src/assets/, I ran npm run test:update-snapshots and committed the updated snapshots — N/A, no src/assets/ changes

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.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[github-actions]

Package Tarball

aws-agentcore-0.21.0.tgz

How to install

gh release download pr-1646-tarball --repo aws/agentcore-cli --pattern "*.tgz" --dir /tmp/pr-tarball
npm install -g /tmp/pr-tarball/aws-agentcore-0.21.0.tgz

[agentcore-cli-automation]

Thanks for the fix — switching the default to PYTHON_3_13 is the right call to unblock new users in regions where PYTHON_3_14 isn't yet GA. Before merging, I think there's one user-visible issue that needs to be addressed in this PR and one cross-repo follow-up worth tracking.

Needs to be addressed in this PR

• docs/configuration.md and docs/container-builds.md still show "runtimeVersion": "PYTHON_3_14" as the example value in the canonical agentcore.json snippets (configuration.md ~lines 34 and 169, container-builds.md ~line 61). Those examples are presented as what the CLI generates, so after this change the docs will conflict with reality — a user who runs agentcore init and then opens the docs will see a value they didn't get. The PR body says "N/A — no devguide change required", but I don't think that's quite right here since the docs are showing the default value that this PR is changing. Please update those examples to PYTHON_3_13.

Worth flagging, not blocking

• The L3 constructs repo (agentcore-l3-cdk-constructs) still has DEFAULT_MCP_PYTHON_VERSION = 'PYTHON_3_14' in src/cdk/constructs/components/mcp/mcp-utils.ts and a lambda.Runtime.PYTHON_3_14 fallback at McpLambdaCompute.ts:81. For CLI-generated projects this is fine — GatewayTargetPrimitive always writes pythonVersion explicitly using DEFAULT_PYTHON_VERSION, so the construct fallback is unreachable. But for hand-authored or imported agentcore.json files that omit pythonVersion on a Lambda MCP target, deploys in PYTHON_3_14-unsupported regions will still hit the original CloudFormation rejection. Since you already called this out as follow-up work in the PR description, I'd suggest filing a tracking issue in the constructs repo so it doesn't get forgotten.

Otherwise the change is minimal, scoped, and the regression tests are solid. LGTM once docs are updated.

[agentcore-cli-automation]

The picker copy here is good — Recommended / Not yet available in all regions clearly steers users to the safe choice while keeping 3.14 selectable. Just noting that this is the only user-facing surface that explains the constraint; the docs at docs/configuration.md and docs/container-builds.md still hardcode PYTHON_3_14 in their example agentcore.json snippets and should be updated in this PR to match the new default.

[aidandaly24]

Done — updated the example agentcore.json snippets in docs/configuration.md (lines 34 and 171) and docs/container-builds.md (line 84) to PYTHON_3_13 so they match the new default. The Runtime Versions reference list still includes PYTHON_3_14 since it remains a selectable opt-in value. Fixed in commit ec3e86b.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-cli-automation]

Reviewed independently and have nothing new to add — the concerns from the prior CHANGES_REQUESTED review have been addressed:

• Docs updated: docs/configuration.md (lines 34, 171) and docs/container-builds.md (line 84) now show PYTHON_3_13 in the example agentcore.json snippets, matching the new default. Fixed in commit ec3e86b.
• Constructs-repo follow-up: still applies (DEFAULT_MCP_PYTHON_VERSION in agentcore-l3-cdk-constructs/src/cdk/constructs/components/mcp/mcp-utils.ts:5 and the lambda.Runtime.PYTHON_3_14 fallback at McpLambdaCompute.ts:81), but was already flagged as non-blocking and is out of scope for this PR.

Other things I checked:

• Searched the CLI repo for other places that bake in a Python default. All Python-default flows (schema-mapper.ts, packaging/python.ts, packaging/index.ts, GatewayTargetPrimitive.ts, harness-mapper.ts, tui-harness/helpers.ts) derive from the single DEFAULT_PYTHON_VERSION constant, so this one-line change propagates everywhere consistently. No stranded PYTHON_3_14 defaults remain.
• Remaining PYTHON_3_14 references in the repo (schemas/agentcore.schema.v1.json enums, src/cli/commands/import/constants.ts mapping, llm-compacted/*.ts type unions, packaging/__tests__/python.test.ts parsing test, agent-env.test.ts enum iteration, AGENTS.md reference list) are all correct — they enumerate supported versions, not the default, and 3.14 stays a valid selectable runtime.
• Tests are appropriate — pure constant inspection, no mocking. No telemetry instrumentation needed since this is a default-value change, not a new feature.

LGTM.