@aws/nx-plugin 1.0.0-rc.67 → 1.0.0-rc.69

package/README.md

@@ -177,6 +177,7 @@ pnpm nx g @aws/nx-plugin:ts#infra
 | `py#lambda-function`    | Python Lambda with type-safe event sources                                                                        |
 | `py#mcp-server`         | MCP server (Python)                                                                                               |
 | `py#agent`              | [Strands Agent](https://strandsagents.com/) (Python)                                                              |
+| `agentcore-harness`     | [AgentCore Harness](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness.html) agent loop        |
 | `connection`            | Connect projects together (e.g. frontend to API)                                                                  |
 | `terraform#project`     | Terraform project                                                                                                 |
 | `license`               | Manage LICENSE files and source headers                                                                           |

package/generators.json

@@ -44,6 +44,13 @@
       "metric": "g70",
       "hidden": true
     },
+    "agentcore-harness": {
+      "factory": "./src/agentcore-harness/generator",
+      "schema": "./src/agentcore-harness/schema.json",
+      "description": "Generate an AgentCore Harness project",
+      "metric": "g71",
+      "guidePages": ["agentcore-harness"]
+    },
     "connection": {
       "factory": "./src/connection/generator",
       "schema": "./src/connection/schema.json",

package/migrations.json

@@ -7,6 +7,11 @@
       "description": "Move Smithy APIs onto the renamed @smithy/server-* packages",
       "implementation": "./src/migrations/latest/smithy-server-package-rename/migration"
     },
