@aws/nx-plugin 1.0.0-rc.9 → 1.0.0-rc.90

package/src/agentcore-gateway/__snapshots__/generator.spec.ts.snap

@@ -0,0 +1,344 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`agentcore-gateway generator > protocol: http > omits protocol_type from the Terraform gateway > my-gateway.tf 1`] = `
+"terraform {
+  required_version = ">= 1.0"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "6.62.0"
+    }
+    time = {
+      source  = "hashicorp/time"
+      version = "0.14.1"
+    }
+    random = {
+      source  = "hashicorp/random"
+      version = "3.9.0"
+    }
+  }
+}
+
+variable "additional_iam_policy_statements" {
+  description = "Additional IAM policy statements to attach to the gateway service role. Connection generators (e.g. agentcore-gateway#mcp-connection) append \`InvokeAgentRuntime*\` entries here."
+  type = list(object({
+    Effect   = string
+    Action   = list(string)
+    Resource = list(string)
+  }))
+  default = []
+}
+
+
+variable "enable_waf" {
+  description = "Associate a regional WAFv2 web ACL (default AWS managed rule groups) with the gateway to inspect inbound requests."
+  type        = bool
+  default     = true
+}
+
+data "aws_caller_identity" "current" {}
+data "aws_region" "current" {}
+
+locals {
+  aws_account_id = data.aws_caller_identity.current.account_id
+  aws_region     = data.aws_region.current.id
+
+  gateway_waf_log_group_name = var.enable_waf ? "aws-waf-logs-my-gateway-\${random_id.unique_suffix.hex}" : null
+}
+
+resource "random_id" "unique_suffix" {
+  byte_length = 4
+}
+
+# IAM role for the gateway service
+resource "aws_iam_role" "gateway_role" {
+  name = "MyGateway-GatewayRole-\${random_id.unique_suffix.hex}"
+
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Sid    = "AgentCoreGatewayAssumeRolePolicy"
+        Effect = "Allow"
+        Principal = {
+          Service = "bedrock-agentcore.amazonaws.com"
+        }
+        Action = "sts:AssumeRole"
+        Condition = {
+          StringEquals = {
+            "aws:SourceAccount" = local.aws_account_id
+          }
+          ArnLike = {
+            "aws:SourceArn" = "arn:aws:bedrock-agentcore:\${local.aws_region}:\${local.aws_account_id}:*"
+          }
+        }
+      }
+    ]
+  })
+}
+
+# Inline policy for statements appended by connection generators
+# (e.g. InvokeAgentRuntime*)
+resource "aws_iam_role_policy" "gateway_role_policy" {
+  count = length(var.additional_iam_policy_statements) > 0 ? 1 : 0
+  name  = "MyGateway-GatewayPolicy"
+  role  = aws_iam_role.gateway_role.id
+
+  policy = jsonencode({
+    Version   = "2012-10-17"
+    Statement = var.additional_iam_policy_statements
+  })
+}
+
+# IAM is eventually consistent, and the gateway assumes this role to reach its
+# targets — an MCP target fetches tools at creation time. Without this wait the
+# fetch intermittently runs before the policy above has propagated and the
+# target lands in FAILED with an authorization error.
+resource "time_sleep" "gateway_role_policy_propagation" {
+  count = length(var.additional_iam_policy_statements) > 0 ? 1 : 0
+
+  depends_on = [aws_iam_role_policy.gateway_role_policy]
+
+  create_duration = "30s"
+
+  triggers = {
+    policy = aws_iam_role_policy.gateway_role_policy[0].policy
+  }
+}
+
+resource "aws_bedrockagentcore_gateway" "this" {
+  # Cap the name so the 11-char service suffix keeps the gateway id within its
+  # 50-char limit (30 prefix + "-<8 hex>" + 11 = 50).
+  name        = "\${substr("MyGateway", 0, 30)}-\${random_id.unique_suffix.hex}"
+  description = "AgentCore Gateway for MyGateway"
+  role_arn    = aws_iam_role.gateway_role.arn
+
+  # No protocol type: AgentCore Runtime targets require a gateway without one.
+  # The gateway proxies requests to its runtime targets via path-based routing
+  # (\`/<targetName>/invocations\`).
+
+  authorizer_type = "AWS_IAM"
+
+  depends_on = [time_sleep.gateway_role_policy_propagation]
+}
+
+# WAFv2 protection for the gateway. AgentCore Gateway requires a REGIONAL web
+# ACL; CloudFront (global) is not supported.
+resource "aws_wafv2_web_acl" "gateway_waf" {
+  #checkov:skip=CKV2_AWS_31:Logging configuration is defined below in aws_wafv2_web_acl_logging_configuration.gateway_waf_logging; Checkov does not resolve the separate resource
+  count = var.enable_waf ? 1 : 0
+
+  name  = "MyGateway-waf-\${random_id.unique_suffix.hex}"
+  scope = "REGIONAL"
+
+  default_action {
+    allow {}
+  }
+
+  rule {
+    name     = "CRSRule"
+    priority = 0
+
+    override_action {
+      none {}
+    }
+
+    statement {
+      managed_rule_group_statement {
+        name        = "AWSManagedRulesCommonRuleSet"
+        vendor_name = "AWS"
+
+        # Count instead of Block: the CRS 8 KB body limit is too restrictive
+        # for typical MCP tool payloads.
+        rule_action_override {
+          name = "SizeRestrictions_BODY"
+          action_to_use {
+            count {}
+          }
+        }
+      }
+    }
+
+    visibility_config {
+      cloudwatch_metrics_enabled = true
+      metric_name                = "MyGatewayWebAcl-CRS"
+      sampled_requests_enabled   = true
+    }
+  }
+
+  rule {
+    name     = "KnownBadInputsRule"
+    priority = 1
+
+    override_action {
+      none {}
+    }
+
+    statement {
+      managed_rule_group_statement {
+        name        = "AWSManagedRulesKnownBadInputsRuleSet"
+        vendor_name = "AWS"
+      }
+    }
+
+    visibility_config {
+      cloudwatch_metrics_enabled = true
+      metric_name                = "MyGatewayWebAcl-KnownBadInputs"
+      sampled_requests_enabled   = true
+    }
+  }
+
+  visibility_config {
+    cloudwatch_metrics_enabled = true
+    metric_name                = "MyGatewayWebAcl"
+    sampled_requests_enabled   = true
+  }
+
+  lifecycle {
+    create_before_destroy = true
+  }
+}
+
+resource "aws_wafv2_web_acl_association" "gateway_waf" {
+  count = var.enable_waf ? 1 : 0
+
+  resource_arn = aws_bedrockagentcore_gateway.this.gateway_arn
+  web_acl_arn  = aws_wafv2_web_acl.gateway_waf[0].arn
+}
+
+# KMS key for encrypting WAF request logs at rest
+resource "aws_kms_key" "gateway_waf_logs" {
+  count = var.enable_waf ? 1 : 0
+
+  description             = "MyGateway gateway WAF log encryption"
+  deletion_window_in_days = 7
+  enable_key_rotation     = true
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Sid       = "Enable IAM User Permissions"
+        Effect    = "Allow"
+        Principal = { AWS = "arn:aws:iam::\${local.aws_account_id}:root" }
+        Action    = "kms:*"
+        Resource  = "*"
+      },
+      {
+        Sid       = "Allow CloudWatch Logs"
+        Effect    = "Allow"
+        Principal = { Service = "logs.\${local.aws_region}.amazonaws.com" }
+        Action = [
+          "kms:Encrypt",
+          "kms:Decrypt",
+          "kms:ReEncrypt*",
+          "kms:GenerateDataKey*",
+          "kms:DescribeKey"
+        ]
+        Resource = "*"
+        Condition = {
+          ArnEquals = {
+            "kms:EncryptionContext:aws:logs:arn" = "arn:aws:logs:\${local.aws_region}:\${local.aws_account_id}:log-group:\${local.gateway_waf_log_group_name}"
+          }
+        }
+      }
+    ]
+  })
+}
+
+resource "aws_kms_alias" "gateway_waf_logs" {
+  count = var.enable_waf ? 1 : 0
+
+  name          = "alias/my-gateway-\${random_id.unique_suffix.hex}-waf-logs"
+  target_key_id = aws_kms_key.gateway_waf_logs[0].key_id
+}
+
+# WAF request logs. WAFv2 requires the \`aws-waf-logs-\` name prefix.
+resource "aws_cloudwatch_log_group" "gateway_waf_logs" {
+  #checkov:skip=CKV_AWS_338:Log retention set to one year which is sufficient for WAF logs
+  count = var.enable_waf ? 1 : 0
+
+  name              = local.gateway_waf_log_group_name
+  retention_in_days = 365
+  kms_key_id        = aws_kms_key.gateway_waf_logs[0].arn
+}
+
+resource "aws_wafv2_web_acl_logging_configuration" "gateway_waf_logging" {
+  count = var.enable_waf ? 1 : 0
+
+  log_destination_configs = [aws_cloudwatch_log_group.gateway_waf_logs[0].arn]
+  resource_arn            = aws_wafv2_web_acl.gateway_waf[0].arn
+}
+
+
+# Add gateway URL to runtime config
+module "add_gateway_url_to_runtime_config" {
+  source = "../../../core/runtime-config/entry"
+
+  namespace = "agentcore"
+  key       = "gateways"
+  value     = { "MyGateway" = aws_bedrockagentcore_gateway.this.gateway_url }
+
+  depends_on = [aws_bedrockagentcore_gateway.this]
+}
+
+output "gateway_id" {
+  description = "ID of the Bedrock AgentCore Gateway"
+  value       = aws_bedrockagentcore_gateway.this.gateway_id
+}
+
+output "gateway_arn" {
+  description = "ARN of the Bedrock AgentCore Gateway"
+  value       = aws_bedrockagentcore_gateway.this.gateway_arn
+}
+
+output "gateway_url" {
+  description = "Endpoint URL of the Bedrock AgentCore Gateway. Runtime targets are served under \`<gateway_url minus /mcp>/<targetName>/invocations\`."
+  value       = aws_bedrockagentcore_gateway.this.gateway_url
+}
+
+output "gateway_role_arn" {
+  description = "ARN of the IAM role assumed by the gateway service"
+  value       = aws_iam_role.gateway_role.arn
+}
+
+output "waf_web_acl_arn" {
+  description = "ARN of the WAFv2 web ACL associated with the gateway, or null if WAF is disabled"
+  value       = var.enable_waf ? aws_wafv2_web_acl.gateway_waf[0].arn : null
+}
+"
+`;
+
+exports[`agentcore-gateway generator > protocol: http > wires the CDK construct with the http protocol > my-gateway.ts 1`] = `
+"import { Construct } from 'constructs';
+import {
+  AgentCoreGateway,
+  AgentCoreGatewayProps,
+} from '../../../core/agentcore-gateway/agentcore-gateway.js';
+import { RuntimeConfig } from '../../../core/runtime-config.js';
+
+export type MyGatewayProps = Omit<AgentCoreGatewayProps, 'protocol'>;
+
+/**
+ * AgentCore Gateway wired for HTTP proxying of agent runtime targets with IAM inbound auth.
+ */
+export class MyGateway extends AgentCoreGateway {
+  /** Default Gateway target name when added to another Gateway. */
+  public readonly gatewayName = 'my-gateway';
+
+  constructor(scope: Construct, id: string, props?: MyGatewayProps) {
+    super(scope, id, {
+      protocol: 'http',
+      ...props,
+    });
+
+    const rc = RuntimeConfig.ensure(this);
+    rc.set('agentcore', 'gateways', {
+      ...rc.get('agentcore').gateways,
+      MyGateway: this.gateway.gatewayUrl,
+    });
+  }
+}
+"
+`;

