@aws/nx-plugin 1.0.0-rc.5 → 1.0.0-rc.51

package/src/utils/__snapshots__/shared-constructs.spec.ts.snap

@@ -79,9 +79,30 @@ export const suppressRules = (
 "
 `;
 
+exports[`shared-constructs utils > sharedConstructsGenerator > should generate shared constructs when they do not exist > packages/common/constructs/src/core/cloudfront.ts 1`] = `
+"import { CfnDistribution, Distribution } from 'aws-cdk-lib/aws-cloudfront';
+
+/**
+ * Finds the domain names associated with a CloudFront distribution.
+ *
+ * Includes the distribution's default \`*.cloudfront.net\` domain name plus any custom
+ * domain names (aliases) configured on it.
+ */
+export const findCloudFrontDomainNames = (
+  distribution: Distribution,
+): string[] => {
+  const cfnDistribution = distribution.node.defaultChild as CfnDistribution;
+  const distributionConfig =
+    cfnDistribution.distributionConfig as CfnDistribution.DistributionConfigProperty;
+  return [distribution.domainName, ...(distributionConfig.aliases ?? [])];
+};
+"
+`;
+
 exports[`shared-constructs utils > sharedConstructsGenerator > should generate shared constructs when they do not exist > packages/common/constructs/src/core/index.ts 1`] = `
 "export * from './app.js';
 export * from './checkov.js';
+export * from './cloudfront.js';
 export * from './runtime-config.js';
 export * from './workspace.js';
 "

package/src/utils/agent-chat/agent-chat.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Tree } from '@nx/devkit';
+export type AgentChatProtocol = 'http' | 'a2a' | 'ag-ui';
+export type AgentChatAuth = 'iam' | 'cognito';
+export interface AddAgentChatScriptsOptions {
+    /** Absolute (tree) directory to emit the chat scripts into. */
+    scriptsDir: string;
+    protocol: AgentChatProtocol;
+    /** Agent server language. Only affects the HTTP chat adapter. */
+    language: 'ts' | 'py';
+    /** Construct class name — the runtime-config key for the deployed agent. */
+    agentNameClassName: string;
+    /** Authentication used by the deployed agent. */
+    auth: AgentChatAuth;
+    /**
+     * Import path to the agent's `client.ts` (TypeScript HTTP agents only),
+     * relative to the chat script.
+     */
+    relativeAgentImport?: string;
+}
+/**
+ * Emit the chat CLI scripts for an agent. Every protocol gets a small
+ * `chat.ts` that connects to the local `dev` server by default, and
+ * to the deployed agent on Bedrock AgentCore (resolved from runtime config)
+ * when `RUNTIME_CONFIG_APP_ID` is set. The shared `agentcore.ts` helper
+ * handles ARN resolution and request authentication.
+ */
+export declare const addAgentChatScripts: (tree: Tree, options: AddAgentChatScriptsOptions) => void;

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

