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

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

@@ -1,195 +1,592 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PY_CORE_TEMPLATES = exports.TS_CORE_TEMPLATES = exports.AGENT_CONNECTION_PROJECT_DIR = void 0;
-exports.getPythonAgentConnectionProjectDir = getPythonAgentConnectionProjectDir;
-exports.getPythonAgentConnectionModuleName = getPythonAgentConnectionModuleName;
-exports.getPythonAgentConnectionPackageName = getPythonAgentConnectionPackageName;
-exports.ensureTypeScriptAgentConnectionProject = ensureTypeScriptAgentConnectionProject;
-exports.addTypeScriptCoreClient = addTypeScriptCoreClient;
-exports.ensurePythonAgentConnectionProject = ensurePythonAgentConnectionProject;
-exports.addPythonCoreClient = addPythonCoreClient;
-exports.addPythonReExport = addPythonReExport;
-const tslib_1 = require("tslib");
 /**
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
- */
-const devkit_1 = require("@nx/devkit");
-const generator_1 = tslib_1.__importStar(require("../../py/project/generator"));
-const generator_2 = tslib_1.__importDefault(require("../../ts/lib/generator"));
-const ast_1 = require("../ast");
-const py_1 = require("../py");
-/** Prefix a GritQL pattern with `language python` */
-const py = (pattern) => `language python\n${pattern}`;
+ */ import { generateFiles, joinPathFragments, OverwriteStrategy } from "@nx/devkit";
+import pyProjectGenerator, { getPyProjectDetails } from "../../py/project/generator.js";
+import tsProjectGenerator from "../../ts/lib/generator.js";
+import { addStarExport, applyGritQL, matchGritQL } from "../ast.js";
+import { forDependencies } from "../declared-dependencies.js";
+import { addDependenciesToPackageJson } from "../dependencies.js";
+import { esmVars } from "../module-format.js";
+import { addDependenciesToPyProjectToml } from "../py.js";
+import { withVersions } from "../versions.js";
+/** TypeScript dependencies a caller must declare to emit agent-connection clients. */ export const AGENT_CONNECTION_DEPENDENCIES = [
+    {
+        name: '@aws-lambda-powertools/parameters'
+    },
+    {
+        name: '@aws-sdk/credential-providers'
+    },
+    {
+        name: 'aws4fetch'
+    },
+    {
+        name: '@modelcontextprotocol/sdk'
+    },
+    {
+        name: '@a2a-js/sdk'
+    },
+    {
+        name: '@strands-agents/sdk'
+    }
+];
+/** Python dependencies a caller must declare to emit agent-connection clients. */ export const AGENT_CONNECTION_PY_DEPENDENCIES = [
+    {
+        name: 'aws-lambda-powertools'
+    },
+    {
+        name: 'strands-agents'
+    }
+];
+/** Prefix a GritQL pattern with `language python` */ const py = (pattern)=>`language python\n${pattern}`;
 const AGENT_CONNECTION_DIR = 'agent-connection';
 const PACKAGES_DIR = 'packages';
 const COMMON_DIR = 'common';
