@aws/nx-plugin 1.2.0 → 1.3.0

package/src/py/agent/guardrails/runtime-check/run_checks.py

@@ -0,0 +1,250 @@
+# 
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+# 
+"""Run a generated, guarded Python agent against fake_aws.py and report what
+the real SDK sent. Used by guardrail-runtime.spec.ts.
+
+Usage: python run_checks.py <project root> <connection root> <fake_aws.py> <framework>
+    <agent package> <agent-connection module> [<scenario>]
+
+<project root> holds the agent project's module and pyproject.toml, and
+<connection root> the agent-connection module, as in a workspace.
+Without a scenario, every scenario runs in a fresh interpreter (so the
+guardrail cache and warn-once state start clean), then the static checks, and
+one line "RESULTS <json>" maps each name to its result.
+"""
+
+import asyncio
+import importlib
+import importlib.util
+import json
+import logging
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from contextlib import contextmanager
+from typing import Any
+
+ROOT, CONNECTION_ROOT, FAKE_AWS, FRAMEWORK, AGENT_PACKAGE, CONNECTION_MODULE = sys.argv[1:7]
+
+ENTRY = {"guardrailId": "grtest", "guardrailVersion": "1"}
+# fake_aws.py blocks a guarded request whose checked text contains "stocks".
+BLOCKED_PROMPT = "Which stocks should I buy this year?"
+
+# scenario: (LOCAL_DEV, RUNTIME_CONFIG_APP_ID, guardrail entry or None, number of calls)
+SCENARIOS: dict[str, tuple[bool, str | None, dict[str, str] | None, int]] = {
+    "guarded": (False, "fake-app", ENTRY, 1),
+    "missing": (False, "fake-app", None, 1),
+    "no-app-id": (False, None, ENTRY, 1),
+    "local-dev": (True, None, ENTRY, 2),
+    "local-dev-broken": (True, "broken", ENTRY, 2),
+    "local-dev-guarded": (True, "fake-app", ENTRY, 1),
+    "draft": (False, "fake-app", {**ENTRY, "guardrailVersion": "DRAFT"}, 1),
+    "draft-local": (True, "fake-app", {**ENTRY, "guardrailVersion": "DRAFT"}, 1),
+    "zero": (False, "fake-app", {**ENTRY, "guardrailVersion": "0"}, 1),
+    "zero-local": (True, "fake-app", {**ENTRY, "guardrailVersion": "0"}, 1),
+    "reread": (False, "fake-app", ENTRY, 0),
+    "concurrent": (False, "fake-app", ENTRY, 0),
+    "blocked-session": (False, "fake-app", ENTRY, 0),
+    "blocked-session-stream": (False, "fake-app", ENTRY, 0),
+}
+
+
+def write_config(path: str, entry: dict[str, str] | None, class_name: str) -> None:
+    data: dict[str, Any] = {"agentRuntimes": {}}
+    if entry is not None:
+        data["guardrails"] = {class_name: entry}
+    with open(path, "w") as f:
+        json.dump(data, f)
+
+
+def read_log(path: str) -> list[dict[str, Any]]:
+    if not os.path.exists(path):
+        return []
+    with open(path) as f:
+        return [json.loads(line) for line in f if line.strip()]
+
+
+class WarningRecorder(logging.Handler):
+    def __init__(self) -> None:
+        super().__init__(logging.WARNING)
+        self.messages: list[str] = []
+
+    def emit(self, record: logging.LogRecord) -> None:
+        if record.name.endswith(".guardrail"):
+            self.messages.append(record.getMessage())
+
+
+def run_scenario(name: str) -> dict[str, Any]:
+    local_dev, app_id, entry, calls = SCENARIOS[name]
+    work = tempfile.mkdtemp(prefix=f"{name}-")
+    config_file, log_file = os.path.join(work, "config.json"), os.path.join(work, "requests.log")
+    # The vended local session storage is relative to the project root, two levels down.
+    cwd = os.path.join(work, "packages", "project")
+    os.makedirs(cwd)
+    os.chdir(cwd)
+
+    spec = importlib.util.spec_from_file_location("fake_aws", FAKE_AWS)
+    assert spec and spec.loader
+    fake_aws = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(fake_aws)
+    _server, port = fake_aws.start_server(config_file, log_file)
+    os.environ["AWS_ENDPOINT_URL_APPCONFIGDATA"] = f"http://127.0.0.1:{port}"
+    os.environ["AWS_ENDPOINT_URL_BEDROCK_RUNTIME"] = f"http://127.0.0.1:{port}"
+    os.environ.pop("LOCAL_DEV", None)
+    os.environ.pop("RUNTIME_CONFIG_APP_ID", None)
+    if local_dev:
+        os.environ["LOCAL_DEV"] = "true"
+    if app_id:
+        os.environ["RUNTIME_CONFIG_APP_ID"] = app_id
+
+    recorder = WarningRecorder()
+    logging.getLogger().addHandler(recorder)
+
+    sys.path[:0] = [ROOT, CONNECTION_ROOT]
+    agent_module = importlib.import_module(f"{AGENT_PACKAGE}.agent")
+    guardrail_module = importlib.import_module(f"{AGENT_PACKAGE}.guardrail")
+    class_name = guardrail_module.RUNTIME_CONFIG_KEY.split(".")[-1]
+    write_config(config_file, entry, class_name)
+
+    result: dict[str, Any] = {"calls": []}
+
+    def snapshot() -> dict[str, Any]:
+        log = read_log(log_file)
+        return {
+            "models": [r for r in log if "modelId" in r],
+            "appConfigCalls": len([r for r in log if "modelId" not in r]),
+        }
+
+    async def scenario() -> None:
+        if FRAMEWORK == "strands":
+            connection = importlib.import_module(CONNECTION_MODULE)
+
+            @contextmanager
+            def agent_scope():
+                with connection.session_id_context("s1"), agent_module.get_agent() as agent:
+                    yield agent
+
+            async def call(agent: Any, prompt: str = "2+2?") -> None:
+                await agent.invoke_async(prompt)
+
+            if name == "concurrent":
+                from strands import Agent
+
+                shared = guardrail_module.get_guardrailed_model()
+                agents = [Agent(model=shared, callback_handler=None) for _ in range(10)]
+                await asyncio.gather(*[a.invoke_async("2+2?") for a in agents])
+                return
+            with agent_scope() as agent:
+                await run_calls(agent, call)
+        else:
+            graph = agent_module.get_agent()
+            counter = iter(range(1000))
+
+            async def call(agent: Any, prompt: str | None = None) -> None:
+                # A call with a prompt continues one session; without, each call is a new session.
+                if name == "blocked-session-stream":
+                    await stream(agent, prompt)
+                    return
+                thread = {"configurable": {"thread_id": "session" if prompt else f"t{next(counter)}"}}
+                await agent.ainvoke({"messages": [{"role": "user", "content": prompt or "2+2?"}]}, thread)
+
+            async def stream(agent: Any, prompt: str | None = None) -> None:
+                thread = {"configurable": {"thread_id": "session" if prompt else f"t{next(counter)}"}}
+                async for _ in agent.astream(
+                    {"messages": [{"role": "user", "content": prompt or "2+2?"}]}, thread, stream_mode="messages"
+                ):
+                    pass
+
+            if name == "concurrent":
+                await asyncio.gather(*[call(graph) for _ in range(10)])
+                return
+            await run_calls(graph, call)
+            if name == "guarded":
+                await stream(graph)
+                result["streamed"] = snapshot()["models"][-1:]
+
+    async def run_calls(agent: Any, call: Any) -> None:
+        if name.startswith("blocked-session"):
+            # A blocked message, then a normal one, in the same session.
+            for prompt in (BLOCKED_PROMPT, "2+2?"):
+                await call(agent, prompt)
+                result["calls"].append(snapshot())
+            return
+        if name == "reread":
+            await call(agent)
+            result["calls"].append(snapshot())
+            write_config(config_file, {**ENTRY, "guardrailVersion": "2"}, class_name)
+            await call(agent)
+            result["calls"].append(snapshot())
+            time.sleep(5.5)
+            await call(agent)
+            result["calls"].append(snapshot())
+            return
+        for _ in range(calls):
+            await call(agent)
+            result["calls"].append(snapshot())
+
+    try:
+        asyncio.run(scenario())
+    except Exception as e:  # noqa: BLE001 - reported to the spec
+        result["error"] = {"type": type(e).__name__, "message": str(e)}
+    result.update(snapshot())
+    result["warnings"] = recorder.messages
+    shutil.rmtree(work, ignore_errors=True)
+    return result
+
+
+def run_static() -> dict[str, Any]:
+    package_dir = os.path.join(ROOT, *AGENT_PACKAGE.split("."))
+    files = [os.path.join(package_dir, f) for f in ("guardrail.py", "agent.py")]
+    # uv's --with environment layers several site-packages directories, which
+    # ty does not discover from the interpreter alone.
+    search_paths = [CONNECTION_ROOT, *(p for p in sys.path if p.endswith("site-packages"))]
+    commands = {
+        "ty": [
+            "ty",
+            "check",
+            "--python",
+            sys.executable,
+            *(arg for path in search_paths for arg in ("--extra-search-path", path)),
+            "--no-progress",
+            *files,
+        ],
+        "ruffFormat": ["ruff", "format", "--check", *files],
+        "ruffCheck": ["ruff", "check", "--select", "E,F,UP,B,SIM,I", *files],
+    }
+    results = {}
+    for key, command in commands.items():
+        done = subprocess.run(command, cwd=ROOT, capture_output=True, text=True)
+        results[key] = {"code": done.returncode, "output": done.stdout + done.stderr}
+    return results
+
+
+if __name__ == "__main__":
+    if len(sys.argv) > 7:
+        print("\nRESULT " + json.dumps(run_scenario(sys.argv[7])), flush=True)
+        # A failed LangChain call in local dev leaves the SQLite checkpointer's
+        # non-daemon thread running, which would keep the interpreter alive.
+        os._exit(0)
+    else:
+        results: dict[str, Any] = {}
+        for scenario_name in SCENARIOS:
+            done = subprocess.run(
+                [sys.executable, __file__, *sys.argv[1:7], scenario_name],
+                capture_output=True,
+                text=True,
+                timeout=180,
+            )
+            lines = [line for line in done.stdout.splitlines() if line.startswith("RESULT ")]
+            results[scenario_name] = (
+                json.loads(lines[-1][len("RESULT ") :])
+                if lines
+                else {"crashed": done.returncode, "stdout": done.stdout[-4000:], "stderr": done.stderr[-4000:]}
+            )
+        results["static"] = run_static()
+        print("RESULTS " + json.dumps(results), flush=True)

