fix(export): make generated Strands runtimes deployable

[aidandaly24]

Summary

• align generated Strands Python agents with the released strands-agents 1.54.x APIs and provider extras
• replace the stateful execution-limit hook with native per-invocation turn/token limits and request-scoped cancellation
• defer credential-backed MCP identity lookup until transport startup, and generate collision-resistant provider/function names
• preserve provider parameters and memory retrieval tuning while emitting export notes for fields that cannot be reproduced
• strictly validate service harness ARNs while preserving service-provided network configuration
• surface unknown or incomplete service union members in EXPORT_NOTES.md instead of silently dropping them
• add --vpc-id to project export harness: export rewrites a containerUri harness as a Dockerfile build so the agent code can be layered in, which makes CodeBuild's VPC id mandatory where the source harness never needed one
• keep additionalParams restricted to the lite_llm provider, and drop it with an export note on the --arn path rather than writing a spec the pinned CDK rejects at synth

Verification

Source gate

• bun install --frozen-lockfile
• bun test src: 2,597 pass, 0 fail
• bun run typecheck
• bun run lint:check
• bun run format:check
• bun run build
• bun run secrets:check

Generated Python matrix

Generated real exports and ran uv sync, compileall, and import main for:

• Bedrock with skills, sliding-window truncation, execution limits, timeout, and credential-backed remote MCP
• OpenAI Responses
• Gemini
• LiteLLM
• Bedrock Mantle Responses

All five resolved strands-agents 1.54.0 and imported successfully. OpenAI/Mantle resolved openai 2.54.0, Gemini resolved google-genai 2.20.0, and LiteLLM resolved litellm 1.96.0. A generated-module probe invoked the Bedrock entrypoint twice and verified fresh cancellation signals plus identical per-invocation limits (LIMITS_OK).

Live AWS

Account 603141041947, region us-east-1, profile deploy:

• deployed source harness ExportHarnessFix0831_source-jBo3nhtmm2 to READY and invoked it
• exported by local name and by service ARN (with ambient us-west-2, proving ARN-region precedence)
• built and deployed runtimes:
  • ExportHarnessFix0831_exported_agent-hLU1ha80fd
  • ExportHarnessFix0831_exported_arn_agent-ItzBMG47U0
• invoked each runtime twice in the same session; all four calls returned HTTP 200, end_turn, and the requested marker
• deployed credential-backed MCP runtime ExportHarnessFix0831_mcp_runtime-6ZSyRO2yME
• confirmed module import succeeds without request identity context
• after creating the referenced disposable API-key provider, invoked the runtime successfully with MCP_CONTEXT_OK

The current refactor deploy path consumes project credentials as references rather than provisioning them, so the exporter now states that the named provider must exist instead of claiming deploy creates it.

Follow-up after review

AlexanderRichey's review asked why the EC2 client existed; the DescribeSubnets lookup was
removed in b3fbb3dd. Reviewing that removal surfaced that dropping it left the underlying problem
unaddressed, and that a separate guard had been deleted:

• --vpc-id (48cae1e6). The Runtime NetworkConfiguration API genuinely has no vpcId — the
  review comment is correct — but CodeBuild's CreateProject requires one, and export is what turns
  a no-build containerUri harness into a build by emitting FROM <containerUri>. Neither source of
  a harness can supply it: the service's VpcConfig has no such field, and a local containerUri
  harness is never built, so its schema rightly does not demand one. The flag lets the caller supply
  it, and export now fails before writing anything when it is needed and absent. No AWS lookup is
  involved: getHarness remains the only request on the --arn path.
• additionalParams guard (b178ac65). Removing the lite_llm-only refinement moved a clean
  failure at project add harness to a raw zod dump at project build, since the pinned CDK
  re-parses harness.json at synth and still rejects the field on other providers. Restored, with
  the --arn mapper dropping it under an export note so a harness authored outside this CLI still
  exports.
• f82282b9 reverts formatting residue the EC2 removal left in two test files, so both now match
  the base byte for byte.
