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

package/bin/aws-nx-mcp.js

@@ -54177,6 +54177,13 @@ var generators$1 = {
 		"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/docs/guides/agentcore-harness.mdx

@@ -0,0 +1,275 @@
+---
+title: AgentCore Harness
+description: Create an Amazon Bedrock AgentCore Harness project
+generator: agentcore-harness
+---
+
+import { FileTree } from '@astrojs/starlight/components';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import Infrastructure from '@components/infrastructure.astro';
+import Link from '@components/link.astro';
+import NxCommands from '@components/nx-commands.astro';
+import RunGenerator from '@components/run-generator.astro';
+import Snippet from '@components/snippet.astro';
+
+Generate an [Amazon Bedrock AgentCore Harness](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness.html) project. A Harness is a managed agent loop powered by Strands Agents: it owns deployment defaults for the model, system prompt, tools, memory, skills, environments, truncation, authorization, and execution limits, while the service accepts per-invocation overrides for supported fields. Reusing the same Runtime Session ID continues the same Harness session.
+
+## Usage
+
+### Generate an AgentCore Harness
+
+<RunGenerator generator="agentcore-harness" />
+
+### Options
+
+<GeneratorParameters generator="agentcore-harness" />
+
+## Generator Output
+
+The generator creates a standalone project at `packages/<name>/`. Because AWS runs the agent loop for you, the project holds only the prompt that shapes it and a script for talking to it:
+
+<FileTree>
+  - packages/\<name>/
+    - src/PROMPT.md The Harness system prompt
+    - scripts/chat.ts Multi-turn chat client for the deployed Harness
+    - project.json Adds the `chat` target
+    - README.md Chat and customization instructions
+</FileTree>
+
+### Infrastructure
+
+Infrastructure is generated when `infra` is `agentcore` (the default). With `infra: none` no infrastructure is generated — set `HARNESS_ARN` to invoke a Harness managed elsewhere, and re-run the generator with `infra: agentcore` later to add infrastructure; existing project files (including your edits) are preserved.
+
+<Snippet name="shared-constructs" />
+
+<Infrastructure>
+  <Fragment slot="cdk">
+    <FileTree>
+      - packages/common/constructs/src/app/harnesses/\<name>/
+        - \<name>.ts CDK construct containing the Harness and execution role
+    </FileTree>
+  </Fragment>
+  <Fragment slot="terraform">
+    <FileTree>
+      - packages/common/terraform/src/app/harnesses/\<name>/
+        - \<name>.tf Terraform module containing the Harness and execution role
+    </FileTree>
+  </Fragment>
+</Infrastructure>
+
+The generated infrastructure manages the Harness through the native resource (CDK `aws_bedrockagentcore.CfnHarness`, Terraform `aws_bedrockagentcore_harness`) with your generated defaults, creates an IAM execution role with the baseline permissions described below, and uses IAM inbound authorization (no custom JWT authorizer is configured by default).
+
+The Harness ARN is registered at `agentcore.harnesses.<ClassName>` in <Link path="guides/runtime-config">Runtime Configuration</Link>, preserving any existing entries.
+
+## Deploying your AgentCore Harness
+
+The generator creates CDK or Terraform infrastructure as code based on your selected `iac` provider. You can use this to deploy your Harness through your usual infrastructure workflow.
+
+<Infrastructure>
+  <Fragment slot="cdk">
+The CDK construct for deploying your Harness lives in the `common/constructs` folder. Instantiate it from a CDK application:
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyHarness } from '@my-scope/common-constructs';
+import { Stack, type StackProps } from 'aws-cdk-lib';
+import type { Construct } from 'constructs';
+
+export class ApplicationStack extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    new MyHarness(this, 'MyHarness');
+  }
+}
+```
+
+The construct's props interface (`MyHarnessProps`) extends `Partial<Omit<CfnHarnessProps, 'executionRoleArn' | 'allowedTools'>>`, so any native Harness property can be supplied and takes precedence over the generated defaults:
+
+```ts
+const harness = new MyHarness(this, 'MyHarness', {
+  maxIterations: 20,
+  timeoutSeconds: 600,
+});
+```
+
+The construct also accepts:
+
+- `allowedTools` — the tools the Harness may use. The Harness deploys with none unless you supply them, see <a href="#configuring-tools">Configuring tools</a>.
+- `executionRole` — an existing IAM role to use instead of the generated role. A supplied role is used as-is: the baseline permissions are not added to it, and its ARN always feeds the Harness (the raw `executionRoleArn` string cannot be overridden).
+- `modelResourceArns` — the Bedrock model and inference-profile ARNs the generated execution role may invoke, replacing the default list.
+- `vpc`, `vpcSubnets` and `securityGroups` — run the Harness in a VPC so it can reach private resources, see <a href="#running-in-a-vpc">Running in a VPC</a>.
+
+Its public members are `harness` (the `CfnHarness`), `executionRole`, `grantPrincipal`, the `harnessArn` getter, `connections` (in a VPC), `addToRolePolicy(statement)` for execution role extensions, and `grantInvokeAccess(grantee)` for authorizing callers.
+
+Deploy the stack with your infrastructure project as usual — see the <Link path="guides/typescript-infrastructure">CDK infrastructure guide</Link>.
+  </Fragment>
+  <Fragment slot="terraform">
+The Terraform module for deploying your Harness is in the `common/terraform` folder. Reference it from a Terraform configuration:
+
+```hcl title="packages/infra/src/main.tf"
+module "my_harness" {
+  source = "../../common/terraform/src/app/harnesses/my-harness"
+}
+```
+
+The module exposes three variables:
+
+- `model_id` — the Bedrock model or inference profile the Harness uses by default.
+- `model_resource_arns` — the Bedrock model and inference-profile ARNs the execution role may invoke, replacing the default list.
+- `additional_execution_role_policy_statements` — a list of IAM statement objects (`Effect`, `Action`, `Resource`, optional `Sid` and `Condition`) appended to the execution role policy.
+
+Everything else is configured on the generated `aws_bedrockagentcore_harness` resource in the module itself.
+
+The module outputs `harness_id`, `harness_arn`, and `execution_role_arn`.
+
+Deploy with your Terraform project's plan/apply workflow as usual — see the <Link path="guides/terraform-project">Terraform project guide</Link>.
+  </Fragment>
+</Infrastructure>
+
+:::note[System prompt visibility]
+Your infrastructure reads `packages/<name>/src/PROMPT.md` when you synthesize (CDK) or plan (Terraform), so the prompt is deployment configuration rather than secret storage: its contents appear in the synthesized CloudFormation template or in Terraform state.
+:::
+
+## Granting access to invoke the harness
+
+You can grant a caller permissions to invoke the harness as follows:
+
+<Infrastructure>
+  <Fragment slot="cdk">
+```ts
+const harness = new MyHarness(this, 'MyHarness');
+
+harness.grantInvokeAccess(caller);
+```
+  </Fragment>
+  <Fragment slot="terraform">
+```hcl
+# Attach to the calling principal's role
+resource "aws_iam_role_policy" "invoke_my_harness" {
+  name = "InvokeMyHarness"
+  role = aws_iam_role.caller.id
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect = "Allow"
+      Action = [
+        "bedrock-agentcore:InvokeHarness",
+        "bedrock-agentcore:InvokeAgentRuntime",
+      ]
+      Resource = [module.my_harness.harness_arn]
+    }]
+  })
+}
+```
+  </Fragment>
+</Infrastructure>
+
+A caller needs both `bedrock-agentcore:InvokeHarness` and `bedrock-agentcore:InvokeAgentRuntime` on the Harness ARN, which is exactly what `grantInvokeAccess` grants.
+
+## Chatting with your Harness
+
+The generated `chat` target runs `scripts/chat.ts`, dropping you into an interactive terminal chat with your deployed Harness:
+
+<NxCommands commands={['run <project>:chat']} />
+
+Every turn of a run shares one session, so the Harness keeps the conversation context until you exit. Credentials come from the standard AWS SDK credential provider chain, and the AWS Region is derived from the Harness ARN.
+
+The Harness ARN is resolved in this order:
+
+1. `HARNESS_ARN` (non-empty): used directly, without reading Runtime Configuration:
+
+   <NxCommands commands={['run <project>:chat']} env={{ HARNESS_ARN: '<harness-arn>' }} />
+
+2. `RUNTIME_CONFIG_APP_ID`: resolves the ARN from the `agentcore.harnesses.<ClassName>` entry published by the deployed infrastructure:
+
+   <NxCommands commands={['run <project>:chat']} env={{ RUNTIME_CONFIG_APP_ID: '<application-id>' }} />
+
+With neither set, the script fails with an error naming both options.
+
+## Customizing your Harness
+
+`src/PROMPT.md` is the Harness system prompt: edit it and redeploy to change how the Harness behaves. Everything else is configured where you instantiate the infrastructure, or by editing the generated construct or module directly. Re-running the generator never overwrites existing files (it only adds missing files and merges project metadata), so your edits to the prompt and to the generated infrastructure are preserved.
+
+<Infrastructure>
+  <Fragment slot="cdk">
+Every native Harness property of the pinned `aws-cdk-lib/aws-bedrockagentcore` module is available through the construct's props — alternate model providers, tool definitions, memory, skills, environment configuration, truncation, custom JWT authorization, and execution limits — and explicit props take precedence over the generated defaults. Alternatively, edit the generated construct in `packages/common/constructs/src/app/harnesses/<name>/<name>.ts`.
+  </Fragment>
+  <Fragment slot="terraform">
+The generated module keeps the native `aws_bedrockagentcore_harness` resource directly editable, so provider-native fields — alternate model providers (`gemini_model_config`, `openai_model_config`), `tool` blocks, `memory`, `skill` blocks, environments (`environment`, `environment_variables`, `environment_artifact`), `truncation`, and `authorizer_configuration` with a `custom_jwt_authorizer` — are configured by editing `packages/common/terraform/src/app/harnesses/<name>/<name>.tf`.
+  </Fragment>
+</Infrastructure>
+
+Omitting authorizer configuration (the default) means IAM inbound authorization; configure a custom JWT authorizer through the native field to change that.
+
+### Configuring tools
+
+The Harness deploys with no tools, so it starts with the least capability. Opt in to the tools it may use:
+
+<Infrastructure>
+  <Fragment slot="cdk">
+```ts
+new MyHarness(this, 'Harness', { allowedTools: ['@builtin'] });
+```
+  </Fragment>
+  <Fragment slot="terraform">
+```hcl title="packages/common/terraform/src/app/harnesses/my-harness/my-harness.tf"
+resource "aws_bedrockagentcore_harness" "this" {
+  # ...
+  allowed_tools = ["@builtin"]
+}
+```
+
+Add an `allowed_tools` variable to the module if you would rather set it as a module argument where you reference the module.
+  </Fragment>
+</Infrastructure>
+
+Narrow `@builtin` to specific patterns such as `@builtin/file_operations` to restrict what the agent loop can do. See [Harness tools](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-tools.html) for the built-in tools you can add.
+
+### Running in a VPC
+
+<Infrastructure>
+  <Fragment slot="cdk">
+Supply a `vpc` to run the Harness inside it, so it can reach private resources such as a database. The construct implements `IConnectable`, so those resources grant it access the same way they would any other:
+
+```ts
+const harness = new MyHarness(this, 'MyHarness', { vpc });
+
+database.connections.allowDefaultPortFrom(harness, 'Harness to database');
+```
+
+The Harness is placed in the VPC's private subnets with egress, in a security group created for it. Override either with `vpcSubnets` and `securityGroups`. Both require `vpc`, and `connections` is only available when the Harness runs in a VPC.
+  </Fragment>
+  <Fragment slot="terraform">
+Add a `network_configuration` block to the generated `aws_bedrockagentcore_harness` resource's `environment.agent_core_runtime_environment`, then reference the security group you place it in from your other resources' rules:
+
+```hcl title="packages/common/terraform/src/app/harnesses/my-harness/my-harness.tf"
+resource "aws_security_group" "harness" {
+  vpc_id = var.vpc_id
+}
+
+resource "aws_bedrockagentcore_harness" "this" {
+  # ...
+  environment {
+    agent_core_runtime_environment {
+      network_configuration {
+        network_mode = "VPC"
+        network_mode_config {
+          security_groups = [aws_security_group.harness.id]
+          subnets         = var.subnet_ids
+        }
+      }
+    }
+  }
+}
+```
+  </Fragment>
+</Infrastructure>
+
+### Per-invocation overrides
+
+The values configured in infrastructure are deployment defaults. The service also accepts per-invocation overrides for supported Harness fields (such as models, tools, and skills) in the `InvokeHarness` request; deployment defaults apply wherever a field is not overridden.
+
+:::caution[Validate invocation overrides]
+Per-invocation overrides are trusted inputs at the service boundary: any authorized caller can override supported fields. If untrusted users can reach an application that forwards overrides to `InvokeHarness`, validate and authorize them at the application layer (for example, allowlist models and tools), keep the execution role scoped to required resources, and do not grant `bedrock-agentcore:InvokeAgentRuntimeCommand` unless you specifically need it.
+:::

package/docs/guides/astro-docs.mdx

@@ -86,6 +86,14 @@ When run without `--all`, the script only translates files that have changed
 since the last translation commit on the current branch — meaning you can
 safely re-run it on every docs PR without re-translating the whole site.
 
+Translations whose source file no longer exists are deleted, so renaming or
+removing a page does not leave stale copies behind in each locale.
+
+Each translation is written as a whole file. The agent is given the source, the
+existing translation, and a diff of what changed, and reuses the existing
+wording for sections the diff left alone — so only prose the diff touched is
+retranslated, and code blocks are copied from the source as-is.
+
 ### Configuring translation
 
 Edit `scripts/translate.config.json` to change:

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/nx-plugin-mcp",
-  "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/schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "agentcore-harness",
+  "title": "agentcore-harness",
+  "description": "Generate an Amazon Bedrock AgentCore Harness project",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The name of your AgentCore Harness project. Must contain at least one non-whitespace character which can be normalized into a kebab-case project name (eg. my-harness).",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "What would you like to call your AgentCore Harness?",
+      "x-priority": "important",
+      "pattern": "\\S"
+    },
+    "directory": {
+      "type": "string",
+      "description": "Parent directory where the harness project is placed. Defaults to packages. Must be a relative path which does not contain parent directory (..) segments.",
+      "x-priority": "important",
+      "pattern": "^(?![A-Za-z]:)(?![\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$))(?=.*\\S).+$"
+    },
+    "subDirectory": {
+      "type": "string",
+      "description": "The sub directory the project is placed in. Defaults to the kebab-case harness name. Must be a relative path which does not contain parent directory (..) segments.",
+      "x-priority": "important",
+      "pattern": "^(?![A-Za-z]:)(?![\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$))(?=.*\\S).+$"
+    },
+    "infra": {
+      "type": "string",
+      "description": "The type of infrastructure to generate for hosting your harness. Defaults to agentcore. Select none for no hosting.",
+      "x-prompt": "How would you like to host your harness?",
+      "x-priority": "important",
+      "enum": ["agentcore", "none"],
+      "default": "agentcore"
+    },
+    "iac": {
+      "type": "string",
+      "description": "The preferred IaC provider for generated harness infrastructure. Defaults to inherit, which uses the provider configured for your workspace.",
+      "x-prompt": "Which provider would you like to manage your infrastructure? (default: inherit)",
+      "x-priority": "important",
+      "enum": ["inherit", "cdk", "terraform"],
+      "default": "inherit"
+    },
+    "preferInstallDependencies": {
+      "type": "boolean",
+      "description": "Whether to prefer installing dependencies after the generator runs. Defaults to true. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end."
+    }
+  },
+  "required": ["name"]
+}