package/src/agentcore-gateway/agent-connection/generator.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { GeneratorCallback, Tree } from '@nx/devkit';
+import { type NxGeneratorInfo } from '../../utils/nx.js';
+import type { AgentcoreGatewayAgentConnectionGeneratorSchema } from './schema';
+export declare const AGENTCORE_GATEWAY_AGENT_CONNECTION_GENERATOR_INFO: NxGeneratorInfo;
+/**
+ * Connect an AgentCore Gateway to an agent, so the agent is added as a
+ * gateway target and served under `<gatewayUrl>/<targetName>/invocations`.
+ *
+ * Chains the gateway's dev target to the agent's dev target, and registers
+ * the agent in the gateway's local-dev.ts so the local gateway proxies to it.
+ * Users must still call `gateway.addAgent(...)` in their application stack to
+ * create the actual CDK/Terraform resource.
+ */
+export declare const agentcoreGatewayAgentConnectionGenerator: (tree: Tree, options: AgentcoreGatewayAgentConnectionGeneratorSchema) => Promise<GeneratorCallback>;
+export default agentcoreGatewayAgentConnectionGenerator;

package/src/agentcore-gateway/agent-connection/generator.js

@@ -0,0 +1,95 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { formatFilesInSubtree } from "../../utils/format.js";
+import { installDependencies } from "../../utils/install.js";
+import { addGeneratorMetricsIfApplicable } from "../../utils/metrics.js";
+import { kebabCase, toClassName } from "../../utils/names.js";
+import { addComponentGeneratorMetadata, getGeneratorInfo, readProjectConfigurationUnqualified } from "../../utils/nx.js";
+import { attachAgentToLocalGateway } from "../attach-upstream.js";
+import { readAgentCoreGatewayMetadata } from "../generator.js";
+export const AGENTCORE_GATEWAY_AGENT_CONNECTION_GENERATOR_INFO = getGeneratorInfo(import.meta.filename);
+/**
+ * The agent protocols an http gateway can front, by agent language. The
+ * gateway proxies plain HTTP request/response and SSE streams:
+ *
+ * - `ag-ui` (ts + py) and `http` (py) serve POST /invocations with streamed
+ *   responses, which proxy cleanly.
+ * - `a2a` (ts + py) is JSON-RPC over POST, which AgentCore applies a default
+ *   schema for.
+ * - `http` (ts) is tRPC over WebSocket, and the gateway does not support
+ *   WebSocket / bidirectional streaming, so it cannot sit behind one.
+ */ const SUPPORTED_AGENT_PROTOCOLS = {
+    'ts#agent': [
+        'ag-ui',
+        'a2a'
+    ],
+    'py#agent': [
+        'ag-ui',
+        'http',
+        'a2a'
+    ]
+};
+/**
+ * Connect an AgentCore Gateway to an agent, so the agent is added as a
+ * gateway target and served under `<gatewayUrl>/<targetName>/invocations`.
+ *
+ * Chains the gateway's dev target to the agent's dev target, and registers
+ * the agent in the gateway's local-dev.ts so the local gateway proxies to it.
+ * Users must still call `gateway.addAgent(...)` in their application stack to
+ * create the actual CDK/Terraform resource.
+ */ export const agentcoreGatewayAgentConnectionGenerator = async (tree, options)=>{
+    const sourceProject = readProjectConfigurationUnqualified(tree, options.sourceProject);
+    const targetProject = readProjectConfigurationUnqualified(tree, options.targetProject);
+    const gateway = readAgentCoreGatewayMetadata(sourceProject);
+    const agentComponent = options.targetComponent;
+    if (!agentComponent) {
+        throw new Error(`Target project '${options.targetProject}' has no agent component metadata. Did you run the 'ts#agent' or 'py#agent' generator?`);
+    }
+    if (gateway.protocol !== 'http') {
+        throw new Error(`Gateway '${gateway.name}' has protocol='${gateway.protocol}'. Agent targets can only be attached to http-protocol gateways — generate one with the 'agentcore-gateway' generator and --protocol=http.`);
+    }
+    const agentGenerator = agentComponent.generator ?? 'ts#agent';
+    const agentProtocol = (agentComponent.protocol ?? 'http').toLowerCase();
+    const supportedProtocols = SUPPORTED_AGENT_PROTOCOLS[agentGenerator] ?? [];
+    if (!supportedProtocols.includes(agentProtocol)) {
+        throw new Error(`Agent '${agentComponent.name}' uses protocol='${agentProtocol}', which cannot be fronted by a gateway` + (agentGenerator === 'ts#agent' && agentProtocol === 'http' ? ` — a TypeScript HTTP agent serves tRPC over WebSocket, and AgentCore Gateway does not support WebSocket streaming. Consider the ag-ui protocol instead.` : `. Supported protocols: ${supportedProtocols.join(', ')}.`));
+    }
+    // Both IAM and Cognito agents can be fronted. An IAM agent is invoked with
+    // the gateway's own role (GATEWAY_IAM_ROLE); a Cognito agent has the caller's
+    // JWT forwarded to it (JWT_PASSTHROUGH) so it authorizes on the token. The
+    // vended `addAgent` picks the credential from the agent's `auth`.
+    const agentAuth = agentComponent.auth ?? 'iam';
+    if (agentAuth !== 'iam' && agentAuth !== 'cognito') {
+        throw new Error(`Agent '${agentComponent.name}' uses auth='${agentAuth}', which a gateway cannot front. Supported: iam, cognito.`);
+    }
+    // The target name must match what the deployed Gateway uses (`agentName` on
+    // the agent construct, derived from the project's class name) so the
+    // `/<target>/invocations` path resolves identically locally and deployed.
+    const agentComponentName = agentComponent.name ?? 'agent';
+    const agentTargetName = kebabCase(agentComponent.rc ?? toClassName(agentComponentName));
+    await attachAgentToLocalGateway(tree, sourceProject, 'dev', {
+        targetName: agentTargetName,
+        port: agentComponent.port ?? 8081,
+        upstreamProjectName: targetProject.name,
+        upstreamDevTargetName: `${agentComponentName}-dev`,
+        // The deployed gateway maps an A2A target's `/invocations/...` paths onto
+        // the agent container's root; HTTP and AG-UI agents serve /invocations
+        // themselves.
+        stripInvocations: agentProtocol === 'a2a'
+    });
+    // Recorded so the version sync can identify this connection.
+    addComponentGeneratorMetadata(tree, sourceProject.name, AGENTCORE_GATEWAY_AGENT_CONNECTION_GENERATOR_INFO, targetProject.root, agentTargetName);
+    await addGeneratorMetricsIfApplicable(tree, [
+        AGENTCORE_GATEWAY_AGENT_CONNECTION_GENERATOR_INFO
+    ]);
+    await formatFilesInSubtree(tree);
+    return ()=>installDependencies(tree, options.preferInstallDependencies, {
+            languages: [
+                'typescript'
+            ]
+        });
+};
+export default agentcoreGatewayAgentConnectionGenerator;
+
+//# sourceMappingURL=generator.js.map

