@aws/nx-plugin 1.0.15 → 1.1.1

package/src/ts/agent/guardrails/files/agent/guardrail.json.template

@@ -0,0 +1,16 @@
+{
+  "blockedInputMessaging": "Sorry, I can't help with that request.",
+  "blockedOutputsMessaging": "Sorry, I can't share that answer.",
+  "deniedTopics": [
+    {
+      "name": "Investment advice",
+      "definition": "Recommendations about which specific stocks, funds or other investments to buy or sell.",
+      "examples": ["Which stocks should I buy this year?"]
+    }
+  ],
+  "piiEntities": [
+    { "type": "EMAIL", "action": "ANONYMIZE" },
+    { "type": "PHONE", "action": "ANONYMIZE" },
+    { "type": "US_SOCIAL_SECURITY_NUMBER", "action": "BLOCK" }
+  ]
+}

package/src/ts/agent/guardrails/files/agent/guardrail.ts.template

@@ -0,0 +1,86 @@
+import { BedrockModel, type BedrockGuardrailConfig } from '@strands-agents/sdk';
+import {
+  type AgentCoreRuntimeConfig,
+  getAgentCoreRuntimeConfig,
+} from '<%- agentConnectionImport %>';
+
+/**
+ * This agent's entry in runtime config, written by the
+ * <%- agentNameClassName %>Guardrail construct or the <%- nameKebabCase %> guardrail module.
+ */
+interface GuardrailEntry {
+  guardrailId?: string;
+  guardrailVersion?: string;
+}
+
+const RUNTIME_CONFIG_KEY = 'agentcore.guardrails.<%- agentNameClassName %>';
+
+let warnedUnguarded = false;
+
+const readEntry = async (): Promise<GuardrailEntry | undefined> => {
+  const config: AgentCoreRuntimeConfig & {
+    guardrails?: Record<string, GuardrailEntry>;
+  } = await getAgentCoreRuntimeConfig();
+  return config.guardrails?.['<%- agentNameClassName %>'];
+};
+
+/**
+ * The guardrail to apply, read from runtime config on every model call
+ * (cached for 5 seconds).
+ */
+const resolveGuardrail = async (): Promise<
+  BedrockGuardrailConfig | undefined
+> => {
+  const localDev = process.env.LOCAL_DEV === 'true';
+  let entry: GuardrailEntry | undefined;
+  if (!localDev) {
+    entry = await readEntry();
+  } else if (process.env.RUNTIME_CONFIG_APP_ID) {
+    entry = await readEntry().catch(() => undefined);
+  }
+
+  if (!entry?.guardrailId || !entry.guardrailVersion) {
+    if (!localDev) {
+      throw new Error(
+        `No guardrail for this agent in runtime config at ${RUNTIME_CONFIG_KEY}. Add the <%- agentNameClassName %>Guardrail construct (CDK) or the guardrails/<%- nameKebabCase %> module (Terraform) to your infrastructure.`,
+      );
+    }
+    if (!warnedUnguarded) {
+      warnedUnguarded = true;
+      console.warn(
+        `No guardrail for this agent in runtime config at ${RUNTIME_CONFIG_KEY}, so the agent is running without a guardrail (LOCAL_DEV=true).`,
+      );
+    }
+    return undefined;
+  }
+
+  if (!/^[1-9][0-9]*$/.test(entry.guardrailVersion)) {
+    throw new Error(
+      `The guardrail version in runtime config at ${RUNTIME_CONFIG_KEY} must be a numbered guardrail version, but is ${entry.guardrailVersion}.`,
+    );
+  }
+
+  return {
+    guardrailIdentifier: entry.guardrailId,
+    guardrailVersion: entry.guardrailVersion,
+    trace: 'enabled',
+  };
+};
+
+/**
+ * A Bedrock model that applies this agent's guardrail from runtime config
+ * before each model call, so a new guardrail version applies without a
+ * restart.
+ */
+export class GuardrailedBedrockModel extends BedrockModel {
+  override async *stream(...args: Parameters<BedrockModel['stream']>) {
+    this.updateConfig({ guardrailConfig: await resolveGuardrail() });
+    return yield* super.stream(...args);
+  }
+}
+
+/**
+ * The Bedrock model with this agent's guardrail applied.
+ */
+export const getGuardrailedModel = (): BedrockModel =>
+  new GuardrailedBedrockModel();

package/src/ts/agent/guardrails/generator.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type GeneratorCallback, type Tree } from '@nx/devkit';
+import { type NxGeneratorInfo } from '../../../utils/nx.js';
+import type { TsAgentGuardrailsGeneratorSchema } from './schema';
+export declare const TS_AGENT_GUARDRAILS_GENERATOR_INFO: NxGeneratorInfo;
+export declare const tsAgentGuardrailsGenerator: (tree: Tree, options: TsAgentGuardrailsGeneratorSchema) => Promise<GeneratorCallback>;
+export default tsAgentGuardrailsGenerator;

package/src/ts/agent/guardrails/generator.js