@@ -0,0 +1,31 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { generateFiles, joinPathFragments, OverwriteStrategy } from "@nx/devkit";
+import { esmVars } from "../module-format.js";
+/**
+ * Emit the chat CLI scripts for an agent. Every protocol gets a small
+ * `chat.ts` that connects to the local `dev` server by default, and
+ * to the deployed agent on Bedrock AgentCore (resolved from runtime config)
+ * when `RUNTIME_CONFIG_APP_ID` is set. The shared `agentcore.ts` helper
+ * handles ARN resolution and request authentication.
+ */ export const addAgentChatScripts = (tree, options)=>{
+    const templateContext = {
+        agentNameClassName: options.agentNameClassName,
+        auth: options.auth,
+        relativeAgentImport: options.relativeAgentImport ?? '',
+        ...esmVars(tree)
+    };
+    // Shared remote-resolution + auth helper, used by every protocol.
+    generateFiles(tree, joinPathFragments(import.meta.dirname, 'files', 'common'), options.scriptsDir, templateContext, {
+        overwriteStrategy: OverwriteStrategy.KeepExisting
+    });
+    // Protocol-specific chat adapter. HTTP differs by server language; A2A and
+    // AG-UI speak standard protocols so the same script serves both languages.
+    const protocolDir = options.protocol === 'http' ? `http-${options.language}` : options.protocol;
+    generateFiles(tree, joinPathFragments(import.meta.dirname, 'files', protocolDir), options.scriptsDir, templateContext, {
+        overwriteStrategy: OverwriteStrategy.KeepExisting
+    });
+};
+
+//# sourceMappingURL=agent-chat.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../packages/nx-plugin/src/utils/agent-chat/agent-chat.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport type { Tree } from '@nx/devkit';\nimport {\n  generateFiles,\n  joinPathFragments,\n  OverwriteStrategy,\n} from '@nx/devkit';\nimport { esmVars } from '../module-format';\n\nexport type AgentChatProtocol = 'http' | 'a2a' | 'ag-ui';\nexport type AgentChatAuth = 'iam' | 'cognito';\n\nexport interface AddAgentChatScriptsOptions {\n  /** Absolute (tree) directory to emit the chat scripts into. */\n  scriptsDir: string;\n  protocol: AgentChatProtocol;\n  /** Agent server language. Only affects the HTTP chat adapter. */\n  language: 'ts' | 'py';\n  /** Construct class name — the runtime-config key for the deployed agent. */\n  agentNameClassName: string;\n  /** Authentication used by the deployed agent. */\n  auth: AgentChatAuth;\n  /**\n   * Import path to the agent's `client.ts` (TypeScript HTTP agents only),\n   * relative to the chat script.\n   */\n  relativeAgentImport?: string;\n}\n\n/**\n * Emit the chat CLI scripts for an agent. Every protocol gets a small\n * `chat.ts` that connects to the local `dev` server by default, and\n * to the deployed agent on Bedrock AgentCore (resolved from runtime config)\n * when `RUNTIME_CONFIG_APP_ID` is set. The shared `agentcore.ts` helper\n * handles ARN resolution and request authentication.\n */\nexport const addAgentChatScripts = (\n  tree: Tree,\n  options: AddAgentChatScriptsOptions,\n): void => {\n  const templateContext = {\n    agentNameClassName: options.agentNameClassName,\n    auth: options.auth,\n    relativeAgentImport: options.relativeAgentImport ?? '',\n    ...esmVars(tree),\n  };\n\n  // Shared remote-resolution + auth helper, used by every protocol.\n  generateFiles(\n    tree,\n    joinPathFragments(import.meta.dirname, 'files', 'common'),\n    options.scriptsDir,\n    templateContext,\n    { overwriteStrategy: OverwriteStrategy.KeepExisting },\n  );\n\n  // Protocol-specific chat adapter. HTTP differs by server language; A2A and\n  // AG-UI speak standard protocols so the same script serves both languages.\n  const protocolDir =\n    options.protocol === 'http' ? `http-${options.language}` : options.protocol;\n  generateFiles(\n    tree,\n    joinPathFragments(import.meta.dirname, 'files', protocolDir),\n    options.scriptsDir,\n    templateContext,\n    { overwriteStrategy: OverwriteStrategy.KeepExisting },\n  );\n};\n"],"names":["generateFiles","joinPathFragments","OverwriteStrategy","esmVars","addAgentChatScripts","tree","options","templateContext","agentNameClassName","auth","relativeAgentImport","dirname","scriptsDir","overwriteStrategy","KeepExisting","protocolDir","protocol","language"],"mappings":"AAAA;;;CAGC,GAGD,SACEA,aAAa,EACbC,iBAAiB,EACjBC,iBAAiB,QACZ,aAAa;AACpB,SAASC,OAAO,QAAQ,sBAAmB;AAsB3C;;;;;;CAMC,GACD,OAAO,MAAMC,sBAAsB,CACjCC,MACAC;IAEA,MAAMC,kBAAkB;QACtBC,oBAAoBF,QAAQE,kBAAkB;QAC9CC,MAAMH,QAAQG,IAAI;QAClBC,qBAAqBJ,QAAQI,mBAAmB,IAAI;QACpD,GAAGP,QAAQE,KAAK;IAClB;IAEA,kEAAkE;IAClEL,cACEK,MACAJ,kBAAkB,YAAYU,OAAO,EAAE,SAAS,WAChDL,QAAQM,UAAU,EAClBL,iBACA;QAAEM,mBAAmBX,kBAAkBY,YAAY;IAAC;IAGtD,2EAA2E;IAC3E,2EAA2E;IAC3E,MAAMC,cACJT,QAAQU,QAAQ,KAAK,SAAS,CAAC,KAAK,EAAEV,QAAQW,QAAQ,EAAE,GAAGX,QAAQU,QAAQ;IAC7EhB,cACEK,MACAJ,kBAAkB,YAAYU,OAAO,EAAE,SAASI,cAChDT,QAAQM,UAAU,EAClBL,iBACA;QAAEM,mBAAmBX,kBAAkBY,YAAY;IAAC;AAExD,EAAE"}