package/src/agentcore-gateway/agent-connection/generator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../packages/nx-plugin/src/agentcore-gateway/agent-connection/generator.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport type { GeneratorCallback, Tree } from '@nx/devkit';\nimport { formatFilesInSubtree } from '../../utils/format.js';\nimport { installDependencies } from '../../utils/install.js';\nimport { addGeneratorMetricsIfApplicable } from '../../utils/metrics.js';\nimport { kebabCase, toClassName } from '../../utils/names.js';\nimport {\n  addComponentGeneratorMetadata,\n  getGeneratorInfo,\n  type NxGeneratorInfo,\n  readProjectConfigurationUnqualified,\n} from '../../utils/nx.js';\nimport { attachAgentToLocalGateway } from '../attach-upstream.js';\nimport { readAgentCoreGatewayMetadata } from '../generator.js';\nimport type { AgentcoreGatewayAgentConnectionGeneratorSchema } from './schema';\n\nexport const AGENTCORE_GATEWAY_AGENT_CONNECTION_GENERATOR_INFO: NxGeneratorInfo =\n  getGeneratorInfo(import.meta.filename);\n\n/**\n * The agent protocols an http gateway can front, by agent language. The\n * gateway proxies plain HTTP request/response and SSE streams:\n *\n * - `ag-ui` (ts + py) and `http` (py) serve POST /invocations with streamed\n *   responses, which proxy cleanly.\n * - `a2a` (ts + py) is JSON-RPC over POST, which AgentCore applies a default\n *   schema for.\n * - `http` (ts) is tRPC over WebSocket, and the gateway does not support\n *   WebSocket / bidirectional streaming, so it cannot sit behind one.\n */\nconst SUPPORTED_AGENT_PROTOCOLS: Record<string, string[]> = {\n  'ts#agent': ['ag-ui', 'a2a'],\n  'py#agent': ['ag-ui', 'http', 'a2a'],\n};\n\n/**\n * Connect an AgentCore Gateway to an agent, so the agent is added as a\n * gateway target and served under `<gatewayUrl>/<targetName>/invocations`.\n *\n * Chains the gateway's dev target to the agent's dev target, and registers\n * the agent in the gateway's local-dev.ts so the local gateway proxies to it.\n * Users must still call `gateway.addAgent(...)` in their application stack to\n * create the actual CDK/Terraform resource.\n */\nexport const agentcoreGatewayAgentConnectionGenerator = async (\n  tree: Tree,\n  options: AgentcoreGatewayAgentConnectionGeneratorSchema,\n): Promise<GeneratorCallback> => {\n  const sourceProject = readProjectConfigurationUnqualified(\n    tree,\n    options.sourceProject,\n  );\n  const targetProject = readProjectConfigurationUnqualified(\n    tree,\n    options.targetProject,\n  );\n\n  const gateway = readAgentCoreGatewayMetadata(sourceProject);\n  const agentComponent = options.targetComponent;\n\n  if (!agentComponent) {\n    throw new Error(\n      `Target project '${options.targetProject}' has no agent component metadata. Did you run the 'ts#agent' or 'py#agent' generator?`,\n    );\n  }\n\n  if (gateway.protocol !== 'http') {\n    throw new Error(\n      `Gateway '${gateway.name}' has protocol='${gateway.protocol}'. Agent targets can only be attached to http-protocol gateways — generate one with the 'agentcore-gateway' generator and --protocol=http.`,\n    );\n  }\n\n  const agentGenerator = agentComponent.generator ?? 'ts#agent';\n  const agentProtocol = (\n    (agentComponent.protocol as string | undefined) ?? 'http'\n  ).toLowerCase();\n  const supportedProtocols = SUPPORTED_AGENT_PROTOCOLS[agentGenerator] ?? [];\n  if (!supportedProtocols.includes(agentProtocol)) {\n    throw new Error(\n      `Agent '${agentComponent.name}' uses protocol='${agentProtocol}', which cannot be fronted by a gateway` +\n        (agentGenerator === 'ts#agent' && agentProtocol === 'http'\n          ? ` — a TypeScript HTTP agent serves tRPC over WebSocket, and AgentCore Gateway does not support WebSocket streaming. Consider the ag-ui protocol instead.`\n          : `. Supported protocols: ${supportedProtocols.join(', ')}.`),\n    );\n  }\n  // Both IAM and Cognito agents can be fronted. An IAM agent is invoked with\n  // the gateway's own role (GATEWAY_IAM_ROLE); a Cognito agent has the caller's\n  // JWT forwarded to it (JWT_PASSTHROUGH) so it authorizes on the token. The\n  // vended `addAgent` picks the credential from the agent's `auth`.\n  const agentAuth = (agentComponent.auth as string | undefined) ?? 'iam';\n  if (agentAuth !== 'iam' && agentAuth !== 'cognito') {\n    throw new Error(\n      `Agent '${agentComponent.name}' uses auth='${agentAuth}', which a gateway cannot front. Supported: iam, cognito.`,\n    );\n  }\n\n  // The target name must match what the deployed Gateway uses (`agentName` on\n  // the agent construct, derived from the project's class name) so the\n  // `/<target>/invocations` path resolves identically locally and deployed.\n  const agentComponentName = agentComponent.name ?? 'agent';\n  const agentTargetName = kebabCase(\n    (agentComponent.rc as string | undefined) ??\n      toClassName(agentComponentName),\n  );\n\n  await attachAgentToLocalGateway(tree, sourceProject, 'dev', {\n    targetName: agentTargetName,\n    port: (agentComponent.port as number | undefined) ?? 8081,\n    upstreamProjectName: targetProject.name,\n    upstreamDevTargetName: `${agentComponentName}-dev`,\n    // The deployed gateway maps an A2A target's `/invocations/...` paths onto\n    // the agent container's root; HTTP and AG-UI agents serve /invocations\n    // themselves.\n    stripInvocations: agentProtocol === 'a2a',\n  });\n\n  // Recorded so the version sync can identify this connection.\n  addComponentGeneratorMetadata(\n    tree,\n    sourceProject.name,\n    AGENTCORE_GATEWAY_AGENT_CONNECTION_GENERATOR_INFO,\n    targetProject.root,\n    agentTargetName,\n  );\n\n  await addGeneratorMetricsIfApplicable(tree, [\n    AGENTCORE_GATEWAY_AGENT_CONNECTION_GENERATOR_INFO,\n  ]);\n\n  await formatFilesInSubtree(tree);\n\n  return () =>\n    installDependencies(tree, options.preferInstallDependencies, {\n      languages: ['typescript'],\n    });\n};\n\nexport default agentcoreGatewayAgentConnectionGenerator;\n"],"names":["formatFilesInSubtree","installDependencies","addGeneratorMetricsIfApplicable","kebabCase","toClassName","addComponentGeneratorMetadata","getGeneratorInfo","readProjectConfigurationUnqualified","attachAgentToLocalGateway","readAgentCoreGatewayMetadata","AGENTCORE_GATEWAY_AGENT_CONNECTION_GENERATOR_INFO","filename","SUPPORTED_AGENT_PROTOCOLS","agentcoreGatewayAgentConnectionGenerator","tree","options","sourceProject","targetProject","gateway","agentComponent","targetComponent","Error","protocol","name","agentGenerator","generator","agentProtocol","toLowerCase","supportedProtocols","includes","join","agentAuth","auth","agentComponentName","agentTargetName","rc","targetName","port","upstreamProjectName","upstreamDevTargetName","stripInvocations","root","preferInstallDependencies","languages"],"mappings":"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"}

package/src/agentcore-gateway/agent-connection/schema.d.js

@@ -0,0 +1,6 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ export { };
+
+//# sourceMappingURL=schema.d.js.map

package/src/agentcore-gateway/agent-connection/schema.d.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../packages/nx-plugin/src/agentcore-gateway/agent-connection/schema.d.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport type { ComponentMetadata } from '../../utils/nx.js';\n\nexport interface AgentcoreGatewayAgentConnectionGeneratorSchema {\n  sourceProject: string;\n  targetProject: string;\n  sourceComponent?: ComponentMetadata;\n  targetComponent?: ComponentMetadata;\n  preferInstallDependencies?: boolean;\n}\n"],"names":[],"mappings":"AAAA;;;CAGC,GAGD,WAMC"}

package/src/agentcore-gateway/agent-connection/schema.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ComponentMetadata } from '../../utils/nx.js';
+
+export interface AgentcoreGatewayAgentConnectionGeneratorSchema {
+  sourceProject: string;
+  targetProject: string;
+  sourceComponent?: ComponentMetadata;
+  targetComponent?: ComponentMetadata;
+  preferInstallDependencies?: boolean;
+}