@@ -0,0 +1,120 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { generateFiles, joinPathFragments, logger, OverwriteStrategy } from "@nx/devkit";
+import { addDestructuredImport, applyGritQL, matchGritQL } from "../../../utils/ast.js";
+import { formatFilesInSubtree } from "../../../utils/format.js";
+import { addGuardrailInfra } from "../../../utils/guardrail-constructs/guardrail-constructs.js";
+import { guardrailWiringMessage } from "../../../utils/guardrail-constructs/guardrail-wiring.js";
+import { addGeneratorMetricsIfApplicable } from "../../../utils/metrics.js";
+import { esmVars, isEsmWorkspace } from "../../../utils/module-format.js";
+import { kebabCase, toClassName } from "../../../utils/names.js";
+import { getNpmScope } from "../../../utils/npm-scope.js";
+import { addComponentGeneratorMetadata, getGeneratorInfo, readProjectConfigurationUnqualified } from "../../../utils/nx.js";
+import { TS_AGENT_GENERATOR_INFO } from "../generator.js";
+import { addGuardrailPolicySynthInputs } from "./synth-inputs.js";
+export const TS_AGENT_GUARDRAILS_GENERATOR_INFO = getGeneratorInfo(import.meta.filename);
+/**
+ * Find the `ts#agent` component to guard, by name when given, otherwise the
+ * project's only one.
+ */ const resolveAgent = (projectName, components, agent)=>{
+    const agents = components.filter((c)=>c.generator === TS_AGENT_GENERATOR_INFO.id);
+    const available = agents.map((c)=>c.name).join(', ') || 'none';
+    if (agent) {
+        const match = agents.find((c)=>c.name === agent);
+        if (!match) {
+            throw new Error(`No TypeScript Agent named ${agent} in project ${projectName}. Available agents: ${available}`);
+        }
+        return match;
+    }
+    if (agents.length !== 1) {
+        throw new Error(agents.length === 0 ? `Project ${projectName} has no TypeScript Agent. Add one with the ts#agent generator first.` : `Project ${projectName} has more than one TypeScript Agent. Specify which to guard with --agent. Available agents: ${available}`);
+    }
+    return agents[0];
+};
+/**
+ * Add `model: getGuardrailedModel()` to the `new Agent({...})` call in
+ * agent.ts. An agent that already sets its own model is left unchanged, and
+ * the lines to add by hand are logged instead.
+ */ const addGuardrailedModelToAgent = async (tree, agentFile)=>{
+    const guardrailImport = isEsmWorkspace(tree) ? './guardrail.js' : './guardrail';
+    if (tree.exists(agentFile)) {
+        if (await matchGritQL(tree, agentFile, '`getGuardrailedModel()`')) {
+            return;
+        }
+        if (await applyGritQL(tree, agentFile, '`new Agent({ $props })` => `new Agent({ model: getGuardrailedModel(), $props })` where { $props <: not some or { `model: $_`, `model` } }')) {
+            await addDestructuredImport(tree, agentFile, [
+                'getGuardrailedModel'
+            ], './guardrail.js');
+            return;
+        }
+    }
+    logger.warn(`Could not add the guardrail to ${agentFile}, because ${tree.exists(agentFile) ? 'its new Agent({...}) call already sets a model or is not an inline object' : 'the file does not exist'}. Set the model of your Agent to the guardrailed model by hand:
+
+  model: getGuardrailedModel(),
+
+and import it:
+
+  import { getGuardrailedModel } from '${guardrailImport}';`);
+};
+export const tsAgentGuardrailsGenerator = async (tree, options)=>{
+    const project = readProjectConfigurationUnqualified(tree, options.project);
+    const agent = resolveAgent(project.name, project.metadata?.components ?? [], options.agent);
+    const agentTargetPrefix = agent.name ?? 'agent';
+    const agentNameClassName = agent.rc ?? toClassName(agentTargetPrefix);
+    const nameKebabCase = kebabCase(agentNameClassName);
+    const agentPath = agent.path ?? joinPathFragments('src', agentTargetPrefix);
+    const agentDir = joinPathFragments(project.root, agentPath);
+    // The policy is the user's to edit, so a re-run never touches these files.
+    generateFiles(tree, joinPathFragments(import.meta.dirname, 'files', 'agent'), agentDir, {
+        ...esmVars(tree),
+        agentConnectionImport: `@${getNpmScope(tree)}/agent-connection`,
+        agentNameClassName,
+        nameKebabCase
+    }, {
+        overwriteStrategy: OverwriteStrategy.KeepExisting
+    });
+    await addGuardrailedModelToAgent(tree, joinPathFragments(agentDir, 'agent.ts'));
+    const iac = agent.iac;
+    let wiringMessage;
+    if (iac) {
+        const policyPath = joinPathFragments(agentDir, 'guardrail.json');
+        await addGuardrailInfra(tree, {
+            iac,
+            nameClassName: agentNameClassName,
+            nameKebabCase,
+            policyPath
+        });
+        if (iac === 'cdk') {
+            for (const message of addGuardrailPolicySynthInputs(tree, [
+                policyPath
+            ])){
+                logger.warn(message);
+            }
+        }
+        wiringMessage = guardrailWiringMessage({
+            iac,
+            nameClassName: agentNameClassName,
+            nameKebabCase,
+            npmScope: getNpmScope(tree)
+        });
+    } else {
+        logger.warn(`Agent ${agentTargetPrefix} in project ${project.name} has no infrastructure, so no guardrail infrastructure was generated. Create the guardrail yourself and write its ID and version to runtime config at agentcore.guardrails.${agentNameClassName} as { guardrailId, guardrailVersion }.`);
+    }
+    addComponentGeneratorMetadata(tree, project.name, TS_AGENT_GUARDRAILS_GENERATOR_INFO, agentPath, agentTargetPrefix);
+    await addGeneratorMetricsIfApplicable(tree, [
+        TS_AGENT_GUARDRAILS_GENERATOR_INFO
+    ]);
+    await formatFilesInSubtree(tree);
+    // Printed from the callback so it appears after Nx lists the changed
+    // files, on every run, since the generator cannot tell whether the stack is
+    // already wired.
+    return ()=>{
+        if (wiringMessage) {
+            logger.info(wiringMessage);
+        }
+    };
+};
+export default tsAgentGuardrailsGenerator;
+
+//# sourceMappingURL=generator.js.map

