@aws/nx-plugin 1.0.0-rc.7 → 1.0.0-rc.71

package/src/utils/agent-connection/agent-connection.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-connection.js","sourceRoot":"","sources":["../../../../../../packages/nx-plugin/src/utils/agent-connection/agent-connection.ts"],"names":[],"mappings":"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"}
+{"version":3,"sources":["../../../../../../packages/nx-plugin/src/utils/agent-connection/agent-connection.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  generateFiles,\n  joinPathFragments,\n  OverwriteStrategy,\n  type Tree,\n} from '@nx/devkit';\nimport pyProjectGenerator, {\n  getPyProjectDetails,\n} from '../../py/project/generator';\nimport tsProjectGenerator from '../../ts/lib/generator';\nimport { addStarExport, applyGritQL, matchGritQL } from '../ast';\nimport {\n  type DependencyDeclaration,\n  forDependencies,\n  type MustDeclare,\n  type MustDeclarePy,\n} from '../declared-dependencies';\nimport { addDependenciesToPackageJson } from '../dependencies';\nimport { esmVars } from '../module-format';\nimport { addDependenciesToPyProjectToml } from '../py';\nimport {\n  type IPyDepVersion,\n  type ITsDepVersion,\n  withVersions,\n} from '../versions';\n\n/** TypeScript dependencies a caller must declare to emit agent-connection clients. */\nexport const AGENT_CONNECTION_DEPENDENCIES = [\n  { name: '@aws-lambda-powertools/parameters' },\n  { name: '@aws-sdk/credential-providers' },\n  { name: 'aws4fetch' },\n  { name: '@modelcontextprotocol/sdk' },\n  { name: '@a2a-js/sdk' },\n  { name: '@strands-agents/sdk' },\n] as const satisfies readonly { name: ITsDepVersion }[];\n\n/** Python dependencies a caller must declare to emit agent-connection clients. */\nexport const AGENT_CONNECTION_PY_DEPENDENCIES = [\n  { name: 'aws-lambda-powertools' },\n  { name: 'strands-agents' },\n] as const satisfies readonly { name: IPyDepVersion }[];\n\ntype AgentConnectionPyDependency =\n  (typeof AGENT_CONNECTION_PY_DEPENDENCIES)[number]['name'];\n\n/** Prefix a GritQL pattern with `language python` */\nconst py = (pattern: string) => `language python\\n${pattern}`;\n\nconst AGENT_CONNECTION_DIR = 'agent-connection';\nconst PACKAGES_DIR = 'packages';\nconst COMMON_DIR = 'common';\n\nexport const AGENT_CONNECTION_PROJECT_DIR = joinPathFragments(\n  PACKAGES_DIR,\n  COMMON_DIR,\n  AGENT_CONNECTION_DIR,\n);\n\nconst PY_AGENT_CONNECTION_NAME = 'agent_connection';\n\n/**\n * Get the directory of the shared Python agent-connection project.\n */\nexport function getPythonAgentConnectionProjectDir(tree: Tree): string {\n  const { dir } = getPyProjectDetails(tree, {\n    name: PY_AGENT_CONNECTION_NAME,\n    directory: joinPathFragments(PACKAGES_DIR, COMMON_DIR),\n  });\n  return dir;\n}\n\n/**\n * Get the Python module name of the shared agent-connection project.\n */\nexport function getPythonAgentConnectionModuleName(tree: Tree): string {\n  const { normalizedModuleName } = getPyProjectDetails(tree, {\n    name: PY_AGENT_CONNECTION_NAME,\n    directory: joinPathFragments(PACKAGES_DIR, COMMON_DIR),\n  });\n  return normalizedModuleName;\n}\n\n/**\n * Get the shared agent-connection project as `{ name, root }`, suitable for\n * passing to {@link addWorkspaceDependencyToPyProject} (which derives the\n * dependency's PEP 503 distribution name from the project itself, so callers\n * never construct the name).\n */\nexport function getPythonAgentConnectionProject(tree: Tree): {\n  name: string;\n  root: string;\n} {\n  const { fullyQualifiedName, dir } = getPyProjectDetails(tree, {\n    name: PY_AGENT_CONNECTION_NAME,\n    directory: joinPathFragments(PACKAGES_DIR, COMMON_DIR),\n  });\n  return { name: fullyQualifiedName, root: dir };\n}\n\n/**\n * The connection protocols an agent framework can connect over. Each maps to a\n * framework-agnostic Layer-0/1 template directory plus a per-framework Layer-2\n * client directory (see `FRAMEWORKS`).\n */\nexport type ConnectionProtocol = 'mcp' | 'gateway' | 'a2a';\n\n/**\n * The agent frameworks we can generate connection clients for. Adding a new\n * framework is an additive change: append an entry to `FRAMEWORKS` with its\n * Layer-2 template directories and dependencies — the framework-agnostic\n * Layer-0/1 (`core-auth`, `core-shared`, the per-protocol transports/configs)\n * is reused unchanged.\n */\nexport type AgentFramework = 'strands' | 'langchain';\n\n/**\n * Resolve an agent component's framework, defaulting to `strands`. Connection\n * generators dispatch on the returned framework to pick the matching templates\n * and agent.py/agent.ts transforms.\n */\nexport function resolveAgentFramework(\n  framework: string | undefined,\n): AgentFramework {\n  return framework === 'langchain' ? 'langchain' : 'strands';\n}\n\n/**\n * Framework-agnostic Layer-1 templates, keyed by protocol. These resolve the\n * endpoint and build the signed transport/client-config; they contain no\n * framework dependency.\n */\nconst TS_PROTOCOL_TEMPLATES: Record<ConnectionProtocol, string> = {\n  mcp: 'core-mcp',\n  gateway: 'core-gateway',\n  a2a: 'core-a2a',\n};\nconst PY_PROTOCOL_TEMPLATES: Record<ConnectionProtocol, string> = {\n  mcp: 'py-core-mcp',\n  gateway: 'py-core-gateway',\n  a2a: 'py-core-a2a',\n};\n\n/**\n * A re-export the framework base emits into the agent-connection module's\n * `__init__.py` (the agent server entry point imports these by name).\n */\ninterface BaseReExport {\n  fromModule: string;\n  importName: string;\n}\n\n/**\n * A framework's Layer-2 templates for one language. `base` (optional) holds the\n * helpers every connection of that framework needs (error logging, per-session\n * agent cache); `baseReExports` lists what those helpers expose at the module\n * root. `protocols` maps each *supported* protocol to the thin client that wraps\n * the matching Layer-1 transport/config in the framework's client type.\n *\n * A framework whose Layer-2 needs no base helpers (e.g. LangChain, whose AG-UI\n * foundation reuses only the framework-agnostic session context) omits `base`\n * and leaves `baseReExports` empty.\n *\n * A protocol absent from `protocols` is not supported by that framework in that\n * language — callers must check before emitting. `deps` are the extra package\n * dependencies the base helpers require (per-connection client deps are added\n * by the connection generators, not here).\n */\ninterface FrameworkLanguageTemplates<Dep extends string> {\n  base?: string;\n  baseReExports: BaseReExport[];\n  protocols: Partial<Record<ConnectionProtocol, string>>;\n  deps: Dep[];\n}\n\n/**\n * Per-framework Layer-2 templates. Support is asymmetric by design: a framework\n * may target only one language (`ts`/`py` is optional) and only a subset of\n * protocols. Adding a framework — or extending an existing one to a new\n * language/protocol — is an additive change to this registry.\n */\ninterface FrameworkTemplates {\n  ts?: FrameworkLanguageTemplates<string>;\n  py?: FrameworkLanguageTemplates<AgentConnectionPyDependency>;\n}\n\nconst FRAMEWORKS: Record<AgentFramework, FrameworkTemplates> = {\n  strands: {\n    ts: {\n      base: 'core-strands/base',\n      baseReExports: [\n        {\n          fromModule: './core/with-session-id-strands.js',\n          importName: '*',\n        },\n        {\n          fromModule: './core/model-errors-strands.js',\n          importName: '*',\n        },\n        {\n          fromModule: './core/tool-errors-strands.js',\n          importName: '*',\n        },\n      ],\n      protocols: {\n        mcp: 'core-strands/mcp',\n        gateway: 'core-strands/gateway',\n        a2a: 'core-strands/a2a',\n      },\n      deps: [],\n    },\n    py: {\n      base: 'py-core-strands/base',\n      baseReExports: [\n        {\n          fromModule: '.core.with_session_id_strands',\n          importName: 'with_session_id',\n        },\n        {\n          fromModule: '.core.model_errors_strands',\n          importName: 'log_model_errors',\n        },\n      ],\n      protocols: {\n        mcp: 'py-core-strands/mcp',\n        gateway: 'py-core-strands/gateway',\n        a2a: 'py-core-strands/a2a',\n      },\n      deps: ['strands-agents'],\n    },\n  },\n  langchain: {\n    // LangChain is supported for Python agents only (the TypeScript LangChain\n    // agent foundation has no in-process AG-UI <-> LangGraph adapter, so it is\n    // not scaffolded — see ts#agent). Its Layer-2 clients stay usable after\n    // agent construction, so there is no base helper layer (no model-error\n    // logger / per-session agent cache) and no strands-agents dependency — its\n    // AG-UI foundation reuses only the framework-agnostic session context, and\n    // its A2A client drives the a2a SDK directly rather than wrapping Strands'\n    // A2AAgent. The per-connection adapter dependency (langchain-mcp-adapters /\n    // a2a-sdk) is added by the connection generators.\n    py: {\n      baseReExports: [],\n      protocols: {\n        mcp: 'py-core-langchain/mcp',\n        gateway: 'py-core-langchain/gateway',\n        a2a: 'py-core-langchain/a2a',\n      },\n      deps: [],\n    },\n  },\n};\n\n/** Resolve a framework's templates for a language + protocol, or throw. */\nfunction frameworkLanguage<L extends 'ts' | 'py'>(\n  framework: AgentFramework,\n  language: L,\n  protocol: ConnectionProtocol,\n): NonNullable<FrameworkTemplates[L]> & { protocol: string } {\n  const lang = FRAMEWORKS[framework][language];\n  if (!lang) {\n    throw new Error(\n      `The '${framework}' framework does not support ${language === 'ts' ? 'TypeScript' : 'Python'} agents.`,\n    );\n  }\n  const protocolDir = lang.protocols[protocol];\n  if (!protocolDir) {\n    throw new Error(\n      `The '${framework}' framework does not support ${protocol} connections for ${language === 'ts' ? 'TypeScript' : 'Python'} agents.`,\n    );\n  }\n  return { ...lang, protocol: protocolDir } as NonNullable<\n    FrameworkTemplates[L]\n  > & { protocol: string };\n}\n\n/** Protocols whose Layer-1 needs the shared MCP transport (`core-shared`). */\nconst MCP_TRANSPORT_PROTOCOLS: ConnectionProtocol[] = ['mcp', 'gateway'];\n\nconst tsCoreDir = () =>\n  joinPathFragments(AGENT_CONNECTION_PROJECT_DIR, 'src', 'core');\n\n/**\n * Runtime dependencies each TypeScript core template directory imports. Emitting\n * a template also declares its dependencies in the agent-connection project's\n * package.json so the `noUndeclaredDependencies` lint rule passes.\n */\nconst TS_TEMPLATE_DEPS: Record<\n  string,\n  (typeof AGENT_CONNECTION_DEPENDENCIES)[number]['name'][]\n> = {\n  'core-runtime-config': ['@aws-lambda-powertools/parameters'],\n  'core-auth': ['@aws-sdk/credential-providers', 'aws4fetch'],\n  'core-shared': ['@aws-sdk/credential-providers', '@modelcontextprotocol/sdk'],\n  'core-mcp': ['@aws-sdk/credential-providers', '@modelcontextprotocol/sdk'],\n  'core-gateway': [\n    '@aws-sdk/credential-providers',\n    '@modelcontextprotocol/sdk',\n  ],\n  'core-a2a': ['@aws-sdk/credential-providers', '@a2a-js/sdk'],\n  'core-strands/base': ['@strands-agents/sdk'],\n  'core-strands/mcp': ['@strands-agents/sdk'],\n  'core-strands/gateway': ['@strands-agents/sdk'],\n  'core-strands/a2a': ['@strands-agents/sdk'],\n};\n\nconst emitTs = (\n  tree: Tree,\n  templateDir: string,\n  declaration: DependencyDeclaration,\n) => {\n  generateFiles(\n    tree,\n    joinPathFragments(import.meta.dirname, 'files', templateDir),\n    tsCoreDir(),\n    { ...esmVars(tree) },\n    { overwriteStrategy: OverwriteStrategy.KeepExisting },\n  );\n  const deps = TS_TEMPLATE_DEPS[templateDir];\n  if (deps?.length) {\n    addDependenciesToPackageJson(\n      tree,\n      withVersions(\n        forDependencies<typeof AGENT_CONNECTION_DEPENDENCIES>(declaration),\n        deps,\n      ),\n      {},\n      joinPathFragments(AGENT_CONNECTION_PROJECT_DIR, 'package.json'),\n    );\n  }\n};\n\n/**\n * Ensure the shared TypeScript agent-connection project exists and has the\n * framework-agnostic core helpers (runtime-config loader, session context).\n * Per-connection generators emit their own protocol + framework client\n * templates via `addTypeScriptCoreClient`.\n */\nexport async function ensureTypeScriptAgentConnectionProject<\n  const D extends DependencyDeclaration,\n>(\n  tree: Tree,\n  declaration: D & MustDeclare<typeof AGENT_CONNECTION_DEPENDENCIES, D>,\n): Promise<void> {\n  const projectJsonPath = joinPathFragments(\n    AGENT_CONNECTION_PROJECT_DIR,\n    'project.json',\n  );\n  if (!tree.exists(projectJsonPath)) {\n    await tsProjectGenerator(tree, {\n      name: AGENT_CONNECTION_DIR,\n      directory: joinPathFragments(PACKAGES_DIR, COMMON_DIR),\n    });\n  }\n\n  // Framework-agnostic runtime-config + session-context helpers.\n  emitTs(tree, 'core-runtime-config', declaration);\n\n  // Re-export session-context helpers so agent server entry points can set the\n  // current session on each inbound request without pulling in internals.\n  await addStarExport(\n    tree,\n    joinPathFragments(AGENT_CONNECTION_PROJECT_DIR, 'src', 'index.ts'),\n    './core/session-context.js',\n  );\n\n  // Re-export the runtime-config loader so agent server entry points can read\n  // their own connected resources (e.g. session storage) without pulling in\n  // internals.\n  await addStarExport(\n    tree,\n    joinPathFragments(AGENT_CONNECTION_PROJECT_DIR, 'src', 'index.ts'),\n    './core/runtime-config.js',\n  );\n}\n\n/**\n * Emit a framework's base Layer-2 helpers (model-error logging + per-session\n * agent cache) into the agent-connection project and re-export them. The agent\n * server entry point imports these regardless of whether any connection client\n * is wired in, so the agent generator calls this directly; connection\n * generators call it transitively via `addTypeScriptCoreClient`.\n */\nexport async function addTypeScriptFrameworkBase<\n  const D extends DependencyDeclaration,\n>(\n  tree: Tree,\n  declaration: D & MustDeclare<typeof AGENT_CONNECTION_DEPENDENCIES, D>,\n  framework: AgentFramework = 'strands',\n): Promise<void> {\n  const lang = FRAMEWORKS[framework].ts;\n  if (!lang) {\n    throw new Error(\n      `The '${framework}' framework does not support TypeScript agents.`,\n    );\n  }\n  if (lang.base) {\n    emitTs(tree, lang.base, declaration);\n  }\n\n  const indexPath = joinPathFragments(\n    AGENT_CONNECTION_PROJECT_DIR,\n    'src',\n    'index.ts',\n  );\n  for (const reExport of lang.baseReExports) {\n    await addStarExport(tree, indexPath, reExport.fromModule);\n  }\n}\n\n/**\n * Emit the TypeScript client templates for a connection protocol and agent\n * framework into the agent-connection project's `src/core/` directory. Safe to\n * call multiple times — `KeepExisting` preserves customised files.\n *\n * Layers emitted:\n *  - Layer 0 `core-auth` (signed fetch + endpoint resolution) — always\n *  - Layer 1 `core-shared` MCP transport — for mcp/gateway protocols\n *  - Layer 1 the protocol's transport/client-config — always\n *  - Layer 2 the framework's base helpers + protocol client — per framework\n */\nexport async function addTypeScriptCoreClient<\n  const D extends DependencyDeclaration,\n>(\n  tree: Tree,\n  protocol: ConnectionProtocol,\n  declaration: D & MustDeclare<typeof AGENT_CONNECTION_DEPENDENCIES, D>,\n  framework: AgentFramework = 'strands',\n): Promise<void> {\n  const fw = frameworkLanguage(framework, 'ts', protocol);\n\n  emitTs(tree, 'core-auth', declaration);\n  if (MCP_TRANSPORT_PROTOCOLS.includes(protocol)) {\n    emitTs(tree, 'core-shared', declaration);\n  }\n  emitTs(tree, TS_PROTOCOL_TEMPLATES[protocol], declaration);\n\n  // Framework Layer 2: base helpers (re-exported for the agent server) + the\n  // thin protocol client.\n  await addTypeScriptFrameworkBase(\n    tree,\n    forDependencies<typeof AGENT_CONNECTION_DEPENDENCIES>(declaration),\n    framework,\n  );\n  emitTs(tree, fw.protocol, declaration);\n}\n\n/**\n * Ensure the shared Python agent-connection project exists.\n * Only creates the project shell — per-connection generators are responsible\n * for emitting their own core client templates.\n */\nexport async function ensurePythonAgentConnectionProject<\n  const D extends DependencyDeclaration,\n>(\n  tree: Tree,\n  declaration: D & MustDeclarePy<typeof AGENT_CONNECTION_PY_DEPENDENCIES, D>,\n): Promise<void> {\n  const projectDir = getPythonAgentConnectionProjectDir(tree);\n  const moduleName = getPythonAgentConnectionModuleName(tree);\n  const projectJsonPath = joinPathFragments(projectDir, 'project.json');\n\n  if (!tree.exists(projectJsonPath)) {\n    // Create the Python project using the standard py#project generator\n    await pyProjectGenerator(tree, {\n      name: PY_AGENT_CONNECTION_NAME,\n      directory: joinPathFragments(PACKAGES_DIR, COMMON_DIR),\n      type: 'library',\n    });\n  }\n\n  const moduleDir = joinPathFragments(projectDir, moduleName);\n\n  // Ensure core/__init__.py exists\n  const coreDir = joinPathFragments(moduleDir, 'core');\n  if (!tree.exists(joinPathFragments(coreDir, '__init__.py'))) {\n    tree.write(joinPathFragments(coreDir, '__init__.py'), '');\n  }\n\n  // Ensure app/__init__.py exists\n  const appInitPath = joinPathFragments(moduleDir, 'app', '__init__.py');\n  if (!tree.exists(appInitPath)) {\n    tree.write(appInitPath, '');\n  }\n\n  // Framework-agnostic runtime-config + session-context helpers.\n  generateFiles(\n    tree,\n    joinPathFragments(import.meta.dirname, 'files', 'py-core-runtime-config'),\n    coreDir,\n    {},\n    { overwriteStrategy: OverwriteStrategy.KeepExisting },\n  );\n\n  // Re-export the session id context so agent server entry points can set the\n  // current session on each inbound request without importing internals.\n  const moduleInitPath = joinPathFragments(moduleDir, '__init__.py');\n  await addPythonReExport(\n    tree,\n    moduleInitPath,\n    '.core.session_context',\n    'get_current_session_id',\n  );\n  await addPythonReExport(\n    tree,\n    moduleInitPath,\n    '.core.session_context',\n    'session_id_context',\n  );\n\n  // The runtime-config loader reads AppConfig via aws-lambda-powertools.\n  addDependenciesToPyProjectToml(\n    tree,\n    projectDir,\n    forDependencies<[], typeof AGENT_CONNECTION_PY_DEPENDENCIES>(declaration),\n    ['aws-lambda-powertools'],\n  );\n}\n\nconst pyCoreDir = (tree: Tree) =>\n  joinPathFragments(\n    getPythonAgentConnectionProjectDir(tree),\n    getPythonAgentConnectionModuleName(tree),\n    'core',\n  );\n\nconst emitPy = (tree: Tree, templateDir: string) =>\n  generateFiles(\n    tree,\n    joinPathFragments(import.meta.dirname, 'files', templateDir),\n    pyCoreDir(tree),\n    {},\n    { overwriteStrategy: OverwriteStrategy.KeepExisting },\n  );\n\n/**\n * Emit a framework's base Layer-2 helpers (model-error logging + per-session\n * agent cache) into the Python agent-connection project and re-export them.\n * The agent server entry point imports these regardless of whether a connection\n * client is wired in, so the agent generator calls this directly; connection\n * generators call it transitively via `addPythonCoreClient`.\n */\nexport async function addPythonFrameworkBase<\n  const D extends DependencyDeclaration,\n>(\n  tree: Tree,\n  declaration: D & MustDeclarePy<typeof AGENT_CONNECTION_PY_DEPENDENCIES, D>,\n  framework: AgentFramework = 'strands',\n): Promise<void> {\n  const lang = FRAMEWORKS[framework].py;\n  if (!lang) {\n    throw new Error(\n      `The '${framework}' framework does not support Python agents.`,\n    );\n  }\n  if (lang.base) {\n    emitPy(tree, lang.base);\n  }\n\n  const moduleInitPath = joinPathFragments(\n    getPythonAgentConnectionProjectDir(tree),\n    getPythonAgentConnectionModuleName(tree),\n    '__init__.py',\n  );\n  for (const reExport of lang.baseReExports) {\n    await addPythonReExport(\n      tree,\n      moduleInitPath,\n      reExport.fromModule,\n      reExport.importName,\n    );\n  }\n\n  if (lang.deps.length > 0) {\n    addDependenciesToPyProjectToml(\n      tree,\n      getPythonAgentConnectionProjectDir(tree),\n      forDependencies<[], typeof AGENT_CONNECTION_PY_DEPENDENCIES>(declaration),\n      lang.deps,\n    );\n  }\n}\n\n/**\n * Emit the Python client templates for a connection protocol and agent\n * framework into the agent-connection project's core directory.\n *\n * Layers emitted:\n *  - Layer 0 `py-core-auth` (SigV4 httpx.Auth, session auth, endpoints) — always\n *  - Layer 1 `py-core-shared` MCP transport — for mcp/gateway protocols\n *  - Layer 1 the protocol's transport/client-config — always\n *  - Layer 2 the framework's base helpers + protocol client — per framework\n */\nexport async function addPythonCoreClient<\n  const D extends DependencyDeclaration,\n>(\n  tree: Tree,\n  protocol: ConnectionProtocol,\n  declaration: D & MustDeclarePy<typeof AGENT_CONNECTION_PY_DEPENDENCIES, D>,\n  framework: AgentFramework = 'strands',\n): Promise<void> {\n  const fw = frameworkLanguage(framework, 'py', protocol);\n\n  emitPy(tree, 'py-core-auth');\n  if (MCP_TRANSPORT_PROTOCOLS.includes(protocol)) {\n    emitPy(tree, 'py-core-shared');\n  }\n  emitPy(tree, PY_PROTOCOL_TEMPLATES[protocol]);\n\n  // Framework Layer 2: base helpers + the thin protocol client.\n  await addPythonFrameworkBase(\n    tree,\n    forDependencies<[], typeof AGENT_CONNECTION_PY_DEPENDENCIES>(declaration),\n    framework,\n  );\n  emitPy(tree, fw.protocol);\n}\n\n/**\n * Patch a TypeScript agent.ts to create a connection client and register it\n * in the Agent's tools. Used by the MCP and gateway connection generators —\n * the client class must expose a static async `create()` returning a value\n * accepted by `Agent.tools` (e.g. an `McpClient`).\n */\nexport async function addTypeScriptClientToAgent(\n  tree: Tree,\n  agentFilePath: string,\n  clientClassName: string,\n  clientVarName: string,\n): Promise<void> {\n  const clientCreationStmt = `const ${clientVarName} = await ${clientClassName}.create();`;\n\n  // Transform the arrow function that contains `new Agent`:\n  // - Expression body: wrap in block with client creation and return\n  // - Block body: prepend client creation statement\n  await applyGritQL(\n    tree,\n    agentFilePath,\n    `or { \\`async ($p) => new Agent($args)\\` => raw\\`async ($p) => {\n  ${clientCreationStmt}\n  return new Agent($args);\n}\\` where { $program <: not contains \\`${clientClassName}.create\\` }, \\`async ($p) => { $body }\\` => raw\\`async ($p) => {\n  ${clientCreationStmt}\n  $body\n}\\` where { $body <: contains \\`new Agent($_)\\`, $program <: not contains \\`${clientClassName}.create\\` } }`,\n  );\n\n  // Prepend the client to the tools array\n  await applyGritQL(\n    tree,\n    agentFilePath,\n    `\\`tools: [$items]\\` => \\`tools: [${clientVarName}, $items]\\` where { $items <: within \\`new Agent($_)\\`, $items <: not contains \\`${clientVarName}\\` }`,\n  );\n}\n\n/**\n * Patch a Python agent.py to create a context-managed connection client,\n * enter it in the `with` block around `yield Agent(...)`, and spread its\n * `list_tools_sync()` into the Agent's tools. Used by the MCP and gateway\n * connection generators — the client class must expose a static `create()`\n * returning a context manager with `list_tools_sync()` (e.g. an `MCPClient`).\n */\nasync function addPythonClientToAgent(\n  tree: Tree,\n  agentFilePath: string,\n  clientClassName: string,\n  clientVarName: string,\n): Promise<void> {\n  await addPythonClientTools(tree, agentFilePath, clientVarName);\n  await addPythonClientToGetAgent(\n    tree,\n    agentFilePath,\n    clientClassName,\n    clientVarName,\n  );\n}\n\n/**\n * Append `*<clientVarName>.list_tools_sync()` to the Agent's tools list.\n */\nconst addPythonClientTools = async (\n  tree: Tree,\n  filePath: string,\n  clientVarName: string,\n): Promise<void> => {\n  if (\n    await matchGritQL(\n      tree,\n      filePath,\n      py(`\\`${clientVarName}.list_tools_sync()\\``),\n    )\n  ) {\n    return;\n  }\n\n  await applyGritQL(\n    tree,\n    filePath,\n    py(`\\`tools=$old\\` where {\n  $old <: not contains \\`${clientVarName}\\`,\n  if ($old <: \\`[]\\`) {\n    $old => \\`[*${clientVarName}.list_tools_sync()]\\`\n  } else {\n    $old <: \\`[$items]\\` where { $items += \\`, *${clientVarName}.list_tools_sync()\\` }\n  }\n}`),\n  );\n};\n\n/**\n * Create the client in get_agent and enter it in the `with` block.\n *\n * First connection: rewrites `def get_agent` to wrap the body in a with\n * block. Subsequent connections: adds to the existing with items and\n * prepends the creation line.\n */\nconst addPythonClientToGetAgent = async (\n  tree: Tree,\n  filePath: string,\n  clientClassName: string,\n  clientVarName: string,\n): Promise<void> => {\n  if (\n    await matchGritQL(tree, filePath, py(`\\`${clientClassName}.create()\\``))\n  ) {\n    return;\n  }\n\n  // Try the \"add to existing with block\" pattern first.\n  // If it succeeds, there was already a with block from a previous connection.\n  const addedToWith = await applyGritQL(\n    tree,\n    filePath,\n    py(`\\`with ($items,): $body\\` where {\n  $items <: not contains \\`${clientVarName}\\`,\n  $items += \\`, ${clientVarName}\\`\n}`),\n  );\n\n  if (addedToWith) {\n    // Subsequent connection — prepend the creation line to the function body\n    // (a single anchor, so the line is inserted exactly once).\n    await applyGritQL(\n      tree,\n      filePath,\n      py(`\\`def get_agent($params):\n    $body\\` where {\n  $body <: contains \\`yield Agent($_)\\`,\n  $body <: not contains \\`${clientClassName}.create\\`\n} => \\`def get_agent($params):\n    ${clientVarName} = ${clientClassName}.create()\n    $body\\``),\n    );\n    return;\n  }\n\n  // First connection — wrap the existing `def get_agent` body in a single\n  // `with (<var>,):` block.\n  await applyGritQL(\n    tree,\n    filePath,\n    py(`\\`def get_agent($params):\n    $body\\` where {\n  $body <: contains \\`yield Agent($_)\\`,\n  $body <: not contains \\`${clientClassName}.create\\`\n} => \\`def get_agent($params):\n    ${clientVarName} = ${clientClassName}.create()\n    with (\n        ${clientVarName},\n    ):\n        $body\\``),\n  );\n};\n\n/**\n * Patch a LangChain agent.py to load connection tools and spread them into the\n * `create_agent(...)` tools list. Used by the MCP and gateway connection\n * generators when the source agent uses the `langchain` framework — the client\n * class must expose a static `create()` returning a `list[BaseTool]`. The tools\n * come from langchain-mcp-adapters' `MultiServerMCPClient`, which keeps the\n * connection config on each tool and opens a fresh MCP session per call, so the\n * tools stay usable after `get_agent` returns — no `with` block is needed.\n * Mirrors {@link addPythonClientToAgent} for the Strands shape.\n */\nasync function addPythonLangchainClientToAgent(\n  tree: Tree,\n  agentFilePath: string,\n  clientClassName: string,\n  clientVarName: string,\n): Promise<void> {\n  await addPythonLangchainClientTools(tree, agentFilePath, clientVarName);\n  await addPythonLangchainClientToGetAgent(\n    tree,\n    agentFilePath,\n    clientClassName,\n    clientVarName,\n  );\n}\n\n/**\n * Spread `*<clientVarName>` into the `create_agent(...)` tools list.\n *\n * Scoped via `$old <: within \\`create_agent($_)\\`` so only the agent's own\n * tools= keyword argument is touched (not an unrelated function with a\n * `tools=` parameter).\n */\nconst addPythonLangchainClientTools = async (\n  tree: Tree,\n  filePath: string,\n  clientVarName: string,\n): Promise<void> => {\n  await applyGritQL(\n    tree,\n    filePath,\n    py(`\\`tools=$old\\` where {\n  $old <: within \\`create_agent($_)\\`,\n  $old <: not contains \\`*${clientVarName}\\`,\n  if ($old <: \\`[]\\`) {\n    $old => \\`[*${clientVarName}]\\`\n  } else {\n    $old <: \\`[$items]\\` where { $items += \\`, *${clientVarName}\\` }\n  }\n}`),\n  );\n};\n\n/**\n * Prepend `<clientVarName> = <clientClassName>.create()` to the get_agent body\n * (which loads the connection's tools). No `with` block — the LangChain client\n * hands langchain-mcp-adapters a connection config, so each tool opens its own\n * MCP session per call and the tools are safe to use after get_agent returns.\n * Idempotent via the `not contains <clientClassName>.create` guard.\n */\nconst addPythonLangchainClientToGetAgent = async (\n  tree: Tree,\n  filePath: string,\n  clientClassName: string,\n  clientVarName: string,\n): Promise<void> => {\n  if (\n    await matchGritQL(tree, filePath, py(`\\`${clientClassName}.create()\\``))\n  ) {\n    return;\n  }\n\n  await applyGritQL(\n    tree,\n    filePath,\n    py(`\\`def get_agent($params):\n    $body\\` where {\n  $body <: contains \\`create_agent($_)\\`,\n  $body <: not contains \\`${clientClassName}.create\\`\n} => \\`def get_agent($params):\n    ${clientVarName} = ${clientClassName}.create()\n    $body\\``),\n  );\n};\n\n/**\n * Per-framework naming + template layout for a Python per-connection client.\n * Every py#agent connection generator (mcp, gateway, a2a) names its client\n * class `<Name>Client<suffix>`, its module `<name>_client_<suffix>`, and reads\n * the per-connection app-client template from a per-framework sub-path of its\n * own `files/` dir — all of which vary only by framework, so they live here as\n * one source of truth.\n *\n * Keyed by {@link AgentFramework} rather than a boolean so a third framework is\n * an additive entry here — never another `if (isLangchain)` branch in each\n * generator.\n */\nexport interface PyClientNaming {\n  /** Class-name suffix on the per-connection app client (`<Name>Client<suffix>`). */\n  clientClassSuffix: string;\n  /** Module/file-name suffix on the per-connection app client (`<name>_client_<suffix>`). */\n  clientModuleSuffix: string;\n  /**\n   * Sub-path, under a connection generator's `files/` dir, of the per-connection\n   * app client template for this framework. Every connection generator lays its\n   * templates out the same way, so this resolves against any of them.\n   */\n  appTemplateSubdir: string;\n}\n\nexport const PY_CLIENT_NAMING: Record<AgentFramework, PyClientNaming> = {\n  strands: {\n    clientClassSuffix: 'Strands',\n    clientModuleSuffix: 'strands',\n    appTemplateSubdir: joinPathFragments('agent-connection', 'app'),\n  },\n  langchain: {\n    clientClassSuffix: 'LangChain',\n    clientModuleSuffix: 'langchain',\n    appTemplateSubdir: joinPathFragments(\n      'langchain',\n      'agent-connection',\n      'app',\n    ),\n  },\n};\n\n/**\n * How an MCP-family connection (an MCP server or an AgentCore Gateway, both of\n * which expose tools over MCP) is wired into a Python agent of a given\n * framework. The mcp-connection and gateway-connection generators share this:\n * they differ only in the metadata of the thing being connected, not in how\n * the framework's client is shaped or spliced into agent.py. A2A connections\n * wire tools differently, so they reuse only {@link PY_CLIENT_NAMING}.\n */\nexport interface PyMcpFamilyConnection extends PyClientNaming {\n  /** Extra Python deps this framework's MCP-family client needs (beyond the shared transport). */\n  deps: IPyDepVersion[];\n  /**\n   * Splice the per-connection client into the agent's `get_agent` in agent.py.\n   * Strands enters a context-managed `MCPClient` and spreads `list_tools_sync()`;\n   * LangChain loads `BaseTool`s and spreads them into `create_agent(...)`.\n   */\n  wireClientIntoAgent: (\n    tree: Tree,\n    agentFilePath: string,\n    clientClassName: string,\n    clientVarName: string,\n  ) => Promise<void>;\n}\n\nexport const PY_MCP_FAMILY_CONNECTIONS: Record<\n  AgentFramework,\n  PyMcpFamilyConnection\n> = {\n  strands: {\n    ...PY_CLIENT_NAMING.strands,\n    deps: [],\n    wireClientIntoAgent: addPythonClientToAgent,\n  },\n  langchain: {\n    ...PY_CLIENT_NAMING.langchain,\n    // langchain-mcp-adapters backs the LangChain client; it must not pull Strands in.\n    deps: ['langchain-mcp-adapters'],\n    wireClientIntoAgent: addPythonLangchainClientToAgent,\n  },\n};\n\n/**\n * Add a re-export to the Python agent-connection module's __init__.py.\n * Equivalent to addStarExport for TS.\n * Uses `__all__` to mark re-exports as public (satisfies ruff F401).\n * Uses GritQL for AST-aware transforms where possible.\n */\nexport async function addPythonReExport(\n  tree: Tree,\n  initFilePath: string,\n  fromModule: string,\n  importName: string,\n): Promise<void> {\n  // Check if already exported\n  if (await matchGritQL(tree, initFilePath, `\\`${importName}\\``)) {\n    return;\n  }\n\n  const importLine = `from ${fromModule} import ${importName}`;\n  const allEntry = `\"${importName}\"`;\n\n  // If there's already an import from the same module, merge into its name list\n  // (ruff I001 rejects two `from X import ...` lines for the same module).\n  const mergedImport = await applyGritQL(\n    tree,\n    initFilePath,\n    py(`\\`from ${fromModule} import $names\\` where {\n  $names <: not contains \\`${importName}\\`,\n  $names += \\`, ${importName}\\`\n}`),\n  );\n\n  if (mergedImport) {\n    await applyGritQL(\n      tree,\n      initFilePath,\n      py(`\\`__all__ = [$items]\\` where { $items += \\`, ${allEntry}\\` }`),\n    );\n    return;\n  }\n\n  // Try to append import after existing import using +=\n  const appendedImport = await applyGritQL(\n    tree,\n    initFilePath,\n    py(\n      `\\`from $mod import $name\\` as $stmt where {\n  $program <: not contains \\`${importName}\\`,\n  $stmt += \\`\\n${importLine}\\`\n}`,\n    ),\n  );\n\n  if (appendedImport) {\n    // Also append to existing __all__\n    await applyGritQL(\n      tree,\n      initFilePath,\n      py(`\\`__all__ = [$items]\\` where { $items += \\`, ${allEntry}\\` }`),\n    );\n    return;\n  }\n\n  // No existing imports — first re-export. Try to anchor after docstring.\n  const anchoredImport = await applyGritQL(\n    tree,\n    initFilePath,\n    py(\n      `\\`\"\"\"Automatically generated by Nx.\"\"\"\\` as $doc => \\`$doc\\n${importLine}\\n\\n__all__ = [${allEntry}]\\``,\n    ),\n  );\n\n  if (!anchoredImport) {\n    // Completely empty file or no docstring — write directly\n    tree.write(initFilePath, `${importLine}\\n\\n__all__ = [${allEntry}]\\n`);\n  }\n}\n"],"names":["generateFiles","joinPathFragments","OverwriteStrategy","pyProjectGenerator","getPyProjectDetails","tsProjectGenerator","addStarExport","applyGritQL","matchGritQL","forDependencies","addDependenciesToPackageJson","esmVars","addDependenciesToPyProjectToml","withVersions","AGENT_CONNECTION_DEPENDENCIES","name","AGENT_CONNECTION_PY_DEPENDENCIES","py","pattern","AGENT_CONNECTION_DIR","PACKAGES_DIR","COMMON_DIR","AGENT_CONNECTION_PROJECT_DIR","PY_AGENT_CONNECTION_NAME","getPythonAgentConnectionProjectDir","tree","dir","directory","getPythonAgentConnectionModuleName","normalizedModuleName","getPythonAgentConnectionProject","fullyQualifiedName","root","resolveAgentFramework","framework","TS_PROTOCOL_TEMPLATES","mcp","gateway","a2a","PY_PROTOCOL_TEMPLATES","FRAMEWORKS","strands","ts","base","baseReExports","fromModule","importName","protocols","deps","langchain","frameworkLanguage","language","protocol","lang","Error","protocolDir","MCP_TRANSPORT_PROTOCOLS","tsCoreDir","TS_TEMPLATE_DEPS","emitTs","templateDir","declaration","dirname","overwriteStrategy","KeepExisting","length","ensureTypeScriptAgentConnectionProject","projectJsonPath","exists","addTypeScriptFrameworkBase","indexPath","reExport","addTypeScriptCoreClient","fw","includes","ensurePythonAgentConnectionProject","projectDir","moduleName","type","moduleDir","coreDir","write","appInitPath","moduleInitPath","addPythonReExport","pyCoreDir","emitPy","addPythonFrameworkBase","addPythonCoreClient","addTypeScriptClientToAgent","agentFilePath","clientClassName","clientVarName","clientCreationStmt","addPythonClientToAgent","addPythonClientTools","addPythonClientToGetAgent","filePath","addedToWith","addPythonLangchainClientToAgent","addPythonLangchainClientTools","addPythonLangchainClientToGetAgent","PY_CLIENT_NAMING","clientClassSuffix","clientModuleSuffix","appTemplateSubdir","PY_MCP_FAMILY_CONNECTIONS","wireClientIntoAgent","initFilePath","importLine","allEntry","mergedImport","appendedImport","anchoredImport"],"mappings":"AAAA;;;CAGC,GACD,SACEA,aAAa,EACbC,iBAAiB,EACjBC,iBAAiB,QAEZ,aAAa;AACpB,OAAOC,sBACLC,mBAAmB,QACd,gCAA6B;AACpC,OAAOC,wBAAwB,4BAAyB;AACxD,SAASC,aAAa,EAAEC,WAAW,EAAEC,WAAW,QAAQ,YAAS;AACjE,SAEEC,eAAe,QAGV,8BAA2B;AAClC,SAASC,4BAA4B,QAAQ,qBAAkB;AAC/D,SAASC,OAAO,QAAQ,sBAAmB;AAC3C,SAASC,8BAA8B,QAAQ,WAAQ;AACvD,SAGEC,YAAY,QACP,iBAAc;AAErB,oFAAoF,GACpF,OAAO,MAAMC,gCAAgC;IAC3C;QAAEC,MAAM;IAAoC;IAC5C;QAAEA,MAAM;IAAgC;IACxC;QAAEA,MAAM;IAAY;IACpB;QAAEA,MAAM;IAA4B;IACpC;QAAEA,MAAM;IAAc;IACtB;QAAEA,MAAM;IAAsB;CAC/B,CAAuD;AAExD,gFAAgF,GAChF,OAAO,MAAMC,mCAAmC;IAC9C;QAAED,MAAM;IAAwB;IAChC;QAAEA,MAAM;IAAiB;CAC1B,CAAuD;AAKxD,mDAAmD,GACnD,MAAME,KAAK,CAACC,UAAoB,CAAC,iBAAiB,EAAEA,SAAS;AAE7D,MAAMC,uBAAuB;AAC7B,MAAMC,eAAe;AACrB,MAAMC,aAAa;AAEnB,OAAO,MAAMC,+BAA+BrB,kBAC1CmB,cACAC,YACAF,sBACA;AAEF,MAAMI,2BAA2B;AAEjC;;CAEC,GACD,OAAO,SAASC,mCAAmCC,IAAU;IAC3D,MAAM,EAAEC,GAAG,EAAE,GAAGtB,oBAAoBqB,MAAM;QACxCV,MAAMQ;QACNI,WAAW1B,kBAAkBmB,cAAcC;IAC7C;IACA,OAAOK;AACT;AAEA;;CAEC,GACD,OAAO,SAASE,mCAAmCH,IAAU;IAC3D,MAAM,EAAEI,oBAAoB,EAAE,GAAGzB,oBAAoBqB,MAAM;QACzDV,MAAMQ;QACNI,WAAW1B,kBAAkBmB,cAAcC;IAC7C;IACA,OAAOQ;AACT;AAEA;;;;;CAKC,GACD,OAAO,SAASC,gCAAgCL,IAAU;IAIxD,MAAM,EAAEM,kBAAkB,EAAEL,GAAG,EAAE,GAAGtB,oBAAoBqB,MAAM;QAC5DV,MAAMQ;QACNI,WAAW1B,kBAAkBmB,cAAcC;IAC7C;IACA,OAAO;QAAEN,MAAMgB;QAAoBC,MAAMN;IAAI;AAC/C;AAkBA;;;;CAIC,GACD,OAAO,SAASO,sBACdC,SAA6B;IAE7B,OAAOA,cAAc,cAAc,cAAc;AACnD;AAEA;;;;CAIC,GACD,MAAMC,wBAA4D;IAChEC,KAAK;IACLC,SAAS;IACTC,KAAK;AACP;AACA,MAAMC,wBAA4D;IAChEH,KAAK;IACLC,SAAS;IACTC,KAAK;AACP;AA6CA,MAAME,aAAyD;IAC7DC,SAAS;QACPC,IAAI;YACFC,MAAM;YACNC,eAAe;gBACb;oBACEC,YAAY;oBACZC,YAAY;gBACd;gBACA;oBACED,YAAY;oBACZC,YAAY;gBACd;gBACA;oBACED,YAAY;oBACZC,YAAY;gBACd;aACD;YACDC,WAAW;gBACTX,KAAK;gBACLC,SAAS;gBACTC,KAAK;YACP;YACAU,MAAM,EAAE;QACV;QACA/B,IAAI;YACF0B,MAAM;YACNC,eAAe;gBACb;oBACEC,YAAY;oBACZC,YAAY;gBACd;gBACA;oBACED,YAAY;oBACZC,YAAY;gBACd;aACD;YACDC,WAAW;gBACTX,KAAK;gBACLC,SAAS;gBACTC,KAAK;YACP;YACAU,MAAM;gBAAC;aAAiB;QAC1B;IACF;IACAC,WAAW;QACT,0EAA0E;QAC1E,2EAA2E;QAC3E,wEAAwE;QACxE,uEAAuE;QACvE,2EAA2E;QAC3E,2EAA2E;QAC3E,2EAA2E;QAC3E,4EAA4E;QAC5E,kDAAkD;QAClDhC,IAAI;YACF2B,eAAe,EAAE;YACjBG,WAAW;gBACTX,KAAK;gBACLC,SAAS;gBACTC,KAAK;YACP;YACAU,MAAM,EAAE;QACV;IACF;AACF;AAEA,yEAAyE,GACzE,SAASE,kBACPhB,SAAyB,EACzBiB,QAAW,EACXC,QAA4B;IAE5B,MAAMC,OAAOb,UAAU,CAACN,UAAU,CAACiB,SAAS;IAC5C,IAAI,CAACE,MAAM;QACT,MAAM,IAAIC,MACR,CAAC,KAAK,EAAEpB,UAAU,6BAA6B,EAAEiB,aAAa,OAAO,eAAe,SAAS,QAAQ,CAAC;IAE1G;IACA,MAAMI,cAAcF,KAAKN,SAAS,CAACK,SAAS;IAC5C,IAAI,CAACG,aAAa;QAChB,MAAM,IAAID,MACR,CAAC,KAAK,EAAEpB,UAAU,6BAA6B,EAAEkB,SAAS,iBAAiB,EAAED,aAAa,OAAO,eAAe,SAAS,QAAQ,CAAC;IAEtI;IACA,OAAO;QAAE,GAAGE,IAAI;QAAED,UAAUG;IAAY;AAG1C;AAEA,4EAA4E,GAC5E,MAAMC,0BAAgD;IAAC;IAAO;CAAU;AAExE,MAAMC,YAAY,IAChBxD,kBAAkBqB,8BAA8B,OAAO;AAEzD;;;;CAIC,GACD,MAAMoC,mBAGF;IACF,uBAAuB;QAAC;KAAoC;IAC5D,aAAa;QAAC;QAAiC;KAAY;IAC3D,eAAe;QAAC;QAAiC;KAA4B;IAC7E,YAAY;QAAC;QAAiC;KAA4B;IAC1E,gBAAgB;QACd;QACA;KACD;IACD,YAAY;QAAC;QAAiC;KAAc;IAC5D,qBAAqB;QAAC;KAAsB;IAC5C,oBAAoB;QAAC;KAAsB;IAC3C,wBAAwB;QAAC;KAAsB;IAC/C,oBAAoB;QAAC;KAAsB;AAC7C;AAEA,MAAMC,SAAS,CACblC,MACAmC,aACAC;IAEA7D,cACEyB,MACAxB,kBAAkB,YAAY6D,OAAO,EAAE,SAASF,cAChDH,aACA;QAAE,GAAG9C,QAAQc,KAAK;IAAC,GACnB;QAAEsC,mBAAmB7D,kBAAkB8D,YAAY;IAAC;IAEtD,MAAMhB,OAAOU,gBAAgB,CAACE,YAAY;IAC1C,IAAIZ,MAAMiB,QAAQ;QAChBvD,6BACEe,MACAZ,aACEJ,gBAAsDoD,cACtDb,OAEF,CAAC,GACD/C,kBAAkBqB,8BAA8B;IAEpD;AACF;AAEA;;;;;CAKC,GACD,OAAO,eAAe4C,uCAGpBzC,IAAU,EACVoC,WAAqE;IAErE,MAAMM,kBAAkBlE,kBACtBqB,8BACA;IAEF,IAAI,CAACG,KAAK2C,MAAM,CAACD,kBAAkB;QACjC,MAAM9D,mBAAmBoB,MAAM;YAC7BV,MAAMI;YACNQ,WAAW1B,kBAAkBmB,cAAcC;QAC7C;IACF;IAEA,+DAA+D;IAC/DsC,OAAOlC,MAAM,uBAAuBoC;IAEpC,6EAA6E;IAC7E,wEAAwE;IACxE,MAAMvD,cACJmB,MACAxB,kBAAkBqB,8BAA8B,OAAO,aACvD;IAGF,4EAA4E;IAC5E,0EAA0E;IAC1E,aAAa;IACb,MAAMhB,cACJmB,MACAxB,kBAAkBqB,8BAA8B,OAAO,aACvD;AAEJ;AAEA;;;;;;CAMC,GACD,OAAO,eAAe+C,2BAGpB5C,IAAU,EACVoC,WAAqE,EACrE3B,YAA4B,SAAS;IAErC,MAAMmB,OAAOb,UAAU,CAACN,UAAU,CAACQ,EAAE;IACrC,IAAI,CAACW,MAAM;QACT,MAAM,IAAIC,MACR,CAAC,KAAK,EAAEpB,UAAU,+CAA+C,CAAC;IAEtE;IACA,IAAImB,KAAKV,IAAI,EAAE;QACbgB,OAAOlC,MAAM4B,KAAKV,IAAI,EAAEkB;IAC1B;IAEA,MAAMS,YAAYrE,kBAChBqB,8BACA,OACA;IAEF,KAAK,MAAMiD,YAAYlB,KAAKT,aAAa,CAAE;QACzC,MAAMtC,cAAcmB,MAAM6C,WAAWC,SAAS1B,UAAU;IAC1D;AACF;AAEA;;;;;;;;;;CAUC,GACD,OAAO,eAAe2B,wBAGpB/C,IAAU,EACV2B,QAA4B,EAC5BS,WAAqE,EACrE3B,YAA4B,SAAS;IAErC,MAAMuC,KAAKvB,kBAAkBhB,WAAW,MAAMkB;IAE9CO,OAAOlC,MAAM,aAAaoC;IAC1B,IAAIL,wBAAwBkB,QAAQ,CAACtB,WAAW;QAC9CO,OAAOlC,MAAM,eAAeoC;IAC9B;IACAF,OAAOlC,MAAMU,qBAAqB,CAACiB,SAAS,EAAES;IAE9C,2EAA2E;IAC3E,wBAAwB;IACxB,MAAMQ,2BACJ5C,MACAhB,gBAAsDoD,cACtD3B;IAEFyB,OAAOlC,MAAMgD,GAAGrB,QAAQ,EAAES;AAC5B;AAEA;;;;CAIC,GACD,OAAO,eAAec,mCAGpBlD,IAAU,EACVoC,WAA0E;IAE1E,MAAMe,aAAapD,mCAAmCC;IACtD,MAAMoD,aAAajD,mCAAmCH;IACtD,MAAM0C,kBAAkBlE,kBAAkB2E,YAAY;IAEtD,IAAI,CAACnD,KAAK2C,MAAM,CAACD,kBAAkB;QACjC,oEAAoE;QACpE,MAAMhE,mBAAmBsB,MAAM;YAC7BV,MAAMQ;YACNI,WAAW1B,kBAAkBmB,cAAcC;YAC3CyD,MAAM;QACR;IACF;IAEA,MAAMC,YAAY9E,kBAAkB2E,YAAYC;IAEhD,iCAAiC;IACjC,MAAMG,UAAU/E,kBAAkB8E,WAAW;IAC7C,IAAI,CAACtD,KAAK2C,MAAM,CAACnE,kBAAkB+E,SAAS,iBAAiB;QAC3DvD,KAAKwD,KAAK,CAAChF,kBAAkB+E,SAAS,gBAAgB;IACxD;IAEA,gCAAgC;IAChC,MAAME,cAAcjF,kBAAkB8E,WAAW,OAAO;IACxD,IAAI,CAACtD,KAAK2C,MAAM,CAACc,cAAc;QAC7BzD,KAAKwD,KAAK,CAACC,aAAa;IAC1B;IAEA,+DAA+D;IAC/DlF,cACEyB,MACAxB,kBAAkB,YAAY6D,OAAO,EAAE,SAAS,2BAChDkB,SACA,CAAC,GACD;QAAEjB,mBAAmB7D,kBAAkB8D,YAAY;IAAC;IAGtD,4EAA4E;IAC5E,uEAAuE;IACvE,MAAMmB,iBAAiBlF,kBAAkB8E,WAAW;IACpD,MAAMK,kBACJ3D,MACA0D,gBACA,yBACA;IAEF,MAAMC,kBACJ3D,MACA0D,gBACA,yBACA;IAGF,uEAAuE;IACvEvE,+BACEa,MACAmD,YACAnE,gBAA6DoD,cAC7D;QAAC;KAAwB;AAE7B;AAEA,MAAMwB,YAAY,CAAC5D,OACjBxB,kBACEuB,mCAAmCC,OACnCG,mCAAmCH,OACnC;AAGJ,MAAM6D,SAAS,CAAC7D,MAAYmC,cAC1B5D,cACEyB,MACAxB,kBAAkB,YAAY6D,OAAO,EAAE,SAASF,cAChDyB,UAAU5D,OACV,CAAC,GACD;QAAEsC,mBAAmB7D,kBAAkB8D,YAAY;IAAC;AAGxD;;;;;;CAMC,GACD,OAAO,eAAeuB,uBAGpB9D,IAAU,EACVoC,WAA0E,EAC1E3B,YAA4B,SAAS;IAErC,MAAMmB,OAAOb,UAAU,CAACN,UAAU,CAACjB,EAAE;IACrC,IAAI,CAACoC,MAAM;QACT,MAAM,IAAIC,MACR,CAAC,KAAK,EAAEpB,UAAU,2CAA2C,CAAC;IAElE;IACA,IAAImB,KAAKV,IAAI,EAAE;QACb2C,OAAO7D,MAAM4B,KAAKV,IAAI;IACxB;IAEA,MAAMwC,iBAAiBlF,kBACrBuB,mCAAmCC,OACnCG,mCAAmCH,OACnC;IAEF,KAAK,MAAM8C,YAAYlB,KAAKT,aAAa,CAAE;QACzC,MAAMwC,kBACJ3D,MACA0D,gBACAZ,SAAS1B,UAAU,EACnB0B,SAASzB,UAAU;IAEvB;IAEA,IAAIO,KAAKL,IAAI,CAACiB,MAAM,GAAG,GAAG;QACxBrD,+BACEa,MACAD,mCAAmCC,OACnChB,gBAA6DoD,cAC7DR,KAAKL,IAAI;IAEb;AACF;AAEA;;;;;;;;;CASC,GACD,OAAO,eAAewC,oBAGpB/D,IAAU,EACV2B,QAA4B,EAC5BS,WAA0E,EAC1E3B,YAA4B,SAAS;IAErC,MAAMuC,KAAKvB,kBAAkBhB,WAAW,MAAMkB;IAE9CkC,OAAO7D,MAAM;IACb,IAAI+B,wBAAwBkB,QAAQ,CAACtB,WAAW;QAC9CkC,OAAO7D,MAAM;IACf;IACA6D,OAAO7D,MAAMc,qBAAqB,CAACa,SAAS;IAE5C,8DAA8D;IAC9D,MAAMmC,uBACJ9D,MACAhB,gBAA6DoD,cAC7D3B;IAEFoD,OAAO7D,MAAMgD,GAAGrB,QAAQ;AAC1B;AAEA;;;;;CAKC,GACD,OAAO,eAAeqC,2BACpBhE,IAAU,EACViE,aAAqB,EACrBC,eAAuB,EACvBC,aAAqB;IAErB,MAAMC,qBAAqB,CAAC,MAAM,EAAED,cAAc,SAAS,EAAED,gBAAgB,UAAU,CAAC;IAExF,0DAA0D;IAC1D,mEAAmE;IACnE,kDAAkD;IAClD,MAAMpF,YACJkB,MACAiE,eACA,CAAC;EACH,EAAEG,mBAAmB;;uCAEgB,EAAEF,gBAAgB;EACvD,EAAEE,mBAAmB;;4EAEqD,EAAEF,gBAAgB,aAAa,CAAC;IAG1G,wCAAwC;IACxC,MAAMpF,YACJkB,MACAiE,eACA,CAAC,iCAAiC,EAAEE,cAAc,iFAAiF,EAAEA,cAAc,IAAI,CAAC;AAE5J;AAEA;;;;;;CAMC,GACD,eAAeE,uBACbrE,IAAU,EACViE,aAAqB,EACrBC,eAAuB,EACvBC,aAAqB;IAErB,MAAMG,qBAAqBtE,MAAMiE,eAAeE;IAChD,MAAMI,0BACJvE,MACAiE,eACAC,iBACAC;AAEJ;AAEA;;CAEC,GACD,MAAMG,uBAAuB,OAC3BtE,MACAwE,UACAL;IAEA,IACE,MAAMpF,YACJiB,MACAwE,UACAhF,GAAG,CAAC,EAAE,EAAE2E,cAAc,oBAAoB,CAAC,IAE7C;QACA;IACF;IAEA,MAAMrF,YACJkB,MACAwE,UACAhF,GAAG,CAAC;yBACiB,EAAE2E,cAAc;;gBAEzB,EAAEA,cAAc;;gDAEgB,EAAEA,cAAc;;CAE/D,CAAC;AAEF;AAEA;;;;;;CAMC,GACD,MAAMI,4BAA4B,OAChCvE,MACAwE,UACAN,iBACAC;IAEA,IACE,MAAMpF,YAAYiB,MAAMwE,UAAUhF,GAAG,CAAC,EAAE,EAAE0E,gBAAgB,WAAW,CAAC,IACtE;QACA;IACF;IAEA,sDAAsD;IACtD,6EAA6E;IAC7E,MAAMO,cAAc,MAAM3F,YACxBkB,MACAwE,UACAhF,GAAG,CAAC;2BACmB,EAAE2E,cAAc;gBAC3B,EAAEA,cAAc;CAC/B,CAAC;IAGA,IAAIM,aAAa;QACf,yEAAyE;QACzE,2DAA2D;QAC3D,MAAM3F,YACJkB,MACAwE,UACAhF,GAAG,CAAC;;;0BAGgB,EAAE0E,gBAAgB;;IAExC,EAAEC,cAAc,GAAG,EAAED,gBAAgB;WAC9B,CAAC;QAER;IACF;IAEA,wEAAwE;IACxE,0BAA0B;IAC1B,MAAMpF,YACJkB,MACAwE,UACAhF,GAAG,CAAC;;;0BAGkB,EAAE0E,gBAAgB;;IAExC,EAAEC,cAAc,GAAG,EAAED,gBAAgB;;QAEjC,EAAEC,cAAc;;eAET,CAAC;AAEhB;AAEA;;;;;;;;;CASC,GACD,eAAeO,gCACb1E,IAAU,EACViE,aAAqB,EACrBC,eAAuB,EACvBC,aAAqB;IAErB,MAAMQ,8BAA8B3E,MAAMiE,eAAeE;IACzD,MAAMS,mCACJ5E,MACAiE,eACAC,iBACAC;AAEJ;AAEA;;;;;;CAMC,GACD,MAAMQ,gCAAgC,OACpC3E,MACAwE,UACAL;IAEA,MAAMrF,YACJkB,MACAwE,UACAhF,GAAG,CAAC;;0BAEkB,EAAE2E,cAAc;;gBAE1B,EAAEA,cAAc;;gDAEgB,EAAEA,cAAc;;CAE/D,CAAC;AAEF;AAEA;;;;;;CAMC,GACD,MAAMS,qCAAqC,OACzC5E,MACAwE,UACAN,iBACAC;IAEA,IACE,MAAMpF,YAAYiB,MAAMwE,UAAUhF,GAAG,CAAC,EAAE,EAAE0E,gBAAgB,WAAW,CAAC,IACtE;QACA;IACF;IAEA,MAAMpF,YACJkB,MACAwE,UACAhF,GAAG,CAAC;;;0BAGkB,EAAE0E,gBAAgB;;IAExC,EAAEC,cAAc,GAAG,EAAED,gBAAgB;WAC9B,CAAC;AAEZ;AA2BA,OAAO,MAAMW,mBAA2D;IACtE7D,SAAS;QACP8D,mBAAmB;QACnBC,oBAAoB;QACpBC,mBAAmBxG,kBAAkB,oBAAoB;IAC3D;IACAgD,WAAW;QACTsD,mBAAmB;QACnBC,oBAAoB;QACpBC,mBAAmBxG,kBACjB,aACA,oBACA;IAEJ;AACF,EAAE;AA0BF,OAAO,MAAMyG,4BAGT;IACFjE,SAAS;QACP,GAAG6D,iBAAiB7D,OAAO;QAC3BO,MAAM,EAAE;QACR2D,qBAAqBb;IACvB;IACA7C,WAAW;QACT,GAAGqD,iBAAiBrD,SAAS;QAC7B,kFAAkF;QAClFD,MAAM;YAAC;SAAyB;QAChC2D,qBAAqBR;IACvB;AACF,EAAE;AAEF;;;;;CAKC,GACD,OAAO,eAAef,kBACpB3D,IAAU,EACVmF,YAAoB,EACpB/D,UAAkB,EAClBC,UAAkB;IAElB,4BAA4B;IAC5B,IAAI,MAAMtC,YAAYiB,MAAMmF,cAAc,CAAC,EAAE,EAAE9D,WAAW,EAAE,CAAC,GAAG;QAC9D;IACF;IAEA,MAAM+D,aAAa,CAAC,KAAK,EAAEhE,WAAW,QAAQ,EAAEC,YAAY;IAC5D,MAAMgE,WAAW,CAAC,CAAC,EAAEhE,WAAW,CAAC,CAAC;IAElC,8EAA8E;IAC9E,yEAAyE;IACzE,MAAMiE,eAAe,MAAMxG,YACzBkB,MACAmF,cACA3F,GAAG,CAAC,OAAO,EAAE4B,WAAW;2BACD,EAAEC,WAAW;gBACxB,EAAEA,WAAW;CAC5B,CAAC;IAGA,IAAIiE,cAAc;QAChB,MAAMxG,YACJkB,MACAmF,cACA3F,GAAG,CAAC,6CAA6C,EAAE6F,SAAS,IAAI,CAAC;QAEnE;IACF;IAEA,sDAAsD;IACtD,MAAME,iBAAiB,MAAMzG,YAC3BkB,MACAmF,cACA3F,GACE,CAAC;6BACsB,EAAE6B,WAAW;eAC3B,EAAE+D,WAAW;CAC3B,CAAC;IAIA,IAAIG,gBAAgB;QAClB,kCAAkC;QAClC,MAAMzG,YACJkB,MACAmF,cACA3F,GAAG,CAAC,6CAA6C,EAAE6F,SAAS,IAAI,CAAC;QAEnE;IACF;IAEA,wEAAwE;IACxE,MAAMG,iBAAiB,MAAM1G,YAC3BkB,MACAmF,cACA3F,GACE,CAAC,4DAA4D,EAAE4F,WAAW,eAAe,EAAEC,SAAS,GAAG,CAAC;IAI5G,IAAI,CAACG,gBAAgB;QACnB,yDAAyD;QACzDxF,KAAKwD,KAAK,CAAC2B,cAAc,GAAGC,WAAW,eAAe,EAAEC,SAAS,GAAG,CAAC;IACvE;AACF"}