package/src/agentcore-gateway/agent-connection/schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "agentcore-gateway#agent-connection",
+  "title": "agentcore-gateway#agent-connection",
+  "description": "Connect an AgentCore Gateway to an agent, adding the agent as a gateway target",
+  "type": "object",
+  "properties": {
+    "sourceProject": {
+      "type": "string",
+      "description": "The gateway project"
+    },
+    "targetProject": {
+      "type": "string",
+      "description": "The agent project"
+    },
+    "sourceComponent": {
+      "type": "string",
+      "description": "The gateway component in the source project"
+    },
+    "targetComponent": {
+      "type": "string",
+      "description": "The agent component in the target project"
+    },
+    "preferInstallDependencies": {
+      "type": "boolean",
+      "description": "Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.",
+      "default": true
+    }
+  },
+  "required": ["sourceProject", "targetProject"]
+}

package/src/agentcore-gateway/attach-upstream.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type ProjectConfiguration, type Tree } from '@nx/devkit';
+export interface LocalGatewayUpstream {
+    /**
+     * Gateway target name for the upstream — prefixes its tools as
+     * `<targetName>___<toolName>` both locally and deployed.
+     */
+    targetName: string;
+    /**
+     * Local port the upstream MCP endpoint listens on.
+     */
+    port: number;
+    /**
+     * Project providing the upstream's dev target.
+     */
+    upstreamProjectName: string;
+    /**
+     * Name of the upstream's dev target.
+     */
+    upstreamDevTargetName: string;
+}
+/**
+ * Attach an upstream MCP endpoint (an MCP server or another gateway's local
+ * gateway) to a gateway's local gateway.
+ *
+ * Chains the gateway's dev target onto the upstream's dev target, and
+ * registers the upstream in the gateway's local-dev.ts so the local gateway
+ * aggregates its tools.
+ */
+export declare const attachUpstreamToLocalGateway: (tree: Tree, gatewayProject: ProjectConfiguration, gatewayDevTargetName: string, upstream: LocalGatewayUpstream) => Promise<void>;
+/**
+ * Attach an upstream agent to an http gateway's local gateway.
+ *
+ * Chains the gateway's dev target onto the agent's dev target, and registers
+ * the agent in the gateway's local-dev.ts so the local gateway proxies
+ * `/<targetName>/...` to it.
+ */
+export declare const attachAgentToLocalGateway: (tree: Tree, gatewayProject: ProjectConfiguration, gatewayDevTargetName: string, upstream: LocalGatewayUpstream & {
+    /**
+     * Whether to strip the `/invocations` path prefix when proxying. The
+     * deployed gateway maps an A2A target's `/invocations/...` paths onto the
+     * agent container's root, so the local proxy does the same; HTTP and
+     * AG-UI agents serve `/invocations` themselves.
+     */
+    stripInvocations: boolean;
+}) => Promise<void>;