package/src/utils/agent-chat/files/a2a/chat.ts.template

@@ -0,0 +1,33 @@
+// Chat CLI for <%- agentNameClassName %> (A2A protocol). Connects to the local
+// `dev` server, or the deployed agent when `RUNTIME_CONFIG_APP_ID` is set.
+import {
+  ClientFactory,
+  ClientFactoryOptions,
+  DefaultAgentCardResolver,
+  JsonRpcTransportFactory,
+} from '@a2a-js/sdk/client';
+import { A2AChatAdapter, chatLoop } from 'agent-chat-cli';
+import { createAgentCoreFetch, resolveRemoteAgent } from './agentcore<% if (esm) { %>.js<% } %>';
+
+const remote = await resolveRemoteAgent();
+
+const url = remote
+  ? `https://bedrock-agentcore.${remote.region}.amazonaws.com/runtimes/${encodeURIComponent(remote.arn)}/invocations/`
+  : process.env.URL!;
+
+// Remote requests are authenticated via a custom fetch; locally the default client talks plain HTTP.
+const clientFactory = remote
+  ? new ClientFactory({
+      ...ClientFactoryOptions.default,
+      transports: [
+        new JsonRpcTransportFactory({
+          fetchImpl: createAgentCoreFetch(<%- auth === 'iam' ? 'remote.region' : '' %>),
+        }),
+      ],
+      cardResolver: new DefaultAgentCardResolver({
+        fetchImpl: createAgentCoreFetch(<%- auth === 'iam' ? 'remote.region' : '' %>),
+      }),
+    })
+  : undefined;
+
+await chatLoop(new A2AChatAdapter({ clientFactory }), url);

package/src/utils/agent-chat/files/ag-ui/chat.ts.template

@@ -0,0 +1,17 @@
+// Chat CLI for <%- agentNameClassName %> (AG-UI protocol). Connects to the local
+// `dev` server, or the deployed agent when `RUNTIME_CONFIG_APP_ID` is set.
+import { AGUIChatAdapter, chatLoop } from 'agent-chat-cli';
+import { createAgentCoreFetch, resolveRemoteAgent } from './agentcore<% if (esm) { %>.js<% } %>';
+
+const remote = await resolveRemoteAgent();
+
+const url = remote
+  ? `https://bedrock-agentcore.${remote.region}.amazonaws.com/runtimes/${encodeURIComponent(remote.arn)}/invocations?qualifier=DEFAULT`
+  : process.env.URL!;
+
+// Remote requests are authenticated via a custom fetch; locally the default agent talks plain HTTP.
+const fetchImpl = remote
+  ? createAgentCoreFetch(<%- auth === 'iam' ? 'remote.region' : '' %>)
+  : undefined;
+
+await chatLoop(new AGUIChatAdapter({ fetch: fetchImpl }), url);

package/src/utils/agent-chat/files/common/agentcore.ts.template