+    "latest-translate-script-whole-file-writes": {
+      "version": "1.0.0-rc.68",
+      "description": "Update the docs translate script to write whole translated files rather than editing them in place",
+      "implementation": "./src/migrations/latest/translate-script-whole-file-writes/migration"
+    },
     "v1.0.0-rc.50-0001-modernize-function-props-cast": {
       "version": "1.0.0-rc.50",
       "description": "Replace the legacy angle-bracket FunctionProps type assertion with the modern as syntax in generated API constructs",
@@ -103,7 +108,7 @@
       "implementation": "./src/migrations/v1.0.0-rc.65/0002-rolldown-code-splitting/migration"
     },
     "sync-vended-versions": {
-      "version": "1.0.0-rc.67",
+      "version": "1.0.0-rc.69",
       "description": "Sync vended dependency versions and the tracked plugin version to those vended by this release",
       "implementation": "./src/utils/version-upgrade-migration/migration"
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/nx-plugin",
-  "version": "1.0.0-rc.67",
+  "version": "1.0.0-rc.69",
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/nx-plugin-for-aws.git",

package/src/agentcore-harness/__snapshots__/generator.spec.ts.snap

@@ -0,0 +1,238 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`agentcore-harness generator > snapshot > snapshots the four rendered harness project files > packages/my-harness/README.md 1`] = `
+"# @proj/my-harness
+
+An [Amazon Bedrock AgentCore Harness](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness.html)
+project generated with [@aws/nx-plugin](https://github.com/awslabs/nx-plugin-for-aws/).
+A Harness is a managed agent loop that AWS runs for you, so this project
+holds only the prompt that shapes it and a script for talking to it:
+
+- \`src/PROMPT.md\` — the system prompt
+- \`scripts/chat.ts\` — a multi-turn chat client for the deployed Harness
+- \`project.json\` — declares the \`chat\` target
+- \`README.md\` — this file
+
+The Harness itself is deployed by the generated CDK construct or Terraform
+module through your usual infrastructure workflow.
+
+## The system prompt
+
+\`src/PROMPT.md\` is the Harness system prompt. Your infrastructure reads the
+file when you synthesize (CDK) or plan (Terraform), so edit it and redeploy
+to change how the Harness behaves.
+
+The prompt is deployment configuration rather than secret storage: its
+contents appear in the synthesized CloudFormation template or in Terraform
+state.
+
+## Chatting with your Harness
+
+\`\`\`bash
+pnpm nx run @proj/my-harness:chat
+\`\`\`
+
+Every turn of a run shares one session, so the Harness keeps the
+conversation context until you exit.
+
+The Harness ARN is resolved in this order:
+
+1. \`HARNESS_ARN\`, used directly:
+
+   \`\`\`bash
+   HARNESS_ARN=<harness-arn> pnpm nx run @proj/my-harness:chat
+   \`\`\`
+
+2. \`RUNTIME_CONFIG_APP_ID\`, which reads the
+   \`agentcore.harnesses.MyHarness\` entry your deployed
+   infrastructure publishes:
+
+   \`\`\`bash
+   RUNTIME_CONFIG_APP_ID=<application-id> pnpm nx run @proj/my-harness:chat
+   \`\`\`
+
+With neither set, the script fails with an error naming both. The AWS Region
+is derived from the Harness ARN, and credentials come from the standard AWS
+SDK credential provider chain.
+
+A caller needs \`bedrock-agentcore:InvokeHarness\` and
+\`bedrock-agentcore:InvokeAgentRuntime\` on the Harness ARN. The CDK
+construct's \`grantInvokeAccess\` grants exactly those two actions.
+
+## Customizing your Harness
+
+Edit \`src/PROMPT.md\` for the system prompt. Everything else is configured
+where you instantiate the infrastructure — including tools, which the
+Harness deploys without:
+
+- CDK construct props, for example
+  \`new MyHarness(this, 'MyHarness', { allowedTools: ['@builtin'] })\`
+- Terraform, by setting \`allowed_tools = ["@builtin"]\` on the module's
+  \`aws_bedrockagentcore_harness\` resource, or by adding an \`allowed_tools\`
+  variable if you would rather set it as a module argument
+
+The generated infrastructure is also yours to edit directly:
+
+- \`packages/common/constructs/src/app/harnesses/my-harness/my-harness.ts\`
+- \`packages/common/terraform/src/app/harnesses/my-harness/my-harness.tf\`
+
+Re-running the generator only adds missing files, so your edits to these
+files and to \`src/PROMPT.md\` are preserved.
+
+## Further reading
+
+- [AgentCore Harness guide](https://awslabs.github.io/nx-plugin-for-aws/guides/agentcore-harness/)
+- [Amazon Bedrock AgentCore Harness documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness.html)
+- [Learn more about Nx](https://nx.dev/getting-started/intro)
+"
+`;
+
+exports[`agentcore-harness generator > snapshot > snapshots the four rendered harness project files > packages/my-harness/project.json 1`] = `
+"{
+  "name": "@proj/my-harness",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "projectType": "application",
+  "sourceRoot": "packages/my-harness",
+  "tags": [],
+  "metadata": {
+    "generator": "agentcore-harness",
+    "name": "my-harness",
+    "rc": "MyHarness",
+    "auth": "iam",
+    "iac": "cdk"
+  },
+  "targets": {
+    "chat": {
+      "executor": "nx:run-commands",
+      "options": {
+        "commands": ["tsx ./scripts/chat.ts"],
+        "cwd": "{projectRoot}"
+      }
+    }
+  }
+}
+"
+`;
+
+exports[`agentcore-harness generator > snapshot > snapshots the four rendered harness project files > packages/my-harness/scripts/chat.ts 1`] = `
+"// Chat CLI for MyHarness. Invokes the deployed Harness with InvokeHarness.
+import { randomUUID } from 'node:crypto';
+import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';
+import {
+  BedrockAgentCoreClient,
+  InvokeHarnessCommand,
+} from '@aws-sdk/client-bedrock-agentcore';
+import { chatLoop, type ChatAdapter } from 'agent-chat-cli';
+
+// The deployed infrastructure publishes the Harness ARN at
+// \`agentcore.harnesses.MyHarness\`.
+const HARNESS_RUNTIME_CONFIG_KEY = 'MyHarness';
+
+// One session id per run, so every turn continues the same Harness session.
+const SESSION_ID = randomUUID();
+
+// Empty strings count as absent, so \`HARNESS_ARN= nx run ...\` still discovers.
+const isPresent = (value: string | undefined): value is string =>
+  value !== undefined && value !== '';
+
+// \`HARNESS_ARN\` wins; \`RUNTIME_CONFIG_APP_ID\` reads the runtime configuration.
+const resolveHarnessArn = async (): Promise<string> => {
+  if (isPresent(process.env.HARNESS_ARN)) {
+    return process.env.HARNESS_ARN;
+  }
+  const application = process.env.RUNTIME_CONFIG_APP_ID;
+  if (!isPresent(application)) {
+    throw new Error(
+      'No Harness ARN source is configured. Set HARNESS_ARN to the deployed ' +
+        'Harness ARN directly, or set RUNTIME_CONFIG_APP_ID to the AppConfig ' +
+        'application ID emitted by your infrastructure stack.',
+    );
+  }
+  const config = (await getAppConfig('agentcore', {
+    application,
+    environment: 'default',
+    transform: 'json',
+  })) as { harnesses?: Record<string, string | undefined> };
+  const harnessArn = config?.harnesses?.[HARNESS_RUNTIME_CONFIG_KEY];
+  if (!harnessArn) {
+    throw new Error(
+      \`Runtime configuration for application '\${application}' has no value \` +
+        \`at 'agentcore.harnesses.\${HARNESS_RUNTIME_CONFIG_KEY}'. Deploy the \` +
+        'Harness infrastructure first, or set HARNESS_ARN directly.',
+    );
+  }
+  return harnessArn;
+};
+
+const HARNESS_ARN = await resolveHarnessArn();
+
+// Region comes from the ARN, and credentials from the standard AWS SDK
+// default provider chain, so no Region is embedded in this project.
+const client = new BedrockAgentCoreClient({
+  region: HARNESS_ARN.split(':')[3],
+});
+
+class HarnessAdapter implements ChatAdapter {
+  async connect() {
+    return { agentName: 'MyHarness' };
+  }
+
+  async *sendMessage(text: string): AsyncIterable<string> {
+    const { stream } = await client.send(
+      new InvokeHarnessCommand({
+        harnessArn: HARNESS_ARN,
+        runtimeSessionId: SESSION_ID,
+        messages: [{ role: 'user', content: [{ text }] }],
+      }),
+    );
+    if (!stream) {
+      throw new Error(
+        'AgentCore returned no event stream for the invocation. Confirm the ' +
+          'Harness is deployed and the caller has the ' +
+          'bedrock-agentcore:InvokeHarness permission.',
+      );
+    }
+    for await (const event of stream) {
+      const serviceError =
+        event.internalServerException ??
+        event.validationException ??
+        event.runtimeClientError;
+      if (serviceError) {
+        const detail = [serviceError.name, serviceError.message]
+          .filter(Boolean)
+          .join(': ');
+        throw new Error(
+          \`Harness invocation failed: \${detail || JSON.stringify(serviceError)}\`,
+        );
+      }
+      const chunk = event.contentBlockDelta?.delta?.text;
+      if (chunk) {
+        yield chunk;
+      }
+    }
+  }
+}
+
+await chatLoop(new HarnessAdapter(), '');
+"
+`;
+
+exports[`agentcore-harness generator > snapshot > snapshots the four rendered harness project files > packages/my-harness/src/PROMPT.md 1`] = `
+"# MyHarness
+
+You are a helpful AI assistant.
+
+## Responding
+
+- Lead with the answer, then the supporting detail.
+- Keep the response proportional to the request: short answers to simple
+  questions, thorough answers to involved ones.
+- Ask for the detail you need when a request is ambiguous instead of guessing.
+- Say when you do not know something, and say what would settle it.
+
+## Using tools
+
+When tools are available, prefer them over recollection for anything you can
+look up, and report what a tool returned, including when it fails.
+"
+`;

