@aws/nx-plugin 1.0.0-rc.2 → 1.0.0-rc.21

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

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addAgentChatScripts = void 0;
+const devkit_1 = require("@nx/devkit");
+/**
+ * Emit the chat CLI scripts for an agent. Every protocol gets a small
+ * `chat.ts` that connects to the local `serve-local` 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.
+ */
+const addAgentChatScripts = (tree, options) => {
+    const templateContext = {
+        agentNameClassName: options.agentNameClassName,
+        auth: options.auth,
+        relativeAgentImport: options.relativeAgentImport ?? '',
+    };
+    // Shared remote-resolution + auth helper, used by every protocol.
+    (0, devkit_1.generateFiles)(tree, (0, devkit_1.joinPathFragments)(__dirname, 'files', 'common'), options.scriptsDir, templateContext, { overwriteStrategy: devkit_1.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;
+    (0, devkit_1.generateFiles)(tree, (0, devkit_1.joinPathFragments)(__dirname, 'files', protocolDir), options.scriptsDir, templateContext, { overwriteStrategy: devkit_1.OverwriteStrategy.KeepExisting });
+};
+exports.addAgentChatScripts = addAgentChatScripts;
+//# sourceMappingURL=agent-chat.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-chat.js","sourceRoot":"","sources":["../../../../../../packages/nx-plugin/src/utils/agent-chat/agent-chat.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAGH,uCAIoB;AAsBpB;;;;;;GAMG;AACI,MAAM,mBAAmB,GAAG,CACjC,IAAU,EACV,OAAmC,EAC7B,EAAE;IACR,MAAM,eAAe,GAAG;QACtB,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;QAC9C,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,mBAAmB,EAAE,OAAO,CAAC,mBAAmB,IAAI,EAAE;KACvD,CAAC;IAEF,kEAAkE;IAClE,IAAA,sBAAa,EACX,IAAI,EACJ,IAAA,0BAAiB,EAAC,SAAS,EAAE,OAAO,EAAE,QAAQ,CAAC,EAC/C,OAAO,CAAC,UAAU,EAClB,eAAe,EACf,EAAE,iBAAiB,EAAE,0BAAiB,CAAC,YAAY,EAAE,CACtD,CAAC;IAEF,2EAA2E;IAC3E,2EAA2E;IAC3E,MAAM,WAAW,GACf,OAAO,CAAC,QAAQ,KAAK,MAAM,CAAC,CAAC,CAAC,QAAQ,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IAC9E,IAAA,sBAAa,EACX,IAAI,EACJ,IAAA,0BAAiB,EAAC,SAAS,EAAE,OAAO,EAAE,WAAW,CAAC,EAClD,OAAO,CAAC,UAAU,EAClB,eAAe,EACf,EAAE,iBAAiB,EAAE,0BAAiB,CAAC,YAAY,EAAE,CACtD,CAAC;AACJ,CAAC,CAAC;AA9BW,QAAA,mBAAmB,uBA8B9B"}

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

@@ -0,0 +1,33 @@
+// Chat CLI for <%- agentNameClassName %> (A2A protocol). Connects to the local
+// `serve-local` 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.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
+// `serve-local` server, or the deployed agent when `RUNTIME_CONFIG_APP_ID` is set.
+import { AGUIChatAdapter, chatLoop } from 'agent-chat-cli';
+import { createAgentCoreFetch, resolveRemoteAgent } from './agentcore.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 `serve-local` 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.js';
+import {
+  createAgentCoreFetch,
+  resolveRemoteAgent,
+  SESSION_ID,
+} from './agentcore.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({ message: 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
+// `serve-local` 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.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(
+          { message: 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,7 @@
  * 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';
 export declare const AGENT_CONNECTION_PROJECT_DIR: string;
 /**
  * Get the directory of the shared Python agent-connection project.
@@ -17,32 +17,46 @@ export declare function getPythonAgentConnectionModuleName(tree: Tree): string;
  */
 export declare function getPythonAgentConnectionPackageName(tree: Tree): 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).
- */
-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";
-};
+ * 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 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';
 /**
  * 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 addTypeScriptCoreClient(tree: Tree, kind: keyof typeof TS_CORE_TEMPLATES): void;
+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, 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 +64,39 @@ 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>;
+/**
+ * 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`).
  */
-export declare function addPythonCoreClient(tree: Tree, kind: keyof typeof PY_CORE_TEMPLATES): void;
+export declare function addPythonClientToAgent(tree: Tree, agentFilePath: string, clientClassName: string, clientVarName: string): Promise<void>;
 /**
  * Add a re-export to the Python agent-connection module's __init__.py.
  * Equivalent to addStarExport for TS.