package/src/ts/agent/guardrails/generator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../packages/nx-plugin/src/ts/agent/guardrails/generator.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  generateFiles,\n  joinPathFragments,\n  logger,\n  OverwriteStrategy,\n  type Tree,\n} from '@nx/devkit';\nimport {\n  addDestructuredImport,\n  applyGritQL,\n  matchGritQL,\n} from '../../../utils/ast.js';\nimport { formatFilesInSubtree } from '../../../utils/format.js';\nimport { addGuardrailInfra } from '../../../utils/guardrail-constructs/guardrail-constructs.js';\nimport { guardrailWiringMessage } from '../../../utils/guardrail-constructs/guardrail-wiring.js';\nimport type { Iac } from '../../../utils/iac.js';\nimport { addGeneratorMetricsIfApplicable } from '../../../utils/metrics.js';\nimport { esmVars, isEsmWorkspace } from '../../../utils/module-format.js';\nimport { kebabCase, toClassName } from '../../../utils/names.js';\nimport { getNpmScope } from '../../../utils/npm-scope.js';\nimport {\n  addComponentGeneratorMetadata,\n  type ComponentMetadata,\n  getGeneratorInfo,\n  type NxGeneratorInfo,\n  readProjectConfigurationUnqualified,\n} from '../../../utils/nx.js';\nimport { TS_AGENT_GENERATOR_INFO } from '../generator.js';\nimport type { TsAgentGuardrailsGeneratorSchema } from './schema';\nimport { addGuardrailPolicySynthInputs } from './synth-inputs.js';\n\nexport const TS_AGENT_GUARDRAILS_GENERATOR_INFO: NxGeneratorInfo =\n  getGeneratorInfo(import.meta.filename);\n\n/**\n * Find the `ts#agent` component to guard, by name when given, otherwise the\n * project's only one.\n */\nconst resolveAgent = (\n  projectName: string,\n  components: ComponentMetadata[],\n  agent?: string,\n): ComponentMetadata => {\n  const agents = components.filter(\n    (c) => c.generator === TS_AGENT_GENERATOR_INFO.id,\n  );\n  const available = agents.map((c) => c.name).join(', ') || 'none';\n  if (agent) {\n    const match = agents.find((c) => c.name === agent);\n    if (!match) {\n      throw new Error(\n        `No TypeScript Agent named ${agent} in project ${projectName}. Available agents: ${available}`,\n      );\n    }\n    return match;\n  }\n  if (agents.length !== 1) {\n    throw new Error(\n      agents.length === 0\n        ? `Project ${projectName} has no TypeScript Agent. Add one with the ts#agent generator first.`\n        : `Project ${projectName} has more than one TypeScript Agent. Specify which to guard with --agent. Available agents: ${available}`,\n    );\n  }\n  return agents[0];\n};\n\n/**\n * Add `model: getGuardrailedModel()` to the `new Agent({...})` call in\n * agent.ts. An agent that already sets its own model is left unchanged, and\n * the lines to add by hand are logged instead.\n */\nconst addGuardrailedModelToAgent = async (\n  tree: Tree,\n  agentFile: string,\n): Promise<void> => {\n  const guardrailImport = isEsmWorkspace(tree)\n    ? './guardrail.js'\n    : './guardrail';\n\n  if (tree.exists(agentFile)) {\n    if (await matchGritQL(tree, agentFile, '`getGuardrailedModel()`')) {\n      return;\n    }\n    if (\n      await applyGritQL(\n        tree,\n        agentFile,\n        '`new Agent({ $props })` => `new Agent({ model: getGuardrailedModel(), $props })` where { $props <: not some or { `model: $_`, `model` } }',\n      )\n    ) {\n      await addDestructuredImport(\n        tree,\n        agentFile,\n        ['getGuardrailedModel'],\n        './guardrail.js',\n      );\n      return;\n    }\n  }\n\n  logger.warn(\n    `Could not add the guardrail to ${agentFile}, because ${tree.exists(agentFile) ? 'its new Agent({...}) call already sets a model or is not an inline object' : 'the file does not exist'}. Set the model of your Agent to the guardrailed model by hand:\n\n  model: getGuardrailedModel(),\n\nand import it:\n\n  import { getGuardrailedModel } from '${guardrailImport}';`,\n  );\n};\n\nexport const tsAgentGuardrailsGenerator = async (\n  tree: Tree,\n  options: TsAgentGuardrailsGeneratorSchema,\n): Promise<GeneratorCallback> => {\n  const project = readProjectConfigurationUnqualified(tree, options.project);\n  const agent = resolveAgent(\n    project.name,\n    (project.metadata as any)?.components ?? [],\n    options.agent,\n  );\n\n  const agentTargetPrefix = agent.name ?? 'agent';\n  const agentNameClassName = agent.rc ?? toClassName(agentTargetPrefix);\n  const nameKebabCase = kebabCase(agentNameClassName);\n  const agentPath = agent.path ?? joinPathFragments('src', agentTargetPrefix);\n  const agentDir = joinPathFragments(project.root, agentPath);\n\n  // The policy is the user's to edit, so a re-run never touches these files.\n  generateFiles(\n    tree,\n    joinPathFragments(import.meta.dirname, 'files', 'agent'),\n    agentDir,\n    {\n      ...esmVars(tree),\n      agentConnectionImport: `@${getNpmScope(tree)}/agent-connection`,\n      agentNameClassName,\n      nameKebabCase,\n    },\n    { overwriteStrategy: OverwriteStrategy.KeepExisting },\n  );\n\n  await addGuardrailedModelToAgent(\n    tree,\n    joinPathFragments(agentDir, 'agent.ts'),\n  );\n\n  const iac = agent.iac as Iac | undefined;\n  let wiringMessage: string | undefined;\n  if (iac) {\n    const policyPath = joinPathFragments(agentDir, 'guardrail.json');\n    await addGuardrailInfra(tree, {\n      iac,\n      nameClassName: agentNameClassName,\n      nameKebabCase,\n      policyPath,\n    });\n    if (iac === 'cdk') {\n      for (const message of addGuardrailPolicySynthInputs(tree, [policyPath])) {\n        logger.warn(message);\n      }\n    }\n    wiringMessage = guardrailWiringMessage({\n      iac,\n      nameClassName: agentNameClassName,\n      nameKebabCase,\n      npmScope: getNpmScope(tree),\n    });\n  } else {\n    logger.warn(\n      `Agent ${agentTargetPrefix} in project ${project.name} has no infrastructure, so no guardrail infrastructure was generated. Create the guardrail yourself and write its ID and version to runtime config at agentcore.guardrails.${agentNameClassName} as { guardrailId, guardrailVersion }.`,\n    );\n  }\n\n  addComponentGeneratorMetadata(\n    tree,\n    project.name,\n    TS_AGENT_GUARDRAILS_GENERATOR_INFO,\n    agentPath,\n    agentTargetPrefix,\n  );\n\n  await addGeneratorMetricsIfApplicable(tree, [\n    TS_AGENT_GUARDRAILS_GENERATOR_INFO,\n  ]);\n\n  await formatFilesInSubtree(tree);\n\n  // Printed from the callback so it appears after Nx lists the changed\n  // files, on every run, since the generator cannot tell whether the stack is\n  // already wired.\n  return () => {\n    if (wiringMessage) {\n      logger.info(wiringMessage);\n    }\n  };\n};\n\nexport default tsAgentGuardrailsGenerator;\n"],"names":["generateFiles","joinPathFragments","logger","OverwriteStrategy","addDestructuredImport","applyGritQL","matchGritQL","formatFilesInSubtree","addGuardrailInfra","guardrailWiringMessage","addGeneratorMetricsIfApplicable","esmVars","isEsmWorkspace","kebabCase","toClassName","getNpmScope","addComponentGeneratorMetadata","getGeneratorInfo","readProjectConfigurationUnqualified","TS_AGENT_GENERATOR_INFO","addGuardrailPolicySynthInputs","TS_AGENT_GUARDRAILS_GENERATOR_INFO","filename","resolveAgent","projectName","components","agent","agents","filter","c","generator","id","available","map","name","join","match","find","Error","length","addGuardrailedModelToAgent","tree","agentFile","guardrailImport","exists","warn","tsAgentGuardrailsGenerator","options","project","metadata","agentTargetPrefix","agentNameClassName","rc","nameKebabCase","agentPath","path","agentDir","root","dirname","agentConnectionImport","overwriteStrategy","KeepExisting","iac","wiringMessage","policyPath","nameClassName","message","npmScope","info"],"mappings":"AAAA;;;CAGC,GACD,SAEEA,aAAa,EACbC,iBAAiB,EACjBC,MAAM,EACNC,iBAAiB,QAEZ,aAAa;AACpB,SACEC,qBAAqB,EACrBC,WAAW,EACXC,WAAW,QACN,wBAAwB;AAC/B,SAASC,oBAAoB,QAAQ,2BAA2B;AAChE,SAASC,iBAAiB,QAAQ,8DAA8D;AAChG,SAASC,sBAAsB,QAAQ,0DAA0D;AAEjG,SAASC,+BAA+B,QAAQ,4BAA4B;AAC5E,SAASC,OAAO,EAAEC,cAAc,QAAQ,kCAAkC;AAC1E,SAASC,SAAS,EAAEC,WAAW,QAAQ,0BAA0B;AACjE,SAASC,WAAW,QAAQ,8BAA8B;AAC1D,SACEC,6BAA6B,EAE7BC,gBAAgB,EAEhBC,mCAAmC,QAC9B,uBAAuB;AAC9B,SAASC,uBAAuB,QAAQ,kBAAkB;AAE1D,SAASC,6BAA6B,QAAQ,oBAAoB;AAElE,OAAO,MAAMC,qCACXJ,iBAAiB,YAAYK,QAAQ,EAAE;AAEzC;;;CAGC,GACD,MAAMC,eAAe,CACnBC,aACAC,YACAC;IAEA,MAAMC,SAASF,WAAWG,MAAM,CAC9B,CAACC,IAAMA,EAAEC,SAAS,KAAKX,wBAAwBY,EAAE;IAEnD,MAAMC,YAAYL,OAAOM,GAAG,CAAC,CAACJ,IAAMA,EAAEK,IAAI,EAAEC,IAAI,CAAC,SAAS;IAC1D,IAAIT,OAAO;QACT,MAAMU,QAAQT,OAAOU,IAAI,CAAC,CAACR,IAAMA,EAAEK,IAAI,KAAKR;QAC5C,IAAI,CAACU,OAAO;YACV,MAAM,IAAIE,MACR,CAAC,0BAA0B,EAAEZ,MAAM,YAAY,EAAEF,YAAY,oBAAoB,EAAEQ,WAAW;QAElG;QACA,OAAOI;IACT;IACA,IAAIT,OAAOY,MAAM,KAAK,GAAG;QACvB,MAAM,IAAID,MACRX,OAAOY,MAAM,KAAK,IACd,CAAC,QAAQ,EAAEf,YAAY,oEAAoE,CAAC,GAC5F,CAAC,QAAQ,EAAEA,YAAY,4FAA4F,EAAEQ,WAAW;IAExI;IACA,OAAOL,MAAM,CAAC,EAAE;AAClB;AAEA;;;;CAIC,GACD,MAAMa,6BAA6B,OACjCC,MACAC;IAEA,MAAMC,kBAAkB/B,eAAe6B,QACnC,mBACA;IAEJ,IAAIA,KAAKG,MAAM,CAACF,YAAY;QAC1B,IAAI,MAAMpC,YAAYmC,MAAMC,WAAW,4BAA4B;YACjE;QACF;QACA,IACE,MAAMrC,YACJoC,MACAC,WACA,8IAEF;YACA,MAAMtC,sBACJqC,MACAC,WACA;gBAAC;aAAsB,EACvB;YAEF;QACF;IACF;IAEAxC,OAAO2C,IAAI,CACT,CAAC,+BAA+B,EAAEH,UAAU,UAAU,EAAED,KAAKG,MAAM,CAACF,aAAa,8EAA8E,0BAA0B;;;;;;uCAMtJ,EAAEC,gBAAgB,EAAE,CAAC;AAE5D;AAEA,OAAO,MAAMG,6BAA6B,OACxCL,MACAM;IAEA,MAAMC,UAAU9B,oCAAoCuB,MAAMM,QAAQC,OAAO;IACzE,MAAMtB,QAAQH,aACZyB,QAAQd,IAAI,EACZ,AAACc,QAAQC,QAAQ,EAAUxB,cAAc,EAAE,EAC3CsB,QAAQrB,KAAK;IAGf,MAAMwB,oBAAoBxB,MAAMQ,IAAI,IAAI;IACxC,MAAMiB,qBAAqBzB,MAAM0B,EAAE,IAAItC,YAAYoC;IACnD,MAAMG,gBAAgBxC,UAAUsC;IAChC,MAAMG,YAAY5B,MAAM6B,IAAI,IAAItD,kBAAkB,OAAOiD;IACzD,MAAMM,WAAWvD,kBAAkB+C,QAAQS,IAAI,EAAEH;IAEjD,2EAA2E;IAC3EtD,cACEyC,MACAxC,kBAAkB,YAAYyD,OAAO,EAAE,SAAS,UAChDF,UACA;QACE,GAAG7C,QAAQ8B,KAAK;QAChBkB,uBAAuB,CAAC,CAAC,EAAE5C,YAAY0B,MAAM,iBAAiB,CAAC;QAC/DU;QACAE;IACF,GACA;QAAEO,mBAAmBzD,kBAAkB0D,YAAY;IAAC;IAGtD,MAAMrB,2BACJC,MACAxC,kBAAkBuD,UAAU;IAG9B,MAAMM,MAAMpC,MAAMoC,GAAG;IACrB,IAAIC;IACJ,IAAID,KAAK;QACP,MAAME,aAAa/D,kBAAkBuD,UAAU;QAC/C,MAAMhD,kBAAkBiC,MAAM;YAC5BqB;YACAG,eAAed;YACfE;YACAW;QACF;QACA,IAAIF,QAAQ,OAAO;YACjB,KAAK,MAAMI,WAAW9C,8BAA8BqB,MAAM;gBAACuB;aAAW,EAAG;gBACvE9D,OAAO2C,IAAI,CAACqB;YACd;QACF;QACAH,gBAAgBtD,uBAAuB;YACrCqD;YACAG,eAAed;YACfE;YACAc,UAAUpD,YAAY0B;QACxB;IACF,OAAO;QACLvC,OAAO2C,IAAI,CACT,CAAC,MAAM,EAAEK,kBAAkB,YAAY,EAAEF,QAAQd,IAAI,CAAC,2KAA2K,EAAEiB,mBAAmB,sCAAsC,CAAC;IAEjS;IAEAnC,8BACEyB,MACAO,QAAQd,IAAI,EACZb,oCACAiC,WACAJ;IAGF,MAAMxC,gCAAgC+B,MAAM;QAC1CpB;KACD;IAED,MAAMd,qBAAqBkC;IAE3B,qEAAqE;IACrE,4EAA4E;IAC5E,iBAAiB;IACjB,OAAO;QACL,IAAIsB,eAAe;YACjB7D,OAAOkE,IAAI,CAACL;QACd;IACF;AACF,EAAE;AAEF,eAAejB,2BAA2B"}

package/src/ts/agent/guardrails/schema.d.js

@@ -0,0 +1,6 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ export { };
+
+//# sourceMappingURL=schema.d.js.map

package/src/ts/agent/guardrails/schema.d.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../packages/nx-plugin/src/ts/agent/guardrails/schema.d.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\n\nexport interface TsAgentGuardrailsGeneratorSchema {\n  project: string;\n  agent?: string;\n}\n"],"names":[],"mappings":"AAAA;;;CAGC,GAED,WAGC"}

package/src/ts/agent/guardrails/schema.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export interface TsAgentGuardrailsGeneratorSchema {
+  project: string;
+  agent?: string;
+}

package/src/ts/agent/guardrails/schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "ts#agent#guardrails",
+  "title": "ts#agent#guardrails",
+  "x-label": "Agent Guardrails",
+  "description": "Add an Amazon Bedrock Guardrail to a TypeScript Agent",
+  "type": "object",
+  "properties": {
+    "project": {
+      "type": "string",
+      "description": "The project containing the TypeScript Agent",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "Select the project containing the TypeScript Agent to guard",
+      "x-dropdown": "projects"
+    },
+    "agent": {
+      "type": "string",
+      "description": "The name of the Agent component to guard. Required when the project contains more than one TypeScript Agent."
+    }
+  },
+  "required": ["project"]
+}

