@aws/nx-plugin 1.2.0 → 1.3.0

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

@@ -4,6 +4,7 @@
  */ import { snakeCase } from "../names.js";
 import { SHARED_CONSTRUCTS_NAME } from "../shared-constructs-constants.js";
 /** The ts#agent guide section that shows how to deploy the agent's Terraform module. */ export 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 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
@@ -39,11 +40,11 @@ module "runtime_config_appconfig_deployment" {
 }`;
 };
 /**
- * How to add the printed Terraform code. `ts#agent` does not add the agent to
- * the root module, so its `module` block may not exist yet.
- */ const terraformSteps = (nameKebabCase)=>{
+ * How to add the printed Terraform code. The agent generators do not add the
+ * agent to the root module, so its `module` block may not exist yet.
+ */ const terraformSteps = (nameKebabCase, deployGuideUrl = TS_AGENT_TERRAFORM_DEPLOY_GUIDE_URL)=>{
     const agentModule = snakeCase(nameKebabCase);
-    return `Add the module "${agentModule}_guardrail" block as printed below. Add its additional_iam_policy_statements line to your existing module "${agentModule}" block, and add module.${agentModule}_guardrail to the depends_on list of your runtime_config_appconfig_deployment module. If your root module does not deploy the agent yet, add the agent's module first, as described in ${TS_AGENT_TERRAFORM_DEPLOY_GUIDE_URL}.`;
+    return `Add the module "${agentModule}_guardrail" block as printed below. Add its additional_iam_policy_statements line to your existing module "${agentModule}" block, and add module.${agentModule}_guardrail to the depends_on list of your runtime_config_appconfig_deployment module. If your root module does not deploy the agent yet, add the agent's module first, as described in ${deployGuideUrl}.`;
 };
 /**
  * The message the generator prints after it adds the guardrail
@@ -53,7 +54,7 @@ module "runtime_config_appconfig_deployment" {
     const missing = `Until you add it, the deployed agent fails on its first request, because runtime config has no guardrail at agentcore.guardrails.${options.nameClassName}.`;
     return options.iac === 'cdk' ? `Add the guardrail to your agent in your stack, for example packages/infra/src/stacks/application-stack.ts. ${missing}
 
-${cdkGuardrailWiring(options)}` : `Add the guardrail to your agent in the root Terraform module where you deploy the agent, for example packages/infra/src/main.tf. ${missing} ${terraformSteps(options.nameKebabCase)}
+${cdkGuardrailWiring(options)}` : `Add the guardrail to your agent in the root Terraform module where you deploy the agent, for example packages/infra/src/main.tf. ${missing} ${terraformSteps(options.nameKebabCase, options.deployGuideUrl)}
 
 ${terraformGuardrailWiring(options)}`;
 };

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

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../packages/nx-plugin/src/utils/guardrail-constructs/guardrail-wiring.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport type { Iac } from '../iac.js';\nimport { snakeCase } from '../names.js';\nimport { SHARED_CONSTRUCTS_NAME } from '../shared-constructs-constants.js';\n\nexport interface GuardrailWiringOptions {\n  iac: Iac;\n  /** Class name of the guarded agent, eg `MyAgent`. */\n  nameClassName: string;\n  /** Kebab-case name of the guarded agent, eg `my-agent`. */\n  nameKebabCase: string;\n  /** npm scope of the workspace without the `@`, eg `my-scope`. */\n  npmScope: string;\n}\n\n/** The ts#agent guide section that shows how to deploy the agent's Terraform module. */\nexport const TS_AGENT_TERRAFORM_DEPLOY_GUIDE_URL =\n  'https://awslabs.github.io/nx-plugin-for-aws/en/guides/ts-agent/#infrastructure-as-code';\n\n/**\n * The code a user adds to their CDK stack to guard the agent.\n * The guide shows the same code for `my-agent` in scope `my-scope`, which\n * generator.spec.ts checks.\n */\nexport const cdkGuardrailWiring = ({\n  nameClassName,\n  npmScope,\n}: Pick<GuardrailWiringOptions, 'nameClassName' | 'npmScope'>): string =>\n  `import { ${nameClassName}, ${nameClassName}Guardrail } from '@${npmScope}/${SHARED_CONSTRUCTS_NAME}';\n\nconst agent = new ${nameClassName}(this, '${nameClassName}');\nnew ${nameClassName}Guardrail(this, '${nameClassName}Guardrail', { agent });`;\n\n/**\n * The code a user adds to their root Terraform module to grant the agent the\n * guardrail and deploy its runtime-config entry, relative to\n * `packages/infra/src`. The guide shows the same code for `my-agent`, which\n * generator.spec.ts checks.\n */\nexport const terraformGuardrailWiring = ({\n  nameKebabCase,\n}: Pick<GuardrailWiringOptions, 'nameKebabCase'>): string => {\n  const agentModule = snakeCase(nameKebabCase);\n  const guardrailModule = `${agentModule}_guardrail`;\n  return `module \"${guardrailModule}\" {\n  source = \"../../common/terraform/src/app/guardrails/${nameKebabCase}\"\n}\n\nmodule \"${agentModule}\" {\n  source = \"../../common/terraform/src/app/agents/${nameKebabCase}\"\n  # ...existing arguments...\n  additional_iam_policy_statements = module.${guardrailModule}.iam_policy_statements\n}\n\nmodule \"runtime_config_appconfig_deployment\" {\n  # ...existing arguments...\n  depends_on = [\n    # ...existing modules...\n    module.${guardrailModule},\n  ]\n}`;\n};\n\n/**\n * How to add the printed Terraform code. `ts#agent` does not add the agent to\n * the root module, so its `module` block may not exist yet.\n */\nconst terraformSteps = (nameKebabCase: string): string => {\n  const agentModule = snakeCase(nameKebabCase);\n  return `Add the module \"${agentModule}_guardrail\" block as printed below. Add its additional_iam_policy_statements line to your existing module \"${agentModule}\" block, and add module.${agentModule}_guardrail to the depends_on list of your runtime_config_appconfig_deployment module. If your root module does not deploy the agent yet, add the agent's module first, as described in ${TS_AGENT_TERRAFORM_DEPLOY_GUIDE_URL}.`;\n};\n\n/**\n * The message the generator prints after it adds the guardrail\n * infrastructure. The generator does not edit the user's stack or root\n * module, so this tells the user what to add there.\n */\nexport const guardrailWiringMessage = (\n  options: GuardrailWiringOptions,\n): string => {\n  const missing = `Until you add it, the deployed agent fails on its first request, because runtime config has no guardrail at agentcore.guardrails.${options.nameClassName}.`;\n  return options.iac === 'cdk'\n    ? `Add the guardrail to your agent in your stack, for example packages/infra/src/stacks/application-stack.ts. ${missing}\n\n${cdkGuardrailWiring(options)}`\n    : `Add the guardrail to your agent in the root Terraform module where you deploy the agent, for example packages/infra/src/main.tf. ${missing} ${terraformSteps(options.nameKebabCase)}\n\n${terraformGuardrailWiring(options)}`;\n};\n"],"names":["snakeCase","SHARED_CONSTRUCTS_NAME","TS_AGENT_TERRAFORM_DEPLOY_GUIDE_URL","cdkGuardrailWiring","nameClassName","npmScope","terraformGuardrailWiring","nameKebabCase","agentModule","guardrailModule","terraformSteps","guardrailWiringMessage","options","missing","iac"],"mappings":"AAAA;;;CAGC,GAED,SAASA,SAAS,QAAQ,cAAc;AACxC,SAASC,sBAAsB,QAAQ,oCAAoC;AAY3E,sFAAsF,GACtF,OAAO,MAAMC,sCACX,yFAAyF;AAE3F;;;;CAIC,GACD,OAAO,MAAMC,qBAAqB,CAAC,EACjCC,aAAa,EACbC,QAAQ,EACmD,GAC3D,CAAC,SAAS,EAAED,cAAc,EAAE,EAAEA,cAAc,mBAAmB,EAAEC,SAAS,CAAC,EAAEJ,uBAAuB;;kBAEpF,EAAEG,cAAc,QAAQ,EAAEA,cAAc;IACtD,EAAEA,cAAc,iBAAiB,EAAEA,cAAc,uBAAuB,CAAC,CAAC;AAE9E;;;;;CAKC,GACD,OAAO,MAAME,2BAA2B,CAAC,EACvCC,aAAa,EACiC;IAC9C,MAAMC,cAAcR,UAAUO;IAC9B,MAAME,kBAAkB,GAAGD,YAAY,UAAU,CAAC;IAClD,OAAO,CAAC,QAAQ,EAAEC,gBAAgB;sDACkB,EAAEF,cAAc;;;QAG9D,EAAEC,YAAY;kDAC4B,EAAED,cAAc;;4CAEtB,EAAEE,gBAAgB;;;;;;;WAOnD,EAAEA,gBAAgB;;CAE5B,CAAC;AACF,EAAE;AAEF;;;CAGC,GACD,MAAMC,iBAAiB,CAACH;IACtB,MAAMC,cAAcR,UAAUO;IAC9B,OAAO,CAAC,gBAAgB,EAAEC,YAAY,2GAA2G,EAAEA,YAAY,wBAAwB,EAAEA,YAAY,uLAAuL,EAAEN,oCAAoC,CAAC,CAAC;AACta;AAEA;;;;CAIC,GACD,OAAO,MAAMS,yBAAyB,CACpCC;IAEA,MAAMC,UAAU,CAAC,iIAAiI,EAAED,QAAQR,aAAa,CAAC,CAAC,CAAC;IAC5K,OAAOQ,QAAQE,GAAG,KAAK,QACnB,CAAC,2GAA2G,EAAED,QAAQ;;AAE5H,EAAEV,mBAAmBS,UAAU,GACzB,CAAC,iIAAiI,EAAEC,QAAQ,CAAC,EAAEH,eAAeE,QAAQL,aAAa,EAAE;;AAE3L,EAAED,yBAAyBM,UAAU;AACrC,EAAE"}
+{"version":3,"sources":["../../../../../../packages/nx-plugin/src/utils/guardrail-constructs/guardrail-wiring.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport type { Iac } from '../iac.js';\nimport { snakeCase } from '../names.js';\nimport { SHARED_CONSTRUCTS_NAME } from '../shared-constructs-constants.js';\n\nexport interface GuardrailWiringOptions {\n  iac: Iac;\n  /** Class name of the guarded agent, eg `MyAgent`. */\n  nameClassName: string;\n  /** Kebab-case name of the guarded agent, eg `my-agent`. */\n  nameKebabCase: string;\n  /** npm scope of the workspace without the `@`, eg `my-scope`. */\n  npmScope: string;\n  /**\n   * The agent guide section that shows how to deploy the agent's Terraform\n   * module. Defaults to the ts#agent guide.\n   */\n  deployGuideUrl?: string;\n}\n\n/** The ts#agent guide section that shows how to deploy the agent's Terraform module. */\nexport const TS_AGENT_TERRAFORM_DEPLOY_GUIDE_URL =\n  'https://awslabs.github.io/nx-plugin-for-aws/en/guides/ts-agent/#infrastructure-as-code';\n\n/** The py#agent guide section that shows how to deploy the agent's Terraform module. */\nexport const PY_AGENT_TERRAFORM_DEPLOY_GUIDE_URL =\n  'https://awslabs.github.io/nx-plugin-for-aws/en/guides/py-agent/#infrastructure-as-code';\n\n/**\n * The code a user adds to their CDK stack to guard the agent.\n * The guide shows the same code for `my-agent` in scope `my-scope`, which\n * generator.spec.ts checks.\n */\nexport const cdkGuardrailWiring = ({\n  nameClassName,\n  npmScope,\n}: Pick<GuardrailWiringOptions, 'nameClassName' | 'npmScope'>): string =>\n  `import { ${nameClassName}, ${nameClassName}Guardrail } from '@${npmScope}/${SHARED_CONSTRUCTS_NAME}';\n\nconst agent = new ${nameClassName}(this, '${nameClassName}');\nnew ${nameClassName}Guardrail(this, '${nameClassName}Guardrail', { agent });`;\n\n/**\n * The code a user adds to their root Terraform module to grant the agent the\n * guardrail and deploy its runtime-config entry, relative to\n * `packages/infra/src`. The guide shows the same code for `my-agent`, which\n * generator.spec.ts checks.\n */\nexport const terraformGuardrailWiring = ({\n  nameKebabCase,\n}: Pick<GuardrailWiringOptions, 'nameKebabCase'>): string => {\n  const agentModule = snakeCase(nameKebabCase);\n  const guardrailModule = `${agentModule}_guardrail`;\n  return `module \"${guardrailModule}\" {\n  source = \"../../common/terraform/src/app/guardrails/${nameKebabCase}\"\n}\n\nmodule \"${agentModule}\" {\n  source = \"../../common/terraform/src/app/agents/${nameKebabCase}\"\n  # ...existing arguments...\n  additional_iam_policy_statements = module.${guardrailModule}.iam_policy_statements\n}\n\nmodule \"runtime_config_appconfig_deployment\" {\n  # ...existing arguments...\n  depends_on = [\n    # ...existing modules...\n    module.${guardrailModule},\n  ]\n}`;\n};\n\n/**\n * How to add the printed Terraform code. The agent generators do not add the\n * agent to the root module, so its `module` block may not exist yet.\n */\nconst terraformSteps = (\n  nameKebabCase: string,\n  deployGuideUrl = TS_AGENT_TERRAFORM_DEPLOY_GUIDE_URL,\n): string => {\n  const agentModule = snakeCase(nameKebabCase);\n  return `Add the module \"${agentModule}_guardrail\" block as printed below. Add its additional_iam_policy_statements line to your existing module \"${agentModule}\" block, and add module.${agentModule}_guardrail to the depends_on list of your runtime_config_appconfig_deployment module. If your root module does not deploy the agent yet, add the agent's module first, as described in ${deployGuideUrl}.`;\n};\n\n/**\n * The message the generator prints after it adds the guardrail\n * infrastructure. The generator does not edit the user's stack or root\n * module, so this tells the user what to add there.\n */\nexport const guardrailWiringMessage = (\n  options: GuardrailWiringOptions,\n): string => {\n  const missing = `Until you add it, the deployed agent fails on its first request, because runtime config has no guardrail at agentcore.guardrails.${options.nameClassName}.`;\n  return options.iac === 'cdk'\n    ? `Add the guardrail to your agent in your stack, for example packages/infra/src/stacks/application-stack.ts. ${missing}\n\n${cdkGuardrailWiring(options)}`\n    : `Add the guardrail to your agent in the root Terraform module where you deploy the agent, for example packages/infra/src/main.tf. ${missing} ${terraformSteps(options.nameKebabCase, options.deployGuideUrl)}\n\n${terraformGuardrailWiring(options)}`;\n};\n"],"names":["snakeCase","SHARED_CONSTRUCTS_NAME","TS_AGENT_TERRAFORM_DEPLOY_GUIDE_URL","PY_AGENT_TERRAFORM_DEPLOY_GUIDE_URL","cdkGuardrailWiring","nameClassName","npmScope","terraformGuardrailWiring","nameKebabCase","agentModule","guardrailModule","terraformSteps","deployGuideUrl","guardrailWiringMessage","options","missing","iac"],"mappings":"AAAA;;;CAGC,GAED,SAASA,SAAS,QAAQ,cAAc;AACxC,SAASC,sBAAsB,QAAQ,oCAAoC;AAiB3E,sFAAsF,GACtF,OAAO,MAAMC,sCACX,yFAAyF;AAE3F,sFAAsF,GACtF,OAAO,MAAMC,sCACX,yFAAyF;AAE3F;;;;CAIC,GACD,OAAO,MAAMC,qBAAqB,CAAC,EACjCC,aAAa,EACbC,QAAQ,EACmD,GAC3D,CAAC,SAAS,EAAED,cAAc,EAAE,EAAEA,cAAc,mBAAmB,EAAEC,SAAS,CAAC,EAAEL,uBAAuB;;kBAEpF,EAAEI,cAAc,QAAQ,EAAEA,cAAc;IACtD,EAAEA,cAAc,iBAAiB,EAAEA,cAAc,uBAAuB,CAAC,CAAC;AAE9E;;;;;CAKC,GACD,OAAO,MAAME,2BAA2B,CAAC,EACvCC,aAAa,EACiC;IAC9C,MAAMC,cAAcT,UAAUQ;IAC9B,MAAME,kBAAkB,GAAGD,YAAY,UAAU,CAAC;IAClD,OAAO,CAAC,QAAQ,EAAEC,gBAAgB;sDACkB,EAAEF,cAAc;;;QAG9D,EAAEC,YAAY;kDAC4B,EAAED,cAAc;;4CAEtB,EAAEE,gBAAgB;;;;;;;WAOnD,EAAEA,gBAAgB;;CAE5B,CAAC;AACF,EAAE;AAEF;;;CAGC,GACD,MAAMC,iBAAiB,CACrBH,eACAI,iBAAiBV,mCAAmC;IAEpD,MAAMO,cAAcT,UAAUQ;IAC9B,OAAO,CAAC,gBAAgB,EAAEC,YAAY,2GAA2G,EAAEA,YAAY,wBAAwB,EAAEA,YAAY,uLAAuL,EAAEG,eAAe,CAAC,CAAC;AACjZ;AAEA;;;;CAIC,GACD,OAAO,MAAMC,yBAAyB,CACpCC;IAEA,MAAMC,UAAU,CAAC,iIAAiI,EAAED,QAAQT,aAAa,CAAC,CAAC,CAAC;IAC5K,OAAOS,QAAQE,GAAG,KAAK,QACnB,CAAC,2GAA2G,EAAED,QAAQ;;AAE5H,EAAEX,mBAAmBU,UAAU,GACzB,CAAC,iIAAiI,EAAEC,QAAQ,CAAC,EAAEJ,eAAeG,QAAQN,aAAa,EAAEM,QAAQF,cAAc,EAAE;;AAEnN,EAAEL,yBAAyBO,UAAU;AACrC,EAAE"}