package/src/agentcore-harness/files/project/README.md.template

@@ -0,0 +1,83 @@
+# <%- fullyQualifiedName %>
+
+An [Amazon Bedrock AgentCore Harness](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness.html)
+project generated with [@aws/nx-plugin](https://github.com/awslabs/nx-plugin-for-aws/).
+A Harness is a managed agent loop that AWS runs for you, so this project
+holds only the prompt that shapes it and a script for talking to it:
+
+- `src/PROMPT.md` — the system prompt
+- `scripts/chat.ts` — a multi-turn chat client for the deployed Harness
+- `project.json` — declares the `chat` target
+- `README.md` — this file
+
+The Harness itself is deployed by the generated CDK construct or Terraform
+module through your usual infrastructure workflow.
+
+## The system prompt
+
+`src/PROMPT.md` is the Harness system prompt. Your infrastructure reads the
+file when you synthesize (CDK) or plan (Terraform), so edit it and redeploy
+to change how the Harness behaves.
+
+The prompt is deployment configuration rather than secret storage: its
+contents appear in the synthesized CloudFormation template or in Terraform
+state.
+
+## Chatting with your Harness
+
+```bash
+pnpm nx run <%- fullyQualifiedName %>:chat
+```
+
+Every turn of a run shares one session, so the Harness keeps the
+conversation context until you exit.
+
+The Harness ARN is resolved in this order:
+
+1. `HARNESS_ARN`, used directly:
+
+   ```bash
+   HARNESS_ARN=<harness-arn> pnpm nx run <%- fullyQualifiedName %>:chat
+   ```
+
+2. `RUNTIME_CONFIG_APP_ID`, which reads the
+   `agentcore.harnesses.<%- nameClassName %>` entry your deployed
+   infrastructure publishes:
+
+   ```bash
+   RUNTIME_CONFIG_APP_ID=<application-id> pnpm nx run <%- fullyQualifiedName %>:chat
+   ```
+
+With neither set, the script fails with an error naming both. The AWS Region
+is derived from the Harness ARN, and credentials come from the standard AWS
+SDK credential provider chain.
+
+A caller needs `bedrock-agentcore:InvokeHarness` and
+`bedrock-agentcore:InvokeAgentRuntime` on the Harness ARN. The CDK
+construct's `grantInvokeAccess` grants exactly those two actions.
+
+## Customizing your Harness
+
+Edit `src/PROMPT.md` for the system prompt. Everything else is configured
+where you instantiate the infrastructure — including tools, which the
+Harness deploys without:
+
+- CDK construct props, for example
+  `new <%- nameClassName %>(this, '<%- nameClassName %>', { allowedTools: ['@builtin'] })`
+- Terraform, by setting `allowed_tools = ["@builtin"]` on the module's
+  `aws_bedrockagentcore_harness` resource, or by adding an `allowed_tools`
+  variable if you would rather set it as a module argument
+
+The generated infrastructure is also yours to edit directly:
+
+- `packages/common/constructs/src/app/harnesses/<%- nameKebabCase %>/<%- nameKebabCase %>.ts`
+- `packages/common/terraform/src/app/harnesses/<%- nameKebabCase %>/<%- nameKebabCase %>.tf`
+
+Re-running the generator only adds missing files, so your edits to these
+files and to `src/PROMPT.md` are preserved.
+
+## Further reading
+
+- [AgentCore Harness guide](https://awslabs.github.io/nx-plugin-for-aws/guides/agentcore-harness/)
+- [Amazon Bedrock AgentCore Harness documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness.html)
+- [Learn more about Nx](https://nx.dev/getting-started/intro)

package/src/agentcore-harness/files/project/scripts/chat.ts.template

@@ -0,0 +1,99 @@
+// Chat CLI for <%- nameClassName %>. Invokes the deployed Harness with InvokeHarness.
+import { randomUUID } from 'node:crypto';
+import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';
+import {
+  BedrockAgentCoreClient,
+  InvokeHarnessCommand,
+} from '@aws-sdk/client-bedrock-agentcore';
+import { chatLoop, type ChatAdapter } from 'agent-chat-cli';
+
+// The deployed infrastructure publishes the Harness ARN at
+// `agentcore.harnesses.<%- nameClassName %>`.
+const HARNESS_RUNTIME_CONFIG_KEY = '<%- nameClassName %>';
+
+// One session id per run, so every turn continues the same Harness session.
+const SESSION_ID = randomUUID();
+
+// Empty strings count as absent, so `HARNESS_ARN= nx run ...` still discovers.
+const isPresent = (value: string | undefined): value is string =>
+  value !== undefined && value !== '';
+
+// `HARNESS_ARN` wins; `RUNTIME_CONFIG_APP_ID` reads the runtime configuration.
+const resolveHarnessArn = async (): Promise<string> => {
+  if (isPresent(process.env.HARNESS_ARN)) {
+    return process.env.HARNESS_ARN;
+  }
+  const application = process.env.RUNTIME_CONFIG_APP_ID;
+  if (!isPresent(application)) {
+    throw new Error(
+      'No Harness ARN source is configured. Set HARNESS_ARN to the deployed ' +
+        'Harness ARN directly, or set RUNTIME_CONFIG_APP_ID to the AppConfig ' +
+        'application ID emitted by your infrastructure stack.',
+    );
+  }
+  const config = (await getAppConfig('agentcore', {
+    application,
+    environment: 'default',
+    transform: 'json',
+  })) as { harnesses?: Record<string, string | undefined> };
+  const harnessArn = config?.harnesses?.[HARNESS_RUNTIME_CONFIG_KEY];
+  if (!harnessArn) {
+    throw new Error(
+      `Runtime configuration for application '${application}' has no value ` +
+        `at 'agentcore.harnesses.${HARNESS_RUNTIME_CONFIG_KEY}'. Deploy the ` +
+        'Harness infrastructure first, or set HARNESS_ARN directly.',
+    );
+  }
+  return harnessArn;
+};
+
+const HARNESS_ARN = await resolveHarnessArn();
+
+// Region comes from the ARN, and credentials from the standard AWS SDK
+// default provider chain, so no Region is embedded in this project.
+const client = new BedrockAgentCoreClient({
+  region: HARNESS_ARN.split(':')[3],
+});
+
+class HarnessAdapter implements ChatAdapter {
+  async connect() {
+    return { agentName: '<%- nameClassName %>' };
+  }
+
+  async *sendMessage(text: string): AsyncIterable<string> {
+    const { stream } = await client.send(
+      new InvokeHarnessCommand({
+        harnessArn: HARNESS_ARN,
+        runtimeSessionId: SESSION_ID,
+        messages: [{ role: 'user', content: [{ text }] }],
+      }),
+    );
+    if (!stream) {
+      throw new Error(
+        'AgentCore returned no event stream for the invocation. Confirm the ' +
+          'Harness is deployed and the caller has the ' +
+          'bedrock-agentcore:InvokeHarness permission.',
+      );
+    }
+    for await (const event of stream) {
+      const serviceError =
+        event.internalServerException ??
+        event.validationException ??
+        event.runtimeClientError;
+      if (serviceError) {
+        const detail = [serviceError.name, serviceError.message]
+          .filter(Boolean)
+          .join(': ');
+        throw new Error(
+          `Harness invocation failed: ${detail || JSON.stringify(serviceError)}`,
+        );
+      }
+      const chunk = event.contentBlockDelta?.delta?.text;
+      if (chunk) {
+        yield chunk;
+      }
+    }
+  }
+}
+
+await chatLoop(new HarnessAdapter(), '');

package/src/agentcore-harness/files/project/src/PROMPT.md.template

@@ -0,0 +1,16 @@
+# <%- nameClassName %>
+
+You are a helpful AI assistant.
+
+## Responding
+
+- Lead with the answer, then the supporting detail.
+- Keep the response proportional to the request: short answers to simple
+  questions, thorough answers to involved ones.
+- Ask for the detail you need when a request is ambiguous instead of guessing.
+- Say when you do not know something, and say what would settle it.
+
+## Using tools
+
+When tools are available, prefer them over recollection for anything you can
+look up, and report what a tool returned, including when it fails.

package/src/agentcore-harness/generator.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type GeneratorCallback, type ProjectConfiguration, type Tree } from '@nx/devkit';
+import { type NxGeneratorInfo } from '../utils/nx';
+import type { IacMetadata } from '../utils/shared-constructs-constants';
+import type { AgentcoreHarnessGeneratorSchema } from './schema';
+export declare const DEPENDENCIES: import("../utils/declared-dependencies").DependencyDeclaration<readonly [{
+    readonly name: "@aws-sdk/client-bedrock-agentcore";
+    readonly root: true;
+}, {
+    readonly name: "@aws-sdk/client-appconfigdata";
+    readonly root: true;
+}, {
+    readonly name: "@aws-lambda-powertools/parameters";
+    readonly root: true;
+}, {
+    readonly name: "agent-chat-cli";
+    readonly root: true;
+}, {
+    readonly name: "@types/node";
+    readonly dev: true;
+    readonly root: true;
+}, {
+    readonly name: "tsx";
+    readonly dev: true;
+    readonly root: true;
+}, {
+    readonly name: "constructs";
+    readonly when: (m: IacMetadata) => boolean;
+} & {
+    versionOnly: true;
+}, {
+    readonly name: "aws-cdk-lib";
+    readonly when: (m: IacMetadata) => boolean;
+} & {
+    versionOnly: true;
+}, {
+    readonly name: "@types/node";
+} & {
+    versionOnly: true;
+}], readonly import("../utils/declared-dependencies").DeclaredPyDependency<"a2a-sdk" | "ag-ui-langgraph" | "ag-ui-protocol" | "ag-ui-strands" | "aws-lambda-powertools" | "aws-lambda-powertools[tracer]" | "aws-lambda-powertools[parser]" | "aws-opentelemetry-distro" | "bedrock-agentcore" | "boto3" | "checkov" | "fastapi" | "fastapi[standard]" | "httpx" | "langchain" | "langchain-aws" | "langchain-mcp-adapters" | "langgraph" | "mcp" | "pip-check-updates" | "pip-licenses" | "ruff" | "strands-agents" | "strands-agents[a2a]" | "strands-agents-tools" | "ty" | "pynamodb" | "uvicorn" | "sqlmodel" | "alembic" | "aiomysql" | "asyncpg" | "greenlet", AgentCoreHarnessMetadata>[]>;
+export declare const AGENTCORE_HARNESS_GENERATOR_INFO: NxGeneratorInfo;
+export declare const agentcoreHarnessGenerator: (tree: Tree, options: AgentcoreHarnessGeneratorSchema) => Promise<GeneratorCallback>;
+/**
+ * Harness details stored in the Harness Project's metadata. `iac` records which
+ * provider's infrastructure was written, so the version sync can tell which
+ * shared constructs packages this project owns.
+ */
+export interface AgentCoreHarnessMetadata extends IacMetadata {
+    generator: string;
+    name: string;
+    rc: string;
+    auth: 'iam';
+}
+/**
+ * Read a Harness Project's metadata, validating it was generated by the
+ * agentcore-harness generator before returning typed data.
+ */
+export declare const readAgentCoreHarnessMetadata: (project: ProjectConfiguration) => AgentCoreHarnessMetadata;
+export default agentcoreHarnessGenerator;