• 60f499a1 aligns the flag with repo conventions: reuse NetworkConfigSchema.shape.vpcId rather
  than restating its regex, use the <placeholder> remedy form (the previous vpc-xxxxxxxx example
  could not satisfy the flag's own pattern), and document the flag in README.md.
• e504774c follows a mutation pass over every test this PR adds — each one had the behaviour it
  covers deliberately broken to confirm it fails. One duplicated assertion was removed, and two gaps
  closed: the --vpc-id failure test now asserts nothing was written, and the ARN test now pins the
  12-digit account group (loosening \d{12} to \d+ previously passed).

Verified by generating a real project with a VPC + containerUri harness and parsing the resulting
agentcore.json with AgentEnvSpecSchema from @aws/agentcore-cdk@0.1.0-alpha.45, the version the
generated project pins: the pre-fix output is rejected with
networkConfig.vpcId is required for Container builds in VPC mode, and the --vpc-id output is
accepted. This path was not re-run against live AWS — it needs a VPC container harness, which the
matrix above does not cover.

Cleanup

• stack AgentCore-ExportHarnessFix0831-default: deleted
• matching AgentCore runtimes: none
• matching AgentCore harnesses: none
• disposable API-key credential provider: deleted

[agentcore-devx-automation]

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

[codecov-commenter]

Codecov Report

❌ Patch coverage is 87.42857% with 22 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.19%. Comparing base (d304147) to head (e504774).
⚠️ Report is 3 commits behind head on refactor.

Files with missing lines	Patch %	Lines
src/handlers/project/export/serviceHarness.ts	78.00%	22 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2154      +/-   ##
============================================
- Coverage     97.22%   97.19%   -0.04%     
============================================
  Files           507      507              
  Lines         33809    33943     +134     
============================================
+ Hits          32872    32992     +120     
- Misses          937      951      +14     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Looks good

Nice, tightly-scoped fix. I walked through the template updates, the exporter changes, and the new EC2-backed VPC lookup and didn't find anything that needs to change before merge. A few observations, none of which are blockers:

• HarnessClient.resolveVpcIdFromSubnets is wired cleanly through AwsClients/CoreClient and the ec2 client is cached like the others; the new tests cover the multi-VPC / no-VPC / happy paths without mocking anything below the SDK boundary. 👍
• The switch to a strict ARN regex in parseHarnessArn is the right call, and the behavior change of always trusting the ARN's region (rather than falling back to CLI region) is now consistent between harnessIdFromArn and regionFromHarnessArn. The test in harness.test.ts (arn:aws:lambda:...) and the partition test in serviceHarness.test.ts (arn:aws-cn:...) cover the important edges.
• The main.py template's limits = { … } or None idiom is intentional: when hasExecutionLimits is true solely because timeoutSeconds is set, both {{#if}} branches inside the dict literal are stripped, so it evaluates to None. As long as agent.stream_async(..., limits=None, ...) is accepted by strands-agents 1.54 (per the verification notes in the PR description, it is), this is fine.
• serviceHarness.ts now surfaces $unknown union members as export notes instead of silently dropping them (skills, memory, environment, environment artifact, filesystem configs). Good coverage in serviceHarness.test.ts.
• Header credential names / python function names now hash their inputs, so X-Api-Key vs X_Api_Key no longer collide — nice; that's exercised by the new "keeps normalized header names distinct" test.
• readStrandsVersion regex was updated to tolerate the new strands-agents[extras] form.
• No new features here that would need telemetry instrumentation; existing plumbing is untouched.

LGTM to merge.

[agentcore-devx-automation]

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

[AlexanderRichey]

Why do we need an EC2 client?

[AlexanderRichey]

Why do we need to do this? The API doesn't require this: https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_NetworkConfiguration.html

[AlexanderRichey]

I'm not sure this need to be in scope. The main thing is generating the code that the user can then use. The user can also configure VPC stuff on their own.

[agentcore-devx-automation]

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

[agentcore-devx-automation]

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