@aws/nx-plugin 1.0.0-rc.6 → 1.0.0-rc.61

package/src/migrations/latest/gateway-agent-targets/migration.js

@@ -0,0 +1,217 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { applyGritQL, GRIT_INSERT_PLACEHOLDER, insertViaGritQL, matchGritQL } from "../../../utils/ast.js";
+import { formatFilesInSubtree } from "../../../utils/format.js";
+import { PACKAGES_DIR, SHARED_CONSTRUCTS_DIR } from "../../../utils/shared-constructs-constants.js";
+/**
+ * Bring existing workspaces up to the generators' current gateway-target
+ * support, so agents can be attached to an http-protocol AgentCore Gateway:
+ *
+ * - The vended `AgentCoreGateway` core construct gains the `protocol` prop
+ *   (http gateways have no protocol type, which AgentCore Runtime targets
+ *   require) and the `addAgent` / `addAgentTarget` methods.
+ * - Vended agent constructs gain the `agentName` member `addAgent` reads as
+ *   the default gateway target name.
+ *
+ * Both files are generated with `KeepExisting`, so without this an upgraded
+ * workspace pairs new app-level constructs with stale core ones.
+ */ const GATEWAY_CONSTRUCT_FILE = `${PACKAGES_DIR}/${SHARED_CONSTRUCTS_DIR}/src/core/agentcore-gateway/agentcore-gateway.ts`;
+const AGENTS_DIR = `${PACKAGES_DIR}/${SHARED_CONSTRUCTS_DIR}/src/app/agents`;
+const PROTOCOL_PROP = `/**
+   * The gateway's protocol. An \`mcp\` gateway aggregates MCP server targets
+   * into a single MCP endpoint. An \`http\` gateway has no protocol type and
+   * proxies requests to AgentCore Runtime targets via path-based routing
+   * (\`/<targetName>/invocations\`) — the target type AgentCore only allows on
+   * gateways without a protocol type.
+   *
+   * @default 'mcp'
+   */
+  readonly protocol?: 'mcp' | 'http';`;
+const PROTOCOL_CONSTRUCTOR_STATEMENTS = `this.protocol = props?.protocol ?? 'mcp';
+`;
+const PROTOCOL_TYPE_REMOVAL = `
+    if (this.protocol === 'http') {
+      // AgentCore Runtime targets require a gateway without a protocol type,
+      // which the Gateway L2 cannot express — it always renders MCP — so
+      // remove the protocol from the underlying CloudFormation resource.
+      const cfnGateway = this.gateway.node.defaultChild as agentcore.CfnGateway;
+      cfnGateway.addPropertyDeletionOverride('ProtocolType');
+      cfnGateway.addPropertyDeletionOverride('ProtocolConfiguration');
+    }`;
+const AGENT_TARGET_METHODS = `
+  /**
+   * Add an agent runtime construct as a target of this Gateway. Requires the
+   * \`http\` protocol — the gateway proxies requests for the agent under
+   * \`<gatewayUrl>/<targetName>/invocations\`, without protocol translation.
+   *
+   * The target name defaults to the agent construct's \`agentName\` (its
+   * project's class name in kebab-case, e.g. \`MyAgent\` -> \`my-agent\`). It
+   * forms the target's invocation path, so renaming it later is a breaking
+   * change for consumers.
+   */
+  public addAgent(
+    agent: Construct & {
+      readonly agentCoreRuntime: agentcore.Runtime;
+      readonly agentName: string;
+    },
+    props?: {
+      gatewayTargetName?: string;
+    },
+  ): agentcore.CfnGatewayTarget {
+    return this.addAgentTarget({
+      gatewayTargetName: props?.gatewayTargetName ?? agent.agentName,
+      agentRuntimeArn: agent.agentCoreRuntime.agentRuntimeArn,
+    });
+  }
+
+  /**
+   * Register an agent runtime ARN as a Gateway target. Prefer
+   * {@link addAgent} when the construct is in scope.
+   */
+  public addAgentTarget(props: {
+    gatewayTargetName: string;
+    agentRuntimeArn: string;
+  }): agentcore.CfnGatewayTarget {
+    if (this.protocol !== 'http') {
+      throw new Error(
+        \`Agent runtime targets require an http-protocol gateway, but this gateway uses '\${this.protocol}'.\`,
+      );
+    }
+
+    // The construct id is derived from the target name so the two change
+    // together — target names are unique per gateway, and replacing a target
+    // under an unchanged name fails with AlreadyExists.
+    const target = new agentcore.CfnGatewayTarget(
+      this,
+      \`Target-\${props.gatewayTargetName}\`,
+      {
+        gatewayIdentifier: this.gateway.gatewayId,
+        name: props.gatewayTargetName,
+        targetConfiguration: {
+          http: {
+            agentcoreRuntime: {
+              arn: props.agentRuntimeArn,
+              qualifier: 'DEFAULT',
+            },
+          },
+        },
+        // The bare gateway IAM role credential: runtime targets reject the
+        // iamCredentialProvider detail MCP targets carry.
+        credentialProviderConfigurations: [
+          {
+            credentialProviderType: 'GATEWAY_IAM_ROLE',
+          },
+        ],
+      },
+    );
+
+    // Grant the gateway role invoke access to the target runtime before the
+    // target is created — AgentCore validates access to the runtime during
+    // target creation.
+    const grant = this.gateway.role.addToPrincipalPolicy(
+      new iam.PolicyStatement({
+        actions: [
+          'bedrock-agentcore:InvokeAgentRuntime',
+          'bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream',
+          // A2A targets additionally serve their agent card via the gateway.
+          'bedrock-agentcore:GetAgentCard',
+        ],
+        resources: [props.agentRuntimeArn, \`\${props.agentRuntimeArn}/*\`],
+      }),
+    );
+    if (grant.policyDependable) {
+      target.node.addDependency(grant.policyDependable);
+    }
+
+    return target;
+  }`;
+/**
+ * Add the `protocol` prop, its constructor handling and the agent-target
+ * methods to the vended `AgentCoreGateway` core construct.
+ */ const migrateGatewayConstruct = async (tree, nextSteps)=>{
+    if (!tree.exists(GATEWAY_CONSTRUCT_FILE)) {
+        // No vended gateway construct in this workspace - nothing to migrate.
+        return;
+    }
+    if ((tree.read(GATEWAY_CONSTRUCT_FILE, 'utf-8') ?? '').includes('addAgentTarget')) {
+        // Already migrated.
+        return;
+    }
+    const divergedMessage = `${GATEWAY_CONSTRUCT_FILE}: the AgentCoreGateway construct has diverged from the generated shape - left untouched. Re-run the agentcore-gateway generator in a fresh workspace to see the current construct, which supports agent runtime targets via a 'protocol' prop and addAgent()/addAgentTarget() methods.`;
+    // Anchored on the shapes every vended version of the construct carries: the
+    // props interface, the class field the protocol field is inserted after,
+    // and the Gateway creation in the constructor.
+    const hasVendedShape = await matchGritQL(tree, GATEWAY_CONSTRUCT_FILE, '`export interface AgentCoreGatewayProps { $_ }`') && await matchGritQL(tree, GATEWAY_CONSTRUCT_FILE, '`private readonly targetRuntimeArns: string[] = []`') && await matchGritQL(tree, GATEWAY_CONSTRUCT_FILE, "`this.gateway = new agentcore.Gateway(this, 'Gateway', $_)`");
+    if (!hasVendedShape) {
+        nextSteps.push(divergedMessage);
+        return;
+    }
+    // 1. The protocol prop on AgentCoreGatewayProps. The placeholder keeps the
+    //    prop's doc comment (with its backticks) out of the GritQL pattern.
+    await insertViaGritQL(tree, GATEWAY_CONSTRUCT_FILE, `\`export interface AgentCoreGatewayProps { $members }\` where {
+  $members <: not contains \`protocol\`
+} => \`export interface AgentCoreGatewayProps { $members
+  ${GRIT_INSERT_PLACEHOLDER}
+}\``, PROTOCOL_PROP);
+    // 2. The protocol class field. Matched without the trailing semicolon —
+    //    GritQL parses the snippet standalone, where the semicolon is not part
+    //    of the field's AST node.
+    await applyGritQL(tree, GATEWAY_CONSTRUCT_FILE, `\`private readonly targetRuntimeArns: string[] = []\` as $field where {
+  $program <: not contains \`private readonly protocol\`
+} => \`$field;
+  private readonly protocol: 'mcp' | 'http'\``);
+    // 3. Assign the field and remove the protocol type for http gateways.
+    await insertViaGritQL(tree, GATEWAY_CONSTRUCT_FILE, `\`this.gateway = new agentcore.Gateway($args);\` as $stmt where {
+  $program <: not contains \`this.protocol = props\`
+} => \`${GRIT_INSERT_PLACEHOLDER}
+    $stmt\``, PROTOCOL_CONSTRUCTOR_STATEMENTS);
+    await insertViaGritQL(tree, GATEWAY_CONSTRUCT_FILE, `\`this.gateway = new agentcore.Gateway($args);\` as $stmt where {
+  $program <: not contains \`addPropertyDeletionOverride\`
+} => \`$stmt
+${GRIT_INSERT_PLACEHOLDER}\``, PROTOCOL_TYPE_REMOVAL);
+    // 4. The agent-target methods, inserted after addGatewayTarget (present in
+    //    every vended version that also has the readiness probe field).
+    const addedMethods = await insertViaGritQL(tree, GATEWAY_CONSTRUCT_FILE, `\`public addGatewayTarget($params): agentcore.CfnGatewayTarget { $body }\` as $method where {
+  $program <: not contains \`addAgentTarget\`
+} => \`$method
+${GRIT_INSERT_PLACEHOLDER}\``, AGENT_TARGET_METHODS);
+    if (!addedMethods) {
+        nextSteps.push(divergedMessage);
+        return;
+    }
+};
+/**
+ * Add the `agentName` member to each vended agent construct, which
+ * `AgentCoreGateway.addAgent` reads as the default gateway target name.
+ */ const migrateAgentConstructs = async (tree, nextSteps)=>{
+    if (!tree.exists(AGENTS_DIR)) {
+        return;
+    }
+    for (const dir of tree.children(AGENTS_DIR)){
+        const constructFile = `${AGENTS_DIR}/${dir}/${dir}.ts`;
+        if (!tree.exists(constructFile)) {
+            continue;
+        }
+        if ((tree.read(constructFile, 'utf-8') ?? '').includes('agentName')) {
+            continue;
+        }
+        const added = await insertViaGritQL(tree, constructFile, `\`public readonly agentCoreRuntime: Runtime\` as $field => \`$field;
+  ${GRIT_INSERT_PLACEHOLDER}\``, `/** Default Gateway target name for this agent. */
+  public readonly agentName = '${dir}'`);
+        if (!added) {
+            nextSteps.push(`${constructFile}: the agent construct has diverged from the generated shape - left untouched. To attach this agent to a gateway with addAgent(), add a \`public readonly agentName = '${dir}';\` member (or use addAgentTarget() with an explicit target name).`);
+        }
+    }
+};
+export default async function migration(tree) {
+    const nextSteps = [];
+    await migrateGatewayConstruct(tree, nextSteps);
+    await migrateAgentConstructs(tree, nextSteps);
+    await formatFilesInSubtree(tree);
+    return {
+        nextSteps
+    };
+}
+
+//# sourceMappingURL=migration.js.map