package/src/ts/agent/guardrails/synth-inputs.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type Tree } from '@nx/devkit';
+/** The Nx fileset input for a workspace-root-relative guardrail.json. */
+export declare const guardrailPolicyInput: (policyPath: string) => string;
+/**
+ * Add each guardrail.json to the `synth` inputs of every CDK infrastructure
+ * project. The CDK guardrail construct reads the file at synth time, but it
+ * belongs to the agent's project and no upstream task output includes it, so
+ * without an explicit input a policy change is served from the Nx cache.
+ *
+ * Existing inputs are kept and entries already present are not repeated. A
+ * project without a `synth` target, or whose `synth` has no `inputs` array, is
+ * left unchanged, since adding an array would replace Nx's implicit inputs;
+ * one message per such project is returned instead.
+ */
+export declare const addGuardrailPolicySynthInputs: (tree: Tree, policyPaths: string[]) => string[];

package/src/ts/agent/guardrails/synth-inputs.js

@@ -0,0 +1,50 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { getProjects, joinPathFragments, updateJson } from "@nx/devkit";
+import { INFRA_APP_GENERATOR_INFO } from "../../../infra/app/generator.js";
+/** The Nx fileset input for a workspace-root-relative guardrail.json. */ export const guardrailPolicyInput = (policyPath)=>`{workspaceRoot}/${policyPath}`;
+/**
+ * Add each guardrail.json to the `synth` inputs of every CDK infrastructure
+ * project. The CDK guardrail construct reads the file at synth time, but it
+ * belongs to the agent's project and no upstream task output includes it, so
+ * without an explicit input a policy change is served from the Nx cache.
+ *
+ * Existing inputs are kept and entries already present are not repeated. A
+ * project without a `synth` target, or whose `synth` has no `inputs` array, is
+ * left unchanged, since adding an array would replace Nx's implicit inputs;
+ * one message per such project is returned instead.
+ */ export const addGuardrailPolicySynthInputs = (tree, policyPaths)=>{
+    const entries = [
+        ...new Set(policyPaths)
+    ].map(guardrailPolicyInput);
+    const messages = [];
+    if (entries.length === 0) {
+        return messages;
+    }
+    for (const [name, project] of getProjects(tree)){
+        if (project.metadata?.generator !== INFRA_APP_GENERATOR_INFO.id) {
+            continue;
+        }
+        const projectJson = joinPathFragments(project.root, 'project.json');
+        const synth = project.targets?.synth;
+        if (!synth || !Array.isArray(synth.inputs)) {
+            const problem = synth ? `the synth target in ${projectJson} has no inputs` : `${projectJson} has no synth target`;
+            messages.push(`${name}: ${problem} - left unchanged. Add ${entries.join(', ')} to its synth inputs so a change to the guardrail policy invalidates the cached synth.`);
+            continue;
+        }
+        const missing = entries.filter((entry)=>!synth.inputs.includes(entry));
+        if (missing.length > 0) {
+            updateJson(tree, projectJson, (config)=>{
+                config.targets.synth.inputs = [
+                    ...config.targets.synth.inputs,
+                    ...missing
+                ];
+                return config;
+            });
+        }
+    }
+    return messages;
+};
+
+//# sourceMappingURL=synth-inputs.js.map