package/src/utils/test/fake-aws/fake_aws.py

@@ -0,0 +1,205 @@
+# 
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+# 
+"""Local stand-in for AppConfigData and Bedrock Runtime, so tests of generated
+agent code send real SDK requests without AWS. Standard library only.
+
+Usage: python fake_aws.py <config.json> <port> <requests.log>
+or, in-process: start_server(config_file, log_file) returns (server, port).
+
+- AppConfigData: POST /configurationsessions and GET /configuration serve the
+  JSON in <config.json>, re-read on every request, so editing the file changes
+  the value. A session whose ApplicationIdentifier is "broken" answers HTTP 400
+  BadRequestException, to simulate a read failure.
+- Bedrock Runtime: POST /model/<id>/converse-stream (event stream) and
+  /model/<id>/converse (JSON) answer "4". A request with a guardrailConfig gets
+  BLOCKED_ANSWER with stop reason guardrail_intervened and a BLOCKED trace when
+  the text the guardrail checks contains DENIED_TERM. As in Bedrock, the
+  guardrail checks only the guardContent blocks if the messages hold any, and
+  every message otherwise.
+
+Every request appends one JSON line to <requests.log>: AppConfigData requests
+as {"path": "StartConfigurationSession" | "GetLatestConfiguration"}, model
+requests as {"path", "modelId", "guardrailConfig", "userTexts", "intervened"}.
+"""
+
+import binascii
+import json
+import struct
+import sys
+import threading
+import urllib.parse
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+DENIED_TERM = "stocks"
+BLOCKED_ANSWER = "Sorry, I can't help with that request."
+
+
+def _header(name: str, value: str) -> bytes:
+    n, v = name.encode(), value.encode()
+    return struct.pack("B", len(n)) + n + b"\x07" + struct.pack(">H", len(v)) + v
+
+
+def _event(event_type: str, payload: dict) -> bytes:
+    headers = (
+        _header(":event-type", event_type)
+        + _header(":content-type", "application/json")
+        + _header(":message-type", "event")
+    )
+    body = json.dumps(payload).encode()
+    total = 12 + len(headers) + len(body) + 4
+    prelude = struct.pack(">II", total, len(headers))
+    prelude += struct.pack(">I", binascii.crc32(prelude) & 0xFFFFFFFF)
+    message = prelude + headers + body
+    return message + struct.pack(">I", binascii.crc32(message) & 0xFFFFFFFF)
+
+
+def _texts(blocks: list) -> list[str]:
+    texts = []
+    for block in blocks:
+        if "text" in block:
+            texts.append(block["text"])
+        elif "guardContent" in block:
+            texts.append(block["guardContent"].get("text", {}).get("text", ""))
+        elif "toolResult" in block:
+            texts.extend(_texts(block["toolResult"].get("content", [])))
+    return texts
+
+
+def _intervenes(request: dict) -> bool:
+    """Whether the guardrail blocks the request's input, by Bedrock's rule for guardContent."""
+    if not request.get("guardrailConfig"):
+        return False
+    messages = request.get("messages", [])
+    guarded = [
+        block["guardContent"].get("text", {}).get("text", "")
+        for message in messages
+        for block in message.get("content", [])
+        if "guardContent" in block
+    ]
+    checked = guarded or [text for message in messages for text in _texts(message.get("content", []))]
+    return any(DENIED_TERM in text.lower() for text in checked)
+
+
+_BLOCKED_TRACE = {
+    "guardrail": {
+        "inputAssessment": {
+            "grtest": {
+                "topicPolicy": {
+                    "topics": [{"name": "Investment advice", "type": "DENY", "action": "BLOCKED", "detected": True}]
+                }
+            }
+        }
+    }
+}
+
+
+def _handler(config_file: str, log_file: str) -> type[BaseHTTPRequestHandler]:
+    lock = threading.Lock()
+
+    def log(entry: dict) -> None:
+        with lock, open(log_file, "a") as f:
+            f.write(json.dumps(entry) + "\n")
+
+    class Handler(BaseHTTPRequestHandler):
+        protocol_version = "HTTP/1.1"
+
+        def log_message(self, *_args) -> None:
+            pass
+
+        def _send(self, status: int, body: bytes, content_type: str, extra=None) -> None:
+            self.send_response(status)
+            self.send_header("Content-Type", content_type)
+            self.send_header("Content-Length", str(len(body)))
+            for k, v in (extra or {}).items():
+                self.send_header(k, v)
+            self.end_headers()
+            self.wfile.write(body)
+
+        def do_GET(self) -> None:
+            if self.path.startswith("/configuration"):
+                log({"path": "GetLatestConfiguration"})
+                with open(config_file, "rb") as f:
+                    body = f.read()
+                self._send(
+                    200,
+                    body,
+                    "application/json",
+                    {"Next-Poll-Configuration-Token": "token", "Next-Poll-Interval-In-Seconds": "60"},
+                )
+                return
+            self._send(404, b"{}", "application/json")
+
+        def do_POST(self) -> None:
+            raw = self.rfile.read(int(self.headers.get("Content-Length", "0")))
+            if self.path.startswith("/configurationsessions"):
+                log({"path": "StartConfigurationSession"})
+                if json.loads(raw or b"{}").get("ApplicationIdentifier") == "broken":
+                    self._send(
+                        400,
+                        json.dumps({"Message": "Application broken does not exist."}).encode(),
+                        "application/json",
+                        {"x-amzn-ErrorType": "BadRequestException"},
+                    )
+                    return
+                self._send(201, json.dumps({"InitialConfigurationToken": "token"}).encode(), "application/json")
+                return
+            if self.path.startswith("/model/"):
+                request = json.loads(raw or b"{}")
+                model_id = urllib.parse.unquote(self.path.split("/")[2])
+                intervened = _intervenes(request)
+                log(
+                    {
+                        "path": self.path.split("/")[-1],
+                        "modelId": model_id,
+                        "guardrailConfig": request.get("guardrailConfig"),
+                        "userTexts": [
+                            text
+                            for message in request.get("messages", [])
+                            if message.get("role") == "user"
+                            for text in _texts(message.get("content", []))
+                        ],
+                        "intervened": intervened,
+                    }
+                )
+                text = BLOCKED_ANSWER if intervened else "4"
+                stop_reason = "guardrail_intervened" if intervened else "end_turn"
+                metadata = {
+                    "usage": {"inputTokens": 1, "outputTokens": 1, "totalTokens": 2},
+                    "metrics": {"latencyMs": 1},
+                    **({"trace": _BLOCKED_TRACE} if intervened else {}),
+                }
+                if self.path.endswith("/converse-stream"):
+                    body = b"".join(
+                        [
+                            _event("messageStart", {"role": "assistant"}),
+                            _event("contentBlockDelta", {"contentBlockIndex": 0, "delta": {"text": text}}),
+                            _event("contentBlockStop", {"contentBlockIndex": 0}),
+                            _event("messageStop", {"stopReason": stop_reason}),
+                            _event("metadata", metadata),
+                        ]
+                    )
+                    self._send(200, body, "application/vnd.amazon.eventstream")
+                    return
+                answer = {
+                    "output": {"message": {"role": "assistant", "content": [{"text": text}]}},
+                    "stopReason": stop_reason,
+                    **metadata,
+                }
+                self._send(200, json.dumps(answer).encode(), "application/json")
+                return
+            self._send(404, b"{}", "application/json")
+
+    return Handler
+
+
+def start_server(config_file: str, log_file: str, port: int = 0) -> tuple[ThreadingHTTPServer, int]:
+    """Serve on 127.0.0.1 in a daemon thread; port 0 picks a free port."""
+    server = ThreadingHTTPServer(("127.0.0.1", port), _handler(config_file, log_file))
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    return server, server.server_address[1]
+
+
+if __name__ == "__main__":
+    ThreadingHTTPServer(("127.0.0.1", int(sys.argv[2])), _handler(sys.argv[1], sys.argv[3])).serve_forever()