package/src/utils/agent-connection/files/core-a2a/agentcore-a2a-client-config.ts.template

@@ -0,0 +1,93 @@
+import {
+  ClientFactory,
+  ClientFactoryOptions,
+  DefaultAgentCardResolver,
+  JsonRpcTransportFactory,
+} from '@a2a-js/sdk/client';
+import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
+import { a2aUrlFromArn, regionFromArn } from './agentcore-endpoints<% if (esm) { %>.js<% } %>';
+import {
+  createJwtFetch,
+  createPlainFetch,
+  createSigV4Fetch,
+} from './agentcore-fetch<% if (esm) { %>.js<% } %>';
+
+/** Common options for resolving an AgentCore A2A endpoint. */
+export interface AgentCoreA2aClientConfigOptions {
+  /** The ARN of the Bedrock AgentCore Runtime to connect to. */
+  agentRuntimeArn: string;
+}
+
+/** Options for an A2A client config with IAM authentication. */
+export interface AgentCoreA2aClientConfigIamOptions
+  extends AgentCoreA2aClientConfigOptions {
+  /** AWS credential provider; defaults to the standard provider chain. */
+  credentialProvider?: ReturnType<typeof fromNodeProviderChain>;
+}
+
+/** Options for an A2A client config with JWT authentication. */
+export interface AgentCoreA2aClientConfigJwtOptions
+  extends AgentCoreA2aClientConfigOptions {
+  /** A function which returns the JWT access token used to authenticate. */
+  accessTokenProvider: () => Promise<string>;
+}
+
+/** Options for an A2A client config with no auth (local dev). */
+export interface AgentCoreA2aClientConfigNoAuthOptions {
+  /** Full URL of the local A2A endpoint. */
+  url: string;
+}
+
+/** A resolved A2A endpoint and a configured `@a2a-js` client factory. */
+export interface A2aClientConfig {
+  /** The A2A endpoint URL. */
+  url: string;
+  /** A client factory wired with a signed, session-forwarding fetch. */
+  clientFactory: ClientFactory;
+}
+
+const build = (url: string, fetchFn: typeof fetch): A2aClientConfig => {
+  const clientFactory = new ClientFactory({
+    ...ClientFactoryOptions.default,
+    transports: [new JsonRpcTransportFactory({ fetchImpl: fetchFn })],
+    cardResolver: new DefaultAgentCardResolver({ fetchImpl: fetchFn }),
+  });
+  return { url, clientFactory };
+};
+
+/**
+ * Factory for A2A client configs that connect to a Bedrock AgentCore runtime.
+ * Each forwards the current async-context session via the AgentCore session
+ * header. Framework-agnostic — wrap the result in a framework's A2A client.
+ */
+export class AgentCoreA2aClientConfig {
+  /** SigV4-authenticated A2A client config for a Bedrock AgentCore runtime. */
+  static withIamAuth(
+    options: AgentCoreA2aClientConfigIamOptions,
+  ): A2aClientConfig {
+    return build(
+      a2aUrlFromArn(options.agentRuntimeArn),
+      createSigV4Fetch({
+        region: regionFromArn(options.agentRuntimeArn),
+        credentialProvider: options.credentialProvider,
+      }),
+    );
+  }
+
+  /** Bearer-authenticated A2A client config for a Bedrock AgentCore runtime. */
+  static withJwtAuth(
+    options: AgentCoreA2aClientConfigJwtOptions,
+  ): A2aClientConfig {
+    return build(
+      a2aUrlFromArn(options.agentRuntimeArn),
+      createJwtFetch(options.accessTokenProvider),
+    );
+  }
+
+  /** For local dev — plain HTTP, no auth. */
+  static withoutAuth(
+    options: AgentCoreA2aClientConfigNoAuthOptions,
+  ): A2aClientConfig {
+    return build(options.url, createPlainFetch());
+  }
+}