package/src/ts/agent/guardrails/synth-inputs.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../packages/nx-plugin/src/ts/agent/guardrails/synth-inputs.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  getProjects,\n  joinPathFragments,\n  type Tree,\n  updateJson,\n} from '@nx/devkit';\nimport { INFRA_APP_GENERATOR_INFO } from '../../../infra/app/generator.js';\n\n/** The Nx fileset input for a workspace-root-relative guardrail.json. */\nexport const guardrailPolicyInput = (policyPath: string): string =>\n  `{workspaceRoot}/${policyPath}`;\n\n/**\n * Add each guardrail.json to the `synth` inputs of every CDK infrastructure\n * project. The CDK guardrail construct reads the file at synth time, but it\n * belongs to the agent's project and no upstream task output includes it, so\n * without an explicit input a policy change is served from the Nx cache.\n *\n * Existing inputs are kept and entries already present are not repeated. A\n * project without a `synth` target, or whose `synth` has no `inputs` array, is\n * left unchanged, since adding an array would replace Nx's implicit inputs;\n * one message per such project is returned instead.\n */\nexport const addGuardrailPolicySynthInputs = (\n  tree: Tree,\n  policyPaths: string[],\n): string[] => {\n  const entries = [...new Set(policyPaths)].map(guardrailPolicyInput);\n  const messages: string[] = [];\n  if (entries.length === 0) {\n    return messages;\n  }\n\n  for (const [name, project] of getProjects(tree)) {\n    if (project.metadata?.generator !== INFRA_APP_GENERATOR_INFO.id) {\n      continue;\n    }\n    const projectJson = joinPathFragments(project.root, 'project.json');\n    const synth = project.targets?.synth;\n    if (!synth || !Array.isArray(synth.inputs)) {\n      const problem = synth\n        ? `the synth target in ${projectJson} has no inputs`\n        : `${projectJson} has no synth target`;\n      messages.push(\n        `${name}: ${problem} - left unchanged. Add ${entries.join(', ')} to its synth inputs so a change to the guardrail policy invalidates the cached synth.`,\n      );\n      continue;\n    }\n    const missing = entries.filter((entry) => !synth.inputs.includes(entry));\n    if (missing.length > 0) {\n      updateJson(tree, projectJson, (config) => {\n        config.targets.synth.inputs = [\n          ...config.targets.synth.inputs,\n          ...missing,\n        ];\n        return config;\n      });\n    }\n  }\n\n  return messages;\n};\n"],"names":["getProjects","joinPathFragments","updateJson","INFRA_APP_GENERATOR_INFO","guardrailPolicyInput","policyPath","addGuardrailPolicySynthInputs","tree","policyPaths","entries","Set","map","messages","length","name","project","metadata","generator","id","projectJson","root","synth","targets","Array","isArray","inputs","problem","push","join","missing","filter","entry","includes","config"],"mappings":"AAAA;;;CAGC,GACD,SACEA,WAAW,EACXC,iBAAiB,EAEjBC,UAAU,QACL,aAAa;AACpB,SAASC,wBAAwB,QAAQ,kCAAkC;AAE3E,uEAAuE,GACvE,OAAO,MAAMC,uBAAuB,CAACC,aACnC,CAAC,gBAAgB,EAAEA,YAAY,CAAC;AAElC;;;;;;;;;;CAUC,GACD,OAAO,MAAMC,gCAAgC,CAC3CC,MACAC;IAEA,MAAMC,UAAU;WAAI,IAAIC,IAAIF;KAAa,CAACG,GAAG,CAACP;IAC9C,MAAMQ,WAAqB,EAAE;IAC7B,IAAIH,QAAQI,MAAM,KAAK,GAAG;QACxB,OAAOD;IACT;IAEA,KAAK,MAAM,CAACE,MAAMC,QAAQ,IAAIf,YAAYO,MAAO;QAC/C,IAAIQ,QAAQC,QAAQ,EAAEC,cAAcd,yBAAyBe,EAAE,EAAE;YAC/D;QACF;QACA,MAAMC,cAAclB,kBAAkBc,QAAQK,IAAI,EAAE;QACpD,MAAMC,QAAQN,QAAQO,OAAO,EAAED;QAC/B,IAAI,CAACA,SAAS,CAACE,MAAMC,OAAO,CAACH,MAAMI,MAAM,GAAG;YAC1C,MAAMC,UAAUL,QACZ,CAAC,oBAAoB,EAAEF,YAAY,cAAc,CAAC,GAClD,GAAGA,YAAY,oBAAoB,CAAC;YACxCP,SAASe,IAAI,CACX,GAAGb,KAAK,EAAE,EAAEY,QAAQ,uBAAuB,EAAEjB,QAAQmB,IAAI,CAAC,MAAM,sFAAsF,CAAC;YAEzJ;QACF;QACA,MAAMC,UAAUpB,QAAQqB,MAAM,CAAC,CAACC,QAAU,CAACV,MAAMI,MAAM,CAACO,QAAQ,CAACD;QACjE,IAAIF,QAAQhB,MAAM,GAAG,GAAG;YACtBX,WAAWK,MAAMY,aAAa,CAACc;gBAC7BA,OAAOX,OAAO,CAACD,KAAK,CAACI,MAAM,GAAG;uBACzBQ,OAAOX,OAAO,CAACD,KAAK,CAACI,MAAM;uBAC3BI;iBACJ;gBACD,OAAOI;YACT;QACF;IACF;IAEA,OAAOrB;AACT,EAAE"}