package/src/utils/test/python-dependencies.d.ts

@@ -12,3 +12,9 @@ export declare const PY_VERIFIER_TYPE_CHECKER: string;
  * they are included too.
  */
 export declare const PY_DYNAMODB_VERIFIER_DEPENDENCIES: string[];
+/**
+ * The packages a Strands or LangChain agent generated by `py#agent` imports
+ * from agent.py and guardrail.py, at the versions the generator vends, plus
+ * the ruff the vended lint and format targets run.
+ */
+export declare const PY_AGENT_GUARDRAIL_VERIFIER_DEPENDENCIES: string[];

package/src/utils/test/python-dependencies.js

@@ -2,6 +2,7 @@
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
  */ import { OPEN_API_PY_CLIENT_DEPENDENCIES } from "../../open-api/py-client/generator.js";
+import { DEPENDENCIES as PY_AGENT_DEPENDENCIES } from "../../py/agent/generator.js";
 import { DEPENDENCIES as PY_DYNAMODB_DEPENDENCIES } from "../../py/dynamodb/generator.js";
 import { declaredNames } from "../declared-dependencies.js";
 import { PY_VERSIONS, withPyVersions } from "../versions.js";
@@ -19,5 +20,23 @@ import { PY_VERSIONS, withPyVersions } from "../versions.js";
     ...withPyVersions(PY_DYNAMODB_DEPENDENCIES, declaredNames(PY_DYNAMODB_DEPENDENCIES.py)),
     ...PY_CLIENT_VERIFIER_DEPENDENCIES
 ];