package/src/utils/agent-connection/files/core-auth/agentcore-endpoints.ts.template

@@ -0,0 +1,37 @@
+/**
+ * Resolve Bedrock AgentCore invocation endpoints from a runtime ARN.
+ * Framework-agnostic — reusable by any framework's connection client.
+ */
+
+/** Extract the AWS region from a Bedrock AgentCore runtime ARN. */
+export const regionFromArn = (agentRuntimeArn: string): string =>
+  agentRuntimeArn.split(':')[3];
+
+/**
+ * The MCP invocation URL for a runtime ARN.
+ * ARN format: arn:partition:service:region:account-id:resource
+ */
+export const mcpUrlFromArn = (agentRuntimeArn: string): string => {
+  const region = regionFromArn(agentRuntimeArn);
+  return `https://bedrock-agentcore.${region}.amazonaws.com/runtimes/${encodeURIComponent(agentRuntimeArn)}/invocations?qualifier=DEFAULT`;
+};
+
+/**
+ * The A2A invocation URL for a runtime ARN. A2A on AgentCore is mounted at the
+ * `/invocations/` root (trailing slash matters).
+ */
+export const a2aUrlFromArn = (agentRuntimeArn: string): string => {
+  const region = regionFromArn(agentRuntimeArn);
+  return `https://bedrock-agentcore.${region}.amazonaws.com/runtimes/${encodeURIComponent(agentRuntimeArn)}/invocations/`;
+};
+
+/** Extract the AWS region from an AgentCore Gateway MCP URL. */
+export const regionFromGatewayUrl = (gatewayUrl: string): string => {
+  const match = /\.bedrock-agentcore\.([^.]+)\.amazonaws\.com/.exec(gatewayUrl);
+  if (!match) {
+    throw new Error(
+      `Cannot determine region from gateway URL '${gatewayUrl}'. Pass region explicitly.`,
+    );
+  }
+  return match[1];
+};

