fix(#907): default Python runtime to PYTHON_3_13 to avoid CloudFormation rejection of PYTHON_3_14

[aidandaly24]

Description

Fixes the bug reported in #907 where agentcore init / agentcore add agent defaulted new agents to runtimeVersion: "PYTHON_3_14", which CloudFormation rejects in most regions with AWS::EarlyValidation::PropertyValidation. The failed Change Set leaves the stack stuck in REVIEW_IN_PROGRESS, blocking all subsequent deploys until the user manually deletes the stack.

Per the maintainer comment on the issue, PYTHON_3_14 is currently only supported by CloudFormation in us-east-1 and us-west-2. The minimal, lowest-risk fix is therefore to flip the default Python runtime to PYTHON_3_13 (broadly supported) while leaving PYTHON_3_14 as a valid opt-in choice for users in supported regions.

Changes

• src/schema/constants.ts — DEFAULT_PYTHON_VERSION: PythonRuntime = 'PYTHON_3_14' → 'PYTHON_3_13'. This single constant flows transparently into every CLI default (TUI prompts, AddAgentScreen, AgentPrimitive, GatewayTargetPrimitive, schema-mapper, packaging, tui-harness), so the one-line change fixes ~10 downstream call sites without further edits. Added a JSDoc block above PythonRuntimeSchema documenting the regional CFN limitation and linking back to PYTHON_3_14 runtime accepted by CLI but rejected by CloudFormation #907.
• agentcore-l3-cdk-constructs (companion PR) — mirrors the change in DEFAULT_MCP_PYTHON_VERSION and the lambda.Runtime.PYTHON_3_14 fallback in McpLambdaCompute.ts.
• docs/configuration.md, docs/container-builds.md — example runtimeVersion values updated from PYTHON_3_14 to PYTHON_3_13. Added an "opt-in only" note next to PYTHON_3_14 in the supported-runtimes list explaining the CFN regional limitation and pointing to PYTHON_3_14 runtime accepted by CLI but rejected by CloudFormation #907.
• src/schema/__tests__/constants.test.ts — added a regression test asserting DEFAULT_PYTHON_VERSION === 'PYTHON_3_13'. The existing test confirming PythonRuntimeSchema still accepts PYTHON_3_14 is preserved.
• src/cli/operations/agent/generate/__tests__/schema-mapper.test.ts — updated the runtime-version assertion to reference DEFAULT_PYTHON_VERSION instead of a hard-coded literal, so future default changes don't cascade into test breakage.

What is intentionally NOT in this PR

• Removing PYTHON_3_14 from the enum — it works in us-east-1 / us-west-2 per the maintainer comment, so removing it would break legitimate users. The schema continues to accept it.
• Auto-cleanup of REVIEW_IN_PROGRESS stacks — the issue's "at minimum" bullet asked for either (a) accept the value, (b) reject it client-side, or (c) better deploy error handling. This PR takes path (b) for the implicit default while preserving explicit opt-in. Auto-cleanup is a larger change to deploy orchestration and is out of scope.

Related Issue

Closes #907

Documentation PR

N/A — documentation updates are included inline in this PR (docs/configuration.md, docs/container-builds.md).

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

Targeted verification:

npx vitest run --project unit \
  src/cli/operations/agent/generate/__tests__/schema-mapper.test.ts \
  src/schema/__tests__/constants.test.ts
# Test Files  2 passed (2)
#       Tests 77 passed (77)

npm run typecheck: clean. Pre-commit hooks (Prettier + ESLint + typecheck) passed.

Code review history

• Round 1 (3 findings): [HIGH] schema-mapper.test.ts hard-coded PYTHON_3_14 assertion would have broken CI — fixed to use DEFAULT_PYTHON_VERSION. [LOW] doc examples still showed PYTHON_3_14 — updated. [LOW] schema accepts PYTHON_3_14 without caveat — added JSDoc + docs note.
• Round 2 (2 findings): all approved, no further changes required.

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.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	43.19%	9034 / 20915
🔵	Statements	42.47%	9592 / 22585
🔵	Functions	40.02%	1558 / 3893
🔵	Branches	40%	5811 / 14527

Generated in workflow #2633 for commit b232579 by the Vitest Coverage Report Action

[agentcore-cli-automation]

Thanks for this fix — the root cause analysis is spot on, the one-line default change cleanly flows through all the downstream call sites (AgentPrimitive, AddAgentScreen, GatewayTargetPrimitive, schema-mapper, packaging, tui-harness), the JSDoc explains the regional CFN limitation, and the regression test locks in the new default. Overall the scope is right: fix the footgun in the implicit default, keep PYTHON_3_14 as an opt-in.

One must-fix before merge (see inline comment): src/assets/agents/AGENTS.md still lists PYTHON_3_14 in the RuntimeVersion enum with no caveat. That file is bundled into every scaffolded agent project and is the doc agent authors see first, so leaving it untouched re-introduces the exact footgun for anyone who bootstraps a new project and edits agentcore.json by hand.

A couple of non-blocking notes that I'm not requesting changes for, just flagging:

• PYTHON_VERSION_OPTIONS in src/cli/tui/screens/mcp/types.ts:279-285 still lists PYTHON_3_14 first with description: 'Latest'. It appears to be unreferenced anywhere in src/, so no functional impact today, but if it ever gets wired into a picker the first-item default would silently re-introduce the bug. Worth either deleting or reordering at some point.
• The companion PR in agentcore-l3-cdk-constructs that flips DEFAULT_MCP_PYTHON_VERSION and the lambda.Runtime.PYTHON_3_14 fallback in McpLambdaCompute.ts:81 — I couldn't independently verify it's merged/published. The CLI always emits an explicit pythonVersion in the generated config (see GatewayTargetPrimitive.ts:777 and the MCP flows), so the CDK-side default is dead code in the normal CLI path and this PR is functionally complete without it. Just worth double-checking the companion has landed before cutting a release so hand-authored agentcore.json files without pythonVersion don't fall back to PYTHON_3_14.

[agentcore-cli-automation]

The caveat added here is great, but the same RuntimeVersion enum list in src/assets/agents/AGENTS.md:71 is unchanged:

- **RuntimeVersion**: `'PYTHON_3_10'` | `'PYTHON_3_11'` | `'PYTHON_3_12'` | `'PYTHON_3_13'` | `'PYTHON_3_14'` | `'NODE_18'` | `'NODE_20'` | `'NODE_22'`

That file is shipped as part of every scaffolded agent project (via src/assets/agents/), so anyone who reads AGENTS.md in a new project and hand-edits agentcore.json will still pick PYTHON_3_14 thinking it's a supported option. A couple of options for the fix:

1. Minimal: mark PYTHON_3_13 as the default and add a short (opt-in only; see docs/configuration.md) note next to PYTHON_3_14 in that line, mirroring what you've done here.
2. Hoist the caveat: expand the enum line into a short bullet list (like the one in docs/configuration.md:199-207) so the regional limitation is visible in-line.
3. Link out: keep the enum line compact and add a one-line note below it pointing to docs/configuration.md#runtime-versions for the PYTHON_3_14 caveat.

Also remember to regenerate src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap (line 5429 / 5537) once AGENTS.md is updated — npm run test:update-snapshots per the PR template.

[agentcore-cli-automation]

Thanks for addressing the prior round — the AGENTS.md update, the matching snapshot refresh, and the JSDoc/doc caveat all look good. The default flip flows cleanly through all the DEFAULT_PYTHON_VERSION call sites I traced (AgentPrimitive, AddAgentScreen, GatewayTargetPrimitive, schema-mapper, packaging, tui-harness).

Requesting one change before merge

src/schema/llm-compacted/agentcore.ts:38 — the same bare PYTHON_3_14 enum the previous review flagged in AGENTS.md also appears here, without the new caveat:

type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13' | 'PYTHON_3_14';

This file is shipped into every scaffolded project. src/cli/templates/schema-assets.ts embeds it into LLM_CONTEXT_FILES, and CDKRenderer.writeLlmContext() writes it to agentcore/.llm-context/agentcore.ts during agentcore init (see src/cli/templates/CDKRenderer.ts:64-66, 156-163). Its explicit purpose, per the header comment in schema-assets.ts, is to "provide AI coding assistants with compact, readable type definitions."

So an AI coding assistant (Claude Code, Cursor, etc.) that reads .llm-context/agentcore.ts while helping a user edit agentcore.json in, say, us-east-2 will see PYTHON_3_14 as an equal member of the union and is reasonably likely to suggest it — reintroducing exactly the #907 footgun that the rest of this PR is closing. The fix in AGENTS.md alone doesn't cover this path because the LLM context file is a separate, parallel copy of the schema surface.

A few options:

1. Mirror the AGENTS.md fix inline — change the union to something like:

   // PYTHON_3_14 is opt-in only; CloudFormation currently supports it in us-east-1
   // and us-west-2. See docs/configuration.md#runtime-versions and issue #907.
   type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13' | 'PYTHON_3_14';

   This is consistent with the style used elsewhere in llm-compacted/agentcore.ts (e.g., // default 'PUBLIC' on NetworkMode).

2. Split the type and document the default — e.g. add // default 'PYTHON_3_13' on the runtimeVersion?: RuntimeVersion field at line 71 and a // opt-in only, see #907 trailing comment on the PYTHON_3_14 token. Slightly more surgical.

3. Temporarily drop PYTHON_3_14 from the LLM-context union and link out to docs/configuration.md for the full list. Most aggressive but guarantees no AI-assisted regression.

Also note that mcp.ts in the same directory has the same line at src/schema/llm-compacted/mcp.ts:180, but LLM_CONTEXT_FILES in schema-assets.ts only ships agentcore.ts + aws-targets.ts + README.md — so mcp.ts is not currently shipped and doesn't need updating unless you want to keep the files in sync for maintenance reasons (the header comment in src/schema/llm-compacted/AGENTS.md suggests they're manually kept in sync with the Zod schemas).

If agentcore.ts in llm-compacted/ is covered by any snapshot I missed, that will need regenerating too; I didn't find one, but npm run test:update-snapshots per the PR template will flush out anything I missed.

[agentcore-cli-automation]

Reviewed the current state of the PR against both prior review rounds and the broader codebase. The two must-fix findings from the earlier rounds (src/assets/agents/AGENTS.md and src/schema/llm-compacted/agentcore.ts) are both addressed, and I verified the snapshot at src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap:5537 was regenerated to match.

I traced all call sites of DEFAULT_PYTHON_VERSION to confirm the one-line flip flows through correctly:

• src/cli/primitives/AgentPrimitive.tsx:585 — agent creation
• src/cli/primitives/GatewayTargetPrimitive.ts:777, 789 — Lambda + AgentCoreRuntime gateway targets
• src/cli/tui/screens/agent/AddAgentScreen.tsx:316, 439, 768 — TUI defaults
• src/cli/operations/agent/generate/schema-mapper.ts:121 — generate flow
• src/lib/packaging/{python,index}.ts — packaging fallback for hand-authored configs missing runtimeVersion
• src/tui-harness/helpers.ts:107 — harness

All now emit PYTHON_3_13. The CLI also always writes an explicit pythonVersion/runtimeVersion into generated configs, so the CDK-side defaults in agentcore-l3-cdk-constructs (DEFAULT_MCP_PYTHON_VERSION, lambda.Runtime.PYTHON_3_14 fallback at McpLambdaCompute.ts:81) are not hit in the normal CLI flow. Companion PR status on the constructs repo is still worth confirming before the next release for the hand-authored-config edge case, but as the previous reviewer noted, it is not blocking for this PR.

No new blocking issues found beyond what was flagged in earlier rounds. Approving.

Non-blocking items already raised in prior reviews (not re-raising)

• PYTHON_VERSION_OPTIONS in src/cli/tui/screens/mcp/types.ts:279-285 still lists PYTHON_3_14 first with description: 'Latest'. It is currently unreferenced in src/, so no functional impact, but worth reordering or deleting at some point.
• The companion PR in agentcore-l3-cdk-constructs that mirrors DEFAULT_MCP_PYTHON_VERSION and the lambda.Runtime.PYTHON_3_14 fallback — verify it has landed before cutting a release.

[aidandaly24]

Closing: re-running with format fix in executor