@aws/nx-plugin 1.0.0-rc.58 → 1.0.0-rc.59

package/src/migrations/latest/gateway-agent-targets/__snapshots__/migration.spec.ts.snap

@@ -0,0 +1,223 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`gateway-agent-targets migration > should add the agentName member to vended agent constructs 1`] = `
+"import {
+  AgentRuntimeArtifact,
+  ProtocolType,
+  Runtime,
+} from 'aws-cdk-lib/aws-bedrockagentcore';
+import { Construct } from 'constructs';
+
+export class MyAgent extends Construct {
+  public readonly dockerImage: AgentRuntimeArtifact;
+  public readonly agentCoreRuntime: Runtime;
+  /** Default Gateway target name for this agent. */
+  public readonly agentName = 'my-agent';
+
+  constructor(scope: Construct, id: string) {
+    super(scope, id);
+    this.agentCoreRuntime = undefined as any;
+  }
+}
+"
+`;
+
+exports[`gateway-agent-targets migration > should add the protocol prop and agent target methods to the vended gateway construct 1`] = `
+"import * as cdk from 'aws-cdk-lib';
+import * as agentcore from 'aws-cdk-lib/aws-bedrockagentcore';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import * as triggers from 'aws-cdk-lib/triggers';
+import * as wafv2 from 'aws-cdk-lib/aws-wafv2';
+import { Construct } from 'constructs';
+
+export interface AgentCoreGatewayProps {
+  readonly cedarPolicyPath?: string;
+  readonly cedarPolicyVariables?: Record<string, string>;
+  readonly enableWaf?: boolean;
+  readonly authorizer?: agentcore.IGatewayAuthorizerConfig;
+  /**
+   * 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';
+}
+
+export class AgentCoreGateway extends Construct implements iam.IGrantable {
+  public readonly gateway: agentcore.Gateway;
+  public readonly policyEngine?: agentcore.CfnPolicyEngine;
+  public readonly webAcl?: wafv2.CfnWebACL;
+  private readonly policies: agentcore.CfnPolicy[] = [];
+  private targetReadinessProbe?: triggers.TriggerFunction;
+  private readonly targetRuntimeArns: string[] = [];
+  private readonly protocol: 'mcp' | 'http';
+
+  constructor(scope: Construct, id: string, props?: AgentCoreGatewayProps) {
+    super(scope, id);
+
+    this.protocol = props?.protocol ?? 'mcp';
+
+    this.gateway = new agentcore.Gateway(this, 'Gateway', {
+      gatewayName: cdk.Names.uniqueResourceName(this, { maxLength: 39 }),
+      protocolConfiguration: new agentcore.McpProtocolConfiguration({
+        searchType: agentcore.McpGatewaySearchType.SEMANTIC,
+        supportedVersions: [agentcore.MCPProtocolVersion.MCP_2025_03_26],
+      }),
+      authorizerConfiguration:
+        props?.authorizer ?? agentcore.GatewayAuthorizer.usingAwsIam(),
+    });
+
+    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');
+    }
+  }
+
+  public get grantPrincipal(): iam.IPrincipal {
+    return this.gateway.role.grantPrincipal;
+  }
+
+  public addGatewayTarget(props: {
+    gatewayTargetName: string;
+    gatewayUrl: string;
+    gatewayArn: string;
+  }): agentcore.CfnGatewayTarget {
+    const target = this.addTarget(props.gatewayTargetName, props.gatewayUrl);
+
+    const grant = this.gateway.role.addToPrincipalPolicy(
+      new iam.PolicyStatement({
+        actions: ['bedrock-agentcore:InvokeGateway'],
+        resources: [props.gatewayArn],
+      }),
+    );
+    if (grant.policyDependable) {
+      target.node.addDependency(grant.policyDependable);
+    }
+
+    return target;
+  }
+
+  /**
+   * 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;
+  }
+
+  private addTarget(
+    gatewayTargetName: string,
+    endpoint: string,
+  ): agentcore.CfnGatewayTarget {
+    const target = new agentcore.CfnGatewayTarget(
+      this,
+      \`Target-\${gatewayTargetName}\`,
+      {
+        gatewayIdentifier: this.gateway.gatewayId,
+        name: gatewayTargetName,
+        targetConfiguration: {
+          mcp: {
+            mcpServer: {
+              endpoint,
+            },
+          },
+        },
+      },
+    );
+
+    for (const policy of this.policies) {
+      policy.node.addDependency(target);
+    }
+
+    return target;
+  }
+}
+"
+`;

package/src/migrations/latest/gateway-agent-targets/metadata.json

@@ -0,0 +1,3 @@
+{
+  "description": "Add agent runtime target support to the vended AgentCoreGateway construct and an agentName member to vended agent constructs"
+}

package/src/migrations/latest/gateway-agent-targets/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-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/smithy-ssdk-bundle-pins/metadata.json

@@ -0,0 +1,3 @@
+{
+  "description": "Bump the rolldown and dts plugin pins in the Smithy build.Dockerfile so the bundled SSDK type declaration resolves"
+}