package/src/py/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/py/agent/guardrails/schema.d.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../packages/nx-plugin/src/py/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 PyAgentGuardrailsGeneratorSchema {\n  project: string;\n  agent?: string;\n}\n"],"names":[],"mappings":"AAAA;;;CAGC,GAED,WAGC"}

package/src/py/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 PyAgentGuardrailsGeneratorSchema {
+  project: string;
+  agent?: string;
+}

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

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "py#agent#guardrails",
+  "title": "py#agent#guardrails",
+  "x-label": "Agent Guardrails",
+  "description": "Add an Amazon Bedrock Guardrail to a Python Agent",
+  "type": "object",
+  "properties": {
+    "project": {
+      "type": "string",
+      "description": "The project containing the Python Agent",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "Select the project containing the Python 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 Python Agent."
+    }
+  },
+  "required": ["project"]
+}

package/src/sdk/py.d.ts

@@ -3,6 +3,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 export { pyAgentGenerator } from '../py/agent/generator.js';
+export { pyAgentGuardrailsGenerator } from '../py/agent/guardrails/generator.js';
+export type { PyAgentGuardrailsGeneratorSchema } from '../py/agent/guardrails/schema';
 export type { PyAgentGeneratorSchema } from '../py/agent/schema';
 export { pyApiGenerator } from '../py/api/generator.js';
 export type { PyApiGeneratorSchema } from '../py/api/schema';

