@aws/nx-plugin 1.0.14 → 1.1.0

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,111 @@
+/**
+ * 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";
+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) {
+        await addGuardrailInfra(tree, {
+            iac,
+            nameClassName: agentNameClassName,
+            nameKebabCase,
+            policyPath: joinPathFragments(agentDir, 'guardrail.json')
+        });
+        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';\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    await addGuardrailInfra(tree, {\n      iac,\n      nameClassName: agentNameClassName,\n      nameKebabCase,\n      policyPath: joinPathFragments(agentDir, 'guardrail.json'),\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","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","nameClassName","policyPath","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;AAG1D,OAAO,MAAMC,qCACXH,iBAAiB,YAAYI,QAAQ,EAAE;AAEzC;;;CAGC,GACD,MAAMC,eAAe,CACnBC,aACAC,YACAC;IAEA,MAAMC,SAASF,WAAWG,MAAM,CAC9B,CAACC,IAAMA,EAAEC,SAAS,KAAKV,wBAAwBW,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,kBAAkB9B,eAAe4B,QACnC,mBACA;IAEJ,IAAIA,KAAKG,MAAM,CAACF,YAAY;QAC1B,IAAI,MAAMnC,YAAYkC,MAAMC,WAAW,4BAA4B;YACjE;QACF;QACA,IACE,MAAMpC,YACJmC,MACAC,WACA,8IAEF;YACA,MAAMrC,sBACJoC,MACAC,WACA;gBAAC;aAAsB,EACvB;YAEF;QACF;IACF;IAEAvC,OAAO0C,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,UAAU7B,oCAAoCsB,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,IAAIrC,YAAYmC;IACnD,MAAMG,gBAAgBvC,UAAUqC;IAChC,MAAMG,YAAY5B,MAAM6B,IAAI,IAAIrD,kBAAkB,OAAOgD;IACzD,MAAMM,WAAWtD,kBAAkB8C,QAAQS,IAAI,EAAEH;IAEjD,2EAA2E;IAC3ErD,cACEwC,MACAvC,kBAAkB,YAAYwD,OAAO,EAAE,SAAS,UAChDF,UACA;QACE,GAAG5C,QAAQ6B,KAAK;QAChBkB,uBAAuB,CAAC,CAAC,EAAE3C,YAAYyB,MAAM,iBAAiB,CAAC;QAC/DU;QACAE;IACF,GACA;QAAEO,mBAAmBxD,kBAAkByD,YAAY;IAAC;IAGtD,MAAMrB,2BACJC,MACAvC,kBAAkBsD,UAAU;IAG9B,MAAMM,MAAMpC,MAAMoC,GAAG;IACrB,IAAIC;IACJ,IAAID,KAAK;QACP,MAAMrD,kBAAkBgC,MAAM;YAC5BqB;YACAE,eAAeb;YACfE;YACAY,YAAY/D,kBAAkBsD,UAAU;QAC1C;QACAO,gBAAgBrD,uBAAuB;YACrCoD;YACAE,eAAeb;YACfE;YACAa,UAAUlD,YAAYyB;QACxB;IACF,OAAO;QACLtC,OAAO0C,IAAI,CACT,CAAC,MAAM,EAAEK,kBAAkB,YAAY,EAAEF,QAAQd,IAAI,CAAC,2KAA2K,EAAEiB,mBAAmB,sCAAsC,CAAC;IAEjS;IAEAlC,8BACEwB,MACAO,QAAQd,IAAI,EACZb,oCACAiC,WACAJ;IAGF,MAAMvC,gCAAgC8B,MAAM;QAC1CpB;KACD;IAED,MAAMb,qBAAqBiC;IAE3B,qEAAqE;IACrE,4EAA4E;IAC5E,iBAAiB;IACjB,OAAO;QACL,IAAIsB,eAAe;YACjB5D,OAAOgE,IAAI,CAACJ;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/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,29 @@
+/**
+ * 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.
+ */
+export declare const addGuardrailInfra: (tree: Tree, options: AddGuardrailInfraOptions) => Promise<void>;

package/src/utils/guardrail-constructs/guardrail-constructs.js