package/src/migrations/latest/gateway-agent-targets/migration.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../packages/nx-plugin/src/migrations/latest/gateway-agent-targets/migration.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport type { MigrationReturnObject, Tree } from '@nx/devkit';\nimport {\n  applyGritQL,\n  GRIT_INSERT_PLACEHOLDER,\n  insertViaGritQL,\n  matchGritQL,\n} from '../../../utils/ast';\nimport { formatFilesInSubtree } from '../../../utils/format';\nimport {\n  PACKAGES_DIR,\n  SHARED_CONSTRUCTS_DIR,\n} from '../../../utils/shared-constructs-constants';\n\n/**\n * Bring existing workspaces up to the generators' current gateway-target\n * support, so agents can be attached to an http-protocol AgentCore Gateway:\n *\n * - The vended `AgentCoreGateway` core construct gains the `protocol` prop\n *   (http gateways have no protocol type, which AgentCore Runtime targets\n *   require) and the `addAgent` / `addAgentTarget` methods.\n * - Vended agent constructs gain the `agentName` member `addAgent` reads as\n *   the default gateway target name.\n *\n * Both files are generated with `KeepExisting`, so without this an upgraded\n * workspace pairs new app-level constructs with stale core ones.\n */\n\nconst GATEWAY_CONSTRUCT_FILE = `${PACKAGES_DIR}/${SHARED_CONSTRUCTS_DIR}/src/core/agentcore-gateway/agentcore-gateway.ts`;\n\nconst AGENTS_DIR = `${PACKAGES_DIR}/${SHARED_CONSTRUCTS_DIR}/src/app/agents`;\n\nconst PROTOCOL_PROP = `/**\n   * The gateway's protocol. An \\`mcp\\` gateway aggregates MCP server targets\n   * into a single MCP endpoint. An \\`http\\` gateway has no protocol type and\n   * proxies requests to AgentCore Runtime targets via path-based routing\n   * (\\`/<targetName>/invocations\\`) — the target type AgentCore only allows on\n   * gateways without a protocol type.\n   *\n   * @default 'mcp'\n   */\n  readonly protocol?: 'mcp' | 'http';`;\n\nconst PROTOCOL_CONSTRUCTOR_STATEMENTS = `this.protocol = props?.protocol ?? 'mcp';\n`;\n\nconst PROTOCOL_TYPE_REMOVAL = `\n    if (this.protocol === 'http') {\n      // AgentCore Runtime targets require a gateway without a protocol type,\n      // which the Gateway L2 cannot express — it always renders MCP — so\n      // remove the protocol from the underlying CloudFormation resource.\n      const cfnGateway = this.gateway.node.defaultChild as agentcore.CfnGateway;\n      cfnGateway.addPropertyDeletionOverride('ProtocolType');\n      cfnGateway.addPropertyDeletionOverride('ProtocolConfiguration');\n    }`;\n\nconst AGENT_TARGET_METHODS = `\n  /**\n   * Add an agent runtime construct as a target of this Gateway. Requires the\n   * \\`http\\` protocol — the gateway proxies requests for the agent under\n   * \\`<gatewayUrl>/<targetName>/invocations\\`, without protocol translation.\n   *\n   * The target name defaults to the agent construct's \\`agentName\\` (its\n   * project's class name in kebab-case, e.g. \\`MyAgent\\` -> \\`my-agent\\`). It\n   * forms the target's invocation path, so renaming it later is a breaking\n   * change for consumers.\n   */\n  public addAgent(\n    agent: Construct & {\n      readonly agentCoreRuntime: agentcore.Runtime;\n      readonly agentName: string;\n    },\n    props?: {\n      gatewayTargetName?: string;\n    },\n  ): agentcore.CfnGatewayTarget {\n    return this.addAgentTarget({\n      gatewayTargetName: props?.gatewayTargetName ?? agent.agentName,\n      agentRuntimeArn: agent.agentCoreRuntime.agentRuntimeArn,\n    });\n  }\n\n  /**\n   * Register an agent runtime ARN as a Gateway target. Prefer\n   * {@link addAgent} when the construct is in scope.\n   */\n  public addAgentTarget(props: {\n    gatewayTargetName: string;\n    agentRuntimeArn: string;\n  }): agentcore.CfnGatewayTarget {\n    if (this.protocol !== 'http') {\n      throw new Error(\n        \\`Agent runtime targets require an http-protocol gateway, but this gateway uses '\\${this.protocol}'.\\`,\n      );\n    }\n\n    // The construct id is derived from the target name so the two change\n    // together — target names are unique per gateway, and replacing a target\n    // under an unchanged name fails with AlreadyExists.\n    const target = new agentcore.CfnGatewayTarget(\n      this,\n      \\`Target-\\${props.gatewayTargetName}\\`,\n      {\n        gatewayIdentifier: this.gateway.gatewayId,\n        name: props.gatewayTargetName,\n        targetConfiguration: {\n          http: {\n            agentcoreRuntime: {\n              arn: props.agentRuntimeArn,\n              qualifier: 'DEFAULT',\n            },\n          },\n        },\n        // The bare gateway IAM role credential: runtime targets reject the\n        // iamCredentialProvider detail MCP targets carry.\n        credentialProviderConfigurations: [\n          {\n            credentialProviderType: 'GATEWAY_IAM_ROLE',\n          },\n        ],\n      },\n    );\n\n    // Grant the gateway role invoke access to the target runtime before the\n    // target is created — AgentCore validates access to the runtime during\n    // target creation.\n    const grant = this.gateway.role.addToPrincipalPolicy(\n      new iam.PolicyStatement({\n        actions: [\n          'bedrock-agentcore:InvokeAgentRuntime',\n          'bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream',\n          // A2A targets additionally serve their agent card via the gateway.\n          'bedrock-agentcore:GetAgentCard',\n        ],\n        resources: [props.agentRuntimeArn, \\`\\${props.agentRuntimeArn}/*\\`],\n      }),\n    );\n    if (grant.policyDependable) {\n      target.node.addDependency(grant.policyDependable);\n    }\n\n    return target;\n  }`;\n\n/**\n * Add the `protocol` prop, its constructor handling and the agent-target\n * methods to the vended `AgentCoreGateway` core construct.\n */\nconst migrateGatewayConstruct = async (\n  tree: Tree,\n  nextSteps: string[],\n): Promise<void> => {\n  if (!tree.exists(GATEWAY_CONSTRUCT_FILE)) {\n    // No vended gateway construct in this workspace - nothing to migrate.\n    return;\n  }\n\n  if (\n    (tree.read(GATEWAY_CONSTRUCT_FILE, 'utf-8') ?? '').includes(\n      'addAgentTarget',\n    )\n  ) {\n    // Already migrated.\n    return;\n  }\n\n  const divergedMessage = `${GATEWAY_CONSTRUCT_FILE}: the AgentCoreGateway construct has diverged from the generated shape - left untouched. Re-run the agentcore-gateway generator in a fresh workspace to see the current construct, which supports agent runtime targets via a 'protocol' prop and addAgent()/addAgentTarget() methods.`;\n\n  // Anchored on the shapes every vended version of the construct carries: the\n  // props interface, the class field the protocol field is inserted after,\n  // and the Gateway creation in the constructor.\n  const hasVendedShape =\n    (await matchGritQL(\n      tree,\n      GATEWAY_CONSTRUCT_FILE,\n      '`export interface AgentCoreGatewayProps { $_ }`',\n    )) &&\n    (await matchGritQL(\n      tree,\n      GATEWAY_CONSTRUCT_FILE,\n      '`private readonly targetRuntimeArns: string[] = []`',\n    )) &&\n    (await matchGritQL(\n      tree,\n      GATEWAY_CONSTRUCT_FILE,\n      \"`this.gateway = new agentcore.Gateway(this, 'Gateway', $_)`\",\n    ));\n\n  if (!hasVendedShape) {\n    nextSteps.push(divergedMessage);\n    return;\n  }\n\n  // 1. The protocol prop on AgentCoreGatewayProps. The placeholder keeps the\n  //    prop's doc comment (with its backticks) out of the GritQL pattern.\n  await insertViaGritQL(\n    tree,\n    GATEWAY_CONSTRUCT_FILE,\n    `\\`export interface AgentCoreGatewayProps { $members }\\` where {\n  $members <: not contains \\`protocol\\`\n} => \\`export interface AgentCoreGatewayProps { $members\n  ${GRIT_INSERT_PLACEHOLDER}\n}\\``,\n    PROTOCOL_PROP,\n  );\n\n  // 2. The protocol class field. Matched without the trailing semicolon —\n  //    GritQL parses the snippet standalone, where the semicolon is not part\n  //    of the field's AST node.\n  await applyGritQL(\n    tree,\n    GATEWAY_CONSTRUCT_FILE,\n    `\\`private readonly targetRuntimeArns: string[] = []\\` as $field where {\n  $program <: not contains \\`private readonly protocol\\`\n} => \\`$field;\n  private readonly protocol: 'mcp' | 'http'\\``,\n  );\n\n  // 3. Assign the field and remove the protocol type for http gateways.\n  await insertViaGritQL(\n    tree,\n    GATEWAY_CONSTRUCT_FILE,\n    `\\`this.gateway = new agentcore.Gateway($args);\\` as $stmt where {\n  $program <: not contains \\`this.protocol = props\\`\n} => \\`${GRIT_INSERT_PLACEHOLDER}\n    $stmt\\``,\n    PROTOCOL_CONSTRUCTOR_STATEMENTS,\n  );\n  await insertViaGritQL(\n    tree,\n    GATEWAY_CONSTRUCT_FILE,\n    `\\`this.gateway = new agentcore.Gateway($args);\\` as $stmt where {\n  $program <: not contains \\`addPropertyDeletionOverride\\`\n} => \\`$stmt\n${GRIT_INSERT_PLACEHOLDER}\\``,\n    PROTOCOL_TYPE_REMOVAL,\n  );\n\n  // 4. The agent-target methods, inserted after addGatewayTarget (present in\n  //    every vended version that also has the readiness probe field).\n  const addedMethods = await insertViaGritQL(\n    tree,\n    GATEWAY_CONSTRUCT_FILE,\n    `\\`public addGatewayTarget($params): agentcore.CfnGatewayTarget { $body }\\` as $method where {\n  $program <: not contains \\`addAgentTarget\\`\n} => \\`$method\n${GRIT_INSERT_PLACEHOLDER}\\``,\n    AGENT_TARGET_METHODS,\n  );\n\n  if (!addedMethods) {\n    nextSteps.push(divergedMessage);\n    return;\n  }\n};\n\n/**\n * Add the `agentName` member to each vended agent construct, which\n * `AgentCoreGateway.addAgent` reads as the default gateway target name.\n */\nconst migrateAgentConstructs = async (\n  tree: Tree,\n  nextSteps: string[],\n): Promise<void> => {\n  if (!tree.exists(AGENTS_DIR)) {\n    return;\n  }\n  for (const dir of tree.children(AGENTS_DIR)) {\n    const constructFile = `${AGENTS_DIR}/${dir}/${dir}.ts`;\n    if (!tree.exists(constructFile)) {\n      continue;\n    }\n    if ((tree.read(constructFile, 'utf-8') ?? '').includes('agentName')) {\n      // Already migrated (or user-added).\n      continue;\n    }\n    const added = await insertViaGritQL(\n      tree,\n      constructFile,\n      `\\`public readonly agentCoreRuntime: Runtime\\` as $field => \\`$field;\n  ${GRIT_INSERT_PLACEHOLDER}\\``,\n      `/** Default Gateway target name for this agent. */\n  public readonly agentName = '${dir}'`,\n    );\n    if (!added) {\n      nextSteps.push(\n        `${constructFile}: the agent construct has diverged from the generated shape - left untouched. To attach this agent to a gateway with addAgent(), add a \\`public readonly agentName = '${dir}';\\` member (or use addAgentTarget() with an explicit target name).`,\n      );\n    }\n  }\n};\n\nexport default async function migration(\n  tree: Tree,\n): Promise<MigrationReturnObject> {\n  const nextSteps: string[] = [];\n\n  await migrateGatewayConstruct(tree, nextSteps);\n  await migrateAgentConstructs(tree, nextSteps);\n\n  await formatFilesInSubtree(tree);\n\n  return { nextSteps };\n}\n"],"names":["applyGritQL","GRIT_INSERT_PLACEHOLDER","insertViaGritQL","matchGritQL","formatFilesInSubtree","PACKAGES_DIR","SHARED_CONSTRUCTS_DIR","GATEWAY_CONSTRUCT_FILE","AGENTS_DIR","PROTOCOL_PROP","PROTOCOL_CONSTRUCTOR_STATEMENTS","PROTOCOL_TYPE_REMOVAL","AGENT_TARGET_METHODS","migrateGatewayConstruct","tree","nextSteps","exists","read","includes","divergedMessage","hasVendedShape","push","addedMethods","migrateAgentConstructs","dir","children","constructFile","added","migration"],"mappings":"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"}

package/src/migrations/latest/gateway-cognito-passthrough/__snapshots__/migration.spec.ts.snap

@@ -0,0 +1,149 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`gateway-cognito-passthrough migration > adds auth=cognito and the Authorization allowlist to a Cognito agent 1`] = `
+"import {
+  Runtime,
+  RuntimeAuthorizerConfiguration,
+} from 'aws-cdk-lib/aws-bedrockagentcore';
+import { Construct } from 'constructs';
+
+export class MyCognitoAgent extends Construct {
+  public readonly agentCoreRuntime: Runtime;
+  /** Default Gateway target name for this agent. */
+  public readonly agentName = 'my-cognito-agent';
+  /** Inbound auth — a fronting Gateway uses this to pick its outbound credential. */
+  public readonly auth = 'cognito';
+
+  constructor(scope: Construct, id: string, props: MyCognitoAgentProps) {
+    super(scope, id);
+    const { identity } = props;
+    this.agentCoreRuntime = new Runtime(this, 'MyCognitoAgent', {
+      authorizerConfiguration: RuntimeAuthorizerConfiguration.usingCognito(
+        identity.userPool,
+        [identity.userPoolClient],
+      ),
+      // Receive the caller's Authorization header (validated by the authorizer).
+      requestHeaderConfiguration: {
+        allowlistedHeaders: ['Authorization'],
+      },
+    });
+  }
+}
+"
+`;
+
+exports[`gateway-cognito-passthrough migration > adds the request_header_configuration block to the terraform runtime 1`] = `
+"resource "aws_bedrockagentcore_agent_runtime" "agent_runtime" {
+  agent_runtime_name = "test"
+
+  dynamic "authorizer_configuration" {
+    for_each = var.authorizer_configuration != null && try(var.authorizer_configuration.custom_jwt_authorizer, null) != null ? [var.authorizer_configuration.custom_jwt_authorizer] : []
+    content {
+      custom_jwt_authorizer {
+        discovery_url    = authorizer_configuration.value.discovery_url
+        allowed_audience = authorizer_configuration.value.allowed_audience
+        allowed_clients  = authorizer_configuration.value.allowed_clients
+      }
+    }
+  }
+
+  # Receive the caller's Authorization header (validated by the JWT authorizer).
+  dynamic "request_header_configuration" {
+    for_each = var.authorizer_configuration != null && try(var.authorizer_configuration.custom_jwt_authorizer, null) != null ? [1] : []
+    content {
+      request_header_allowlist = ["Authorization"]
+    }
+  }
+
+  network_configuration {
+    network_mode = "PUBLIC"
+  }
+}
+"
+`;
+
+exports[`gateway-cognito-passthrough migration > makes the gateway pick the target credential from the agent auth 1`] = `
+"import * as agentcore from 'aws-cdk-lib/aws-bedrockagentcore';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import { Construct } from 'constructs';
+
+export class AgentCoreGateway extends Construct implements iam.IGrantable {
+  public addAgent(
+    agent: Construct & {
+      readonly agentCoreRuntime: agentcore.Runtime;
+      readonly agentName: string;
+      readonly auth?: 'iam' | 'cognito';
+    },
+    props?: {
+      gatewayTargetName?: string;
+    },
+  ): agentcore.CfnGatewayTarget {
+    return this.addAgentTarget({
+      gatewayTargetName: props?.gatewayTargetName ?? agent.agentName,
+      agentRuntimeArn: agent.agentCoreRuntime.agentRuntimeArn,
+      credentials: agent.auth === 'cognito' ? 'jwt-passthrough' : 'gateway-iam',
+    });
+  }
+
+  public addAgentTarget(props: {
+    gatewayTargetName: string;
+    agentRuntimeArn: string;
+    credentials?: 'gateway-iam' | 'jwt-passthrough';
+  }): agentcore.CfnGatewayTarget {
+    const target = new agentcore.CfnGatewayTarget(
+      this,
+      \`Target-\${props.gatewayTargetName}\`,
+      {
+        gatewayIdentifier: this.gateway.gatewayId,
+        name: props.gatewayTargetName,
+        targetConfiguration: {
+          http: {
+            agentcoreRuntime: {
+              arn: props.agentRuntimeArn,
+              qualifier: 'DEFAULT',
+            },
+          },
+        },
+        // The bare gateway IAM role credential: runtime targets reject the
+        // iamCredentialProvider detail MCP targets carry.
+        credentialProviderConfigurations: [
+          {
+            credentialProviderType:
+              props.credentials === 'jwt-passthrough'
+                ? 'JWT_PASSTHROUGH'
+                : 'GATEWAY_IAM_ROLE',
+          },
+        ],
+      },
+    );
+    return target;
+  }
+
+  public addMcpServerTarget(props: {
+    gatewayTargetName: string;
+    mcpServerRuntimeArn: string;
+  }): agentcore.CfnGatewayTarget {
+    const target = new agentcore.CfnGatewayTarget(
+      this,
+      \`Target-\${props.gatewayTargetName}\`,
+      {
+        gatewayIdentifier: this.gateway.gatewayId,
+        name: props.gatewayTargetName,
+        targetConfiguration: {
+          mcp: { openApiSchema: { inlinePayload: 'x' } },
+        },
+        credentialProviderConfigurations: [
+          {
+            credentialProviderType: 'GATEWAY_IAM_ROLE',
+            credentialProvider: {
+              iamCredentialProvider: { service: 'bedrock-agentcore' },
+            },
+          },
+        ],
+      },
+    );
+    return target;
+  }
+}
+"
+`;

package/src/migrations/latest/gateway-cognito-passthrough/metadata.json

@@ -0,0 +1,3 @@
+{
+  "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"
+}

package/src/migrations/latest/gateway-cognito-passthrough/migration.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { MigrationReturnObject, Tree } from '@nx/devkit';
+export default function migration(tree: Tree): Promise<MigrationReturnObject>;

package/src/migrations/latest/gateway-cognito-passthrough/migration.js

@@ -0,0 +1,195 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { applyGritQL, GRIT_INSERT_PLACEHOLDER, insertViaGritQL, matchGritQL } from "../../../utils/ast.js";
+import { formatFilesInSubtree } from "../../../utils/format.js";
+import { PACKAGES_DIR, SHARED_CONSTRUCTS_DIR, SHARED_TERRAFORM_DIR } from "../../../utils/shared-constructs-constants.js";
+/**
+ * Bring existing workspaces up to the generators' current gateway->agent
+ * support for Cognito agents, which forward the caller's JWT to the runtime:
+ *
+ * - The vended `AgentCoreGateway` construct's `addAgent`/`addAgentTarget` pick
+ *   the outbound credential from the agent's `auth`: a `cognito` agent uses
+ *   `JWT_PASSTHROUGH` (the caller's token reaches the runtime), an `iam` agent
+ *   the gateway role (`GATEWAY_IAM_ROLE`, the previous behaviour).
+ * - Vended agent constructs gain an `auth` member `addAgent` reads, and Cognito
+ *   agents allowlist the `Authorization` header (CDK + Terraform runtime) so the
+ *   runtime receives the forwarded token.
+ *
+ * These files are generated with `KeepExisting`, so without this an upgraded
+ * workspace pairs new app-level constructs with stale core ones. Diverged files
+ * are left untouched and reported via `nextSteps`.
+ */ const GATEWAY_CONSTRUCT_FILE = `${PACKAGES_DIR}/${SHARED_CONSTRUCTS_DIR}/src/core/agentcore-gateway/agentcore-gateway.ts`;
+const AGENTS_DIR = `${PACKAGES_DIR}/${SHARED_CONSTRUCTS_DIR}/src/app/agents`;
+const TF_RUNTIME_FILE = `${PACKAGES_DIR}/${SHARED_TERRAFORM_DIR}/src/core/agent-core/runtime.tf`;
+/**
+ * Teach the vended `AgentCoreGateway` construct to pick the target credential
+ * from the agent's `auth` (JWT passthrough for Cognito, gateway role for IAM).
+ */ const migrateGatewayConstruct = async (tree, nextSteps)=>{
+    if (!tree.exists(GATEWAY_CONSTRUCT_FILE)) {
+        return; // No vended gateway construct.
+    }
+    // Predates agent-target support (the gateway-agent-targets migration adds
+    // addAgentTarget first) — match the method, not a bare identifier.
+    if (!await matchGritQL(tree, GATEWAY_CONSTRUCT_FILE, '`addAgentTarget(props: { $_ }): agentcore.CfnGatewayTarget { $_ }`')) {
+        return;
+    }
+    // Already migrated: the credentials member is on addAgentTarget's props.
+    if (await matchGritQL(tree, GATEWAY_CONSTRUCT_FILE, "`credentials?: 'gateway-iam' | 'jwt-passthrough'`")) {
+        return;
+    }
+    const divergedMessage = `In ${GATEWAY_CONSTRUCT_FILE}: have addAgent read the agent's \`auth\` and pass \`credentials: 'jwt-passthrough'\` to addAgentTarget, so the target's credentialProviderType becomes 'JWT_PASSTHROUGH' for Cognito agents.`;
+    // GritQL patterns for each of the four edits. Verified against the tree
+    // up-front so the transform is all-or-nothing: a construct missing any
+    // anchor is left untouched with a single actionable next step, rather than
+    // half-migrated.
+    const authParamPattern = `\`readonly agentName: string\` as $sig where {
+  $program <: not contains \`readonly auth?\`
+} => \`$sig;
+      readonly auth?: 'iam' | 'cognito'\``;
+    const callPattern = `\`agentRuntimeArn: agent.agentCoreRuntime.agentRuntimeArn\` as $prop where {
+  $program <: not contains \`credentials:\`
+} => \`$prop,
+      credentials: agent.auth === 'cognito' ? 'jwt-passthrough' : 'gateway-iam'\``;
+    // The addAgentTarget props type: matched on its `agentRuntimeArn: string`
+    // member signature (without trailing semicolon), which the rewrite re-adds
+    // followed by the credentials member. The `: string` type distinguishes it
+    // from the `agentRuntimeArn:` value in the addAgent call.
+    const paramPattern = `\`agentRuntimeArn: string\` as $sig where {
+  $program <: not contains \`credentials?\`
+} => \`$sig;
+    credentials?: 'gateway-iam' | 'jwt-passthrough'\``;
+    // Scoped to the agent target's own CfnGatewayTarget (the one configured with
+    // an agentcoreRuntime), so the MCP server target's GATEWAY_IAM_ROLE — a
+    // sibling method with its own credential block — is left untouched.
+    const credentialPattern = `\`credentialProviderType: 'GATEWAY_IAM_ROLE'\` as $cred where {
+  $cred <: within \`new agentcore.CfnGatewayTarget($_, $_, $config)\`,
+  $config <: contains \`agentcoreRuntime\`
+} => \`credentialProviderType:
+              props.credentials === 'jwt-passthrough'
+                ? 'JWT_PASSTHROUGH'
+                : 'GATEWAY_IAM_ROLE'\``;
+    // Verify every anchor matches before mutating anything (matchGritQL is
+    // read-only), so a diverged construct is never left partially migrated.
+    for (const pattern of [
+        authParamPattern,
+        callPattern,
+        paramPattern,
+        credentialPattern
+    ]){
+        if (!await matchGritQL(tree, GATEWAY_CONSTRUCT_FILE, pattern)) {
+            nextSteps.push(divergedMessage);
+            return;
+        }
+    }
+    await applyGritQL(tree, GATEWAY_CONSTRUCT_FILE, authParamPattern);
+    await applyGritQL(tree, GATEWAY_CONSTRUCT_FILE, callPattern);
+    await applyGritQL(tree, GATEWAY_CONSTRUCT_FILE, paramPattern);
+    await applyGritQL(tree, GATEWAY_CONSTRUCT_FILE, credentialPattern);
+};
+/**
+ * Add the `auth` member to each vended agent construct, and for Cognito agents
+ * allowlist the Authorization header so the runtime receives the forwarded JWT.
+ */ const migrateAgentConstructs = async (tree, nextSteps)=>{
+    if (!tree.exists(AGENTS_DIR)) {
+        return;
+    }
+    for (const dir of tree.children(AGENTS_DIR)){
+        const constructFile = `${AGENTS_DIR}/${dir}/${dir}.ts`;
+        if (!tree.exists(constructFile)) {
+            continue;
+        }
+        // Only agents (which carry a gateway target name), not MCP servers.
+        if (!await matchGritQL(tree, constructFile, '`public readonly agentName = $_`')) {
+            continue;
+        }
+        if (await matchGritQL(tree, constructFile, '`public readonly auth = $_`')) {
+            continue; // Already migrated (or user-added).
+        }
+        // Cognito agents configure the runtime's inbound authorizer with a Cognito
+        // JWT — match that authorizerConfiguration property specifically.
+        const isCognito = await matchGritQL(tree, constructFile, '`authorizerConfiguration: RuntimeAuthorizerConfiguration.usingCognito($_)`');
+        const authValue = isCognito ? 'cognito' : 'iam';
+        // The `auth` member, after the agentName member. Matched without the
+        // trailing semicolon — GritQL parses the field's initializer as its AST
+        // node, so the semicolon is appended by the rewrite.
+        const authPattern = `\`public readonly agentName = $name\` as $field => \`$field;
+  /** Inbound auth — a fronting Gateway uses this to pick its outbound credential. */
+  public readonly auth = '${authValue}'\``;
+        // Cognito agents allowlist the Authorization header so the runtime (and a
+        // fronting gateway, via passthrough) receives the caller's token.
+        const headerNeeded = isCognito && !await matchGritQL(tree, constructFile, '`requestHeaderConfiguration: $_`');
+        const headerPattern = `\`authorizerConfiguration: RuntimeAuthorizerConfiguration.usingCognito($args)\` as $authz where {
+  $program <: not contains \`requestHeaderConfiguration\`
+} => \`$authz,
+      ${GRIT_INSERT_PLACEHOLDER}\``;
+        const headerText = `// Receive the caller's Authorization header (validated by the authorizer).
+      requestHeaderConfiguration: {
+        allowlistedHeaders: ['Authorization'],
+      }`;
+        // Verify every anchor up-front so the construct is never half-migrated:
+        // if any edit can't be applied, leave the file untouched with one
+        // actionable next step.
+        const authOk = await matchGritQL(tree, constructFile, authPattern);
+        const headerOk = !headerNeeded || await matchGritQL(tree, constructFile, headerPattern);
+        if (!authOk || !headerOk) {
+            const actions = [
+                `add a \`public readonly auth = '${authValue}';\` member`
+            ];
+            if (headerNeeded) {
+                actions.push(`add \`requestHeaderConfiguration: { allowlistedHeaders: ['Authorization'] }\` to its Runtime so a gateway can pass the caller's JWT through`);
+            }
+            nextSteps.push(`In ${constructFile}: ${actions.join('; and ')}.`);
+            continue;
+        }
+        await applyGritQL(tree, constructFile, authPattern);
+        if (headerNeeded) {
+            await insertViaGritQL(tree, constructFile, headerPattern, headerText);
+        }
+    }
+};
+/**
+ * Add the `request_header_configuration` block to the vended Terraform runtime
+ * module so a JWT-authorized runtime receives the forwarded Authorization
+ * header (the analogue of the CDK requestHeaderConfiguration).
+ */ const migrateTerraformRuntime = async (tree, nextSteps)=>{
+    if (!tree.exists(TF_RUNTIME_FILE)) {
+        return;
+    }
+    if (await matchGritQL(tree, TF_RUNTIME_FILE, 'language hcl\n`dynamic "request_header_configuration" { $_ }`')) {
+        return; // Already migrated.
+    }
+    const tfActionMessage = `In ${TF_RUNTIME_FILE}: add a \`request_header_configuration { request_header_allowlist = ["Authorization"] }\` block (guarded by the JWT authorizer) to the aws_bedrockagentcore_agent_runtime resource so a gateway can pass the caller's JWT through.`;
+    const hasAuthorizerBlock = await matchGritQL(tree, TF_RUNTIME_FILE, 'language hcl\n`dynamic "authorizer_configuration" { $_ }`');
+    if (!hasAuthorizerBlock) {
+        nextSteps.push(tfActionMessage);
+        return;
+    }
+    const added = await insertViaGritQL(tree, TF_RUNTIME_FILE, `language hcl
+\`dynamic "authorizer_configuration" { $body }\` as $block where {
+  $block <: within \`resource "aws_bedrockagentcore_agent_runtime" $_ { $_ }\`
+} => \`$block
+
+  ${GRIT_INSERT_PLACEHOLDER}\``, `# Receive the caller's Authorization header (validated by the JWT authorizer).
+  dynamic "request_header_configuration" {
+    for_each = var.authorizer_configuration != null && try(var.authorizer_configuration.custom_jwt_authorizer, null) != null ? [1] : []
+    content {
+      request_header_allowlist = ["Authorization"]
+    }
+  }`);
+    if (!added) {
+        nextSteps.push(tfActionMessage);
+    }
+};
+export default async function migration(tree) {
+    const nextSteps = [];
+    await migrateGatewayConstruct(tree, nextSteps);
+    await migrateAgentConstructs(tree, nextSteps);
+    await migrateTerraformRuntime(tree, nextSteps);
+    await formatFilesInSubtree(tree);
+    return {
+        nextSteps
+    };
+}
+
+//# sourceMappingURL=migration.js.map

package/src/migrations/latest/gateway-cognito-passthrough/migration.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../packages/nx-plugin/src/migrations/latest/gateway-cognito-passthrough/migration.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport type { MigrationReturnObject, Tree } from '@nx/devkit';\nimport {\n  applyGritQL,\n  GRIT_INSERT_PLACEHOLDER,\n  insertViaGritQL,\n  matchGritQL,\n} from '../../../utils/ast';\nimport { formatFilesInSubtree } from '../../../utils/format';\nimport {\n  PACKAGES_DIR,\n  SHARED_CONSTRUCTS_DIR,\n  SHARED_TERRAFORM_DIR,\n} from '../../../utils/shared-constructs-constants';\n\n/**\n * Bring existing workspaces up to the generators' current gateway->agent\n * support for Cognito agents, which forward the caller's JWT to the runtime:\n *\n * - The vended `AgentCoreGateway` construct's `addAgent`/`addAgentTarget` pick\n *   the outbound credential from the agent's `auth`: a `cognito` agent uses\n *   `JWT_PASSTHROUGH` (the caller's token reaches the runtime), an `iam` agent\n *   the gateway role (`GATEWAY_IAM_ROLE`, the previous behaviour).\n * - Vended agent constructs gain an `auth` member `addAgent` reads, and Cognito\n *   agents allowlist the `Authorization` header (CDK + Terraform runtime) so the\n *   runtime receives the forwarded token.\n *\n * These files are generated with `KeepExisting`, so without this an upgraded\n * workspace pairs new app-level constructs with stale core ones. Diverged files\n * are left untouched and reported via `nextSteps`.\n */\n\nconst GATEWAY_CONSTRUCT_FILE = `${PACKAGES_DIR}/${SHARED_CONSTRUCTS_DIR}/src/core/agentcore-gateway/agentcore-gateway.ts`;\nconst AGENTS_DIR = `${PACKAGES_DIR}/${SHARED_CONSTRUCTS_DIR}/src/app/agents`;\nconst TF_RUNTIME_FILE = `${PACKAGES_DIR}/${SHARED_TERRAFORM_DIR}/src/core/agent-core/runtime.tf`;\n\n/**\n * Teach the vended `AgentCoreGateway` construct to pick the target credential\n * from the agent's `auth` (JWT passthrough for Cognito, gateway role for IAM).\n */\nconst migrateGatewayConstruct = async (\n  tree: Tree,\n  nextSteps: string[],\n): Promise<void> => {\n  if (!tree.exists(GATEWAY_CONSTRUCT_FILE)) {\n    return; // No vended gateway construct.\n  }\n  // Predates agent-target support (the gateway-agent-targets migration adds\n  // addAgentTarget first) — match the method, not a bare identifier.\n  if (\n    !(await matchGritQL(\n      tree,\n      GATEWAY_CONSTRUCT_FILE,\n      '`addAgentTarget(props: { $_ }): agentcore.CfnGatewayTarget { $_ }`',\n    ))\n  ) {\n    return;\n  }\n  // Already migrated: the credentials member is on addAgentTarget's props.\n  if (\n    await matchGritQL(\n      tree,\n      GATEWAY_CONSTRUCT_FILE,\n      \"`credentials?: 'gateway-iam' | 'jwt-passthrough'`\",\n    )\n  ) {\n    return;\n  }\n\n  const divergedMessage = `In ${GATEWAY_CONSTRUCT_FILE}: have addAgent read the agent's \\`auth\\` and pass \\`credentials: 'jwt-passthrough'\\` to addAgentTarget, so the target's credentialProviderType becomes 'JWT_PASSTHROUGH' for Cognito agents.`;\n\n  // GritQL patterns for each of the four edits. Verified against the tree\n  // up-front so the transform is all-or-nothing: a construct missing any\n  // anchor is left untouched with a single actionable next step, rather than\n  // half-migrated.\n  const authParamPattern = `\\`readonly agentName: string\\` as $sig where {\n  $program <: not contains \\`readonly auth?\\`\n} => \\`$sig;\n      readonly auth?: 'iam' | 'cognito'\\``;\n\n  const callPattern = `\\`agentRuntimeArn: agent.agentCoreRuntime.agentRuntimeArn\\` as $prop where {\n  $program <: not contains \\`credentials:\\`\n} => \\`$prop,\n      credentials: agent.auth === 'cognito' ? 'jwt-passthrough' : 'gateway-iam'\\``;\n\n  // The addAgentTarget props type: matched on its `agentRuntimeArn: string`\n  // member signature (without trailing semicolon), which the rewrite re-adds\n  // followed by the credentials member. The `: string` type distinguishes it\n  // from the `agentRuntimeArn:` value in the addAgent call.\n  const paramPattern = `\\`agentRuntimeArn: string\\` as $sig where {\n  $program <: not contains \\`credentials?\\`\n} => \\`$sig;\n    credentials?: 'gateway-iam' | 'jwt-passthrough'\\``;\n\n  // Scoped to the agent target's own CfnGatewayTarget (the one configured with\n  // an agentcoreRuntime), so the MCP server target's GATEWAY_IAM_ROLE — a\n  // sibling method with its own credential block — is left untouched.\n  const credentialPattern = `\\`credentialProviderType: 'GATEWAY_IAM_ROLE'\\` as $cred where {\n  $cred <: within \\`new agentcore.CfnGatewayTarget($_, $_, $config)\\`,\n  $config <: contains \\`agentcoreRuntime\\`\n} => \\`credentialProviderType:\n              props.credentials === 'jwt-passthrough'\n                ? 'JWT_PASSTHROUGH'\n                : 'GATEWAY_IAM_ROLE'\\``;\n\n  // Verify every anchor matches before mutating anything (matchGritQL is\n  // read-only), so a diverged construct is never left partially migrated.\n  for (const pattern of [\n    authParamPattern,\n    callPattern,\n    paramPattern,\n    credentialPattern,\n  ]) {\n    if (!(await matchGritQL(tree, GATEWAY_CONSTRUCT_FILE, pattern))) {\n      nextSteps.push(divergedMessage);\n      return;\n    }\n  }\n\n  await applyGritQL(tree, GATEWAY_CONSTRUCT_FILE, authParamPattern);\n  await applyGritQL(tree, GATEWAY_CONSTRUCT_FILE, callPattern);\n  await applyGritQL(tree, GATEWAY_CONSTRUCT_FILE, paramPattern);\n  await applyGritQL(tree, GATEWAY_CONSTRUCT_FILE, credentialPattern);\n};\n\n/**\n * Add the `auth` member to each vended agent construct, and for Cognito agents\n * allowlist the Authorization header so the runtime receives the forwarded JWT.\n */\nconst migrateAgentConstructs = async (\n  tree: Tree,\n  nextSteps: string[],\n): Promise<void> => {\n  if (!tree.exists(AGENTS_DIR)) {\n    return;\n  }\n  for (const dir of tree.children(AGENTS_DIR)) {\n    const constructFile = `${AGENTS_DIR}/${dir}/${dir}.ts`;\n    if (!tree.exists(constructFile)) {\n      continue;\n    }\n    // Only agents (which carry a gateway target name), not MCP servers.\n    if (\n      !(await matchGritQL(\n        tree,\n        constructFile,\n        '`public readonly agentName = $_`',\n      ))\n    ) {\n      continue;\n    }\n    if (await matchGritQL(tree, constructFile, '`public readonly auth = $_`')) {\n      continue; // Already migrated (or user-added).\n    }\n\n    // Cognito agents configure the runtime's inbound authorizer with a Cognito\n    // JWT — match that authorizerConfiguration property specifically.\n    const isCognito = await matchGritQL(\n      tree,\n      constructFile,\n      '`authorizerConfiguration: RuntimeAuthorizerConfiguration.usingCognito($_)`',\n    );\n    const authValue = isCognito ? 'cognito' : 'iam';\n\n    // The `auth` member, after the agentName member. Matched without the\n    // trailing semicolon — GritQL parses the field's initializer as its AST\n    // node, so the semicolon is appended by the rewrite.\n    const authPattern = `\\`public readonly agentName = $name\\` as $field => \\`$field;\n  /** Inbound auth — a fronting Gateway uses this to pick its outbound credential. */\n  public readonly auth = '${authValue}'\\``;\n\n    // Cognito agents allowlist the Authorization header so the runtime (and a\n    // fronting gateway, via passthrough) receives the caller's token.\n    const headerNeeded =\n      isCognito &&\n      !(await matchGritQL(\n        tree,\n        constructFile,\n        '`requestHeaderConfiguration: $_`',\n      ));\n    const headerPattern = `\\`authorizerConfiguration: RuntimeAuthorizerConfiguration.usingCognito($args)\\` as $authz where {\n  $program <: not contains \\`requestHeaderConfiguration\\`\n} => \\`$authz,\n      ${GRIT_INSERT_PLACEHOLDER}\\``;\n    const headerText = `// Receive the caller's Authorization header (validated by the authorizer).\n      requestHeaderConfiguration: {\n        allowlistedHeaders: ['Authorization'],\n      }`;\n\n    // Verify every anchor up-front so the construct is never half-migrated:\n    // if any edit can't be applied, leave the file untouched with one\n    // actionable next step.\n    const authOk = await matchGritQL(tree, constructFile, authPattern);\n    const headerOk =\n      !headerNeeded || (await matchGritQL(tree, constructFile, headerPattern));\n    if (!authOk || !headerOk) {\n      const actions = [\n        `add a \\`public readonly auth = '${authValue}';\\` member`,\n      ];\n      if (headerNeeded) {\n        actions.push(\n          `add \\`requestHeaderConfiguration: { allowlistedHeaders: ['Authorization'] }\\` to its Runtime so a gateway can pass the caller's JWT through`,\n        );\n      }\n      nextSteps.push(`In ${constructFile}: ${actions.join('; and ')}.`);\n      continue;\n    }\n\n    await applyGritQL(tree, constructFile, authPattern);\n    if (headerNeeded) {\n      await insertViaGritQL(tree, constructFile, headerPattern, headerText);\n    }\n  }\n};\n\n/**\n * Add the `request_header_configuration` block to the vended Terraform runtime\n * module so a JWT-authorized runtime receives the forwarded Authorization\n * header (the analogue of the CDK requestHeaderConfiguration).\n */\nconst migrateTerraformRuntime = async (\n  tree: Tree,\n  nextSteps: string[],\n): Promise<void> => {\n  if (!tree.exists(TF_RUNTIME_FILE)) {\n    return;\n  }\n  if (\n    await matchGritQL(\n      tree,\n      TF_RUNTIME_FILE,\n      'language hcl\\n`dynamic \"request_header_configuration\" { $_ }`',\n    )\n  ) {\n    return; // Already migrated.\n  }\n\n  const tfActionMessage = `In ${TF_RUNTIME_FILE}: add a \\`request_header_configuration { request_header_allowlist = [\"Authorization\"] }\\` block (guarded by the JWT authorizer) to the aws_bedrockagentcore_agent_runtime resource so a gateway can pass the caller's JWT through.`;\n\n  const hasAuthorizerBlock = await matchGritQL(\n    tree,\n    TF_RUNTIME_FILE,\n    'language hcl\\n`dynamic \"authorizer_configuration\" { $_ }`',\n  );\n  if (!hasAuthorizerBlock) {\n    nextSteps.push(tfActionMessage);\n    return;\n  }\n\n  const added = await insertViaGritQL(\n    tree,\n    TF_RUNTIME_FILE,\n    `language hcl\n\\`dynamic \"authorizer_configuration\" { $body }\\` as $block where {\n  $block <: within \\`resource \"aws_bedrockagentcore_agent_runtime\" $_ { $_ }\\`\n} => \\`$block\n\n  ${GRIT_INSERT_PLACEHOLDER}\\``,\n    `# Receive the caller's Authorization header (validated by the JWT authorizer).\n  dynamic \"request_header_configuration\" {\n    for_each = var.authorizer_configuration != null && try(var.authorizer_configuration.custom_jwt_authorizer, null) != null ? [1] : []\n    content {\n      request_header_allowlist = [\"Authorization\"]\n    }\n  }`,\n  );\n  if (!added) {\n    nextSteps.push(tfActionMessage);\n  }\n};\n\nexport default async function migration(\n  tree: Tree,\n): Promise<MigrationReturnObject> {\n  const nextSteps: string[] = [];\n\n  await migrateGatewayConstruct(tree, nextSteps);\n  await migrateAgentConstructs(tree, nextSteps);\n  await migrateTerraformRuntime(tree, nextSteps);\n\n  await formatFilesInSubtree(tree);\n\n  return { nextSteps };\n}\n"],"names":["applyGritQL","GRIT_INSERT_PLACEHOLDER","insertViaGritQL","matchGritQL","formatFilesInSubtree","PACKAGES_DIR","SHARED_CONSTRUCTS_DIR","SHARED_TERRAFORM_DIR","GATEWAY_CONSTRUCT_FILE","AGENTS_DIR","TF_RUNTIME_FILE","migrateGatewayConstruct","tree","nextSteps","exists","divergedMessage","authParamPattern","callPattern","paramPattern","credentialPattern","pattern","push","migrateAgentConstructs","dir","children","constructFile","isCognito","authValue","authPattern","headerNeeded","headerPattern","headerText","authOk","headerOk","actions","join","migrateTerraformRuntime","tfActionMessage","hasAuthorizerBlock","added","migration"],"mappings":"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"}

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.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type MigrationReturnObject, type Tree } from '@nx/devkit';
+export default function migration(tree: Tree): Promise<MigrationReturnObject>;