package/src/migrations/v1.0.0-rc.50/modernize-function-props-cast/metadata.json

@@ -0,0 +1,3 @@
+{
+  "description": "Replace the legacy angle-bracket FunctionProps type assertion with the modern as syntax in generated API constructs"
+}

package/src/migrations/v1.0.0-rc.50/restrict-cors-to-custom-domains/metadata.json

@@ -0,0 +1,3 @@
+{
+  "description": "Include CloudFront custom domain aliases in restrictCorsTo and UserIdentity callback URLs"
+}

package/src/migrations/v1.0.0-rc.50/terraform-bootstrap-adopt-existing-bucket/metadata.json

@@ -0,0 +1,3 @@
+{
+  "description": "Adopt an existing Terraform state bucket in the vended bootstrap script when its state object is missing"
+}

package/src/migrations/v1.0.0-rc.52/user-identity-waf-allow-localhost-callback/metadata.json

@@ -0,0 +1,3 @@
+{
+  "description": "Count the EC2MetaDataSSRF_QUERYARGUMENTS WAF rule on the UserIdentity Web ACL so sign-in from a local dev server is not blocked"
+}

package/src/migrations/v1.0.0-rc.54/order-access-log-delivery-after-bucket-policy/metadata.json

@@ -0,0 +1,3 @@
+{
+  "description": "Order the S3 server access log delivery source after the bucket policy to avoid a 409 from concurrent bucket configuration writes"
+}

package/src/migrations/v1.0.0-rc.55/backfill-generator-metadata/metadata.json

@@ -0,0 +1,3 @@
+{
+  "description": "Backfill the project metadata the version sync reads, recovered from the files the generators left behind"
+}

package/src/migrations/v1.0.0-rc.56/dynamodb-local-remove-optimize-flag/metadata.json

@@ -0,0 +1,3 @@
+{
+  "description": "Drop -optimizeDbBeforeStartup from the vended DynamoDB Local container script, which can corrupt shared-local-instance.db"
+}

package/src/migrations/v1.0.0-rc.57/ts-agent-session-management-support/metadata.json

@@ -0,0 +1,3 @@
+{
+  "description": "Add session management support to ts#agent"
+}

package/src/py/agent/__snapshots__/generator.constructs.spec.ts.snap