package/src/utils/guardrail-constructs/files/cdk/app/guardrails/__nameKebabCase__/__nameKebabCase__-guardrail.ts.template

@@ -0,0 +1,128 @@
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as url from 'node:url';
+import { CfnOutput, Names, Stack } from 'aws-cdk-lib';
+import * as bedrock from 'aws-cdk-lib/aws-bedrock';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import { Construct } from 'constructs';
+import { RuntimeConfig } from '../../../core/runtime-config<% if (esm) { %>.js<% } %>';
+import { findWorkspaceRoot } from '../../../core/workspace<% if (esm) { %>.js<% } %>';
+
+interface GuardrailPolicy {
+  blockedInputMessaging: string;
+  blockedOutputsMessaging: string;
+  deniedTopics?: { name: string; definition: string; examples?: string[] }[];
+  piiEntities?: { type: string; action: string }[];
+}
+
+// Read at synth time, anchored on the workspace root so it still resolves once
+// this file compiles to dist/.
+const policyFile = fs.readFileSync(
+  path.join(
+    findWorkspaceRoot(url.fileURLToPath(new URL(<% if (esm) { %>import.meta.url<% } else { %>require('url').pathToFileURL(__filename).href<% } %>))),
+    '<%- policyPath %>',
+  ),
+);
+const policy: GuardrailPolicy = JSON.parse(policyFile.toString('utf-8'));
+
+/**
+ * Properties for the <%- nameClassName %>Guardrail. Any CfnGuardrail property
+ * supplied here takes precedence over guardrail.json.
+ */
+export type <%- nameClassName %>GuardrailProps = Partial<bedrock.CfnGuardrailProps> & {
+  /** The agent that applies this guardrail. It is granted bedrock:ApplyGuardrail. */
+  readonly agent: iam.IGrantable;
+};
+
+/**
+ * An Amazon Bedrock Guardrail for <%- nameClassName %>, with a numbered version
+ * that changes whenever its rules change. Its ID and version are written to
+ * runtime config, where the agent reads them.
+ */
+export class <%- nameClassName %>Guardrail extends Construct {
+  public readonly guardrail: bedrock.CfnGuardrail;
+  public readonly version: bedrock.CfnGuardrailVersion;
+  public readonly guardrailId: string;
+  public readonly guardrailArn: string;
+  public readonly guardrailVersion: string;
+
+  constructor(
+    scope: Construct,
+    id: string,
+    props: <%- nameClassName %>GuardrailProps,
+  ) {
+    super(scope, id);
+
+    const { agent, ...overrides } = props;
+
+    const deniedTopics = policy.deniedTopics ?? [];
+    const piiEntities = policy.piiEntities ?? [];
+
+    this.guardrail = new bedrock.CfnGuardrail(this, 'Guardrail', {
+      name: Names.uniqueResourceName(this, {
+        maxLength: 50,
+        separator: '-',
+        allowedSpecialCharacters: '-_',
+      }),
+      blockedInputMessaging: policy.blockedInputMessaging,
+      blockedOutputsMessaging: policy.blockedOutputsMessaging,
+      ...(deniedTopics.length > 0 && {
+        topicPolicyConfig: {
+          topicsConfig: deniedTopics.map(({ name, definition, examples }) => ({
+            name,
+            definition,
+            examples,
+            type: 'DENY',
+          })),
+        },
+      }),
+      ...(piiEntities.length > 0 && {
+        sensitiveInformationPolicyConfig: {
+          piiEntitiesConfig: piiEntities.map(({ type, action }) => ({
+            type,
+            action,
+          })),
+        },
+      }),
+      ...overrides,
+    });
+
+    const hash = createHash('sha256').update(policyFile);
+    if (Object.keys(overrides).length > 0) {
+      hash.update(JSON.stringify(Stack.of(this).resolve(overrides)));
+    }
+
+    this.version = new bedrock.CfnGuardrailVersion(this, 'Version', {
+      guardrailIdentifier: this.guardrail.attrGuardrailId,
+      description: `guardrail.json sha256 ${hash.digest('hex')}`,
+    });
+
+    this.guardrailId = this.guardrail.attrGuardrailId;
+    this.guardrailArn = this.guardrail.attrGuardrailArn;
+    this.guardrailVersion = this.version.attrVersion;
+
+    new CfnOutput(this, 'GuardrailId', { value: this.guardrailId });
+    new CfnOutput(this, 'GuardrailVersion', { value: this.guardrailVersion });
+
+    const rc = RuntimeConfig.ensure(this);
+    rc.set('agentcore', 'guardrails', {
+      ...rc.get('agentcore').guardrails,
+      <%- nameClassName %>: {
+        guardrailId: this.guardrailId,
+        guardrailVersion: this.guardrailVersion,
+      },
+    });
+
+    this.grantApply(agent);
+  }
+
+  /** Grant permission to apply this guardrail. */
+  public grantApply(grantee: iam.IGrantable): iam.Grant {
+    return iam.Grant.addToPrincipal({
+      grantee,
+      actions: ['bedrock:ApplyGuardrail'],
+      resourceArns: [this.guardrailArn],
+    });
+  }
+}