package/src/agentcore-gateway/attach-upstream.js

@@ -0,0 +1,59 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { joinPathFragments, updateProjectConfiguration } from "@nx/devkit";
+import { applyGritQL } from "../utils/ast.js";
+import { addDependencyToTargetIfNotPresent } from "../utils/nx.js";
+/**
+ * Attach an upstream MCP endpoint (an MCP server or another gateway's local
+ * gateway) to a gateway's local gateway.
+ *
+ * Chains the gateway's dev target onto the upstream's dev target, and
+ * registers the upstream in the gateway's local-dev.ts so the local gateway
+ * aggregates its tools.
+ */ export const attachUpstreamToLocalGateway = async (tree, gatewayProject, gatewayDevTargetName, upstream)=>{
+    chainGatewayDevTarget(tree, gatewayProject, gatewayDevTargetName, upstream);
+    // Register the upstream in the gateway's local local-dev.ts
+    const serveTsPath = joinPathFragments(gatewayProject.root, 'local-dev.ts');
+    if (tree.exists(serveTsPath)) {
+        const entry = `{ name: '${upstream.targetName}', url: 'http://localhost:${upstream.port}/mcp' }`;
+        await applyGritQL(tree, serveTsPath, `or {
+  \`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = []\` => \`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = [${entry}]\`,
+  \`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = [$items]\` => \`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = [${entry}, $items]\` where {
+    $items <: not contains \`'${upstream.targetName}'\`
+  }
+}`);
+    }
+};
+/**
+ * Attach an upstream agent to an http gateway's local gateway.
+ *
+ * Chains the gateway's dev target onto the agent's dev target, and registers
+ * the agent in the gateway's local-dev.ts so the local gateway proxies
+ * `/<targetName>/...` to it.
+ */ export const attachAgentToLocalGateway = async (tree, gatewayProject, gatewayDevTargetName, upstream)=>{
+    chainGatewayDevTarget(tree, gatewayProject, gatewayDevTargetName, upstream);
+    const serveTsPath = joinPathFragments(gatewayProject.root, 'local-dev.ts');
+    if (tree.exists(serveTsPath)) {
+        const entry = `{ name: '${upstream.targetName}', url: 'http://localhost:${upstream.port}', stripInvocations: ${upstream.stripInvocations} }`;
+        await applyGritQL(tree, serveTsPath, `or {
+  \`const ATTACHED_AGENTS: AttachedAgent[] = []\` => \`const ATTACHED_AGENTS: AttachedAgent[] = [${entry}]\`,
+  \`const ATTACHED_AGENTS: AttachedAgent[] = [$items]\` => \`const ATTACHED_AGENTS: AttachedAgent[] = [${entry}, $items]\` where {
+    $items <: not contains \`'${upstream.targetName}'\`
+  }
+}`);
+    }
+};
+/** Chain the gateway's dev target onto the upstream's dev target. */ const chainGatewayDevTarget = (tree, gatewayProject, gatewayDevTargetName, upstream)=>{
+    if (gatewayProject.targets?.[gatewayDevTargetName]) {
+        addDependencyToTargetIfNotPresent(gatewayProject, gatewayDevTargetName, {
+            projects: [
+                upstream.upstreamProjectName
+            ],
+            target: upstream.upstreamDevTargetName
+        });
+        updateProjectConfiguration(tree, gatewayProject.name, gatewayProject);
+    }
+};
+
+//# sourceMappingURL=attach-upstream.js.map

