@aws/nx-plugin 1.0.0-rc.60 → 1.0.0-rc.62

package/migrations.json

@@ -7,75 +7,85 @@
       "description": "Add agent runtime target support to the vended AgentCoreGateway construct and an agentName member to vended agent constructs",
       "implementation": "./src/migrations/latest/gateway-agent-targets/migration"
     },
-    "latest-gateway-cognito-passthrough": {
-      "version": "1.0.0-rc.60",
-      "description": "Front Cognito agents with an AgentCore Gateway via JWT passthrough: addAgent picks the target credential from the agent's auth, agent constructs gain an auth member, and Cognito runtimes allowlist the Authorization header",
-      "implementation": "./src/migrations/latest/gateway-cognito-passthrough/migration"
-    },
     "latest-smithy-ssdk-bundle-pins": {
       "version": "1.0.0-rc.58",
       "description": "Bump the rolldown and dts plugin pins in the Smithy build.Dockerfile so the bundled SSDK type declaration resolves",
       "implementation": "./src/migrations/latest/smithy-ssdk-bundle-pins/migration"
     },
-    "latest-strip-pip-from-python-images": {
+    "latest-gateway-cognito-passthrough": {
       "version": "1.0.0-rc.60",
-      "description": "Remove pip from vended Python agent / MCP server images so its vulnerable vendored packages are not present at runtime",
-      "implementation": "./src/migrations/latest/strip-pip-from-python-images/migration"
+      "description": "Front Cognito agents with an AgentCore Gateway via JWT passthrough: addAgent picks the target credential from the agent's auth, agent constructs gain an auth member, and Cognito runtimes allowlist the Authorization header",
+      "implementation": "./src/migrations/latest/gateway-cognito-passthrough/migration"
     },
     "latest-waf-log-group-removal": {
       "version": "1.0.0-rc.60",
       "description": "Set RemovalPolicy.DESTROY on WAF log groups in the vended AgentCoreGateway and REST API constructs so a rolled-back deploy does not orphan them",
       "implementation": "./src/migrations/latest/waf-log-group-removal/migration"
     },
-    "v1.0.0-rc.50-modernize-function-props-cast": {
+    "latest-strip-pip-from-python-images": {
+      "version": "1.0.0-rc.60",
+      "description": "Remove pip from vended Python agent / MCP server images so its vulnerable vendored packages are not present at runtime",
+      "implementation": "./src/migrations/latest/strip-pip-from-python-images/migration"
+    },
+    "latest-py-agent-lifespan-construction": {
+      "version": "1.0.0-rc.61",
+      "description": "Move py#agent HTTP/AG-UI agent construction out of module import time and into a FastAPI lifespan handler, stored on app.state",
+      "implementation": "./src/migrations/latest/py-agent-lifespan-construction/migration"
+    },
+    "latest-rename-load-runtime-config-target": {
+      "version": "1.0.0-rc.62",
+      "description": "Clone the react website 'load:runtime-config' target to a 'load-runtime-config' target so it can be run with the verb syntax (nx load-runtime-config <project>)",
+      "implementation": "./src/migrations/latest/rename-load-runtime-config-target/migration"
+    },
+    "v1.0.0-rc.50-0001-modernize-function-props-cast": {
       "version": "1.0.0-rc.50",
       "description": "Replace the legacy angle-bracket FunctionProps type assertion with the modern as syntax in generated API constructs",
-      "implementation": "./src/migrations/v1.0.0-rc.50/modernize-function-props-cast/migration"
+      "implementation": "./src/migrations/v1.0.0-rc.50/0001-modernize-function-props-cast/migration"
     },
-    "v1.0.0-rc.50-restrict-cors-to-custom-domains": {
+    "v1.0.0-rc.50-0002-restrict-cors-to-custom-domains": {
       "version": "1.0.0-rc.50",
       "description": "Include CloudFront custom domain aliases in restrictCorsTo and UserIdentity callback URLs",
-      "implementation": "./src/migrations/v1.0.0-rc.50/restrict-cors-to-custom-domains/migration"
+      "implementation": "./src/migrations/v1.0.0-rc.50/0002-restrict-cors-to-custom-domains/migration"
     },
-    "v1.0.0-rc.50-terraform-bootstrap-adopt-existing-bucket": {
+    "v1.0.0-rc.50-0003-terraform-bootstrap-adopt-existing-bucket": {
       "version": "1.0.0-rc.50",
       "description": "Adopt an existing Terraform state bucket in the vended bootstrap script when its state object is missing",
-      "implementation": "./src/migrations/v1.0.0-rc.50/terraform-bootstrap-adopt-existing-bucket/migration"
+      "implementation": "./src/migrations/v1.0.0-rc.50/0003-terraform-bootstrap-adopt-existing-bucket/migration"
     },
-    "v1.0.0-rc.52-user-identity-waf-allow-localhost-callback": {
+    "v1.0.0-rc.52-0001-user-identity-waf-allow-localhost-callback": {
       "version": "1.0.0-rc.52",
       "description": "Count the EC2MetaDataSSRF_QUERYARGUMENTS WAF rule on the UserIdentity Web ACL so sign-in from a local dev server is not blocked",
-      "implementation": "./src/migrations/v1.0.0-rc.52/user-identity-waf-allow-localhost-callback/migration"
+      "implementation": "./src/migrations/v1.0.0-rc.52/0001-user-identity-waf-allow-localhost-callback/migration"
     },
-    "v1.0.0-rc.54-order-access-log-delivery-after-bucket-policy": {
+    "v1.0.0-rc.54-0001-order-access-log-delivery-after-bucket-policy": {
       "version": "1.0.0-rc.54",
       "description": "Order the S3 server access log delivery source after the bucket policy to avoid a 409 from concurrent bucket configuration writes",
-      "implementation": "./src/migrations/v1.0.0-rc.54/order-access-log-delivery-after-bucket-policy/migration"
+      "implementation": "./src/migrations/v1.0.0-rc.54/0001-order-access-log-delivery-after-bucket-policy/migration"
     },
-    "v1.0.0-rc.55-backfill-generator-metadata": {
+    "v1.0.0-rc.55-0001-backfill-generator-metadata": {
       "version": "1.0.0-rc.55",
       "description": "Backfill the project metadata the version sync reads, recovered from the files the generators left behind",
-      "implementation": "./src/migrations/v1.0.0-rc.55/backfill-generator-metadata/migration"
+      "implementation": "./src/migrations/v1.0.0-rc.55/0001-backfill-generator-metadata/migration"
     },
-    "v1.0.0-rc.56-dynamodb-local-remove-optimize-flag": {
+    "v1.0.0-rc.56-0001-dynamodb-local-remove-optimize-flag": {
       "version": "1.0.0-rc.56",
       "description": "Drop -optimizeDbBeforeStartup from the vended DynamoDB Local container script, which can corrupt shared-local-instance.db",
-      "implementation": "./src/migrations/v1.0.0-rc.56/dynamodb-local-remove-optimize-flag/migration"
+      "implementation": "./src/migrations/v1.0.0-rc.56/0001-dynamodb-local-remove-optimize-flag/migration"
     },
-    "v1.0.0-rc.57-ts-agent-session-management-support": {
+    "v1.0.0-rc.57-0001-ts-agent-session-management-support": {
       "version": "1.0.0-rc.57",
       "description": "Add session management support to ts#agent",
-      "implementation": "./src/migrations/v1.0.0-rc.57/ts-agent-session-management-support/migration"
+      "implementation": "./src/migrations/v1.0.0-rc.57/0001-ts-agent-session-management-support/migration"
     },
     "sync-vended-versions": {
-      "version": "1.0.0-rc.60",
+      "version": "1.0.0-rc.62",
       "description": "Sync vended dependency versions and the tracked plugin version to those vended by this release",
       "implementation": "./src/utils/version-upgrade-migration/migration"
     }
   },
   "packageJsonUpdates": {
     "nx-23.1.1-nx-packages": {
-      "version": "1.0.0-rc.60",
+      "version": "1.0.0-rc.62",
       "packages": {
         "nx": {
           "version": "23.1.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/nx-plugin",
-  "version": "1.0.0-rc.60",
+  "version": "1.0.0-rc.62",
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/nx-plugin-for-aws.git",

package/src/mcp-server/tools/general-guidance.js

@@ -64,7 +64,7 @@ ${PACKAGE_MANAGERS.map((pm)=>buildNxCommand('<options>', pm)).join(' - \n')}
 - Carefully examine the files that have been generated and always refer back to the generator guide when working in a generated project
 - Generate all projects into the \`packages/\` directory
 - After making changes to your projects, fix linting issues, then run a full build
-- When it's time to start testing a project, suggest to the user that infrastructure is deployed to AWS. For websites, if a runtime-config.json is needed, use the load:runtime-config target after a deployment to point a local website at a sandbox stack.
+- When it's time to start testing a project, suggest to the user that infrastructure is deployed to AWS. For websites, if a runtime-config.json is needed, use the load-runtime-config target after a deployment to point a local website at a sandbox stack.
 
 ## Batching Generators
 

package/src/mcp-server/tools/general-guidance.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../packages/nx-plugin/src/mcp-server/tools/general-guidance.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport type { NxGeneratorInfo } from '../../utils/generators';\nimport { IAC_PROVIDERS } from '../../utils/iac-providers';\nimport { buildNxCommand, fetchGuidePages } from '../generator-info';\nimport { PACKAGE_MANAGERS } from '../schema';\n\nexport const TOOL_SELECTION_GUIDE = `## Tool Selection Guide\n\n- Use the \\`general-guidance\\` tool for guidance and best practices for working with Nx and the Nx Plugin for AWS.\n- Use the \\`create-workspace-command\\` tool to discover how to create a workspace to start a new project.\n- Use the \\`add-to-existing-project\\` tool when adding the plugin to an existing Nx workspace or non-Nx monorepo, or when troubleshooting configuration errors in such a workspace.\n- Use the \\`upgrade-workspace\\` tool when upgrading Nx or the Nx Plugin for AWS to a newer version.\n- Use the \\`list-generators\\` tool to discover the available generators and how to run them.\n- Use the \\`generator-guide\\` tool to retrieve detailed information about a specific generator.`;\n\n/**\n * Add a tool which provides general guidance for using Nx and the Nx Plugin for AWS\n */\nexport const addGeneralGuidanceTool = (\n  server: McpServer,\n  generators: NxGeneratorInfo[],\n) => {\n  server.registerTool(\n    'general-guidance',\n    {\n      title: 'General Guidance',\n      description:\n        'Tool for guidance and best practices for working with Nx and the Nx Plugin for AWS',\n    },\n    async () => ({\n      content: [\n        {\n          type: 'text' as const,\n          text: `# Nx Plugin for AWS Guidance\n\n${TOOL_SELECTION_GUIDE}\n\n## Getting Started\n\n- Choose a package manager first. You can choose between ${PACKAGE_MANAGERS.join(', ')}. It's recommended to use \"pnpm\" if the user has no preference\n- Choose an infrastructure as code (IaC) provider next. You can choose between ${IAC_PROVIDERS.join(', ')}. It's recommended to use CDK if the user has no preference\n- Next, you must create an Nx workspace. Use the \\`create-workspace-command\\` tool for more details, and provide it with your chosen package manager\n- After this, you can start scaffolding the main components of your application using generators. Use the \\`list-generators\\` tool to discover available generators, and the \\`generator-guide\\` tool for more detailed information about a specific generator\n\n## Nx Primer\n\n- Prefix nx commands with the appropriate prefix for your package manager, for example:\n${PACKAGE_MANAGERS.map((pm) => buildNxCommand('<options>', pm)).join(' - \\n')}\n- Each project in your workspace has a file named \\`project.json\\` which contains important project information such as its name, and defines the \"targets\" which can be run for that project, for example building or testing the project\n- Use the command \\`nx reset\\` to reset the Nx daemon when unexpected issues arise\n- After adding dependencies between TypeScript projects, use \\`nx sync\\` to ensure project references are set up correctly\n\n## General Instructions\n\n- Each project declares the third-party runtime dependencies its source imports in its own \\`package.json\\`; shared build/test tooling (test runners, bundlers, etc.) is declared in the root \\`package.json\\` \\`devDependencies\\`. Versions follow a single version policy, recorded in the package manager's dependency catalog where supported (referenced as \\`catalog:\\`). Install with the appropriate command for your package manager:\n  - Add a project runtime dependency: \\`pnpm add <package> --filter <project>\\` / \\`yarn workspace <project> add <package>\\` / \\`npm install <package> -w <project>\\` / \\`bun add <package> --cwd <project-directory>\\`\n  - Add a shared dev tool at the root: \\`pnpm add -Dw <package>\\` / \\`yarn add -D <package>\\` / \\`npm install --legacy-peer-deps -D <package>\\` / \\`bun install -D <package>\\`\n- The \\`noUndeclaredDependencies\\` lint rule enforces that a project's source only imports packages declared in its own \\`package.json\\`\n- Projects in the same workspace can import one another directly by package name (eg \\`@workspace-name/project-name\\`) without declaring a dependency in \\`package.json\\` — TypeScript path aliases in \\`tsconfig.base.json\\` resolve these imports\n- When specifying project names as arguments to generators, prefer the _fully qualified_ project name, for example \\`@workspace-name/project-name\\`. Check the \\`project.json\\` file for the specific package to find its fully qualified name\n- When no generator exists for a specific framework required, use the base \\`ts#project\\` and \\`py#project\\` generators and build on top.\n- Leave the \\`--infra\\` option at its default value unless the user has explicitly instructed otherwise. Generators choose a sensible default type of infrastructure to deploy the project with, so only override \\`--infra\\` when the user has specified a particular requirement.\n\n## Useful Commands\n\n- Fix lint issues with \\`nx run-many --target lint --configuration=fix --all --output-style=stream\\`\n- Build all projects with \\`nx run-many --target build --all --output-style=stream\\`\n- Prefer importing the CDK constructs vended by generators in \\`packages/common/constructs\\` over writing your own\n\n## Best Practices\n\n- After running a generator, use the \\`nx show projects\\` command to check which projects have been added (if any)\n- Carefully examine the files that have been generated and always refer back to the generator guide when working in a generated project\n- Generate all projects into the \\`packages/\\` directory\n- After making changes to your projects, fix linting issues, then run a full build\n- When it's time to start testing a project, suggest to the user that infrastructure is deployed to AWS. For websites, if a runtime-config.json is needed, use the load:runtime-config target after a deployment to point a local website at a sandbox stack.\n\n## Batching Generators\n\nWhen scaffolding several projects in one go, chain generators to avoid a slow dependency install after every generator:\n\n- **Chain generators** with \\`&&\\` in a single command. Pass \\`--prefer-install-dependencies=false\\` on each generator except the last so dependencies install once at the end, for example:\n\n${PACKAGE_MANAGERS.map(\n  (pm) => `  \\`\\`\\`bash\n  ${buildNxCommand('g @aws/nx-plugin:ts#trpc-api --no-interactive --name=my-app-api --auth=IAM --prefer-install-dependencies=false', pm)} && \\\\\n    ${buildNxCommand('g @aws/nx-plugin:ts#react-website --no-interactive --name=my-app-website --prefer-install-dependencies=false', pm)} && \\\\\n    ${buildNxCommand('g @aws/nx-plugin:connection --no-interactive --sourceProject=@my-app/my-app-website --targetProject=@my-app/my-app-api --prefer-install-dependencies=false', pm)} && \\\\\n    ${buildNxCommand('g @aws/nx-plugin:ts#infra --no-interactive --name=infra', pm)} && \\\\\n    ${buildNxCommand('sync', pm)}\n  \\`\\`\\``,\n).join('\\n')}\n\n- **\\`--prefer-install-dependencies=false\\`** asks a generator to defer its dependency install so the batch installs once at the end (the final generator above omits the flag and installs everything).\n- **\\`nx sync\\`** is required before building — generators modify TypeScript project references.\n\n## Detailed Guides\n\nPlease refer to the below documentation for important details regarding workspaces and working with TypeScript or Python projects.\n\n${await fetchGuidePages(['workspace', 'typescript-project', 'python-project'], generators)}\n\n    `,\n        },\n      ],\n    }),\n  );\n};\n"],"names":["IAC_PROVIDERS","buildNxCommand","fetchGuidePages","PACKAGE_MANAGERS","TOOL_SELECTION_GUIDE","addGeneralGuidanceTool","server","generators","registerTool","title","description","content","type","text","join","map","pm"],"mappings":"AAAA;;;CAGC,GAGD,SAASA,aAAa,QAAQ,+BAA4B;AAC1D,SAASC,cAAc,EAAEC,eAAe,QAAQ,uBAAoB;AACpE,SAASC,gBAAgB,QAAQ,eAAY;AAE7C,OAAO,MAAMC,uBAAuB,CAAC;;;;;;;+FAO0D,CAAC,CAAC;AAEjG;;CAEC,GACD,OAAO,MAAMC,yBAAyB,CACpCC,QACAC;IAEAD,OAAOE,YAAY,CACjB,oBACA;QACEC,OAAO;QACPC,aACE;IACJ,GACA,UAAa,CAAA;YACXC,SAAS;gBACP;oBACEC,MAAM;oBACNC,MAAM,CAAC;;AAEjB,EAAET,qBAAqB;;;;yDAIkC,EAAED,iBAAiBW,IAAI,CAAC,MAAM;+EACR,EAAEd,cAAcc,IAAI,CAAC,MAAM;;;;;;;AAO1G,EAAEX,iBAAiBY,GAAG,CAAC,CAACC,KAAOf,eAAe,aAAae,KAAKF,IAAI,CAAC,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoC9E,EAAEX,iBAAiBY,GAAG,CACpB,CAACC,KAAO,CAAC;EACT,EAAEf,eAAe,kHAAkHe,IAAI;IACrI,EAAEf,eAAe,gHAAgHe,IAAI;IACrI,EAAEf,eAAe,8JAA8Je,IAAI;IACnL,EAAEf,eAAe,2DAA2De,IAAI;IAChF,EAAEf,eAAe,QAAQe,IAAI;QACzB,CAAC,EACPF,IAAI,CAAC,MAAM;;;;;;;;;AASb,EAAE,MAAMZ,gBAAgB;wBAAC;wBAAa;wBAAsB;qBAAiB,EAAEK,YAAY;;IAEvF,CAAC;gBACG;aACD;QACH,CAAA;AAEJ,EAAE"}
+{"version":3,"sources":["../../../../../../packages/nx-plugin/src/mcp-server/tools/general-guidance.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport type { NxGeneratorInfo } from '../../utils/generators';\nimport { IAC_PROVIDERS } from '../../utils/iac-providers';\nimport { buildNxCommand, fetchGuidePages } from '../generator-info';\nimport { PACKAGE_MANAGERS } from '../schema';\n\nexport const TOOL_SELECTION_GUIDE = `## Tool Selection Guide\n\n- Use the \\`general-guidance\\` tool for guidance and best practices for working with Nx and the Nx Plugin for AWS.\n- Use the \\`create-workspace-command\\` tool to discover how to create a workspace to start a new project.\n- Use the \\`add-to-existing-project\\` tool when adding the plugin to an existing Nx workspace or non-Nx monorepo, or when troubleshooting configuration errors in such a workspace.\n- Use the \\`upgrade-workspace\\` tool when upgrading Nx or the Nx Plugin for AWS to a newer version.\n- Use the \\`list-generators\\` tool to discover the available generators and how to run them.\n- Use the \\`generator-guide\\` tool to retrieve detailed information about a specific generator.`;\n\n/**\n * Add a tool which provides general guidance for using Nx and the Nx Plugin for AWS\n */\nexport const addGeneralGuidanceTool = (\n  server: McpServer,\n  generators: NxGeneratorInfo[],\n) => {\n  server.registerTool(\n    'general-guidance',\n    {\n      title: 'General Guidance',\n      description:\n        'Tool for guidance and best practices for working with Nx and the Nx Plugin for AWS',\n    },\n    async () => ({\n      content: [\n        {\n          type: 'text' as const,\n          text: `# Nx Plugin for AWS Guidance\n\n${TOOL_SELECTION_GUIDE}\n\n## Getting Started\n\n- Choose a package manager first. You can choose between ${PACKAGE_MANAGERS.join(', ')}. It's recommended to use \"pnpm\" if the user has no preference\n- Choose an infrastructure as code (IaC) provider next. You can choose between ${IAC_PROVIDERS.join(', ')}. It's recommended to use CDK if the user has no preference\n- Next, you must create an Nx workspace. Use the \\`create-workspace-command\\` tool for more details, and provide it with your chosen package manager\n- After this, you can start scaffolding the main components of your application using generators. Use the \\`list-generators\\` tool to discover available generators, and the \\`generator-guide\\` tool for more detailed information about a specific generator\n\n## Nx Primer\n\n- Prefix nx commands with the appropriate prefix for your package manager, for example:\n${PACKAGE_MANAGERS.map((pm) => buildNxCommand('<options>', pm)).join(' - \\n')}\n- Each project in your workspace has a file named \\`project.json\\` which contains important project information such as its name, and defines the \"targets\" which can be run for that project, for example building or testing the project\n- Use the command \\`nx reset\\` to reset the Nx daemon when unexpected issues arise\n- After adding dependencies between TypeScript projects, use \\`nx sync\\` to ensure project references are set up correctly\n\n## General Instructions\n\n- Each project declares the third-party runtime dependencies its source imports in its own \\`package.json\\`; shared build/test tooling (test runners, bundlers, etc.) is declared in the root \\`package.json\\` \\`devDependencies\\`. Versions follow a single version policy, recorded in the package manager's dependency catalog where supported (referenced as \\`catalog:\\`). Install with the appropriate command for your package manager:\n  - Add a project runtime dependency: \\`pnpm add <package> --filter <project>\\` / \\`yarn workspace <project> add <package>\\` / \\`npm install <package> -w <project>\\` / \\`bun add <package> --cwd <project-directory>\\`\n  - Add a shared dev tool at the root: \\`pnpm add -Dw <package>\\` / \\`yarn add -D <package>\\` / \\`npm install --legacy-peer-deps -D <package>\\` / \\`bun install -D <package>\\`\n- The \\`noUndeclaredDependencies\\` lint rule enforces that a project's source only imports packages declared in its own \\`package.json\\`\n- Projects in the same workspace can import one another directly by package name (eg \\`@workspace-name/project-name\\`) without declaring a dependency in \\`package.json\\` — TypeScript path aliases in \\`tsconfig.base.json\\` resolve these imports\n- When specifying project names as arguments to generators, prefer the _fully qualified_ project name, for example \\`@workspace-name/project-name\\`. Check the \\`project.json\\` file for the specific package to find its fully qualified name\n- When no generator exists for a specific framework required, use the base \\`ts#project\\` and \\`py#project\\` generators and build on top.\n- Leave the \\`--infra\\` option at its default value unless the user has explicitly instructed otherwise. Generators choose a sensible default type of infrastructure to deploy the project with, so only override \\`--infra\\` when the user has specified a particular requirement.\n\n## Useful Commands\n\n- Fix lint issues with \\`nx run-many --target lint --configuration=fix --all --output-style=stream\\`\n- Build all projects with \\`nx run-many --target build --all --output-style=stream\\`\n- Prefer importing the CDK constructs vended by generators in \\`packages/common/constructs\\` over writing your own\n\n## Best Practices\n\n- After running a generator, use the \\`nx show projects\\` command to check which projects have been added (if any)\n- Carefully examine the files that have been generated and always refer back to the generator guide when working in a generated project\n- Generate all projects into the \\`packages/\\` directory\n- After making changes to your projects, fix linting issues, then run a full build\n- When it's time to start testing a project, suggest to the user that infrastructure is deployed to AWS. For websites, if a runtime-config.json is needed, use the load-runtime-config target after a deployment to point a local website at a sandbox stack.\n\n## Batching Generators\n\nWhen scaffolding several projects in one go, chain generators to avoid a slow dependency install after every generator:\n\n- **Chain generators** with \\`&&\\` in a single command. Pass \\`--prefer-install-dependencies=false\\` on each generator except the last so dependencies install once at the end, for example:\n\n${PACKAGE_MANAGERS.map(\n  (pm) => `  \\`\\`\\`bash\n  ${buildNxCommand('g @aws/nx-plugin:ts#trpc-api --no-interactive --name=my-app-api --auth=IAM --prefer-install-dependencies=false', pm)} && \\\\\n    ${buildNxCommand('g @aws/nx-plugin:ts#react-website --no-interactive --name=my-app-website --prefer-install-dependencies=false', pm)} && \\\\\n    ${buildNxCommand('g @aws/nx-plugin:connection --no-interactive --sourceProject=@my-app/my-app-website --targetProject=@my-app/my-app-api --prefer-install-dependencies=false', pm)} && \\\\\n    ${buildNxCommand('g @aws/nx-plugin:ts#infra --no-interactive --name=infra', pm)} && \\\\\n    ${buildNxCommand('sync', pm)}\n  \\`\\`\\``,\n).join('\\n')}\n\n- **\\`--prefer-install-dependencies=false\\`** asks a generator to defer its dependency install so the batch installs once at the end (the final generator above omits the flag and installs everything).\n- **\\`nx sync\\`** is required before building — generators modify TypeScript project references.\n\n## Detailed Guides\n\nPlease refer to the below documentation for important details regarding workspaces and working with TypeScript or Python projects.\n\n${await fetchGuidePages(['workspace', 'typescript-project', 'python-project'], generators)}\n\n    `,\n        },\n      ],\n    }),\n  );\n};\n"],"names":["IAC_PROVIDERS","buildNxCommand","fetchGuidePages","PACKAGE_MANAGERS","TOOL_SELECTION_GUIDE","addGeneralGuidanceTool","server","generators","registerTool","title","description","content","type","text","join","map","pm"],"mappings":"AAAA;;;CAGC,GAGD,SAASA,aAAa,QAAQ,+BAA4B;AAC1D,SAASC,cAAc,EAAEC,eAAe,QAAQ,uBAAoB;AACpE,SAASC,gBAAgB,QAAQ,eAAY;AAE7C,OAAO,MAAMC,uBAAuB,CAAC;;;;;;;+FAO0D,CAAC,CAAC;AAEjG;;CAEC,GACD,OAAO,MAAMC,yBAAyB,CACpCC,QACAC;IAEAD,OAAOE,YAAY,CACjB,oBACA;QACEC,OAAO;QACPC,aACE;IACJ,GACA,UAAa,CAAA;YACXC,SAAS;gBACP;oBACEC,MAAM;oBACNC,MAAM,CAAC;;AAEjB,EAAET,qBAAqB;;;;yDAIkC,EAAED,iBAAiBW,IAAI,CAAC,MAAM;+EACR,EAAEd,cAAcc,IAAI,CAAC,MAAM;;;;;;;AAO1G,EAAEX,iBAAiBY,GAAG,CAAC,CAACC,KAAOf,eAAe,aAAae,KAAKF,IAAI,CAAC,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoC9E,EAAEX,iBAAiBY,GAAG,CACpB,CAACC,KAAO,CAAC;EACT,EAAEf,eAAe,kHAAkHe,IAAI;IACrI,EAAEf,eAAe,gHAAgHe,IAAI;IACrI,EAAEf,eAAe,8JAA8Je,IAAI;IACnL,EAAEf,eAAe,2DAA2De,IAAI;IAChF,EAAEf,eAAe,QAAQe,IAAI;QACzB,CAAC,EACPF,IAAI,CAAC,MAAM;;;;;;;;;AASb,EAAE,MAAMZ,gBAAgB;wBAAC;wBAAa;wBAAsB;qBAAiB,EAAEK,YAAY;;IAEvF,CAAC;gBACG;aACD;QACH,CAAA;AAEJ,EAAE"}

package/src/migrations/latest/py-agent-lifespan-construction/metadata.json

@@ -0,0 +1,3 @@
+{
+  "description": "Move py#agent HTTP/AG-UI agent construction out of module import time and into a FastAPI lifespan handler, stored on app.state"
+}

package/src/migrations/latest/py-agent-lifespan-construction/migration.js

@@ -0,0 +1,412 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { getProjects, joinPathFragments } from "@nx/devkit";
+import { PY_AGENT_GENERATOR_INFO } from "../../../py/agent/generator.js";
+import { addPythonDestructuredImport, applyGritQL, captureGritQLVariable, matchGritQL } from "../../../utils/ast.js";
+import { formatFilesInSubtree } from "../../../utils/format.js";
+/**
+ * Move py#agent HTTP/AG-UI agent construction out of module import time and
+ * into a FastAPI `lifespan` handler, stored on `app.state`.
+ *
+ * Building the agent eagerly at import time breaks any codepath that imports
+ * the module before `RUNTIME_CONFIG_APP_ID`/AgentCore env vars are set (e.g.
+ * OpenAPI spec generation, tests) - and, for AgentCore, construction belongs
+ * at container/app startup rather than import, since AgentCore hands each
+ * session its own container. The A2A protocol is unaffected: `with_session_id`
+ * only touches the agent factory lazily on first use, so its eager
+ * `__enter__()` was never actually eager in practice.
+ *
+ * How to write a migration:
+ * - https://nx.dev/docs/kb/migration-generators
+ * - What `nextSteps` means: https://nx.dev/docs/reference/devkit/MigrationReturnObject
+ *
+ * Guardrails:
+ * - Pattern-match before writing: every rewrite this migration makes to a file
+ *   is preceded by a read-only `matchGritQL` check of every pattern it will
+ *   need - so a diverged file is reported via `nextSteps` and left completely
+ *   untouched, rather than partially rewritten into a broken state.
+ * - Idempotent: re-running must be a no-op (each rewrite's own shape change
+ *   means its pattern no longer matches on a second pass).
+ * - Format what you write: finish with `formatFilesInSubtree`.
+ */ /** A read-only GritQL match against a python file (no rewrite). */ const pyMatch = (snippet)=>`language python\n\`${snippet}\``;
+/** A GritQL rewrite deleting the matched python snippet entirely. */ const pyDelete = (snippet)=>`${pyMatch(snippet)} => .`;
+/**
+ * A GritQL rewrite of one python snippet into another. Multi-line
+ * replacements go through `raw` so GritQL's own reformatting doesn't fight
+ * the exact shape being written (formatFilesInSubtree normalizes it after).
+ */ const pyRewrite = (from, to, where)=>{
+    const replacement = to.includes('\n') ? `raw\`${to}\`` : `\`${to}\``;
+    return `${pyMatch(from)} => ${replacement}${where ? ` where { ${where} }` : ''}`;
+};
+/** All checks must match before anything is written for that agent. */ const allMatch = async (tree, checks)=>{
+    for (const [filePath, pattern] of checks){
+        if (!await matchGritQL(tree, filePath, pattern)) return false;
+    }
+    return true;
+};
+const AGENT_CONNECTION_MODULE_PATTERN = (names)=>pyMatch(`from $mod import ${names}`);
+const STRANDS_HTTP_MARKER = '_agent_ctx = with_session_id(';
+const LANGCHAIN_HTTP_MARKER = '_graph = get_agent()';
+const STRANDS_AGUI_MARKER = 'create_strands_app';
+const LANGCHAIN_AGUI_MARKER = '_graph = get_agent()';
+// Shared by strands/http and langchain/http - only the lifespan body differs.
+const HTTP_INIT_APP_OLD = `app = FastAPI(
+    title="$name",
+    responses={500: {"model": InternalServerErrorDetails}},
+    generate_unique_id_function=lambda route: route.name,
+)`;
+// --- Strands HTTP -----------------------------------------------------------
+const STRANDS_HTTP_MAIN_CTX_OLD = `_agent_ctx = with_session_id(
+    get_agent,
+    name="$name",
+    description="A Strands Agent exposed via HTTP streaming.",
+)`;
+const STRANDS_HTTP_INIT_APP_NEW = `@asynccontextmanager
+async def lifespan(app: FastAPI):
+    with with_session_id(
+        get_agent,
+        name="$name",
+        description="A Strands Agent exposed via HTTP streaming.",
+    ) as agent:
+        app.state.agent = agent
+        yield
+
+
+app = FastAPI(
+    title="$name",
+    responses={500: {"model": InternalServerErrorDetails}},
+    generate_unique_id_function=lambda route: route.name,
+    lifespan=lifespan,
+)`;
+const migrateStrandsHttpAgent = async (tree, dir, nextSteps)=>{
+    const initPath = joinPathFragments(dir, 'init.py');
+    const mainPath = joinPathFragments(dir, 'main.py');
+    if (!tree.exists(initPath) || !tree.exists(mainPath)) return;
+    const mainContents = tree.read(mainPath, 'utf-8') ?? '';
+    if (!mainContents.includes(STRANDS_HTTP_MARKER)) return;
+    const mod = await captureGritQLVariable(tree, mainPath, AGENT_CONNECTION_MODULE_PATTERN('session_id_context, with_session_id'), 'mod');
+    const ready = !!mod && await allMatch(tree, [
+        [
+            mainPath,
+            pyMatch(STRANDS_HTTP_MAIN_CTX_OLD)
+        ],
+        [
+            mainPath,
+            pyMatch('_agent = _agent_ctx.__enter__()')
+        ],
+        [
+            mainPath,
+            pyMatch('from .agent import get_agent')
+        ],
+        [
+            mainPath,
+            pyMatch('_agent.stream_async($prompt)')
+        ],
+        [
+            initPath,
+            pyMatch(HTTP_INIT_APP_OLD)
+        ]
+    ]);
+    if (!ready) {
+        nextSteps.push(`${mainPath}: diverged from the generated shape - left untouched, along with ${initPath}. Manually move agent construction into an \`init.py\` \`lifespan\` handler storing the agent on \`app.state.agent\` (see the py#agent generator's strands/http template).`);
+        return;
+    }
+    await addPythonDestructuredImport(tree, initPath, [
+        'asynccontextmanager'
+    ], 'contextlib');
+    await addPythonDestructuredImport(tree, initPath, [
+        'get_agent'
+    ], '.agent');
+    await addPythonDestructuredImport(tree, initPath, [
+        'with_session_id'
+    ], mod);
+    await applyGritQL(tree, initPath, pyRewrite(HTTP_INIT_APP_OLD, STRANDS_HTTP_INIT_APP_NEW));
+    await applyGritQL(tree, mainPath, pyRewrite('from $mod import session_id_context, with_session_id', 'from $mod import session_id_context'));
+    await applyGritQL(tree, mainPath, pyDelete('from .agent import get_agent'));
+    await applyGritQL(tree, mainPath, pyDelete(STRANDS_HTTP_MAIN_CTX_OLD));
+    await applyGritQL(tree, mainPath, pyDelete('_agent = _agent_ctx.__enter__()'));
+    await applyGritQL(tree, mainPath, pyRewrite('_agent.stream_async($prompt)', 'app.state.agent.stream_async($prompt)'));
+};
+// --- LangChain HTTP ----------------------------------------------------------
+const LANGCHAIN_HTTP_INIT_APP_NEW = `@asynccontextmanager
+async def lifespan(app: FastAPI):
+    app.state.graph = get_agent()
+    yield
+
+
+app = FastAPI(
+    title="$name",
+    responses={500: {"model": InternalServerErrorDetails}},
+    generate_unique_id_function=lambda route: route.name,
+    lifespan=lifespan,
+)`;
+const migrateLangchainHttpAgent = async (tree, dir, nextSteps)=>{
+    const initPath = joinPathFragments(dir, 'init.py');
+    const mainPath = joinPathFragments(dir, 'main.py');
+    if (!tree.exists(initPath) || !tree.exists(mainPath)) return;
+    const mainContents = tree.read(mainPath, 'utf-8') ?? '';
+    if (!mainContents.includes(LANGCHAIN_HTTP_MARKER)) return;
+    const ready = await allMatch(tree, [
+        [
+            mainPath,
+            pyMatch('_graph = get_agent()')
+        ],
+        [
+            mainPath,
+            pyMatch('from .agent import get_agent')
+        ],
+        [
+            mainPath,
+            pyMatch('_graph.astream($args)')
+        ],
+        [
+            initPath,
+            pyMatch(HTTP_INIT_APP_OLD)
+        ]
+    ]);
+    if (!ready) {
+        nextSteps.push(`${mainPath}: diverged from the generated shape - left untouched, along with ${initPath}. Manually wrap \`get_agent()\` in an \`init.py\` \`lifespan\` handler storing the graph on \`app.state.graph\` (see the py#agent generator's langchain/http template).`);
+        return;
+    }
+    await addPythonDestructuredImport(tree, initPath, [
+        'asynccontextmanager'
+    ], 'contextlib');
+    await addPythonDestructuredImport(tree, initPath, [
+        'get_agent'
+    ], '.agent');
+    await applyGritQL(tree, initPath, pyRewrite(HTTP_INIT_APP_OLD, LANGCHAIN_HTTP_INIT_APP_NEW));
+    await applyGritQL(tree, mainPath, pyDelete('from .agent import get_agent'));
+    await applyGritQL(tree, mainPath, pyDelete('_graph = get_agent()'));
+    await applyGritQL(tree, mainPath, pyRewrite('_graph.astream($args)', 'app.state.graph.astream($args)'));
+};
+// --- LangChain AG-UI ---------------------------------------------------------
+const LANGCHAIN_AGUI_AGENT_OLD = `agui_agent = LangGraphAgent(
+    name="$name",
+    graph=_graph,
+    description="A LangChain/LangGraph Agent exposed via the AG-UI protocol.",
+)`;
+const LANGCHAIN_AGUI_AGENT_NEW = `@asynccontextmanager
+async def lifespan(app: FastAPI):
+    graph = get_agent()
+    app.state.agui_agent = LangGraphAgent(
+        name="$name",
+        graph=graph,
+        description="A LangChain/LangGraph Agent exposed via the AG-UI protocol.",
+    )
+    yield`;
+const migrateLangchainAgUiAgent = async (tree, dir, nextSteps)=>{
+    const mainPath = joinPathFragments(dir, 'main.py');
+    if (!tree.exists(mainPath)) return;
+    const mainContents = tree.read(mainPath, 'utf-8') ?? '';
+    if (!mainContents.includes(LANGCHAIN_AGUI_MARKER)) return;
+    const ready = await allMatch(tree, [
+        [
+            mainPath,
+            pyMatch('_graph = get_agent()')
+        ],
+        [
+            mainPath,
+            pyMatch(LANGCHAIN_AGUI_AGENT_OLD)
+        ],
+        [
+            mainPath,
+            pyMatch('agui_agent.run($input)')
+        ],
+        [
+            mainPath,
+            pyMatch('app = FastAPI(title="$name")')
+        ]
+    ]);
+    if (!ready) {
+        nextSteps.push(`${mainPath}: diverged from the generated shape - left untouched. Manually wrap graph + \`LangGraphAgent\` construction in a \`lifespan\` handler storing the wrapper on \`app.state.agui_agent\` (see the py#agent generator's langchain/ag-ui template).`);
+        return;
+    }
+    await addPythonDestructuredImport(tree, mainPath, [
+        'asynccontextmanager'
+    ], 'contextlib');
+    await applyGritQL(tree, mainPath, pyDelete('_graph = get_agent()'));
+    await applyGritQL(tree, mainPath, pyRewrite(LANGCHAIN_AGUI_AGENT_OLD, LANGCHAIN_AGUI_AGENT_NEW));
+    await applyGritQL(tree, mainPath, pyRewrite('agui_agent.run($input)', 'request.app.state.agui_agent.run($input)'));
+    await applyGritQL(tree, mainPath, pyRewrite('app = FastAPI(title="$name")', 'app = FastAPI(title="$name", lifespan=lifespan)'));
+};
+// --- Strands AG-UI -----------------------------------------------------------
+// The biggest of the four: `ag_ui_strands.create_strands_app` is dropped
+// entirely for an inlined FastAPI app (matching upstream `ag_ui_strands`,
+// plus a Content-Type-independent body-parsing fix and an explicit session
+// re-bind `create_strands_app` was missing), so most of the file is new.
+const STRANDS_AGUI_IMPORT_OLD = 'from ag_ui_strands import StrandsAgent, create_strands_app';
+const STRANDS_AGUI_AGENT_OLD = `agui_agent = StrandsAgent(
+    agent=_agent,
+    name="$name",
+    description="A Strands Agent exposed via the AG-UI protocol.",
+)`;
+const STRANDS_AGUI_AGENT_NEW = `@asynccontextmanager
+async def lifespan(app: FastAPI):
+    with get_agent() as agent:
+        app.state.agui_agent = StrandsAgent(
+            agent=agent,
+            name="$name",
+            description="A Strands Agent exposed via the AG-UI protocol.",
+        )
+        yield`;
+const STRANDS_AGUI_APP_OLD = 'app = create_strands_app(agui_agent, path="/invocations")';
+// `$name` isn't bound within this match (unlike STRANDS_AGUI_AGENT_OLD above),
+// so the title is built from a name captured separately rather than reused as
+// a metavariable - GritQL leaves a rewrite whose replacement references an
+// unbound metavariable unapplied.
+const strandsAguiAppNew = (name)=>`app = FastAPI(title="AWS Strands - ${name}", lifespan=lifespan)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)`;
+const STRANDS_AGUI_MIDDLEWARE_OLD = 'app.add_middleware(_SessionIdMiddleware)';
+const STRANDS_AGUI_ROUTES_NEW = `app.add_middleware(_SessionIdMiddleware)
+
+
+@app.post("/invocations")
+async def invocations(request: Request):
+    # Validate the body manually since AgentCore may omit Content-Type.
+    encoder = EventEncoder(accept=request.headers.get("accept") or "")
+    raw = await request.body()
+    try:
+        input_data = RunAgentInput.model_validate_json(raw)
+    except Exception as exc:
+        message = f"Invalid RunAgentInput: {str(exc)[:200]}"
+
+        async def _bad():
+            yield encoder.encode(RunErrorEvent(type=EventType.RUN_ERROR, message=message, code="BAD_REQUEST"))
+
+        return StreamingResponse(_bad(), media_type=encoder.get_content_type())
+
+    session_id = request.headers.get(SESSION_ID_HEADER) or get_current_session_id()
+
+    async def event_generator():
+        # Re-bind the session: the streaming body runs outside the middleware.
+        with session_id_context(session_id or str(uuid.uuid4())):
+            async for event in request.app.state.agui_agent.run(input_data):
+                try:
+                    yield encoder.encode(event)
+                except Exception as e:
+                    error_event = RunErrorEvent(
+                        type=EventType.RUN_ERROR,
+                        message=f"Encoding error: {e}",
+                        code="ENCODING_ERROR",
+                    )
+                    yield encoder.encode(error_event)
+                    break
+
+    return StreamingResponse(event_generator(), media_type=encoder.get_content_type())
+
+
+@app.get("/ping")
+async def ping():
+    return {"status": "healthy"}`;
+const STRANDS_AGUI_COMMENTS_OLD = [
+    '# Create AG-UI agent wrapper',
+    '# Create FastAPI app with AG-UI endpoint and health check'
+];
+const migrateStrandsAgUiAgent = async (tree, dir, nextSteps)=>{
+    const mainPath = joinPathFragments(dir, 'main.py');
+    if (!tree.exists(mainPath)) return;
+    const mainContents = tree.read(mainPath, 'utf-8') ?? '';
+    if (!mainContents.includes(STRANDS_AGUI_MARKER)) return;
+    const mod = await captureGritQLVariable(tree, mainPath, AGENT_CONNECTION_MODULE_PATTERN('session_id_context'), 'mod');
+    const agentClassName = await captureGritQLVariable(tree, mainPath, pyMatch(STRANDS_AGUI_AGENT_OLD), 'name');
+    const ready = !!mod && !!agentClassName && await allMatch(tree, [
+        [
+            mainPath,
+            pyMatch(STRANDS_AGUI_IMPORT_OLD)
+        ],
+        [
+            mainPath,
+            pyMatch('_agent_ctx = get_agent()')
+        ],
+        [
+            mainPath,
+            pyMatch('_agent = _agent_ctx.__enter__()')
+        ],
+        [
+            mainPath,
+            pyMatch(STRANDS_AGUI_AGENT_OLD)
+        ],
+        [
+            mainPath,
+            pyMatch(STRANDS_AGUI_APP_OLD)
+        ],
+        [
+            mainPath,
+            pyMatch(STRANDS_AGUI_MIDDLEWARE_OLD)
+        ]
+    ]);
+    if (!ready) {
+        nextSteps.push(`${mainPath}: diverged from the generated shape - left untouched. Manually rebuild this file without \`create_strands_app\`: a \`lifespan\` handler storing the wrapper on \`app.state.agui_agent\`, and inlined \`/invocations\`/\`/ping\` routes with Content-Type-independent body parsing (see the py#agent generator's strands/ag-ui template).`);
+        return;
+    }
+    await addPythonDestructuredImport(tree, mainPath, [
+        'asynccontextmanager'
+    ], 'contextlib');
+    await addPythonDestructuredImport(tree, mainPath, [
+        'EventType',
+        'RunAgentInput',
+        'RunErrorEvent'
+    ], 'ag_ui.core');
+    await addPythonDestructuredImport(tree, mainPath, [
+        'EventEncoder'
+    ], 'ag_ui.encoder');
+    await addPythonDestructuredImport(tree, mainPath, [
+        'FastAPI'
+    ], 'fastapi');
+    await addPythonDestructuredImport(tree, mainPath, [
+        'CORSMiddleware'
+    ], 'fastapi.middleware.cors');
+    await addPythonDestructuredImport(tree, mainPath, [
+        'StreamingResponse'
+    ], 'fastapi.responses');
+    await addPythonDestructuredImport(tree, mainPath, [
+        'get_current_session_id'
+    ], mod);
+    await applyGritQL(tree, mainPath, pyRewrite(STRANDS_AGUI_IMPORT_OLD, 'from ag_ui_strands import StrandsAgent'));
+    await applyGritQL(tree, mainPath, pyDelete('_agent_ctx = get_agent()'));
+    await applyGritQL(tree, mainPath, pyDelete('_agent = _agent_ctx.__enter__()'));
+    await applyGritQL(tree, mainPath, pyRewrite(STRANDS_AGUI_AGENT_OLD, STRANDS_AGUI_AGENT_NEW));
+    for (const comment of STRANDS_AGUI_COMMENTS_OLD){
+        await applyGritQL(tree, mainPath, pyDelete(comment));
+    }
+    await applyGritQL(tree, mainPath, pyRewrite(STRANDS_AGUI_APP_OLD, strandsAguiAppNew(agentClassName)));
+    await applyGritQL(tree, mainPath, pyRewrite(STRANDS_AGUI_MIDDLEWARE_OLD, STRANDS_AGUI_ROUTES_NEW));
+};
+/** This agent's ComponentMetadata entries. */ const findAgentComponents = (components)=>(components ?? []).filter((component)=>component.generator === PY_AGENT_GENERATOR_INFO.id);
+export default async function migration(tree) {
+    const nextSteps = [];
+    for (const project of getProjects(tree).values()){
+        const components = findAgentComponents(project.metadata?.components);
+        for (const component of components){
+            if (!component.path) continue;
+            const dir = joinPathFragments(project.root, component.path);
+            const framework = component.framework ?? 'strands';
+            if (component.protocol === 'http') {
+                if (framework === 'langchain') {
+                    await migrateLangchainHttpAgent(tree, dir, nextSteps);
+                } else {
+                    await migrateStrandsHttpAgent(tree, dir, nextSteps);
+                }
+            } else if (component.protocol === 'ag-ui') {
+                if (framework === 'langchain') {
+                    await migrateLangchainAgUiAgent(tree, dir, nextSteps);
+                } else {
+                    await migrateStrandsAgUiAgent(tree, dir, nextSteps);
+                }
+            }
+        }
+    }
+    await formatFilesInSubtree(tree);
+    return {
+        nextSteps
+    };
+}
+
+//# sourceMappingURL=migration.js.map