package/src/utils/agent-connection/files/core-auth/agentcore-fetch.ts.template

@@ -0,0 +1,54 @@
+import { AwsClient } from 'aws4fetch';
+import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
+import { getCurrentSessionId } from './session-context<% if (esm) { %>.js<% } %>';
+
+const SESSION_HEADER = 'X-Amzn-Bedrock-AgentCore-Runtime-Session-Id';
+
+/** Wrap a fetch so each request carries the current async-context session id. */
+const withSessionHeader =
+  (inner: typeof fetch): typeof fetch =>
+  async (input, init) => {
+    const headers = new Headers(init?.headers);
+    const sessionId = getCurrentSessionId();
+    if (sessionId) headers.set(SESSION_HEADER, sessionId);
+    return inner(input, { ...init, headers });
+  };
+
+/** Options for a SigV4-signing fetch. */
+export interface SigV4FetchOptions {
+  /** AWS region to sign for. */
+  region: string;
+  /** AWS service to sign for. Defaults to `bedrock-agentcore`. */
+  service?: string;
+  /** AWS credential provider; defaults to the standard provider chain. */
+  credentialProvider?: ReturnType<typeof fromNodeProviderChain>;
+}
+
+/** A fetch that signs every request with AWS SigV4 (per-request, body-aware). */
+export const createSigV4Fetch = (options: SigV4FetchOptions): typeof fetch => {
+  const { region, service = 'bedrock-agentcore' } = options;
+  const credentialProvider =
+    options.credentialProvider ?? fromNodeProviderChain();
+  const signedFetch: typeof fetch = async (...args) => {
+    const client = new AwsClient({
+      ...(await credentialProvider()),
+      service,
+      region,
+    });
+    return client.fetch(...args);
+  };
+  return withSessionHeader(signedFetch);
+};
+
+/** A fetch that adds a bearer token from the given async provider. */
+export const createJwtFetch = (
+  accessTokenProvider: () => Promise<string>,
+): typeof fetch =>
+  withSessionHeader(async (input, init) => {
+    const headers = new Headers(init?.headers);
+    headers.set('Authorization', `Bearer ${await accessTokenProvider()}`);
+    return fetch(input, { ...init, headers });
+  });
+
+/** A plain fetch (local dev) that still forwards the session id. */
+export const createPlainFetch = (): typeof fetch => withSessionHeader(fetch);