@@ -55,6 +55,8 @@ export class SnapshotBedrockAgent
 {
   public readonly dockerImage: AgentRuntimeArtifact;
   public readonly agentCoreRuntime: Runtime;
+  /** Default Gateway target name for this agent. */
+  public readonly agentName = 'snapshot-bedrock-agent';
 
   constructor(scope: Construct, id: string, props?: SnapshotBedrockAgentProps) {
     super(scope, id);

package/src/py/agent/react-connection/generator.d.ts

@@ -4,6 +4,7 @@
  */
 import { type Tree } from '@nx/devkit';
 import type { ResolvedConnectionOptions } from '../../../connection/generator';
+import type { AgentGatewayRoute } from '../../../ts/agent/react-connection/generator';
 import { type NxGeneratorInfo } from '../../../utils/nx';
 /** The metadata this generator records, which its predicates read. */
 export interface PyAgentReactConnectionMetadata {
@@ -152,5 +153,7 @@ export declare const DEPENDENCIES: import("../../../utils/declared-dependencies"
     when: (m: PyAgentReactConnectionMetadata) => boolean;
 }], readonly import("../../../utils/declared-dependencies").DeclaredPyDependency<"a2a-sdk" | "ag-ui-langgraph" | "ag-ui-protocol" | "ag-ui-strands" | "aws-lambda-powertools" | "aws-lambda-powertools[tracer]" | "aws-lambda-powertools[parser]" | "aws-opentelemetry-distro" | "bedrock-agentcore" | "boto3" | "checkov" | "fastapi" | "fastapi[standard]" | "httpx" | "langchain" | "langchain-aws" | "langchain-mcp-adapters" | "langgraph" | "mcp" | "pip-check-updates" | "pip-licenses" | "ruff" | "strands-agents" | "strands-agents[a2a]" | "strands-agents-tools" | "ty" | "pynamodb" | "uvicorn" | "sqlmodel" | "alembic" | "aiomysql" | "asyncpg" | "greenlet", PyAgentReactConnectionMetadata>[]>;
 export declare const PY_AGENT_REACT_CONNECTION_GENERATOR_INFO: NxGeneratorInfo;
-export declare const pyAgentReactConnectionGenerator: (tree: Tree, options: ResolvedConnectionOptions) => Promise<() => Promise<void>>;
+export declare const pyAgentReactConnectionGenerator: (tree: Tree, options: ResolvedConnectionOptions & {
+    gatewayRoute?: AgentGatewayRoute;
+}) => Promise<() => Promise<void>>;
 export default pyAgentReactConnectionGenerator;

package/src/py/agent/react-connection/generator.js

@@ -10,7 +10,7 @@ import { formatFilesInSubtree } from "../../../utils/format.js";
 import { installDependencies } from "../../../utils/install.js";
 import { addGeneratorMetricsIfApplicable } from "../../../utils/metrics.js";
 import { kebabCase, toClassName, toSnakeCase } from "../../../utils/names.js";
-import { addComponentGeneratorMetadata, getGeneratorInfo, readProjectConfigurationUnqualified } from "../../../utils/nx.js";
+import { addComponentGeneratorMetadata, addDependencyToTargetIfNotPresent, getGeneratorInfo, readProjectConfigurationUnqualified } from "../../../utils/nx.js";
 import { sortObjectKeys } from "../../../utils/object.js";
 import { toProjectRelativePath } from "../../../utils/paths.js";
 import { addPyAgentTargetToLocalDev, openApiClientLocalDevDeps } from "./local-dev.js";
@@ -36,7 +36,8 @@ export const pyAgentReactConnectionGenerator = async (tree, options)=>{
     const agentName = targetComponent?.name ?? 'agent';
     const agentNameClassName = targetComponent?.rc ?? toClassName(agentName);
     const agentPort = targetComponent?.port ?? metadata?.ports?.[0] ?? 8081;
-    const auth = (targetComponent?.auth ?? metadata?.auth ?? 'iam').toLowerCase();
+    // Behind a gateway the browser authenticates with the gateway, not the agent.
+    const auth = (options.gatewayRoute?.gatewayAuth ?? targetComponent?.auth ?? metadata?.auth ?? 'iam').toLowerCase();
     const protocol = (targetComponent?.protocol ?? 'http').toLowerCase();
     // Recorded below and read by the declaration's predicates, so the packages
     // added here are exactly the ones the version sync will own.
@@ -54,7 +55,8 @@ export const pyAgentReactConnectionGenerator = async (tree, options)=>{
             frontendProjectConfig,
             agentName,
             agentNameClassName,
-            auth: auth
+            auth: auth,
+            gatewayRoute: options.gatewayRoute
         });
     } else {
         const moduleName = getModuleName(agentProjectConfig);
@@ -101,25 +103,44 @@ export const pyAgentReactConnectionGenerator = async (tree, options)=>{
             auth,
             port: agentPort,
             isAgentRuntime: true,
+            gatewayRoute: options.gatewayRoute,
             skipLocalDev: true
         }, DEPENDENCIES);
         additionalLocalDevDeps = openApiClientLocalDevDeps(agentNameClassName);
         // HTTP only — the AG-UI branch handles this inside addAgUiReactConnection.
         // Agent constructs publish their runtime ARN to the 'agentcore' namespace
         // by default, which isn't exposed to the website; patch them to also
-        // publish under 'connection' so the browser can read it.
-        await addAgentRuntimeToConnectionNamespace(tree, {
-            agentNameKebabCase: kebabCase(agentNameClassName),
-            agentNameClassName
+        // publish under 'connection' so the browser can read it. When routing via
+        // a gateway, the gateway publishes its own URL instead.
+        if (!options.gatewayRoute) {
+            await addAgentRuntimeToConnectionNamespace(tree, {
+                agentNameKebabCase: kebabCase(agentNameClassName),
+                agentNameClassName
+            });
+        }
+    }
+    if (options.gatewayRoute) {
+        // The gateway react-connection wires the website's dev target to the
+        // local gateway (which proxies to the agent); only the OpenAPI client
+        // generation targets are still needed here.
+        if (additionalLocalDevDeps.length > 0) {
+            const websiteConfig = readProjectConfigurationUnqualified(tree, frontendProjectConfig.name);
+            if (websiteConfig.targets?.['dev']) {
+                for (const additional of additionalLocalDevDeps){
+                    addDependencyToTargetIfNotPresent(websiteConfig, 'dev', additional);
+                }
+                updateProjectConfiguration(tree, websiteConfig.name, websiteConfig);
+            }
+        }
+    } else {
+        await addPyAgentTargetToLocalDev(tree, frontendProjectConfig.name, agentProjectConfig.name, {
+            agentName,
+            agentNameClassName,
+            port: agentPort,
+            targetComponent,
+            additionalDependencyTargets: additionalLocalDevDeps
         });
     }
-    await addPyAgentTargetToLocalDev(tree, frontendProjectConfig.name, agentProjectConfig.name, {
-        agentName,
-        agentNameClassName,
-        port: agentPort,
-        targetComponent,
-        additionalDependencyTargets: additionalLocalDevDeps
-    });
     // Recorded so the version sync knows this connection's dependencies are ours.
     addComponentGeneratorMetadata(tree, frontendProjectConfig.name, PY_AGENT_REACT_CONNECTION_GENERATOR_INFO, toProjectRelativePath(frontendProjectConfig, protocol === 'ag-ui' ? joinPathFragments(frontendProjectConfig.sourceRoot, 'hooks', `useAgui${agentNameClassName}`) : joinPathFragments(frontendProjectConfig.sourceRoot, 'components', `${agentNameClassName}Provider`)), agentNameClassName, connectionMetadata);
     await addGeneratorMetricsIfApplicable(tree, [