+/**
+ * The packages a Strands or LangChain agent generated by `py#agent` imports
+ * from agent.py and guardrail.py, at the versions the generator vends, plus
+ * the ruff the vended lint and format targets run.
+ */ export const PY_AGENT_GUARDRAIL_VERIFIER_DEPENDENCIES = [
+    ...withPyVersions(PY_AGENT_DEPENDENCIES, [
+        'aws-lambda-powertools',
+        'boto3',
+        'strands-agents',
+        'strands-agents-tools',
+        'langchain',
+        'langchain-aws',
+        'langgraph',
+        'langgraph-checkpoint-sqlite',
+        'aiosqlite'
+    ]),
+    `ruff${PY_VERSIONS.ruff}`
+];
 
 //# sourceMappingURL=python-dependencies.js.map

package/src/utils/test/python-dependencies.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../packages/nx-plugin/src/utils/test/python-dependencies.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport { OPEN_API_PY_CLIENT_DEPENDENCIES } from '../../open-api/py-client/generator.js';\nimport { DEPENDENCIES as PY_DYNAMODB_DEPENDENCIES } from '../../py/dynamodb/generator.js';\nimport { declaredNames } from '../declared-dependencies.js';\nimport { PY_VERSIONS, withPyVersions } from '../versions.js';\n\n/**\n * The packages a client generated by `open-api#py-client` imports, at the\n * versions the generator vends — so a worker runs the code under test against\n * exactly what a consumer gets.\n */\nexport const PY_CLIENT_VERIFIER_DEPENDENCIES: string[] = withPyVersions(\n  OPEN_API_PY_CLIENT_DEPENDENCIES,\n  declaredNames(OPEN_API_PY_CLIENT_DEPENDENCIES.py),\n);\n\n/** The type checker every Python worker installs alongside its dependencies. */\nexport const PY_VERIFIER_TYPE_CHECKER = `ty${PY_VERSIONS.ty}`;\n\n/**\n * The packages a project generated by `py#dynamodb` imports, at the versions\n * the generator vends. The worker itself imports the py-client packages, so\n * they are included too.\n */\nexport const PY_DYNAMODB_VERIFIER_DEPENDENCIES: string[] = [\n  ...withPyVersions(\n    PY_DYNAMODB_DEPENDENCIES,\n    declaredNames(PY_DYNAMODB_DEPENDENCIES.py),\n  ),\n  ...PY_CLIENT_VERIFIER_DEPENDENCIES,\n];\n"],"names":["OPEN_API_PY_CLIENT_DEPENDENCIES","DEPENDENCIES","PY_DYNAMODB_DEPENDENCIES","declaredNames","PY_VERSIONS","withPyVersions","PY_CLIENT_VERIFIER_DEPENDENCIES","py","PY_VERIFIER_TYPE_CHECKER","ty","PY_DYNAMODB_VERIFIER_DEPENDENCIES"],"mappings":"AAAA;;;CAGC,GACD,SAASA,+BAA+B,QAAQ,wCAAwC;AACxF,SAASC,gBAAgBC,wBAAwB,QAAQ,iCAAiC;AAC1F,SAASC,aAAa,QAAQ,8BAA8B;AAC5D,SAASC,WAAW,EAAEC,cAAc,QAAQ,iBAAiB;AAE7D;;;;CAIC,GACD,OAAO,MAAMC,kCAA4CD,eACvDL,iCACAG,cAAcH,gCAAgCO,EAAE,GAChD;AAEF,8EAA8E,GAC9E,OAAO,MAAMC,2BAA2B,CAAC,EAAE,EAAEJ,YAAYK,EAAE,EAAE,CAAC;AAE9D;;;;CAIC,GACD,OAAO,MAAMC,oCAA8C;OACtDL,eACDH,0BACAC,cAAcD,yBAAyBK,EAAE;OAExCD;CACJ,CAAC"}
+{"version":3,"sources":["../../../../../../packages/nx-plugin/src/utils/test/python-dependencies.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport { OPEN_API_PY_CLIENT_DEPENDENCIES } from '../../open-api/py-client/generator.js';\nimport { DEPENDENCIES as PY_AGENT_DEPENDENCIES } from '../../py/agent/generator.js';\nimport { DEPENDENCIES as PY_DYNAMODB_DEPENDENCIES } from '../../py/dynamodb/generator.js';\nimport { declaredNames } from '../declared-dependencies.js';\nimport { PY_VERSIONS, withPyVersions } from '../versions.js';\n\n/**\n * The packages a client generated by `open-api#py-client` imports, at the\n * versions the generator vends — so a worker runs the code under test against\n * exactly what a consumer gets.\n */\nexport const PY_CLIENT_VERIFIER_DEPENDENCIES: string[] = withPyVersions(\n  OPEN_API_PY_CLIENT_DEPENDENCIES,\n  declaredNames(OPEN_API_PY_CLIENT_DEPENDENCIES.py),\n);\n\n/** The type checker every Python worker installs alongside its dependencies. */\nexport const PY_VERIFIER_TYPE_CHECKER = `ty${PY_VERSIONS.ty}`;\n\n/**\n * The packages a project generated by `py#dynamodb` imports, at the versions\n * the generator vends. The worker itself imports the py-client packages, so\n * they are included too.\n */\nexport const PY_DYNAMODB_VERIFIER_DEPENDENCIES: string[] = [\n  ...withPyVersions(\n    PY_DYNAMODB_DEPENDENCIES,\n    declaredNames(PY_DYNAMODB_DEPENDENCIES.py),\n  ),\n  ...PY_CLIENT_VERIFIER_DEPENDENCIES,\n];\n\n/**\n * The packages a Strands or LangChain agent generated by `py#agent` imports\n * from agent.py and guardrail.py, at the versions the generator vends, plus\n * the ruff the vended lint and format targets run.\n */\nexport const PY_AGENT_GUARDRAIL_VERIFIER_DEPENDENCIES: string[] = [\n  ...withPyVersions(PY_AGENT_DEPENDENCIES, [\n    'aws-lambda-powertools',\n    'boto3',\n    'strands-agents',\n    'strands-agents-tools',\n    'langchain',\n    'langchain-aws',\n    'langgraph',\n    'langgraph-checkpoint-sqlite',\n    'aiosqlite',\n  ]),\n  `ruff${PY_VERSIONS.ruff}`,\n];\n"],"names":["OPEN_API_PY_CLIENT_DEPENDENCIES","DEPENDENCIES","PY_AGENT_DEPENDENCIES","PY_DYNAMODB_DEPENDENCIES","declaredNames","PY_VERSIONS","withPyVersions","PY_CLIENT_VERIFIER_DEPENDENCIES","py","PY_VERIFIER_TYPE_CHECKER","ty","PY_DYNAMODB_VERIFIER_DEPENDENCIES","PY_AGENT_GUARDRAIL_VERIFIER_DEPENDENCIES","ruff"],"mappings":"AAAA;;;CAGC,GACD,SAASA,+BAA+B,QAAQ,wCAAwC;AACxF,SAASC,gBAAgBC,qBAAqB,QAAQ,8BAA8B;AACpF,SAASD,gBAAgBE,wBAAwB,QAAQ,iCAAiC;AAC1F,SAASC,aAAa,QAAQ,8BAA8B;AAC5D,SAASC,WAAW,EAAEC,cAAc,QAAQ,iBAAiB;AAE7D;;;;CAIC,GACD,OAAO,MAAMC,kCAA4CD,eACvDN,iCACAI,cAAcJ,gCAAgCQ,EAAE,GAChD;AAEF,8EAA8E,GAC9E,OAAO,MAAMC,2BAA2B,CAAC,EAAE,EAAEJ,YAAYK,EAAE,EAAE,CAAC;AAE9D;;;;CAIC,GACD,OAAO,MAAMC,oCAA8C;OACtDL,eACDH,0BACAC,cAAcD,yBAAyBK,EAAE;OAExCD;CACJ,CAAC;AAEF;;;;CAIC,GACD,OAAO,MAAMK,2CAAqD;OAC7DN,eAAeJ,uBAAuB;QACvC;QACA;QACA;QACA;QACA;QACA;QACA;QACA;QACA;KACD;IACD,CAAC,IAAI,EAAEG,YAAYQ,IAAI,EAAE;CAC1B,CAAC"}