@@ -0,0 +1,52 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { generateFiles, joinPathFragments, OverwriteStrategy } from "@nx/devkit";
+import { addStarExport } from "../ast.js";
+import { esmVars } from "../module-format.js";
+import { PACKAGES_DIR, SHARED_CONSTRUCTS_DIR, SHARED_TERRAFORM_DIR } from "../shared-constructs-constants.js";
+import { terraformProviderVersions } from "../versions.js";
+/**
+ * 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.
+ */ export const addGuardrailInfra = async (tree, options)=>{
+    const templateContext = {
+        nameClassName: options.nameClassName,
+        nameKebabCase: options.nameKebabCase,
+        policyPath: options.policyPath
+    };
+    switch(options.iac){
+        case 'cdk':
+            {
+                const appDir = joinPathFragments(PACKAGES_DIR, SHARED_CONSTRUCTS_DIR, 'src', 'app');
+                generateFiles(tree, joinPathFragments(import.meta.dirname, 'files', 'cdk', 'app', 'guardrails'), joinPathFragments(appDir, 'guardrails'), {
+                    ...templateContext,
+                    ...esmVars(tree)
+                }, {
+                    overwriteStrategy: OverwriteStrategy.KeepExisting
+                });
+                await addStarExport(tree, joinPathFragments(appDir, 'guardrails', 'index.ts'), `./${options.nameKebabCase}/${options.nameKebabCase}-guardrail.js`);
+                await addStarExport(tree, joinPathFragments(appDir, 'index.ts'), './guardrails/index.js');
+                break;
+            }
+        case 'terraform':
+            generateFiles(tree, joinPathFragments(import.meta.dirname, 'files', 'terraform', 'app', 'guardrails'), joinPathFragments(PACKAGES_DIR, SHARED_TERRAFORM_DIR, 'src', 'app', 'guardrails'), {
+                ...templateContext,
+                // Guardrail names are at most 50 characters: the prefix, a hyphen
+                // and the 8 hex characters of the random suffix.
+                guardrailNamePrefix: `${options.nameKebabCase}-guardrail`.slice(0, 41),
+                ...terraformProviderVersions()
+            }, {
+                overwriteStrategy: OverwriteStrategy.KeepExisting
+            });
+            break;
+    }
+};
+
+//# sourceMappingURL=guardrail-constructs.js.map