package/src/sdk/py.js

@@ -2,6 +2,7 @@
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
  */ export { pyAgentGenerator } from "../py/agent/generator.js";
+export { pyAgentGuardrailsGenerator } from "../py/agent/guardrails/generator.js";
 export { pyApiGenerator } from "../py/api/generator.js";
 export { pyDynamoDBGenerator } from "../py/dynamodb/generator.js";
 export { pyLambdaFunctionGenerator } from "../py/lambda-function/generator.js";

package/src/sdk/py.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../packages/nx-plugin/src/sdk/py.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\n\nexport { pyAgentGenerator } from '../py/agent/generator.js';\nexport type { PyAgentGeneratorSchema } from '../py/agent/schema';\n\nexport { pyApiGenerator } from '../py/api/generator.js';\nexport type { PyApiGeneratorSchema } from '../py/api/schema';\n\nexport { pyDynamoDBGenerator } from '../py/dynamodb/generator.js';\nexport type { PyDynamoDBGeneratorSchema } from '../py/dynamodb/schema';\n\nexport { pyLambdaFunctionGenerator } from '../py/lambda-function/generator.js';\nexport type { PyLambdaFunctionGeneratorSchema } from '../py/lambda-function/schema';\n\nexport { pyMcpServerGenerator } from '../py/mcp-server/generator.js';\nexport type { PyMcpServerGeneratorSchema } from '../py/mcp-server/schema';\nexport { pyProjectGenerator } from '../py/project/generator.js';\nexport type { PyProjectGeneratorSchema } from '../py/project/schema';\n\nexport { pyRdbGenerator } from '../py/rdb/generator.js';\nexport type { PyRdbGeneratorSchema } from '../py/rdb/schema';\n"],"names":["pyAgentGenerator","pyApiGenerator","pyDynamoDBGenerator","pyLambdaFunctionGenerator","pyMcpServerGenerator","pyProjectGenerator","pyRdbGenerator"],"mappings":"AAAA;;;CAGC,GAED,SAASA,gBAAgB,QAAQ,2BAA2B;AAG5D,SAASC,cAAc,QAAQ,yBAAyB;AAGxD,SAASC,mBAAmB,QAAQ,8BAA8B;AAGlE,SAASC,yBAAyB,QAAQ,qCAAqC;AAG/E,SAASC,oBAAoB,QAAQ,gCAAgC;AAErE,SAASC,kBAAkB,QAAQ,6BAA6B;AAGhE,SAASC,cAAc,QAAQ,yBAAyB"}
+{"version":3,"sources":["../../../../../packages/nx-plugin/src/sdk/py.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\n\nexport { pyAgentGenerator } from '../py/agent/generator.js';\nexport { pyAgentGuardrailsGenerator } from '../py/agent/guardrails/generator.js';\nexport type { PyAgentGuardrailsGeneratorSchema } from '../py/agent/guardrails/schema';\nexport type { PyAgentGeneratorSchema } from '../py/agent/schema';\n\nexport { pyApiGenerator } from '../py/api/generator.js';\nexport type { PyApiGeneratorSchema } from '../py/api/schema';\n\nexport { pyDynamoDBGenerator } from '../py/dynamodb/generator.js';\nexport type { PyDynamoDBGeneratorSchema } from '../py/dynamodb/schema';\n\nexport { pyLambdaFunctionGenerator } from '../py/lambda-function/generator.js';\nexport type { PyLambdaFunctionGeneratorSchema } from '../py/lambda-function/schema';\n\nexport { pyMcpServerGenerator } from '../py/mcp-server/generator.js';\nexport type { PyMcpServerGeneratorSchema } from '../py/mcp-server/schema';\nexport { pyProjectGenerator } from '../py/project/generator.js';\nexport type { PyProjectGeneratorSchema } from '../py/project/schema';\n\nexport { pyRdbGenerator } from '../py/rdb/generator.js';\nexport type { PyRdbGeneratorSchema } from '../py/rdb/schema';\n"],"names":["pyAgentGenerator","pyAgentGuardrailsGenerator","pyApiGenerator","pyDynamoDBGenerator","pyLambdaFunctionGenerator","pyMcpServerGenerator","pyProjectGenerator","pyRdbGenerator"],"mappings":"AAAA;;;CAGC,GAED,SAASA,gBAAgB,QAAQ,2BAA2B;AAC5D,SAASC,0BAA0B,QAAQ,sCAAsC;AAIjF,SAASC,cAAc,QAAQ,yBAAyB;AAGxD,SAASC,mBAAmB,QAAQ,8BAA8B;AAGlE,SAASC,yBAAyB,QAAQ,qCAAqC;AAG/E,SAASC,oBAAoB,QAAQ,gCAAgC;AAErE,SAASC,kBAAkB,QAAQ,6BAA6B;AAGhE,SAASC,cAAc,QAAQ,yBAAyB"}

