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

package/src/utils/add-dependencies.js

@@ -0,0 +1,83 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { joinPathFragments } from "@nx/devkit";
+import { applicableDependencies } from "./declared-dependencies.js";
+import { addDependenciesToPackageJson } from "./dependencies.js";
+import { addDependenciesToDependencyGroupInPyProjectToml, addDependenciesToPyProjectToml } from "./py.js";
+import { TS_VERSIONS } from "./versions.js";
+/**
+ * The manifest an entry belongs in: the workspace root for shared tooling
+ * (`root: true`), otherwise the project's own.
+ *
+ * A project-level entry with no `projectRoot` is a mistake rather than a default
+ * — silently adding it to the root manifest would leave the project failing
+ * `noUndeclaredDependencies` on a dependency it imports.
+ */ const requireProjectRoot = (entry, projectRoot, generator)=>{
+    if (entry.root) {
+        return undefined;
+    }
+    if (!projectRoot) {
+        throw new Error(`${generator} was called without a projectRoot, but '${String(entry.name)}' is not declared with \`root: true\`. ` + `Pass the project's root, or declare the dependency with \`root: true\` if it belongs to the workspace root.`);
+    }
+    return projectRoot;
+};
+/**
+ * Add every applicable TypeScript dependency from a declaration.
+ *
+ * Runtime deps land in the project's manifest so `noUndeclaredDependencies`
+ * passes; `dev: true` entries go to the root, where shared tooling belongs.
+ */ export const addTsDependencies = (tree, declaration, { metadata = {}, projectRoot } = {})=>{
+    const applicable = applicableDependencies(declaration.ts, metadata);
+    const manifests = new Map();
+    for (const entry of applicable){
+        const root = requireProjectRoot(entry, projectRoot, 'addTsDependencies');
+        const manifestPath = root ? joinPathFragments(root, 'package.json') : 'package.json';
+        const manifest = manifests.get(manifestPath) ?? {
+            runtime: {},
+            dev: {}
+        };
+        manifest[entry.dev ? 'dev' : 'runtime'][entry.name] = TS_VERSIONS[entry.name];
+        manifests.set(manifestPath, manifest);
+    }
+    const callbacks = [
+        ...manifests
+    ].map(([manifestPath, { runtime, dev }])=>addDependenciesToPackageJson(tree, runtime, dev, manifestPath));
+    return async ()=>{
+        for (const callback of callbacks){
+            await callback();
+        }
+    };
+};
+/**
+ * Add every applicable Python dependency from a declaration, routing `group`
+ * entries to their pyproject dependency group.
+ *
+ * `root: true` entries go to the workspace root pyproject, where shared tooling
+ * belongs, mirroring the TypeScript side.
+ */ export const addPyDependencies = (tree, declaration, { metadata = {}, projectRoot } = {})=>{
+    const applicable = applicableDependencies(declaration.py, metadata);
+    // Keyed by the pyproject to write and the group within it, since one
+    // declaration may span the project's and the workspace root's.
+    const buckets = new Map();
+    for (const entry of applicable){
+        const root = requireProjectRoot(entry, projectRoot, 'addPyDependencies') ?? '.';
+        const key = `${root}\0${entry.group ?? ''}`;
+        const bucket = buckets.get(key) ?? {
+            root,
+            group: entry.group,
+            names: []
+        };
+        bucket.names.push(entry.name);
+        buckets.set(key, bucket);
+    }
+    for (const { root, group, names } of buckets.values()){
+        if (group) {
+            addDependenciesToDependencyGroupInPyProjectToml(tree, root, group, declaration, names);
+        } else {
+            addDependenciesToPyProjectToml(tree, root, declaration, names);
+        }
+    }
+};
+
+//# sourceMappingURL=add-dependencies.js.map

