fix(unit-only): DX gap, not a schema defect (the breaking change was inte... (#719)

[aidandaly24]

Refs aws#719

Issues

• agentcore.json: "unknown keys (remove): agents" after upgrading to v0.4.0 — migration guide for agents→runtimes and type→authorizerType aws/agentcore-cli#719 — Any AgentCore project created before the v0.4.0 schema rename (agents->runtimes, credential type->authorizerType) fails to validate, deploy, or run ANY project-aware command (deploy/add/invoke/import/export/validate) after upgrading. The CLI emits a cryptic Zod error ("root: unknown keys (remove): "agents"") with zero hint that the field was renamed and no auto-migration. Bounded to users upgrading existing pre-v0.4.0 projects; new projects are unaffected.

Root cause

Reproduced live against the v0.20.2 schema. The top-level AgentCoreProjectSpecSchema is .strict() (src/schema/schemas/agentcore-project.ts:564), so the legacy agents key produces an unrecognized_keys issue at the root. PR aws#706 renamed agents->runtimes (schema field at agentcore-project.ts:398; confirmed in CHANGELOG.md:647) and PR aws#709 renamed the credential discriminator type->authorizerType (z.discriminatedUnion('authorizerType', ...) at agentcore-project.ts:346). The error flows verbatim: ConfigIO.readProjectSpec (src/lib/schemas/io/config-io.ts:113) -> readAndValidate safeParse (config-io.ts:325) -> ConfigValidationError (src/lib/errors/types.ts:218-225) -> formatZodErrors -> formatZodIssue unrecognized_keys branch "unknown keys (remove)" (src/lib/errors/zod.ts:69-72) -> validate/action.ts formatError (src/cli/commands/validate/action.ts:200). readProjectSpec is the universal gate (27 call sites across commands), so the block is total, not validate-only. There is NO .transform()/preprocess back-compat for agents and no migrate command (verified by grep; harness.ts has legacy preprocess and payments silently drops the removed pattern key per agentcore-project.test.ts:442, but agents/credentials got neither). NUANCE correcting the brief: the leftover credential type does NOT surface as "unknown keys (remove): type" — it surfaces as a discriminated-union failure on the missing authorizerType (zod.ts:76-78 -> "invalid "authorizerType" value"); and a leftover type on a runtime entry is silently stripped (AgentEnvSpecSchema is not .strict()), so removing it is cosmetic, not required.

The fix

DX gap, not a schema defect (the breaking change was intentional and announced in CHANGELOG.md:598-604). Best fix: a Zod .preprocess on AgentCoreProjectSpecSchema that auto-renames legacy keys at parse time (agents->runtimes, credential type->authorizerType, strip runtime type) so old projects keep working with zero user action — this mirrors the existing legacy-aware .preprocess pattern in src/schema/schemas/primitives/harness.ts:374. Cheaper alternative: a targeted friendly error mirroring the httpGateways .max(0, '...') deprecation pattern at agentcore-project.ts:545-551, e.g. add an agents field that errors with "The 'agents' field was renamed to 'runtimes' in v0.4.0; rename it and change credential 'type' to 'authorizerType'." At minimum, make the cryptic root message name the rename instead of only living in GitHub issue aws#719. A full agentcore migrate command is the heaviest option and likely unnecessary given the migration is 3 deterministic edits.

Files touched: src/schema/schemas/agentcore-project.ts (AgentCoreProjectSpecSchema, ~line 390-564): add a .preprocess wrapper that renames legacy keys, OR add an agents deprecation field next to the httpGateways pattern at line 545-551 plus a credential-level hint. Optionally src/cli/commands/validate/action.ts:199 formatError for a targeted upgrade hint, and docs/configuration.md for the written migration guide. No new migrate command exists today. CDK and SDK are NOT touched.

Validation evidence

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

BUILD: OK (.../dist/cli/index.mjs). REPRODUCED original symptom on pristine code (fix stashed): AgentCoreProjectSpecSchema.safeParse({name,version, agents:[...], credentials:[{type:'ApiKeyCredentialProvider',...}]}) -> success=false with TWO bare Zod issues: path [] message "Unrecognized key: "agents"" (Zod v4 phrasing of the issue's unknown keys (remove): \"agents\" from the .strict() top-level object) AND path [credentials,0,authorizerType] message "Invalid discriminator value. Expected 'ApiKeyCredentialProvider' | 'OAuthCredentialProvider' | 'PaymentCredentialProvider'". No rename hint, no migration -- matches the reported symptom exactly. AFTER fix restored: same legacy spec parses success=true; result.data.runtimes has 1 entry (name 'MyAgent'), 'agents' absent from output, credentials[0].authorizerType === 'ApiKeyCredentialProvider'. The bare unknown-keys/agents message is ABSENT. End-to-end via the BUILT CLI: created temp project /tmp/acfix-719-legacy.* with a pre-v0.4.0 agentcore.json (top-level 'agents' + credential 'type'); node <abs>/dist/cli/index.mjs validate got PAST the project-spec parse (no Zod error) and, once aws-targets.json was added, exited 0 printing "Valid" (only an unrelated Node-version SDK warning). This proves the fix flows through the real readProjectSpec path. Fix = z.preprocess(migrateLegacyProjectSpec, AgentCoreProjectSpecBaseSchema) in src/schema/schemas/agentcore-project.ts (renames agents->runtimes and credential type->authorizerType be

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.25%	13648 / 36635
🔵	Statements	36.51%	14508 / 39730
🔵	Functions	31.93%	2347 / 7350
🔵	Branches	31.23%	9055 / 28992

Generated in workflow #140 for commit 20ac6df by the Vitest Coverage Report Action