package/src/ts/agent/guardrails/__snapshots__/generator.spec.ts.snap

@@ -445,6 +445,10 @@ exports[`ts#agent#guardrails generator > protocol a2a > should generate the guar
       source  = "hashicorp/random"
       version = "3.9.1"
     }
+    time = {
+      source  = "hashicorp/time"
+      version = "0.14.2"
+    }
   }
 }
 
@@ -509,12 +513,25 @@ resource "aws_bedrock_guardrail_version" "this" {
   }
 }
 
+resource "time_sleep" "version_retention" {
+  destroy_duration = "15s"
+
+  triggers = {
+    guardrail_id      = aws_bedrock_guardrail.this.guardrail_id
+    guardrail_version = aws_bedrock_guardrail_version.this.version
+  }
+
+  lifecycle {
+    create_before_destroy = true
+  }
+}
+
 module "add_guardrail_to_runtime_config" {
   source = "../../../core/runtime-config/entry"
 
   namespace = "agentcore"
   key       = "guardrails"
-  value     = { "TestProjectAgent" = { guardrailId = aws_bedrock_guardrail.this.guardrail_id, guardrailVersion = aws_bedrock_guardrail_version.this.version } }
+  value     = { "TestProjectAgent" = { guardrailId = time_sleep.version_retention.triggers.guardrail_id, guardrailVersion = time_sleep.version_retention.triggers.guardrail_version } }
 }
 
 output "guardrail_id" {
@@ -977,6 +994,10 @@ exports[`ts#agent#guardrails generator > protocol ag-ui > should generate the gu
       source  = "hashicorp/random"
       version = "3.9.1"
     }