package/src/utils/add-dependencies.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../packages/nx-plugin/src/utils/add-dependencies.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  type GeneratorCallback,\n  joinPathFragments,\n  type Tree,\n} from '@nx/devkit';\nimport {\n  applicableDependencies,\n  type DependencyDeclaration,\n  type DependencyMetadata,\n} from './declared-dependencies';\nimport { addDependenciesToPackageJson } from './dependencies';\nimport {\n  addDependenciesToDependencyGroupInPyProjectToml,\n  addDependenciesToPyProjectToml,\n} from './py';\nimport { TS_VERSIONS } from './versions';\n\n/**\n * Add the dependencies a declaration says apply, so the declaration is the only\n * place packages are listed.\n *\n * Pass the very object recorded as the project's metadata: the version sync\n * migration replays the same predicates against it, so what a generator adds and\n * what the migration owns cannot drift.\n */\nexport interface AddDependenciesOptions {\n  /** The metadata the declaration's `when` predicates read. */\n  readonly metadata?: DependencyMetadata;\n  /**\n   * Project whose manifests receive the dependencies. Required unless every\n   * applicable entry is marked `root`, which targets the workspace root instead.\n   */\n  readonly projectRoot?: string;\n}\n\n/**\n * The manifest an entry belongs in: the workspace root for shared tooling\n * (`root: true`), otherwise the project's own.\n *\n * A project-level entry with no `projectRoot` is a mistake rather than a default\n * — silently adding it to the root manifest would leave the project failing\n * `noUndeclaredDependencies` on a dependency it imports.\n */\nconst requireProjectRoot = (\n  entry: { name: unknown; root?: boolean },\n  projectRoot: string | undefined,\n  generator: string,\n): string | undefined => {\n  if (entry.root) {\n    return undefined;\n  }\n  if (!projectRoot) {\n    throw new Error(\n      `${generator} was called without a projectRoot, but '${String(entry.name)}' is not declared with \\`root: true\\`. ` +\n        `Pass the project's root, or declare the dependency with \\`root: true\\` if it belongs to the workspace root.`,\n    );\n  }\n  return projectRoot;\n};\n\n/**\n * Add every applicable TypeScript dependency from a declaration.\n *\n * Runtime deps land in the project's manifest so `noUndeclaredDependencies`\n * passes; `dev: true` entries go to the root, where shared tooling belongs.\n */\nexport const addTsDependencies = (\n  tree: Tree,\n  declaration: DependencyDeclaration,\n  { metadata = {}, projectRoot }: AddDependenciesOptions = {},\n): GeneratorCallback => {\n  const applicable = applicableDependencies(declaration.ts, metadata);\n  const manifests = new Map<\n    string,\n    { runtime: Record<string, string>; dev: Record<string, string> }\n  >();\n  for (const entry of applicable) {\n    const root = requireProjectRoot(entry, projectRoot, 'addTsDependencies');\n    const manifestPath = root\n      ? joinPathFragments(root, 'package.json')\n      : 'package.json';\n    const manifest = manifests.get(manifestPath) ?? { runtime: {}, dev: {} };\n    manifest[entry.dev ? 'dev' : 'runtime'][entry.name as string] =\n      TS_VERSIONS[entry.name];\n    manifests.set(manifestPath, manifest);\n  }\n\n  const callbacks = [...manifests].map(([manifestPath, { runtime, dev }]) =>\n    addDependenciesToPackageJson(tree, runtime, dev, manifestPath),\n  );\n  return async () => {\n    for (const callback of callbacks) {\n      await callback();\n    }\n  };\n};\n\n/**\n * Add every applicable Python dependency from a declaration, routing `group`\n * entries to their pyproject dependency group.\n *\n * `root: true` entries go to the workspace root pyproject, where shared tooling\n * belongs, mirroring the TypeScript side.\n */\nexport const addPyDependencies = (\n  tree: Tree,\n  declaration: DependencyDeclaration,\n  { metadata = {}, projectRoot }: AddDependenciesOptions = {},\n): void => {\n  const applicable = applicableDependencies(declaration.py, metadata);\n\n  // Keyed by the pyproject to write and the group within it, since one\n  // declaration may span the project's and the workspace root's.\n  const buckets = new Map<\n    string,\n    { root: string; group?: string; names: string[] }\n  >();\n  for (const entry of applicable) {\n    const root =\n      requireProjectRoot(entry, projectRoot, 'addPyDependencies') ?? '.';\n    const key = `${root}\\0${entry.group ?? ''}`;\n    const bucket = buckets.get(key) ?? { root, group: entry.group, names: [] };\n    bucket.names.push(entry.name as string);\n    buckets.set(key, bucket);\n  }\n\n  for (const { root, group, names } of buckets.values()) {\n    if (group) {\n      addDependenciesToDependencyGroupInPyProjectToml(\n        tree,\n        root,\n        group,\n        declaration,\n        names as never,\n      );\n    } else {\n      addDependenciesToPyProjectToml(tree, root, declaration, names as never);\n    }\n  }\n};\n"],"names":["joinPathFragments","applicableDependencies","addDependenciesToPackageJson","addDependenciesToDependencyGroupInPyProjectToml","addDependenciesToPyProjectToml","TS_VERSIONS","requireProjectRoot","entry","projectRoot","generator","root","undefined","Error","String","name","addTsDependencies","tree","declaration","metadata","applicable","ts","manifests","Map","manifestPath","manifest","get","runtime","dev","set","callbacks","map","callback","addPyDependencies","py","buckets","key","group","bucket","names","push","values"],"mappings":"AAAA;;;CAGC,GACD,SAEEA,iBAAiB,QAEZ,aAAa;AACpB,SACEC,sBAAsB,QAGjB,6BAA0B;AACjC,SAASC,4BAA4B,QAAQ,oBAAiB;AAC9D,SACEC,+CAA+C,EAC/CC,8BAA8B,QACzB,UAAO;AACd,SAASC,WAAW,QAAQ,gBAAa;AAoBzC;;;;;;;CAOC,GACD,MAAMC,qBAAqB,CACzBC,OACAC,aACAC;IAEA,IAAIF,MAAMG,IAAI,EAAE;QACd,OAAOC;IACT;IACA,IAAI,CAACH,aAAa;QAChB,MAAM,IAAII,MACR,GAAGH,UAAU,wCAAwC,EAAEI,OAAON,MAAMO,IAAI,EAAE,uCAAuC,CAAC,GAChH,CAAC,2GAA2G,CAAC;IAEnH;IACA,OAAON;AACT;AAEA;;;;;CAKC,GACD,OAAO,MAAMO,oBAAoB,CAC/BC,MACAC,aACA,EAAEC,WAAW,CAAC,CAAC,EAAEV,WAAW,EAA0B,GAAG,CAAC,CAAC;IAE3D,MAAMW,aAAalB,uBAAuBgB,YAAYG,EAAE,EAAEF;IAC1D,MAAMG,YAAY,IAAIC;IAItB,KAAK,MAAMf,SAASY,WAAY;QAC9B,MAAMT,OAAOJ,mBAAmBC,OAAOC,aAAa;QACpD,MAAMe,eAAeb,OACjBV,kBAAkBU,MAAM,kBACxB;QACJ,MAAMc,WAAWH,UAAUI,GAAG,CAACF,iBAAiB;YAAEG,SAAS,CAAC;YAAGC,KAAK,CAAC;QAAE;QACvEH,QAAQ,CAACjB,MAAMoB,GAAG,GAAG,QAAQ,UAAU,CAACpB,MAAMO,IAAI,CAAW,GAC3DT,WAAW,CAACE,MAAMO,IAAI,CAAC;QACzBO,UAAUO,GAAG,CAACL,cAAcC;IAC9B;IAEA,MAAMK,YAAY;WAAIR;KAAU,CAACS,GAAG,CAAC,CAAC,CAACP,cAAc,EAAEG,OAAO,EAAEC,GAAG,EAAE,CAAC,GACpEzB,6BAA6Bc,MAAMU,SAASC,KAAKJ;IAEnD,OAAO;QACL,KAAK,MAAMQ,YAAYF,UAAW;YAChC,MAAME;QACR;IACF;AACF,EAAE;AAEF;;;;;;CAMC,GACD,OAAO,MAAMC,oBAAoB,CAC/BhB,MACAC,aACA,EAAEC,WAAW,CAAC,CAAC,EAAEV,WAAW,EAA0B,GAAG,CAAC,CAAC;IAE3D,MAAMW,aAAalB,uBAAuBgB,YAAYgB,EAAE,EAAEf;IAE1D,qEAAqE;IACrE,+DAA+D;IAC/D,MAAMgB,UAAU,IAAIZ;IAIpB,KAAK,MAAMf,SAASY,WAAY;QAC9B,MAAMT,OACJJ,mBAAmBC,OAAOC,aAAa,wBAAwB;QACjE,MAAM2B,MAAM,GAAGzB,KAAK,EAAE,EAAEH,MAAM6B,KAAK,IAAI,IAAI;QAC3C,MAAMC,SAASH,QAAQT,GAAG,CAACU,QAAQ;YAAEzB;YAAM0B,OAAO7B,MAAM6B,KAAK;YAAEE,OAAO,EAAE;QAAC;QACzED,OAAOC,KAAK,CAACC,IAAI,CAAChC,MAAMO,IAAI;QAC5BoB,QAAQN,GAAG,CAACO,KAAKE;IACnB;IAEA,KAAK,MAAM,EAAE3B,IAAI,EAAE0B,KAAK,EAAEE,KAAK,EAAE,IAAIJ,QAAQM,MAAM,GAAI;QACrD,IAAIJ,OAAO;YACTjC,gDACEa,MACAN,MACA0B,OACAnB,aACAqB;QAEJ,OAAO;YACLlC,+BAA+BY,MAAMN,MAAMO,aAAaqB;QAC1D;IACF;AACF,EAAE"}

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, { arn: string }> };
+  const arn = config?.agentRuntimes?.['<%- agentNameClassName %>']?.arn;
+  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