package/src/utils/agent-connection/files/core-gateway/agentcore-gateway-mcp-transport.ts.template

@@ -0,0 +1,41 @@
+import type { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
+import { regionFromGatewayUrl } from './agentcore-endpoints<% if (esm) { %>.js<% } %>';
+import { sigV4Transport, noAuthTransport } from './agentcore-transport<% if (esm) { %>.js<% } %>';
+
+export interface AgentCoreGatewayMcpTransportIamOptions {
+  /**
+   * The MCP URL of the AgentCore Gateway, of the form
+   * https://<gatewayId>.gateway.bedrock-agentcore.<region>.amazonaws.com/mcp
+   */
+  gatewayUrl: string;
+  /** AWS region override; by default parsed from `gatewayUrl`. */
+  region?: string;
+  /** AWS credential provider; defaults to the standard provider chain. */
+  credentialProvider?: ReturnType<typeof fromNodeProviderChain>;
+}
+
+/**
+ * Factory for MCP transports that connect to an AgentCore Gateway. Forwards the
+ * current async-context session via the AgentCore session header, which the
+ * gateway propagates to downstream MCP server targets.
+ */
+export class AgentCoreGatewayMcpTransport {
+  /** Create a gateway MCP transport authenticated with IAM SigV4. */
+  static withIamAuth(
+    options: AgentCoreGatewayMcpTransportIamOptions,
+  ): StreamableHTTPClientTransport {
+    return sigV4Transport({
+      region: options.region ?? regionFromGatewayUrl(options.gatewayUrl),
+      url: options.gatewayUrl,
+      credentialProvider: options.credentialProvider,
+    });
+  }
+
+  /** Plain-HTTP gateway transport, for the local gateway started by the dev target. */
+  static withoutAuth(options: {
+    gatewayUrl: string;
+  }): StreamableHTTPClientTransport {
+    return noAuthTransport({ url: options.gatewayUrl });
+  }
+}

package/src/utils/agent-connection/files/core-mcp/agentcore-mcp-transport.ts.template

@@ -0,0 +1,70 @@
+import type { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
+import {
+  mcpUrlFromArn,
+  regionFromArn,
+} from './agentcore-endpoints<% if (esm) { %>.js<% } %>';
+import {
+  sigV4Transport,
+  jwtTransport,
+  noAuthTransport,
+} from './agentcore-transport<% if (esm) { %>.js<% } %>';
+
+/**
+ * Options for an MCP transport with IAM authentication.
+ */
+export interface AgentCoreMcpTransportIamOptions {
+  /** The ARN of the Bedrock AgentCore Runtime to connect to. */
+  agentRuntimeArn: string;
+  /** AWS credential provider; defaults to the standard provider chain. */
+  credentialProvider?: ReturnType<typeof fromNodeProviderChain>;
+}
+
+/**
+ * Options for an MCP transport with JWT authentication.
+ */
+export interface AgentCoreMcpTransportJwtOptions {
+  /** The ARN of the Bedrock AgentCore Runtime to connect to. */
+  agentRuntimeArn: string;
+  /** A function which returns the JWT access token used to authenticate. */
+  accessTokenProvider: () => Promise<string>;
+}
+
+/**
+ * Options for an MCP transport with no auth (local dev).
+ */
+export interface AgentCoreMcpTransportNoAuthOptions {
+  /** Full URL of the local MCP endpoint. */
+  url: string;
+}
+
+/** Factory for MCP transports that connect to a Bedrock AgentCore runtime. */
+export class AgentCoreMcpTransport {
+  /** SigV4-authenticated transport for a Bedrock AgentCore runtime. */
+  static withIamAuth(
+    options: AgentCoreMcpTransportIamOptions,
+  ): StreamableHTTPClientTransport {
+    return sigV4Transport({
+      region: regionFromArn(options.agentRuntimeArn),
+      url: mcpUrlFromArn(options.agentRuntimeArn),
+      credentialProvider: options.credentialProvider,
+    });
+  }
+
+  /** Bearer-authenticated transport for a Bedrock AgentCore runtime. */
+  static withJwtAuth(
+    options: AgentCoreMcpTransportJwtOptions,
+  ): StreamableHTTPClientTransport {
+    return jwtTransport({
+      url: mcpUrlFromArn(options.agentRuntimeArn),
+      accessTokenProvider: options.accessTokenProvider,
+    });
+  }
+
+  /** For local dev — plain HTTP, no auth. */
+  static withoutAuth(
+    options: AgentCoreMcpTransportNoAuthOptions,
+  ): StreamableHTTPClientTransport {
+    return noAuthTransport({ url: options.url });
+  }
+}

package/src/utils/agent-connection/files/core-runtime-config/runtime-config.ts.template

@@ -1,40 +1,40 @@
 import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';
 
+/** An agent or MCP server runtime registered in AppConfig. */
+export interface AgentRuntimeEntry {
+  arn: string;
+  /** Session storage details. Only set when the agent has S3 session storage configured. */
+  session?: {
+    /** Name of the S3 bucket storing session data. */
+    bucketName: string;
+  };
+}
+
 /**
- * Read the runtime-config `agentcore` namespace from AppConfig.
- * `RUNTIME_CONFIG_APP_ID` is set on the AgentCore runtime by the generated
- * CDK/Terraform construct for this project.
+ * Shape of this project's runtime configuration in AppConfig. Keys are the
+ * class names of connected target constructs (e.g. `MyAgent`, `MyGateway`).
  */
-const getAgentCoreRuntimeConfig = async (): Promise<{
-  agentRuntimes?: Record<string, string>;
-}> => {
-  const application = process.env.RUNTIME_CONFIG_APP_ID;
-  if (!application) {
-    throw new Error(
-      'RUNTIME_CONFIG_APP_ID is not set — cannot resolve connected agent ARNs from AppConfig.',
-    );
-  }
-  return (await getAppConfig('agentcore', {
-    application,
-    environment: 'default',
-    transform: 'json',
-  })) as { agentRuntimes?: Record<string, string> };
-};
+export interface AgentCoreRuntimeConfig {
+  agentRuntimes?: Record<string, AgentRuntimeEntry>;
+  gateways?: Record<string, string>;
+}
 
 /**
- * Resolve the AgentCore runtime ARN for a connected agent or MCP server
- * from this project's runtime configuration. `name` must match the class
- * name of the target construct (e.g. `MyAgent`, `InventoryMcpServer`).
+ * Read the runtime-config `agentcore` namespace from AppConfig.
+ * `RUNTIME_CONFIG_APP_ID` is set on the AgentCore runtime by the generated
+ * CDK/Terraform construct for this project.
  */
-export const getConnectedAgentRuntimeArn = async (
-  name: string,
-): Promise<string> => {
-  const config = await getAgentCoreRuntimeConfig();
-  const arn = config.agentRuntimes?.[name];
-  if (!arn) {
-    throw new Error(
-      `No connected agent runtime named '${name}' found in runtime configuration.`,
-    );
-  }
-  return arn;
-};
+export const getAgentCoreRuntimeConfig =
+  async (): Promise<AgentCoreRuntimeConfig> => {
+    const application = process.env.RUNTIME_CONFIG_APP_ID;
+    if (!application) {
+      throw new Error(
+        'RUNTIME_CONFIG_APP_ID is not set — cannot resolve connected agent ARNs from AppConfig.',
+      );
+    }
+    return (await getAppConfig('agentcore', {
+      application,
+      environment: 'default',
+      transform: 'json',
+    })) as AgentCoreRuntimeConfig;
+  };

package/src/utils/agent-connection/files/core-shared/agentcore-transport.ts.template

@@ -0,0 +1,39 @@
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
+import {
+  createSigV4Fetch,
+  createJwtFetch,
+  createPlainFetch,
+} from './agentcore-fetch<% if (esm) { %>.js<% } %>';
+
+const build = (
+  url: string,
+  fetchFn: typeof fetch,
+): StreamableHTTPClientTransport =>
+  new StreamableHTTPClientTransport(new URL(url), { fetch: fetchFn });
+
+/** SigV4-signed transport for a resolved AgentCore endpoint. */
+export const sigV4Transport = (options: {
+  region: string;
+  url: string;
+  credentialProvider?: ReturnType<typeof fromNodeProviderChain>;
+}): StreamableHTTPClientTransport =>
+  build(
+    options.url,
+    createSigV4Fetch({
+      region: options.region,
+      credentialProvider: options.credentialProvider,
+    }),
+  );
+
+/** Bearer-token transport for a resolved AgentCore endpoint. */
+export const jwtTransport = (options: {
+  url: string;
+  accessTokenProvider: () => Promise<string>;
+}): StreamableHTTPClientTransport =>
+  build(options.url, createJwtFetch(options.accessTokenProvider));
+
+/** Plain-HTTP transport — for local dev. */
+export const noAuthTransport = (options: {
+  url: string;
+}): StreamableHTTPClientTransport => build(options.url, createPlainFetch());

package/src/utils/agent-connection/files/core-strands/a2a/agentcore-a2a-client-strands.ts.template

@@ -0,0 +1,61 @@
+import { A2AAgent } from '@strands-agents/sdk/a2a';
+import {
+  type A2aClientConfig,
+  AgentCoreA2aClientConfig,
+  type AgentCoreA2aClientConfigIamOptions,
+  type AgentCoreA2aClientConfigJwtOptions,
+  type AgentCoreA2aClientConfigNoAuthOptions,
+} from './agentcore-a2a-client-config<% if (esm) { %>.js<% } %>';
+
+/** Optional friendly metadata for the remote agent. */
+export interface StrandsA2aOptions {
+  /** Optional friendly name for the remote agent. */
+  name?: string;
+  /** Optional description for the remote agent. */
+  description?: string;
+}
+
+/** Strands A2A clients for a Bedrock AgentCore runtime. */
+export class AgentCoreA2aClientStrands {
+  private static build(
+    { url, clientFactory }: A2aClientConfig,
+    options: StrandsA2aOptions,
+  ): A2AAgent {
+    return new A2AAgent({
+      url,
+      clientFactory,
+      ...(options.name ? { name: options.name } : {}),
+      ...(options.description ? { description: options.description } : {}),
+    });
+  }
+
+  /** SigV4-authenticated client for a Bedrock AgentCore runtime. */
+  static withIamAuth(
+    options: AgentCoreA2aClientConfigIamOptions & StrandsA2aOptions,
+  ): A2AAgent {
+    return AgentCoreA2aClientStrands.build(
+      AgentCoreA2aClientConfig.withIamAuth(options),
+      options,
+    );
+  }
+
+  /** Bearer-authenticated client for a Bedrock AgentCore runtime. */
+  static withJwtAuth(
+    options: AgentCoreA2aClientConfigJwtOptions & StrandsA2aOptions,
+  ): A2AAgent {
+    return AgentCoreA2aClientStrands.build(
+      AgentCoreA2aClientConfig.withJwtAuth(options),
+      options,
+    );
+  }
+
+  /** For local dev — plain HTTP, no auth. */
+  static withoutAuth(
+    options: AgentCoreA2aClientConfigNoAuthOptions & StrandsA2aOptions,
+  ): A2AAgent {
+    return AgentCoreA2aClientStrands.build(
+      AgentCoreA2aClientConfig.withoutAuth(options),
+      options,
+    );
+  }
+}

package/src/utils/agent-connection/files/core-strands/base/model-errors-strands.ts.template

@@ -0,0 +1,47 @@
+import {
+  AfterModelCallEvent,
+  type LocalAgent,
+  type Plugin,
+} from '@strands-agents/sdk';
+
+const NO_CREDENTIALS =
+  'Unable to invoke the model: no AWS credentials found. Configure credentials ' +
+  '(e.g. run `aws configure`, set AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / ' +
+  'AWS_SESSION_TOKEN, or assume a role) before running the agent.';
+const ACCESS_DENIED =
+  'Unable to invoke the model: access denied. Grant your AWS principal permission ' +
+  'to call bedrock:InvokeModelWithResponseStream for your model.';
+
+// AWS SDK v3 errors are identified by their `name` rather than `instanceof`,
+// since the SDK may be loaded from more than one place. Strands wraps them in a
+// ModelError, so we check the error and its `cause` chain.
+const hasErrorNamed = (error: unknown, name: string): boolean => {
+  let current: unknown = error;
+  while (current instanceof Error) {
+    if (current.name === name) return true;
+    current = current.cause;
+  }
+  return false;
+};
+
+/**
+ * Plugin that logs model invocation errors, calling out missing credentials or
+ * denied permissions.
+ */
+export class ModelErrorLoggingPlugin implements Plugin {
+  readonly name = 'model-error-logging';
+
+  initAgent(agent: LocalAgent): void {
+    agent.addHook(AfterModelCallEvent, (event) => {
+      const error = event.error;
+      if (!error) return;
+      if (hasErrorNamed(error, 'CredentialsProviderError')) {
+        console.error(NO_CREDENTIALS);
+      } else if (hasErrorNamed(error, 'AccessDeniedException')) {
+        console.error(ACCESS_DENIED);
+      } else {
+        console.error(`Model invocation failed: ${error.message}`);
+      }
+    });
+  }
+}