package/src/agentcore-gateway/attach-upstream.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../packages/nx-plugin/src/agentcore-gateway/attach-upstream.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  joinPathFragments,\n  type ProjectConfiguration,\n  type Tree,\n  updateProjectConfiguration,\n} from '@nx/devkit';\nimport { applyGritQL } from '../utils/ast.js';\nimport { addDependencyToTargetIfNotPresent } from '../utils/nx.js';\n\nexport interface LocalGatewayUpstream {\n  /**\n   * Gateway target name for the upstream — prefixes its tools as\n   * `<targetName>___<toolName>` both locally and deployed.\n   */\n  targetName: string;\n  /**\n   * Local port the upstream MCP endpoint listens on.\n   */\n  port: number;\n  /**\n   * Project providing the upstream's dev target.\n   */\n  upstreamProjectName: string;\n  /**\n   * Name of the upstream's dev target.\n   */\n  upstreamDevTargetName: string;\n}\n\n/**\n * Attach an upstream MCP endpoint (an MCP server or another gateway's local\n * gateway) to a gateway's local gateway.\n *\n * Chains the gateway's dev target onto the upstream's dev target, and\n * registers the upstream in the gateway's local-dev.ts so the local gateway\n * aggregates its tools.\n */\nexport const attachUpstreamToLocalGateway = async (\n  tree: Tree,\n  gatewayProject: ProjectConfiguration,\n  gatewayDevTargetName: string,\n  upstream: LocalGatewayUpstream,\n): Promise<void> => {\n  chainGatewayDevTarget(tree, gatewayProject, gatewayDevTargetName, upstream);\n\n  // Register the upstream in the gateway's local local-dev.ts\n  const serveTsPath = joinPathFragments(gatewayProject.root, 'local-dev.ts');\n  if (tree.exists(serveTsPath)) {\n    const entry = `{ name: '${upstream.targetName}', url: 'http://localhost:${upstream.port}/mcp' }`;\n    await applyGritQL(\n      tree,\n      serveTsPath,\n      `or {\n  \\`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = []\\` => \\`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = [${entry}]\\`,\n  \\`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = [$items]\\` => \\`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = [${entry}, $items]\\` where {\n    $items <: not contains \\`'${upstream.targetName}'\\`\n  }\n}`,\n    );\n  }\n};\n\n/**\n * Attach an upstream agent to an http gateway's local gateway.\n *\n * Chains the gateway's dev target onto the agent's dev target, and registers\n * the agent in the gateway's local-dev.ts so the local gateway proxies\n * `/<targetName>/...` to it.\n */\nexport const attachAgentToLocalGateway = async (\n  tree: Tree,\n  gatewayProject: ProjectConfiguration,\n  gatewayDevTargetName: string,\n  upstream: LocalGatewayUpstream & {\n    /**\n     * Whether to strip the `/invocations` path prefix when proxying. The\n     * deployed gateway maps an A2A target's `/invocations/...` paths onto the\n     * agent container's root, so the local proxy does the same; HTTP and\n     * AG-UI agents serve `/invocations` themselves.\n     */\n    stripInvocations: boolean;\n  },\n): Promise<void> => {\n  chainGatewayDevTarget(tree, gatewayProject, gatewayDevTargetName, upstream);\n\n  const serveTsPath = joinPathFragments(gatewayProject.root, 'local-dev.ts');\n  if (tree.exists(serveTsPath)) {\n    const entry = `{ name: '${upstream.targetName}', url: 'http://localhost:${upstream.port}', stripInvocations: ${upstream.stripInvocations} }`;\n    await applyGritQL(\n      tree,\n      serveTsPath,\n      `or {\n  \\`const ATTACHED_AGENTS: AttachedAgent[] = []\\` => \\`const ATTACHED_AGENTS: AttachedAgent[] = [${entry}]\\`,\n  \\`const ATTACHED_AGENTS: AttachedAgent[] = [$items]\\` => \\`const ATTACHED_AGENTS: AttachedAgent[] = [${entry}, $items]\\` where {\n    $items <: not contains \\`'${upstream.targetName}'\\`\n  }\n}`,\n    );\n  }\n};\n\n/** Chain the gateway's dev target onto the upstream's dev target. */\nconst chainGatewayDevTarget = (\n  tree: Tree,\n  gatewayProject: ProjectConfiguration,\n  gatewayDevTargetName: string,\n  upstream: LocalGatewayUpstream,\n): void => {\n  if (gatewayProject.targets?.[gatewayDevTargetName]) {\n    addDependencyToTargetIfNotPresent(gatewayProject, gatewayDevTargetName, {\n      projects: [upstream.upstreamProjectName],\n      target: upstream.upstreamDevTargetName,\n    });\n    updateProjectConfiguration(tree, gatewayProject.name, gatewayProject);\n  }\n};\n"],"names":["joinPathFragments","updateProjectConfiguration","applyGritQL","addDependencyToTargetIfNotPresent","attachUpstreamToLocalGateway","tree","gatewayProject","gatewayDevTargetName","upstream","chainGatewayDevTarget","serveTsPath","root","exists","entry","targetName","port","attachAgentToLocalGateway","stripInvocations","targets","projects","upstreamProjectName","target","upstreamDevTargetName","name"],"mappings":"AAAA;;;CAGC,GACD,SACEA,iBAAiB,EAGjBC,0BAA0B,QACrB,aAAa;AACpB,SAASC,WAAW,QAAQ,kBAAkB;AAC9C,SAASC,iCAAiC,QAAQ,iBAAiB;AAsBnE;;;;;;;CAOC,GACD,OAAO,MAAMC,+BAA+B,OAC1CC,MACAC,gBACAC,sBACAC;IAEAC,sBAAsBJ,MAAMC,gBAAgBC,sBAAsBC;IAElE,4DAA4D;IAC5D,MAAME,cAAcV,kBAAkBM,eAAeK,IAAI,EAAE;IAC3D,IAAIN,KAAKO,MAAM,CAACF,cAAc;QAC5B,MAAMG,QAAQ,CAAC,SAAS,EAAEL,SAASM,UAAU,CAAC,0BAA0B,EAAEN,SAASO,IAAI,CAAC,OAAO,CAAC;QAChG,MAAMb,YACJG,MACAK,aACA,CAAC;mHAC4G,EAAEG,MAAM;yHACF,EAAEA,MAAM;8BACnG,EAAEL,SAASM,UAAU,CAAC;;CAEnD,CAAC;IAEA;AACF,EAAE;AAEF;;;;;;CAMC,GACD,OAAO,MAAME,4BAA4B,OACvCX,MACAC,gBACAC,sBACAC;IAUAC,sBAAsBJ,MAAMC,gBAAgBC,sBAAsBC;IAElE,MAAME,cAAcV,kBAAkBM,eAAeK,IAAI,EAAE;IAC3D,IAAIN,KAAKO,MAAM,CAACF,cAAc;QAC5B,MAAMG,QAAQ,CAAC,SAAS,EAAEL,SAASM,UAAU,CAAC,0BAA0B,EAAEN,SAASO,IAAI,CAAC,qBAAqB,EAAEP,SAASS,gBAAgB,CAAC,EAAE,CAAC;QAC5I,MAAMf,YACJG,MACAK,aACA,CAAC;iGAC0F,EAAEG,MAAM;uGACF,EAAEA,MAAM;8BACjF,EAAEL,SAASM,UAAU,CAAC;;CAEnD,CAAC;IAEA;AACF,EAAE;AAEF,mEAAmE,GACnE,MAAML,wBAAwB,CAC5BJ,MACAC,gBACAC,sBACAC;IAEA,IAAIF,eAAeY,OAAO,EAAE,CAACX,qBAAqB,EAAE;QAClDJ,kCAAkCG,gBAAgBC,sBAAsB;YACtEY,UAAU;gBAACX,SAASY,mBAAmB;aAAC;YACxCC,QAAQb,SAASc,qBAAqB;QACxC;QACArB,2BAA2BI,MAAMC,eAAeiB,IAAI,EAAEjB;IACxD;AACF"}