+    time = {
+      source  = "hashicorp/time"
+      version = "0.14.2"
+    }
   }
 }
 
@@ -1041,12 +1062,25 @@ resource "aws_bedrock_guardrail_version" "this" {
   }
 }
 
+resource "time_sleep" "version_retention" {
+  destroy_duration = "15s"
+
+  triggers = {
+    guardrail_id      = aws_bedrock_guardrail.this.guardrail_id
+    guardrail_version = aws_bedrock_guardrail_version.this.version
+  }
+
+  lifecycle {
+    create_before_destroy = true
+  }
+}
+
 module "add_guardrail_to_runtime_config" {
   source = "../../../core/runtime-config/entry"
 
   namespace = "agentcore"
   key       = "guardrails"
-  value     = { "TestProjectAgent" = { guardrailId = aws_bedrock_guardrail.this.guardrail_id, guardrailVersion = aws_bedrock_guardrail_version.this.version } }
+  value     = { "TestProjectAgent" = { guardrailId = time_sleep.version_retention.triggers.guardrail_id, guardrailVersion = time_sleep.version_retention.triggers.guardrail_version } }
 }
 
 output "guardrail_id" {
@@ -1523,6 +1557,10 @@ exports[`ts#agent#guardrails generator > protocol http > should generate the gua
       source  = "hashicorp/random"
       version = "3.9.1"
     }
+    time = {
+      source  = "hashicorp/time"
+      version = "0.14.2"
+    }
   }
 }
 
@@ -1587,12 +1625,25 @@ resource "aws_bedrock_guardrail_version" "this" {
   }
 }
 
+resource "time_sleep" "version_retention" {
+  destroy_duration = "15s"
+
+  triggers = {
+    guardrail_id      = aws_bedrock_guardrail.this.guardrail_id
+    guardrail_version = aws_bedrock_guardrail_version.this.version
+  }
+
+  lifecycle {
+    create_before_destroy = true
+  }
+}
+
 module "add_guardrail_to_runtime_config" {
   source = "../../../core/runtime-config/entry"
 
   namespace = "agentcore"
   key       = "guardrails"
-  value     = { "TestProjectAgent" = { guardrailId = aws_bedrock_guardrail.this.guardrail_id, guardrailVersion = aws_bedrock_guardrail_version.this.version } }
+  value     = { "TestProjectAgent" = { guardrailId = time_sleep.version_retention.triggers.guardrail_id, guardrailVersion = time_sleep.version_retention.triggers.guardrail_version } }
 }
 
 output "guardrail_id" {

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

@@ -4,7 +4,7 @@
  */ 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 { addGuardrailInfra, addGuardrailPolicy } 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";
@@ -74,6 +74,7 @@ export const tsAgentGuardrailsGenerator = async (tree, options)=>{
     }, {
         overwriteStrategy: OverwriteStrategy.KeepExisting
     });
+    addGuardrailPolicy(tree, agentDir);
     await addGuardrailedModelToAgent(tree, joinPathFragments(agentDir, 'agent.ts'));
     const iac = agent.iac;
     let wiringMessage;

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

@@ -1 +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":"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"}
+{"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 {\n  addGuardrailInfra,\n  addGuardrailPolicy,\n} 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  addGuardrailPolicy(tree, agentDir);\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","addGuardrailPolicy","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":"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"}

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

@@ -8,6 +8,10 @@ terraform {
       source  = "hashicorp/random"
       version = "<%- randomProviderVersion %>"
     }
+    time = {
+      source  = "hashicorp/time"
+      version = "<%- timeProviderVersion %>"
+    }
   }
 }
 
@@ -72,12 +76,25 @@ resource "aws_bedrock_guardrail_version" "this" {
   }
 }
 
+resource "time_sleep" "version_retention" {
+  destroy_duration = "15s"
+
+  triggers = {
+    guardrail_id      = aws_bedrock_guardrail.this.guardrail_id
+    guardrail_version = aws_bedrock_guardrail_version.this.version
+  }
+
+  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 } }
+  value     = { "<%= nameClassName %>" = { guardrailId = time_sleep.version_retention.triggers.guardrail_id, guardrailVersion = time_sleep.version_retention.triggers.guardrail_version } }
 }
 
 output "guardrail_id" {

package/src/utils/guardrail-constructs/guardrail-constructs.d.ts

@@ -16,6 +16,11 @@ export interface AddGuardrailInfraOptions {
     /** Workspace-root-relative path of the guardrail.json policy file. */
     policyPath: string;
 }
+/**
+ * Write the guardrail.json policy next to the agent. The policy is the
+ * user's to edit, so a re-run never touches an existing file.
+ */
+export declare const addGuardrailPolicy: (tree: Tree, agentDir: string) => void;
 /**
  * Add the Amazon Bedrock Guardrail infrastructure for the selected IaC
  * provider: a CDK construct in the shared constructs project, or a Terraform

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

@@ -6,6 +6,14 @@ 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";
+/**
+ * Write the guardrail.json policy next to the agent. The policy is the
+ * user's to edit, so a re-run never touches an existing file.
+ */ export const addGuardrailPolicy = (tree, agentDir)=>{
+    generateFiles(tree, joinPathFragments(import.meta.dirname, 'files', 'policy'), agentDir, {}, {
+        overwriteStrategy: OverwriteStrategy.KeepExisting
+    });
+};
 /**
  * Add the Amazon Bedrock Guardrail infrastructure for the selected IaC
  * provider: a CDK construct in the shared constructs project, or a Terraform

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

@@ -1 +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 * for CDK the generator lists that file as a `synth` input instead, so the\n * infrastructure's cached synth follows it.\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;;;;;;;;;;;CAWC,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"}
+{"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 * Write the guardrail.json policy next to the agent. The policy is the\n * user's to edit, so a re-run never touches an existing file.\n */\nexport const addGuardrailPolicy = (tree: Tree, agentDir: string): void => {\n  generateFiles(\n    tree,\n    joinPathFragments(import.meta.dirname, 'files', 'policy'),\n    agentDir,\n    {},\n    { overwriteStrategy: OverwriteStrategy.KeepExisting },\n  );\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 * for CDK the generator lists that file as a `synth` input instead, so the\n * infrastructure's cached synth follows it.\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","addGuardrailPolicy","tree","agentDir","dirname","overwriteStrategy","KeepExisting","addGuardrailInfra","options","templateContext","nameClassName","nameKebabCase","policyPath","iac","appDir","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;;;CAGC,GACD,OAAO,MAAMC,qBAAqB,CAACC,MAAYC;IAC7CX,cACEU,MACAT,kBAAkB,YAAYW,OAAO,EAAE,SAAS,WAChDD,UACA,CAAC,GACD;QAAEE,mBAAmBX,kBAAkBY,YAAY;IAAC;AAExD,EAAE;AAEF;;;;;;;;;;;CAWC,GACD,OAAO,MAAMC,oBAAoB,OAC/BL,MACAM;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,SAASrB,kBACbI,cACAC,uBACA,OACA;gBAEFN,cACEU,MACAT,kBACE,YAAYW,OAAO,EACnB,SACA,OACA,OACA,eAEFX,kBAAkBqB,QAAQ,eAC1B;oBAAE,GAAGL,eAAe;oBAAE,GAAGb,QAAQM,KAAK;gBAAC,GACvC;oBAAEG,mBAAmBX,kBAAkBY,YAAY;gBAAC;gBAEtD,MAAMX,cACJO,MACAT,kBAAkBqB,QAAQ,cAAc,aACxC,CAAC,EAAE,EAAEN,QAAQG,aAAa,CAAC,CAAC,EAAEH,QAAQG,aAAa,CAAC,aAAa,CAAC;gBAEpE,MAAMhB,cACJO,MACAT,kBAAkBqB,QAAQ,aAC1B;gBAEF;YACF;QACA,KAAK;YACHtB,cACEU,MACAT,kBACE,YAAYW,OAAO,EACnB,SACA,aACA,OACA,eAEFX,kBACEI,cACAE,sBACA,OACA,OACA,eAEF;gBACE,GAAGU,eAAe;gBAClB,kEAAkE;gBAClE,iDAAiD;gBACjDM,qBAAqB,GAAGP,QAAQG,aAAa,CAAC,UAAU,CAAC,CAACK,KAAK,CAC7D,GACA;gBAEF,GAAGhB,2BAA2B;YAChC,GACA;gBAAEK,mBAAmBX,kBAAkBY,YAAY;YAAC;YAEtD;IACJ;AACF,EAAE"}

package/src/utils/guardrail-constructs/guardrail-wiring.d.ts

@@ -11,9 +11,16 @@ export interface GuardrailWiringOptions {
     nameKebabCase: string;
     /** npm scope of the workspace without the `@`, eg `my-scope`. */
     npmScope: string;
+    /**
+     * The agent guide section that shows how to deploy the agent's Terraform
+     * module. Defaults to the ts#agent guide.
+     */
+    deployGuideUrl?: string;
 }
 /** The ts#agent guide section that shows how to deploy the agent's Terraform module. */
 export declare const TS_AGENT_TERRAFORM_DEPLOY_GUIDE_URL = "https://awslabs.github.io/nx-plugin-for-aws/en/guides/ts-agent/#infrastructure-as-code";
+/** The py#agent guide section that shows how to deploy the agent's Terraform module. */
+export declare const PY_AGENT_TERRAFORM_DEPLOY_GUIDE_URL = "https://awslabs.github.io/nx-plugin-for-aws/en/guides/py-agent/#infrastructure-as-code";
 /**
  * The code a user adds to their CDK stack to guard the agent.
  * The guide shows the same code for `my-agent` in scope `my-scope`, which