@@ -3,6 +3,28 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { type Tree } from '@nx/devkit';
+import { type DependencyDeclaration, type MustDeclare, type MustDeclarePy } from '../declared-dependencies';
+import { type IPyDepVersion } from '../versions';
+/** TypeScript dependencies a caller must declare to emit agent-connection clients. */
+export declare const AGENT_CONNECTION_DEPENDENCIES: readonly [{
+    readonly name: "@aws-lambda-powertools/parameters";
+}, {
+    readonly name: "@aws-sdk/credential-providers";
+}, {
+    readonly name: "aws4fetch";
+}, {
+    readonly name: "@modelcontextprotocol/sdk";
+}, {
+    readonly name: "@a2a-js/sdk";
+}, {
+    readonly name: "@strands-agents/sdk";
+}];
+/** Python dependencies a caller must declare to emit agent-connection clients. */
+export declare const AGENT_CONNECTION_PY_DEPENDENCIES: readonly [{
+    readonly name: "aws-lambda-powertools";
+}, {
+    readonly name: "strands-agents";
+}];
 export declare const AGENT_CONNECTION_PROJECT_DIR: string;
 /**
  * Get the directory of the shared Python agent-connection project.
@@ -13,47 +35,138 @@ 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<const D extends DependencyDeclaration>(tree: Tree, declaration: D & MustDeclare<typeof AGENT_CONNECTION_DEPENDENCIES, D>): Promise<void>;
+/**
+ * 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 ensureTypeScriptAgentConnectionProject(tree: Tree): Promise<void>;
+export declare function addTypeScriptFrameworkBase<const D extends DependencyDeclaration>(tree: Tree, declaration: D & MustDeclare<typeof AGENT_CONNECTION_DEPENDENCIES, D>, framework?: AgentFramework): 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 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<const D extends DependencyDeclaration>(tree: Tree, protocol: ConnectionProtocol, declaration: D & MustDeclare<typeof AGENT_CONNECTION_DEPENDENCIES, D>, framework?: AgentFramework): Promise<void>;
 /**
  * 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.
  */
-export declare function ensurePythonAgentConnectionProject(tree: Tree): Promise<void>;
+export declare function ensurePythonAgentConnectionProject<const D extends DependencyDeclaration>(tree: Tree, declaration: D & MustDeclarePy<typeof AGENT_CONNECTION_PY_DEPENDENCIES, D>): Promise<void>;
+/**
+ * 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<const D extends DependencyDeclaration>(tree: Tree, declaration: D & MustDeclarePy<typeof AGENT_CONNECTION_PY_DEPENDENCIES, D>, 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<const D extends DependencyDeclaration>(tree: Tree, protocol: ConnectionProtocol, declaration: D & MustDeclarePy<typeof AGENT_CONNECTION_PY_DEPENDENCIES, D>, 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>;
 /**
- * Emit a Python core client template (mcp / a2a / shared auth) into the
- * agent-connection project's core directory.
+ * 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.