package/src/utils/guardrail-constructs/guardrail-constructs.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../packages/nx-plugin/src/utils/guardrail-constructs/guardrail-constructs.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  generateFiles,\n  joinPathFragments,\n  OverwriteStrategy,\n  type Tree,\n} from '@nx/devkit';\nimport { addStarExport } from '../ast.js';\nimport type { Iac } from '../iac.js';\nimport { esmVars } from '../module-format.js';\nimport {\n  PACKAGES_DIR,\n  SHARED_CONSTRUCTS_DIR,\n  SHARED_TERRAFORM_DIR,\n} from '../shared-constructs-constants.js';\nimport { terraformProviderVersions } from '../versions.js';\n\nexport interface AddGuardrailInfraOptions {\n  iac: Iac;\n  /** Class name of the guarded agent, eg `MyAgent` gives `MyAgentGuardrail`. */\n  nameClassName: string;\n  /**\n   * Kebab-case name of the guarded agent, used for the directory and, with a\n   * `-guardrail` suffix, the file.\n   */\n  nameKebabCase: string;\n  /** Workspace-root-relative path of the guardrail.json policy file. */\n  policyPath: string;\n}\n\n/**\n * Add the Amazon Bedrock Guardrail infrastructure for the selected IaC\n * provider: a CDK construct in the shared constructs project, or a Terraform\n * module in the shared Terraform project. Both read the policy file at synth\n * or plan time.\n *\n * Files are written with `KeepExisting`, so a re-run leaves them unchanged.\n * No build dependency is added on the agent's project, since the\n * infrastructure reads a source file and imports none of the agent's code.\n */\nexport const addGuardrailInfra = async (\n  tree: Tree,\n  options: AddGuardrailInfraOptions,\n): Promise<void> => {\n  const templateContext = {\n    nameClassName: options.nameClassName,\n    nameKebabCase: options.nameKebabCase,\n    policyPath: options.policyPath,\n  };\n\n  switch (options.iac) {\n    case 'cdk': {\n      const appDir = joinPathFragments(\n        PACKAGES_DIR,\n        SHARED_CONSTRUCTS_DIR,\n        'src',\n        'app',\n      );\n      generateFiles(\n        tree,\n        joinPathFragments(\n          import.meta.dirname,\n          'files',\n          'cdk',\n          'app',\n          'guardrails',\n        ),\n        joinPathFragments(appDir, 'guardrails'),\n        { ...templateContext, ...esmVars(tree) },\n        { overwriteStrategy: OverwriteStrategy.KeepExisting },\n      );\n      await addStarExport(\n        tree,\n        joinPathFragments(appDir, 'guardrails', 'index.ts'),\n        `./${options.nameKebabCase}/${options.nameKebabCase}-guardrail.js`,\n      );\n      await addStarExport(\n        tree,\n        joinPathFragments(appDir, 'index.ts'),\n        './guardrails/index.js',\n      );\n      break;\n    }\n    case 'terraform':\n      generateFiles(\n        tree,\n        joinPathFragments(\n          import.meta.dirname,\n          'files',\n          'terraform',\n          'app',\n          'guardrails',\n        ),\n        joinPathFragments(\n          PACKAGES_DIR,\n          SHARED_TERRAFORM_DIR,\n          'src',\n          'app',\n          'guardrails',\n        ),\n        {\n          ...templateContext,\n          // Guardrail names are at most 50 characters: the prefix, a hyphen\n          // and the 8 hex characters of the random suffix.\n          guardrailNamePrefix: `${options.nameKebabCase}-guardrail`.slice(\n            0,\n            41,\n          ),\n          ...terraformProviderVersions(),\n        },\n        { overwriteStrategy: OverwriteStrategy.KeepExisting },\n      );\n      break;\n  }\n};\n"],"names":["generateFiles","joinPathFragments","OverwriteStrategy","addStarExport","esmVars","PACKAGES_DIR","SHARED_CONSTRUCTS_DIR","SHARED_TERRAFORM_DIR","terraformProviderVersions","addGuardrailInfra","tree","options","templateContext","nameClassName","nameKebabCase","policyPath","iac","appDir","dirname","overwriteStrategy","KeepExisting","guardrailNamePrefix","slice"],"mappings":"AAAA;;;CAGC,GACD,SACEA,aAAa,EACbC,iBAAiB,EACjBC,iBAAiB,QAEZ,aAAa;AACpB,SAASC,aAAa,QAAQ,YAAY;AAE1C,SAASC,OAAO,QAAQ,sBAAsB;AAC9C,SACEC,YAAY,EACZC,qBAAqB,EACrBC,oBAAoB,QACf,oCAAoC;AAC3C,SAASC,yBAAyB,QAAQ,iBAAiB;AAe3D;;;;;;;;;CASC,GACD,OAAO,MAAMC,oBAAoB,OAC/BC,MACAC;IAEA,MAAMC,kBAAkB;QACtBC,eAAeF,QAAQE,aAAa;QACpCC,eAAeH,QAAQG,aAAa;QACpCC,YAAYJ,QAAQI,UAAU;IAChC;IAEA,OAAQJ,QAAQK,GAAG;QACjB,KAAK;YAAO;gBACV,MAAMC,SAAShB,kBACbI,cACAC,uBACA,OACA;gBAEFN,cACEU,MACAT,kBACE,YAAYiB,OAAO,EACnB,SACA,OACA,OACA,eAEFjB,kBAAkBgB,QAAQ,eAC1B;oBAAE,GAAGL,eAAe;oBAAE,GAAGR,QAAQM,KAAK;gBAAC,GACvC;oBAAES,mBAAmBjB,kBAAkBkB,YAAY;gBAAC;gBAEtD,MAAMjB,cACJO,MACAT,kBAAkBgB,QAAQ,cAAc,aACxC,CAAC,EAAE,EAAEN,QAAQG,aAAa,CAAC,CAAC,EAAEH,QAAQG,aAAa,CAAC,aAAa,CAAC;gBAEpE,MAAMX,cACJO,MACAT,kBAAkBgB,QAAQ,aAC1B;gBAEF;YACF;QACA,KAAK;YACHjB,cACEU,MACAT,kBACE,YAAYiB,OAAO,EACnB,SACA,aACA,OACA,eAEFjB,kBACEI,cACAE,sBACA,OACA,OACA,eAEF;gBACE,GAAGK,eAAe;gBAClB,kEAAkE;gBAClE,iDAAiD;gBACjDS,qBAAqB,GAAGV,QAAQG,aAAa,CAAC,UAAU,CAAC,CAACQ,KAAK,CAC7D,GACA;gBAEF,GAAGd,2BAA2B;YAChC,GACA;gBAAEW,mBAAmBjB,kBAAkBkB,YAAY;YAAC;YAEtD;IACJ;AACF,EAAE"}