@@ -0,0 +1,81 @@
+// Resolves the deployed <%- agentNameClassName %> agent from runtime config and authenticates requests to it.
+import { randomUUID } from 'node:crypto';
+import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';
+<%_ if (auth === 'iam') { _%>
+import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
+import { AwsClient } from 'aws4fetch';
+<%_ } _%>
+
+const SESSION_HEADER = 'X-Amzn-Bedrock-AgentCore-Runtime-Session-Id';
+
+// AgentCore session ids must be at least 33 characters.
+export const SESSION_ID = randomUUID().replaceAll('-', '').padEnd(33, '0');
+
+export interface RemoteAgent {
+  /** ARN of the deployed Bedrock AgentCore runtime. */
+  arn: string;
+  /** AWS region parsed from the runtime ARN. */
+  region: string;
+}
+
+// Returns the deployed agent when `RUNTIME_CONFIG_APP_ID` is set, otherwise `undefined` to chat locally.
+export const resolveRemoteAgent = async (): Promise<
+  RemoteAgent | undefined
+> => {
+  const application = process.env.RUNTIME_CONFIG_APP_ID;
+  if (!application) {
+    return undefined;
+  }
+  const config = (await getAppConfig('agentcore', {
+    application,
+    environment: 'default',
+    transform: 'json',
+  })) as { agentRuntimes?: Record<string, string> };
+  const arn = config?.agentRuntimes?.['<%- agentNameClassName %>'];
+  if (!arn) {
+    throw new Error(
+      `No deployed agent named '<%- agentNameClassName %>' found in runtime configuration (application ${application}).`,
+    );
+  }
+  return { arn, region: arn.split(':')[3] };
+};
+
+<%_ if (auth === 'cognito') { _%>
+/** The Cognito access token used to authenticate with the deployed agent. */
+export const getAccessToken = (): string => {
+  const accessToken = process.env.AGENT_ACCESS_TOKEN;
+  if (!accessToken) {
+    throw new Error(
+      'AGENT_ACCESS_TOKEN is not set. Provide a Cognito access token to chat with the deployed agent.',
+    );
+  }
+  return accessToken;
+};
+<%_ } _%>
+
+// A `fetch` that authenticates requests to the deployed agent and forwards the session id.
+<%_ if (auth === 'iam') { _%>
+export const createAgentCoreFetch = (region: string): typeof fetch => {
+  const credentialProvider = fromNodeProviderChain();
+  return async (input, init) => {
+    const headers = new Headers(init?.headers);
+    headers.set(SESSION_HEADER, SESSION_ID);
+    const client = new AwsClient({
+      ...(await credentialProvider()),
+      service: 'bedrock-agentcore',
+      region,
+    });
+    return client.fetch(input, { ...init, headers });
+  };
+};
+<%_ } else { _%>
+export const createAgentCoreFetch = (): typeof fetch => {
+  const accessToken = getAccessToken();
+  return (input, init) => {
+    const headers = new Headers(init?.headers);
+    headers.set(SESSION_HEADER, SESSION_ID);
+    headers.set('Authorization', `Bearer ${accessToken}`);
+    return fetch(input, { ...init, headers });
+  };
+};
+<%_ } _%>

package/src/utils/agent-chat/files/http-py/chat.ts.template

@@ -0,0 +1,43 @@
+// Chat CLI for <%- agentNameClassName %> (Python FastAPI / JSONL streaming), using the
+// generated client. Connects to the local `dev` server, or the deployed
+// agent when `RUNTIME_CONFIG_APP_ID` is set.
+import { chatLoop, type ChatAdapter } from 'agent-chat-cli';
+import { <%- agentNameClassName %> } from './generated/client.gen<% if (esm) { %>.js<% } %>';
+import {
+  createAgentCoreFetch,
+  resolveRemoteAgent,
+  SESSION_ID,
+} from './agentcore<% if (esm) { %>.js<% } %>';
+
+const SESSION_ID_HEADER = 'X-Amzn-Bedrock-AgentCore-Runtime-Session-Id';
+
+const remote = await resolveRemoteAgent();
+
+class <%- agentNameClassName %>Adapter implements ChatAdapter {
+  private client!: <%- agentNameClassName %>;
+
+  async connect(url: string) {
+    this.client = remote
+      ? new <%- agentNameClassName %>({
+          url: `https://bedrock-agentcore.${remote.region}.amazonaws.com/runtimes/${encodeURIComponent(remote.arn)}`,
+          fetch: createAgentCoreFetch(<%- auth === 'iam' ? 'remote.region' : '' %>),
+        })
+      : new <%- agentNameClassName %>({
+          url,
+          fetch: (input, init) => {
+            const headers = new Headers(init?.headers);
+            headers.set(SESSION_ID_HEADER, SESSION_ID);
+            return fetch(input, { ...init, headers });
+          },
+        });
+    return { agentName: '<%- agentNameClassName %>' };
+  }
+
+  async *sendMessage(text: string): AsyncIterable<string> {
+    for await (const chunk of this.client.invoke({ prompt: text })) {
+      if (typeof chunk.content === 'string') yield chunk.content;
+    }
+  }
+}
+
+await chatLoop(new <%- agentNameClassName %>Adapter(), process.env.URL ?? '');

package/src/utils/agent-chat/files/http-ts/chat.ts.template