package/src/utils/test/warm-python-cache.js

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */ import { execFileSync } from "child_process";
 import { pyenvPythonVersion } from "../versions.js";
-import { PY_CLIENT_VERIFIER_DEPENDENCIES, PY_DYNAMODB_VERIFIER_DEPENDENCIES, PY_VERIFIER_TYPE_CHECKER } from "./python-dependencies.js";
+import { PY_AGENT_GUARDRAIL_VERIFIER_DEPENDENCIES, PY_CLIENT_VERIFIER_DEPENDENCIES, PY_DYNAMODB_VERIFIER_DEPENDENCIES, PY_VERIFIER_TYPE_CHECKER } from "./python-dependencies.js";
 /**
  * Vitest globalSetup that warms uv's cache once before any worker spawns.
  *
@@ -31,6 +31,10 @@ import { PY_CLIENT_VERIFIER_DEPENDENCIES, PY_DYNAMODB_VERIFIER_DEPENDENCIES, PY_
         {
             dependencies: PY_DYNAMODB_VERIFIER_DEPENDENCIES,
             python: pyenvPythonVersion()
+        },
+        {
+            dependencies: PY_AGENT_GUARDRAIL_VERIFIER_DEPENDENCIES,
+            python: pyenvPythonVersion()
         }
     ];
     for (const { dependencies, python } of environments){

package/src/utils/test/warm-python-cache.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../packages/nx-plugin/src/utils/test/warm-python-cache.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport { execFileSync } from 'child_process';\nimport { pyenvPythonVersion } from '../versions.js';\nimport {\n  PY_CLIENT_VERIFIER_DEPENDENCIES,\n  PY_DYNAMODB_VERIFIER_DEPENDENCIES,\n  PY_VERIFIER_TYPE_CHECKER,\n} from './python-dependencies.js';\n\n/**\n * Vitest globalSetup that warms uv's cache once before any worker spawns.\n *\n * `PythonVerifier` starts a `uv run --with …` worker per spec file. On a cold\n * cache the first invocation takes an exclusive write lock while it downloads\n * and installs those packages; with many workers racing that lock, startup\n * stalls and a worker can be torn down before it answers. Installing them once\n * up front means every worker hits a warm cache, where uv only takes shared\n * locks.\n *\n * Mirrors the pre-warm this suite used for `ruff` before it moved in-process.\n *\n * A failure here is not fatal — a missing `uv` is reported by the verifier\n * itself, with a message naming the tool — but it is warned about rather than\n * swallowed: a broken cache otherwise degrades silently to every worker racing a\n * cold one, which is the startup failure this exists to prevent.\n */\nexport default function setup() {\n  // The same sets the verifiers install, on the same interpreters, so the warm\n  // cache is the one they hit. Wheels can be interpreter-specific, so each set\n  // is warmed on the interpreter its verifier runs.\n  const environments: { dependencies: string[]; python?: string }[] = [\n    { dependencies: PY_CLIENT_VERIFIER_DEPENDENCIES },\n    {\n      dependencies: PY_DYNAMODB_VERIFIER_DEPENDENCIES,\n      python: pyenvPythonVersion(),\n    },\n  ];\n  for (const { dependencies, python } of environments) {\n    const deps = [...dependencies, PY_VERIFIER_TYPE_CHECKER].flatMap((spec) => [\n      '--with',\n      spec,\n    ]);\n    const interpreter = python ? ['--python', python] : [];\n    try {\n      execFileSync('uv', ['run', ...interpreter, ...deps, 'python', '-c', ''], {\n        stdio: 'ignore',\n      });\n    } catch (error) {\n      console.warn(\n        `Could not warm uv's cache, so each Python worker will install its own ` +\n          `dependencies and may time out starting up: ${error}`,\n      );\n    }\n  }\n}\n"],"names":["execFileSync","pyenvPythonVersion","PY_CLIENT_VERIFIER_DEPENDENCIES","PY_DYNAMODB_VERIFIER_DEPENDENCIES","PY_VERIFIER_TYPE_CHECKER","setup","environments","dependencies","python","deps","flatMap","spec","interpreter","stdio","error","console","warn"],"mappings":"AAAA;;;CAGC,GACD,SAASA,YAAY,QAAQ,gBAAgB;AAC7C,SAASC,kBAAkB,QAAQ,iBAAiB;AACpD,SACEC,+BAA+B,EAC/BC,iCAAiC,EACjCC,wBAAwB,QACnB,2BAA2B;AAElC;;;;;;;;;;;;;;;;CAgBC,GACD,eAAe,SAASC;IACtB,6EAA6E;IAC7E,6EAA6E;IAC7E,kDAAkD;IAClD,MAAMC,eAA8D;QAClE;YAAEC,cAAcL;QAAgC;QAChD;YACEK,cAAcJ;YACdK,QAAQP;QACV;KACD;IACD,KAAK,MAAM,EAAEM,YAAY,EAAEC,MAAM,EAAE,IAAIF,aAAc;QACnD,MAAMG,OAAO;eAAIF;YAAcH;SAAyB,CAACM,OAAO,CAAC,CAACC,OAAS;gBACzE;gBACAA;aACD;QACD,MAAMC,cAAcJ,SAAS;YAAC;YAAYA;SAAO,GAAG,EAAE;QACtD,IAAI;YACFR,aAAa,MAAM;gBAAC;mBAAUY;mBAAgBH;gBAAM;gBAAU;gBAAM;aAAG,EAAE;gBACvEI,OAAO;YACT;QACF,EAAE,OAAOC,OAAO;YACdC,QAAQC,IAAI,CACV,CAAC,sEAAsE,CAAC,GACtE,CAAC,2CAA2C,EAAEF,OAAO;QAE3D;IACF;AACF"}
+{"version":3,"sources":["../../../../../../packages/nx-plugin/src/utils/test/warm-python-cache.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport { execFileSync } from 'child_process';\nimport { pyenvPythonVersion } from '../versions.js';\nimport {\n  PY_AGENT_GUARDRAIL_VERIFIER_DEPENDENCIES,\n  PY_CLIENT_VERIFIER_DEPENDENCIES,\n  PY_DYNAMODB_VERIFIER_DEPENDENCIES,\n  PY_VERIFIER_TYPE_CHECKER,\n} from './python-dependencies.js';\n\n/**\n * Vitest globalSetup that warms uv's cache once before any worker spawns.\n *\n * `PythonVerifier` starts a `uv run --with …` worker per spec file. On a cold\n * cache the first invocation takes an exclusive write lock while it downloads\n * and installs those packages; with many workers racing that lock, startup\n * stalls and a worker can be torn down before it answers. Installing them once\n * up front means every worker hits a warm cache, where uv only takes shared\n * locks.\n *\n * Mirrors the pre-warm this suite used for `ruff` before it moved in-process.\n *\n * A failure here is not fatal — a missing `uv` is reported by the verifier\n * itself, with a message naming the tool — but it is warned about rather than\n * swallowed: a broken cache otherwise degrades silently to every worker racing a\n * cold one, which is the startup failure this exists to prevent.\n */\nexport default function setup() {\n  // The same sets the verifiers install, on the same interpreters, so the warm\n  // cache is the one they hit. Wheels can be interpreter-specific, so each set\n  // is warmed on the interpreter its verifier runs.\n  const environments: { dependencies: string[]; python?: string }[] = [\n    { dependencies: PY_CLIENT_VERIFIER_DEPENDENCIES },\n    {\n      dependencies: PY_DYNAMODB_VERIFIER_DEPENDENCIES,\n      python: pyenvPythonVersion(),\n    },\n    {\n      dependencies: PY_AGENT_GUARDRAIL_VERIFIER_DEPENDENCIES,\n      python: pyenvPythonVersion(),\n    },\n  ];\n  for (const { dependencies, python } of environments) {\n    const deps = [...dependencies, PY_VERIFIER_TYPE_CHECKER].flatMap((spec) => [\n      '--with',\n      spec,\n    ]);\n    const interpreter = python ? ['--python', python] : [];\n    try {\n      execFileSync('uv', ['run', ...interpreter, ...deps, 'python', '-c', ''], {\n        stdio: 'ignore',\n      });\n    } catch (error) {\n      console.warn(\n        `Could not warm uv's cache, so each Python worker will install its own ` +\n          `dependencies and may time out starting up: ${error}`,\n      );\n    }\n  }\n}\n"],"names":["execFileSync","pyenvPythonVersion","PY_AGENT_GUARDRAIL_VERIFIER_DEPENDENCIES","PY_CLIENT_VERIFIER_DEPENDENCIES","PY_DYNAMODB_VERIFIER_DEPENDENCIES","PY_VERIFIER_TYPE_CHECKER","setup","environments","dependencies","python","deps","flatMap","spec","interpreter","stdio","error","console","warn"],"mappings":"AAAA;;;CAGC,GACD,SAASA,YAAY,QAAQ,gBAAgB;AAC7C,SAASC,kBAAkB,QAAQ,iBAAiB;AACpD,SACEC,wCAAwC,EACxCC,+BAA+B,EAC/BC,iCAAiC,EACjCC,wBAAwB,QACnB,2BAA2B;AAElC;;;;;;;;;;;;;;;;CAgBC,GACD,eAAe,SAASC;IACtB,6EAA6E;IAC7E,6EAA6E;IAC7E,kDAAkD;IAClD,MAAMC,eAA8D;QAClE;YAAEC,cAAcL;QAAgC;QAChD;YACEK,cAAcJ;YACdK,QAAQR;QACV;QACA;YACEO,cAAcN;YACdO,QAAQR;QACV;KACD;IACD,KAAK,MAAM,EAAEO,YAAY,EAAEC,MAAM,EAAE,IAAIF,aAAc;QACnD,MAAMG,OAAO;eAAIF;YAAcH;SAAyB,CAACM,OAAO,CAAC,CAACC,OAAS;gBACzE;gBACAA;aACD;QACD,MAAMC,cAAcJ,SAAS;YAAC;YAAYA;SAAO,GAAG,EAAE;QACtD,IAAI;YACFT,aAAa,MAAM;gBAAC;mBAAUa;mBAAgBH;gBAAM;gBAAU;gBAAM;aAAG,EAAE;gBACvEI,OAAO;YACT;QACF,EAAE,OAAOC,OAAO;YACdC,QAAQC,IAAI,CACV,CAAC,sEAAsE,CAAC,GACtE,CAAC,2CAA2C,EAAEF,OAAO;QAE3D;IACF;AACF"}