feat(migrate): add agentcore migrate

[notgitika]

Description

Adds agentcore migrate, which upgrades a v0 project to the v1 format without replacing any deployed resource. Runtimes, memories (and their data), gateways, evaluators and the rest keep their ARNs.

agentcore migrate                 preview, then "Apply these changes? (y/N)" on a terminal
agentcore migrate --yes           preview, then apply a ready migration without asking (CI)
agentcore migrate --target prod   migrate that deployment target (required when several are deployed)
agentcore migrate --json          the preview (and, with --yes, the result) as JSON

One flow, every run

Every agentcore migrate run computes the full read-only preview from scratch: checks, file changes, and the selected target's refactor and first v1 deploy. Nothing from an earlier run is saved or reused.

• On a terminal it then asks Apply these changes? (y/N).
• --yes skips only the prompt. The checks still apply, and a not-ready preview never applies.
• Non-interactive and --json runs without --yes print the summary (or, with --json, the full plan as JSON) and stop, exiting 0 when ready and 1 when not.
• There is no --dry-run.
• Outside a project you get the standard error. In a project that's already v1 with nothing pending, it says there's nothing to migrate.

Output

migrate prints a short summary on stdout. The full plan (every check, the names table, every file, each stack's moves, and the first v1 deploy's changes per resource) goes to agentcore/.cli/migrate/plan-<UTC>.md on every run, and the result of applying goes to result-<UTC>.md. Migrate never reads these back, and the git check ignores the directory even when a project's .gitignore doesn't. Progress (each step, and the stack's resource events while a refactor executes) uses the shared runWithProgress task list on stderr.

Migration plan: testingmigrate3 → v1 (target default, 998846730471/us-east-1)
  Keeps the names of 3 deployed resources (runtime agent, memory agentMemory, gateway gw)
  Moves 8 resources in AgentCore-testingmigrate3-default to new logical IDs (stack refactor)
  First v1 deploy: replaces nothing; updates 1 resource in place
  Changes 11 files (agentcore/agentcore.json, agentcore/cdk/…)

Full plan: agentcore/.cli/migrate/plan-20261013T234046Z.md

Apply these changes? (y/N)

A plan that isn't ready lists one line per blocker, then the report path:

Not ready to migrate: 3 issues need fixing first.
  ✖ cdk library: This CLI's v1 CDK app uses @aws/agentcore-cdk 1.0.0-rc.3, which doesn't keep v0 resource names (…)
  ✖ v1 synth: The CDK library the v1 app synthesized with doesn't support migratedFrom yet, …
  ✖ stack plan skipped: the converted project's v1 CDK app didn't synthesize (see the v1 synth check)

After applying, it prints one line per stack and the next step. A partial or unknown outcome keeps the refactor ID and the commands to check it on stdout. With AGENTCORE_MIGRATE_CDK_LIBRARY (testing only), both the summary and the next steps include the cd agentcore/cdk && npm install <library> --no-save command, to run before agentcore deploy.

Target selection

Deployed targets	What migrate does
0	Converts the project files only.
1	Selects it automatically.
Several	--target <name> is required; only that target is planned and refactored.

There is no --all-targets flag.

• Account check: the active credentials must belong to the selected target's account. Otherwise the plan blocks, naming the expected account, the active account and the region.
• Several targets: the first run converts the files, refactors the selected target, and records the others as pending, without storing a precomputed refactor for them. agentcore migrate --target <other> then migrates each one with its own fresh preview, built from the current v1 files and its still-v0 stack. That's what "finish pending migration" means; it isn't a separate mode.

How migration keeps resources

v1 renames almost every CloudFormation logical ID, and most AgentCore resource names can't change after creation, so deploying v1 over a v0 stack would replace them. Migration avoids that in two parts:

1. v0 physical names, through migratedFrom. The converted agentcore.json gets "version": 2, "migratedFrom": "v1", where "v1" is the schema version the v0 CLI wrote. The CDK library then builds every physical name the v0 way.
2. Logical IDs are renamed with CloudFormation stack refactoring. Migrate maps each v0 logical ID to its v1 ID by resource identity. It then refactors the stack with a bridge template: the deployed template with only references renamed, so literal strings such as IAM PolicyName stay untouched.

The journal

agentcore/.cli/migration-state.json is written atomically, before migrate changes anything. If it can't be written, nothing changes. It's updated as each step completes:

• The files' phase: writing → written → installed, plus where the v0 backup is.
• Each target that still has v0 logical IDs: pending, or refactoring with the refactor ID once a refactor is created.
• The targets already refactored.

A run stopped at any point is either finished or undone by running migrate again:

• Stopped while writing the files: the preview offers to put the v0 files back from the backup.
• Nothing refactored and the refactor known not to have started: the v0 files are put back, and the record is removed.
• A refactor the record says was running: it's read back first. If it finished, the logical IDs are verified and the migration carries on. If it never ran, it's planned again. If it's still running, or its state isn't known, migrate blocks with the commands to check it.

Unknown execute outcomes

Only a synchronous 4xx client error from ExecuteStackRefactor counts as "not started". Timeouts, 5xx errors, network errors and lost responses are unknown, and repeated AVAILABLE reads aren't treated as proof. An unknown outcome:

• stops the migration
• keeps the journal with the refactor ID
• never puts the files back
• prints the refactor ID with aws cloudformation describe-stack-refactor --stack-refactor-id <id> --region <r> and aws cloudformation list-stack-resources --stack-name <s> --region <r>

A rerun reconciles using that ID.

Deploy precheck

Deploying a target the journal still lists as pending (or refactoring) is refused. The error names the target's account and region and points to agentcore migrate --target <name>. Other targets deploy as usual.

• Where it runs: in the project manager's deploy, which covers the deploy command, the TUI and harness dev's auto-deploy, and in the v0 deploy delegation.
• A migration stopped while writing the project files blocks every target.

agentcore/cdk file check

Migrating replaces agentcore/cdk wholesale, so any added or modified file there blocks, and the preview lists each one with guidance to move the custom code out or revert it.

• What's compared: every file except node_modules, cdk.out and dist, compared (formatting aside) with what each release from v0.4.0 to v0.31.1 and 1.0.0-preview.1 to .33 vended. That data is generated from the release tags by scripts/generate-v0-cdk-apps.ts into v0CdkApps.ts.
• package.json may differ only in dependency versions, since v0 deploys re-pin them.
• The lockfile may record only the manifest's packages.

Other checks and the plan

• Checks:
  • the project is v0
  • the git tree is clean (re-enforced at apply)
  • the CDK dependencies are a supported version
  • knowledge bases, datasets and capacity providers: the message explains how to keep their data or remove them, and links to the preserve-resources guide
  • deployed state is present
  • the selected stack is stable with no stack policy
  • nothing is deployed outside the v0 app's constructs
  • the CLI's vended @aws/agentcore-cdk honors migratedFrom
• Conversion: the project is converted in a temporary copy (spec v2, harness.yaml, the v1 CDK app) and synthesized. The first v1 deploy is predicted with @aws-cdk/cloudformation-diff.
• These block the plan:
  • replacing or deleting AgentCore resources, ECR repositories or harness roles
  • stateful resources that aren't retained
  • unknown types
  • names v0 naming doesn't reproduce
  • properties the service can't change in place
  • custom-name replacements
  • type changes
  • chained or swapped renames
  • nested stacks
• Applying:
  1. CreateStackRefactor, with a TemplateURL through the CDK bootstrap bucket for templates over 51,200 bytes.
  2. Execution happens only if CloudFormation's actions match the planned moves exactly.
  3. ExecuteStackRefactor.
  4. A check that the physical IDs are unchanged.
• Credential providers in a migrated project keep v0's bare names and are never deleted.

Dependencies

• Hard: an @aws/agentcore-cdk release that honors migratedFrom, vended in src/assets/cdk/package.json. Until then, the plan fails its cdk library check. AGENTCORE_MIGRATE_CDK_LIBRARY (dev/test only) plans against a local library build; it warns loudly and never writes the override into the project. MIN_MIGRATED_FROM_CDK_VERSION is bumped together with the vended pin.
• Already merged: v0 project loading (feat(compat): load v0 projects and delegate deployment #2575), hyphenated target names (feat(targets): allow hyphens in target names #2577), v0 credential names (feat(compat): keep v0 credential provider names #2579) and the version/library check (feat(compat): fail when project version and CDK library disagree #2578).

Library PR: aws/agentcore-l3-cdk-constructs#423 adds migratedFrom support.

Related Issue

No public issue yet. This follows the reviewed v0→v1 compatibility and migration proposal, like #2575.

Documentation PR

The migration guide is in progress separately. MIGRATION_DOCS_URL and PRESERVE_RESOURCES_DOCS_URL hold the expected page URLs, to be confirmed when it's published. command.md is generated, so it isn't edited here.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other (please describe):

Testing

• I ran bun test: 4436 pass, 0 fail. The tests cover:
  • the preview-then-apply flow: prompt, --yes, --json, non-interactive runs, and the removed --dry-run
  • target selection and the account check
  • the journal: recorded first, atomic, phases, refusing to start when it can't be written, undo after an interrupted write
  • finishing pending targets, and reconciling a recorded refactor (finished, never ran)
  • 4xx-vs-unknown execute outcomes
  • the deploy precheck for each entry point: the CLI deploy, the TUI deploy screen, harness dev's deploy, the project manager, and the v0 deploy delegation
  • the agentcore/cdk file check: added and modified files, package.json and lockfile rules, generated directories, old releases and previews
• I ran the relevant end-to-end tests with bun run test:e2e, or explained why they are not applicable. There's no migrate e2e suite yet. Earlier revisions were migrated live end to end on real deployed v0 projects (CodeZip and container, v0 0.31.1). Every ARN, createdAt and IAM RoleId and the memory data stayed identical through migrate --yes and the first v1 deploy, and cdk diff was clean afterwards. The agentcore/cdk file check was also run over every v0 project on hand, and every unmodified one passes.
• I ran bun run typecheck
• I ran bun run lint:check
• I ran bun run format:check
• I ran bun run build
• If I modified src/assets/, I updated affected snapshots with bun test <test-file> --update-snapshots and committed them (not modified)

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 (command.md is generated; the migration guide is separate)
• 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 (the @aws/agentcore-cdk release with migratedFrom is pending)

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the
terms of your choice.

[agentcore-devx-automation]

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

[agentcore-devx-automation]

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

[codecov-commenter]

Codecov Report

❌ Patch coverage is 93.13640% with 79 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.55%. Comparing base (0c43c32) to head (341c5a5).

Files with missing lines	Patch %	Lines
src/core/project/migrate/convertHarness.ts	73.28%	39 Missing ⚠️
src/core/project/migrate/apply.ts	91.37%	32 Missing ⚠️
src/core/project/migrate/files.ts	95.13%	7 Missing ⚠️
src/core/project/migrate/convertSpec.ts	99.71%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2584      +/-   ##
============================================
+ Coverage     96.33%   96.55%   +0.21%     
============================================
  Files           671      697      +26     
  Lines         51321    56670    +5349     
============================================
+ Hits          49439    54716    +5277     
- Misses         1882     1954      +72     

☔ 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]

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

[agentcore-devx-automation]

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

[agentcore-devx-automation]

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

[agentcore-devx-automation]

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

[agentcore-devx-automation]

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

[AlexanderRichey]

I pulled this down and tried to run it but ran into a few errors.

---

If I create a new project with the latest v0 CLI, deploy, and try to migrate, I get these errors:

Not ready to migrate: 3 issues need fixing first.
  ✖ cdk library: This CLI's v1 CDK app uses @aws/agentcore-cdk 1.0.0-rc.3, which doesn't keep v0 resource names (migratedFrom needs 1.0.0-rc.4 or later), so the first deploy…
  ✖ v1 synth: The CDK library the v1 app synthesized with doesn't support migratedFrom yet, so it can't keep this project's v0 resource names.
  ✖ stack plan skipped: the converted project's v1 CDK app didn't synthesize (see the v1 synth check)

I'd expect this to work as a main case.

---

This CLI's v1 CDK app uses @aws/agentcore-cdk 1.0.0-rc.3, which doesn't keep v0 resource names (migratedFrom needs 1.0.0-rc.4 or later), so the first deploy after migrating would replace this project's resources. Update the AgentCore CLI to a release with that library, then run agentcore migrate again.

Can we include the command the user has to run in this message so that it's clear how to fix?

---

agentcore/cdk isn't the CDK app a release that creates v0 projects (v0.4.0 to v0.31.1, 1.0.0-preview.1 to 1.0.0-preview.33) created; compared with v0 0.20.0 to…

Unclear what this means.

[notgitika]

@AlexanderRichey

1. My bad, I should have included testing instructions. migrate needs the library change in aws/agentcore-l3-cdk-constructs#423, which isn't released yet, so it refuses on purpose (otherwise the first v1 deploy would replace the runtime and memory). To test against it:

in a checkout of #423

npm pack --ignore-scripts
export AGENTCORE_MIGRATE_CDK_LIBRARY=/path/to/aws-agentcore-cdk-1.0.0-rc.3.tgz
agentcore migrate

after migrating, before deploying:

cd agentcore/cdk && npm install /path/to/aws-agentcore-cdk-1.0.0-rc.3.tgz --no-save && cd ../..
agentcore deploy

I'll add this to the PR description.

2. good call, I'll change it to: "Run agentcore update, then run agentcore migrate again."
3. I'll fix up the messaging but this fails because it's the check that agentcore/cdk is still exactly what v0 generated, since migrating replaces that folder and any custom CDK code there would be lost. I couldn't reproduce it with a fresh 0.31.1 project. Could you paste the cdk app section of the full plan (agentcore/.cli/migrate/plan-*.md)? It lists the files that differ.

I'll also have the summary show the edited files instead of hiding them

[jariy17]

pretty good. My comments could be follow up prs.

[jariy17]

Simplify the unsupported-resource errors

I tested migration with a project containing knowledge bases, datasets, capacity providers, and online insights.

Currently, the summary prints:

✖ supported resources: This project uses knowledge bases (ReviewKnowledge); datasets (ReviewDataset); capacity providers (ReviewCapacity), which v1 doesn't support yet.
✖ Dataset ApplicationDatasetReviewDataset9D0FBD40: the v1 template has no counterpart, so the v1 deploy would delete it
✖ CapacityProvider ApplicationCapacityProviderReviewCapacity1B8156D5: the v1 template has no counterpart, so the v1 deploy would delete it
✖ OnlineEvaluationConfig ApplicationOnlineEvalReviewInsights9296C75D: the v1 template has no counterpart, so the v1 deploy would delete it

Could we remove the individual deletion messages from the summary and point users to the full plan for remediation?

Proposed:

✖ Migration blocked: This project uses resources that v1 doesn't support yet: knowledge bases, datasets, capacity providers, and online insights.

Please see the full plan for instructions on how to fix this issue.
Full plan: <path to migration plan>

[jariy17]

Include online insights in the unsupported-resources summary

I also added online insights (ReviewInsights). The full plan correctly says:

This project runs online insights (ReviewInsights), which v1 doesn't support.

But the terminal summary omits online insights from the unsupported-resources list. It only appears as an OnlineEvaluationConfig that the v1 deploy would delete. Could we include it in the unsupported-resources summary, as shown above?

[jariy17]

Remove the deletion instructions

Could we remove these deletion instructions from the plan?

If you don't need them: remove them from agentcore/agentcore.json and run `agentcore deploy`. This deletes them from AWS.

Remove the insights settings from those online eval configs in agentcore/agentcore.json and run `agentcore deploy`; insights hold no data to keep.

I don’t think we should encourage customers to delete resources to complete migration.

[jariy17]

Automatically prepare retention policies

Could migration automatically apply DeletionPolicy: Retain to unsupported resources and their required dependencies, instead of asking customers to edit the generated CDK app? Show the proposed changes for confirmation, then deploy and verify the retention policies before removing any resources from the stack. This would make the preservation steps easier to follow.

[jariy17]

Explain why the code is needed

Instead of explaining what the code does, explain why we need it. For example, scripts/generate-v0-cdk-apps.ts exists so migration can recognize CDK files generated by older CLI versions and avoid overwriting customer customizations. Could we include that rationale in the script's introductory comment?

[jariy17]

Fix the unsupported dry-run command in the instructions

The preservation instructions in src/core/project/migrate/preflight.ts:203 tell users to run agentcore migrate --dry-run, but the migrate command doesn't register a --dry-run flag.