fix(cli): No deploy-path or CDK change needed (field + wiring alrea... (#870)

[aidandaly24]

Refs aws#870

Issues

• AgentCore CLI does not support specifying a custom IAM execution role for runtime deployment aws/agentcore-cli#870 — A user who wants to deploy an AgentCore runtime with a pre-existing, least-privilege IAM role has no CLI flag to do it: agentcore add agent exposes no --execution-role-arn (or equivalent) option. Worse, guessing the field name "roleArn" in agentcore.json passes agentcore validate cleanly yet is silently dropped at deploy, so the CLI creates its own CDK-managed role and the user's role is ignored with zero warning. The supported field (executionRoleArn) does work in agentcore.json and was undocumented until PR docs: document executionRoleArn in runtime spec aws/agentcore-cli#872, but it is non-obvious and there is still no command-line flag and no warning on the typo'd key.

Root cause

Two things, neither a deploy-path code defect. (1) Field-name UX/footgun: AgentEnvSpecSchema is a non-strict z.object().superRefine() (src/schema/schemas/agent-env.ts:306-447); the supported key is executionRoleArn (agent-env.ts:335, doc comment :334). Zod object schemas strip unknown keys, so the reporter's "roleArn" is silently dropped at ConfigIO.readProjectSpec parse time (src/lib/schemas/io/config-io.ts:113,325 via AgentCoreProjectSpecSchema -> agents array of AgentEnvSpecSchema at src/schema/schemas/agentcore-project.ts:399). validate and deploy share that parse, so validate passes (action.ts:185-194) yet deploy makes a CDK-managed role. (2) Missing flag / discoverability: the correct field exists and is fully wired — cdk-stack.ts:114 passes the whole spec to AgentCoreApplication, AgentEnvironment.ts:53/78 (CDK v0.1.0-alpha.19) hands the agent to AgentCoreRuntime, which at AgentCoreRuntime.ts:56 sets useImportedRole = !!agent.executionRoleArn, :59 iam.Role.fromRoleArn(...,{mutable:false}), :202 passes roleArn to CfnRuntime (all verified at tag v0.1.0-alpha.19, the pinned ^0.1.0-alpha.19) — but AgentPrimitive.tsx option block (lines 254-326) registers NO execution-role flag, so the capability is config-only and undiscoverable from the CLI. Docs gap was real and is now fixed (commit abfd33b / PR aws#872, docs/configuration.md:196). I downgrade the brief's already-fixed: functional workaround and docs are in place, but the CLI flag the issue explicitly requests does not exist at v0.20.2 and the silent-strip footgun remains.

The fix

No deploy-path or CDK change needed (field + wiring already correct at pinned versions). Actionable work, both in CLI: (1) Expose executionRoleArn as a flag — add a Commander .option('--execution-role-arn ', ...) in src/cli/primitives/AgentPrimitive.tsx (option block ~254-326, currently has --network-mode/--authorizer-type but no role flag) and map it onto spec.executionRoleArn in the non-interactive add path (optionally on agentcore create too). (2) UX hardening for the silent strip: have validate/parse warn on unknown top-level runtime keys (or switch AgentEnvSpecSchema to a strict variant in validate) so a future roleArn-style typo surfaces instead of being dropped silently — this is what would have saved the reporter. Docs already done (docs/configuration.md:196, PR aws#872).

Files touched: Flag enhancement: src/cli/primitives/AgentPrimitive.tsx (option registration ~lines 254-326 + the non-interactive add handler that builds AgentEnvSpec). Unknown-key warning: src/cli/commands/validate/action.ts (and/or AgentEnvSpecSchema in src/schema/schemas/agent-env.ts:306). Field/wiring already correct (no change): src/schema/schemas/agent-env.ts:334-335; src/assets/cdk/lib/cdk-stack.ts:114; @aws/agentcore-cdk AgentEnvironment.ts:53/78 and AgentCoreRuntime.ts:56,59,202 at tag v0.1.0-alpha.19. Docs already fixed: docs/configuration.md:196.

Validation evidence

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

SYMPTOM REPRODUCED AT BASE: stashed the fix and grepped base source — src/cli/primitives/AgentPrimitive.tsx and src/cli/commands/add/types.ts contain NO 'execution-role-arn'/'executionRoleArn' (confirmed absent). The capability existed only as schema key src/schema/schemas/agent-env.ts:335 (executionRoleArn: z.string().optional()), so a custom role could not be supplied via the CLI. AFTER FIX (built dist/cli/index.mjs): (1) add agent --help now prints --execution-role-arn <arn> ARN of an existing IAM execution role to use instead of creating a CDK-managed one [non-interactive]. (2) Manual end-to-end: create --no-agent then add agent --type byo ... --execution-role-arn arn:aws:iam::123456789012:role/MyRole --json wrote raw agentcore/agentcore.json line 19 nested inside the RoleAgent runtime entry: "executionRoleArn": "arn:aws:iam::123456789012:role/MyRole". (3) Wrote a 4-case integ test (later removed) driving the real built CLI via test-utils: help shows flag; ARN round-trips through AgentCoreProjectSpecSchema.parse via readProjectConfig (proves not stripped); field is undefined when flag omitted; invalid ARN not-an-arn is rejected (exit!=0). All 4 passed. The new schema-mapper round-trip unit tests (mapGenerateConfigToAgent - executionRoleArn) also pass.

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%	13595 / 36580
🔵	Statements	36.43%	14454 / 39670
🔵	Functions	31.8%	2333 / 7336
🔵	Branches	31.11%	9004 / 28940

Generated in workflow #108 for commit 3a221ee by the Vitest Coverage Report Action