package/src/utils/guardrail-constructs/files/terraform/app/guardrails/__nameKebabCase__/__nameKebabCase__-guardrail.tf.template

@@ -0,0 +1,108 @@
+terraform {
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "<%- awsProviderVersion %>"
+    }
+    random = {
+      source  = "hashicorp/random"
+      version = "<%- randomProviderVersion %>"
+    }
+  }
+}
+
+variable "tags" {
+  description = "Tags to apply to resources"
+  type        = map(string)
+  default     = {}
+}
+
+locals {
+  policy_file = "${path.module}/../../../../../../../<%- policyPath %>"
+  policy      = jsondecode(file(local.policy_file))
+  name_prefix = "<%- guardrailNamePrefix %>"
+}
+
+resource "random_id" "unique_suffix" {
+  byte_length = 4
+}
+
+resource "aws_bedrock_guardrail" "this" {
+  name                      = "${local.name_prefix}-${random_id.unique_suffix.hex}"
+  blocked_input_messaging   = local.policy.blockedInputMessaging
+  blocked_outputs_messaging = local.policy.blockedOutputsMessaging
+
+  dynamic "topic_policy_config" {
+    for_each = length(try(local.policy.deniedTopics, [])) > 0 ? [1] : []
+    content {
+      dynamic "topics_config" {
+        for_each = local.policy.deniedTopics
+        content {
+          name       = topics_config.value.name
+          definition = topics_config.value.definition
+          examples   = try(topics_config.value.examples, [])
+          type       = "DENY"
+        }
+      }
+    }
+  }
+
+  dynamic "sensitive_information_policy_config" {
+    for_each = length(try(local.policy.piiEntities, [])) > 0 ? [1] : []
+    content {
+      dynamic "pii_entities_config" {
+        for_each = local.policy.piiEntities
+        content {
+          type   = pii_entities_config.value.type
+          action = pii_entities_config.value.action
+        }
+      }
+    }
+  }
+
+  tags = var.tags
+}
+
+resource "aws_bedrock_guardrail_version" "this" {
+  guardrail_arn = aws_bedrock_guardrail.this.guardrail_arn
+  description   = "guardrail.json sha256 ${filesha256(local.policy_file)}"
+
+  lifecycle {
+    create_before_destroy = true
+  }
+}
+
+module "add_guardrail_to_runtime_config" {
+  source = "../../../core/runtime-config/entry"
+
+  namespace = "agentcore"
+  key       = "guardrails"
+  value     = { "<%= nameClassName %>" = { guardrailId = aws_bedrock_guardrail.this.guardrail_id, guardrailVersion = aws_bedrock_guardrail_version.this.version } }
+}
+
+output "guardrail_id" {
+  description = "ID of the guardrail"
+  value       = aws_bedrock_guardrail.this.guardrail_id
+}
+
+output "guardrail_arn" {
+  description = "ARN of the guardrail"
+  value       = aws_bedrock_guardrail.this.guardrail_arn
+}
+
+output "guardrail_version" {
+  description = "Numbered version of the guardrail"
+  value       = aws_bedrock_guardrail_version.this.version
+}
+
+output "iam_policy_statements" {
+  description = "IAM policy statements that allow the agent to apply the guardrail"
+  value = [
+    {
+      Effect   = "Allow"
+      Action   = ["bedrock:ApplyGuardrail"]
+      Resource = [aws_bedrock_guardrail.this.guardrail_arn]
+    }
+  ]
+  depends_on = [module.add_guardrail_to_runtime_config]
+}

package/src/utils/guardrail-constructs/guardrail-constructs.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';
+import type { Iac } from '../iac.js';
+export interface AddGuardrailInfraOptions {
+    iac: Iac;
+    /** Class name of the guarded agent, eg `MyAgent` gives `MyAgentGuardrail`. */
+    nameClassName: string;
+    /**
+     * Kebab-case name of the guarded agent, used for the directory and, with a
+     * `-guardrail` suffix, the file.
+     */
+    nameKebabCase: string;
+    /** Workspace-root-relative path of the guardrail.json policy file. */
+    policyPath: string;
+}
+/**
+ * Add the Amazon Bedrock Guardrail infrastructure for the selected IaC
+ * provider: a CDK construct in the shared constructs project, or a Terraform
+ * module in the shared Terraform project. Both read the policy file at synth
+ * or plan time.
+ *
+ * Files are written with `KeepExisting`, so a re-run leaves them unchanged.
+ * No build dependency is added on the agent's project, since the
+ * infrastructure reads a source file and imports none of the agent's code;
+ * for CDK the generator lists that file as a `synth` input instead, so the
+ * infrastructure's cached synth follows it.
+ */
+export declare const addGuardrailInfra: (tree: Tree, options: AddGuardrailInfraOptions) => Promise<void>;