-exports.AGENT_CONNECTION_PROJECT_DIR = (0, devkit_1.joinPathFragments)(PACKAGES_DIR, COMMON_DIR, AGENT_CONNECTION_DIR);
+export const AGENT_CONNECTION_PROJECT_DIR = joinPathFragments(PACKAGES_DIR, COMMON_DIR, AGENT_CONNECTION_DIR);
 const PY_AGENT_CONNECTION_NAME = 'agent_connection';
 /**
  * Get the directory of the shared Python agent-connection project.
- */
-function getPythonAgentConnectionProjectDir(tree) {
-    const { dir } = (0, generator_1.getPyProjectDetails)(tree, {
+ */ export function getPythonAgentConnectionProjectDir(tree) {
+    const { dir } = getPyProjectDetails(tree, {
         name: PY_AGENT_CONNECTION_NAME,
-        directory: (0, devkit_1.joinPathFragments)(PACKAGES_DIR, COMMON_DIR),
+        directory: joinPathFragments(PACKAGES_DIR, COMMON_DIR)
     });
     return dir;
 }
 /**
  * Get the Python module name of the shared agent-connection project.
- */
-function getPythonAgentConnectionModuleName(tree) {
-    const { normalizedModuleName } = (0, generator_1.getPyProjectDetails)(tree, {
+ */ export function getPythonAgentConnectionModuleName(tree) {
+    const { normalizedModuleName } = getPyProjectDetails(tree, {
         name: PY_AGENT_CONNECTION_NAME,
-        directory: (0, devkit_1.joinPathFragments)(PACKAGES_DIR, COMMON_DIR),
+        directory: joinPathFragments(PACKAGES_DIR, COMMON_DIR)
     });
     return normalizedModuleName;
 }
 /**
- * Get the fully qualified Python package name of the shared agent-connection project.
- */
-function getPythonAgentConnectionPackageName(tree) {
-    const { fullyQualifiedName } = (0, generator_1.getPyProjectDetails)(tree, {
+ * Get the shared agent-connection project as `{ name, root }`, suitable for
+ * passing to {@link addWorkspaceDependencyToPyProject} (which derives the
+ * dependency's PEP 503 distribution name from the project itself, so callers
+ * never construct the name).
+ */ export function getPythonAgentConnectionProject(tree) {
+    const { fullyQualifiedName, dir } = getPyProjectDetails(tree, {
         name: PY_AGENT_CONNECTION_NAME,
-        directory: (0, devkit_1.joinPathFragments)(PACKAGES_DIR, COMMON_DIR),
+        directory: joinPathFragments(PACKAGES_DIR, COMMON_DIR)
     });
-    return fullyQualifiedName;
+    return {
+        name: fullyQualifiedName,
+        root: dir
+    };
+}
+/**
+ * Resolve an agent component's framework, defaulting to `strands`. Connection
+ * generators dispatch on the returned framework to pick the matching templates
+ * and agent.py/agent.ts transforms.
+ */ export function resolveAgentFramework(framework) {
+    return framework === 'langchain' ? 'langchain' : 'strands';
 }
 /**
- * Directories (relative to this file) holding per-protocol core client
- * template files. Per-connection generators select which set to emit so
- * the MCP connection doesn't pull in the A2A client (or vice versa).
- */
-exports.TS_CORE_TEMPLATES = {
+ * Framework-agnostic Layer-1 templates, keyed by protocol. These resolve the
+ * endpoint and build the signed transport/client-config; they contain no
+ * framework dependency.
+ */ const TS_PROTOCOL_TEMPLATES = {
     mcp: 'core-mcp',
-    a2a: 'core-a2a',
+    gateway: 'core-gateway',
+    a2a: 'core-a2a'
 };
-exports.PY_CORE_TEMPLATES = {
+const PY_PROTOCOL_TEMPLATES = {
     mcp: 'py-core-mcp',
-    a2a: 'py-core-a2a',
-    /** Shared SigV4 `httpx.Auth` used by both MCP and A2A clients. */
-    auth: 'py-core-auth',
+    gateway: 'py-core-gateway',
+    a2a: 'py-core-a2a'
+};
+const FRAMEWORKS = {
+    strands: {
+        ts: {
+            base: 'core-strands/base',
+            baseReExports: [
+                {
+                    fromModule: './core/with-session-id-strands.js',
+                    importName: '*'
+                },
+                {
+                    fromModule: './core/model-errors-strands.js',
+                    importName: '*'
+                },
+                {
+                    fromModule: './core/tool-errors-strands.js',
+                    importName: '*'
+                }
+            ],
+            protocols: {
+                mcp: 'core-strands/mcp',
+                gateway: 'core-strands/gateway',
+                a2a: 'core-strands/a2a'
+            },
+            deps: []
+        },
+        py: {
+            base: 'py-core-strands/base',
+            baseReExports: [
+                {
+                    fromModule: '.core.with_session_id_strands',
+                    importName: 'with_session_id'
+                },
+                {
+                    fromModule: '.core.model_errors_strands',
+                    importName: 'log_model_errors'
+                }
+            ],
+            protocols: {
+                mcp: 'py-core-strands/mcp',
+                gateway: 'py-core-strands/gateway',
+                a2a: 'py-core-strands/a2a'
+            },
+            deps: [
+                'strands-agents'
+            ]
+        }
+    },
+    langchain: {
+        // LangChain is supported for Python agents only (the TypeScript LangChain
+        // agent foundation has no in-process AG-UI <-> LangGraph adapter, so it is
+        // not scaffolded — see ts#agent). Its Layer-2 clients stay usable after
+        // agent construction, so there is no base helper layer (no model-error
+        // logger / per-session agent cache) and no strands-agents dependency — its
+        // AG-UI foundation reuses only the framework-agnostic session context, and
+        // its A2A client drives the a2a SDK directly rather than wrapping Strands'
+        // A2AAgent. The per-connection adapter dependency (langchain-mcp-adapters /
+        // a2a-sdk) is added by the connection generators.
+        py: {
+            baseReExports: [],
+            protocols: {
+                mcp: 'py-core-langchain/mcp',
+                gateway: 'py-core-langchain/gateway',
+                a2a: 'py-core-langchain/a2a'
+            },
+            deps: []
+        }
+    }
+};
+/** Resolve a framework's templates for a language + protocol, or throw. */ function frameworkLanguage(framework, language, protocol) {
+    const lang = FRAMEWORKS[framework][language];
+    if (!lang) {
+        throw new Error(`The '${framework}' framework does not support ${language === 'ts' ? 'TypeScript' : 'Python'} agents.`);
+    }
+    const protocolDir = lang.protocols[protocol];
+    if (!protocolDir) {
+        throw new Error(`The '${framework}' framework does not support ${protocol} connections for ${language === 'ts' ? 'TypeScript' : 'Python'} agents.`);
+    }
+    return {
+        ...lang,
+        protocol: protocolDir
+    };
+}
+/** Protocols whose Layer-1 needs the shared MCP transport (`core-shared`). */ const MCP_TRANSPORT_PROTOCOLS = [
+    'mcp',
+    'gateway'
+];
+const tsCoreDir = ()=>joinPathFragments(AGENT_CONNECTION_PROJECT_DIR, 'src', 'core');
+/**
+ * Runtime dependencies each TypeScript core template directory imports. Emitting
+ * a template also declares its dependencies in the agent-connection project's
+ * package.json so the `noUndeclaredDependencies` lint rule passes.
+ */ const TS_TEMPLATE_DEPS = {
+    'core-runtime-config': [
+        '@aws-lambda-powertools/parameters'
+    ],
+    'core-auth': [
+        '@aws-sdk/credential-providers',
+        'aws4fetch'
+    ],
+    'core-shared': [
+        '@aws-sdk/credential-providers',
+        '@modelcontextprotocol/sdk'
+    ],
+    'core-mcp': [
+        '@aws-sdk/credential-providers',
+        '@modelcontextprotocol/sdk'
+    ],
+    'core-gateway': [
+        '@aws-sdk/credential-providers',
+        '@modelcontextprotocol/sdk'
+    ],
+    'core-a2a': [
+        '@aws-sdk/credential-providers',
+        '@a2a-js/sdk'
+    ],
+    'core-strands/base': [
+        '@strands-agents/sdk'
+    ],
+    'core-strands/mcp': [
+        '@strands-agents/sdk'
+    ],
+    'core-strands/gateway': [
+        '@strands-agents/sdk'
+    ],
+    'core-strands/a2a': [
+        '@strands-agents/sdk'
+    ]
+};
+const emitTs = (tree, templateDir, declaration)=>{
+    generateFiles(tree, joinPathFragments(import.meta.dirname, 'files', templateDir), tsCoreDir(), {
+        ...esmVars(tree)
+    }, {
+        overwriteStrategy: OverwriteStrategy.KeepExisting
+    });
+    const deps = TS_TEMPLATE_DEPS[templateDir];
+    if (deps?.length) {
+        addDependenciesToPackageJson(tree, withVersions(forDependencies(declaration), deps), {}, joinPathFragments(AGENT_CONNECTION_PROJECT_DIR, 'package.json'));
+    }
 };
 /**
  * Ensure the shared TypeScript agent-connection project exists and has the
- * shared core helpers (runtime-config loader). Per-connection generators
- * are responsible for emitting their own per-protocol core client templates.
- */
-async function ensureTypeScriptAgentConnectionProject(tree) {
-    const projectJsonPath = (0, devkit_1.joinPathFragments)(exports.AGENT_CONNECTION_PROJECT_DIR, 'project.json');
+ * framework-agnostic core helpers (runtime-config loader, session context).
+ * Per-connection generators emit their own protocol + framework client
+ * templates via `addTypeScriptCoreClient`.
+ */ export async function ensureTypeScriptAgentConnectionProject(tree, declaration) {
+    const projectJsonPath = joinPathFragments(AGENT_CONNECTION_PROJECT_DIR, 'project.json');
     if (!tree.exists(projectJsonPath)) {
-        await (0, generator_2.default)(tree, {
+        await tsProjectGenerator(tree, {
             name: AGENT_CONNECTION_DIR,
-            directory: (0, devkit_1.joinPathFragments)(PACKAGES_DIR, COMMON_DIR),
+            directory: joinPathFragments(PACKAGES_DIR, COMMON_DIR)
         });
     }
-    // Shared core helpers — emitted regardless of which per-protocol core
-    // client the caller needs, so both MCP and A2A clients can import from them.
-    (0, devkit_1.generateFiles)(tree, (0, devkit_1.joinPathFragments)(__dirname, 'files', 'core-runtime-config'), (0, devkit_1.joinPathFragments)(exports.AGENT_CONNECTION_PROJECT_DIR, 'src', 'core'), {}, { overwriteStrategy: devkit_1.OverwriteStrategy.KeepExisting });
-    // Re-export session-context helpers so agent server entry points
-    // can set the current session on each inbound request without pulling in
-    // the agent-connection internals.
-    await (0, ast_1.addStarExport)(tree, (0, devkit_1.joinPathFragments)(exports.AGENT_CONNECTION_PROJECT_DIR, 'src', 'index.ts'), './core/session-context.js');
-    await (0, ast_1.addStarExport)(tree, (0, devkit_1.joinPathFragments)(exports.AGENT_CONNECTION_PROJECT_DIR, 'src', 'index.ts'), './core/with-session-id.js');
+    // Framework-agnostic runtime-config + session-context helpers.
+    emitTs(tree, 'core-runtime-config', declaration);
+    // Re-export session-context helpers so agent server entry points can set the
+    // current session on each inbound request without pulling in internals.
+    await addStarExport(tree, joinPathFragments(AGENT_CONNECTION_PROJECT_DIR, 'src', 'index.ts'), './core/session-context.js');
+    // Re-export the runtime-config loader so agent server entry points can read
+    // their own connected resources (e.g. session storage) without pulling in
+    // internals.
+    await addStarExport(tree, joinPathFragments(AGENT_CONNECTION_PROJECT_DIR, 'src', 'index.ts'), './core/runtime-config.js');
+}
+/**
+ * Emit a framework's base Layer-2 helpers (model-error logging + per-session
+ * agent cache) into the agent-connection project and re-export them. The agent
+ * server entry point imports these regardless of whether any connection client
+ * is wired in, so the agent generator calls this directly; connection
+ * generators call it transitively via `addTypeScriptCoreClient`.
+ */ export async function addTypeScriptFrameworkBase(tree, declaration, framework = 'strands') {
+    const lang = FRAMEWORKS[framework].ts;
+    if (!lang) {
+        throw new Error(`The '${framework}' framework does not support TypeScript agents.`);
+    }
+    if (lang.base) {
+        emitTs(tree, lang.base, declaration);
+    }
+    const indexPath = joinPathFragments(AGENT_CONNECTION_PROJECT_DIR, 'src', 'index.ts');
+    for (const reExport of lang.baseReExports){
+        await addStarExport(tree, indexPath, reExport.fromModule);
+    }
 }
 /**
- * Emit one of the TypeScript core client templates (mcp or a2a) into the
- * agent-connection project's `src/core/` directory. Safe to call multiple
- * times — `KeepExisting` preserves customised files.
- */
-function addTypeScriptCoreClient(tree, kind) {
-    (0, devkit_1.generateFiles)(tree, (0, devkit_1.joinPathFragments)(__dirname, 'files', exports.TS_CORE_TEMPLATES[kind]), (0, devkit_1.joinPathFragments)(exports.AGENT_CONNECTION_PROJECT_DIR, 'src', 'core'), {}, { overwriteStrategy: devkit_1.OverwriteStrategy.KeepExisting });
+ * Emit the TypeScript client templates for a connection protocol and agent
+ * framework into the agent-connection project's `src/core/` directory. Safe to
+ * call multiple times — `KeepExisting` preserves customised files.
+ *
+ * Layers emitted:
+ *  - Layer 0 `core-auth` (signed fetch + endpoint resolution) — always
+ *  - Layer 1 `core-shared` MCP transport — for mcp/gateway protocols
+ *  - Layer 1 the protocol's transport/client-config — always
+ *  - Layer 2 the framework's base helpers + protocol client — per framework
+ */ export async function addTypeScriptCoreClient(tree, protocol, declaration, framework = 'strands') {
+    const fw = frameworkLanguage(framework, 'ts', protocol);
+    emitTs(tree, 'core-auth', declaration);
+    if (MCP_TRANSPORT_PROTOCOLS.includes(protocol)) {
+        emitTs(tree, 'core-shared', declaration);
+    }
+    emitTs(tree, TS_PROTOCOL_TEMPLATES[protocol], declaration);
+    // Framework Layer 2: base helpers (re-exported for the agent server) + the
+    // thin protocol client.
+    await addTypeScriptFrameworkBase(tree, forDependencies(declaration), framework);
+    emitTs(tree, fw.protocol, declaration);
 }
 /**
  * Ensure the shared Python agent-connection project exists.
  * Only creates the project shell — per-connection generators are responsible
  * for emitting their own core client templates.
- */
-async function ensurePythonAgentConnectionProject(tree) {
+ */ export async function ensurePythonAgentConnectionProject(tree, declaration) {
     const projectDir = getPythonAgentConnectionProjectDir(tree);
     const moduleName = getPythonAgentConnectionModuleName(tree);
-    const projectJsonPath = (0, devkit_1.joinPathFragments)(projectDir, 'project.json');
+    const projectJsonPath = joinPathFragments(projectDir, 'project.json');
     if (!tree.exists(projectJsonPath)) {
         // Create the Python project using the standard py#project generator
-        await (0, generator_1.default)(tree, {
+        await pyProjectGenerator(tree, {
             name: PY_AGENT_CONNECTION_NAME,
-            directory: (0, devkit_1.joinPathFragments)(PACKAGES_DIR, COMMON_DIR),
-            type: 'library',
+            directory: joinPathFragments(PACKAGES_DIR, COMMON_DIR),
+            type: 'library'
         });
     }
-    const moduleDir = (0, devkit_1.joinPathFragments)(projectDir, moduleName);
+    const moduleDir = joinPathFragments(projectDir, moduleName);
     // Ensure core/__init__.py exists
-    const coreDir = (0, devkit_1.joinPathFragments)(moduleDir, 'core');
-    if (!tree.exists((0, devkit_1.joinPathFragments)(coreDir, '__init__.py'))) {
-        tree.write((0, devkit_1.joinPathFragments)(coreDir, '__init__.py'), '');
+    const coreDir = joinPathFragments(moduleDir, 'core');
+    if (!tree.exists(joinPathFragments(coreDir, '__init__.py'))) {
+        tree.write(joinPathFragments(coreDir, '__init__.py'), '');
     }
     // Ensure app/__init__.py exists
-    const appInitPath = (0, devkit_1.joinPathFragments)(moduleDir, 'app', '__init__.py');
+    const appInitPath = joinPathFragments(moduleDir, 'app', '__init__.py');
     if (!tree.exists(appInitPath)) {
         tree.write(appInitPath, '');
     }
-    // Shared core helpers — emitted regardless of which per-protocol core
-    // client the caller needs, so both MCP and A2A clients can import them.
-    (0, devkit_1.generateFiles)(tree, (0, devkit_1.joinPathFragments)(__dirname, 'files', 'py-core-runtime-config'), coreDir, {}, { overwriteStrategy: devkit_1.OverwriteStrategy.KeepExisting });
-    // Re-export session-context helpers so agent server entry points
-    // can set the current session on each inbound request without importing
-    // the agent-connection internals directly.
-    const moduleInitPath = (0, devkit_1.joinPathFragments)(moduleDir, '__init__.py');
+    // Framework-agnostic runtime-config + session-context helpers.
+    generateFiles(tree, joinPathFragments(import.meta.dirname, 'files', 'py-core-runtime-config'), coreDir, {}, {
+        overwriteStrategy: OverwriteStrategy.KeepExisting
+    });
+    // Re-export the session id context so agent server entry points can set the
+    // current session on each inbound request without importing internals.
+    const moduleInitPath = joinPathFragments(moduleDir, '__init__.py');
     await addPythonReExport(tree, moduleInitPath, '.core.session_context', 'get_current_session_id');
     await addPythonReExport(tree, moduleInitPath, '.core.session_context', 'session_id_context');
-    await addPythonReExport(tree, moduleInitPath, '.core.with_session_id', 'with_session_id');
-    // Shared core helpers depend on aws-lambda-powertools for AppConfig access.
-    (0, py_1.addDependenciesToPyProjectToml)(tree, projectDir, ['aws-lambda-powertools']);
+    // The runtime-config loader reads AppConfig via aws-lambda-powertools.
+    addDependenciesToPyProjectToml(tree, projectDir, forDependencies(declaration), [
+        'aws-lambda-powertools'
+    ]);
 }
+const pyCoreDir = (tree)=>joinPathFragments(getPythonAgentConnectionProjectDir(tree), getPythonAgentConnectionModuleName(tree), 'core');
+const emitPy = (tree, templateDir)=>generateFiles(tree, joinPathFragments(import.meta.dirname, 'files', templateDir), pyCoreDir(tree), {}, {
+        overwriteStrategy: OverwriteStrategy.KeepExisting
+    });
 /**
- * Emit a Python core client template (mcp / a2a / shared auth) into the
- * agent-connection project's core directory.
- */
-function addPythonCoreClient(tree, kind) {
-    const projectDir = getPythonAgentConnectionProjectDir(tree);
-    const moduleName = getPythonAgentConnectionModuleName(tree);
-    const coreDir = (0, devkit_1.joinPathFragments)(projectDir, moduleName, 'core');
-    (0, devkit_1.generateFiles)(tree, (0, devkit_1.joinPathFragments)(__dirname, 'files', exports.PY_CORE_TEMPLATES[kind]), coreDir, {}, { overwriteStrategy: devkit_1.OverwriteStrategy.KeepExisting });
+ * Emit a framework's base Layer-2 helpers (model-error logging + per-session
+ * agent cache) into the Python agent-connection project and re-export them.
+ * The agent server entry point imports these regardless of whether a connection
+ * client is wired in, so the agent generator calls this directly; connection
+ * generators call it transitively via `addPythonCoreClient`.
+ */ export async function addPythonFrameworkBase(tree, declaration, framework = 'strands') {
+    const lang = FRAMEWORKS[framework].py;
+    if (!lang) {
+        throw new Error(`The '${framework}' framework does not support Python agents.`);
+    }
+    if (lang.base) {
+        emitPy(tree, lang.base);
+    }
+    const moduleInitPath = joinPathFragments(getPythonAgentConnectionProjectDir(tree), getPythonAgentConnectionModuleName(tree), '__init__.py');
+    for (const reExport of lang.baseReExports){
+        await addPythonReExport(tree, moduleInitPath, reExport.fromModule, reExport.importName);
+    }
+    if (lang.deps.length > 0) {
+        addDependenciesToPyProjectToml(tree, getPythonAgentConnectionProjectDir(tree), forDependencies(declaration), lang.deps);
+    }
+}
+/**
+ * Emit the Python client templates for a connection protocol and agent
+ * framework into the agent-connection project's core directory.
+ *
+ * Layers emitted:
+ *  - Layer 0 `py-core-auth` (SigV4 httpx.Auth, session auth, endpoints) — always
+ *  - Layer 1 `py-core-shared` MCP transport — for mcp/gateway protocols
+ *  - Layer 1 the protocol's transport/client-config — always
+ *  - Layer 2 the framework's base helpers + protocol client — per framework
+ */ export async function addPythonCoreClient(tree, protocol, declaration, framework = 'strands') {
+    const fw = frameworkLanguage(framework, 'py', protocol);
+    emitPy(tree, 'py-core-auth');
+    if (MCP_TRANSPORT_PROTOCOLS.includes(protocol)) {
+        emitPy(tree, 'py-core-shared');
+    }
+    emitPy(tree, PY_PROTOCOL_TEMPLATES[protocol]);
+    // Framework Layer 2: base helpers + the thin protocol client.
+    await addPythonFrameworkBase(tree, forDependencies(declaration), framework);
+    emitPy(tree, fw.protocol);
+}
+/**
+ * Patch a TypeScript agent.ts to create a connection client and register it
+ * in the Agent's tools. Used by the MCP and gateway connection generators —
+ * the client class must expose a static async `create()` returning a value
+ * accepted by `Agent.tools` (e.g. an `McpClient`).
+ */ export async function addTypeScriptClientToAgent(tree, agentFilePath, clientClassName, clientVarName) {
+    const clientCreationStmt = `const ${clientVarName} = await ${clientClassName}.create();`;
+    // Transform the arrow function that contains `new Agent`:
+    // - Expression body: wrap in block with client creation and return
+    // - Block body: prepend client creation statement
+    await applyGritQL(tree, agentFilePath, `or { \`async ($p) => new Agent($args)\` => raw\`async ($p) => {
+  ${clientCreationStmt}
+  return new Agent($args);
+}\` where { $program <: not contains \`${clientClassName}.create\` }, \`async ($p) => { $body }\` => raw\`async ($p) => {
+  ${clientCreationStmt}
+  $body
+}\` where { $body <: contains \`new Agent($_)\`, $program <: not contains \`${clientClassName}.create\` } }`);
+    // Prepend the client to the tools array
+    await applyGritQL(tree, agentFilePath, `\`tools: [$items]\` => \`tools: [${clientVarName}, $items]\` where { $items <: within \`new Agent($_)\`, $items <: not contains \`${clientVarName}\` }`);
+}
+/**
+ * Patch a Python agent.py to create a context-managed connection client,
+ * enter it in the `with` block around `yield Agent(...)`, and spread its
+ * `list_tools_sync()` into the Agent's tools. Used by the MCP and gateway
+ * connection generators — the client class must expose a static `create()`
+ * returning a context manager with `list_tools_sync()` (e.g. an `MCPClient`).
+ */ async function addPythonClientToAgent(tree, agentFilePath, clientClassName, clientVarName) {
+    await addPythonClientTools(tree, agentFilePath, clientVarName);
+    await addPythonClientToGetAgent(tree, agentFilePath, clientClassName, clientVarName);
+}
+/**
+ * Append `*<clientVarName>.list_tools_sync()` to the Agent's tools list.
+ */ const addPythonClientTools = async (tree, filePath, clientVarName)=>{
+    if (await matchGritQL(tree, filePath, py(`\`${clientVarName}.list_tools_sync()\``))) {
+        return;
+    }
+    await applyGritQL(tree, filePath, py(`\`tools=$old\` where {
+  $old <: not contains \`${clientVarName}\`,
+  if ($old <: \`[]\`) {
+    $old => \`[*${clientVarName}.list_tools_sync()]\`
+  } else {
+    $old <: \`[$items]\` where { $items += \`, *${clientVarName}.list_tools_sync()\` }
+  }
+}`));
+};
+/**
+ * Create the client in get_agent and enter it in the `with` block.
+ *
+ * First connection: rewrites `def get_agent` to wrap the body in a with
+ * block. Subsequent connections: adds to the existing with items and
+ * prepends the creation line.
+ */ const addPythonClientToGetAgent = async (tree, filePath, clientClassName, clientVarName)=>{
+    if (await matchGritQL(tree, filePath, py(`\`${clientClassName}.create()\``))) {
+        return;
+    }
+    // Try the "add to existing with block" pattern first.
+    // If it succeeds, there was already a with block from a previous connection.
+    const addedToWith = await applyGritQL(tree, filePath, py(`\`with ($items,): $body\` where {
+  $items <: not contains \`${clientVarName}\`,
+  $items += \`, ${clientVarName}\`
+}`));
+    if (addedToWith) {
+        // Subsequent connection — prepend the creation line to the function body
+        // (a single anchor, so the line is inserted exactly once).
+        await applyGritQL(tree, filePath, py(`\`def get_agent($params):
+    $body\` where {
+  $body <: contains \`yield Agent($_)\`,
+  $body <: not contains \`${clientClassName}.create\`
+} => \`def get_agent($params):
+    ${clientVarName} = ${clientClassName}.create()
+    $body\``));
+        return;
+    }
+    // First connection — wrap the existing `def get_agent` body in a single
+    // `with (<var>,):` block.
+    await applyGritQL(tree, filePath, py(`\`def get_agent($params):
+    $body\` where {
+  $body <: contains \`yield Agent($_)\`,
+  $body <: not contains \`${clientClassName}.create\`
+} => \`def get_agent($params):
+    ${clientVarName} = ${clientClassName}.create()
+    with (
+        ${clientVarName},
+    ):
+        $body\``));
+};
+/**
+ * Patch a LangChain agent.py to load connection tools and spread them into the
+ * `create_agent(...)` tools list. Used by the MCP and gateway connection
+ * generators when the source agent uses the `langchain` framework — the client
+ * class must expose a static `create()` returning a `list[BaseTool]`. The tools
+ * come from langchain-mcp-adapters' `MultiServerMCPClient`, which keeps the
+ * connection config on each tool and opens a fresh MCP session per call, so the
+ * tools stay usable after `get_agent` returns — no `with` block is needed.
+ * Mirrors {@link addPythonClientToAgent} for the Strands shape.
+ */ async function addPythonLangchainClientToAgent(tree, agentFilePath, clientClassName, clientVarName) {
+    await addPythonLangchainClientTools(tree, agentFilePath, clientVarName);
+    await addPythonLangchainClientToGetAgent(tree, agentFilePath, clientClassName, clientVarName);
 }
+/**
+ * Spread `*<clientVarName>` into the `create_agent(...)` tools list.
+ *
+ * Scoped via `$old <: within \`create_agent($_)\`` so only the agent's own
+ * tools= keyword argument is touched (not an unrelated function with a
+ * `tools=` parameter).
+ */ const addPythonLangchainClientTools = async (tree, filePath, clientVarName)=>{
+    await applyGritQL(tree, filePath, py(`\`tools=$old\` where {
+  $old <: within \`create_agent($_)\`,
+  $old <: not contains \`*${clientVarName}\`,
+  if ($old <: \`[]\`) {
+    $old => \`[*${clientVarName}]\`
+  } else {
+    $old <: \`[$items]\` where { $items += \`, *${clientVarName}\` }
+  }
+}`));
+};
+/**
+ * Prepend `<clientVarName> = <clientClassName>.create()` to the get_agent body
+ * (which loads the connection's tools). No `with` block — the LangChain client
+ * hands langchain-mcp-adapters a connection config, so each tool opens its own
+ * MCP session per call and the tools are safe to use after get_agent returns.
+ * Idempotent via the `not contains <clientClassName>.create` guard.
+ */ const addPythonLangchainClientToGetAgent = async (tree, filePath, clientClassName, clientVarName)=>{
+    if (await matchGritQL(tree, filePath, py(`\`${clientClassName}.create()\``))) {
+        return;
+    }
+    await applyGritQL(tree, filePath, py(`\`def get_agent($params):
+    $body\` where {
+  $body <: contains \`create_agent($_)\`,
+  $body <: not contains \`${clientClassName}.create\`
+} => \`def get_agent($params):
+    ${clientVarName} = ${clientClassName}.create()
+    $body\``));
+};
+export const PY_CLIENT_NAMING = {
+    strands: {
+        clientClassSuffix: 'Strands',
+        clientModuleSuffix: 'strands',
+        appTemplateSubdir: joinPathFragments('agent-connection', 'app')
+    },
+    langchain: {
+        clientClassSuffix: 'LangChain',
+        clientModuleSuffix: 'langchain',
+        appTemplateSubdir: joinPathFragments('langchain', 'agent-connection', 'app')
+    }
+};
+export const PY_MCP_FAMILY_CONNECTIONS = {
+    strands: {
+        ...PY_CLIENT_NAMING.strands,
+        deps: [],
+        wireClientIntoAgent: addPythonClientToAgent
+    },
+    langchain: {
+        ...PY_CLIENT_NAMING.langchain,
+        // langchain-mcp-adapters backs the LangChain client; it must not pull Strands in.
+        deps: [
+            'langchain-mcp-adapters'
+        ],
+        wireClientIntoAgent: addPythonLangchainClientToAgent
+    }
+};
 /**
  * Add a re-export to the Python agent-connection module's __init__.py.
  * Equivalent to addStarExport for TS.
  * Uses `__all__` to mark re-exports as public (satisfies ruff F401).
  * Uses GritQL for AST-aware transforms where possible.
- */
-async function addPythonReExport(tree, initFilePath, fromModule, importName) {
+ */ export async function addPythonReExport(tree, initFilePath, fromModule, importName) {
     // Check if already exported
-    if (await (0, ast_1.matchGritQL)(tree, initFilePath, `\`${importName}\``)) {
+    if (await matchGritQL(tree, initFilePath, `\`${importName}\``)) {
         return;
     }
     const importLine = `from ${fromModule} import ${importName}`;
     const allEntry = `"${importName}"`;
     // If there's already an import from the same module, merge into its name list
     // (ruff I001 rejects two `from X import ...` lines for the same module).
-    const mergedImport = await (0, ast_1.applyGritQL)(tree, initFilePath, py(`\`from ${fromModule} import $names\` where {
+    const mergedImport = await applyGritQL(tree, initFilePath, py(`\`from ${fromModule} import $names\` where {
   $names <: not contains \`${importName}\`,
   $names += \`, ${importName}\`
 }`));
     if (mergedImport) {
-        await (0, ast_1.applyGritQL)(tree, initFilePath, py(`\`__all__ = [$items]\` where { $items += \`, ${allEntry}\` }`));
+        await applyGritQL(tree, initFilePath, py(`\`__all__ = [$items]\` where { $items += \`, ${allEntry}\` }`));
         return;
     }
     // Try to append import after existing import using +=
-    const appendedImport = await (0, ast_1.applyGritQL)(tree, initFilePath, py(`\`from $mod import $name\` as $stmt where {
+    const appendedImport = await applyGritQL(tree, initFilePath, py(`\`from $mod import $name\` as $stmt where {
   $program <: not contains \`${importName}\`,
   $stmt += \`\n${importLine}\`
 }`));
     if (appendedImport) {
         // Also append to existing __all__
-        await (0, ast_1.applyGritQL)(tree, initFilePath, py(`\`__all__ = [$items]\` where { $items += \`, ${allEntry}\` }`));
+        await applyGritQL(tree, initFilePath, py(`\`__all__ = [$items]\` where { $items += \`, ${allEntry}\` }`));
         return;
     }
     // No existing imports — first re-export. Try to anchor after docstring.
-    const anchoredImport = await (0, ast_1.applyGritQL)(tree, initFilePath, py(`\`"""Automatically generated by Nx."""\` as $doc => \`$doc\n${importLine}\n\n__all__ = [${allEntry}]\``));
+    const anchoredImport = await applyGritQL(tree, initFilePath, py(`\`"""Automatically generated by Nx."""\` as $doc => \`$doc\n${importLine}\n\n__all__ = [${allEntry}]\``));
     if (!anchoredImport) {
         // Completely empty file or no docstring — write directly
         tree.write(initFilePath, `${importLine}\n\n__all__ = [${allEntry}]\n`);
     }
 }
+
 //# sourceMappingURL=agent-connection.js.map