feat(config-bundle): add --kms-key for customer-managed encryption

[jariy17]

Summary

Adds (CMK) encryption for AgentCore configuration bundles. A new --kms-key <arn> flag and an optional wizard step set kmsKeyArn in agentcore.json, validated by the shared KmsKeyArnSchema. The value flows through the create control-plane API and the L3 ConfigurationBundle construct (as KmsKeyArn).

CFN property name (KmsKeyArn) verified against the official AWS CloudFormation resource reference for AWS::BedrockAgentCore::ConfigurationBundle.

Important

Depends on aws/agentcore-l3-cdk-constructs#294 — merge and release @aws/agentcore-cdk first so the vended CDK project emits KmsKeyArn.

Changes

• src/schema/schemas/primitives/config-bundle.ts — kmsKeyArn (reuses KmsKeyArnSchema)
• src/cli/aws/agentcore-config-bundles.ts — option + create request body
• src/cli/primitives/ConfigBundlePrimitive.ts — --kms-key flag, threaded through add()
• src/cli/tui/screens/config-bundle/*, src/cli/tui/hooks/useCreateConfigBundle.ts — optional wizard step
• schemas/agentcore.schema.v1.json — regenerated

Tests

• API wrapper: createConfigurationBundle includes/omits kmsKeyArn in request body
• Wizard: kmsKey step advance/store/skip/back-navigation
• Integration (add-remove-config-bundle.test.ts): --kms-key persisted in full-options add; invalid KMS ARN rejected
• Full suite: 5546 passing, no snapshot drift; lint clean

Manual verification

agentcore add config-bundle --kms-key <arn> writes kmsKeyArn to agentcore.json; an invalid ARN is rejected at write-time; omitting the flag writes no field; synthesizing the bundle produces KmsKeyArn on the CFN resource.

[github-actions]

Package Tarball

aws-agentcore-0.21.0.tgz

How to install

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

[agentcore-devx-automation]

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

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	37.44%	13781 / 36808
🔵	Statements	36.72%	14659 / 39919
🔵	Functions	32.07%	2363 / 7366
🔵	Branches	31.47%	9188 / 29190

Generated in workflow #3844 for commit 91b9afd by the Vitest Coverage Report Action

[agentcore-cli-automation]

Nice, focused change overall — wizard step plumbing, validation reuse, and API/test coverage all line up. A couple of items worth addressing before merge:

1. Missing telemetry for the new feature. Per src/cli/telemetry/README.md, new features should be instrumented. add.config-bundle is currently absent from COMMAND_SCHEMAS in src/cli/telemetry/schemas/command-run.ts (note remove.config-bundle is already there), and this PR adds a meaningful new attribute (CMK usage) that we'd want visibility on. Recommend adding an add.config-bundle entry with at least has_kms_key: z.boolean() (and maybe component_count: Count) and wiring it through the CLI handler with runCliCommand/withCommandRunTelemetry. See inline comment for specifics.

2. Inconsistent up-front validation for --kms-key. EvaluatorPrimitive validates the same ARN format up-front with a clear, flag-named error (--kms-key-arn must be a valid KMS key ARN ...). This PR relies on the Zod schema at writeProjectSpec time, so a bad ARN surfaces as a generic schema validation error. The integ test only asserts json.error exists, so it doesn't catch the worse message. Either add an up-front isValidKmsKeyArn check in the action handler (matching the evaluator pattern), or accept the trade-off but assert the resulting error message in the integ test so we know what users see.

3. Cross-repo release ordering. The PR description correctly calls out the dependency on aws/agentcore-l3-cdk-constructs#294. Worth confirming explicitly in this PR's status checks: if @aws/agentcore-cdk isn't published with KmsKeyArn support and bundled into this CLI's tarball (bundled-agentcore-cdk.tgz in CDKRenderer) before this lands, the --kms-key flag will silently no-op at deploy time. Not a code change request — just flagging that the bundled CDK version needs to roll forward as part of merging this.

A couple of smaller notes inline.

[agentcore-cli-automation]

Inconsistent up-front validation + missing telemetry on this handler.

(1) EvaluatorPrimitive.ts:298 validates kmsKeyArn with isValidKmsKeyArn right before calling this.add(...) and fails with a clear, flag-named message. Here, an invalid ARN falls through to writeProjectSpec's Zod validation, producing a generic schema error. The integ test (integ-tests/add-remove-config-bundle.test.ts:243) only asserts json.error is defined, so the worse message wouldn't be caught. Either:

• Mirror EvaluatorPrimitive and add an explicit isValidKmsKeyArn check just before this this.add({...}) call that calls fail('--kms-key must be a valid KMS key ARN ...').
• Or keep relying on the Zod schema, but tighten the integ test to assert the actual error message users see.

(2) Missing telemetry instrumentation. Per src/cli/telemetry/README.md, new features should be instrumented. add.config-bundle isn't in COMMAND_SCHEMAS (src/cli/telemetry/schemas/command-run.ts) at all today, and this PR is a natural opportunity to add it since we now have an interesting attribute to track (CMK adoption). Suggested:

// command-run.ts
const AddConfigBundleAttrs = safeSchema({
  has_kms_key: z.boolean(),
  component_count: Count,
});
// ...
'add.config-bundle': AddConfigBundleAttrs,

Then wrap this non-interactive handler in runCliCommand('add.config-bundle', !!cliOptions.json, async () => { ...; return { has_kms_key: !!cliOptions.kmsKey, component_count: Object.keys(components).length }; }).

[agentcore-cli-automation]

Reusing KmsKeyArnSchema from ./evaluator is fine, but that schema's JSDoc in evaluator.ts:128-130 explicitly says it's the pattern accepted by the AgentCore Evaluation service, and notes alias ARNs are unsupported for evaluator encryption. Since this is now shared across services (evaluator + config bundle), please either:

1. Move KmsKeyArnSchema/KMS_KEY_ARN_PATTERN/isValidKmsKeyArn to a shared/generic location with a service-agnostic docstring, or
2. At minimum, update the JSDoc on KmsKeyArnSchema in evaluator.ts to reflect that it's the general KMS key-ARN pattern used across multiple AgentCore resources, and confirm the Configuration Bundle service has the same alias-ARN constraint as the Evaluator service (so users aren't getting a needlessly stricter check than the service requires).

[agentcore-cli-automation]

Minor UX note (non-blocking): the wizard now unconditionally shows the KMS step to every user creating a config bundle, even though CMK is an advanced/opt-in feature. Given the prompt explicitly says "press Enter to skip", this is probably acceptable, but consider whether this should be gated behind a yes/no question ("Encrypt with a customer-managed KMS key?") so the common path doesn't grow an extra prompt. Feel free to ignore if this was a deliberate design choice.

[agentcore-devx-automation]

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