@@ -0,0 +1,54 @@
+// Chat CLI for <%- agentNameClassName %> (HTTP / tRPC WebSocket). Connects to the local
+// `dev` server, or the deployed agent when `RUNTIME_CONFIG_APP_ID` is set.
+import { chatLoop, type ChatAdapter } from 'agent-chat-cli';
+import { <%- agentNameClassName %>Client } from '<%- relativeAgentImport %>/client.js';
+import {
+  resolveRemoteAgent,
+  SESSION_ID,
+<%_ if (auth === 'cognito') { _%>
+  getAccessToken,
+<%_ } _%>
+} from './agentcore<% if (esm) { %>.js<% } %>';
+
+const remote = await resolveRemoteAgent();
+
+class TrpcWebSocketAdapter implements ChatAdapter {
+  private client!: ReturnType<typeof <%- agentNameClassName %>Client.local>;
+
+  async connect(url: string) {
+    this.client = remote
+<%_ if (auth === 'iam') { _%>
+      ? <%- agentNameClassName %>Client.withIamAuth({
+          agentRuntimeArn: remote.arn,
+          sessionId: SESSION_ID,
+        })
+<%_ } else { _%>
+      ? <%- agentNameClassName %>Client.withJwtAuth({
+          agentRuntimeArn: remote.arn,
+          sessionId: SESSION_ID,
+          accessTokenProvider: async () => getAccessToken(),
+        })
+<%_ } _%>
+      : <%- agentNameClassName %>Client.local({ url, sessionId: SESSION_ID });
+    return { agentName: '<%- agentNameClassName %>' };
+  }
+
+  async *sendMessage(text: string): AsyncIterable<string> {
+    const stream = new ReadableStream<string>({
+      start: (controller) => {
+        this.client.invoke.subscribe(
+          { prompt: text },
+          {
+            onData: (chunk: string) => controller.enqueue(chunk),
+            onComplete: () => controller.close(),
+            onError: (err: unknown) => controller.error(err),
+          },
+        );
+      },
+    });
+
+    yield* stream as unknown as AsyncIterable<string>;
+  }
+}
+
+await chatLoop(new TrpcWebSocketAdapter(), process.env.URL ?? '');

package/src/utils/agent-connection/agent-connection.d.ts

@@ -2,7 +2,8 @@
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
-import { Tree } from '@nx/devkit';
+import { type Tree } from '@nx/devkit';
+import { type IPyDepVersion } from '../versions';
 export declare const AGENT_CONNECTION_PROJECT_DIR: string;
 /**
  * Get the directory of the shared Python agent-connection project.
@@ -13,36 +14,62 @@ export declare function getPythonAgentConnectionProjectDir(tree: Tree): string;
  */
 export declare function getPythonAgentConnectionModuleName(tree: Tree): string;
 /**
- * Get the fully qualified Python package name of the shared agent-connection project.
+ * 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 declare function getPythonAgentConnectionPackageName(tree: Tree): string;
+export declare function getPythonAgentConnectionProject(tree: Tree): {
+    name: string;
+    root: string;
+};
 /**
- * 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).
+ * The connection protocols an agent framework can connect over. Each maps to a
+ * framework-agnostic Layer-0/1 template directory plus a per-framework Layer-2
+ * client directory (see `FRAMEWORKS`).
  */
-export declare const TS_CORE_TEMPLATES: {
-    readonly mcp: "core-mcp";
-    readonly a2a: "core-a2a";
-};
-export declare const PY_CORE_TEMPLATES: {
-    readonly mcp: "py-core-mcp";
-    readonly a2a: "py-core-a2a";
-    /** Shared SigV4 `httpx.Auth` used by both MCP and A2A clients. */
-    readonly auth: "py-core-auth";
-};
+export type ConnectionProtocol = 'mcp' | 'gateway' | 'a2a';
+/**
+ * The agent frameworks we can generate connection clients for. Adding a new
+ * framework is an additive change: append an entry to `FRAMEWORKS` with its
+ * Layer-2 template directories and dependencies — the framework-agnostic
+ * Layer-0/1 (`core-auth`, `core-shared`, the per-protocol transports/configs)
+ * is reused unchanged.
+ */
+export type AgentFramework = 'strands' | 'langchain';
+/**
+ * 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 declare function resolveAgentFramework(framework: string | undefined): AgentFramework;
 /**
  * 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.
+ * framework-agnostic core helpers (runtime-config loader, session context).
+ * Per-connection generators emit their own protocol + framework client
+ * templates via `addTypeScriptCoreClient`.
  */
 export declare function ensureTypeScriptAgentConnectionProject(tree: Tree): Promise<void>;
 /**
- * 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.
+ * 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 declare function addTypeScriptFrameworkBase(tree: Tree, framework?: AgentFramework): Promise<void>;
+/**
+ * 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 declare function addTypeScriptCoreClient(tree: Tree, kind: keyof typeof TS_CORE_TEMPLATES): void;
+export declare function addTypeScriptCoreClient(tree: Tree, protocol: ConnectionProtocol, framework?: AgentFramework): Promise<void>;
 /**
  * Ensure the shared Python agent-connection project exists.
  * Only creates the project shell — per-connection generators are responsible
@@ -50,10 +77,75 @@ export declare function addTypeScriptCoreClient(tree: Tree, kind: keyof typeof T
  */
 export declare function ensurePythonAgentConnectionProject(tree: Tree): Promise<void>;
 /**
- * Emit a Python core client template (mcp / a2a / shared auth) into the
- * agent-connection project's core directory.
+ * 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 declare function addPythonFrameworkBase(tree: Tree, framework?: AgentFramework): Promise<void>;
+/**
+ * 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 declare function addPythonCoreClient(tree: Tree, protocol: ConnectionProtocol, framework?: AgentFramework): Promise<void>;
+/**
+ * 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 declare function addTypeScriptClientToAgent(tree: Tree, agentFilePath: string, clientClassName: string, clientVarName: string): Promise<void>;
+/**
+ * Per-framework naming + template layout for a Python per-connection client.
+ * Every py#agent connection generator (mcp, gateway, a2a) names its client
+ * class `<Name>Client<suffix>`, its module `<name>_client_<suffix>`, and reads
+ * the per-connection app-client template from a per-framework sub-path of its
+ * own `files/` dir — all of which vary only by framework, so they live here as
+ * one source of truth.
+ *
+ * Keyed by {@link AgentFramework} rather than a boolean so a third framework is
+ * an additive entry here — never another `if (isLangchain)` branch in each
+ * generator.
+ */
+export interface PyClientNaming {
+    /** Class-name suffix on the per-connection app client (`<Name>Client<suffix>`). */
+    clientClassSuffix: string;
+    /** Module/file-name suffix on the per-connection app client (`<name>_client_<suffix>`). */
+    clientModuleSuffix: string;
+    /**
+     * Sub-path, under a connection generator's `files/` dir, of the per-connection
+     * app client template for this framework. Every connection generator lays its
+     * templates out the same way, so this resolves against any of them.
+     */
+    appTemplateSubdir: string;
+}
+export declare const PY_CLIENT_NAMING: Record<AgentFramework, PyClientNaming>;
+/**
+ * How an MCP-family connection (an MCP server or an AgentCore Gateway, both of
+ * which expose tools over MCP) is wired into a Python agent of a given
+ * framework. The mcp-connection and gateway-connection generators share this:
+ * they differ only in the metadata of the thing being connected, not in how
+ * the framework's client is shaped or spliced into agent.py. A2A connections
+ * wire tools differently, so they reuse only {@link PY_CLIENT_NAMING}.
  */
-export declare function addPythonCoreClient(tree: Tree, kind: keyof typeof PY_CORE_TEMPLATES): void;
+export interface PyMcpFamilyConnection extends PyClientNaming {
+    /** Extra Python deps this framework's MCP-family client needs (beyond the shared transport). */
+    deps: IPyDepVersion[];
+    /**
+     * Splice the per-connection client into the agent's `get_agent` in agent.py.
+     * Strands enters a context-managed `MCPClient` and spreads `list_tools_sync()`;
+     * LangChain loads `BaseTool`s and spreads them into `create_agent(...)`.
+     */
+    wireClientIntoAgent: (tree: Tree, agentFilePath: string, clientClassName: string, clientVarName: string) => Promise<void>;
+}
+export declare const PY_MCP_FAMILY_CONNECTIONS: Record<AgentFramework, PyMcpFamilyConnection>;
 /**
  * Add a re-export to the Python agent-connection module's __init__.py.
  * Equivalent to addStarExport for TS.